Using the Module Reference Component

A StreamBase application module can be referenced by another module, as described in Module Introduction. In an EventFlow application, a Module Reference is the component in one module that links to the called module.

This topic describes how to configure the properties of a Module Reference in the calling module.

Notes

  • Module Reference properties apply only in the current, referencing module. Any changes you make do not affect the referenced module, or references to it in other modules.

  • This topic applies only to the EventFlow Module Reference operator. For details about defining Module References in a StreamSQL Application, see APPLY Statement.

Properties: General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Application:

  • If this is a Module Reference that you have created by dragging an EventFlow or StreamSQL file from the Package Explorer, the application's file name appears here.

  • If you extracted a subset of components from an EventFlow, the name of the EventFlow file created by StreamBase appears here.

  • If you inserted an empty Module Reference from the Palette view, this field is blank. Choose the application file you want to reference from the drop-down list.

  • If you have an empty Module Reference and the module you want to use is not listed, it might because the module is not in your project's module search path. Click the Choose button to open a dialog that helps you navigate a large module search path.

    To see what folders are currently in the search path, click the View search path link, which opens the Module Search Path Property Panel of the current project's Properties dialog.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Schemas Tab

The Schemas tab displays the schemas for each input port of the Module Reference. Use the Show schema for drop-down list to select the port whose schema you want to view.

Properties: Input Ports Tab

Use this tab to add and remove input ports and assign schemas.

The ports on the Module Reference are assigned to the outer input and output streams of the referenced application. Therefore, when you connect a component to a Module Reference, the schema of the arc going into the Module Reference is passed into the referenced application. For more information about input and output port associations in Module References, refer to Extracting a Module.

The names and schemas of these streams are initially inherited from the referenced application module. However, Module References can be changed independently from their original applications. Therefore, as you work with a Module Reference you may need to know how module streams correspond to the input and output streams in the referenced application. In some cases, the port associations might need to be changed. For example, if the name of a stream changes in an application module, a Module Reference that is linked to it might fail because a port cannot find its associated stream.

For these reasons, the Properties View allows you to see and manage the mapping of ports to module streams.

The Port associations table shows the current ports and their assignments, and provides the following ways of managing them:

  • If the Module Reference was extracted or inserted from the Package Explorer, the ports and assignments are automatically filled in for you.

  • If you are creating a new Module Reference, the port association is initially blank. Use the control buttons to create input ports and assign schemas to them. To do this manually, use the Add and Remove buttons. Alternatively, use the Assign All button to automatically create an input port for each input stream in the referenced application. The streams are assigned to ports in sorted order.

  • Use the drop-down control in the Module Stream field to define or change the stream assignment of a port.

Properties: Output Ports Tab

Use this tab to add and remove output ports and assign schemas.

The Port associations table shows the current ports and their assignments, and provides the following ways of managing them:

  • If the Module Reference was extracted or inserted from the Package Explorer, the ports and assignments are automatically filled in for you.

  • If you are creating a new Module Reference, the port association is initially blank. Use the control buttons to create input ports and assign schemas to them. To do this manually, use the Add and Remove buttons. Alternatively, use the Assign All button to automatically create an output port for each output stream in the referenced application. The streams are assigned to ports in sorted order.

  • Use the drop-down control in the Module Stream field to define or change the stream assignment of a port.

Properties: Tables Tab

The Tables tab has two controls:

  • Re-export shared tables

  • Associate placeholder tables

Re-Export Shared Tables

You can mark a Query Table with the Shared attribute, which makes the table visible to Query operators in modules one level higher. Using the Re-export shared tables control, you can export the shared state of one or more Query Tables from one module below the current module, to one module above.

Consider three modules, Top, Middle, and Lower, where:

  • Module Top contains a Module Reference to module Middle.

  • Module Middle contains a Module Reference to module Lower.

  • Module Lower contains a Query Table named LowerTable, which has the Shared access level attribute.

By default, Query operators in module Middle can access LowerTable, but not Query operators in module Top.

To give module Top access to the shared table in module Lower, two levels down, follow these steps:

  1. Open the EventFlow application for Middle.

  2. In Middle, select the Module Reference to Lower, and open the Tables tab in its Properties view.

  3. In the Re-export shared tables control, select the check box next to LowerTable.

  4. Open the EventFlow application for Top. Notice that the Module Reference to Middle now has a gray data port at the top of the icon.

  5. In Top, drag a new Query operator from the Palette view and connect it to the Module Reference to Middle.

  6. In the Properties view for the new Query operator, in the Query tab, select LowerTable in the Associated Table drop-down list.

There is no limit on how far up the chain of nested modules you can export a shared table.

Associate Placeholder Tables

A placeholder Query Table is a pointer to an actual Query Table in another module. If your Module Reference contains one or more placeholder tables, and you connect it to one or more Query Tables in the module that contains the Module Reference, use this control to map the connections to the Query Tables. In this case, the Application Table field is loaded automatically when you make each connection. Use the Module Table control to specify the table you want to connect to within the module.

When connecting a Query Table to a Module Reference that contains only one Query Table marked as a placeholder table, the placeholder table association is filled in for you automatically.

Properties: Parameters Tab

Use this tab to bind values to parameters that were defined in (or imported into) the referenced application module (as described in Using Module Parameters).

Click the Show parameter definitions link to display the available parameter names. The list includes the name of each parameter plus any default value assigned in the application module.

Add a row for each parameter whose value you want to assign. You must include a row for any parameter that does not have a default value; you can optionally include any parameter that has a default value if you want to override the default.

Use either the Add button to add and edit rows manually, or use the Fill All Rows button to load the parameters for you from the inner module. Click the down arrow on the right of the Fill All Rows button to select between the following options:

Fill in all module parameters

Loads a row for every parameter defined in (or imported into) the inner module. Use this option if you want to override one or more default values for parameters with defaults.

Fill in parameters without default values (default)

Loads a row for each parameter for which there is no default value defined. Use this option to silently accept the default value for all parameters that have default values. This leaves only the parameters with no defaults to be loaded into the edit grid.

Properties: Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.