About the CICS Transaction Server for z/OS Channel Connectivity sample

The CICS program WMBCHAN1 expects a channel with a number of containers:

Program WMBCHAN1 also returns two other containers: mirrorTran, which contains the mirror transaction under which WMBCHAN1 is running, and ChannelName, which contains the name of the channel (which is the name of the input message collection).

The XML input to the message flow is shown in the following example:

<Data>
  <Explanation1>These numbers are added together by CICS. Each number is a separate input container</Explanation1>
  <Numbers>
    <number>10</number>
    <number>20</number>
    <number>30</number>
    <number>40</number>
    <number>50</number>
  </Numbers>
  <Explanation2>CICS examines each string and returns the longest
string in a response container</Explanation2>
  <Strings>
    <string>short data</string>
    <string>some other data, but not long enough</string>
    <string>A really long sentence that CICS can pick out and
return in a container.</string>
    <string>data</string>
    <string>some more strings</string>
  </Strings>
</Data>

The input channel must look like the following example:

Container name Contents
number1 10
number2 20
number3 30
number4 40
number5 50
string1 short data
string2 some other data, but not long enough
string3 a really long sentence that CICS can pick out and return in a container
string4 data
string5 some more strings

Input messages

This sample is designed to work in two different modes. The first mode is message collection mode. In this mode, the sample demonstrates how to construct a message collection and use it to represent multiple input containers.

The second mode is single message mode. The CICSRequest node can create a single container from a single (non-message collection) message. In single message mode, the sample demonstrates how to send a message as a container to CICS without the overhead of a message collection.

Message collection mode

The message collection is constructed in ESQL by using a Compute node. The Compute node completes the following tasks:

Single message mode

In single message mode, a single XML message is sent into the flow. A Compute node sets metadata in the local environment which names the container and the channel that will be used. The XML data is turned into a bit stream and sent as the body of the named container.

To complete these actions, the Compute node has the following statements:

Send the message with a channel name of SINGLEMSG:
SET OutputLocalEnvironment.Destination.CICS.RequestChannel.ChannelName='SINGLEMSG';

Send the message body in a container called string1.
SET OutputLocalEnvironment.Destination.CICS.RequestChannel.SingleMessageContainerName='string1';

Send string1 as a character container.
SET OutputLocalEnvironment.Destination.CICS.RequestChannel.Containers.string1='CHARACTER';

Processing the response

Regardless of the type of input sent to the CICSRequest node, when using channel support, the output is always a message collection.

The response message contains four containers of interest:

On the CICSRequest Response Message Parsing properties tab, an entry in the table maps the sum container to an MRM domain, along with the same message set (CICSIntegerMSet) that was used for the input number containers. Therefore, if the sum container is returned, it is mapped to this parsing information.

The check box on the Response Message Parsing tab is set so that any containers returned from CICS that are not named in the table are returned as name-value attributes, rather than message folders. The containers longestString, mirrorTran, and channelName are all character containers that do not require additional interpretation, therefore they can be put straight into the XML message for output from the flow.

Message flows

The following diagram shows the main CICS Transaction Server for z/OS Channel Connectivity sample message flow.

CICS Transaction Server for z/OS Channel Connectivity sample message flow

Node type Node name
MQInput CICSCHANNEL_IN, CICSSingleMsg_IN
Compute CreateCollection, AddLENames, ProcessChannel, ProcessAbend
CICSRequest CICS Request
MQOutput CICSCHANNEL_OUT, CICSCHANNEL_ABEND

To find out more information about the nodes that are used in the CICS Transaction Server for z/OS Channel Connectivity sample, see Built-in nodes in the WebSphere Message Broker documentation.

Route taken by the channel sample messages

When you put one of the messages onto the input queue, the message passes through the nodes. If any of the queues have been disabled, the message cannot follow this path.

The following section describes the route taken by the messages, and the function of the nodes in the main CICS Transaction Server for z/OS Channel Connectivity sample message flow.

Message collection mode: A message is sent to the queue CICSCHANNEL_IN

  1. CICSCHANNEL_IN: The CICSCHANNEL_IN MQInput node gets the input message from the input queue.
  2. CreateCollection: The CreateCollection Compute node creates a message collection by first creating an immediate last-child of the root element called Collection and copying the input properties folder. The node creates an element (CollectionName) and gives it the name (which will become the channel name). The node then iterates through each of the number folders from the input message, and creates a uniquely named message folder for each one. For the string folders, the node creates unique elements rather than folders. The node sets a local environment value for each element to identify it as a character container.
  3. CICS Request: The CICSRequest node is configured for channel data structures. The node calls the CICS program WMBCHAN1, and expects a channel response.
  4. ProcessChannel: The ProcessChannel Compute node creates a new XMLNSC output message based on the message collection produced by the CICSRequest node. The node copies the integer value from the message folder sum into the XML code, along with the three string attributes: longestString, channelName, and mirrorTran.
  5. CICSCHANNEL_OUT: The CICSCHANNEL_OUT MQOutput node puts the message on the CICSCHANNEL_OUT output queue.

Single message mode: A message is sent to the queue CICS_SINGLEMSG_IN

  1. CICSSingleMsg_IN: The CICSSingleMsg_IN MQInput node gets the input message from the input queue.
  2. AddLENames: The AddLENames Compute node sets the name for the channel, and the name for the container that holds the input message data. The node also sets the container to be a character container.
  3. CICS Request: The CICSRequest node is configured for channel data structures. The node calls the CICS program WMBCHAN1, and expects a channel response.
  4. ProcessChannel: The ProcessChannel Compute node creates a new XMLNSC output message based on the message collection produced by the CICSRequest node. The node copies the integer value from the message folder, sum, into the XML code, along with the three string attributes: longestString, channelName, and mirrorTran.
  5. CICSCHANNEL_OUT: The CICSCHANNEL_OUT MQOutput node puts the message on the CICSCHANNEL_OUT output queue.

The CICS Transaction Server for z/OS Channel Connectivity sample demonstrates how to read an input message, construct a message collection, connect to CICS, and how to drive a channel-based program. The returning message collection is transformed to XML and is output to a queue.

For more information, see Working with CICS Transaction Server for z/OS in the WebSphere Message Broker documentation.

You can now complete the setup steps described in Setting up the CICS Transaction Server for z/OS Channel Connectivity sample before running the sample.

Back to sample home