Banded Report Writer Revealed – RTI_BRW_GenerateReport
Our next installment in the Banded Report Writer Revealed series explores the second of the two primary stored procedures that provide command line interaction with this rich reporting tool. Whereas the RTI_BRWSupport function provides multiple services, the RTI_BRW_GenerateReport function only has one purpose: to generate BRW reports. Thus, RTI_BRW_GenerateReport works with the Banded Report Writer in much the same way that Run_Report works with the Report Builder. Like the RTI_BRWSupport function, RTI_BRW_GenerateReport is documented in the more recent BRW Reference Guides (see pages 82ff.), but we’ll see that there is still more to discover than what has been put in the official documentation.
One might ask this question: if the RTI_BRWSupport function can also generate BRW reports (via the DISPLAY action), why do we need RTI_BRW_GenerateReport? Why not just focus on RTI_BRWSupport as a one-stop-shop function? One of the most significant reasons is that RTI_BRWSupport does not communicate directly with the Banded Report Writer .NET assembly. Instead, it goes through the same layer that the Set_Printer LOADREPORT message does: OIPI.Net. This is relevant because OIPI.Net works through the OpenInsight presentation server.
RTI_BRW_GenerateReport, on the other hand, works directly with the underlying .NET assembly. This opens up additional opportunities for developers who wish to provide dynamic reports through web applications or any other “engine farm” system. When the presentation server is required, the developer is forced to use an alternative approach. Typically, this becomes a rather complex and relatively brittle system that launches OpenInsight on the desktop. This instance then polls for queued report requests, generates a report, and then it notifies the waiting OpenEngine for pick up. Hence, lots of moving parts are required when the report cannot be generated directly.
The following documentation uses a layout familiar to anyone who uses the Programmer’s Reference Guide. This has also been added to our wiki site alongside the other pages of Banded Report Writer documentation:
Description
RTI_BRW_GenerateReport is a routine that allows banded reports to be generated with a variety of options.
Syntax
RTI_BRW_GenerateReport(rptFile, rptName, outputName, rptType, overrideListID, rptDetails, bUseGUI, overrideCfg)
Parameters
The function has the following parameters:
| Parameter | Description | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| rptFile | The name of an existing report group or a dynamically generated XML report definition string. Note: If the XML report definition string was derived using the READ action of the RTI_BRWSupport function, a Swap \0D0A\ with @FM command needs to be ran against the XML string. This is because RTI_BRW_GenerateReport looks for the presence of @FM delimiters in rptFile to determine if this is an XML report definition string. If the XML report definition string was derived differently, such as a direct read from the SYSREPOSREPORTS record, then a different step might be required. Newer versions of the BRW embed the version into attribute 1 and the dynamic dictionary data (or an empty string if there are none) into attribute 2 before the report definition string. These need to be removed from the XML string or the following error will result: Data at the root level is invalid. Line 1, position 1 |
|||||||||||||||||||||
| rptName | If rptFile contains the name of a report group, then rptName contains the name of a specific report to run (or "*" to run all the reports in the group). You may also specify a semicolon-delimited list of report names if desired. Note: The "*", or wildcard, feature and the semicolon delimited list only work with specific CFG_OIBRW configuration settings. In short, only those settings that create new engines and then close them after each report will work properly. See the CFG_OIBRW Configuration article for more information. |
|||||||||||||||||||||
| outputName | The path and name of the file to save the output to (if producing a PDF, HTM, etc. document). Leave this blank to generate printed output. | |||||||||||||||||||||
| rptType | The type of output to generate, and can be PDF, TIFF, HTML, TEXT, XLS, or XLSX (or PRINT to generate printed output, but that isn't really needed if you leave outputName blank). | |||||||||||||||||||||
| overrideListID | The ID of a saved list that contains the record keys you want this report generation to use. If there is no overrideListID specified, but there is an active select list when RTI_BRW_GenerateReport is called, then the active list will be used instead. | |||||||||||||||||||||
| rptDetails | When the rptType is PDF, you can specify the access permissions for the PDF, including the password(s) for PDF access. If rptType is PRINT (or ""), you can use this parameter to specify the printer name to use and other report options (see table below):
For all report types (i.e., rptType can be set to anything), <1, 1, 1> can be set to a literal "UID" and <1, 1, 2> can be set to any custom value. Doing this informs the BRW that this report has a unique identifier, which can be used in the INIT or TERM actions of the designated OI_BRW_FILTER hook. |
|||||||||||||||||||||
| bUseGUI |
|
|||||||||||||||||||||
| overrideCfg | OECGI Invocation Only - Override configuration settings to be used for this instance of the BRW. While the format of this setting uses the same attributes as the CFG_OIBRW configuration record, no defaults will be applied. Therefore, each attribute will have to be explicitly populated (i.e., fully resolved) with the correct value. See the notes regarding each attribute's default value in the the CFG_OIBRW Configuration article to understand how to resolve these values. The purpose for an override setting is to ensure that systems like O4W can call the BRW with applicable configuration settings. For instance, the default configuration might be to share the engine, but O4W systems require a new connection. Note: Even if this is not an OECGI invocation, pass in an empty string to avoid a VNAV error. |
|||||||||||||||||||||
| Returns |
|
Remarks
Multiple reports, even from different report groups, can be ran from a single RTI_BRW_GenerateReport call through @RM delimited values for each parameter. This is similar to the way Set_Property supports @RM delimited parameters. While multiple reports can be specified to export to a file, this cannot be used to create a single file that contains all reports. Each report must have its own file name or older reports will be overwritten.
RTI_BRW_GenerateReport is the only way to create PDF reports without the use of the Presentation Server. Using RTI_BRWSupport or the LOADREPORT Set_Printer message both work through OIPI.Net, which requires the Presentation Server.
Dynamically created XML report definitions do not support Dynamic Dictionaries. These will come through as plain text.
See the notes for the rptFile parameter for important information when passing in dynamically generated XML report definition strings.
Leave a Reply