Transaction management XPI functions

This section describes the transaction management XPI calls.

The INQUIRE_CONTEXT call

INQUIRE_CONTEXT returns information about the environment in which a transaction is running. Specifically, it provides information for transactions running in a bridge environment.

INQUIRE_CONTEXT

DFHBRIQX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_CONTEXT),]
       [OUT,
       [CONTEXT(byte1),]
       [BRIDGE_TRANSACTION_ID(name4),]
       [BRIDGE_EXIT_PROGRAM(name8),]
       [BFB_TOKEN(name4),]
       [BRXA_TOKEN(name4),]
       [FACILITYTOKEN(name8),]
       [START_TYPE(byte1),]
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

BFB_TOKEN(name4)
returns a pointer that contains the address of the bridge facility used by this task. Although the bridge facility is not a real terminal, it is represented by a data structure that has the same format as a TCTTE and can be mapped using the DSECT DFHTCTTE. If CONTEXT returns NORMAL, the contents of this field are meaningless.
Note:
In earlier releases of CICS®, this field was called BRIDGE_FACILITY_TOKEN.
name4
The name of a 4-byte location to receive the token.
BRIDGE_EXIT_PROGRAM(name8)
returns the name of the bridge exit program used by this task. If CONTEXT returns NORMAL, the contents of this field are meaningless.
name8
The name of an 8-byte location to receive the name of the bridge exit program.
BRIDGE_TRANSACTION_ID(name4)
returns the name of the bridge monitor transaction that issued a START BREXIT TRANSID command to start this transaction. If CONTEXT returns NORMAL, the contents of this field are meaningless.
name4
The name of a 4-byte location to receive the name of the bridge monitor transaction.
BRXA_TOKEN(name4)
returns a token that contains the address of the bridge exit area (BRXA) used by this task. The BRXA is not applicable to the Link3270 bridge (START_TYPE=BRIQ_LINK). The format of BRXA is defined by the DFHBRARx copy books. If CONTEXT returns NORMAL, the contents of this field are meaningless.
name4
The name of a 4-byte location to receive the token.
CONTEXT(byte1)
returns, in a 1-byte location (byte1), the type of environment in which the transaction is running.
BRIDGE
A user transaction that was started using a bridge
BREXIT
A bridge exit program
NORMAL
A transaction that is not running in a bridge environment.
FACILITYTOKEN(name8)
returns the facilitytoken ( an identifier associated with the bridge facility). If CONTEXT returns NORMAL, the contents of this field are meaningless.
name8
The name of an 8-byte location to receive the facilitytoken.
START_TYPE(byte1)
returns, in a 1-byte location (byte1), an indication of how the 3270 bridge was started. If CONTEXT returns NORMAL, the contents of this field are meaningless.
BRIQ_START
The bridge was started using START BREXIT.
BRIQ_LINK
The bridge was started using the Link3270 mechanism.

RESPONSE and REASON values for INQUIRE_CONTEXT:

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

The INQUIRE_DTRTRAN call

INQUIRE_DTRTRAN returns the name of the dynamic transaction routing (DTR) transaction definition.

The DTR transaction definition provides common attributes for transactions that are to be dynamically routed and which do not have a specific transaction definition. It is specified on the DTRTRAN system initialization parameter; the CICS-supplied default definition is CRTX.

INQUIRE_DTRTRAN

DFHXMSRX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_DTRTRAN),]
       [OUT,
       DTRTRAN(name4),
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

DTRTRAN(name4)
returns the name of the DTR transaction definition to used for routing transactions that are not defined by an explicit transaction resource definition.
name4
The name of a 4-byte location that is to receive the name of the DTR transaction definition. If 'NO' was specified on the DTRTRAN system initialization parameter, 'NO' will be placed in this field.

RESPONSE and REASON values for INQUIRE_DTRTRAN:

RESPONSE REASON
OK None
DISASTER ABEND
LOGIC_ERROR
LOOP
INVALID INVALID_FUNCTION
KERNERROR None
PURGED None

The INQUIRE_MXT call

The INQUIRE_MXT function is provided on the DFHXMSRX macro call. Its purpose is to provide current value of the MXT parameter.

INQUIRE_MXT

DFHXMSRX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_MXT),]
       [OUT,
       CURRENT_ACTIVE(name4 | (Rn) ),
       MXT_LIMIT(name4 | (Rn)),
       MXT_QUEUED(name4 | (Rn) ),
       TCLASS_QUEUED(name4 | (Rn) ),
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

CURRENT_ACTIVE(name4 | (Rn))
returns the current number of all active user tasks.
name4
The name of a 4-byte location that is to receive the current number of active user tasks, expressed as a binary value.
(Rn)
A register to receive the current number of active user tasks, expressed as a binary value.
MXT_LIMIT(name4 | (Rn))
returns the current number of the MXT parameter.
name4
The name of a 4-byte location that is to receive the maximum number of all user tasks currently allowed, expressed as a binary value.
(Rn)
A register to receive the maximum number of all tasks currently allowed, expressed as a binary value.
MXT_QUEUED(name4 | (Rn))
returns the current number of user transactions that are queued as a result of the maximum tasks (MXT) being reached.
name4
The name of a 4-byte location that is to receive the current number of queued user tasks, expressed as a binary value.
(Rn)
A register to receive the current number of queued user tasks, expressed as a binary value.
TCLASS_QUEUED(name4 | (Rn))
returns the current number of all transactions that are queued for transaction class membership.
name4
The name of a 4-byte location that is to receive the current number of queued transaction class members, expressed as a binary value.
(Rn)
A register to receive the current number of queued transaction class members, expressed as a binary value.

RESPONSE and REASON values for INQUIRE_MXT:

RESPONSE REASON
OK None
DISASTER LOGIC_ERROR
ABEND
LOOP
INVALID INVALID_FUNCTION
KERNERROR None
PURGED None

The INQUIRE_TCLASS call

The INQUIRE_TCLASS function is provided on the DFHXMCLX macro call. Its purpose is to provide current information about the specified transaction class (TCLASS).

INQUIRE_TCLASS

DFHXMCLX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_TCLASS),
       INQ_TCLASS_NAME(name8 | string | ‘string’),]
       [OUT,
       [CURRENT_ACTIVE(name4 | (Rn)),]
       [CURRENT_QUEUED(name4 | (Rn)),]
       [MAX_ACTIVE(name4 | (Rn)),]
       [PURGE_THRESHOLD(name4 | (Rn)),]
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

CURRENT_ACTIVE(name4 | (Rn))
returns the current number of active user tasks in this transaction class.
name4
The name of a 4-byte location that is to receive the current number of active user tasks for this transaction class, expressed as a binary value.
(Rn)
A register to receive the current number of active user tasks for this transaction class, expressed as a binary value.
CURRENT_QUEUED(name4 | (Rn))
returns the current number of queued user tasks.
name4
The name of a 4-byte location that is to receive the current number of queued user tasks in this transaction class, expressed as a binary value.
(Rn)
A register to receive the current number of queued user tasks, expressed as a binary value.
INQ_TCLASS_NAME(name8 | string | ‘string’)
specifies the name of the transaction class for this inquiry.
name8
The name of an 8-byte location that contains the name of the transaction class being inquired on.
string
A string of characters, without intervening blanks, naming the transaction class.
‘string’
A string of characters, within quotation marks, naming the transaction class. The string length is set to 8 by padding with blanks within the quotation marks.
MAX_ACTIVE(name4 | (Rn))
returns the current maximum number of active tasks allowed for the transaction class.
name4
The name of a 4-byte location that is to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value.
(Rn)
A register to receive the current maximum number of active tasks currently allowed for this transaction class, expressed as a binary value.
PURGE_THRESHOLD(name4 | (Rn))
returns the purge threshold limit for this transaction class.
name4
The name of a 4-byte location that is to receive the current purge threshold limit for this transaction class, expressed as a binary value.
(Rn)
A register to receive the current purge threshold limit for this transaction class, expressed as a binary value.

RESPONSE and REASON values for INQUIRE_TCLASS:

RESPONSE REASON
OK None
DISASTER LOGIC_ERROR
INVALID None
EXCEPTION UNKNOWN_CLASS

The INQUIRE_TRANDEF call

The INQUIRE_TRANDEF function is provided on the DFHXMXDX macro call. Its purpose is to allow you to obtain information about the specified transaction definition. In general, this function call is equivalent to the EXEC CICS INQUIRE TRANSACTION command, with some differences.

INQUIRE_TRANDEF

DFHXMXDX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_TRANDEF),
       INQ_TRANSACTION_ID(name4 | string | ‘string’),]
       [OUT,
       [BREXIT(name8),]
       [CMDSEC(name1),]
       [DTIMEOUT(name4 | (Rn)),]
       [DUMP(name1),]
       [DYNAMIC(name1),]
       [INDOUBT(name1),]
       [INDOUBT_WAIT(name1),]
       [INDOUBT_WAIT_TIME(name4),]
       [INITIAL_PROGRAM(name8),]
       [ISOLATE(name1),]
       [LOCAL_QUEUING(name1),]
       [OTSTIMEOUT(name4 | (Rn)),]
       [PARTITIONSET(name1),]
       [PARTITIONSET_NAME(name8),]
       [PROFILE_NAME(name8),]
       [REMOTE(name1),]
       [REMOTE_NAME(name8),]
       [REMOTE_SYSTEM(name4),]
       [RESSEC(name1),]
       [RESTART(name1),]
       [ROUTABLE_STATUS(ROUTABLE|NOT_ROUTABLE),]
       [RUNAWAY_LIMIT(name4 | (Rn)),]
       [SHUTDOWN(name1),]
       [SPURGE(name1),]
       [STATUS(name1),]
       [STORAGE_CLEAR(name1),]
       [STORAGE_FREEZE(name1),]
       [SYSTEM_ATTACH(name1),]
       [SYSTEM_RUNAWAY(name1),]
       [TASKDATAKEY(name1),]
       [TASKDATALOC(name1),]
       [TCLASS(name1),[TCLASS_NAME(name8),]]
       [TPURGE(name1),]
       [TRACE(name1),]
       [TRAN_PRIORITY(name4 | (Rn)),]
       [TRAN_ROUTING_PROFILE(name8),]
       [TRANSACTION_ID(name4),]
       [TWASIZE(name4 | (Rn)),]
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

The following parameter descriptions explain briefly the possible values that can be returned on an INQUIRE_TRANDEF call. For a more detailed explanation of some of these parameters, see the corresponding parameter descriptions for the TRANSACTION resource definition in the CICS Resource Definition Guide.

BREXIT(name8)
returns the name of the default bridge exit program specified for the named transaction. If no bridge exit is specified, blanks are returned.
name8
The name of an 8-byte location to receive the name of the bridge exit program.
CMDSEC(name1)
returns, in a 1-byte location (name1), an equated value indicating whether command security checking is required for the transaction.
XMXD_YES
Command security checking is required.
XMXD_NO
Command security checking is not required.
DTIMEOUT(name4)
returns the deadlock time-out value for the transaction.
name4
The name of a 4-byte location that is to receive the deadlock time-out value, expressed as a binary value.
(Rn)
A register to receive the deadlock time-out value, expressed as a binary value.

Note that a value of zero means that the transaction resource definition specifies DTIMOUT(NO).

DUMP(name1)
returns, in a 1-byte location (name1), an equated value indicating whether CICS is to take a transaction dump if the transaction abends.
XMXD_YES
A transaction dump is required.
XMXD_NO
A transaction dump is not required.
DYNAMIC(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined for dynamic transaction routing.
XMXD_YES
The transaction is to be dynamically routed to a remote CICS.
XMXD_NO
The transaction is not to be dynamically routed.
INDOUBT(name1)
returns, in a 1-byte location (name1), an equated value indicating the action to be taken if the CICS region fails or loses connectivity with its coordinator while a unit of work is in the in-doubt period. (The action is based on the ACTION attribute of the TRANSACTION resource definition.)

The action is dependent on the values returned in INDOUBT_WAIT and INDOUBT_WAIT_TIME; if INDOUBT_WAIT returns XMXD_YES, the action is not taken until the time returned in INDOUBT_WAIT_TIME expires.

XMXD_BACKOUT
Any changes made by the transaction to recoverable resources are to be backed out.
XMXD_COMMIT
Any changes made by the transaction to recoverable resources are to be committed.
INDOUBT_WAIT(name1)
returns, in a 1-byte location (name1), an equated value indicating how a unit of work (UOW) is to respond if a failure occurs while it is in an in-doubt state.
XMXD_NO
The UOW is not to wait, pending recovery from the failure. CICS is to take immediately whatever action is specified on the ACTION attribute of the TRANSACTION definition.
XMXD_YES
The UOW is to wait, pending recovery from the failure, to determine whether recoverable resources are to be backed out or committed.
INDOUBT_WAIT_TIME(name4)
returns the length of time, in minutes, after a failure during the in-doubt period, before the transaction is to take the action returned in the INDOUBT field. The returned value is valid only if the unit of work is in-doubt and INDOUBT_WAIT returns XMXD_YES.
name4
The name of a 4-byte location that is to receive the delay time, expressed as a binary value.

See also INDOUBT and INDOUBT_WAIT.

INITIAL_PROGRAM(name8)
returns the name of the initial program to be given control for the transaction.
name8
The name of an 8-byte location to receive the initial program name.
INQ_TRANSACTION_ID(name4 | string | ‘string’)
specifies the transaction identifier for this transaction definition inquiry.
name4
The name of a 4-byte location that contains the name of the transaction identifier.
string
A string of characters, without intervening blanks, naming the transaction identifier.
‘string’
A string of characters, within quotation marks, naming the transaction identifier. The string length is set to 4 by padding with blanks within the quotation marks.
ISOLATE(name1)
returns, in a 1-byte location (name1), an equated value indicating whether transaction isolation is required for the transaction's task-lifetime user-key storage.
XMXD_NO
Transaction isolation is not required for task-lifetime user-key storage.
XMXD_YES
Transaction isolation is required for task-lifetime user-key storage.
LOCAL_QUEUING(name1)
returns, in a 1-byte location (name1), an equated value indicating whether a start request for this transaction is eligible to queue locally if the transaction is to be started on another system, and the remote system is not available.

XMXD_NO
The request is not to be queued locally.
XMXD_YES
The request can be queued locally.
OTSTIMEOUT(name4)
returns the default period in seconds that an Object Transaction Service (OTS) transaction created in an Enterprise JavaBeans (EJB) environment and executing under this CICS transaction is allowed to execute without the initiator of the OTS transaction taking a syncpoint (or rolling back the OTS transaction).
name4
The name of a 4-byte location to receive the timeout setting, expressed as a binary value.
(Rn)
A register to receive the timeout setting, expressed as a binary value.

A value of zero means that the transaction resource definition specifies OTSTIMEOUT(NO).

PARTITIONSET(name1)
returns, in a 1-byte location (name1), an equated value indicating the partitionset specified on the transaction definition.
XMXD_KEEP
The reserved name KEEP is specified for the partitionset, which means tasks running under this transaction definition use the application partitionset for the terminal associated with the transaction.
XMXD_NAMED
The partitionset is named specifically on the transaction definition. The name is returned on the PARTITIONSET_NAME parameter.
XMXD_NONE
There is no partitionset specified for the transaction definition.
XMXD_OWN
The reserved name OWN is specified for the partitionset, which means tasks running under this transaction definition perform their own partitionset management.
PARTITIONSET_NAME(name8)
returns the name of the partitionset defined on the transaction definition.
name8
The name of an 8-byte location that is to receive the name of the partitionset.
PROFILE_NAME(name8)
returns the name of the profile definition that is associated with the transaction definition.
name8
The name of an 8-byte location to receive the name of the profile definition associated with the transaction definition.
REMOTE(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined as remote.
XMXD_NO
The transaction is not a remote transaction.
XMXD_YES
The transaction is a remote transaction.
REMOTE_NAME(name8)
returns the name by which the transaction is known in a remote system.
name8
The name of an 8-byte location to receive the transaction's remote name.
REMOTE_SYSTEM(name4)
returns the name of the remote system as specified on the transaction definition.

If the DYNAMIC parameter returns XMXD_YES, REMOTE_SYSTEM returns the default name, which can be changed by the dynamic routing program.

If the DYNAMIC parameter returns XMXD_NO, this is the actual remote system to which the transaction is to be routed.

name4
The name of a 4-byte location to receive the defined name of the remote system.
RESSEC(name1)
returns, in a 1-byte location (name1), an equated value indicating whether resource security checking is required for the transaction.
XMXD_NO
Resource security checking is not required.
XMXD_YES
Resource security checking is required.
RESTART(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction is to be considered for transaction restart.
XMXD_NO
The transaction cannot be restarted.
XMXD_YES
The transaction can be restarted.
ROUTABLE_STATUS(ROUTABLE|NOT_ROUTABLE)
returns a value indicating whether, if the transaction is the subject of an eligible EXEC CICS START command, it will be routed using the enhanced routing method.
NOT_ROUTABLE
If the transaction is the subject of a START command, it will be routed using the "traditional" method.
ROUTABLE
If the transaction is the subject of an eligible START command, it will be routed using the enhanced method.

For details of the enhanced and "traditional" methods of routing transactions invoked by EXEC CICS START commands, see the CICS Intercommunication Guide.

RUNAWAY_LIMIT(name4 | (Rn))
returns the runaway-task time limit specified on the transaction definition. If SYSTEM_RUNAWAY is XMXD_YES, the value returned is the value defined by the ICVR system initialization parameter.
name4
The name of a 4-byte location that is to receive the task runaway limit, expressed as a binary value.
(Rn)
A register to receive the task runaway limit, expressed as a binary value.
SHUTDOWN(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction can be run during CICS shutdown.
XMXD_DISABLED
The transaction is disabled from running during CICS shutdown.
XMXD_ENABLED
The transaction is enabled to run during CICS shutdown.
SPURGE(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined as system-purgeable.
XMXD_NO
The transaction is not system-purgeable.
XMXD_YES
The transaction is system-purgeable.
STATUS(name1)
returns, in a 1-byte location (name1), an equated value indicating the status of the transaction definition.
XMXD_DISABLED
The transaction definition is disabled.
XMXD_ENABLED
The transaction definition is enabled.
STORAGE_CLEAR(name1)
returns, in a 1-byte location (name1), an equated value indicating whether task-lifetime storage, of tasks associated with this transaction definition, is to be cleared before it is freed by a FREEMAIN command.
XMXD_NO
Task-lifetime storage need not be cleared before it's freed.
XMXD_YES
Task-lifetime storage must be cleared before it's freed.
STORAGE_FREEZE(name1 | (Rn))
returns, in a 1-byte location (name1), an equated value indicating whether storage freeze is defined for the transaction by means of the STGFRZ option on the CICS-supplied field engineering transaction, CSFE.
XMXD_NO
Storage is freed normally during the running of the transaction.
XMXD_YES
Storage that is normally freed during the running of a transaction is frozen.
SYSTEM_ATTACH(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the tasks attached with this tranid are always to be attached as system tasks.
XMXD_NO
A user task is being attached for this transaction.
XMXD_YES
A system task is being attached for this transaction.
SYSTEM_RUNAWAY(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction definition specifies the system default runaway-task time limit, which is specified on the ICVR system initialization parameter.
XMXD_NO
The transaction is not governed by the system runaway limit.
XMXD_YES
The transaction definition specifies the system default runaway limit.
TASKDATAKEY(name1)
returns, in a 1-byte location (name1), an equated value indicating the storage key of task-lifetime storage for tasks associated with this transaction definition.
XMXD_CICS
CICS key is specified for task-lifetime storage.
XMXD_USER
USER key is specified for task-lifetime storage.
TASKDATALOC(name1)
returns, in a 1-byte location (name1), an equated value indicating the data location of task-lifetime storage for tasks associated with this transaction definition.
XMXD_ANY
Task-lifetime storage can be located above 16MB in virtual storage.
XMXD_BELOW
Task-lifetime storage must be located below 16MB in virtual storage.
TCLASS(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction belongs to a transaction class.
XMXD_NO
The transaction is not a member of a transaction class.
XMXD_YES
The transaction is a member of the transaction class named in the TCLASS_NAME parameter.
TCLASS_NAME(name8)
returns the name of the transaction class to which the transaction belongs.
name8
The name of an 8-byte location to receive transaction class name to which the transaction belongs.
TPURGE(name1)
returns, in a 1-byte location (name1), an equated value indicating whether the transaction is defined as purgeable in the event of a VTAM® terminal error.
XMXD_NO
The transaction can not be purged if a terminal error occurs.
XMXD_YES
The transaction can be purged if a terminal error occurs.
TRACE(name1)
returns, in a 1-byte location (name1), an equated value indicating the level of tracing defined for the transaction:
XMXD_SPECIAL
CICS special-level trace This is the result of special trace being set by means of an EXEC CICS SET TRANSACTION command.
XMXD_STANDARD
CICS standard-level trace This equates to TRACE(YES) in the TRANSACTION resource definition.
XMXD_SUPPRESSED
Tracing is suppressed for the transaction This equates to TRACE(NO) in the TRANSACTION resource definition.
TRAN_PRIORITY(name4 | (Rn))
returns the transaction priority specified on the transaction definition.
name4
The name of a 4-byte location to receive the transaction priority, expressed as a binary value.
(Rn)
A register to receive the transaction priority, expressed as a binary value.
TRAN_ROUTING_PROFILE(name8)
returns the name of the profile that CICS is to use to route the transaction to a remote system.
name8
The name of an 8-byte location to receive the transaction-routing profile.
TRANSACTION_ID(name4)
returns the primary transaction identifier for this transaction definition inquiry.
name4
The name of a 4-byte location that contains the name of the transaction identifier.
TWASIZE(name4 | (Rn))
returns the size of the transaction work area specified on the transaction definition.
name4
The name of a 4-byte location to receive the size of the transaction work area, expressed as a binary value.
(Rn)
A register to receive the size of the transaction work area, expressed as a binary value.

RESPONSE and REASON values for INQUIRE_TRANDEF:

RESPONSE REASON
OK None
EXCEPTION UNKNOWN_TRANSACTION_ID
INVALID None
DISASTER LOGIC_ERROR
PURGED None

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(name8),]
       [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),]]
       Start of change[TERMINATE_PROTECTED(name1),]End of change       [TPURGE(name1),]
       [TRANNUM(name4 | string | ‘string’),]
       [TRAN_PRIORITY(name1),]
       [TRAN_ROUTING_PROFILE(name8),]
       [TRANSACTION_ID(name4),]
       [USERID(name8),]
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

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 the CICS Resource Definition Guide.

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(name8)
returns the name of a resource that the (suspended) transaction waiting for.
name8
The name of an 8-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.
Start of changeTERMINATE_PROTECTED(name1)End of change
Start of changereturns, 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.
End of change
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

The SET_TRANSACTION call

The SET_TRANSACTION function is provided on the DFHXMIQX macro call. Its purpose is to allow you to change the task priority and transaction class of the current task.

Note that you can use this call to change the TCLASS_NAME only when it is invoked from an XXMATT global user exit program.

SET_TRANSACTION

DFHXMIQX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(SET_TRANSACTION),
       [TASK_PRIORITY(name4),]
       [TCLASS_NAME(name8),]
       [TRANSACTION_TOKEN(name8),]]
       [OUT,
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

TASK_PRIORITY(name4)
specifies the new task priority being set for the task identified by TRANSACTION_TOKEN.
name4
The name of a 4-byte location that contains the new task priority number, expressed as a binary value.
TCLASS_NAME(name8)
specifies the new transaction class name that you want to associate this task with. To specify that the task is not to be in any transaction class, specify the special default system name DFHTCL00.
name8
The name of an 8-byte location that contains the name of the new transaction class. Set this field to DFHTCL00 for no transaction class.
TRANSACTION_TOKEN(name8)
specifies the transaction token that represents the task being modified. If you omit this parameter, the call defaults to the current task.
name8
The name of an 8-byte location that contains the transaction token.

RESPONSE and REASON values for SET_TRANSACTION:

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

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]