Control data in synchronous callout requests

IMS application programs can make a synchronous callout request by using the ICAL DL/I call. The ICAL call sends a callout request to an IMS Connect client application and receives a response. The routing specification of a callout message is defined in the message’s application interface block (AIB) and an OTMA destination descriptor. You can define up to 4095 destination descriptors in a DFSYDTx member of the IMS PROCLIB data set. When there are thousands of callout end points for the messages, using a limited number of OTMA destination descriptor entries for routing specification creates a challenge. Additionally, there is no easy way to include multiple Universally Unique Identifiers (UUID), SOAP headers, security token, or even user-provided routing information in the callout message.

To solve this problem, the ICAL call format accepts optional control data, which can be the URL for a port, UUID, user token, security information, or any other information. By using the control data field, IMS application programs can specify the routing information or other control data at run time when they issue the ICAL call.

The control data can consist of 1 to many control data items so that a number of services or operations can be specified on the same synchronous callout call. Each control data item starts with 4 bytes length field followed by a tag, data, and an end tag.

The ICAL control data can consist of one to many control data items so that a number of services or operations can be specified on the same ICAL call. Each control data item starts with a 4-byte length field followed by a tag, data, and the end tag. Tags can be of any length. The start tag consists of a less than sign (<), the tag name, and a greater than sign (>). The end tag consists of a less than sign (<), a slash ( / ), the tag name that matches the start tag), and a greater than sign (>).

The format of a control data item in ICAL control data is as follows:

LLLL  <tag1> data1 </tag1>  { LLLL <tag2> data2 </tag2> ... }

An IBM®-initiated control data item starts with DFS in the tag, such as <DFSCNVTR>.

The tag name and data contents are treated as binary data and passed "as is" to the target client. The <, /, and > signs, and IBM-initiated control data tag names, which begin with DFS, must be EBCDIC.

OTMA does the “well-form” checking for the control data to make sure that it follows the supported format with the correct length. The total length of the control data with control data items needs to be specified in the AIBOPLEN field in the AIB. OTMA puts the control data in front of the application data and update the OTMA prefix to indicate the number of segments of control data in the application data section for a callout message. The OTMA resume tpipe protocol command supports the callout with control data option.

The IMS Connect user message exits look for a flag in the IRM that indicates whether the client supports control data. If a flag is set, an appropriate flag is set in the state data section of the OTMA headers for the resume tpipe. Upon receiving the message that contains control data from IMS, the user message exits extract the control data from the application data section of the message and build a segment similar to the callout correlation token segment. This is done for messages other than IMS TM Resource Adapter messages for IMS Connect. The resulting message from the user message exit will then be transmitted to the client by IMS Connect.

If you are using SOAP Gateway, you can use control data to specify the name of the XML converter you would like to use to process the request. In the control data, use the <DFSCNVTR> tags to specify an XML converter name.

The IMS Java™ dependent region (JDR) support provides an API for control data of the ICAL call.

The control data is designed for a callout request for an outbound message. The control data in a response message is not supported.