INQUIRE TRANSACTION

Retrieve information about a TRANSACTION definition.

Read syntax diagramSkip visual syntax diagramINQUIRE TRANSACTION
 
>>-INQUIRE TRANSACTION(data-value)------------------------------>
 
   .------------------------------.
   V                              |
>----+--------------------------+-+----------------------------><
     +-BREXIT(data-area)--------+
     +-CMDSEC(cvda)-------------+
     +-DTIMEOUT(data-area)------+
     +-DUMPING(cvda)------------+
     +-FACILITYLIKE(data-area)--+
     +-INDOUBT(cvda)------------+
     +-INDOUBTMINS(data-area)---+
     +-INDOUBTWAIT(cvda)--------+
     +-ISOLATEST(cvda)----------+
     +-PRIORITY(data-area)------+
     +-OTSTIMEOUT(data-area)----+
     +-PROFILE(data-area)-------+
     +-PROGRAM(data-area)-------+
     +-PURGEABILITY(cvda)-------+
     +-REMOTENAME(data-area)----+
     +-REMOTESYSTEM(data-area)--+
     +-RESSEC(cvda)-------------+
     +-ROUTING(cvda)------------+
     +-ROUTESTATUS(cvda)--------+
     +-RTIMEOUT(data-area)------+
     +-RUNAWAY(data-area)-------+
     +-RUNAWAYTYPE(cvda)--------+
     +-SCRNSIZE(cvda)-----------+
     +-SHUTDOWN(cvda)-----------+
     +-STATUS(cvda)-------------+
     +-STORAGECLEAR(cvda)-------+
     +-TASKDATAKEY(cvda)--------+
     +-TASKDATALOC(cvda)--------+
     +-+-TCLASS(data-area)----+-+
     | '-TRANCLASS(data-area)-' |
     +-TRACING(cvda)------------+
     +-TRPROF(data-area)--------+
     '-TWASIZE(data-area)-------'
 

Conditions: END, ILLOGIC, INVREQ, NOTAUTH, TRANSIDERR

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The INQUIRE TRANSACTION command retrieves information about a particular transaction installed in your CICS system.

Most of the values come from the TRANSACTION resource definition, but a few come from the profile definition to which it points (these are noted in the descriptions). See the CICS® Resource Definition Guide for full details about the attributes of these two types of resources.

Many of the values produced by an INQUIRE TRANSACTION command are the same as those produced by the same-named options in an INQUIRE TASK command, when the task is executing the transaction, because a task acquires most of its characteristics from the definition of the transaction. However, as noted in the description of that command, the values for a task also reflect the CICS system environment.

Furthermore, when a task is routed from one CICS to another, the transaction specified in the sending region may be different from the one executed in the receiving region, so that an inquiry about its TRANSACTION value can produce different results in the sending and receiving regions. Indeed, in the case of dynamic routing, the transaction specified in the sending CICS (and shown as the TRANSACTION value in an INQUIRE TASK there) need not even be defined if the default processing for an undefined transaction code is dynamic routing.

Browsing

You can also browse through all of the TRANSACTION definitions in your system by using the browse options (START, AT, NEXT, and END) on INQUIRE TRANSACTION commands. In browse mode, the definitions are returned in alphabetic order, and you can specify a starting point with the AT option if you wish. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Options

BREXIT(data-area)
returns the 8-character name of the bridge exit defined by the BREXIT parameter of the named transaction resource definition.

If BREXIT is not defined, blanks are returned.

CMDSEC(cvda)
returns a CVDA value indicating whether command security checking should be performed for tasks executing this transaction. CVDA values are:
CMDSECNO
Command security checking should not be performed.
CMDSECYES
Command security checking should be performed.
DTIMEOUT(data-area)
returns a fullword binary field giving the deadlock time-out value (in seconds) for a task executing this transaction. CICS abends a task that waits for a locked resource longer than its deadlock timeout value.
DUMPING(cvda)
returns a CVDA value indicating whether CICS should take a transaction dump if a task executing this transaction terminates abnormally. CVDA values are:
NOTRANDUMP
No dump should be taken.
TRANDUMP
A dump should be taken.

This DATAvalue applies only to abend dumps and has no effect on DUMP TRANSACTION commands.

FACILITYLIKE(data-area)
returns the 4-character name of the terminal defined by the FACILITYLIKE parameter in the PROFILE associated with the named transaction resource definition.

If FACILITYLIKEis not defined, blanks are returned.

INDOUBT(cvda)
returns a CVDA value, based on the ACTION attribute of the TRANSACTION resource definition, 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 depends on the values returned in INDOUBTWAIT and INDOUBTMINS; if INDOUBTWAIT returns WAIT, the action is not normally taken until the time returned in INDOUBTMINS expires. (For exceptions to this rule, see INDOUBTWAIT.)

CVDA values are:

