Library Articles
Understanding Parameterized Modules
Authors: Richard Tibbetts, Eddie Galvez, Kimberley Burchett, Dr. John Lifter
StreamBase Systems
26-February-2007
Applicable To: StreamBase 3.7, 5.0
Topics:
In earlier releases of StreamBase, your applications would use a stream to pass data between modules. Beginning with StreamBase 3.7, you now have the additional option of using named parameters. Each StreamSQL EventFlow module (.sbapp file) or StreamSQL module (.ssql file) may include parameters whose default value may be reset from a value passed from another module. By using parameters, you can increase the reusability of your modules.
When you create an EventFlow module using StreamBase Studio, you drag icons from the Palette view onto the Editor tab of the application canvas. Parameters, which are available to all operators within the module, are configured on the Parameters tab of the application canvas as illustrated in the following screen shot.
To declare a parameter for an EventFlow module, click the 
Toolbar Button toolbar button to enter an empty row into the listing. Then enter a name and default value for the parameter. The default value for parameters of type string must be enclosed within quotation marks. If needed, use the other toolbar buttons to remove or rearrange the order of the parameters.
Once a parameter has been defined, you can use its name in an expression. The Map operator in the following simple diagram
uses the parameter in an expression that sets the value of a field, greeting, in its emitted tuple.
Note how the parameter value is referenced by enclosing its name within the dollar sign and curly brace characters — ${...}.
When you subsequently reuse a parameterized module in another application, the Module Reference provides a mechanism to override the parameter's default value.
The application pictured in the preceding diagram reuses the module shown earlier. If you select Module Reference icon (modulesRef1),its Properties view, Parameters tab can be used to enter values that will override the default parameter settings in the referenced module.
You can either use the Toolbar Button toolbar button to add an empty row to the listing, or list all of the parameters by clicking on the 
button. Selecting the Show parameter definitions link will display a popup that lists all of the parameters available in the referenced module.
For each parameter whose value you want to override, add an entry to the listing and provide the new parameter value.
In this example, the default value, "Hello ",for the parameter preface has been replaced with "Howdy ". When the application using the referenced module runs, the greeting field in the emitted tuple will contain "Howdy name" instead of "Hello name".
Within a StreamSQL document, you use the CREATE PARAMETERS statement to declare parameters and their default values. Once a parameter has been declared, you reference it at other places in your code by enclosing its name within the dollar sign and curly brace characters — ${...}.
In StreamSQL, a module parameter is considered to be a named character string that can be referenced at other places in the StreamSQL document through its assigned name. Consequently, the default, or initial, value assigned to the parameter should be enclosed within quotation marks as illustrated in the following example.
CREATE PARAMETERS (parameter_name DEFAULT "value");
If the parameter is a string type, then value must also be enclosed within escaped quotation marks.
CREATE PARAMETERS (parameter_name DEFAULT "\"value\"");
By following these conventions, parameters of all types may be referenced using a common syntax — ${parameter_name}.
A parameter in StreamSQL may represent a value, a constant, a literal, or a character string that can be used in a StreamSQL expression or predicate or as a StreamSQL statement. For example, the parameter declaration:
CREATE PARAMETERS (max_value DEFAULT "10000");
May be used in an expression
SELECT (if tuple_field < ${max_value})
then tuple_field
else ${max_value} AS alias_name ...
Or in a predicate
SELECT ...
WHERE tuple_field < ${max_value} ...
And a string parameter type could be used as follows.
CREATE PARAMETERS (preface DEFAULT "\"Hello \"");
CREATE INPUT STREAM in (name string(10));
SELECT ${preface} + name AS greeting
FROM in => CREATE OUTPUT STREAM out;
This example would emit a tuple with a string field named greeting that contains the content Hello name.
Additionally, a parameter may contain another StreamSQL statement, which can then be used within the StreamSQL document. For example, consider the following module named module1.ssql:
CREATE PARAMETERS (in_stream DEFAULT "CREATE INPUT STREAM ",
in_stream_name DEFAULT "in",
out_stream_name DEFAULT "out");
${in_stream} ${in_stream_name} (name string(10), age int);
SELECT * FROM ${in_stream_name} => CREATE OUTPUT STREAM ${out_stream_name};
Note that CREATE INPUT STREAM, in, and out are treated as character strings (enclosed in quotation marks), not as string literals (enclosed in escaped quotation marks).
When a module that uses parameters is referenced from another module, the referencing module can override the default (initial) parameter values by simply including a parenthesized list of parameter_name=value entries within theAPPLY clause. As in the CREATE PARAMETER statement, value must be enclosed within quotation marks ("value") and strings must also be enclosed within escaped quotation marks ("\"value\""). In the following example, the APPLY statement is used to reference the module1.ssql StreamSQL module. Note that only one of the parameters (in_stream_name) was overridden from the referencing module.
CREATE INPUT STREAM i (name string(10), age int);
CREATE OUTPUT STREAM o;
APPLY MODULE "module1.ssql" (in_stream_name = "myInStream")
FROM i INTO o;
Back to Top ^