Compute node Use the Compute node to construct one or more new output messages. This topic contains the following sections:
Purpose Using this node in a message flow Configuring the Compute node Defining database interaction Specifying ESQL Setting the mode Validating messages Terminals and properties
Purpose The output messages that you create in the Compute node might be created by modifying the information that is provided in the input message, or by using only new information which can be taken from a database or from other sources. Elements of the input message (for example, headers, header fields, and body data), its associated environment, and its exception list can be used to create the new output message. Specify how the new messages are created by coding ESQL in the message flow ESQL resource file. For more information, see Specifying ESQL. 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
The Compute node is contained in the Transformation drawer of the palette, and is represented in theWebSphere® Message Broker Toolkit by the following icon:
Using this node in a message flow Look at the following samples to see how to use this node:
Airline Reservations Aggregation JMS Nodes Large Messaging Message Routing Scribble Timeout Processing
Video Rental
You can view information about samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit or the online information center. You can run samples only when you use the information center that is integrated with the WebSphere Message Broker Toolkit. 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; seeConfiguring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk. Configure the Compute node by: 1. 2. 3. 4.
Defining database interaction Specifying ESQL Setting the mode Validating messages
Defining database interaction To access a database from this node:
On the Basic tab, specify in Data Source the name by which the appropriate database is known on the system on which this message flow is to run. The broker connects to this database with user ID and password information that you have specified on the mqsicreatebroker, mqsichangebroker, ormqsisetdbparms command. 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 .SBIPPROC. Select the Transaction setting from the list. The values are: o 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 chooseAutomatic, 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. o Commit. 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. To treat database warning messages as errors and have the node propagate the output message to the Failure terminal, select Treat warnings as errors. The check box is cleared initially. 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 typical return codes, and does not raise any exceptions. The most significant warning raised is not found, which can be handled as a typical return code safely in most circumstances. To force the broker to generate an exception when a database error is detected, select Throw exception on database error. The check box is selected initially.
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 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 the node 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 storing the result in a field in the output message. Code the ESQL statements that you want in an ESQL file that is 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.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, double-click the Compute node, or right-click the node and click Open ESQL. This action creates and opens a new ESQL file in the ESQL editor view. If you prefer, you can open the appropriate ESQL file in the Broker Development view and select this node in the Outline view. If the file exists already, click Browse beside the ESQL Module property to display the Module Selection dialog box, 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 does not exist, it 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 COMPUTE MODULE _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;
If you create your own ESQL module, you must create this skeleton exactly as shown except for the procedure calls and definitions (described later in this section). 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 quotation marks in the ESQL Moduleproperty. 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.
Setting the mode The Compute Mode property controls which components are used by default in the output message. Select the property to specify whether the Message, LocalEnvironment (previously specified as DestinationList), andException List components that are either generated in the node or contained in the incoming message are used. This default value is used when the transformed message is routed to the Out terminal when processing in the node is completed. The default value is also used whenever a PROPAGATE statement does not specify the composition of its output message. Those components that are not included in your selection are passed on unchanged; even if you modify those components, the updates are local to this node. Conversely, those components that are included in the selection are not passed on and the updates that are made in the node persist. The seven possible values that the Compute Mode property can take are listed in the following table. Mode
Description
Mode
Description
Message (the default)
The message is generated or passed through by the Computenode as modified in the node.
LocalEnvironment
The LocalEnvironment tree structure is generated or passed through by the Compute node as modified in 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 Computenode 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.
The value of the Compute Mode property specifies which new message trees are propagated from the Computenode. Therefore, for those message trees that are selected, the input messages are discarded unless they are explicitly copied into the new equivalent output message tree. If All is selected, the Compute node is expecting to generate all three new message trees for the Root, LocalEnvironment, and ExceptionList by populating the OutputRoot, OutputLocalEnvironment, and OutputExceptionList. The input message trees are not passed to the output unless they are copied explicitly from the Input to the Output. Therefore, if the Compute Mode property is set to All, you must code the following ESQL to allow the input trees to be propagated to the output terminal: SET OutputRoot = InputRoot; SET OutputLocalEnvironment = InputLocalEnvironment; SET OutputExceptionList = InputExceptionList;
If the ESQL was CopyEntireMessage(), the LocalEnvironment and ExceptionList are not copied across and are not propagated to the output terminal; they are lost at that node in the message flow.
To produce a new or changed output message, and propagate the same LocalEnvironment and ExceptionList, set the Compute Mode property to Message so that the LocalEnvironment and ExceptionList that are passed to the Compute or Mapping node, are passed on from the Compute node. The Compute Mode applies only to propagation from the node. You can create all three output trees in aCompute or Mapping node and these can be manipulated and exist in the node. However, the Compute Modedetermines whether such output trees are used on propagation from the node. On propagation from the node, the following trees are propagated from the Compute or Mapping node for the following settings. Compute Mode
Trees propagated
All
OutputRoot, OutputLocalEnvironment, OutputExceptionList
Message
OutputRoot, InputLocalEnvironment, InputExceptionList
LocalEnvironment
InputRoot, OutputLocalEnvironment, InputExceptionList
LocalEnvironment and Message
OutputRoot, OutputLocalEnvironment, InputExceptionList
Exception
InputRoot, InputLocalEnvironment, OutputExceptionList
Exception and Message
OutputRoot, InputLocalEnvironment, OutputExceptionList
Exception and LocalEnvironment
InputRoot, OutputLocalEnvironment, OutputExceptionList
Where an output tree is named, ESQL creates this message tree before propagation. If your ESQL does not create the tree, no tree is propagated for that correlation name, and the input tree is not used in its place because the Compute Mode property did not indicate this option. Therefore, dependent on Compute Modeproperty settings and your ESQL, you might delete a tree that was input to the node, because you did not transfer it to the output tree, or propagate a changed tree as you intended. The converse is also true. If your ESQL interrogates the input trees and does not need to propagate these trees, the Compute Mode property value might mean that the message tree propagates when you do not intend it to. For example, you might not want to propagate the LocalEnvironment and ExceptionList from aCompute node, but because you selected Message, the
input versions of the trees are propagated. Even if the ESQL explicitly deletes the OutputLocalEnvironment and OutputExceptionList, these changes are local to that node because the Compute Mode property setting causes the input trees to be propagated. The Environment component of the message tree is not affected by the Compute Mode property setting. Its contents, if any, are passed on from this node in the output message. Set this property to reflect the output message format that you require. If you select an option (or accept the default value) that does not include a particular part of the message, that part of the message is not included in any output message that is constructed. The Compute node has both an input and output message, so that you can use ESQL to refer to fields in either message. You can also work with both InputLocalEnvironment and OutputLocalEnvironment, and InputExceptionList and OutputExceptionList, as well as the input and output message bodies.
Validating messages Set the validation properties to define how the message that is produced by the Compute node is to be validated. These properties do not cause the input message to be validated. It is expected that, if such validation is required, the validation has already been performed by the input node or a preceding validation node. For more details, see Validating messages and Validation properties.
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 an unhandled exception occurs during the computation.
Out
The output terminal to which the transformed message is routed when processing in the node is completed. The transformed message might also be routed to this terminal by a PROPAGATE statement.
Out1
The first alternative output terminal to which the transformed message might be routed by a PROPAGATE statement.
Out2
The second alternative output terminal to which the transformed message might be routed by a PROPAGATE statement.
Terminal
Description
Out3
The third alternative output terminal to which the transformed message might be routed by a PROPAGATE statement.
Out4
The fourth alternative output terminal to which the transformed message might be routed by a PROPAGATE statement.
For the syntax of the PROPAGATE statement, see PROPAGATE statement. The following tables describe the node properties. The column headed M indicates whether the property ismandatory (marked with an asterisk 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 for deployment). The Compute node Description properties are described in the following table.
Property
M
C
Default
Node name
No
No
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.
The node type
Description
The name of the node.
The Compute node Basic properties are described in the following table.
Property
M
C
Data Source
No
Yes
Default
Description
mqsiapplybaroverridecommand property dataSource
The ODBC data source name for the database that contains the tables to which you refer in the ESQL file that is associated with this message flow (identified in the ESQL Moduleproperty). You can specify only one data source for the node. 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 theData Source property.
Transaction
Yes
No
Automatic
The transaction mode for the node. Valid options are Automatic andCommit. The property is valid only if you have selected a
Property
M
C
Default
Description
mqsiapplybaroverridecommand property
database table for input.
ESQL Module
Yes
No
Compute
The name of the module in the ESQL file that contains the statements to run 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 For more information about setting the mode options, see Setting the mode. Treat warnings as errors
Yes
No
Cleared
If you select the check box, database SQL warnings are treated as errors.
Throw exception on database error
Yes
No
Selected
If you select this check box, database errors cause the broker to throw an exception.
The Parser Options properties for the Compute node are described in the following table.
Property
M
C
Default
Use XMLNSC Compact Parser for XMLNS Domain
No
No
Cleared
Description
Setting this property causes the outgoing MQRFH2 to specify the XMLNS instead of XMLNSC parser, allowing an external application to remain unchanged. If outgoing messages do not contain MQRFH2 headers this property has no effect.
The Validation properties of the Compute node are described in the following table. For a full description of these properties, see Validation properties.
Property
M
C
Validate
No
Yes
Default
None
Description
This property controls whether validation takes place. Valid values are None,Content and Value,Content, and Inherit.
mqsiapplybaroverridecommand property
validateMaster
Property
M
C
Default
Failure Action
No
No
Exception
Description
mqsiapplybaroverridecommand property
This property controls what happens if a validation failure occurs. You can set this property only if Validate is set to Content or Content and Value. Valid values areUser Trace, Local Error Log, Exception, andException List.
The Monitoring properties of the node are described in the following table.
Property
M
C
Default
Events
No
No
None
Description
Events that you have defined for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change or delete monitoring events for the node; seeConfiguring monitoring event sources using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.
