Explanation of OTMA message-control information fields

This topic provides explanations for the fields in the message-control information section of the message prefix.

Architecture level (TMAMCALV)

Specifies the OTMA architecture level. The client specifies an architecture level, and the server indicates in the response message which architecture level it is using. The architecture levels used by a client and a server must match.

Mandatory for all messages.

Message type (TMAMCMGT)

Specifies the message type. Every OTMA message must specify a value for the message type. The values are not mutually exclusive. For example, when the server sends an ACK message to a client-submitted transaction, both the transaction and response flags are set.

Data (TMAMCDTA - X'80')

Specifies server output data sent to the client. If the client specifies synchronization level Confirm in the state-data section of the message prefix, the server also sets Response Requested for the response flag. If the client does not specify a synchronization level, the server uses the default, Confirm.

Transaction (TMAMCTXN - X'40')

Specifies client input data to the server.

Whether the server replies with an ACK or NAK message depends only on whether Response Requested is also set for the response flag.

Response (TMAMCRSP - X'20')

Specifies the message type as response message, and is set when the message response flag specifies Response Requested.

If this flag is set, the response flag specifies either ACK or NAK.

The send-sequence numbers must match for the original data message and the response message. Chained transaction input messages to the server must always request a response before the next transaction (for a particular transaction pipe) is sent.

Command (TMAMCCMD - X'10')

Specifies an OTMA protocol command. OTMA commands must always specify Response Requested for the Response flag.

Commit confirmation (TMAMCCMT - X'08')

Specifies that commit is complete. This is sent by the server when a sync point has completed, and is only applicable for send-then-commit transactions. This flag can also be set by an OTMA client to inform the OTMA server to end the IMS conversational transaction.

Response flag (TMAMCRSI)

Specifies either that the message is a response message or that a response is requested.

Acknowledgments to transactions include attributes (for that transaction) in the application-data section of the message prefix only if the transaction specifies Extended Response Requested.

ACK (TMAMCACK - X'80')

Specifies a positive acknowledgment.

NAK (TMAMCNAK - X'40')

Specifies a negative acknowledgment.

See the sense code field for more information on the reason for the NAK.

Response requested (TMAMCRRQ - X'20')

Specifies that a response is requested for this message. This can be set for message types of Data, Transaction, or Command.

When sending send-then-commit IMS command output, IMS does not request an ACK regardless of the synchronization level.

Extended response requested (TMAMCERQ - X'10')

Specifies that an extended response is requested for this message. Can be set by a client only for transactions (or for transactions that specify an IMS command instead of a transaction code).

If this flag is set for a transaction, IMS returns the architected attributes for that transaction in the application-data section of the ACK message.

If this flag is set for a command, IMS returns the architected attributes in the application-data section of the ACK message. This flag can be set for the IMS commands /DISPLAY TRANSACTION and /DISPLAY TRANSACTION ALL.

Response to a synchronous callout request (TMAMSYRP - X'08')

Specifies that this message is a response to a synchronous callout message issued by an IMS application program running in an IMS dependent region.

When the flag for a synchronous callout response is set, most hold-queue capable clients, such as IMS Connect, also set the send-only message flag (TMAMHSOM - X'80') in the client flag field (TMAMHCFL) of the state data section of the message prefix.

If both the response-requested flag (TMAMCRRQ - X'20') and the TMAMSYRP flag are set in the response flag field, OTMA sends the client an indication (an ACK or NAK) of whether the response was successfully delivered to the IMS ICAL application.

Support for delayed ACK or NAK response (TMAMDACK - X'02')

Specifies that the client asks OTMA to return a NAK response to the client if OTMA receives a late or invalid acknowledgement from the client. For example, OTMA returns a NAK to the client when OTMA receives an acknowledgement after either the ACK timeout interval expires or a /STO TMEMBER TPIPE command has been issued clear the WAIT status of the tpipe. The NAK returned to the client by OTMA includes an X'2B' sense code.

Commit-confirmation and other flags

Specifies the success of a commit request. Sent by the server to the client in a commit-confirmation message. These messages are only applicable for send-then-commit transactions, and are not affected by the synchronization-level flag in the state-data section of the message prefix.

