Release 10.1A: OpenEdge Reporting:
Report Builder Deployment

> ## 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.

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