Using Module Parameters

You can define a module parameter in a StreamBase application, and use the parameter as part or all of an expression within an operator in the application. When you then reference the application in a module reference, you can bind the parameter to a value, which is substituted when the expression is evaluated. In this way, you can reference the same application module using different expression values.

Note

Module parameters are distinct from both expression parameters (described in StreamBase Expression Language and Functions), and StreamSQL CREATE PARAMETERS Statement statements:

  • A module parameter is defined only for a given parameterized module, not at the server level as expression parameters are.

  • Module parameters can only be used within expressions. StreamSQL CREATE PARAMETER statements are more flexible: they can be used to represent expressions as well as other parts of the application.

  • If you use an expression parameter and a module parameter with the same name, the module parameter value takes precedence.

The value for a module parameter is resolved in the following order of precedence:

  1. A value set in the calling Module Reference operator.

  2. If no value is passed to a module by the referring module, and a default value is set, the default value is used.

  3. If no default value is set, StreamBase uses any value set for the an operator of the same name in the operator-parameters section of the server configuration file. See operator-parameters in the Reference Guide.

Using Parameters in EventFlow Applications

This section describes how to use module parameters in StreamBase Studio. Compare each step with the example and its illustrations at the end of the topic.

  1. Define module parameters in the application module:

    1. Open the application module that will be referenced. Click the Parameters tab at the bottom of the EventFlow Editor.

    2. In the Parameters tab add a row for each parameter you want to define.

      Optionally, define a default value. Depending on how the application uses the parameter, defining a default value for the parameter may be necessary to get the application to typecheck without errors.

    3. Save the application module.

  2. Reference the parameters in the application module:

    Open the Editor tab of the EventFlow Editor, and use parameters as all or part of any operator expression. For example, in a Map operator that has an expression that uses a hard-coded string value, you might substitute a parameter reference in place of the string value. To refer to a parameter, use the syntax ${param}.

  3. Reference the module in another application:

    Open or create the second application, and create a module reference using the application module whose parameters you defined in the preceding step. For detailed steps see Referencing an Application Module.

  4. Bind the parameters to values in the module reference:

    Select the module reference component to open its Properties view. In the Parameters tab, each parameter defined in the referenced module is listed. Assign a value to each parameter using one of the following methods:

    • Assign a default value when you define the parameter.

    • Pass in a value from a module reference.

      • If you left the default value blank in the parameter definition, you must provide a value.

      • If you provided a default value in the parameter definition, you may provide a value in the module reference if you want to override the default.

    For details about using the Parameters tab, see Defining Module Reference Properties. 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.

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 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. Let's follow the procedure steps earlier in this topic.

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

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

  3. Reference the module in another application.

    The following figure shows an application named UseAlarms, which simply references the GatherAlarms module twice:

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

Using Module Parameters in StreamSQL Applications

  1. Define a module parameter using the CREATE PARAMETERS statement. Optionally include a default value. Example: 

    CREATE PARAMETERS (table_name DEFAULT "TABLE1", other_parameter);

  2. Reference the parameter in the application module. For example: 

    ${table_name}

  3. 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;

Related Topics

Details about module references are covered in these topics:

Back to Top ^