COMMAREA or channel data structures
CICS® Transaction Server for z/OS® programs can be linked to by using either a COMMAREA data structure or a channel data structure as input, which return the same data structure as output. The CICSRequest node supports interaction with CICS through 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.
binary. The type of container can affect the data conversion between IBM® Integration Bus and CICS, however the container type does not have any impact on the format of the information that can be put into the container.
- Character containers
- Character containers are more likely to be individual strings
or discrete data items, but can also be mapped structures, however
it is important to remember that data conversion is applied to the
data in the container. When a character container is constructed,
the source coded character set ID (CCSID) information about the container
is sent to CICS as metadata.
The CICS program uses the
GET CONTAINERapplication programming interface (API) call to convert the metadata to the default CCSID of the region, unless another CCSID is provided. The CICS program then places the container back into the channel, and the data is converted ready for the IBM Integration Bus application to retrieve and use.
- Binary containers
- Binary containers can be mapped by using a COBOL copybook structure or they might be discrete values. Data conversion is not applied to the data in a binary container, therefore the data in a binary container is sent to CICS and retrieved from CICS in original form only.
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
The target CICS program can retrieve both of these containers from the channel by providing the name of the container when using the
01 ORDER_STRUCTURE. 03 QTY COMP-1. 03 ITEM PIC X(10). 03 PRICE PIC S9(9).
GET CONTAINERAPI. When the data is provided to the CICS program, the program processes the data however it chooses. For example, the program can place other containers into the channel to provide a response to the called container by using the
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.
|CICS||IBM Integration Bus|
|Channel name||Message collection name|
|Container name (must be unique to the parent channel)||Child message name (must be unique to the message collection)|
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
You can add name-value attributes to a message collection to create CICS containers. Name-value
attributes in the message collection, apart from
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.
CollectionNameand CustomerName are both name-value attributes, however the
CollectionNameattribute 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.
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>;
ChannelNamein the LocalEnvironment. The 16-character maximum alphanumeric
SingleMessageContainerNamethat needs to be created must also be provided in the following location:
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.
- The channel must be given a 16 character maximum alphanumeric
Because the channel is represented by a message collection in IBM Integration Bus, you can create the channel name by setting the message collection name. Message collection names are set by using the
CollectionNameattribute. For more information about creating a message collection and setting the message collection name, see Creating a message collection by using ESQL.
- The following details must be specified for each container in
- A 16 character maximum alphanumeric name.
Because a container is represented by a child message in IBM Integration Bus, you can create a container name by setting the child message name. For more information about creating a message collection and setting the child message name, see Creating a message collection by using ESQL.
- A container type; for example,
- A directory to use to place the response data into.
- A 16 character maximum alphanumeric name.