This section describes the transaction management XPI calls.
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 | *)]
This command is threadsafe.
- 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 |
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 | *)]
This command is threadsafe.
- 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 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 | *)]
This command is threadsafe.
- 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 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 | *)]
This command is threadsafe.
- 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 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 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 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),]]
[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 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.
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 |
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 | *)]
This command is threadsafe.
- 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 |
[[ Contents Previous Page | Next Page Index ]]