BACKOUT
All changes made to recoverable resources are to be backed out.
COMMIT
All changes made to recoverable resources are to be committed, and the unit of work marked as completed.
Note:
If a program uses the obsolete DTB option, which was replaced by INDOUBT, a CVDA value of NOTSUPPORTED is returned.
INDOUBTMINS(data-area)
returns a fullword binary field giving 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 INDOUBTWAIT returns WAIT.
INDOUBTWAIT(cvda)
returns a CVDA value, based on the WAIT attribute of the TRANSACTION definition, indicating how CICS is to respond if a failure occurs while a unit of work (UOW) is in an in-doubt state. CVDA values are:
NOWAIT
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.
WAIT
The UOW is to wait, pending recovery from the failure, to determine whether recoverable resources are to be backed out or committed.
Note:
Even if INDOUBTWAIT returns WAIT, there may be aspects of the UOW that force CICS to take an immediate decision--that is, to take immediately the action specified on the ACTION attribute of the transaction definition. This can happen if, for example, the UOW contains:
  • Subordinate LU6.1 sessions
  • Subordinate MRO sessions to pre-CICS Transaction Server for z/OS® systems.

For further information about the meaning of the ACTION and WAIT attributes of the TRANSACTION definition, see the CICS Resource Definition Guide.

ISOLATEST(cvda)
returns a CVDA value indicating whether a task executing this transaction should run isolated when isolation is active in the system.

Isolation limits the access, for both read and write, of user-key programs to task storage. A program executing in user key on behalf of an isolated task can access the task storage of only that task, and this storage cannot be accessed by programs executing in user key on behalf of other tasks. Isolation does not affect access by CICS-key programs and does not apply to storage with the SHARED attribute or any other non-task storage.

Isolation must be turned on for the system as well as the transaction in order for a task to run isolated. (See the TRANISOLATE option of the INQUIRE SYSTEM command.) CVDA values are:

ISOLATE
Tasks should run isolated.
NOISOLATE
Tasks should not run isolated.
OTSTIMEOUT(data-area)
returns a fullword data-area containing the default period in seconds an OTS transaction, created in an EJB environment executing under this CICS transaction, is allowed to execute prior to syncpoint.
PRIORITY(data-area)
returns a fullword binary field giving the priority of this transaction relative to other transactions in the CICS system, in the range 1-255.
PROFILE(data-area)
returns the 8-character name of the profile definition for this transaction. The profile defines attributes that govern the interaction between a task executing the transaction and the terminal or session which is its principal facility.
PROGRAM(data-area)
returns the 8-character name of the first program invoked by a task executing this transaction.
PURGEABILITY(cvda)
returns a CVDA value indicating whether CICS is allowed to purge this task (that is, to terminate it abnormally). Purge requests come from SET TASK PURGE commands (or CEMT equivalents), and CICS can generate them internally to reclaim resources to relieve a system stall condition. CVDA values are:
NOTPURGEABLE
The task cannot be purged.
PURGEABLE
The task can be purged.

The PURGEABILITY value is set initially by the SPURGE option in the definition of the TRANSACTION this task is executing.

REMOTENAME(data-area)
returns the 8-character name by which this transaction is known in the remote system, if it is defined as a remote transaction. (Read the description of "Defining a TRANSACTION" in the CICS Resource Definition Guide for a fuller discussion of the length of REMOTENAME). Blanks are returned if the transaction is not remote.
REMOTESYSTEM(data-area)
returns the 4-character name of the remote system on which this transaction is defined, if it is defined as a remote transaction.

If the remote transaction is defined as DYNAMIC=YES, and remotesystem is omitted, CICS returns the name of the local region.

Blanks are returned if the transaction is not remote.

RESSEC(cvda)
returns a CVDA value identifying whether resource-level security checking should be performed for a task executing this transaction. CVDA values are:
RESSECNO
Resource-level checking should not be performed.
RESSECYES
Resource-level checking should be performed.
ROUTING(cvda)
returns a CVDA value indicating whether a task executing this transaction is subject to dynamic routing. CVDA values are:
DYNAMIC
The task can be routed dynamically.
STATIC
The task cannot be routed dynamically.
ROUTESTATUS
returns a CVDA value indicating whether, if the transaction is the subject of an eligible START command, it is routed using the enhanced routing method. CVDA values are:
NOTROUTABLE
If the transaction is the subject of a START command, it is 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.

