You are currently on IBM Systems Media’s archival website. Click here to view our new website.

MAINFRAME > Administrator > IMS

Using IMS 14 Callout for Increased Throughput and Control

Many IMS customers rely on the synchronous callout function to issue requests from IMS applications to web services, message-driven beans or user-written IMS Connect client application for data or services. The responses are returned in the same transaction during the same unit of work. Several enhancements in IMS 14 enhance this function through transaction pipe (Tpipe) parallelism and the support for passing additional information through the control data area in the Data Language Interface (DL/I) ICAL call.

Tpipe Parallelism for Increased Throughput

When an IMS host application program issues a synchronous callout request using the DL/I ICAL call, IMS acts as a client in a client-server relationship where the server is the external ap-plication. The external application, such as the IMS TM resource adapter, IBM IMS Enterprise Suite SOAP Gateway or IBM WebSphere DataPower appliances, needs to pick up the callout re-quests by issuing a Resume Tpipe call to IMS.

However, even when multiple external applications are set up to retrieve callout messages from a specific Tpipe queue, the external application that picks up the first callout message would re-main active and persist to process all the remaining callout messages. All the other retrieve calls from other applications will be queued in IMS to be activated when the current active retrieve call or Resume Tpipe call is ended. This behavior impacts the response time and throughput of synchronous callout messages.

In IMS 14, the Tpipe parallelism enhancement allows multiple Resume Tpipe calls to be active concurrently so that synchronous callout messages can be sent in parallel to more than one IMS Connect client. If the processing for any one Resume Tpipe request becomes impaired, Open Transaction Manager Access (OTMA) will continue to deliver the output messages on the Tpipe through the other active Resume Tpipe requests, preventing the Resume Tpipe request, or the Tpipe itself, from becoming a bottleneck.

Turning on the MULTIRTP= option in the IMS Connect configuration statement or OTMA cli-ent descriptor will activate the Tpipe parallelism function. Another method to enable the TPIPE parallelism function is to specify the LIMITRTP=nnnn parameter in the OTMA client descriptor, where nnnn is the maximum number of active Resume Tpipe calls for the Tpipe parallelism function. If MULTIRTP=YES isn’t already specified, specifying a value on LIMITRTP enables the Tpipe parallelism function.

A performance study for the Tpipe parallelism function concluded that setting the LIMITRTP value to 25 received the best performance throughput.

Control Data in an IMS Host Application

Each DL/I ICAL call in an IMS host application program specifies an application interface block (AIB) to communicate with IMS the routing information for the request. Routing information, such as IMS Connect cross-system coupling facility member name, Tpipe destination name, super member name, adapter name for SOAP Gateway and converter name for SOAP Gateway can be defined in an IMS OTMA destination descriptor or by issuing the IMS CREATE OT-MADESC command. However, other information such as TCP/IP port, routing operation code, security token or other routing information that users might want to have control of can’t be specified. In addition, the number of OTMA destination descriptor entries that can be specified in IMS is limited. These restrictions confine the usage of the synchronous callout function.

In IMS 14, a new “control data area” parameter is added to the end of the existing format of DL/I ICAL call. This new area is optional and it gives users the control of any routing information they want to add, such as user-provided token or security data. Each control data can consist of 1-to-many control data items. The format of control data items is:

 	LLLL | <tag> | data | </tag> {LLLL | <tag> | data | </tag>…}

The tag name and data contents will be treated as binary and passed "as is" to the target client. The AIBOPLEN field in AIB specifies the total length of the control data that includes all the control data item(s). See Figure 1 for a COBOL example.

For IMS Java applications running in Java message processing and Java batch processing re-gions, three new or enhanced Java Message Service API methods are provided to issue DL/I ICAL calls with control data. See figures 2 and 3 for information about the API and a Java ex-ample.

Using Control Data in User-Written IMS Connect Client Applications

For a user-written TCP/IP application to which an IMS host application issues a synchronous callout, the external TCP/IP application can be expanded to recognize the control data passed from the IMS host application. Since the control data can contain anything, the TCP/IP applica-tion needs to sync up with the DL/I ICAL call to take appropriate actions.

First, the TCP/IP application must send a RESUME TPIPE request to IMS Connect and specify the IRM_F5 flag in the IMS Request Message (IRM) header of IMS Connect. This flag informs IMS Connect that the application supports control data for the synchronous callout. Second, the application needs to handle the enhanced format of the output message sent by IMS Connect (see Figure 4). This format includes a new structure for control data that is placed before the callout request data.

Using Control Data for Synchronous Callout Through IMS SOAP Gateway

As one of the IMS Connect clients, IMS SOAP Gateway in IMS Enterprise Suite V3.2 is en-hanced to support and take advantage of the DL/I ICAL control data to allow you to customize and dynamically control the processing of the callout request at runtime with finer granularity. This enhancement provides options for overriding the static configuration for service invocation and allows IMS SOAP Gateway to honor and dynamically act based on the “control data” pro-vided as part of the DL/I ICAL request. For example, you can change the target destination from what is specified in the callout web service description file, which is in the format of a web ser-vices description language (WSDL) file. You can also specify a different XML converter from what is specified in the correlator file that specifies transaction and run-time related properties. Or you can include a customized SOAP header to pass along a variety of user data, such as secu-rity information, logging information, statistic data or routing information.

Table 1 lists XML tag names supported by IMS SOAP Gateway for DL/I ICAL control data support.

You can also send other custom data through the control data area in your DL/I ICAL call to be passed through the SOAP header provided that:

  • They are enclosed in tags that do not start with the IMS-reserved prefix DFS
  • The tags are well-formed, with self-contained names, namespaces and attributes

IMS SOAP Gateway places these “non-DFS-prefixed” elements as part of a custom child header element with a predefined header name, SOAPHEADERFORUSERDATA, with a namespace prefix of icalcdextras, and the namespace value of (see Figure 5).

Figure 6 shows an example that demonstrates how to use the control data area to overwrite the static configuration for a callout web service that’s already deployed to the SOAP Gateway serv-er.

Enhanced Experience

The Tpipe parallelism enhancement in IMS 14 significantly improves the throughput on OTMA Tpipe for output messages, especially those for synchronous callout requests. The optional control data area that can be specified in the DL/I ICAL call adds flexibility in request destination routing and opens the door to a wide variety of possibilities, allowing IMS callout applications to pass just about any information to external web services or IMS Connect client applications. If you’re us-ing or considering to use the synchronous callout function in IMS 14, these enhancements defi-nitely are worth your attention.

Sandy Sun is a IMS SOAP Gateway developer. She can be reached at

Jack Yuan is a senior software engineer for IMS development. He can be contacted at

Yee-Rong Lai is a key information developer for the IMS SOA solution suite at the IBM Silicon Valley lab.

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Bringing IMS and SOA Together With IMS Connect

New requirements for IMS Connect functionality could make implementing an SOA environment with IMS easier and more flexible.

Celebrating 40 Successful Years

IMS version 10 supports synchronous and asynchronous callout

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
Mainframe News Sign Up Today! Past News Letters