Filter node

On z/OS® systems, the integration node uses the integration node started task ID, or the user ID and password that are specified on the mqsisetdbparms command JCL, BIPSDBP, in the customization data set <hlq>.SBIPPROC.

If the ESQL that is associated with this node includes a PASSTHRU statement or SELECT function and a database reference, you must specify a value for the Data Source property.

• Automatic (the default). The message flow, of which the Filter node is a part, is committed if it is successful. That is, the actions that you define in the ESQL module are performed and the message continues through the message flow. If the message flow fails, it is rolled back. Therefore, if you choose Automatic, the ability to commit or roll back the action of the Filter node on the database depends on the success or failure of the entire message flow.
• Commit. To commit any uncommitted actions that are performed in this message flow on the database that is connected to this node, irrespective of the success or failure of the message flow as a whole, select Commit. The changes to the database are committed even if the message flow itself fails.

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.

If an ESQL file does not already exist for this message flow, double-click the Filter node, or right-click the node and click Open ESQL to create and open a new ESQL file in the ESQL editor view.

If the file exists already, click Browse beside the Filter Expression property to display the Module Selection dialog box, which lists the available Filter node modules defined in the ESQL files that can be accessed 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 that you specify does not exist, that module is created for you, and the editor displays it. If the file and the module exist already, the editor highlights the correct module.

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 this skeleton exactly. You can update the default name, but ensure that the name that you specify matches the name of the corresponding node property Filter Expression.

To customize this node, add your own ESQL 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 a null value, or you code RETURN;, or you omit the RETURN statement, the node propagates the message to the Unknown terminal.

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. Therefore, in the Filter node, like the Database node, you have only one message to which to refer.

The ESQL correlation names that you use in a Filter node are different from those used for a Compute node. For more information about correlation names refer to the related links.

You cannot modify any part of any message, so 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 check 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 check 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 safely as a normal return code in most circumstances.

If you clear the check box, you must include ESQL to check for any database error that might be returned after each database call that 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 integration node 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 integration node. 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.