RTIMEOUT(data-area)
returns a fullword binary field giving the read time-out value for a task executing this transaction, in seconds. CICS abends a task if it waits for input longer than its read time-out value. This value is defined in the profile definition (see the PROFILE option).
RUNAWAY(data-area)
returns a fullword binary field giving the "runaway task" time, in milliseconds, for tasks executing this transaction. If a task keeps control of the processor for more than this interval, CICS assumes it is in a loop and abends it. If the value is zero, CICS does not monitor the task for a runaway condition.
RUNAWAYTYPE(cvda)
returns a CVDA value indicating the source of the RUNAWAY option value for this transaction. CVDA values are:
SYSTEM
The value is the current default for the system. (See the ICVR option of the INQUIRE SYSTEM command.)
USER
The value was defined explicitly in the transaction definition.
SCRNSIZE(cvda)
returns a CVDA value indicating whether a task executing this transaction should use the alternate or the default screen size. This value is defined in the profile definition (see the PROFILE option). CVDA values are:
ALTERNATE
The alternate screen size is to be used.
DEFAULT
The default screen size is to be used.
SHUTDOWN(cvda)
returns a CVDA value indicating whether this transaction can be executed during CICS shutdown by a task created to process unsolicited input. (The transaction also can be executed in this situation if it appears in the transaction list table (XLT) for shutdown.) CVDA values are:
SHUTDISABLED
The transaction cannot be executed.
SHUTENABLED
The transaction can be executed.
STATUS(cvda)
returns a CVDA value indicating whether the transaction is available for use. CVDA values are:
DISABLED
The transaction is not available for use.
ENABLED
The transaction is available for use.
STORAGECLEAR(cvda)
returns a CVDA value indicating whether CICS should clear storage that is released from a task executing this transaction (to prevent other tasks accidentally viewing confidential data). CVDA values are:
CLEAR
Storage is cleared.
NOCLEAR
Storage will not be cleared.
TASKDATAKEY(cvda)
returns a CVDA value indicating the key of the storage CICS assigns to a task executing this transaction. This storage includes task life-time storage--the transaction work area (TWA) and the EXEC interface block (EIB)--and the storage that CICS obtains on behalf of programs that run under the task.

CVDA values are:

CICSDATAKEY
CICS-key storage is assigned.
USERDATAKEY
User-key storage is assigned.
TASKDATALOC(cvda)
returns a CVDA value indicating whether task-lifetime storage for a task executing this transaction should be above or below the 16MB line. Task-lifetime storage includes the EIB and TWA. CVDA values are:
ANY
Task-lifetime storage can be above or below the 16MB line.
BELOW
Task-lifetime storage must be below the 16MB line.
TCLASS(data-area)
returns a fullword binary field giving the number of the transaction class to which the transaction belongs, if the task belongs to a numbered class. Zero is returned if the transaction does not belong to any class, and an INVREQ exception condition is raised if the transaction belongs to a class that does not correspond to a numbered class.

The TCLASS option is retained for compatibility with earlier releases of CICS, where transaction classes were numbered from 1 to 10. In this release, transaction classes have 8-character names, specified by the TRANCLASS value in the definition (see that option in this command).

A class is numbered only if its name is of the form DFHTCLnn, where nn is a number from 00 to 10, and it is this number that is returned by the TCLASS option in this command. (The TRANSACTION definition can contain a TCLASS value as well, to allow the same definition to be installed in a system running under an earlier release, but the TCLASS value is ignored in this release and does not need to correspond to the TRANCLASS value.)

TRACING(cvda)
returns a CVDA value indicating the type of tracing to be done for tasks executing this transaction. CVDA values are:
SPECTRACE
Tracing is to be special.
SPRSTRACE
Tracing is suppressed.
STANTRACE
Tracing is to be standard.

If this value is other than SPRSTRACE and the task has a principal facility, the tracing value for the task is determined from a combination of the TRACING values for its terminal and the transaction it is executing. In this case, tracing is special if either the terminal or the transaction specifies SPECTRACE, standard if both specify STANTRACE.

A TRACING value of STANTRACE is assigned when the transaction is defined. You can specify other values only with a SET TERMINAL command or the CICS-supplied CETR transaction.

TRANCLASS(data-area)
returns the 8-character name of the transaction class to which this transaction belongs. If the transaction does not belong to any class, the value DFHTCL00 is returned.
TRANSACTION(data-value)
specifies the 4-character name of the transaction definition about which you are inquiring.
TRPROF(data-area)
returns the 8-character name of the profile definition used to define attributes associated with the session used for routing, if transaction routing occurs.
TWASIZE(data-area)
returns a fullword binary field giving the size, in bytes, of the transaction work area (TWA) for this transaction.

Conditions

END
RESP2 values:
2
There are no more resource definitions of this type.
ILLOGIC
RESP2 values:
1
You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
INVREQ
RESP2 values:
3
The TCLASS option has been specified in this INQUIRE command, and the transaction belongs to a class that is not one of the numbered classes DFHTCL00 through DFHTCL10.
NORMAL
RESP2 values:
10
The profile definition associated with the transaction is not available.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
TRANSIDERR
RESP2 values:
1
The transaction could not be found.
[[ Contents Previous Page | Next Page Index ]]