Progress
Report Builder
Deployment Guide
Complete Descriptions of Each Predefined Parameter
This section describes each of the predefined Report Engine parameters in alphabetical order.
RB-BEGIN-PAGE
Specifies the starting page number for the report. The value you specify for RB-BEGIN-PAGE must be less than or equal to the report’s ending page, which can be saved in the report definition or specified by RB-END-PAGE. The default value of RB-BEGIN-PAGE is 0, which means to use the beginning page saved in the report definition. The default beginning page value saved in a report definition is 1.
For example, A user can restart a cancelled report where it was interrupted by specifying the starting page number as the RB-BEGIN-PAGE value and 999999999 as the RB-END-PAGE value.
To reprint one or more consecutive pages of a report, specify the page numbers in the RB-BEGIN-PAGE and RB-END-PAGE parameters. To print just one page, specify the same page number for both parameters.
RB-DB-CONNECTION
Allows you to override the saved database connections by specifying the logical name of the database as saved in the report and all connection parameters Report Engine needs to connect to the database containing the report data. You can specify a string composed of any valid Progress 4GL connection parameters.
Report Builder saves all required database connection information with the report definition (except the password). You need to specify a value for RB-DB-CONNECTION only in three situations:
- If you want to run a report using a database other than the one saved with the report definition
- If you want to run a report using the same database that is saved with the report definition, but you are connecting to that database on the command line that invokes Report Engine (or in a .pf file that Report Engine reads on startup)
- If your database requires a password, and you do not want Report Engine to prompt you for it
Use the logical database name, not the physical database name, when specifying which report databases are to be overridden with the RB-DB-CONNECTION parameter.
If you have security measures such as passwords and user IDs enabled, you must specify the Password (-P) and User ID (-U) parameters or the Report Password (-rbP) parameter if you are using the table interface.
RB-DB-CONNECTION and the Report Engine Table Interface
When you use the Report Engine table interface, you can use RB-DB-CONNECTION in two ways:
- Specify all the database connection information. To do this, simply specify the database connection information using the Progress 4GL connection parameters.
- Specify to use a database to which Report Engine was connected by the command line. To do this, you must specify a complete database connection for the report on the command line or in the rbstart.pf file, then specify the RB-DB CONNECTION values. See "Report Engine Table Interface," for information about using and invoking the table interface, including using the rbstart.pf file.
You use two symbols to indicate different types of database connection overrides: “=>” and “=”. The “=>” symbol indicates to use a database already connected on the command line. The “=” symbol indicates to establish a new database connection and ignore any databases connected on the command line. The “=>” override can only be used with the table interface.
When you use these symbols to specify the database connection information, follow these rules:
To override a connection to a Progress Atlas database saved in the report definition with a connection to a non-Progress database, you must specify two connections. The first connection is to the Progress schema holder and the second is to the non-Progress database. Because you must use two connections, you cannot simply use the “=” symbol in the RB-DB-CONNECTION parameter. Instead, you must connect to the schema holder and non-Progress database on the command line and then use the “=>” symbol in the RB-DB-CONNECTION parameter to override the database used in the report with the non-Progress database. This can only be done with the table interface.
NOTE: If you put the Report Engine table into the same database as your application data, and if you create a report that refers to that database, you must use the RB-DB-CONNECTION parameter with the => symbol. If you do not, Report Engine might indicate that the database is already connected when it tries to run the report.The problem is that because the Report Engine table information is in the database, you must specify the database connection information on the command line that invokes Report Engine (or in a .pf file that Report Engine reads on startup). This means that Report Engine will already be connected to the database by the time it starts working on the report; when it tries to connect to the database requested in the report, it will be attempting to connect to the same database a second time.
Sometimes, Report Engine considers this an error; however, even if it does not, this second connection can slow down your database server. To avoid this, when you run this report, you must specify a value for RB-DB-CONNECTION that tells Report Engine to reuse the connection it has already made, rather than trying to establish a new connection for the report.
The RB-DB-CONNECTION value looks something like this:
Note that logical1 is the logical name of the database as stored in the report and logical2 is the logical name used for the same database in the connection parameters on the command line. In this situation, where the Report Engine database is the same as the application database, these two logical names are often the same.
The following example shows how to override the stored connection information. If the report definition specifies the physical database as newdb1.db and the logical database name as newdb1, you override the saved database with a connection established on the command line with the following steps:
- Override the saved database connection information using the following value in the RB-DB-CONNECTION parameter:
The “=>” symbol indicates to use a database already connected on the command line. This parameter value means that when Report Engine runs the report, it uses the connection established on the command line and does not attempt to make a connection to the newdb1 database.
- Invoke Report Engine with the following command:
This command invokes Report Engine with a connection to the newdb2 database. In this example, the newdb2 database contains both the tables required by the report and the table (Rep-Eng) that specifies the RB-DB-CONNECTION parameter value.
Instead of specifying the connection on the command line, you could have used the following value in the RB-DB-CONNECTION parameter in the Rep-Eng table:
The “=” symbol indicates to establish a new database connection using the specified connection information and ignore the databases connected on the command line. This value means that when you invoke Report Engine, it will override the stored database connection information for newdb1 with the information “-db newdb3 -1".
You can override the database connection information for multiple databases using the RB-DB-CONNECTION parameter. To override multiple databases in the same RB-DB-CONNECTION parameter value, separate each section with a new-line character (~n) as shown in the following example:
This example overrides the connection information for three report databases (with logical names sample, demo, and sports). Notice that each database override is separated by a new-line character (~n). When entering data into a Progress fill-in field, you must use CHR(10) to identify the new-line character.
When you are overriding database connection information for a report that uses multiple databases, you do not have to provide override information for all the databases; only the ones that you want to override.
There are several reasons to use the table interface with RB-DB-CONNECTION:
- You can specify overrides for more than one database.
- You can use the RB-DB-CONNECTION parameter to reference a database connected on the command line, rather than hard-coding the connect string in the RB-DB-CONNECTION parameter.
- If all the reports are run against the same database, you can connect to it on the command line, and then Report Engine maintains that one database connection for all reports instead of re-establishing the connection as it runs each report.
RB-DB-CONNECTION and the Report Engine PRINTRB and PRNTRB2 Interfaces
When you use the PRINTRB or PRNTRB2 interfaces to the Report Engine, the RB-DB-CONNECTION parameter allows you to override only one database.
In versions of Report Builder before Version 8.0, the parameters in the RB-DB-CONNECTION parameter to PRINTRB do not completely substitute for the full database connection string in the report definition. Instead, Report Engine substitutes them on a connection-parameter-by-connection-parameter basis. Thus, if your report definition specifies the connection information “-db orders -N tcp -H server -S ordersrvc”, and the RB-DB-CONNECTION parameter specifies the string “-H newserver”, Report Engine uses the connection string “-db orders -N tcp -H newserver -S ordersrvc” when it attempts to establish the database connection. Therefore, it unintentionally prevents you from overriding the previously described report database connection with a new connection string such as “-db c:\mydata\orders -1", because there is no way to eliminate the -H, -S, and -N connection parameters.
Because some users might have utilized this behavior, Report Builder Version 8.0 and greater retains it. However, Report Builder also augments the syntax of the RB-DB-CONNECTION parameter to allow you to completely replace the report database connection information. If you specify the RB-DB-CONNECTION parameter as “orders=-db c:\mydata\orders -1", where the leading “orders=” indications the logical name of the database as specified in the report definition, Report Engine discards all the connection information saved in the report definition and uses only the newly specified database connection parameters.
With the PRINTRB or PRNTRB2 interfaces, you cannot use the “=>” symbol. However, you can use only the “=” symbol. The “=” symbol indicates to establish a new database connection using the specified connection information.
When you use the “=” symbol to specify the database connection information, follow these rules:
For example, if the report definition specifies the physical database as newdb1.db and the logical database name as newdb1, you use the RB-DB-CONNECTION parameter to override the connection information using the following value:
This value means that when you invoke Report Engine, it will override all the stored database connection information for newdb1 with the information “-db newdb3 -1". The “=” symbol indicates to establish a new database connection using the specified connection information.
For backward compatibility, you can still use the syntax required by earlier versions of Report Builder to override individual parameters. For example, the following value tells Report Engine to simply add the values to the existing connection information stored in the report:
RB-DISPLAY-ERRORS
Controls whether Report Engine displays an error message dialog box when it encounters an error.
If the parameter is false and you are using the PRINTRB and/or PRNTRB2 interfaces, Report Engine does not display the error messages, but writes them to the report status file in the current working directory. However, if you are using the table interface, Report Engine writes to the report status file only if you use the Report Status File (-rbstatfile) parameter. The report status file is a text file to which Report Engine writes status and error information. For information about the status file, see the “Verifying Report Status” section of Report Engine Administration."
If the parameter is true, Report Engine displays the error message on the screen in addition to possibly writing it to the report status file. When Report Engine displays the error message dialog box, the user must choose OK to acknowledge the error. Report Engine then either terminates processing of that report or displays a dialog box where the user can enter the correct information.
RB-DISPLAY-STATUS
Controls whether Report Engine displays a Print Status window while it generates a report.
If the parameter is false, Report Engine does not display a Status window, but displays as an icon while it is running.
If the parameter is true, Report Engine displays a Status window.
RB-END-PAGE
Specifies the ending page number for the report. The default value for this parameter is 0, which means to use the ending page saved in the report definition. The default ending page saved in the report definition is 999999999. The value you specify for RB-END-PAGE must be greater than or equal to the report’s beginning page, which can be either saved in the report definition or specified using RB-BEGIN-PAGE.
For example, to print only the first ten pages of a long report, specify RB-BEGIN-PAGE as 1 and RB-END-PAGE as 10.
To reprint one or more consecutive pages of a report, specify the page numbers in the RB-BEGIN-PAGE and RB-END-PAGE parameters. To print just one page, specify the same page number for both parameters.
RB-FILTER
Specifies a logical expression to override the filter saved in the report definition, if any, when RB-INCLUDE-RECORDS is set to override ("O").
The syntax of the RB-FILTER expression is identical to that of any calculated field expression that returns a logical value. The RB-FILTER expression can be up to 1024 characters long. When an expression is specified, Report Engine selects all records where the value of the RB-FILTER expression is true. The expression can reference any data, aggregate fields, or calculated fields that are available in the report. See the Progress Report Builder User’s Guide for the restrictions on filtering with aggregate and calculated fields.
If the expression you enter is not server-evaluatable, the report might run significantly slower. See the Progress Report Builder User’s Guide for more information about server-evaluatable expressions.
For example, if you enter the filter expression City = "Dallas", Report Engine selects all records where the value in the City field is Dallas. If the city name were in a character field named City-Note, the following filter expression selects all records in which the City-Note field begins with the word "Dallas":
You must enclose literal strings in quotation marks and use the tilde-quote (~"string~") or quote-quote (""string"") around the embedded character strings.
Entering Balance >= 200 selects all records where the value in the Balance field is greater than or equal to 200. To select records where the date in the Order-Date field of the Order table is January 31, 1994, use this format:
If the same field name exists in more than one table used in your report, you must specify the table alias and the field name as shown in the previous example.
You can enter compound filter expressions by using parentheses. For example, the following filter expression selects all records where the value in the City field is either Dallas or Houston and where the value in the Credit-Limit field is greater than 50,000:
See the Progress Report Builder User’s Guide for information about the order in which Report Builder evaluates expressions.
NOTE: You must set RB-INCLUDE-RECORDS to override ("O") for the RB-FILTER to override the filter in the report definition.RB-INCLUDE-RECORDS
Controls whether to apply a filter to the report at run time. Table 3–2 lists the valid RB-INCLUDE-RECORDS values.
When you use the question mark (?) value for the RB-INCLUDE-RECORDS parameter, Report Engine ignores the value of RB-FILTER.
RB-MEMO-FILE
Contains the name and optional directory location of a memo file to be used in place of the one saved in the report definition. The override memo file must be on the machine where Report Engine is running. Report Engine searches for the memo file in the following ways:
If you leave this parameter blank, Report Engine uses the memo file specified in the report definition.
RB-NO-WAIT
Specifies whether to use synchronous or asynchronous processing when you are using the PRINTRB or PRNTRB2 interfaces. If this parameter is “No”, then
aderb/_printrb.p
does not return until Report Engine finishes printing the report. If it is “Yes”, thenaderb/_printrb.p
returns as soon as Report Engine starts, allowing the 4GL program to continue with other tasks while the report prints.RB-NO-WAIT is required only with the PRINTRB and PRNTRB2 interfaces. In order to run multiple instances of Report Engine with PRNTRB2, RB-NO-WAIT must be set to “Yes.” You cannot use this parameter if you are using the table interface. Instead, you specify this functionality as an argument to
_prore.p
. See "Report Engine Table Interface," for more information.RB-NUMBER-COPIES
Specifies the number of copies of the report you want to print. The number must be between 0 and 999, inclusive. If you enter 0, Report Engine prints the number of copies specified in the report definition. If you specify a number, the specified value overrides the number entered in the Report Builder Print Setup dialog box.
RB-OUTPUT-FILE
Saves report output as a file for printing later, or use it in conjunction with RB-PRINT-DESTINATION to export a report to a text file without printer control codes. The name of the output file can include a path. The override output file must be on the machine where Report Engine is running.
For example, to send a report to a text file
Order.txt
in thec:\projects\text
subdirectory, specify the following value for the RB-OUTPUT-FILE parameter, and RB-PRINT-DESTINATION as “A”:
If RB-OUTPUT-FILE does not include a path, Report Engine places the file in the current working directory.
When you specify this parameter, and if RB-PRINT-DESTINATION contains the value A, the report outputs as a text file. If the value of RB-PRINT-DESTINATION is anything other than A, Report Engine outputs the report to a file with printer control codes.
If RB-OUTPUT-FILE does not include a path, Report Engine places the file in the current working directory.
RB-PRINT-DESTINATION
Specifies to print the report on the printer specified in the report definition or with the RB-PRINTER-NAME parameter or to display the report on the screen. Leave the parameter blank to print to the printer saved in the report definition or to the printer specified as the RB-PRINTER-NAME value. Table 3–3 describes the valid RB-PRINT-DESTINATION values.
RB-PRINTER-NAME
Specifies the printer on which to print the report. You can specify:
- The name of an available Windows printer (for example, “HP LaserJet Series III”). In Report Builder choose Report
Print Setup to access the Printer Setup dialog box. This dialog box lists the available Windows printers.
- A question mark (?) to allow the user to select a printer at run time. When RB-PRINTER-NAME contains a question mark, the Printer Setup dialog box appears.
- A blank value to use the printer saved in the report definition
Regardless of which value is specified, the printer must be a printer that is available to the machine where Report Engine is running.
When you specify a question mark (?), the Printer Setup option in the Windows Control Panel controls which printers appear in the Printer Setup dialog box. The selected printer is always the printer specified in the report definition. The user can select another printer and port or choose the Setup button to change other print characteristics.
You cannot override the paper tray selection with the Report Engine parameters. You can change the paper tray selction only when running a report. However, if you specify a tray (upper or lower) and use a printer that has only a single tray, Report Engine runs the reports correctly.
RB-PRINTER-PORT
Specifies the printer port. You can:
Regardless of which value is specified, the port must be on the machine where Report Engine is running.
RB-REPORT-LIBRARY
Identifies the library that contains the report. The library name can include a path. If you do not include a path, Report Engine searches for the library in the default directory specified in the registry or
NOTE: You must specify the library name. If you leave this parameter blank or if the library you specify cannot be found or read, Report Engine writes an error in the status file or RB-STATUS field, depending on the interface or optional command-line parameters you are using. Regardless of which interface you use, if you enable RB-DISPLAY-ERRORS, Report Engine displays an error message box.progress.ini
. If you have not specified a default library directory, Report Engine searches for the library in the current working directory. The .prl extension is optional. The report library must be accessible from the machine on which Report Engine is running.For example, a value of
c:\projects\reports
identifies the report library asreports.prl
in the subdirectoryprojects
on drive C.RB-REPORT-NAME
Specifies the report name.
For example, to run a report named Discount Order, enter "Discount Order" as the value for this parameter. The report you specify must be in the library specified by RB-REPORT-LIBRARY.
NOTE: You must specify the report name. If you leave this parameter blank or if the report does not exist in the library you specify, Report Engine writes an error in the status file or RB-STATUS field, depending on the interface or optional command-line parameters you are using. Regardless of which interface you use, if you enable RB-DISPLAY-ERRORS, Report Engine displays an error message box.RB-STATUS
Specifies the status of the report generation for the table interface. If you specify the Report Update (-rbupds) parameter when you invoke Report Engine, Report Engine updates the RB-STATUS field with information describing where it is in the report generation process. Table 3–4 describes the possible parameter values.
For example, if you specify -rbupds when you invoke Report Engine, when Report Engine starts generating the report, it sets the value of the RB-STATUS field to “STARTED.”
You optionally use RB-STATUS when you use the table interface. You cannot use this parameter with the PRINTRB interface.
RB-STATUS-FILE
Specifies the filename of the report status file into which Report Engine will write the status information.
This parameter tells Report Engine to create a file containing information about the report it has generated. This file is called the report status file. If the file does not exist, Report Engine creates one. If the file does exist, Report Engine overwrites it. If you do not specify a filename, Report Engine does not generate a status file. If you do not specify the full pathname, Report Engine uses its current working directory.
For example, to create a status file
status.txt
in thec:\work\status
subdirectory, specify the following value for the RB-STATUS-FILE parameter:
RB-TAG
Specifies a tag that determines whether to generate a report, based on the value from the Report Tag (-rbtag) parameter, when you use the table interface. When Report Engine generates the reports for which you have specified report parameters in the table, it generates only those whose values in this parameter match the -rbtag parameter value.
If you do not specify a -rbtag value, Report Engine runs all the reports in the Report Engine table, regardless of the value in the RB-TAG field.
For example, if the Report Engine table contains report records for four different quarterly reports, you can assign each set of records for a quarter a different RB-TAG value such as Q1, Q2, Q3, and Q4. Then when you invoke Report Engine, specify the desired tag with the -rbtag parameter. For example, to run the reports for the first quarter, you specify Q1 as the -rbtag value:
Another way to use this parameter is to store the reports for multiple users in the Report Engine table, then specify a specific user’s tag to run only his or her reports.
You optionally use RB-TAG when you use the table interface. You cannot use this parameter with the PRINTRB or PRNTRB2 interfaces.
RB-TEST-PATTERN
Controls whether Report Engine allows the user to print a test pattern. A test pattern is useful for aligning forms or labels in the printer.
The test pattern flag can be either true or false. True means to display a prompt before printing the report to allow the user the option of printing a test pattern. False means do not display this prompt.
If the parameter is false, Report Engine does not offer a choice to print a test pattern.
If the parameter is true, Report Engine prompts the user to select whether to print the test pattern before printing the report. The user can print the test pattern as many times as necessary and then print the report.
RB-WINDOW-TITLE
Displays the specified title in the following places:
- The Title Bar of the Preview window
- The Print Status window (if RB-DISPLAY-STATUS = True)
- Below the Runtime icon (if RB-DISPLAY-STATUS = False)
- The title bar of the dialog box that displays when RB-PRINT-DESTINATION = ?
By default, Report Engine displays the report name in these places. You can enter up to 31 characters for the window title.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |