Compute node

This topic contains the following sections:

Purpose

Use the Compute node to construct one or more new output messages by creating messages and populating them with new information, with modified information from the input message, or with information taken from a database. You can modify elements (headers, header fields, and body data) of the input message, its associated environment, and its exception list to create the new output message.

You specify how the new messages are created by coding ESQL in the message flow ESQL resource file. You can both create and modify the components of the message using ESQL expressions, and can refer to elements of both the input message and data from an external database. An expression can use arithmetic operators, text operators (for example, concatenation), logical operators, and other built-in functions.

Use the Compute node to:

  • Build a new message using a set of assignment statements
  • Copy messages between parsers
  • Convert messages from one code set to another
  • Transform messages from one format to another

You define the ESQL statements in a module associated with this node in the ESQL .esql) file associated with this message flow. You must create this file to complete the definition of the message flow.

The Compute node is represented in the workbench by the following icon:

Compute node icon

Using this node in a message flow

Look at the following samples to see how you can use this node:

Consider a message flow in which you want to give each order that you receive a unique identifier for audit purposes. The Compute node does not modify its input message; it creates a new, modified copy of the message as an output message. You can use the Compute node to insert a unique identifier for your order into the output message, which can be used by subsequent nodes in the message flow.

Configuring the Compute node

When you have put an instance of the Compute 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 Compute node by:

  1. Defining database interaction
  2. Specifying ESQL
  3. Setting the mode
  4. Validating messages

When you have completed your configuration, click Apply. This makes the changes to the Compute node without closing the properties dialog. Click OK to apply the changes and close the properties dialog. Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Defining database interaction

If you want to use data from a database in this node (by referring to database tables in the associated ESQL module):

  • Specify in Data Source the name by which the appropriate database is known on the system on which this message flow is to execute. The broker connects to this database with user ID and password information that you have specified on the mqsicreatebroker, mqsichangebroker, or mqsisetdbparms command.

    On z/OS systems, the broker uses the broker started task ID.

  • Select the Transaction setting from the drop-down menu. The values are:
    • Automatic (the default). The message flow, of which the Compute node is a part, is committed if it is successful. That is, the actions that you define in the ESQL module are performed on the message and it continues through the message flow. If the message flow fails, it is rolled back. If you choose Automatic, the ability to commit or roll back the action of the Compute node on the database depends on the success or failure of the entire message flow.
    • Commit. If you want to commit the action of the Compute node on the database, irrespective of the success or failure of the message flow as a whole, select Commit. The database update is committed even if the message flow itself fails.

    The value that you choose is implemented for the one or more database tables that you have added: you cannot select a different value for each table.

  • Select Basic in the properties dialog navigator and select or clear the two check boxes:
    • If you want database warning messages to be treated as errors and want the node to propagate the output message to the failure terminal, select the Treat warnings as errors check box. The box is initially cleared.

      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 want the broker to generate an exception when a database error is detected, select the Throw exception on database error check box. The box is initially selected.

      If you clear the 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 occurs, 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 in the message flow.

Specifying ESQL

Code ESQL statements to customize the behavior of the Compute node. For example, you can customize it to create a new output message or messages, using input message or database content (unchanged or modified), or new data. For example, you might want to modify a value in the input message by adding a value from a database, and store the result in a field in the output message.

Code the ESQL statements that you want in an ESQL file associated with the message flow in which you have included this instance of the Compute 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 Compute 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 ESQL Module property. This displays the Module Selection dialog, which lists the available Compute 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 that you have specified doesn't exist, it 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 COMPUTE MODULE <flow_name>_Compute
       CREATE FUNCTION Main() RETURNS BOOLEAN
       BEGIN
              -- CALL CopyMessageHeaders();
              -- CALL CopyEntireMessage();
              RETURN TRUE;
       END;

       CREATE PROCEDURE CopyMessageHeaders() BEGIN
              DECLARE I INTEGER 1;
              DECLARE J INTEGER CARDINALITY(InputRoot.*[]);
              WHILE I < J DO
                     SET OutputRoot.*[I] = InputRoot.*[I];
                     SET I = I + 1;
              END WHILE;
       END;

       CREATE PROCEDURE CopyEntireMessage() BEGIN
              SET OutputRoot = InputRoot;
       END;
END MODULE;

Note: Start of changeIf you want to deploy the message flow that contains this Compute node to a broker whose version is earlier than version 5.0, you must make the following changes to the ESQL in the module skeleton shown above:
  • Replace
    DECLARE I INTEGER 1;
    by
    DECLARE I INTEGER; SET I=1;
  • Replace
    DECLARE J INTEGER CARDINALITY(InputRoot.*[]);
    by
    DECLARE J INTEGER; SET J=CARDINALITY(InputRoot.*[]);
End of change

If you create your own ESQL module, you must create this skeleton exactly as shown except for the procedure calls and definitions (described below). You can change the default name, but ensure that the name you specify matches the name of the corresponding node property ESQL Module. If you want the module name to include one or more spaces, enclose the name in double quotes in the ESQL Module property.

Add your own ESQL to customize this node after the BEGIN statement that follows CREATE FUNCTION, and before RETURN TRUE. You can use the two calls included in the skeleton, to procedures CopyEntireMessage and CopyMessageHeaders.

