IMS 15.2 - Communications and connections - OTMA state data fields used by IMS Connect

The numbered notes in each table are explained in Notes to OTMA header tables.

Server Available and Client Bid command format

Table 1. HWSOMHDR DSECT - OTMA state data header. State data common section for Server Available and Client Bid command format
Field	Length	Hexadecimal offset	Field value	Description and settings	Note
OMHDRLEN	2	0		STATE DATA LENGTH Set to State Data length.	1
OMHDRORG		2	State data for 'Server Available' and 'Client Bid' commands.
OMHDRONM	16	2		MEMBER NAME OF ORIGINATING SERVER. NEITHER TESTED NOR SET BY EXIT.	4
OMHDROMT	8	12		MEMBER TOKEN OF COMMAND ORIGINATOR. NEITHER TESTED NOR SET BY EXIT.	4
OMHDRDMT	8	1A		MEMBER TOKEN OF COMMAND DESTINATION. NEITHER TESTED NOR SET BY EXIT.	4
OMHDRUEN	8	22		UNRESOLVED DESTINATION EXIT NAME. NEITHER TESTED NOR SET BY EXIT.	4
OMHDRMBS	2	2A		XCF TRANSMISSION MAX BLOCKSIZE. NEITHER TESTED NOR SET BY EXIT.	4
OMHDRQUE	1	2C	OMHDRCMQ X'80'	CREATE HOLD MESSAGE QUEUE. NEITHER TESTED OR SET BY EXIT.	4
			X'40'	Reserved for OTMA Callable Interface. NEITHER TESTED OR SET BY EXIT.	4
			OMHDRICN X'20'	Reserved for IMS Connect Client Type. NEITHER TESTED OR SET BY EXIT.	4
			X'10'	Reserved Client Type.	3
			X'08'	Reserved Client Type.	3
OMHDRFL2	1	2D		CLIENT FLAGS.	3
			X'80'	OMHDRMXI - Specifies that OTMA limit the number of active messages that IMS can process concurrently. The maximum number is specified in the OMHDRTIB field.
			X'40'	Reserved
			X'20'	OMHDRTMO - CM1 connections time out if OTMA does not receive an ACK message in the interval specified in the OMHDRTO field.
			X'10'	OMHDRCSC – Set by IMS Connect to indicate that synchlevel=2 (syncpoint) transactions use RRS cascaded transaction support.
			X'08'	OMHDRSMI - This client is a member of the super member group specified in the OMHDRSMN field.
			X'04'	OMHDR2SY - This client processes synchronous callout messages from IMS application programs.
			X'02'	OMHDRTOQ - CM0 ACK Timeout Queue Name.
			X'01'	OMHDRITI - Set by IMS Connect to indicate that IMS Connect supports IMS-to-IMS TCP/IP communications for OTMA messages.
OMHDRUAV	4	2E		SAF USER ID TABLE AGING VALUE. NEITHER TESTED OR SET BY EXIT.	4
OMHDRHTS	4	32		MESSAGE RE-ASSEMBLY HASH TABLE SIZE. NEITHER TESTED OR SET BY EXIT.	4
OMHDRSMN	4	36
OMHDROSY	2	3A
OMHDRODE	2	3C		Offset to the OTMA destination descriptor in the user data section of the message prefix.
OMHDRTIB	2	3E
OMHDRFL3	1	40		Client bid flags
			X'80'	OMHDRRTY - MULTIRTP=Y is set for this connection. The tpipe supports multiple active resume tpipe requests.
			X'40'	OMHDRRTN - MULTIRTP=N is set for this connection. The tpipe supports only one active resume tpipe request at a time.
			X'10'	OMHDRSAY - SENDALTP=Y is set for this data store connection.
			X'08'	OMHDRSAN - SENDALTP=N is set for this data store connection.
OMHDRTO	1	41
OMHDRTQN	8	42
		2	ORG OMHDRORG

Resume output for single named TPIPE for the asynchronous option of NO OPTION selection