Committed (TMAMCCTD - X'80')

Specifies that the server committed successfully.

Aborted (TMAMCABT -X'40')

Specifies that the server aborted the commit.

Committed (TMAMCRTC - X'20')

Specifies that the server is ready to commit the output in the IOPCB after the server receives a commit notification from the client via RRS.

Aborted due to the OTMA timeout condition (TMAMCTMO -X'08')

Indicates that an ACK or NAK response from the OTMA client was not received before the timeout limit was reached.

Message level activation for SENDALTP function (TMAMALTP -X'04')

Indicates that a message level activation of the SENDALTP function for IMS Connect is specified.

Command type (TMAMCTYP)

Specifies the OTMA protocol command type.

IMS MTO commands are specified in the application-data section of the message.

Client-bid (TMAMCBID - X'04')

Specifies the first message a client sends to the OTMA server. This command must also set the response-requested flag and the security flag in the message-control information section of the message prefix. The appropriate state-data fields (for example, Member Name) must also be set.

The security-data prefix must specify a Utoken field so the OTMA server can validate the client's authority to act as an OTMA client.

Because the server can respond to the client-bid request, this message should not be sent until the client is ready to start accepting data messages.

Server available (TMAMCAVL - X'08')

Specifies the first message the server sends to a client. It is sent when the server has connected to the z/OS® cross-system coupling facility (XCF) group before the client has connected. The client replies to the Server Available message with a client-bid request. The appropriate state data fields (for example, Member Name) must also be set.

If the client connects first, it is notified by XCF when the server connects, and begins processing with a client-bid request.

CBresynch (TMAMCRSN - X'0C')

Specifies a client-bid message with a request by the client for resynchronization. This command is optional and causes the server to send an SRVresynch message to the client. The CBresynch command is the first message that a client sends to the OTMA server when it attempts to resynchronize with IMS and existing synchronized tpipes exist for the client. Other than the CBresynch message indicator in the message prefix, the information required for the message prefix should be identical to the client-bid command.

If IMS receives a client-bid request from the client and IMS is aware of existing synchronized tpipes, IMS issues informational message DFS2394I to the MTO. IMS resets the recoverable send- or receive-sequence numbers to 0 (zero) for all the synchronized tpipes.

Suspend processing for all tpipes (TMAMCSPA - X'14')

Specifies that the server is suspending all message activity with the client. All subsequent data input receives a NAK message from the server. Similarly, the client should send a NAK message for any subsequent server messages.

Clients can suspend processing for a particular transaction pipe by submitting a /STOP TPIPE command as an OTMA message.

Resume processing for all tpipes (TMAMCRSA - X'18')

Specifies that the server is resuming message activity with the client.

Clients can resume processing for a particular transaction pipe that has been stopped by submitting a /START TPIPE command as an OTMA message.

Suspend input for tpipe (TMAMCSPN - X'1C')

Specifies that the server is overloaded and is temporarily suspending input for the transaction pipe. All subsequent client input receives NAK messages for the transaction pipe specified in the message-control information section of the message prefix. A response is not requested for this command.

This command is also sent by IMS when the master terminal operator enters a /STOP TPIPE command.

Resume input for tpipe (TMAMCRSM - X'20')

Specifies that the server is ready to resume client input following an earlier Suspend Input for tpipe command. A response is not requested for this command.

This command is also sent by IMS when the IMS master terminal operator issues a /START TPIPE command.

Resume output for tpipe (TMAMCRTP - X'24')

Specifies one or multiple tpipe names to the OTMA server. All queued output on the tpipes will be resent again.

Resume output for all tpipes (TMAMCRAT - X'26')

Sent by client to request that OTMA resume sending output messages from all tpipes associated with the client. Does not apply to tpipe hold queues.

Resume output for the hold queue for tpipe (TMAMCRHQ - X'28')

Specifies that a client is requesting to retrieve messages from the hold queue for tpipe. There are command options to retrieve messages.

Cancel resume tpipe request (TMAMCDRH - X'29')

Sent by a client to the server to cancel a pending resume tpipe request. The resume tpipe request must be identified by specifying its resume tpipe token in byte 4 of the OTMA state data.

