INQUIRE TRANSACTION

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 definition attributes and PROFILE definition 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 definition 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 definition 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.