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 | *)]

This command is threadsafe.

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 TRANSACTION attributes.

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 timeout value for the transaction.

name4: The name of a 4-byte location that is to receive the deadlock timeout value, expressed as a binary value.
(Rn): A register to receive the deadlock timeout 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 indoubt 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 indoubt 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 indoubt 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 indoubt 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 CICS transaction routing.

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 16 MB in virtual storage.
XMXD_BELOW: Task-lifetime storage must be located below 16 MB 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 z/OS® Communications Server 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