Table 2. HWSOMHDR DSECT - OTMA state data header. State data common section for resume output for single named TPIPE for the asynchronous option of NO OPTION selection
Field	Length	Hexadecimal offset	Field value	Description and settings	Note
OMHDCRSM_COUNT	2	2		NUMBER OF TPIPES IN THE ARRAY. Set to number of tpipes to retrieve output from a RESUME TPIPE call. Only valid value is one (1).	1
OMHDCRSM_TPIPEN	n	4		TPIPE ARRAY. Set to the name of the tpipe to retrieve output from a RESUME TPIPE call. Only one name is valid.	1
		2	ORG OMHDRORG

Resume output for single named TPIPE for options of NOAUTO, SINGLE, SINGLE with WAIT, and AUTO

Table 3. HWSOMHDR DSECT - OTMA state data header. State data common section for resume output for single named TPIPE for options of NOAUTO, SINGLE, SINGLE with WAIT, and AUTO
Field	Length	Hexadecimal offset	Field value	Description and settings	Note
OMHDRRHQ	1	2	Message return options for resume tpipe calls
			OMHDRRHQ_NOAUTO - X'00'	`NOAUTO -` Return all messages that are on the IMS queue when the call is received. Any messages received after the resume tpipe call is received are not sent. If no messages are on the queue, do not wait. Default option of HWSIMS00, HWSIMS01, HWSSMPL0, HWSSMPL1.	1
			OMHDRRHQ_AUTO1 - X'04'	`SINGLE with WAIT -` Return one message only from the queue. If no message is on the queue, wait and send the next message to arrive. This option requires that IRM_TIMER be set to X'E9' on ACK to IMS Connect from client, as an indication not to wait for any further output from IMS Connect.
			OMHDRRHQ_AUTO - X'02'	`AUTO -` Return all messages that are currently on the IMS queue. After all current messages are sent, wait and send each new message as it arrives. This option requires that IRM_TIMER be set to any value other than X'E9' on ACK to IMS Connect from client, as an indication to wait for next output from IMS Connect.	1
			OMHDRRQ_ONE - X'01'	`SINGLE -` Return one message only from the queue. If no messages are on the queue, cancel resume tpipe request. A new RESUME TPIPE Receive sequence is required to get any subsequent messages.	1
OMHDRRHQ_MODE	1	3	Processing mode for synchronous callout messages
			OMHDRRHQ_SYNC - X'80'	This client processes only synchronous callout messages.
			OMHDRRHQ_SYAS - X'40'	This client processes both synchronous callout messages and asynchronous messages
			OMHDRRHQ_CTLDATA - X'20'	This client supports callout messages containing control data.
			OMHDRRHQ_NWSE - X'10'	This client supports output messages that contain network security information.
OMHDCRHQ_TPIPEN	8	4		Tpipe name. Set to the name of the tpipe to retrieve output from a RESUME TPIPE call. Only one name is valid.	1
OMHDCRHQ_TPIPEN	8	2	ORG OMHDRORG

Transaction messages

Table 4. HWSOMHDR DSECT - OTMA state data header. State data common section for transaction messages
Field	Length	Hexadecimal offset	Field value	Description and settings	Note
OMHDRIST	1	2	OMHDRCNV X'80'	IMS STATE FLAG Conversational State.	2
			OMHDRRSP X'40'	Response Mode. Neither tested nor set by exit.	4
			OMHDRMHQ X'20'	Message from Hold Queue.
			OMHDRROT X'08'	Message rerouted
			OMHDRNWS X'02'	The output message for clients that issued a RESUME TPIPE call contains network security information in the security header.
			OMHDRXP1 X'01'	For input transaction messages, X'01' indicates that a transaction expiration time is provided in the user data section at the offset specified in OMHDRSXP
			OMHDRTOE X'01'	For resume tpipe requests and responses, X'01' indicates that a resume tpipe token is present in the OMHDRTKN field.
