This topic contains the following sections:
Use the Filter node to route a message according to message content. You define the route by coding a filter expression in ESQL. You can include elements of the input message or message properties in the filter expression. You can also use data held in an external database to complete the expression. The output terminal to which the message is routed depends on whether the expression evaluates to true, false, or unknown.
Connect the terminals that cover all situations that could result from the filter; if the node propagates the message to a terminal that is not connected, the message is discarded even if it is transactional.
This node accepts ESQL statements in the same way as the Compute and Database nodes. The last statement executed must be a RETURN <expression> statement whose expression evaluates to a Boolean value. This Boolean value determines which terminal the message is routed to. In many cases, the routing algorithm is a simple comparison of message field values. The comparison is described by the expression and the RETURN statement is the only statement. If you code RETURN without an expression (RETURN;) or with a NULL expression, the node propagates the message to the unknown terminal.
If your message flow requires more complex routing options, you can use the RouteToLabel and Label nodes.
The Filter node is represented in the workbench by the following icon:
Look at the following samples for examples of how you can use this node:
Consider a situation in which you have produced an online test with 10 multiple choice questions. Each message coming in has a candidate name and address followed by a series of answers. Each answer is checked, and if it is correct the field SCORE is incremented by 1. When all the answers have been checked, the field SCORE is tested to see if it is greater than 5. If it is, the Filter node propagates the message to the flow which handles successful candidate input; otherwise the message is filtered into the rejection process, and a rejection message is created.
When you have put an instance of the Filter node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.
All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.
Configure the Filter node as follows:
On z/OS systems, the broker uses the broker started task ID, or the user ID and password that were specified on the mqsisetdbparms command JCL, BIPSDBP in the customization data set <hlq>.SBIPPROC.
Code ESQL statements to customize the behavior of the Filter node in an ESQL file that is associated with the message flow in which you have included this instance of the Filter node. The ESQL file, which by default has the name <message_flow_name>.esql, contains ESQL for every node in the message flow that requires it. Each portion of code that is related to a specific node is known as a module.
If an ESQL file does not already exist for this message flow, right-click the Filter node and click Open ESQL. This creates and opens a new ESQL file in the ESQL editor view.
If the file already exists, click the Browse button beside the Filter Expression property. This displays the Module Selection dialog, which lists the available Filter node modules defined in the ESQL files that are accessible by this message flow (ESQL files can be defined in other, dependent, projects). Select the appropriate module and click OK. If no suitable modules are available, the list is empty.
If the module you specify doesn't exist, that module is created for you, and the editor positions the file to display it. If the file and the module already exist, the editor positions the file and displays and highlights the correct module.
If you prefer, you can open the appropriate ESQL file in the Resource Navigator and select this node in the Outline view.
If a module skeleton is created for this node in a new or existing ESQL file, it consists of the following ESQL. The default module name is shown in this example:
CREATE FILTER MODULE <flow_name>_Filter CREATE FUNCTION Main() RETURNS BOOLEAN BEGIN RETURN TRUE; END; END MODULE;
If you create your own ESQL module, you must create exactly this skeleton. You can update the default name, but ensure that the name that you specify matches the name of the corresponding node property Filter Expression.
Add your own ESQL to customize this node after the BEGIN statement, and before the RETURN statement. If the expression on the RETURN statement is not TRUE or FALSE, its value is resolved to determine the terminal to which the message is propagated. If the expression resolves to NULL, or you code RETURN;, or you omit the RETURN statement, the node propagates the message to the unknown terminal.
You can also click
to create an ESQL file.You can use all the ESQL statements including SET, WHILE, DECLARE, and IF in this module, but (unlike the Compute node) the Filter node propagates the message that it receives at its input terminal to its output terminal unchanged. This means that, like the Database node, you have only one message to refer to in a Filter node.
Because you can't modify any part of any message, the assignment statement (the SET statement, not the SET clause of the INSERT statement) can assign values only to temporary variables. The scope of actions that you can take with an assignment statement is therefore limited.
When you select the box, the node handles all positive return codes from the database as errors and generates exceptions in the same way as it does for the negative, or more serious, errors.
If you do not select the box, the node treats warnings as normal return codes, and does not raise any exceptions. The most significant warning raised is not found, which can be handled as a normal return code safely in most circumstances.
If you clear the box, you must include ESQL to check for any database error that might be returned after each database call you make (you can use SQLCODE and SQLSTATE to do this). If an error has occurred, you must handle the error in the message flow to ensure the integrity of the broker and the database: the error is ignored if you do not handle it through your own processing, because you have chosen not to invoke the default error handling by the broker. For example, you can include the ESQL THROW statement to throw an exception in this node, or you can use the Throw node to generate your own exception at a later point.
Click Cancel to close the dialog and discard all the changes that you have made to the properties.
The Filter node terminals are described in the following table.
Terminal | Description |
---|---|
In | The input terminal that accepts a message for processing by the node. |
Failure | The output terminal to which the message is routed if a failure is detected during the computation. |
Unknown | The output terminal to which the message is routed if the specified filter expression evaluates to unknown or null. |
False | The output terminal to which the message is routed if the specified filter expression evaluates to false. |
True | The output terminal to which the message is routed if the specified filter expression evaluates to true. |
The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog if you must enter a value when no default is defined), the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).
The Filter node Basic properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Data Source | No | Yes | The ODBC data source name of the database in which reside the tables to which you refer in the ESQL associated with this node (identified by the Filter Expression property). | |
Transaction | Yes | No | Automatic | The transaction mode for the node. This can be Automatic or Commit. |
Filter Expression | Yes | No | Filter | The name of the module within the ESQL resource (file) that contains the statements to execute against the message that is received in the node. |
Treat warnings as errors | Yes | No | Cleared | Treat database SQL warnings as errors. If you select the check box, this action is performed. |
Throw exception on database error | Yes | No | Selected | Database errors cause the broker to throw an exception. If you select the check box, this action is performed. |
The Filter node Description properties are described in the following table.
Property | M | C | Default | Description |
---|---|---|---|---|
Short Description | No | No | A brief description of the node. | |
Long Description | No | No | Text that describes the purpose of the node in the message flow. |
Notices |
Trademarks |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
ac04780_ |