Skip to main content

An Introduction to IBM IMS OTMA

IMS Open Transaction Manager Access (OTMA) is a component of IMS TM and is a transaction-based, connectionless client/server protocol. The implementation of OTMA is specific to IMS in a z/OS sysplex environment and the domain of the OTMA protocol is restricted to the domain of the z/OS Cross-System Coupling Facility (XCF). For a visual, see Figure 1.

OTMA provides standard access into IMS from any MVS client and uses the MVS XCF Interface, allowing high performance cross address space communications.


Figure 1: An OTMA client talks to OTMA via. the z/OS Cross-System Coupling Facility

OTMA only operates in the following IMS environments:

  1. IMS TM and DB (the IMS DB/DC environment)
  2. IMS TM with Db2 for z/OS (the IMS DCCTL environment)

Now that we have been introduced to what OTMA is, it’s probably a good time to get introduced to some familiar OTMA terminologies.

OTMA Client (subhead)

OTMA is designed to be a high-performance comprehensive protocol that allows z/OS programs to access IMS applications. A z/OS program in this case means any z/OS application that is a member of an XCF group that includes IMS. The XCF group members that IMS communicates with are called OTMA clients. By using OTMA, each OTMA client (z/OS application) can submit transactions to IMS or issue IMS Commands and receive output from IMS applications programs and IMS itself.

So, in simple terms, an MVS address space that issues XCF calls to IMS is called an OTMA Client. OTMA clients can access IMS transactions and commands.

fig2.pngFigure 2: OTMA clients are simply those that issue XCF calls to IMS


OTMA is a client/server protocol in which IMS can communicate with, or serve, many OTMA clients. Therefore, IMS is called the Server. In other words, the IMS support for XCF is called OTMA, wherein IMS functions as a SERVER.

Transaction Pipes

A Transaction Pipe (TPIPE) is a logical connection between an OTMA client and the server (IMS). TPIPES enable an OTMA client to associate its transactions with a TPIPE name. IMS uses the TPIPE name to associate all input and output with an OTMA client. Thus, OTMA TPIPEs are IMS constructs (control blocks) that allow IMS to associate messages with a specific OTMA client.

OTMA TPIPEs are not predefined; the TPIPE structure is created dynamically. Thus, different OTMA clients could use the same TPIPE name and each is treated as a unique instance.

How Is an OTMA TPIPE Analogous to an IMS Logical Terminal?

An IMS transaction represents a request for IMS to do some work. Many transactions also require a response after IMS has completed the work. So, each transaction has a source (the requester) and often a destination (for the response). IMS uses the concept of a logical terminal (LTERM) to ensure that responses are associated with the correct requesters. An LTERM uses a queue where the transaction output is kept before it is returned to the requester. Thus, for each LTERM, IMS maintains a connection between the queue and the physical node that receives the output.

Although OTMA does not use an LTERM, it still must maintain a connection between the OTMA client and IMS. That connection is the OTMA TPIPE.

Flow of IMS Messages in an OTMA Environment: Basic OTMA Message Flow

The key to message flow for OTMA is the TPIPE which is the logical connection between the server (IMS) and the OTMA client.
fig3.pngFigure 3: All messages sent between IMS and the OTMA client have a pre-defined OTMA Message Prefix

The basic message flow for OTMA clients is as follows:

  1. The OTMA client submits a transaction or command to IMS. An OTMA client includes the TPIPE name in the message-control information section of the message prefix for the input message. The IMS Transaction Code is specified in the application-data section of the input message. If the OTMA client is submitting an IMS Command, the command is also included in the application-data section of the input message. The message prefix is always attached to the input transaction, even in the case of segmented input. The message prefix contains important information, such as the TPIPE name and the client token. A client application program can send several transactions specifying the same TPIPE name. The client token must always be present in the message prefix, so that the client application program knows how to process the IMS output it receives.
  2. IMS accepts IMS transactions or commands as input from any OTMA client.
  3. The input message is processed. An IMS transaction is enqueued to the appropriate application program using an IMS Scheduler Message Block (SMB). An IMS Command is processed by IMS itself.
  4. Application output is sent to the OTMA client. The output is sent to the client synchronously or asynchronously, depending on the type of request. Generation of output and commit are coordinated based on the commit mode specified in the state-data section of the message prefix for the input message.
  5. IMS associates application output for an OTMA client with a specific TPIPE. The application output is enqueued to a dynamically created IMS Transaction-PIPE structure (specific to the OTMA client) before being sent to the client.

Figure 4:
A basic OTMA message flow starts with the OTMA client, goes through the XCF group to IMS. Within the IMS address space, the IMS Control Region contains OTMA and the message flow ends at a TPIPE

NOTE: Important Things to Understand

OTMA clients do not need to predefine TPIPES. Two different clients can use the same TPIPE name. Although many clients can use the same TPIPE name, each TPIPE is unique. For example, in figure 4 above, Client1 and Client2 both use TPIPE1, yet each is a unique TPIPE. An OTMA client can create and use as many TPIPEs as it needs. The TPIPE structure is created dynamically when OTMA receives the IMS output and is used as an anchor for the application output.

All information in this article is provided to you “as is” and represents the views of the authors. TechChannel cannot guarantee or imply absolute reliability, serviceability or function of the information herein.