Oct 30 ’13

Sending IMS Callout Messages to WebSphere MQ Using OTMA Destination Descriptors

by Ben Johnson, Dave Cameron & Jack Yuan  in Enterprise Tech Journal

Version 13 of the IBM Information Management System (IMS) makes sending asynchronous callout messages to WebSphere MQ simpler and more flexible than ever before. You no longer need to code IMS exit routines to define MQ headers or restart IMS after changing either the MQ header values or message routing information. You can now use Open Transaction Manager Access (OTMA) destination descriptors and IMS commands to dynamically define and route messages in IMS that are destined for WebSphere MQ.

OTMA Destination Descriptors

Prior to IMS 10, sending outbound asynchronous callout messages to external destinations through the IMS OTMA component required systems programmers to code several Assembler OTMA routing user exit routines, such as the OTMA Destination Resolution exit routine (DFSYPRX0) and the OTMA User Data Formatting exit routine (DFSYDRU0). Writing or updating an IMS user exit routine in the Assembler programming language can be difficult and can inhibit or delay the adaptation of IMS to new connectivity implementations.

The OTMA destination descriptors, first introduced in IMS 10, can eliminate the need to code these OTMA routing user exit routines by providing an easier way to indicate the values and options that previously could be specified only by the exit routines. IMS stores OTMA destination descriptors in the DFSYDTx member of the IMS procedure library (IMS PROCLIB). During start-up, IMS reads any predefined descriptors in the DFSYDTx member and initializes them.
After IMS start-up, you can use IMS type-2 commands to query, create, update or delete the OTMA destination descriptors, which makes managing OTMA messages even easier.

In IMS 13, if both an OTMA destination descriptor and an OTMA routing user exit routine are used, the OTMA exit routines can be called to make a final routing decision and override the values specified in the destination descriptor, if necessary.

You can use OTMA destination descriptors to:

• Send OTMA asynchronous callout messages to non-OTMA destinations, such as SNA printers and terminals
• Initiate a synchronous program switch in IMS 13 between two IMS application programs
• Send asynchronous and synchronous callout messages to IMS Connect
• Send asynchronous callout messages to WebSphere MQ.

Let’s examine how to use the OTMA destination descriptors to send asynchronous callout messages from IMS application programs to WebSphere MQ.

Calling Out to WebSphere MQ

Figure 1 shows how an OTMA descriptor can be used with an asynchronous callout message to WebSphere MQ. A Batch Message Processing (BMP) application program specifies MQM001 as the destination for an asynchronous callout message. An OTMA destination descriptor is defined with the name MQ*. The asterisk is a wild card character.

When IMS receives the asynchronous callout message, it searches all OTMA destination descriptors to find a match for MQM001. In this case, IMS doesn’t find a destination descriptor name that exactly matches MQM001, so the descriptor MQ* is used. By using a wildcard character, one descriptor can be used for multiple destinations. 

WebSphere MQ Options

You can use OTMA destination descriptors to route asynchronous callout messages to WebSphere MQ and to create the MQMD (Message Descriptor) that WebSphere MQ requires. To route asynchronous callout requests to WebSphere MQ, you must specify these parameters in the OTMA destination descriptor:

• TMEMBER, to identify which OTMA client to send the message to
• MQRTQMGR, to identify which WebSphere MQ reply queue manager will process the message
• MQRTQ, to specify the WebSphere MQ queue for the message. 

Setting MQMD Options

Messages sent to WebSphere MQ require an MQMD header. Prior to IMS 13, you had to code OTMA exit routines in Assembler to build and define the MQMD headers. In IMS 13, you can specify MQMD values in an OTMA destination descriptor and OTMA will build the MQMD headers for you.

You can still use the OTMA routing exit routines to modify the values specified in the OTMA destination descriptors.

Reusing the MQMD Structure

If a transaction message that was originally received from WebSphere MQ starts as an asynchronous callout request, you can have IMS create the MQMD for the asynchronous callout message from the MQMD of the input message by specifying MQCOPYMD=Y in the OTMA destination descriptor.

All of the MQMD fields from the input message are copied to the callout message. Any MQ specifications in the OTMA destination descriptor that differ from the original MQMD specifications override the original MQMD values. 

Setting MQMD Values

The WebSphere MQ application uses some of the parameters you can specify on the OTMA destination descriptor (such as MQMSGID, MQCORRELID and MQAPPLID) to selectively retrieve from the queue only those IMS callout messages that match certain criteria.

