Basic OTMA message flow

The basic message flow for OTMA clients is relatively simple.

The basic message flow is:

  1. The client submits a transaction or command to IMS.
  2. IMS accepts IMS transactions as input from any client.

    The IMS transaction code is specified in the application-data section of the input message.

    If the client is submitting an IMS command, the command is included in the application-data section of the input message.

  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. The output is sent to the client synchronously or asynchronously, depending on the type of request.

  4. Application output is sent to the client.

    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.

    The application output is enqueued to a dynamically created IMS transaction-pipe structure (specific to that client) before being sent to the client.

    For an OTMA-submitted transaction, IOPCB output is returned to the OTMA client. By default, all alternate PCB output is also sent to the OTMA client. You can change this by coding either an OTMA destination descriptor in the OTMA DFSYDTx PROCLIB member or by coding the OTMA Destination Resolution user exit (OTMAYPRX) or the client's OTMA User Data Formatting user routine (DFSYDRU0). You can also use these exit routines to route alternate PCB output from non-OTMA-submitted transactions to OTMA clients.

    IMS delivers segmented messages in order, even though the z/OS® cross-system coupling facility (XCF) does not guarantee sequential delivery of messages.

The following figure shows an example of the message flow in an OTMA environment. Two clients are shown side by side in the example; they can be a TCP/IP client, a IBM® MQ Queue Manager client, or a client of any other network type. Message flow starts with the client, goes through the XCF group, and to IMS. Within the IMS address space, a control region contains OTMA; the message flow ends at a transaction-pipe. The IMS application program issues a Get Unique (GU) call in the dependent region.

Figure 1. IMS message flow in an OTMA environment
Client 1 issues prefix plus message for tpipe 1. Client 2 issues prefix plus message for tpipe 1. Messages go through XCF group to IMS control region, where GU and ISRT calls are made in dependent region.

In the preceding figure:

  1. The message prefix is always attached to the input transaction, even in the case of segmented input. This prefix contains important information, such as the transaction-pipe name and the client token.

    A client application program can send several transactions specifying the same transaction-pipe name. The client token must always be present in the prefix, so that the client application program knows how to process the IMS output it receives.

  2. OTMA clients do not need to predefine transaction pipes. Two different clients can use the same transaction-pipe name. Although many clients can use the same transaction-pipe name, each transaction pipe is unique. client 1 and client 2 both use tpipe1, yet each is a unique transaction pipe.

    A client can create and use as many transaction pipes as it needs.

  3. The transaction-pipe structure is created dynamically when OTMA receives output and is used as an anchor for the application output.
  4. The IMS application program has no knowledge of the OTMA message prefix when it issues the GU call.
IMS supports a full-duplex message flow for a client/server session. The client can instead request a half-duplex message flow, but this flow must be implemented and managed by the client itself:
  • A correlator token in the state-data section of the message prefix can be used to uniquely identify a transaction. IMS maintains this field in the message prefix for a transaction.
  • The client can set the response-requested flag in the message-control information section of the message prefix to receive a response for a message.
  • Any unsolicited output from IMS is easily identified by a client, because the message prefix specifies only the transaction-pipe name. The client can ask IMS to discard the output.

    Unsolicited output should not interfere with half-duplex processing. That is, the client must be prepared for full-duplex flows while still maintaining a half-duplex flow on a user-token level. Contention should not be an error condition.