No messages on tpipe hold queue (TMAMCMSG - X'2A')

Sent by the server to the client when a resume tpipe request is received and the tpipe hold queue is empty.

SRVresynch (TMAMCSRS - X'2C')

Specifies the server's response to a client's CBresynch command. This command specifies the states of synchronized transaction pipes within the server (the send- and receive-sequence numbers).

This command is sent as a single message (with single or multiple segments), and an ACK is requested.

REQresynch (TMAMCRQS - X'30')

Specifies the send-sequence number and the receive sequence for a particular tpipe. REQresynch is sent from IMS to a client.

REPresynch (TMAMCRPS - X'34')

Specifies the client's desired state information for a tpipe. A client sends the REPresynch command to IMS in response to the REQresynch command received from IMS.

TBresynch (TMAMCTBR - X'38')

Specifies that the client is ready to receive the REQresynch command from IMS.

Resource state (TMAMMNTR - X'3C')

Sent by server to notify the client of the state of OTMA resources. The client can use this information to redirect transactions to a different server if server processing slows.

Processing flag (TMAMCPFG)

Specifies options by which a client or server can control message processing.

Resume tpipe token (TMAMQRTP - X'80')

For resume tpipe requests only, indicates that a resume tpipe request includes a token that uniquely identifies the request. OTMA uses the token to queue and process multiple resume tpipe requests in order.

The Resume Tpipe token is also specified by the client when the client cancels a resume tpipe request.

Synchronized tpipe (TMAMCSYP - X'40')

Specifies that the transaction pipe is to be synchronized. Allows the client to resynchronize a transaction pipe if there is a failure. Only valid for commit-then-send transactions.

This flag causes input and output sequence numbers to be maintained for the transaction pipe. All transactions routed through the transaction pipe must specify this flag consistently (either on or off).

Asynchronous output (TMAMCASY - X'20')

Specifies that the server is sending unsolicited queued output to the client. This can occur when IMS inserts a message to an alternate PCB.

Certain IMS commands, when submitted as commit-then-send, can cause IMS to send the output to a client with this flag set. In this case, the OTMA prefixes contain no identifying information that the client can use to correlate the output to the originating command message. These command output data messages simply identify the transaction-pipe name. IMS can also send some unsolicited error messages with only the transaction-pipe name.

Error message follows (TMAMCERR - X'10')

Specifies that an error message follows this message. This flag is set for NAK messages from the server. An additional error message is then sent to the client.

The asynchronous-output flag is not set in the error data message, because the output is not generated by an IMS application.

Message in the hold queue (TMAMCQUE - X'08')

Specifies that one or more messages exist in the hold queue for the tpipe to be delivered. This flag is always on for an IMS output message that has been sent from the hold queue for tpipe. Therefore, this flag can be used to determine whether there is any message in the hold queue for an IMS output message that has been sent from the regular queue for tpipe.

To determine whether the IMS output message is sent from the regular queue or from the hold queue, check the From Hold Queue flag in the Server State of the State Data.

To retrieve one or more messages from the hold queue, issue the Resume Output for the Hold Queue for tpipe protocol command.

Extra info set (TMAMXINF - X'02')

For a RESUME TPIPE request, it indicates that the user ID of the client who issues the request is included in the last 8-byte of the message-control information section. See Resume tpipe requester ID (TMAMRTID) below.

For a callout message, it indicates that the user ID of the client who issues the request is included in the state data section at offset 22. See Resume tpipe user ID (TMAMRTOD) in Transaction and callout messages.

Error message sent (TMAMCER3 - X'01')

An error was detected while processing a CM1 transaction and the application did not issue an ISRT to the IOPCB. Therefore, the DFS message is the only response for this CM1 transaction. The OTMA client, for example IMS Connect or IBM® MQ, must deliver the DFS message to the client application even if OTMA sets the deallocate abort flag in the commit confirmation message.

IMS Shutdown in progress (OMCTSHDN - X'80')

This flag indicates that the suspended processing for all tpipes (TMAMCSPA) is due to IMS shutdown.

This is only an output flag.

Tpipe name (TMAMCTNM)

