Xbasic

a5w_report_saveas Function

IN THIS PAGE

Specifying the Report to Print
Sending a Report to the Client
Printing SSRS Reports
Global Variables in Web Applications
Filter Parameters
Uploading a Report to Amazon S3
Emailing a Report

Syntax

filenameOut as C = a5w_report_saveAs(C LayoutName [,C Saveas_format [,C Filter [,C Order [,C Filename [,P globalVariables [,P PrintOptions [,SQL::Arguments Arguments [,P Options ]]]]]]])

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
PDF: 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.
email: 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.

If a report needs to get access to global variables defined in a .a5w page, you must use this function, and not Report.SaveAs().

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())

[PathAlias.ADB_Path] is an alias for the application webroot.

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"

Use Project Reports (*.a5rpt) in web and mobile applications when creating reports.

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())