OMHDRSYN	1	3	OMHDRCTD X'80'	Control data is present in the application data section of the message. This value is set by OTMA on outbound synchronous callout requests.
			OMHDRCM0 X'40'	Commit Mode 0 Set if default for exit or the IRM requests Commit Mode 0, field IRM_F2 is set to "IRM_CMODE0."	1
			OMHDRCM1 X'20'	Commit Mode 1 Set if default for exit or the IRM requests Commit Mode 1, field IRM_F2 is set to "IRM_CMODE1."	1
			OMHDRNTX X'10'	Notify of transfer. NEITHER TESTED NOR SET BY EXIT.	4
			OMHDRSYC X'08'	This is a synchronous callout message.
			OMHDRI2I X'04'	Set by OTMA to indicate that this messages is destined for a remote IMS system by way of an IMS Connect to IMS Connect connection.
OMHDRSLV	1	4	OMHDRSL0 X'00'	SYNCH LEVEL Synchlevel=0 (None) Set if default for exit or the IRM requests synch level none, field IRM_F3 is not set to "IRM_CONFIRM." Synchlevel=0 is only valid for Commit Mode 1.	1
			OMHDRSL1 X'01'	Synchlevel=1 (Confirm) Set if default for exit or the IRM requests synch level confirm, field IRM_F3 is set to "IRM_CONFIRM." Synchlevel=1 is valid for Commit Modes 0 and 1.	1
			OMHDRSL2 X'02'	Synchlevel=2 (Syncpt) NEITHER TESTED NOR SET BY EXIT.
OMHDRCFL	1	5	OMHDRSOM X'80'	Set for SENDONLY. SENDONLY is indicated in the IRM from the client.	1
			OMHDRAGN X'40'	Specifies either: An aging value is in effect for the input message. This is a NAK response message to a synchronous callout message that instructs OTMA to retain the undelivered message on the tpipe hold queue until it is retrieved by another resume tpipe or the message times out.
			OMHDRRRQ X'20'	Set for REROUTE REQUEST for undeliverable CM0 output.
			OMHDRPND X'10'	Set for PURGE NOT DELIVERABLE. SENDONLY and PURGE NOT DELIVERABLE are mutually exclusive.
			OMHDREWC X'04'	Obsolete. EWLM is no longer supported by IMS. If this flag is specified, it is ignored by OTMA.
OMHDRMAP	8	6		MAP NAME If client application requested that the MODname be returned, then the exit must build an RRM in front of the data being returned to the client. The MODname (OMHDRMAP) would be moved to the RRM to field RRM_MODNAME by the exit.	1
OMHDRTOK	16	E		SERVER TOKEN. NEITHER TESTED NOR SET BY EXIT.	4
		ORG OMHDRTOK + 4
OMHDRSXP	2	12		OFFSET IN USER DATA PREFIX TO THE TRAN EXPIRATION UTC
OMHDRSXQ	2	14		Offset in the user data section at which OTMA placed the correlation token for this synchronous callout message. This offset is specified by IMS Connect and passed to OTMA in the OMHDROSY field in the client bid.
OMHDRUID	8	16		USERID RETURNED FOR RT REQ
OMHDRCOR	16	1E		CORRELATOR. NEITHER TESTED NOR SET BY EXIT.	4
		ORG OMHDRCOR + 8
OMHDRTIM	8	26		Time stamp correlator ID. On send and receive messages, this field contains the time stamp that is used to correlate responses to original input messages.
OMHDRTKN	8	2E		Resume tpipe token. On resume tpipe requests and associated responses, this field contains the resume tpipe token.
		ORG OMHDRTKN
OMHDRPDR	8	36		Program name for synchronous callout messages using DL/I ICAL.
OMHDRCID	16	2E		CONTEXT ID. NEITHER TESTED NOR SET BY EXIT.	4
OMHDRLTM	8	3E		OVERRIDE LTERM NAME. Set from IRM LTERM field "IRM_LTERM."	1
OMHDRLIU	2	46		LENGTH OF IMS HEADER USER DATA. Set to the user header data length that follows. The length of this field is not included in the total length.	5
OMHDRIUD	n	48		IMS HEADER USER DATA. Variable length, set by the user.	5
	ORG OMHDRTOK+4
OMHDRSXP	2	12	Offset at which the transaction expiration time is located in the user data section of the OTMA header	This field is set by IMS Connect	2

