skip to main content
OpenEdge Reporting: Report Builder Deployment
Report Engine Parameters : User-defined parameters
 
User-defined parameters
User‑defined parameters are character string arguments that you specify in the RB-OTHER-PARAMETERS field. Regardless of which interface you use, you can specify multiple user‑defined parameters or arguments, but Report Engine expects to find them all in a single RB-OTHER-PARAMETERS value.
User‑defined parameters provide only character values (text strings) to Report Engine. If you want to access a numeric, date, or logical value, you must perform the conversion from character to the desired data type within the report definition. See the “Overriding a table name” section for information about converting values.
You can use user‑defined parameters to provide information that you do not want hard‑coded in the report definition. You can also specify user‑defined parameters to override table specifications and prompt for user input.
The following steps describe how to override all report characteristics except table names. See the “Overriding a table name” section for an example of how to specify different table names for a report.
To use a user-defined parameter:
1. Decide upon a parameter name to identify the parameter. Parameter names can be up to 32 characters long and can consist of alphabetic characters (A–Z, a–z), digits (0–9), and special characters ($, &, #, %, –, _). In addition, parameter names must begin with a letter (A–Z, a–z). Each name must be unique within the report and cannot contain spaces.
2. In the Report Builder, create a calculated field that uses the RUNTIME-PARAMETER( ) function using the following format for the field’s expression:
 
RUNTIME-PARAMETER("parameter-name")
The RUNTIME-PARAMETER( ) function takes a quoted parameter name as its argument and returns the value of the parameter as a string.
3. Place the calculated field in the report layout.
4. When you run Report Engine, enter the following code for the RB-OTHER-PARAMETERS value:
 
parameter-name = value
If you allow your users to specify report characteristics at run time, you can create one report definition and use it with the user input to run many different reports from the same report definition. See the “Prompting for user input” section for information about prompting users for information.
This section describes the following examples of how to use user‑defined parameters:
*Overriding a table name.
*Specifying an author’s name.
*Specifying multiple user‑defined parameters.
*Overriding the sort criteria.
Overriding a table name
You can override the tables specified in the report definition with tables that have the same structure. Therefore, if you store your quarterly information in four tables with identical structures and you create the report definition with the First-Quarter table, when you run Report Engine, you can use the Second-Quarter, Third-Quarter, or Fourth-Quarter table instead.
The syntax for overriding tables is different from the generic user‑defined parameter syntax in that the parameter “name” is a report “table-alias”. To override the table specified in the report definition, enter the table alias and the new table name.
For example, if you specify the First-Quarter table in the report definition with an alias of “Quarter”, when you run Report Engine, enter the following code in the RB-OTHER-PARAMETERS parameter to use the Third-Quarter table instead:
 
"Quarter = Third-Quarter"
Specifying an author’s name
You can specify an author’s name when you generate a report.
To print the report author’s name at the top of the report:
1. In Report Builder, create a calculated field named My-Name with the following expression:
 
RUNTIME-PARAMETER("My-Name")
2. Place My-Name in a title band line.
3. When you run Report Engine, specify the author’s name by entering the following as the RB-OTHER-PARAMETERS value:
 
"My-Name = Todd Winmill"
Report Engine prints “Todd Winmill” in the title area of the report.
Specifying multiple user‑defined parameters
You can specify up to 99 table override parameters and as many user‑defined parameters as you need. Follow these rules when entering multiple parameters:
*Separate each parameter with a 1‑byte linefeed character (ASCII value 10.) In character string constants in 4GL code, you can use the two‑character symbol “~n” to represent the 1‑byte linefeed character.
*Use only one set of quotation marks for the entire argument. Because all of the parameters make up one character string, you cannot enclose each parameter in a separate set of quotation marks.
For example:
 
"City = Boston~nState = MA~nQuarter = Third-Quarter"
Note: The two‑character sequence “~n” represents the linefeed character only when you use it with a 4GL application. If you enter “~n” in a 4GL fill‑in field, the 4GL does not convert it to a 1‑byte linefeed character.
Another way to separate multiple user‑defined parameters is to use “CHR(10)” to identify a line feed instead of embedding “~n” in a string.
For example:
 
"City = Boston" + CHR(10) + "State = MA" + CHR(10) + "Quarter = Third-Quarter"
Notice that when you use “CHR(10)” instead of “~n”, you must enclose each user‑defined parameter in quotation marks.
Overriding the sort criteria
You can override the sort criteria at run time with a user‑defined parameter.
To specify the sort criteria:
1. In Report Builder, create a calculated field named Sort-Criteria with the following expression:
 
CASE(RUNTIME-PARAMETER("SORTFIELD"), "NAME", Name, "STATE", State, 
"ZIP CODE", Postal-Code, City)
Because the CASE function requires that all potential return values have the same data type, you must list fields that have the same data type for sort criteria options.
2. Sort on the Sort-Criteria field.
3. When you run Report Engine, choose a sort criteria from the four choices (Name, State, Postal-Code, or City), using the RB-OTHER-PARAMETERS parameter. For example:
 
"SORTFIELD = NAME"
Note: If you override the sort order at run time, the sort will always be evaluated by Report Builder.
Parameter guidelines and restrictions
Each time you run Report Engine, you must specify a value for each of its parameters, even if that value is blank or zero (for the PRINTRB and PRNTRB2 interfaces) or is the parameter field’s default value (for the table interface). Each of the parameter values must be of the correct data type for the corresponding Report Engine parameter.
Note: For the PRINTRB and PRNTRB2 interfaces, the parameters must also be in the correct order (the order in which they appear in Table 3–1).
You must specify a value for two parameters: RB-REPORT-LIBRARY and RB-REPORT-NAME. If you do not specify the report name and library name, Report Engine cannot run the report. For the remaining parameters, you can specify either a real value or a special default value. The default value specifies to use the value stored in the report definition. The default value is different for each data type.
 
Table 3–5: Report Engine parameter default values 
Parameter data type
Default value
Character
""
Numeric
0
Logical
NA
When you use the table interface, the default values listed in Table 3–5 match the Initial Value that is used by default when you create a new record in the Report Engine table. (The Initial Value is specified when you create a field in the Data Dictionary.) Thus, when you create a record, all the fields are set to the default value. However, you must assign actual values to RB-REPORT-NAME and RB-REPORT-LIBRARY fields before you call Report Engine.
Prompting for user input
You can use both predefined and user‑defined parameters to prompt users for input. However, the user must be using the machine where Report Engine is running.
Prompting for input with a predefined parameter
There are two ways to prompt for user input using predefined parameters. The first way is to write your own 4GL code to prompt users for input, then pass the values to Report Engine using predefined parameters. The second way to prompt for user input is to use the built‑in Report Engine prompting mechanism. Several of the predefined parameters allow you to specify a question mark (?) as the parameter value. When you specify a question mark, Report Engine automatically prompts the user for input for the parameter.
You can specify a question mark for the RB-PRINT-DESTINATION, RB-PRINTER-NAME, RB-PRINTER-PORT, and RB-INCLUDE-RECORDS parameters.
Prompting for input with a user‑defined parameter
You can prompt a user for other report information using a user‑defined parameter.
In the “Specifying an author’s name” section, the example shows how to print the report author’s name at the top of the report.
To prompt the user to enter his or her name:
1. In the Report Builder, create a calculated field named MYNAME with the following expression:
 
RUNTIME-PARAMETER("MYNAME")
2. Place MYNAME in the title band line.
3. When you run the Report Engine, you can:
*Use the Report Engine prompt to prompt the user to enter his or her name using the following code in the RB-OTHER-PARAMETERS parameter:
 
"MYNAME = ?"
A dialog box similar to the one shown below appears:
*Customize the prompt using the following code:
 
"MYNAME = ?Please enter your name:"
A dialog box similar to the one shown below appears:
Note that the title of the two dialog boxes shown is customer. This is because when you prompt users for input, the dialog box title bar contains the value of the RB-WINDOW-TITLE parameter. If RB-WINDOW-TITLE is empty or UNKNOWN, Report Engine uses the report name as the dialog box title.
You cannot modify the dimensions of the dialog box to accommodate the anticipated user input. The dialog box always remains the same size and users can enter up to 512 characters. If the user chooses the Cancel button, Report Engine does not run the report and writes the “Cancelled” message to the report status file or the RB-STATUS field, depending on the interface and command‑line parameters you use. See the “Verifying report status” section for information about the status file.
Incorporating parameters in the report definition
The RUNTIME-PARAMETER() function takes a parameter name as its argument and returns the value of the parameter as a string. This means that user‑defined parameters provide only character values (text strings) to Report Engine. If you want to access a numeric, date, or logical value, you must perform the conversion from character to the desired data type within the report definition.
To convert to numeric, date, or logical values, use the functions shown in the following table in a calculated field in the report definition:
 
To convert to . . .
Use . . .
Numeric data
NUMERIC (parameter)
Dates
DATE (parameter)
Logical data
IIF (parameter = "Yes", Yes, No)
You can also use the RUNTIME-PARAMETER( ) function to get the value of predefined parameters whose arguments are character strings.
To print the database connection information on the title band line:
1. In Report Builder, create a calculated field named Connect-String with the following expression:
 
RUNTIME-PARAMETER("RB-DB-CONNECTION")
2. Place Connect-String in the title band line.
When Report Engine prints the report, it displays the database connection information specified by the RB-DB-CONNECTION parameter in the report title area.