Progress
Report Builder
Deployment Guide


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. Follow these steps 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:
  3. 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.

  4. Place the calculated field in the report layout.
  5. When you run Report Engine, enter the following code for the RB-OTHER-PARAMETERS value:
  6. 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

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. For example, to print the report author’s name at the top of the report, follow these steps:

  1. In Report Builder, create a calculated field named My-Name with the following expression:
  2. RUNTIME-PARAMETER("My-Name") 
    

  3. Place My-Name in a title band line.
  4. When you run Report Engine, specify the author’s name by entering the following as the RB-OTHER-PARAMETERS value:
  5. "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:

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 Progress fill-in field, Progress 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. For example, to specify the sort criteria, follow these steps:

  1. In Report Builder, create a calculated field named Sort-Criteria with the following expression:
  2. 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.

  3. Sort on the Sort-Criteria field.
  4. 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:
  5. "SORTFIELD = NAME" 
    

NOTE: If you override the sort order at run time, the sort will always be evaluated by Report Builder.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095