A parameter is a value either entered by the user or passed to the report that can be used for something. For example, Report Writer automatically adds two parameters to reports: ReportTitle and ReportFilter. It passes the title of the report to ReportTitle and the filter condition to ReportFilter. Both are data-bound to label objects in the PageHeader band so the report title and filter condition appear at the top of every page.

Editing a parameter

You can add a parameter that prompts the user for a value, and then use that value in some way in the report. To do that, select the Field List, right-click the Parameters item or an existing parameter, and choose Add Parameter from the shortcut menu to display the Add New Parameter dialog.

The settings in this dialog are:

• Name: the name of the parameter. The name must start with a letter or underscore and can only contain letters, numbers, and underscores.

• Description: the prompt the user sees when they run the report if Show in the parameters panel is turned on.

• Type: the data type of the parameter's value: String, Date, Number (16 bit integer), Number (32 bit integer), Number (floating-point), Number (double-precision floating-point), Number (decimal), and Boolean.

• Default Value: the default value to use. This appears as Value in the Property Grid when you select the parameter in the Field List.

• Show in the parameters panel: turn this on if the user should be prompted for the value or off if not. This appears as Visible in the Property Grid when you select the parameter in the Field List.

• Supports the collection of standard values: turn this on to enable the other settings, which allow you to define standard values the user can choose from. If this is turned off, the Look-Up Settings property in the Property Grid is set to No Look-Up.

• Dynamic values: choose this tab to set properties specifying how to get values from the database. Doing so sets the Look-Up Settings property in the Property Grid is set to Dynamic List.

• Data Source: the name of the result set for the report. You can normally leave this blank, but if there's more than one data set, choose the desired one from the list.

• Data Adapter: the data adapter to use. You can normally leave this blank, but if there's more than one data adapter, choose the desired one from the list.

• Data Member: the name of the data table in the data set for the report. You can normally leave this blank, but if the data set contains more than one data table, choose the desired one from the list.

• Value Member: the name of the field containing the values to use.

• Display Member: the name of the field containing the values to display to the user.

• Static values: choose this tab to define a hard-coded list of values. Doing so sets the Look-Up Settings property in the Property Grid is set to Static List. To add a value, click the + button and enter the value and its description. To remove the selected value, click the - button. Click the arrow buttons to move through the list or simply scroll the list and click on a value to select it.

To edit a parameter's properties, select it in the Parameters list and edit it as necessary in the Property Grid. See the Field List topic for other shortcut menu items related to parameters.

Using a parameter

A parameter can be used anywhere a field is used, such as being data-bound to a report object like the ReportTitle and ReportFilter parameters discussed earlier. For example, you can create a calculated field that determines the salesperson commission for an invoice with the commission percentage being a parameter. In that case, the parameter would be something like this, using a default commission rate of 5.25%:

The calculated field that calculates the commission amount is something like this:

Note how the parameter is used in the expression. You would then add a label to the report and data-bind it to the Commission calculated field. When the user runs the report, they're prompted for the commission rate and the commission amount appears in the report. Note that the Request Parameters report property and the Visible property of the parameter must both be set to Yes for the user to be prompted.