Command line interface for the OI BRW (Reporting and Printing)
Created at 17 JAN 2012 03:22PM
To start up the Banded Report designer, you can do the following:
CALL RTI_BRWSUPPORT("LAUNCH")
Once you have your report(s) defined, you can generate them programmatically using the following:
CALL RTI_BRW_GENERATEREPORT(rptFile, rptName, outputName, rptType, overrideListID, rptDetails, bUseGUI)
where rptFile is the name of the report group you saved the desired report(s) into and rptName is the name of the 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.
OutputName is 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 is 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 is 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 is only used when the rptType is PDF - if desired, you can specify in rptDetails the access permissions for the PDF, and the password(s) for PDF access.
bUseGUI is a flag that indicates whether you want report generation to occur with a GUI (set bUseGUI to "1") or without a GUI, ie, silently (set bUseGUI to "0"). Note that if the output is going to the printer, you can also set bUseGUI to "2" - in this case, you'll get a full print preview window, instead of just a printer control window as you would if bUseGUI is "1". Note that the default if bUseGUI is not specified is "0" (no GUI).
You can also call, during SET_PRINTER, the LOADREPORT call; this will "embed" generated BRW output into OIPI output (this is only available when using VSPRINTER2, aka OIPI.NET). You'll pass in to the SET_PRINTER call the name of the report group, the name of the report to include ("*" for all in the group, or a semicolon-delimited list), the overrideListName, and a flag (0/1) to indicate whether the BRW report is appended to the current output (1) or replaces the current output (0).
Note that in both cases (LOADREPORT in OIPI.NET, or RTI_BRW_GENERATEREPORT) you can if desired pass in a full report definition (which is just an XML string) in the "report group" parameter. In this way, you can actually access the report definition and modify it, or create one entirely programmatically.
If this is something you wish to do, you can use the following to read an existing report definition:
rptdef = RTI_BRWSUPPORT("READ", reportGroupName, bLockFlag)
where reportGroupName is the name of the report group, and bLockFlag is a flag to indicate whether the record should be locked (1) or left unlocked (0).
By default, the RTI_BRW_GENERATEREPORT routine can generate one or more documents of the same output type (PDF, print, XLS, etc.) that are all contained in a single report group. For example, to invoke RTI_BRW_GENERATEREPORT to build a PDF based on the report “Sample Report” in the report group “SAMPLES”:
DECLARE FUNCTION RTI_BRW_GENERATEREPORT
reportGroup = “SAMPLES”
reportName = “Sample Report”
outputName = “C:\TEMP\OUTPUT.PDF”
reportType = “PDF”
bUseGUI = “0”
rslt = RTI_BRW_GENERATEREPORT(reportGroup, reportName, outputName, reportType, ‘’, ‘’, bUseGUI)
If you wish to build multiple reports (contained in the same report group) of the same output type, multiple report names can be specified in a single request, using the semicolon delimiter. For example, to build a PDF based on the reports “Sample Report” and “Example Output”, both contained in the “SAMPLES” report group:
DECLARE FUNCTION RTI_BRW_GENERATEREPORT
reportGroup = “SAMPLES”
reportName = “Sample Report;Example Output”
outputName = “C:\TEMP\OUTPUT.PDF”
reportType = “PDF”
bUseGUI = “0”
rslt = RTI_BRW_GENERATEREPORT(reportGroup, reportName, outputName, reportType, ‘’, ‘’, bUseGUI)
If you wish to generate multiple different output types (for example, both PDF and print output) or output from different report groups, these can also be created with a single call to RTI_BRW_GENERATEREPORT by using the record mark delimiter (@RM) to delimit each report file, report name collection, output name, report type, override list name, and GUI flag.
For example, to build a PDF based on the report “Sample Report” in the report group “SAMPLES”, and an on-screen display of the report “Display Report” in the report group “DISPLAYS”:
DECLARE FUNCTION RTI_BRW_GENERATEREPORT
reportGroup = “SAMPLES”:@rm:”DISPLAYS”
reportName = “Sample Report”:@rm:”Display Report”
outputName = “C:\TEMP\OUTPUT.PDF”:@rm:””
reportType = “PDF”:@rm:”PRINT”
bUseGUI = “0”:@rm:”2”
rslt = RTI_BRW_GENERATEREPORT(reportGroup, reportName, outputName, reportType, ‘’, ‘’, bUseGUI)
As seen in the above examples, the RTI_BRW_GENERATEREPORT stored procedure is a function that can return a status value so the developer can determine the results from the request. Note that many of the available status values (and the parameter modifications, described below) will only be set when the BRW is configured to use a new engine to generate its output; when configured to ‘share’ the current engine (the default), most of these values will not be returned.
The return values are:
0: success
-1: Either parameter “reportFile” or “reportName” is null (“”)
1: Report definition is null – specified report is not on file
2: unable to open SYSLISTS table
<error text> : error returned by call to the BRW component
<ole status>: error returned by call to the BRW component
In addition, the RTI_BRW_GENERATEREPORT routine may modify the passed-in parameters for “reportName” and “outputName”. If multiple reports are specified in the reportName parameter (either by using the “*” wildcard, or explicitly by using multiple report names separated by semicolons (“;”)), when the RTI_BRW_GENERATEREPORT completes, the reportName parameter will be changed to a full list of all the individual report names that were accessed (@VM delimited), and the outputName parameter will be changed to a full list of all the individual output files that were generated (one per report name), @VM delimited.
RTI_BRWSUPPORT is a handy function with a few different actions. We've already discussed LAUNCH and READ; you can also call it with the following actions:
DISPLAY: pass in the report group name and specific report name (in parameters 2 and 3) and the report will be displayed via OIPI.NET;
REPORTS: this will return, as the result of the function call, an @VM delimited list of the report groups defined for your application