The INQUIRE_TRANSACTION call

The INQUIRE_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to obtain information about a transaction that is attached (task). In general, this call is equivalent to the EXEC CICS® INQUIRE TASK command, with some minor differences.

INQUIRE_TRANSACTION

DFHXMIQX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_TRANSACTION),
       [TRANSACTION_TOKEN(name8),]]
       [OUT,
       [ATTACH_TIME(name8),]
       [CICS_UOW_ID(name8),]
       [DTIMEOUT(name4 | (Rn)),]
       [DYNAMIC(name1),]
       [FACILITY_NAME(name4),]
       [FACILITY_TYPE(name1),]
       [INITIAL_PROGRAM(name8),]
       [NETNAME(name8),]
       [ORIGINAL_TRANSACTION_ID(name4),]
       [OUT_TRANSACTION_TOKEN(name8),]
       [RE_ATTACHED_TRANSACTION(name1),]
       [REMOTE(name1),]
       [REMOTE_NAME(name8),]
       [REMOTE_SYSTEM(name4),]
       [RESOURCE_NAME(name16),]
       [RESOURCE_TYPE(name8),]
       [RESTART(name1),]
       [RESTART_COUNT(name2 | (Rn)),]
       [SPURGE(name1),]
       [START_CODE(name1),]
       [STATUS(name1),]
       [SUSPEND_TIME(name4 | (Rn)),]
       [SYSTEM_TRANSACTION(name1),]
       [TASK_PRIORITY(name1),]
       [TCLASS(name1),[TCLASS_NAME(name8),]]
       [TERMINATE_PROTECTED(name1),]       [TPURGE(name1),]
       [TRANNUM(name4 | string | ‘string'),]
       [TRAN_PRIORITY(name1),]
       [TRAN_ROUTING_PROFILE(name8),]
       [TRANSACTION_ID(name4),]
       [USERID(name8),]
       RESPONSE (name1 | *),
       REASON (name1 | *)]

This command is threadsafe.

The descriptions of the following parameters are the same as the corresponding parameters on the INQUIRE_TRANDEF function call.

DTIMEOUT
DYNAMIC
INITIAL_PROGRAM
REMOTE
REMOTE_NAME
REMOTE_SYSTEM
RESTART
SPURGE
STATUS
TCLASS
TRAN_ROUTING_PROFILE
TRANSACTION_ID

The parameter descriptions that follow explain briefly the possible values that can be returned on an INQUIRE_TRANSACTION call. For a more detailed explanation of these parameters, see the corresponding parameter descriptions for the TRANSACTION resource definition in TRANSACTION attributes.

ATTACH_TIME(name8)

returns the time in milliseconds since the task was attached.

name8: The name of an 8-byte location to receive the time, in packed decimal ABSTIME format.

CICS_UOW_ID(name8)

returns the CICS unit of work identifier for the task.

name8: The name of an 8-byte location to receive the unit of work id.

FACILITY_NAME(name4)

returns the name of the principal facility associated with the task.

name4: The name of a 4-byte location to receive the name of the principal facility.

FACILITY_TYPE(name1)

returns, in a 1-byte location (name1), an equated value indicating the type of principal facility associated with the task.

XMIQ_NONE: There is no principal facility.
XMIQ_START: The principal facility is an interval control element.
XMIQ_TD: The principal facility is a transient data queue.
XMIQ_TERMINAL: The principal facility is a terminal.

NETNAME(name8)

returns the network name of the principal facility associated with this task.

name8: The name of an 8-byte location to receive the network name.

ORIGINAL_TRANSACTION_ID(name4)

returns the transaction id that was used to attach the transaction. For example, if an alias was used at a terminal, this field returns the alias.

name4: The name of a 4-byte location to receive the name of the original transaction identifier.

OUT_TRANSACTION_TOKEN(name8)

returns the token that represents the task.

name8: The name of an 8-byte location to receive the transaction token for the task.

RE_ATTACHED_TRANSACTION(name1)

returns, in a 1-byte location (name1), an equated value indicating whether the transaction has been re-attached.

XMIQ_NO: The transaction has not been re-attached and the global user exit program is invoked in the same environment as the original transaction-attach.
XMIQ_YES: The transaction has been re-attached and the global user exit program is invoked in a different environment from the original transaction-attach.

RESOURCE_NAME(name16)

returns the name of a resource that the (suspended) transaction waiting for.

name16: The name of an 16-byte location to receive the name of the resource on which the transaction is waiting.

RESOURCE_TYPE(name8)

returns the type of resource that the (suspended) transaction waiting for.

name8: The name of an 8-byte location to receive the type of resource on which the transaction is waiting.

RESTART_COUNT(name2 | (Rn))

returns the number of times this instance of the transaction has been restarted.

name2: The name of a 2-byte location to receive the number of times the transaction has been restarted, expressed as a half-word binary value.
(Rn): A register to receive the number of times the transaction has been restarted, expressed as a half-word binary value.

START_CODE(name1)

returns, in a 1-byte location (name1), an equated value indicating how the task was started:

C: A CICS internal attach.
XMIQ_DF: The start code isn't yet known—to be set later.
XMIQ_QD: A transient data trigger level attach.
XMIQ_S: A START command without any data.
XMIQ_SD: A START command with data.
XMIQ_SZ: A front end programming interface (FEPI) attach.
XMIQ_T: A terminal input attach.
XMIQ_TT: A permanent transaction terminal attach.

SUSPEND_TIME(name4 | (Rn))

returns the length of time that the task has been in its current suspended state.

name4: The name of a 4-byte location to receive the number of seconds, rounded down, the task has been suspended, expressed as a binary value.
(Rn): A register to receive the number of seconds, rounded down, the task has been suspended, expressed as a binary value.

SYSTEM_TRANSACTION(name1)

returns, in a 1-byte location (name1), an equated value indicating whether the task is CICS system task.

XMIQ_NO: The task is not a CICS system task.
XMIQ_YES: The task is a CICS system task.

TASK_PRIORITY(name1)

returns the combined task priority, which is the sum of the priorities defined for the terminal, transaction, and operator.

name1: The name of a 1-byte location to receive the task priority, expressed as a binary number.

TERMINATE_PROTECTED(name1)

returns, in a 1-byte location (name1), an equated value indicating whether the transaction can be killed.

XMIQ_NO: The transaction can be killed.
XMIQ_YES: The transaction cannot be killed.

TRANNUM(name4)

returns the task number of the transaction.

name4: The name of a 4-byte location to receive the task number.

TRANSACTION_TOKEN(name8)

specifies the transaction token for the task being inquired upon. This parameter is optional, and if omitted, the current task is assumed.

If you issue this call within an XXMATT global user exit program, the current task may be a CICS system task. To inquire on the user task for which XXMATT is invoked, you must specify the transaction token passed on the XXMATT exit-specific parameter list.

name8: The name of an 8-byte location that contains the transaction token.

USERID(name8)

returns the userid associated with this task.

name8: The name of an 8-byte location to receive the userid.

RESPONSE and REASON values for INQUIRE_TRANSACTION

RESPONSE	REASON
OK	None
DISASTER	ABEND
	LOOP
INVALID	None
EXCEPTION	NO_TRANSACTION_ENVIRONMENT
	BUFFER_TOO_SMALL
	INVALID_TRANSACTION_TOKEN
KERNERROR	None