MAINFRAME > Administrator > IMS

Enhanced IMS 13 Java Adapter Improves Applications’ Request-Response Communication

IMS provides a set of Java APIs called the IMS Java dependent region resource adapter to help developers create applications that run in IMS Java Message Processing (JMP) and Java Batch Processing (JBP) dependent regions. With IMS Version 13, the adapter is significantly enhanced to provide Java applications with improved internal and external options for synchronous request-response communication.

These functions are provided to the adapter with the IMS implementation of the Java Message Service (JMS) API. The JMS API provides a standardized front end to the IMS DL/I ICAL interface for IMS Java applications. Such applications can use this API to participate in two models of synchronous request-response communication in the same way as PL/I and COBOL applications that use the DL/I interface directly:

  • Synchronous callout to external services and applications
  • Synchronous program switch to other IMS applications

In either type of request, the IMS application sends the request and then remains scheduled while it’s completed by the target application or external service. The requesting application receives the response and can then continue processing in the same unit of work (UOW). The requesting application specifies the target by including the name of an Open Transaction Manager Access (OTMA) destination descriptor in the request. Each OTMA destination descriptor is defined to IMS either at startup in the DFSYDTx member of the IMS.PROCLIB data set or with a type-2 command—CREATE OTMADESC. The descriptor includes all of the routing information that IMS needs to find the destination for the request. For DL/I applications, the request and response data are stored in the application interface block (AIB) data area, which must be managed by the requesting application. In a Java application program, you can use JMS-supplied message objects to contain the request and response message data.

Synchronous Callout

IMS Java applications can request data or services from external applications by issuing a synchronous callout request. In a synchronous callout request, the application remains scheduled while IMS determines the request destination from the OTMA routing descriptor, gets the response from the external service, and returns the response data to the requesting application. In IMS V13, OTMA supports the following destination types for synchronous callout requests:

  • TCP/IP applications via IMS Connect and the Connect APIs
  • SOAP applications via IMS Connect and IMS Enterprise Suite SOAP Gateway
  • IBM WebSphere Application Server applications via IMS Connect and IMS TM Resource Adapter

A synchronous callout request, which is illustrated in Figure 1, consists of the following sequence of events:

  1. The IMS Java application program builds and submits a request message with the JMS API.
  2. The JMS API call is translated into a DL/I ICAL call by the IMS DB Resource Adapter.
  3. The DL/I ICAL call is sent to the IMS TM control region and routed according to the OTMA destination descriptor specified in the request.
  4. The external client retrieves the request from an IMS Connect TPIPE hold queue, processes it, and sends a response message.
  5. The IMS DB Resource Adapter translates the response into a JMS API response message.
  6. The original Java application program retrieves and reads the response message.

The following example (also found in Code Sample 1) demonstrates the program flow used to issue a synchronous callout request from an application that runs in an IMS Java Message Processing region.

package testcases.udb.opendb.t2;

import javax.jms.QueueConnection;
import javax.jms.QueueRequestor;
import javax.jms.QueueSession;
import javax.jms.TextMessage;


public class SyncCalloutFromJMPSample {
	private static IOMessage inputMessage = null;
	private static IOMessage outputMessage = null;
	private static MessageQueue msgQueue = null;
	private static Application app = null;

	public static void main(String args[]) {
		// Create an IMS JMP application
		app = ApplicationFactory.createApplication();

		// Get the IMS JMS queue connection factory
		IMSQueueConnectionFactory jmsConnectionFactory = app.getIMSQueueConnectionFactory();
		QueueConnection jmsConnection = null;
		QueueSession jmsQueueSession = null;
		javax.jms.Queue jmsQueue = null;
		QueueRequestor jmsQueueRequestor = null;

		try {
			// Get a reference to the IMS message queue
			msgQueue = app.getMessageQueue();

			// Create an input message object
			inputMessage = app.getIOMessage("class://MyInputMessage");

			// Create an output message object
			outputMessage = app.getIOMessage("class://MyOutputMessage");

			// Retrieve messages off the queue
			while (msgQueue.getUnique(inputMessage)) {

				// Setting the JMS settings to issue an ICAL call

				// Specify the amount of time to wait for a response from an
				// ICAL call. This value corresponds to the RSFLD value in the AIB

				// Specify the expected size of the response message from the
				// ICAL call. This value corresponds to the OAUSE value in the AIB
                          	int expectedResponseLength = 50;

				// Create the JMS queue connection
				jmsConnection = jmsConnectionFactory.createQueueConnection();

				// Create the JMS queue session
				jmsQueueSession = jmsConnection.createQueueSession(false, 1);

				// Specify the OTMA Routing descriptor which describes the
				// target that the ICAL call will be sent to. This value 
				//corresponds with the RSNM1 value in the AIB
				jmsQueue = jmsQueueSession.createQueue("MYDEST");

				// Create the JMS queue requester
				jmsQueueRequestor = new QueueRequestor(jmsQueueSession,

				// Build the request area for the ICAL call
				// For synchronous callout a TextMessage object must be used
				TextMessage sendMsg = jmsQueueSession.createTextMessage();

				// Specify the input data for the synchronous callout

				// Submit the ICAL call
				// >>-ICAL--aib--request_area--responseArea------<<
				// For synchronous callout, the reply message will be a TextMessage object
				TextMessage replyMsg = (TextMessage) jmsQueueRequestor

				// Retrieve the Data field


			// Terminate the application and free up any associated resources

		} catch (Exception e) {
			// Error scenario, free up resources


To make a synchronous callout request, you must first create an OTMA destination descriptor with the TYPE value of IMSCON for the destination. The descriptor describes to OTMA how to route the request. A simple OTMA destination descriptor for is shown here:


This descriptor specifies that messages will be routed to an IMS application and that the requesting application will wait up to five seconds for a response from the target application before the request times out. If a response message is returned after the requesting application times out, it is de-queued.

David Hanson is an information developer for IBM IMS, focused on connectivity and application modernization. He can be contacted at

Hugh White III is an IBM software engineer working as an IMS systems QA tester.

Richard Tran is an IBM software engineer working as the IMS Open Database team lead. He is involved in integrating IMS with other business solutions such as business analytics and reporting, content discovery and web enablement.

comments powered by Disqus



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