Transaction and callout messages
The state data for the transaction-related and synchronous callout request information in the OTMA message prefix is mapped by the TMAMHDR DSECT of the DFSYMSG macro.
The following table summarizes the format of state data for transaction-related and synchronous callout request information. The summary includes byte, length, content, hexadecimal value, and descriptions of the use of each field.
| Byte | Length | Content | Value | Description |
|---|---|---|---|---|
| 0 | 2 | Length | Specifies the total length of the state-data section of the message prefix, including the length field. | |
| 2 | 1 | Server state: specifies the mode in which the transaction is running. | X'80' | Conversational State: for a conversational transaction. Both the server and the client set this flag when sending conversational data. |
| X'40' | Set by the client for a commit-then-send (CM0) transaction. When this flag is set
for a commit-then-send transaction, if the IMS application does not reply to the IOPCB or complete a
message switch to another transaction, OTMA issues a DFS2082 message to the client, regardless of
the transaction response mode. This flag will be cleared when the SENDALTP function is activated. |
|||
| X'20' | From Hold Queue: specifies that the output message was sent from the IMS hold queue for the tpipe. The server initially sets this flag when sending a commit-then-send output message. The client also needs to set this flag when sending the subsequent ACK or NAK to IMS. |
|||
| X'10' | Hold queue capable: asynchronous output can be sent to hold queue. Set by the server. |
|||
| X'08' | Rerouted message: output has been rerouted. Set by the server when processing a rerouted output. |
|||
| X'04' | CM1 time out: a time out occurs for this CM1 output. Set by the server. |
|||
| X'02' | This value has different meanings for different message types. Transaction expiration: length of time: On transaction messages, when X'02' is specified, the transaction expiration function is enabled and submitted transactions expire after a specified length of time. The length of time is specified in the TMAMOSXP field. Network security information is included: On callout messages to clients that issued a RESUME TPIPE call, X'02' specifies that the message contains network security information in the security-data section. |
|||
| X'01' | This value has different meanings for different message types. Transaction expiration: point in time: On transaction messages from the client, X'01' enables the transaction expiration function and indicates that the submitted transaction expires at a specified point in time. Specify the point in time in STCK format in the user data prefix. Specify the byte offset of the time specification at byte 22 (the TMAMOSXP field) of the state data for transaction messages. Resume tpipe token included: For messages sent by the server from a tpipe hold queue, X'01' signifies that the output message includes a resume tpipe token at byte 48 (TMAMRTOK) in the OTMA state data prefix. |
|||
| 3 | 1 | Synchronization or callout flag: specifies either the commit mode of a transaction or that a message is a synchronous callout request. | X'80' | TMAMHCTD: This callout message has control data in the application data section of the message. |
| X'40' | Commit-then-send: a commit-then-send (CM0)
transaction. The server commits output before sending it to the client. |
|||
| X'20' | Send-then-commit: a send-then-commit (CM1) transaction.
The server sends output to the client before committing it. |
|||
| X'10' | SendOnly ACK no msg resp: for response messages to synchronous callout requests, which are sent to OTMA with the Send Only with ACK protocol, this value indicates that the ACK to the response message does not include the response data also. | |||
| X'08' | Callout message with a correlator token: This flag is on for a synchronous callout message with a correlator token or an asynchronous callout message with a correlator token. For an asynchronous callout message, an additional flag X'01' in byte 3 of control data prefix is also on. | |||
| X'04' | IMS-to-IMS TCP/IP communications message: Set by IMS Connect to indicate that IMS Connect supports IMS-to-IMS TCP/IP communications. | |||
| X'02' | Need dump for transaction expiration: Set by client to request a symptom dump and a DFS554A message if this transaction expires on the IMS input queue before an application issues a GU call to retrieve it. | |||
| X'01' | Send SQ BE ALTPCB msg to FE IMS:: Set by the client to request that the output generated on a back-end IMS system in a shared queues environment be returned to the client via the front-end IMS system. | |||
| 4 | 1 | Synchronization level: specifies the
transaction synchronization level; that is, the way in which the client and an IMS application program interact for program output
messages. The default is Confirm, in which IMS always requests a response when sending commit-then-send output to a client. |
X'00' | None: specifies that the programs participate in coordinated commit
processing on resources updated during the conversation under the z/OS®
Resource Recovery Services recovery platform. The server application program does not request an ACK message when it sends output to a client. None is only valid for send-then-commit transactions. |
| X'01' | Confirm: specifies that synchronization is requested. The server sends
transaction output with the response flag set to Confirm can be used for either commit-then-send or send-then-commit transactions. |
|||
| X'02' | Syncpt: specifies that the programs participate in coordinated commit
processing on resources updated during the conversation under the RRS recovery platform. A conversation with this level is also called a protected conversation and the resources updated under this conversation use the two-phase commit protocol. |
|||
| 5 | 1 | Client flags: specifies optional processing requested by the client. | X'80' | Send Only Message: this is a send only message; the response is placed on
the hold queue. This flag is valid only if the client requested a hold queue during open. |
| X'40' | Aging Value or NAK message for callout If specified for the aging value, this flag instructs IMS to accept the accessor environment element (ACEE) aging value specified at byte 20 of the message control information. If specified on a NAK response to a synchronous callout message, OTMA keeps the callout message on the queue until it is retrieved by another resume tpipe call or the callout message times out. |
|||
| X'20' | Reroute Request: reroute requested. Setting this flag reroutes CM0 output to the destination that is specified in the Destination Override field. |
|||
| X'10' | Purge CM0 IOPCB output: when CM0 IOPCB output cannot be delivered to the
client, delete it. Set by the client in the input message. |
|||
| X'08' | Enable message level time out: enable the timeout value specified in the
message-control information section. This timeout value only applies to this particular CM1 message. If there is no message level time out specified, the member level timeout value is used. |
|||
| X'04' | Obsolete. EWLM is no longer supported by IMS. If this flag is specified, it is ignored by OTMA. | |||
| X'02' | Ignore PURG Calls: for commit then send (CM0) messages that generate
multiple PURG calls in the TP PCB, when this optional flag is set, IMS ignores the PURG calls so that the OTMA client application receives one response CM0
message with multiple output segments. When this flag is not set, if there are multiple ISRT and PURG calls on the TP PCB for a CM0 message, the OTMA client application receives multiple response messages. This flag is applies only to CM0 input messages. If this flag is specified in a CM1 input message, IMS resets the flag and ignores it for any remaining program-to-program switches and ALT-PCB processing. |
|||
| X'01' | Send only ordered: identifies the protocol as send only with serial
delivery. When the SENDALTP function is activated and an ALTPCB output is sent to an IMS Connect client, this flag is set on the output message for serviceability. |
|||
| 6 | 8 | Map name | Specifies the formatting map used by the server to map
input or output data streams (for example, 3270 data streams). Although OTMA does not provide MFS support, you can use the map name to define the output data stream. The name is an 8-byte MOD name that is placed in the I/O PCB. IMS replaces this field in the prefix with the map name in the I/O PCB when the message is inserted. The map name is optional. |
|
| 14 | 16 | Server token | For CM1 messages, the server sets the server token for correlation purposes. After receiving a CM1 output message from the server, the client must return the server token on the following acknowledgment (ACK or NAK) or conversational iteration. | |
| Alternate mapping for bytes 14 through 29 when server token is not specified or not relevant | ||||
| 14 | 4 | Super member name | On output from ALTPCB, specifies the super member name for the OTMAYPRX user exit and DFSYDRU0 exit routine. | |
| 18 | 2 | Transaction expiration value or offset |
If the server state flag is set to X'02' (TMAMTXP2), this field contains the length of time in seconds after which the input transaction expires. If the server state flag is set to X'01' (TMAMTXP1), this field contains the offset to the point in time specification, in STCK format, in the user data prefix. This field cannot be used for CM1 conversational iterations. |
|
| 20 | 2 | Offset to correlation token for synchronous callout messages |
Specifies the offset in the user data section at which the client can find the correlation token in a synchronous callout message. This value should match the offset specified by the client in the TMAMOSYN field of the state data in the client bid message. |
|
| 22 | 8 | Resume tpipe user ID |
Specifies the user ID of the client who issues the RESUME TPIPE request. |
|
| End of alternate mapping for bytes 14 through 29 | ||||
| 30 | 16 | Correlation token |
A client token to correlate input with output. This token is optional and is not used by the server. Recommendation: Use this token to help clients manage their
transactions.
|
|
| 46 | 16 | CM1 context ID | On input transaction messages sent by the client, specifies the RRS token that is used with SYNCLVL=02 and protected conversations. | |
| Alternate mapping for bytes 46 through 61 when CM1 context ID is not used | ||||
| 46 | 8 | Resume tpipe token | On output messages sent by the server from the tpipe hold queue, this field contains the resume tpipe request token. | |
| 54 | 8 | Time received from XCF | In the message returned to a client after a transaction has expired, this field contains the time that the expired transaction was received by IMS from XCF. | |
| End of alternate mapping for bytes 46 through 61 | ||||
| 54 | 8 | Program name for callout | In an IMS synchronous callout message which is sent from an IMS dependent region, this field identifies the program that makes the DL/I ICAL call. | |
| 62 | 8 | Destination override | Specifies an LTERM name used to override the LTERM name
in the IMS application program's I/O PCB. This override is used if the client does not want to override the LTERM name in the I/O PCB with the transaction-pipe name. This optional override is not used if it begins with a blank. |
|
| 70 | 2 | Server user data length | Specifies the length of the server user data, if
any. The maximum length of the server user data is 256 bytes. The server user data length is not included in the length calculation. |
|
| 72 | * | Server user data | Specifies any data needed by the server. If included in a transaction message by the client, it is returned by the server in the output data messages. Variable length. Optional. |
|