# ScalarParameter

Defines a simple single-value parameter.

### Description

This element defines a single-value parameter. Scalar parameters can have selection lists.

Scalar parameters can provide a selection list. The list can be static (defined by the `selectionList` property) or dynamic (defined by the `dataSet`, `valueExpr` and `labelExpr` properties.) The user can be required to select a value from the list, or can enter a value not in the list (as controlled by the `mustMatch` property).

BIRT uses the following rules to determine the selection list:

- If the dataSet property is set, then the selection list is dynamic.
- Else, if the selectionList property has one or more entries, use that list.
- Else, assume the parameter has no selection list.

### See Also

## dataType

The data type for the parameter.

### Choices

- string: Arbitrary Unicode text.
- decimal: Any type of number including currency. Fixed decimal, arbitrary precision.
- float: A scientific amount using the usual floating point notation.
- dateTime: A date, time or combination of date and time.
- boolean: A simple true/false value.

### Description

The data type for the parameter. The data type controls how the Requester formats, parses and validates the parameter. Every type can optionally provide a choice list. And, the parameter can require that the user select one of the choices.

### See Also

`selectionList` property

`defaultValue` property

## concealValue

Hides the user’s entry by displaying asterisks or similar characters. Often used for passwords.

### Description

This property hides the user’s entry by displaying asterisks or similar characters. Often used for passwords. The default is to show the entry in plain text.

### See Also

`hidden` Property

## defaultValue

The default value of the parameter.

### Description

The default value for the parameter. The default value can be an expression, but cannot reference any other parameters.

### See Also

## allowNull

Whether the value of the parameter can be null.

### Description

Whether the value of the parameter can be null. The default is false. The user must enter a value for the parameter if no default is provided.

### See Also

## allowBlank

Whether to allow a blank value for string parameters.

### Description

If the parameter is a string field, this attribute says whether to allow a blank string value. The default is true. Ignored for parameters of type other than string.

### See Also

## listLimit

List limitation number.

### Description

Value for the list limitation number. If the limitation is provided, only the top-n choices will be available in the parameter request dialog.

## promptText

The prompt text displayed when user input the parameter value.

### Description

The text that will be displayed to the user when he/she is prompt for the parameter value.

## valueType

Type of the parameter

### Description

Type of the parameter, can be static or dynamic

## format

Formatting pattern for showing the parameter in the UI.

### Description

Formatting instructions for the parameter value within the parameter UI. For UIs that are able to show formatted parameter values, provides a BIRT format used to display the value. The format is dropped, and the unformatted value presented, when the user edits the parameter value.

Formatting instructions for the parameter value within the parameter UI. By default the UI should use the following rules:

- Text ? No formatting.
- Number, Float, Date-Time ? Default locale formatting.

The format string must be one of the valid BIRT format strings (see the Style element for a list.) The format is used by the UI to display the value after the user moves away from a field. For example, to format a number as a dollar amount.

### See Also

## controlType

The suggested type of UI control to use when displaying the parameter.

### Choices

- text-box: The user can type in the value.
- list-box: Requires a list of choices: static or dynamic. Shown as a list box if set of choices are fixed, combo-box if set of choices is open.
- radio-button: Only allowed for a fixed set of choices.
- check-box: Only for Boolean values

### Description

The suggested type of UI control to use when displaying the parameter. The default depends on the parameter properties:

- text-box ? Default for non-Boolean values when no choices are available.
- list-box ? Default for parameters with choices.
- check-box ? Default for Boolean values.

The list-box control is rendered in the UI depending on the value of the `mustMatch` property. If `mustMatch` is true, then the user much choose a value from the list, and the control is rendered as a UI list box. However, if `mustMatch` is false, then the user can chose an item from the list, or type in a different value, and the control is rendered as a UI combo box.

### See Also

`mustMatch` property

## alignment

How the items should appear in the UI. Choices are auto (default), left, center or right.

### Choices

- auto: Numbers are left aligned, all others are right aligned.
- left: Values are left-aligned.
- center: Values are centered.
- right: Values are right-aligned.

### Description

How the items should appear in the UI. Choices are auto (default), left, center or right.

### See Also

## selectionList

Defines a selection list for the parameter: static list of values from which the user can choose.

### Description

The parameter selection list provides a developer-defined list of choices. Every choice has two parts: a choice and a label. The label can be externalized and appears in the UI. The choice is the value passed to the report. For example, labels may be “Open? and “Closed?, while the values are ?0? and ?1?.

The items in the list are of the type given by the parameter data type.

### See Also

`mustMatch` property

`fixedOrder` property

`controlType` property

## mustMatch

If true, then the value that the user provides must match one of the values in the static or dynamic selection list.

### Description

If true, then the value that the user provides must match one of the values in the list. If false, then the values in the list are a reference; the use can enter additional values as well. Ignored if the property does not have a selection list.

### See Also

## fixedOrder

Whether to display the list sorted in unsorted (fixed) order.

### Description

Whether to display the values in the order defined in the list, or whether to resort the list lexicographically based on the actual translated values. The default is true, and the selections are displayed in the order in which they are defined.

### See Also

`selectionList` property

`dynamicList` property

## dataSetName

The name of the data set to execute to obtain a selection list dynamically.

### Description

The name of the data set to execute to obtain the list.

This element defines or references a query that defines a dynamic selection list for the parameter. The data set can reference other parameters, but only those that appear in the design before this parameter. Sorting can be done by the data set (if the fixedOrder property is true), or can be done by BIRT (if the fixedOrder property is false.)

The data set must return a column that contains the choice values. It may also contain a column that returns the labels for the values. All other columns are ignored. The choice is that passed to the report when run. The optional display value is shown to the user in the UI. For example, the display values might be “Residential?, “Commercial?, and “Government? while the corresponding parameter values are “R?, “C?, and “G?.

### See Also

## valueExpr

An expression on the data set row to return the value of each choice in a dynamic list.

### Description

An expression on the data row from the dynamic list data set that returns the value for the choice. If omitted, then BIRT uses the first column.

### See Also

## labelExpr

An expression on the data row to return the display value for each choice in a dynamic list.

### Description

An expression on the data row from the dynamic list data set that returns the prompt for the choice. If omitted, then BIRT uses the value as the label.

### See Also

## boundDataColumns

Bindings the data set column and expressions with the property values..

### Description

Property values of a scalar parameter can bind to a data set column through bound data columns' names. If a data set column or expression are not bound in the data columns, the exeuction of the expression fails.

### See Also