a5w_report_saveas Function
Syntax
Arguments
- LayoutNameCharacter
The report to print. The report must include a fully qualified path to the report location. If specifying a SSRS report, use the format reportName.ssrs.a5rpt. See examples below.
- Saveas_formatCharacter
Type of file to create. Can be one of the following values:
- Format
- Description
Creates a PDF file.
- Excel
Exports report as an Excel file.
- HTML
Creates an HTML report.
- RTF
Creates an RTF file.
- Text
Creates a text file.
- FilterCharacter
Filter expression to apply to report. Specify an empty string for no filter. Not supported for SSRS reports.
If the report is based on a SQL data source and the filter can be promoted to a SQL filter, Filter is automatically added to the options.filter property for improved performance. See Filter Parameters below for more info.
- OrderCharacter
Order expression to apply to report detail. Specify an empty string for no order. Not supported for SSRS reports.
- FilenameCharacter
Name of file to create or a JSON string.
A JSON string can be passed using the Filename argument to upload the report to an S3 Bucket or send it as an email attachment using SparkPost or SendGrid.
- typeCharacter
Defines what to do with the report after it has been created. Options include:
- type
- Description
- Store
Report will be uploaded to an S3 bucket.
Report is sent as an email.
- ConnectionStringCharacter
Required if type is "Store". An Amazon S3 Storage Connection string.
- objectNameCharacter
Required if type is "Store". The name of the object to store the report as in the bucket.
{"type":"Store", "ConnectionString":"AmazonS3", "objectName":"myReport.pdf"}
- apikeyCharacter
Required if type is "email". Your SparkPost or SendGrid API key. Leave blank (an empty string) to use the API key stored in [Web Project Properties].
If using SendGrid, the API key must be prefixed with sendgrid:. For example:
{"type":"email", "apikey":"sendgrid:1234567890", "htmlInline": false, "send_to":"[email protected]", "send_from":"[email protected]", "subject":"Your Report", "message":"Here's the report you requested."}
- send_toCharacter
Required if type is "email". The recipient's address.
- send_fromCharacter
Required if type is "email". The sender's address.
- send_from_friendly_nameCharacter
Optional if type is "email". Friendly name to use in the from field.
- subjectCharacter
Required if type is "email". The email subject.
- messageCharacter
Required if type is "email". The email body defined as HTML.
- globalVariablesPointer
A pointer to the global variables. Pass in global_variables() if you do not need to define your own global variables. Not supported for SSRS reports. See explanation below for more information.
- PrintOptionsPointer
Default = null_value(). PDF Driver options. Not supported for SSRS reports. See Report.SaveAs() for more details.
- ArgumentsSQL::Arguments
Default = null_value(). Optional SQL Arguments if required by the report data source or used in filter/order expressions. See Report.SaveAs() for more information.
- OptionsPointer
Default = null_value(). Additional options that can be used to add a SQL filter or SQL order expression to the query used to generate the report. Options has the following properties:
- filterCharacter
Defines a WHERE clause that is added to the SQL expression that fetches the data for the report. If the report definition has a WHERE clause, Options.filter is added to it.
dim options as P options.filter = "quantity < 100 AND quantity > 50"
The filter can include SQL::Arguments, which are passed into the function using the Arguments parameter:
dim arguments as SQL::Arguments arguments.set("maxqty",100) arguments.set("minqty",50) dim options as P options.filter = "quantity < :maxqty AND quantity > :minqty"
- orderCharacter
Defines an ORDER clause to use in the SQL expression that fetches the data for the report. If the report definition has an ORDER clause, Options.order replaces it.
dim options as P options.order = "country ASC, city ASC"
Returns
- filenameOutCharacter
The filename where the report output is stored. Generally, this will be the same as what is specified in the Filename parameter, unless the file extension was changed.
Description
The a5w_report_saveas() method generates a report as a PDF, HTML, RTF, or TXT document. The report can be downloaded, uploaded to Amazon S3, or emailed.
Discussion
The a5w_report_saveas function generates a Report from the Application Server.
dim layoutName as c = "customer List@[PathAlias.ADB_Path]\myalphaworkspace.alb" dim filename as c = "c:\data\custlist.pdf" a5w_report_saveAs(layoutName,"PDF","","",filename,global_variables())
Specifying the Report to Print
Reports can be defined in the workspace library or as individual report files on the Web Projects Control Panel. The LayoutName must include a fully qualified path to the location of the report file. Depending on where the report is located, you can specify the path as follows:
- Report Location
- Layout Name
- Workspace Library (*.alb)
"MyReport@C:/Path/To/Workspace/Library/MyWorkspace.alb"
- Project Report (*.a5rpt)
"C:/Path/To/Webroot/MyReport.a5rpt"
The example below shows how to use the [PathAlias.ADB_Path] placeholder when specifying the location of the workspace library.
'Print a report stored in the workspace library: dim layoutName as c = "myReport@[PathAlias.ADB_Path]\MyWorkspace.alb" dim filename as c = "myReport.pdf" a5w_report_saveAs(layoutName,"PDF","","",filename,global_variables())
The next example shows how to use the context.request.applicationRoot property when specifying the location of a Project Report (a report saved as a *.a5rpt file.)
'Print a Project Report: dim layoutName as c = context.request.applicationRoot + "myReport.a5rpt" dim filename as c filename = context.request.getRequestTempFilename(".pdf") a5w_report_saveAs(layoutName,"PDF","","",filename,global_variables())
Sending a Report to the Client
Files can be sent back to the client browser using the context.response.SendFile() method. The file will be sent to the user's browser. The user will either be prompted to download the file or be shown the file. Using context.response.SendFile() is a Best Practice and is strongly recommended over other, less efficient methods, such as context.response.Redirect():
dim layoutName as c = context.request.applicationRoot + "MyReport.a5rpt" dim filter as c = "" dim order as c = "" dim filename as c = context.request.GetRequestTempFileName() a5w_report_saveAs(layoutName,"pdf",filter,order,filename) if file.exists(filename) ' Prompt user to save file with alternate file name: context.response.SendFile(filename,.t.,"MyReport.pdf") end if
Printing SSRS Reports
Reports created using SQL Server Reporting Services can be generated from Xbasic using the a5w_report_saveAs() function. If the SSRS report has any parameters, they can be specified using the Arguments parameter. For example:
dim reportName as c reportName = "customersbystate.ssrs.a5rpt" dim args as sql::Arguments args.add("whatcountry","UK") dim filename as c filename = "c:\pdf\report1.pdf" result = a5w_report_saveAs(reportName,"pdf","","",filename,null_value(),null_value(),args) sys_open(result)
Not all parameters are supported for SSRS reports. Specifically, you cannot use the filter, order, global variables or print options parameters.
Global Variables in Web Applications
In a desktop application, global variables are accessible throughout the application. Passing a pointer to the global variables is not necessary.
In a web application, global variables are variables defined on on the .a5w page and exist for the duration of the page. They are not accessible to other .a5w pages. You can use the global_variables() method to create a pointer to the global variables defined in an .a5w page
dim globalvars as p globalvars = global_variables() globalvars.userName = "John Smith"
If you have global variables that are used by the report, you must create and pass the global variable to the a5w_report_saveas method in a web application.
dim globalvars as p globalvars = global_variables() globalvars.myglobal1 = "foo" dim layoutName as c layoutName = a5_removeTrailingBackslash(context.request.applicationRoot) + chr(92) + "customerList.a5rpt" dim filename as c filename = "c:\data\custlist.pdf" a5w_report_saveAs(layoutName,"PDF","","",filename,globalvars)
Filter Parameters
If the report layout is based on a SQL data source and an Xbasic filter is defined in Filter, Alpha Anywhere will attempt to promote the filter to a SQL filter. SQL filtering should be preferred over Xbasic filtering. This is because a SQL filter is applied in the database query before the data is downloaded to the application server.
SQL filters are defined in the options.filter object. If the filter can be promoted to a SQL filter, the Filter parameter is automatically moved into the options.filter property, which will typically result is much better performance as the query will be executed by the database server.
An example of a filter parameter that can be promoted to a SQL filter is shown below:
quantity = 100
If Filter uses Xbasic functions in the expression, the filter is not promoted. For example, the expression below uses the Xbasic max() function.
quantity = max(100,0)
In order for this filter to be promoted to a SQL filter, it would need to be rewritten to remove the Xbasic function or rewritten as a SQL filter and added to the options.filter property.
In general, you should prefer to use a SQL filter instead of an Xbasic filter.
Uploading a Report to Amazon S3
Reports can be uploaded to Amazon S3 automatically by passing a JSON string as the Filename parameter. For example, the Xbasic below uploads the generated report to an Amazon S3 Bucket and saves it as "myReport.pdf":
'Upload a Project Report: dim layoutName as c = context.request.applicationRoot + "myReport.a5rpt" dim fileUploadJSON as c =<<%json% { "type":"Store", "ConnectionString":"AmazonS3", "objectName":"myReport.pdf" } %json% a5w_report_saveAs(layoutName,"PDF","","",fileUploadJSON,global_variables())
Emailing a Report
Similar to uploading a report to S3, you can email the report after it's generated. To do this, you need to pass in a JSON string as the Filename parameter. The JSON needs to define the API key to use (either SparkPost or SendGrid), where to send the email, the from address, email subject, and message to include in the email body. The report is sent as an attachment to the message if the htmlInline property if false, and is sent in the body of the email if the htmlInline property is true..
The example below shows the JSON required to email the report using SparkPost:
'Email a Project Report: dim layoutName as c = context.request.applicationRoot + "myReport.a5rpt" ' prefix the api key value with "sendgrid:" if using SendGrid ' e.g.: "sendgrid:1234567890XXXXX" dim fileEmailJSON as c =<<%json% { "type":"email", "apikey":"1234567890XXXXX", "send_to":"[email protected]", "send_from":"[email protected]", "subject":"Your Report", "message":"Here's the report you requested." } %json% a5w_report_saveAs(layoutName,"PDF","","",fileEmailJSON,global_variables())
See Also