These procedures, defined following function Main, provide common functions that you might want when you manipulate messages. The calls in the skeleton are commented out; remove the comment markers if you want to use the procedure. If you do not want to use a procedure, remove both the call and the procedure definition from the module.

In previous releases, the functions performed by these procedures were provided by the two equivalent Compute node radio buttons on the properties dialog.

You can also create an ESQL file using the File > New > Message Flow ESQL File.

Setting the mode

When you select the Compute mode, you specify which combination of Message, LocalEnvironment (previously specified as DestinationList), and Exception components are generated and modified in the output message. Those components not included in your selection are passed on unchanged: even if you modify those components, the updates are local to this node.

(The Environment component of the message tree is not affected by the mode setting. Its contents, if any, are passed on from this node in the output message.)

You must set this property to correctly reflect the output message format that you require. If you select an option (or accept the default value) that does not include a particular content of the message, that part of the message is not included in any output message that is constructed.

The options are explained in the following table.

Mode Description
Message (the default) The message is generated or passed through by the Compute node as modified within the node.
LocalEnvironment The LocalEnvironment tree structure is generated or passed through by the Compute node as modified within the node.
LocalEnvironment And Message The LocalEnvironment tree structure and message are generated or passed through by the Compute node as modified by the node.
Exception The Exception List is generated or passed through by the Compute node as modified by the node.
Exception And Message The Exception List and message are generated or passed through by the Compute node as modified by the node.
Exception and LocalEnvironment The Exception List and LocalEnvironment tree structure are generated or passed through by the Compute node as modified by the node.
All The message, Exception List, and LocalEnvironment are generated or passed through by the Compute node as modified by the node.

Because the Compute node has both an input and output message, you can use ESQL to refer to fields in either. You can also work with both InputLocalEnvironment and OutputLocalEnvironment, and InputExceptionList and OutputExceptionList, as well as the input and output message bodies.

Validating messages

Select Validation in the properties dialog navigator if you want the MRM parser to validate the body of messages against the dictionary generated from the message set. The validation options you set on a Compute node apply only to any output messages that are created. Validation does not take place within the node itself, but only when the message is subsequently converted to a bit stream.

  • The Validate property is initially set to None. Change this to Content and Value to request both content validation (type content and composition checks) and value validation (value data type checks, null permitted checks, length checks, range checks, enumeration checks, and so on). The Compute node adds the options specified to the output message tree for when it is subsequently validated.
  • To specify what happens when a validation failure occurs, select one of the following options for Failure Action:
    • User Trace: write all validation failures to user trace and continue processing .
    • Local Error Log: write all validation failures to the event log and continue processing.
    • Exception: throw an exception on the first validation failure. This is the default behavior.

    The first two options are particularly useful when validation is first invoked because you see all validation failures, not just the first error that is encountered. When you have analyzed the failures, you might typically select Exception for future use.

    The failure destinations behave like those for Trace node output. So, for example, if you select User Trace, trace entries are written regardless of the setting of the user trace flag for the message flow.

  • Include All Value Constraints is selected by default and cannot be changed. This setting means that full data type checks and value checks are made (see Simple type logical value constraints for further information about constraints).
  • Fix cannot be changed from its default setting of None. If Failure Action is not set to Exception, limited remedial action is taken when validation failures occur. If Failure Action is set to Exception, no remedial action is taken, and an exception is thrown at the first validation failure.

Terminals and properties

The Compute 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 input message is routed if a failure is detected during the computation. (Even if the Validate property is set, messages propagated to the failure terminal of the node are not validated.)
Out The output terminal to which the transformed message is routed.

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 Compute node Basic properties are described in the following table.

Property M C Default Description
Data Source No Yes   The ODBC data source name for the database within which reside any tables to which you refer in the ESQL file associated with this message flow (identified in the ESQL Module property). You can specify only one data source for the node.
Transaction Yes No Automatic The transaction mode for the node. This can be Automatic or Commit. It is valid only if you have selected a database table for input.
ESQL Module Yes No Compute The name of the module within the ESQL file that contains the statements to execute against the database and input and output messages.
Compute Mode Yes No Message Choose from:
  • Message
  • LocalEnvironment
  • LocalEnvironment And Message
  • Exception
  • Exception And Message
  • Exception And LocalEnvironment
  • All
These are explained in Setting the mode.
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 Compute node Validation properties are described in the following table.

Property M C Default Description
Validate Yes No None Whether validation takes place. Valid values are None and Content and Value.
Failure Action Yes No Exception What happens if a validation failure occurs. You can set this property only if Validate is set to Content and Value. Valid values are User Trace, Local Error Log, and Exception.
Include All Value Constraints Yes No Selected This property cannot be edited. The default action, indicated by the check box being selected, is that all value constraints are included in the validation.
Fix Yes No None This property cannot be edited. Minimal fixing is provided.

The Compute 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.

Related concepts
Message flows
Message flows, mappings, and ESQL
Correlation names

Related tasks
Setting up DB2
Deciding which nodes to use
Validating messages
Creating destination lists
Handling errors in message flows
Configuring coordinated message flows
Creating ESQL for a node
Configuring ESQL within nodes
Editing configurable properties

Related reference
ESQL
Simple type logical value constraints
mqsichangebroker command
mqsicreatebroker command
mqsisetdbparms command