Parameter
A parameter is a user-defined value that can be substituted into task commands and other statements. Parameters extend the fixed set of system Placeholders with values specific to the installation or to the individual run.
A parameter is referenced with the u: prefix:
%u:parameter_name%
Contents
Attributes
| Attribute | Description |
|---|---|
| Name | Maximum 100 characters. May contain letters, digits, space and the characters _, - and /. Must be unique.
|
| Description | Free text. |
| Default value | The value used when no query is defined, or when the query cannot supply one. Maximum 2000 characters. |
| Connection | The connection used to evaluate the query. Leave as None for a parameter that only has a default value. |
| Query | An SQL statement returning the value. Only shown once a connection is selected. |
Static and query-based parameters
A parameter can work in two ways:
- Static — no connection and no query. The parameter always resolves to its default value. Use this for values that vary between environments but not between runs, such as a target schema name or a file path.
- Query-based — a connection and a query are defined. The value is obtained by running the query.
The query may itself contain placeholders; the scenario-level placeholders are available, so a parameter can be derived from the state of previous processings.
When parameters are evaluated
This is the most important thing to know about parameters.
Query-based parameters are evaluated once, when the processing is planned — not each time a task runs. Two consequences follow:
- The value is fixed for the whole processing. Every task in the run sees the same value, even if the underlying data changes while the run is in progress. This is usually what you want: it keeps a long run internally consistent.
- A parameter cannot be used to communicate between tasks within a run. Setting a value in one task will not change what a later task sees. Where tasks need to pass values, they must do so through the target system.
Only the parameters actually used by the tasks in the scenario are evaluated. A parameter that no task in the scenario references is not evaluated, so a failing query on an unused parameter will not affect planning.
The values resolved for a run can be seen through Show processing details in the Monitor console. This is the reliable way to confirm what a parameter evaluated to.
Default values in planning queries
Where a user-defined parameter is used in a scenario planning query, only its default value is available. The planning query runs before the processing exists, so there is nothing yet for a query-based value to be attached to.
Practical notes
- Give parameters names that make their scope obvious. They are global, not scoped to a scenario, so a name like schema will not stay unambiguous for long.
- Keep a default value on query-based parameters where a sensible fallback exists. A parameter that resolves to nothing produces a statement with an empty substitution rather than an obvious error.
- Substitution is textual and unquoted — see Placeholders#Quoting. Quote string values in the statement, and prefer passing parameters as procedure arguments over concatenating them into SQL.