An 8-byte character field that specifies a transaction-pipe name. For IMS, this name is used to override the LTERM name on the I/O PCB. This field is applicable for all transaction, data, and commit-confirmation message types. It is also applicable for certain response and command message types.

Chain flag (TMAMCCHN)

Specifies how many segments are in the message. This flag is applicable to transaction and data message types, and it is mandatory for multi-segment messages.

First-in-chain (TMAMCFIC - X'80')

Specifies the first segment in a chain of segments which comprise a multi-segment message. Subsequent segments of the message only need the message-control information section of the message prefix. Other applicable prefix segments (for example, those specified by the client on the transaction message) are sent only with the first segment (with the first-in-chain flag set).

If the OTMA message has only one segment, the last-in-chain flag should also be set.

Middle-in-chain (TMAMCMIC - X'40')

Specifies a segment that is neither first nor last in a chain of segments that comprise a multi-segment message. These segments only need the message-control information section of the message prefix.

Restriction: Because the client and server tokens are in the state-data section of the message prefix, they cannot be used to correlate and combine segmented messages. The transaction-pipe name and send-sequence numbers can be used for this purpose; they are in the message-control information section of the message prefix for each segment.

Last-in-chain (TMAMCLIC - X'20')

Specifies the last segment of a multi-segment message.

Discard chain (TMAMCCAN - X'10')

Specifies that the entire chain of a multi-segment message is to be discarded. The last-in-chain flag must also be set.

Prefix flag (TMAMCPFL)

Specifies the sections of the message prefix that are attached to the OTMA message. Every message must have the message-control information and state-data sections, but any combination of other sections can be sent with an OTMA message.

State data (TMAMCSTD - X'80')

Specifies that the message includes the state-data section of the message prefix.

Security data (TMAMCSEC - X'40')

Specifies that the message includes the security-data section of the message prefix.

User data (TMAMCUSR - X'20')

Specifies that the message includes the user-data section of the message prefix.

Application data (TMAMCAPP - X'10')

Specifies that the message includes the application-data section of the message prefix.

Send-sequence number (TMAMCSSN)

Specifies the sequence number for a transaction pipe. This sequence number is updated by the client and server when sending messages or transactions.

Recommendation: Increment the number separately for each transaction pipe.

This number can also be used to match an ACK or NAK message with the specific message being acknowledged.

Sense code (TMAMCSNS)

Specifies a 4-byte sense code that accompanies a NAK message. TMAMCSNS has two parts, a 2-byte sense code (TMAMCSNC) and a 2-byte reason code (TMAMCRSC). For an explanation of the codes returned in this field, see IMS Version 15.4 Messages and Codes, Volume 2: Non-DFS Messages.

Sense code (TMAMCSNC)

Specifies a 2-byte sense code that accompanies a NAK message. For an explanation of the codes returned in this field, see IMS Version 15.4 Messages and Codes, Volume 2: Non-DFS Messages.

Reason code (TMAMCRSC)

Specifies the 2-byte reason code that accompanies a NAK message. This code can further qualify a sense code.

Userid aging value (TMAMAGNG)

Specifies a 4-byte aging value in seconds for the input user ID. This field is different from the aging value specified in the OTMA client-bid command for OTMA connection. The aging value in the client-bid command sets the default aging value for all the OTMA user IDs; however, the Userid Aging Value overrides the default aging value for a specific user ID. If the Userid Aging Value is less than 300 seconds (5 minutes), IMS always creates a non-cached accessor environment element (ACEE).

Recoverable sequence number (TMAMCRSQ)

Specifies the recoverable sequence number for a transaction pipe. Incremented on every send of a recoverable message using a synchronized transaction pipe. Both the client and the server increment their recoverable send-sequence numbers and maintain them separately from the send-sequence number. Required for resynchronization only.

Segment sequence number (TMAMCSEQ)

Specifies the sequence number for a segment of a multi-segment message. This number must be updated for each segment, because messages are not necessarily delivered sequentially by XCF.

This number must have a value of 1 if the message has only one segment.

Resume tpipe requester ID (TMAMRTID)

The user ID of the client that is issuing the resume tpipe request.