Using Module Parameters

< Previous		Next >

Module Parameter Overview

Module parameters allow you to reference the same application module using different expression values. Declare module parameters in the context of a single module. The scope of a module parameter is the containing module.

You can reference module parameters as part or all of an expression in any operator or adapter in the containing module, using the syntax ${param-name}. When the expression is evaluated, the value of the parameter is substituted.

Module parameters are evaluated at module load time, when the container holding the module is started by its hosting StreamBase Server. If a container holding a module is stopped and restarted, the module's module parameters are re-evaluated when the container is restarted.

In general, the workflow for declaring and using module parameters is as follows:

Declare a parameter for a module. We will refer to this as module B. See Declaring Module Parameters.
Reference the parameter with the syntax ${param-name} in one or more expressions in an operator or adapter in module B.
In the EventFlow canvas for a different module, A, use a Module Reference operator to call module B. See Properties: Parameters Tab.
Set the value for the parameter to use when calling B from A using the Module Reference operator's Parameters tab (or using one of the other methods described in Setting Values for Module Parameters).

Module parameters are not the same as global parameters. See Parameter Overview and Using Global Parameters to understand the differences.

Declaring Module Parameters

In EventFlow programs, declare module parameters in the Parameters tab at the bottom of the EventFlow Editor:

Add a row for each parameter you want to declare.
Optionally specify a default value. If you do not specify a default value, the module receives a typechecking error. Depending on how the application uses the parameter, it may be necessary to specify a default value to get the application to typecheck without errors.

In the absence of a default value, you must specify a value for the parameter when you call the containing module, as described in the next section.

In StreamSQL programs, declare module parameters with the CREATE PARAMETERS statement.

Setting Values for Module Parameters

You can set a default, initial value when you declare a parameter in the Parameters tab of the EventFlow Editor.

You can set a new value for a module parameter in several ways:

In the Parameters tab of the Properties view for Module References.

This is the primary method for setting module parameter values when calling modules. You can use an expression to set the value. To set a value that depends on an environment variable, use the systemenv() function.

For details about using the Parameters tab, see Properties: Parameters Tab. In particular, you may find it useful to use the Show parameter definitions link to see what parameters are defined, and the Fill All Rows button to create rows for the parameters.
In the <module-parameters> child element of the <application> element in the server configuration file.

Use this method to define values for module parameters for a module in a container. The values you specify are set when the server is started and the configuration file is loaded. The values are passed to the module when the container holding the module is started. Values specified in a <module-parameters> element can be enciphered to preserve the privacy of the information. See Enciphering Passwords and Parameter Values for details.
In the Main tab of the Run/Debug Configuration dialog when editing a Studio launch configuration, for setting parameter values for the top-level module.
In the Containers tab of the Run/Debug Configuration dialog when editing a Studio launch configuration, for setting parameter values for modules in containers.

You can use this method in Studio when starting application modules in containers.
With the sbadmin addContainer --parameter command.
With the sbargen --parameter command.
When writing your own administrative client utility with the StreamBaseAdminClient class, using the --parameter option of the addContainer() method.

Only when using the <module-parameters> method, you can encipher the values of module parameters so that the values cannot be read in the configuration file. See Enciphering Passwords and Parameter Values for details.

Passing Values to Inner Modules

A complex application might have several layers of modules. For example, a top-level module, A, might call module B, which calls module C, which calls module D. Your application design might require the same variable to be used in expressions in modules B, C, and D.

In the previous section's list of methods to set module parameter values, methods 2 through 6 all set the value for the top-level module in a container as the container starts. Method 1 sets the parameter value from a calling module to the called module, such as when module A calls module B. The parameter value is not automatically passed down to modules C and D.

In these cases, you can use chaining to pass the same value down the chain of module references. Follow these steps:

Declare the same module parameter name in all modules of interest. For example, we might declare parameter param-name in modules B, C, and D.
In module A, use the Parameters tab of the Properties view of the Module Reference component that calls module B. Set a value for param-name, such as param-name=100.0.
In module B, in the Module Reference component that calls module C, use the Parameters tab to set the value of C's parameter to the same as B's: param-name=${param-name}.
In module C, in the Module Reference component that calls module D, use the same setting: param-name=${param-name}.

You can also use parameter chaining when setting module parameter values from outside the top-level module when its container starts. In this case, use the following variation:

Declare the same module parameter name in all modules, including the top-level module. For our example, declare param-name in modules A, B, C, and D.
Set the value of param-name for A, the top-level module, when you start the container holding all four modules. Use one of methods 2 through 6 in Setting Values for Module Parameters.
Use the param-name=${param-name} syntax in the Module References for modules A, B, and C when calling modules B, C, and D, respectively.

Order of Precedence in Resolving Values

If a module parameter has the same name as a global parameter, the module parameter takes precedence. In general, the values of parameters are resolved with the following order of precedence:

Module parameters with values set in Module Reference operators.
Module parameters with values set with the <module-parameters> element in the configuration file.
Module parameter default values.
Global parameters with values set with the <operator-parameters> element in the configuration file.

EventFlow Example

To demonstrate parameter modules, we will start with a simple application, GatherAlarms, that receives stock data on the input stream, and outputs an alarm when a tuple arrives with a stock trade that exceeds a specified volume or price. The EventFlow canvas looks like this:

The volume and price thresholds are defined as follows in our sample application:

The VolAlarm Map operator's Output Settings tab has a field with the expression, Volume >= 10000.
The PriceAlarm Map operator's Output Settings tab has a field with the expression, Price >= 200.0.

To make this application more flexible as a reusable module, we want to be able to vary the price and volume thresholds that trigger the alarm. To demonstrate, we will design the application to output two alarms: one when trades exceed 12000 shares or a price of 225, and the other when trades exceed 15000 shares or a price of 200.

Define module parameters in the application module.

In the following figure, we have selected the Parameters tab and defined two parameters in the GatherAlarms application:

Notice that we have set a default value for only one of the parameters. We will see later how this affects our use of the parameters.
Use the module parameters in the application module.

Let us change the volume and price expressions shown previously, as follows:
- VolAlarm expression: Volume >= ${MinVolume}.
- PriceAlarm expression: Price >= ${MinPrice}.
Note

Because we did not define a default value for MinVolume, the PriceAlarm operator will have a typecheck error at this point. That error will disappear once we provide a value for MinVolume in the UseAlarms application, defined below.
Reference the module in another application.

The following figure shows an application named UseAlarms, which simply references the GatherAlarms module twice:
Bind the parameters to values in the module reference.

Our example has two module references, and we will set the parameters differently in each one:
- In GatherAlarmsRef1, we set values for both the MinVolume and MinPrice parameters, as shown in the following figure:
- In GatherAlarmsRef2, we add only a row for the MinVolume parameter, setting its value to 15000. This means that we accept the default value of 200 for the MinPrice parameter that we set earlier in the application module. We must always set a value for MinVolume because no default value was set.

StreamSQL Example

Define a module parameter using the CREATE PARAMETERS statement, optionally including a default value. For example:
```
CREATE PARAMETERS (table_name DEFAULT "TABLE1");
```
Reference the parameter in an expression in the application module, using the following syntax:
```
${table_name}
```
Reference the module using an APPLY MODULE statement. Within the statement, you must specify any undefined parameter values. You do not need to bind a parameter that has a default value, except when you want to override the default value. For example:
```
APPLY MODULE "GatherAlarms.sbapp"
  (MinVolume=4000000, MinPrice=500)
FROM Input1 = Input1
INTO Output1 = Output1;
```