Combining a result message with an incoming message

The following nodes can fetch data in the middle of a message flow and merge the result with the input message:

• Use the CICSRequest node to call CICS® Transaction Server for z/OS® programs over TCP/IP-based IP InterCommunications protocol (IPIC).
• Use the CORBARequest node to call an external CORBA application over Internet Inter-Orb Protocol (IIOP).
• Use the FileRead node to read one record, or the entire contents of a file, from within a message flow.
• Use the IMSRequest node to send a request to run a transaction on a local or remote IMS™ system, and wait for a response.
• Use the JMSReceive node to consume or browse JMS messages from a JMS queue in the middle of a message flow.
• Use the TCPIPClientReceive node to receive data over a client TCP/IP connection.
• Use the TCPIPServerReceive node to receive data over a server TCP/IP connection.

When you use one of these nodes in the middle of a message flow, you can fetch data from external resources. The result data is merged with the input message according to the values of the Output data location and, if it exists on the node, the Result data location properties.

The input root is first copied to the output root, and the result data is then copied to the location on the output tree specified by Output data location. The default value is $OutputRoot, which replaces the copied message tree with the result data, and propagates none of the input message.

The default value for Result data location, if it exists on the node, is $ResultRoot, which copies the entire result message to the output data location. If you specify a value underneath $ResultRoot, the specified subtree of the result message is inserted into the output tree.

The following examples use the JMSReceive node and show the effect of possible different values specified for Output data location and Result data location.

Example 1: Replacing the whole message tree

• Output data location = $OutputRoot
• Result data location = $ResultRoot

These values are the default values, and cause the input message to be overwritten with the result message.

The input message tree is shown. The root element is selected to be overwritten:

The result message tree is shown. The root element is selected for insertion:

The output message tree is shown. The output root has been replaced by the result root tree:

Example 2: Replacing the message headers

• Output data location = $OutputRoot/JMSTransport
• Result data location = $ResultRoot/JMSTransport

The input root is copied to the output root, and then the headers are overwritten by the headers of the result message.

In the input message tree, the JMSTransport subtree is selected to be overwritten:

In the result message tree, the JMSTransport subtree is selected for insertion:

In the output message tree, the output JMSTransport subtree is replaced by the result JMSTransport subtree:

Example 3: Replacing the message body

• Output data location = $OutputRoot/XMLNSC
• Result data location = $ResultRoot/XMLNSC

The input root is copied to the output root, and then the message body is overwritten by the body of the result message.

In the input message tree, the XMLNSC element is selected to be overwritten:

In the result message tree, the XMLNSC element is selected for insertion:

In the output message tree, the XMLNSC element has been replaced by the result XMLNSC element:

Example 4: Inserting a subtree of the result message

• Output data location = $OutputRoot/XMLNSC/request/Operation
• Result data location = $ResultRoot/XMLNSC/request/Operation

The input root is copied to the output root, and then the Operation subtree of the result message is inserted into the output tree underneath the request element. The input message tree does not contain an Operation element, but its location is determined by the Output data location value.

In the input message tree, the location is selected to be written to. This location does not yet exist:

In the result message tree, the Operation element is selected for insertion:

In the output message tree, the Operation element from the result message tree is inserted under the existing request element: