Message-control information section

For every OTMA message, you must provide message-control information in the first section of the OTMA message prefix.

The message-control information section is mapped by the TMAMCTL DSECT of the DFSYMSG macro.

The following table is a summary of the content of the message-control information section of the message prefix (column 1 from the table in OTMA message prefix). The summary includes byte, length, content, hexadecimal value, the meaning, and includes usage comments.

Table 1. Format of the message-control information section of the OTMA message prefix
Byte Length Content Value Meaning
0 1 Architecture level X'01' OTMA release level. This is mandatory for all messages.
1 1 Message type: A specification in this field is mandatory for all messages. X'80' Data: Server output data (output from an IMS application program). This data is not a transaction.
X'40' Transaction: Transaction or IMS command input to the server. The actual transaction name is specified in the application-data section of the prefix.
X'20' Response: A response message.
X'10' Protocol command: An OTMA protocol command (not an IMS command). See Protocol command type below at byte offset 4.
X'08' Commit Confirmation: Commit complete. Used by the server to notify the client of sync point completion. Only used for send-then-commit transactions. See commit-confirmation flag below.
X'04' Synchronous program switch: A synchronous program switch request.
2 1 Response flag: Values in the response flag field are mutually exclusive. X'80' ACK: Positive acknowledgment.
X'40' NAK: Negative acknowledgment. A NAK can be accompanied by an additional sense code.
X'20' Response Requested: A response is requested for this message.
X'10' Extended Response Requested: Requests architected transaction or command attributes to be returned to the client.
X'08' Response to a synchronous callout request: This message is a response to a synchronous callout request that was issued by an IMS application program.
X'04' The input transaction expired before GU call: Set by the server, this flag indicates that the input transaction timed out on the IMS input queue before an IMS application could issue a GU call to retrieve it.
X'02' Support for delayed ACK or NAK response: The OTMA client sets this flag to instruct OTMA to send a NAK to the client if OTMA receives a late or invalid ACK/NAK from the client.
X'01' Return input message on transaction expiration: Set by the client to request that, if a transaction times out before processing by IMS, OTMA returns the original input message to the client instead of message DFS3588I.
3 1 Commit-confirmation and other flags X'80' Committed: Server committed successfully.
X'40' Aborted: Server aborted commit.
X'08' Aborted due to the OTMA timeout condition: Indicates that an ACK or NAK response from the OTMA client was not received before the timeout limit was reached.
X'04' SENDALTP function activated for IMS Connect commit-then-send messages.
4 1 Protocol command type X'04' Client-Bid: Sent by a client to the server. The response-requested flag and the appropriate state data fields (for example, Member Name) must also be set.
X'08' Server Available: Sent by the server to a client. The appropriate state data fields (for example, Member Name) must also be set.
X'0C' CBresynch: Sent by a client to the server to request a resynchronization. This client-bid request with resynchronization to follow is optional, and causes the server to send an SRVresynch command to the client.
X'14' Suspend Processing for All Tpipes: The server sends this command to suspend all message activity with the client.
X'18' Resume Processing for All Tpipes: The server sends this command to resume message processing with the client.
X'1C' Suspend Input for Tpipe: The server sends this command when it is overloaded.
X'20' Resume Input for Tpipe: The server sends this command when it is ready for client input (following a Suspend Input for tpipe command).
X'24' Resume output for tpipe: Sent by a client to the server to request queued tpipe output be resent.
X'26' Resume output for all tpipes: 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.
X'28' Resume output for the hold queue for tpipe: Sent by a client to the server to request messages from the hold queue for tpipe.
X'29' Cancel resume tpipe request: 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.
X'2A' No messages on tpipe hold queue: Sent by the server to the client when a resume tpipe request is received and the tpipe hold queue is empty.
X'2C' SRVresynch: Sent by the server to a client who has sent a CBresynch. This command identifies all synchronized tpipes within the server.
X'30' REQresynch: Sent by the server to a client to specify the state of a synchronized tpipe.
X'34' REPresynch: Sent by a client to the server to indicate the type of resynchronization to be performed by the server.
X'38' TBresynch: Sent by a client to the server to initiate resynchronization for a particular tpipe.
X'3C' Server state: Sent by the server to the client with the current status of server processing. The client can use this information to redirect transactions to a different server if server processing slows.
Table 2. Format of the message-control information section of the OTMA message prefix
Byte Length Content Value Meaning
5 1 Processing flag X'80' Resume Tpipe token: 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.

