INQUIRE TRANSACTION
Retrieve information about a TRANSACTION definition.
Conditions: END, ILLOGIC, INVREQ, NOTAUTH, TRANSIDERR
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
This command is threadsafe.
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 values are noted in the descriptions. See TRANSACTION attributes and PROFILE attributes 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 running 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 might be different from the one that is run 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 want. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.
The resource signature
You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.
Options
- APPLICATION(data-value)
- Returns, in a 64-character area, the application name of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, APPLICATION returns blanks.
- APPLMAJORVER(data-value)
- Returns, in full word binary form, the major version number of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, APPLMAJORVER returns -1.
- APPLMICROVER(data-value)
- Returns, in full word binary form, the micro version number of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, APPLMICROVER returns -1.
- APPLMINORVER(data-value)
- Returns, in full word binary form, the minor version number of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, APPLMINORVER returns -1.
- AVAILSTATUS(cvda)
-
Returns the availability status of the TRANSACTION resource as an
application entry point for an application deployed on a platform.
- AVAILABLE
- The TRANSACTION resource is declared as an application entry point, and the application entry point controls its availability and is available, so the TRANSACTION resource is available to callers.
- UNAVAILABLE
- The TRANSACTION resource is declared as an application entry point, but the application entry point that controls its availability is unavailable, so the TRANSACTION resource is not available to callers.
- NONE
- The TRANSACTION resource is available to callers. Either the TRANSACTION resource is not declared as an application entry point, or it is declared as an application entry point but the application entry point is disabled or does not control the availability of the TRANSACTION resource.
- 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.
- CHANGEAGENT(cvda)
- Returns a CVDA value that identifies the agent that made the last
change to the resource definition. The possible values are as follows:
- CREATESPI
- The resource definition was last changed by an EXEC CICS CREATE command.
- CSDAPI
- The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.
- CSDBATCH
- The resource definition was last changed by a DFHCSDUP job.
- DREPAPI
- The resource definition was last changed by a CICSPlex SM BAS API command.
- SYSTEM
- The resource definition was last changed by the CICS or CICSPlex system.
- CHANGEAGREL(data-area)
- Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.
- CHANGETIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.
- CHANGEUSRID(data-area)
- Returns the 8-character user ID that ran the change agent.
- CMDSEC(cvda)
- Returns
a CVDA value indicating whether command security checking is performed
for tasks running this transaction. CVDA values are as follows:
- CMDSECNO
- Command security checking is not performed.
- CMDSECYES
- Command security checking is performed.
- DEFINESOURCE(data-area)
- Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.
- DEFINETIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource definition was created.
- DTIMEOUT(data-area)
- Returns a fullword binary field giving the deadlock timeout value in seconds for a task running this transaction. CICS stops a task that waits for a locked resource longer than its deadlock timeout value.
- DUMPING(cvda)
- Returns
a CVDA value indicating whether CICS takes
a transaction dump if a task running this transaction stops abnormally.
CVDA values are as follows:
- NOTRANDUMP
- No dump is taken.
- TRANDUMP
- A dump is taken.
This data value 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 FACILITYLIKE is 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 indoubt period.
The action depends on the values returned in the INDOUBTWAIT and INDOUBTMINS options; if INDOUBTWAIT returns WAIT, the action is not usually taken until the time returned in INDOUBTMINS expires. (For exceptions to this rule, see the INDOUBTWAIT option.)
CVDA values are as follows:- 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.
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 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 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 indoubt state. CVDA values are as follows:
- 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. Even if INDOUBTWAIT returns WAIT, aspects of the UOW might force CICS to take an immediate decision; that is, to take immediately the action specified on the ACTION attribute of the transaction definition. This action can happen if, for example, the UOW contains one of these sessions:
- 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 TRANSACTION attributes.
- INSTALLAGENT(cvda)
- Returns a CVDA value that identifies the agent that installed
the resource. The possible values are as follows:
- BUNDLE
- The resource was installed by a bundle deployment.
- CREATESPI
- The resource was installed by an EXEC CICS CREATE command.
- CSDAPI
- The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
- GRPLIST
- The resource was installed by GRPLIST INSTALL.
- SYSTEM
- The resource was installed by the CICS or CICSPlex SM system.
- INSTALLTIME(data-area)
- Returns an ABSTIME value that represents the time stamp when the resource was installed.
- INSTALLUSRID(data-area)
- Returns the 8-character user ID that installed the resource.
- ISOLATEST(cvda)
- Returns
a CVDA value indicating whether a task running this transaction will
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 running 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 running 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 for a task to run isolated. See the TRANISOLATE option of the INQUIRE SYSTEM command. CVDA values are as follows:- ISOLATE
- Tasks run isolated.
- NOISOLATE
- Tasks do not run isolated.
- OPERATION(data-value)
- Returns, in a 64-character area, the operation name of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, OPERATION returns blanks.
- OTSTIMEOUT(data-area)
- Returns a fullword data area containing the default period in seconds that an OTS transaction, created in an EJB environment under this CICS transaction, is allowed to run before sync point.
- PLATFORM(data-value)
- Returns, in a 64-character area, the platform name of the application for which this TRANSACTION resource is defined as an entry point. If the TRANSACTION resource is not defined as an application entry point, PLATFORM returns blanks.
- 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 running the transaction and the terminal or session which is its principal facility.
- PROGRAM(data-area)
- Returns the 8-character name of the first program called by a task running this transaction.
- PURGEABILITY(cvda)
- Returns
a CVDA value indicating whether CICS is
allowed to purge this task; that is, to end 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 as follows:
- 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 running.
- 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. See TRANSACTION attributes for a fuller discussion of the length of REMOTENAME. Blanks are returned if the transaction is not remote.
- REMOTESYSTEM(data-area)
- Returns
the first four characters 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 the REMOTESYSTEM option 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
is performed for a task running this transaction. CVDA values are
as follows:
- RESSECNO
- Resource-level checking is not performed.
- RESSECYES
- Resource-level checking is performed.
- ROUTING(cvda)
- Returns
a CVDA value indicating whether a task running this transaction is
subject to dynamic routing. CVDA values are as follows:
- 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 as follows:
- 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 is routed using the enhanced method.
For details of the enhanced and “traditional” methods of routing transactions invoked by EXEC CICS START commands, see Routing transactions invoked by START commands.
- RTIMEOUT(data-area)
- Returns a fullword binary field giving the read timeout value for a task running this transaction, in seconds. CICS stops a task if it waits for input longer than its read timeout 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 running this transaction. If a task keeps control of the processor for more than this interval, CICS assumes it is in a loop and stops 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 as follows:
- 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 running this transaction uses
the alternate or the default screen size. This value is defined in
the profile definition; see the PROFILE option. CVDA values are as
follows:
- 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 run during CICS shutdown by a task created
to process unsolicited input. The transaction also can be run in this
situation if it appears in the transaction list table (XLT) for shutdown.
CVDA values are as follows:
- SHUTDISABLED
- The transaction cannot be run.
- SHUTENABLED
- The transaction can be run.
- STATUS(cvda)
- Returns
a CVDA value indicating whether the transaction is available for use.
CVDA values are as follows:
- DISABLED
- The transaction is not available for use.
- ENABLED
- The transaction is available for use.
- STORAGECLEAR(cvda)
- Returns
a CVDA value indicating whether CICS clears
storage that is released from a task running this transaction, to
prevent other tasks accidentally viewing confidential data. CVDA values
are as follows:
- CLEAR
- Storage is cleared.
- NOCLEAR
- Storage is not cleared.
- TASKDATAKEY(cvda)
- Returns
a CVDA value indicating the key of the storage that CICS assigns to a task running this transaction.
This storage includes task-lifetime storage; that is, 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 as follows:
- 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 running
this transaction is above or below the 16 MB line. Task-lifetime storage
includes the EIB and TWA. CVDA values are as follows:
- ANY
- Task-lifetime storage can be above or below the 16 MB line.
- BELOW
- Task-lifetime storage must be below the 16 MB 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 this number 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 running
this transaction. CVDA values are as follows:
- 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 running. 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 was not found.