Resource state protocol command

The resource state protocol command is used by OTMA for two purposes: to notify the OTMA client about the current state of the IMS server resources or to send a heartbeat message to the client. IMS Connect currently ignores heartbeat messages.

The resource state protocol command is identified by X'3C' in the command type field (OMCTLTYP) of the message control information section of the OTMA header.

When IMS Connect receives a resource state protocol command, IMS Connect updates the exit interface block data store entry (HWSXIBDS with the information contained in the resource state protocol command message.

The following table summarizes the format of state data for the resource state protocol command. The summary includes byte, length, content, hexadecimal value, the meaning, and includes usage comments.

Table 5. HWSOMHDR DSECT - OTMA state data header. State data common section for resource state protocol command format
Content	Length	Dec offset	Hex offset	Value
OMHDRLEN	2	0	X'00'	Length of the state-data section, including the length field itself.
OMHDRSIM_STATUS	2	2	X'02'	The state of OTMA resources in the IMS system server. X'03' - Normal state IMS is available and processing messages normally. OTMA issues a normal state protocol command: When an OTMA client establishes a new tpipe connection When an OTMA client reestablishes a tpipe connection As a heartbeat message at 60 second intervals X'02' - Degraded state IMS is processing messages slowly. OTMA issues a degraded state protocol command when one or more conditions indicate that IMS is not processing messages as quickly as it should. X'01' - Unavailable state IMS can no longer accept messages for processing. OTMA issues the unavailable state protocol command to alert the OTMA client that one or more severe conditions prevent IMS from processing OTMA messages.
OMHDRSIM_SVRFLG1	1	4	X'04'	Reserved
OMHDRSIM_SVRFLG2	1	5	X'05'	Reserved
OMHDRSIM_SVRFLG3	1	6	X'06'	Reserved
OMHDRSIM_SVRFLG4	1	7	X'07'	Flags for resource in the fourth group of unavailable resources. X'01' - OMHDRSIM_S4FLOOD The server is flooded with OTMA messages that are waiting to be processed and is no longer available.
OMHDRSIM_WRNFLG1	1	8	X'08'	Flags for resources in the first group of degraded resources. X'80' - OMHDRSIM_W1FLOOD Global flood warning for all OTMA clients X'40' - OMHDRSIM_W1MTP Global tpipe warning. The total number of tpipes that are being monitored by OTMA on the server is equal to or greater than the highest specified limit for any one OTMA client.
OMHDRSIM_WRNFLG2	1	9	X'09'	Reserved
OMHDRSIM_WRNFLG3	1	10	X'0A'	Reserved
OMHDRSIM_WRNFLG4	1	11	X'0B'	Flags for resources in the fourth group of degraded resources. X'08' - OMHDRSIM_W5MTP The number of tpipes for this OTMA client has reached the maximum allowable number of tpipes set for this client on the MAXTP parameter of the OTMA client descriptor. No new tpipes can be created for this OTMA client until the number of tpipes drops. X'04' - OMHDRSIM_W4MTP The number of tpipes for this OTMA client has reached 80% of the maximum allowable number of tpipes set for this client on the MAXTP parameter of the OTMA client descriptor. X'02' - OMHDRSIM_AWE Message AWE reaches 80% flood. X'01' - OMHDRSIM_W4FLOOD Flood warning for this client only. The number of OTMA messages waiting to be processed on the server is at eighty percent of the maximum allowable number defined for the server.
OMHDRSIM_NRSFLGS	1	12	X'0C'	Other flags for non-resource related indicators. X'80' - OMHDRSIM_HB60S Identifies this message as a heartbeat message. The server is available and resource usage is within normal limits. Heartbeat messages are sent every 60 seconds.
Reserved	3	13	X'0D'
OMHDRSIM_SRVNAME	16	16	X'10'	The 16 character z/OS® cross-system coupling facility (XCF) member name of the OTMA server.
OMHDRSIM_CLTNAME	16	32	X'20'	The 16 character XCF member name of the OTMA client.
Reserved	20	48	X'30'
OMHDRSIM_UTC	12	68	X'44'	UTC time for this message