COMMAREA or channel data structures

If using a COMMAREA as the input data structure for communicating with CICS, the CICSRequest node takes a portion of the Input Body, as defined in the CICSRequest node Request properties, and sends it to CICS as the COMMAREA.

The returning COMMAREA is then put into the Output tree and replaces the existing Body at the location that is defined in the CICSRequest node Result properties. The COMMAREA can then be configured for parsing by using the CICSRequest node Response Message Parsing properties.

When defining a COMMAREA data structure as input, you must ensure that the CICSRequest node Commarea length property value is large enough to contain the input request data, or the output response data, but that it does not exceed the maximum value of 32767 bytes. If the Commarea length value is not large enough to be used for the response data, or the request data, a memory leak occurs in CICS. The size of the COMMAREA cannot be changed by the CICS program. If the serialized request data is larger than the Commarea length, the data is truncated to the Commarea length. You can obtain the Commarea length value from the CICS administrator or developer.

The default value for the CICSRequest node data structure basic property is Commarea.

If using direct two-tier connection, CICS looks at the JVM file.encoding property to determine the code page of the COMMAREA. This can cause code page conversion errors in the CICS program. If the property is not set, a default value of 437 is used. For more information, see the CICS documentation about code pages.

For more information about using a COMMAREA data structure as input, see Defining a CICS Transaction Server for z/OS data structure, Developing a message flow with a CICSRequest node, and Building a message for the CICSRequest node.

CICS channels hold a number of structures called containers. Containers hold the business information that is accessed by the target CICS program. Each container can hold up to 2 GB of data, and channels can have as many containers within them as required, which provides flexibility in terms of the size and layout of data. Each container has a 16-character maximum alphanumeric container name, which is unique within the channel, and is used as the mechanism to retrieve the contents of the container from the channel.

Unlike COMMAREA structures, the size of the response channel does not need to resemble the request, whereas COMMAREAs must allow for the size of the response in the request.

Channels and containers in CICS

In the following example diagram, the CICS channel has two containers; CustomerName and Order.

01 ORDER_STRUCTURE.
          03 QTY                  COMP-1.
          03 ITEM                 PIC X(10).
          03 PRICE                PIC S9(9).

Channels and containers in IBM Integration Bus

In IBM Integration Bus, a CICS channel is represented as a message collection structure. A message collection can hold child messages, each treated as a container by the CICSRequest node. A message collection structure is used as both input and output to the CICSRequest node when using a channel data structure. For more information about message collections, see Message collections, and for information about creating a message collection, see Creating a message collection by using ESQL.

The message collection name is used to name the channel. The name of the child message in the message collection is used as the name of the container in the channel, and must be unique. If the child message name in the message collection is not unique, the request is rejected in CICS.

Name-value attributes

IBM Integration Bus supports adding name-value attributes to a message collection to create a container. A message collection can have zero or more attributes. The name of an attribute must be unique within a message collection. A standard attribute for the message collection is an attribute called CollectionName.

You can add name-value attributes to a message collection to create CICS containers. Name-value attributes in the message collection, apart from CollectionName, can be used in lieu of full message-folders for simple data. For example, a name-value string attribute can be set in the message collection and used directly by the CICSRequest node without needing to create a message set for the element.

Name-value attributes can be produced from containers on output, as well as accepted for input. For information about creating an attribute instead of a message folder from a container, see CICSRequest node.

In the following example diagram, the CICS channel is represented by a message collection named Collection. Collection holds two containers that are represented by child messages named CustomerName and Order. CollectionName and CustomerName are both name-value attributes, however the CollectionName attribute is not treated as a container by the CICSRequest node, and is therefore not sent to CICS.

If the CustomerName attribute is to be treated as a character container by the CICSRequest node, the LocalEnvironment must reflect this.

LocalEnvironment

SET OutputLocalEnvironment.Destination.CICS.RequestChannel.Containers.<myContainerName> = CHARACTER;

When a message collection is emitted from the CICSRequest node following the request, the LocalEnvironment contains the returned type information for the containers. For example, when the response channel comes back from CICS, the LocalEnvironment shows the types of the containers that have come back in the following location: LocalEnvironment.CICS.ResponseChannel.Containers.<myContainerName> = CHARACTER

SET OutputLocalEnvironment.Destination.CICS.RequestChannel.ChannelName = <myNewChannelName>;

SET OutputLocalEnvironment.Destination.CICS.RequestChannel.SingleMessageContainerName = <mySingleMessageContainerName>;

Because a message collection allows each container in the channel to be modeled as a separate message, each message has its own structure and parsing options. For example, one container might be XML and another might be based on a copybook, which can be represented by using XMLNSC and MRM messages within a message collection.

Each child message in the message collection contains message domain, set, type, format, CCSID, and encoding information in the Properties folder that is associated with the child message, which is serialized into a byte stream and sent to CICS. Each child message folder within the message collection that is being sent to CICS is serialized at the level of the last child of the message property domain. Not all CICS containers require a message set to represent them.

In the previous example, the Order container can be represented as MRM, and a message set can be created from the copybook ORDER_STRUCTURE to represent it. The returning channel is converted into a message collection, where every child message in the message collection represents a container from the channel. Child messages in the message collection are mapped to a list of message domain, set, type, format, CCSID, and encoding information by using the child message name, however CCSID, and encoding information are ignored for character messages. If a mapping cannot be found in the message, a default mapping can be provided.

Because it is not possible to know how many containers are in the response, a message collection is always produced as output.

You can use the CICSRequest node Response Message Parsing properties to map a returning container to a message domain, set, type, format, CCSID, and encoding information. In particular, the Result data location property can be used to reduce the result tree down to a single message folder, or down to a single field or subtree for output. For information about the Result data location property, see CICSRequest node.