The parameters in the OTMA destination descriptor WebSphere MQ uses correspond to parameters WebSphere MQ defines. For example, the MQREPORT parameter corresponds to MQMD_REPORT. This parameter is used to tell WebSphere MQ how to manage the MQMSGID and MQCORRELID values. The values you specify for these options must work with the WebSphere MQ application that will retrieve the messages.

If the transaction that issued the asynchronous callout message was initiated from WebSphere MQ and you specify MQCOPYMD=Y, then IMS copies the values for MQMSGID and MQCORRELID from the MQMD_MSGID and MQMD_CORRELID fields in the original MQMD. These values will be overridden if MQMSGID or MQCORRELID are coded in the OTMA descriptor.  

You can specify several options on the MQREPORT keyword in the OTMA destination descriptors. Here’s a list, with the name of the value as it’s defined in WebSphere MQ shown in parentheses:

• NEWMSGID (MQRO_NEW_MSG_ID) results in the MQMD_MSGID being generated by WebSphere MQ and the MQMD_CORRELID using the MQMSGID from the OTMA descriptor.
• PASSMSGI (MQRO_PASS_MSG_ID) results in the OTMA descriptor MQMSGID value being used for both the MQMD_MSGID and MQMD_CORRELID.
• PASSCORR (MQRO_PASS_CORREL_ID) results in the MQMD_MSGID being generated by WebSphere MQ and the MQMD_CORRELID uses the MQCORRELID from the OTMA descriptor.  

The MQFORMAT parameter is used to indicate to WebSphere MQ the nature of the data for the asynchronous callout message. The name of this value in WebSphere MQ is MQMD_FORMAT.
Values you can specify are:

• MQIMS (MQFMT_IMS), which specifies that the message begins with an IMS Information Header (MQIIH) followed by the application data. The format of the application data is specified in the MQIIH.
• MQIMSVS (MQFMT_IMS_VAR_STRING), which specifies that the application data is in the standard IMS variable-string format, LL ZZ DATA. The data might be in multiple segments with each segment starting with LL ZZ and no bytes between segments. 
• NONE (MQFMT_NONE), which specifies the application data type is undefined.


IMS 13 continues to takes new strides toward simplifying administration, increasing flexibility and integrating more closely with the other products that you use, such as WebSphere MQ.

Eliminating the need to code Assembler exit routines or map MQMD headers makes routing callout messages through OTMA to WebSphere MQ much easier. The ability to define and manage message routing dynamically with IMS commands—and without complex coding or restarts of IMS—gives you the flexibility you need to respond quickly and easily to changing business needs.

After 45 years, IMS still supports the core, strategic business needs of enterprises around the globe. With IMS 13, IBM continues to ensure that IMS will meet the needs of your enterprise for many years to come.

Additional Information: IMS 13—A Lot More for Less

IMS 13, which has been in beta all year, provides more open access, more integration, more manageability, more availability, more flexibility and more performance, all with less cost.

More open access. IMS 13 improves access to IMS data through industry standard technologies by moving the processing of SQL calls to the mainframe and expanding its support for the Distributed Relational Database Architecture (DRDA). IMS 13 can process SQL calls from COBOL, Java, DRDA and .NET application programs.

More manageable. Administering IMS 13 is simpler and more intuitive with the new IMS Explorer for Administration, a function being added to IBM Tools Base V1.4 through a service update. Designing application programs and databases is easier with the enhanced IMS Enterprise Suite Explorer for Development. Both IMS Explorer functions offer graphical interfaces.

More integrated. More products than ever provide integrated support for IMS databases, IMS transactions or both, including IBM products and product families such as Cognos, Optim, WebSphere, InfoSphere and Data Studio, as well as non-IBM offerings from providers such as SAP. IMS 13 also expands interoperability with the WebSphere DataPower SOA appliances and simplifies messaging with WebSphere MQ.

More flexibility and availability. IMS 13 makes adapting to new business requirements easier by letting you alter HALDB and DEDB databases online. Furthermore, with the new database versioning function, you can make certain changes to database structures without modifying application programs that use the structure.

More performance. IMS 13 improves performance with numerous enhancements to algorithms, locking and latching. IMS 13 uses storage services more efficiently and supports a higher rate of transactions per second than ever before.

Less cost. The improvements to processing efficiency in IMS 13 mean less processing cost. IMS 13 also extends the optional System z Integrated Information Processor (zIIP) specialty engine support to additional functionalities.

For more information about IMS 13, see the IMS 13 announcement letter available at www.ibm.com.