For output messages, this flag indicates that the suspended processing for all tpipes (TMAMCSPA) is due to IMS shutdown. This is only an output flag.
X'40' Synchronized Tpipe: Input and output sequence numbers are maintained for the transaction pipe.
X'20' Asynchronous output: The server is sending unsolicited queued data messages.
X'10' Error Message Follows: An error data message follows. Set by the server when sending a NAK.
X'08' Message in Hold Queue: One or more messages in the hold queue for tpipe. Not available for shared queues.
X'02' Extra info set. For a RESUME TPIPE request, see byte 24 of the message-control information of the OTMA message prefix for the RESUME TPIPE ID info. For a callout message, see byte 22 in the transaction and callout messages of the state data section prefix of the OTMA message prefix for the RESUME TPIPE ID info.
X'01' Error Message Sent: An error message was sent as a CM1 response. A CM1 transaction generated an error message as the only response.
Table 3. Format of the message-control information section of the OTMA message prefix
Byte Length Content Value Meaning
6 8 Tpipe name   OTMA identification and processing control token. This name is used to override the LTERM name on the I/O PCB for an IMS application program.
14 1 Chain flag This flag is mandatory for multi-segment messages. X'80' First-In-Chain: The first segment of a multi-segment message. A message of only one segment is indicated by setting both the first-in-chain and last-in-chain flags.
X'40' Middle-In-Chain: Part of a multi-segment message.
X'20' Last-In-Chain: The last segment of a multi-segment message.
X'10' Discard Chain: Discard the current chain of message segments.
15 1 Prefix flag The value of this field indicates which sections of the message prefix are attached to this message. X'80' State Data: The state-data section is included with the message. State data section is mandatory for each message.
X'40' Security: The security section is included with the message.
X'20' User Data: The user-data section is included with the message. This data is specified by an OTMA client.
X'10' Application Data: The application-data section is included with the message.
16 4 Send-sequence number   The sequence number for the transaction pipe. Incremented on every send for each transaction pipe.
20 4 Sense code    
  ORG to byte offset 20 (TMAMCSNS)
20 2 Sense code   Accompanies a NAK message.
22 2 Reason code   Accompanies a NAK message.
  ORG to byte offset 20 (TMAMCSNS)
20 4 Aging value   Specifies the accessor environment element (ACEE) aging value, in seconds. IMS creates an ACEE if the age of the current ACEE is greater than this value.

The aging value specifies how often the cached user ID ACEE should be refreshed. The aging value flag, X'40', must also be set in byte 5 of the State Data. This value does not apply to an ACK or NAK message.

The minimum value for caching support is 300 seconds (5 minutes). If the aging value specified is less than the minimum, IMS always creates a non-cached ACEE.
24 4 Recoverable sequence number   The recoverable sequence number for the transaction pipe. Incremented on every send of a recoverable message using a synchronized transaction pipe. Required for resynchronization only.
28 2 Segment sequence number   Sequence number for segments of a multi-segment OTMA message.
30 1 CM1 ACK Timeout 1 to 255 Specifies a message level timeout value in seconds for this message.
31 1 Reserved   Applies only to send-then-commit messages when synclevel=confirm or synclevel=syncpt.

Sets a message level timeout value for this transaction only. The value cannot be greater than the timeout value set in OTMA; otherwise, the value is ignored.

The time out value is set in OTMA either by the /START TMEMBER command or the OTMA client descriptor.
Number of control data segments 1 to 255 Specifies the number of control data segments when TMAMHCTD is set in the state data. This field is used only when IMS sends an ICAL callout message with control data.
  ORG to byte offset 24 (TMAMCRSQ)
24 8 Resume tpipe requester ID