INQUIRE TASK

Description

The INQUIRE TASK command returns information about a specific user task. User tasks are those associated with user-defined transactions or with CICS-supplied transactions that are normally invoked by an operator.

Many of the options available on this command are the same as those available on the INQUIRE TRANSACTION command, because a task obtains most of its characteristics from the definition of the transaction it is executing. However, these properties are determined at task initiation.

If the transaction definition is changed after the task begins, the task may have a different value for a property than the current transaction definition. Task values can also be changed with a SET TASK command or its CEMT equivalent.

In addition, the INQUIRE TASK command always produces information about the task you specify on the local CICS® system. You need to keep this in mind for tasks that are subject to routing or that issue LINK commands that may be shipped to another system.

Whenever a task is executed wholly or in part on a system other than the one on which it originates, there is a matching task on the remote system. The task on the originating system takes its characteristics from the definition on that system of the transaction it is to execute. The corresponding task on the remote system (if routing takes place or the task issues distributed program links) takes its characteristics from the definition of whatever transaction on the remote system that the originating system tells the remote system to use. This remote transaction may have different properties from those of the transaction on the originating system. (It may or may not have a different name; in the case of static transaction routing, the name of the transaction in the remote system comes from the REMOTENAME option of the transaction in the local system.)

Consequently, an inquiry about the task on the originating system may produce entirely different results from an inquiry about the corresponding task on the remote system. For the same reason, a task that issues distributed program links may get a different result from an INQUIRE TASK about itself (taking the task number from the EIB) in a program executing remotely than from the same command in a program executing locally.

Options

ACTIVITY(data-area)

Returns the 16-character, user-assigned, name of the BTS activity that this task is executing on behalf of.

ACTIVITYID(data-area)

Returns the 52-character, CICS-assigned, identifier of the BTS activity that this task is executing on behalf of.

ATTACHTIME(data-area)

Returns an 8-byte packed decimal value, in ABSTIME format, representing the time in milliseconds at which the task was attached.

BRFACILITY(data-area)

Returns the 8-byte facility token representing the virtual terminal used by the current task if it is running in a bridged environment. If the task is not running in the 3270 bridge environment, zeroes are returned.

BRIDGE(data-area)

Returns the 4-character transaction identifier of the bridge monitor transaction that issued a START BREXIT TRANSID command to start this task, or the client that issued a link to DFHL3270. If the task is not currently running in the 3270 bridge environment, then blanks are returned.

CMDSEC(cvda)

Returns a CVDA value indicating whether the definition of the transaction the task is executing specifies command security. CVDA values are as follows:

CMDSECNO

Command security is not specified.

CMDSECYES

Command security is specified.

When a task being checked issues a system programming command, CICS calls the external security manager (ESM) to verify that the user associated with the task has authority to use these commands.

A task is command-checked only when an ESM is active and either the CMDSEC value for the task is CMDSECYES or the system initialization option CMDSEC value is ALWAYS (see the SECURITYMGR option of INQUIRE SYSTEM for more information.

CURRENTPROG(data-area)

Returns a 1- to 8-character name of the current program, as known to the CICS program manager domain, executing for this task.

DB2PLAN(data-area)

Returns a 1- to 8-character name of the DB2PLAN being used by this task, or blanks if no DB2PLAN is being used.

DTIMEOUT(data-area)

Returns a fullword binary field giving the deadlock timeout interval, in seconds. CICS abends a task that waits longer than its deadlock timeout value for a locked resource.

DUMPING(cvda)

Returns a CVDA value indicating whether CICS should take a transaction dump if the task terminates abnormally. CVDA values are as follows:

NOTRANDUMP

No dump is taken.

TRANDUMP

A dump is taken.

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

FACILITY(data-area)

Returns the 4-character name of the facility associated with initiation of this task, if that facility is a transient data queue or a terminal or system. If the task was initiated otherwise, the facility value is blanks. The FACILITYTYPE option tells you what type of facility caused task initiation, and therefore what FACILITY represents.

FACILITYTYPE(cvda)

Returns a CVDA value identifying the type of facility that initiated this task. CVDA values are:

DEST

CICS initiated the task to process a transient data queue which had reached trigger level; the FACILITY option returns the name of queue.

TASK

Another task initiated the task with a START command that did not specify a terminal, or CICS created the task internally; the FACILITY option returns blanks in this case.

TERM

Either the task was initiated to process unsolicited input or another task initiated the task with a START command with the TERMID option. In the first case the FACILITY option returns the name of the terminal that sent the input, and in the second, it returns the terminal named in TERMID.

IDENTIFIER(data-area)

Returns a 48-character field containing user data provided by the bridge exit, if the task was initiated in the 3270 bridge environment, or blanks, otherwise. This field is intended to assist in online problem resolution. For example, it could contain the WebSphere® MQ correlator for the CICS-WebSphere MQ bridge, or a Web token.

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 is dependent on the values returned in INDOUBTWAIT and INDOUBTMINS; if INDOUBTWAIT returns WAIT, the action is not taken until the time returned in INDOUBTMINS expires.

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 indoubt period, before the task 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.

See also INDOUBT and INDOUBTWAIT.

INDOUBTWAIT(cvda)

Returns a CVDA value, based on the WAIT attribute of the TRANSACTION definition, indicating how a unit of work (UOW) is to respond if a failure occurs while it is in an indoubt state. CVDA values are:

NOWAIT

The unit of work 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 unit of work is to wait, pending recovery from the failure, to determine whether recoverable resources are to be backed out or committed.

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

IPFACILITIES(ptr-ref)

Returns the address of a list of 4-byte binary tokens, each of which identifies an IPCONN session that the task is using to communicate with another system. If there are no such IP facilities for this task, the IPFACILITIES pointer contains a null value.

CICS obtains the storage for the list and frees it when the inquiring task issues another INQUIRE TASK command or ends; the task cannot free the storage itself.

IPFLISTSIZE(data-area)

Returns a fullword binary field giving the number of IP facilities associated with this task. (That is, it returns the number of items in the list addressed by the IPFACILITIES option.)

If this task has no IP facilities, IPFLISTSIZE contains zero.

ISOLATEST(cvda)

Returns a CVDA value indicating whether the task is defined as isolated or not. 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 nontask storage.

The value of ISOLATEST is taken from the definition of the TRANSACTION the task is executing when the task is created. For a task defined as isolated to execute isolated, transaction isolation for the system must also be active (see the TRANISOLATE option of INQUIRE SYSTEM.

ISOLATE

The task is defined as isolated.

NOISOLATE

The task is defined as not isolated.

PRIORITY(data-area)

Returns a fullword binary field giving the total priority of the task. Total priority is the sum of the priority of the user associated with the task, the priority of the terminal which is the principal facility, and the priority of the transaction being executed (see the TRANPRIORITY option).

PROCESS(data-area)

Returns the 36-character name of the BTS process of which this task is a part.

PROCESSTYPE(data-area)

Returns the 8-character identifier of the type definition of the BTS process of which this task is a part.

PROFILE(data-area)

Returns the 8-character name of the PROFILE for the transaction this task is executing.

PROGRAM(data-area)

Returns the 8-character name of the program executed first in this task.

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 4-character name assigned in the REMOTENAME option of the definition of the TRANSACTION which this task is executing. When CICS routes a task statically, REMOTENAME is the name of the transaction that the partner task on the remote system executes. Consequently REMOTENAME is significant to the task about which you are inquiring only if it is subject to routing.

CICS returns blanks if the transaction definition does not specify REMOTENAME.

REMOTESYSTEM(data-area)

Returns the 4-character name assigned in the REMOTESYSTEM option of the definition of the TRANSACTION which this task is executing. When CICS routes a task statically, REMOTESYSTEM is the name of the CONNECTION definition of the system to which the task is routed. Like REMOTENAME, REMOTESYSTEM is significant to the task about which you are inquiring only if it is subject to routing.

CICS returns blanks if the TRANSACTION definition does not specify REMOTESYSTEM.

RESNAME(data-area)

RESNAME, an alternative to SUSPENDVALUE, returns a 16-character resource name of tasks suspended on TS queues.

RESSEC(cvda)

Returns a CVDA value indicating whether the definition of the TRANSACTION the task is executing specifies resource-level security checking. CVDA values are:

RESSECNO

Command security is not specified.

RESSECYES

Command security is specified.

When a task is being checked, CICS verifies on each command that the user associated with the task has authority to access the resource named in the way requested.

A task is checked only when an external security manager is active and either the RESSEC value for the task is RESSECYES or the system initialization option RESSEC value is ALWAYS (see the SECURITYMGR option of INQUIRE SYSTEM for more information.

ROUTING(cvda)

Returns a CVDA value indicating whether the transaction this task is executing specifies dynamic routing or not (in the DYNAMIC option in the TRANSACTION definition). Dynamic routing occurs just before the initial dispatch of a task, and therefore this value indicates whether dynamic routing may have occurred (if the task is already in execution) or may yet occur (if it has not yet been dispatched). CVDA values are:

DYNAMIC

Dynamic routing applies.

STATIC

Dynamic routing does not apply.

RTIMEOUT(data-area)

Returns a fullword binary field giving the read timeout interval, in seconds. CICS abends a task if it waits for input longer than its read timeout value. The RTIMEOUT value is set by the RTIMOUT option in the PROFILE definition associated with the TRANSACTION this task is executing.

RUNAWAY(data-area)

Returns the runaway task time for this task, in milliseconds, as a fullword binary value. If a task keeps control of the processor for more than this interval on a single dispatch, 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.

RUNSTATUS(cvda)

Returns a CVDA value indicating the dispatch status of the task. CVDA values are:

DISPATCHABLE

The task is ready to run.

RUNNING

The task is running.

SUSPENDED

The task is not ready to run.

SCRNSIZE(cvda)

Returns a CVDA value indicating whether the alternate or the default screen size applies to this task. CVDA values are:

ALTERNATE

Alternate screen size applies.

DEFAULT

Default screen size applies.

The SCRNSIZE value is set by the same-named option in the PROFILE definition associated with the transaction this task is executing.

STARTCODE(data-area)

Returns a 2-character value indicating how this task started. Possible values are:

D

The task was initiated to process a distributed programming link (DPL) command that did not specify the SYNCONRETURN option. (The task is not allowed to issue syncpoints.)

DS

The task was initiated to process a distributed programming link (DPL) command containing the SYNCONRETURN option. (The task is allowed to issue syncpoints).

QD

CICS initiated the task to process a transient data queue that had reached trigger level.

S

Another task initiated this one, using a START command that did not pass data in the FROM option. The START command may or may not have passed a channel.

SD

Another task initiated this one, using a START command that passed data in the FROM option.

SZ

The task was initiated with a FEPI START command.

TO

The task was initiated to process unsolicited input from a terminal (or another system), and the transaction to be executed was determined from the input.

TP

The task was initiated to process unsolicited input or in response to a RETURN IMMEDIATE command in another task. In either case, the transaction to be executed was preset (in the RETURN command or in the associated TERMINAL definition) without reference to input.

U

CICS created the task internally.

Note: When the IIOP request processor is run locally the startcode for an ASSIGN command or an INQUIRE TASK is U. When the IIOP request processor is run remotely, over an MRO link, the startcode for these commands is TO. (If you attempt to run the IIOP request processor remotely over any other type of connection, the routing request is not accepted, so startcodes for these commands are not relevant in this situation).

STORAGECLEAR(cvda)

Returns a CVDA value indicating whether CICS should clear storage that is released from this task (to prevent other tasks accidentally viewing confidential data). CVDA values are:

CLEAR

Storage is cleared.

NOCLEAR

Storage will not be cleared.

SUSPENDTIME(data-area)

Returns a fullword binary field giving the number of seconds (rounded down) for which the task has been suspended since last dispatch, if its RUNSTATUS value is SUSPENDED. If the task is running or dispatchable, the SUSPENDTIME value is −1 .

SUSPENDTYPE(data-area)

Returns an 8-character text string indicating why this task is suspended, if it is (blanks are returned for tasks that are running or dispatchable). See the SUSPENDVALUE option also.

SUSPENDVALUE(data-area)

Returns the 8-character name of the resource for which this task is waiting (the name of the file if the task is enqueued on a record, for example). SUSPENDVALUE applies only to suspended tasks; if the task is running or dispatchable, the value returned is blanks.

For information on the values that can appear in the SUSPENDTYPE and SUSPENDVALUE options, and how they can be used as an aid in problem determination, see the resource type and resource name details in the CICS Problem Determination Guide.

TASK(data-value)

Specifies the 4-byte packed-decimal sequence number of the task to be inquired upon.

TASKDATAKEY(cvda)

Returns a CVDA value indicating the storage key in which CICS obtains storage for this task. This includes the task-lifetime 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 this task.

See the description of the TASKDATAKEY option in TRANSACTION definition attributes for more information.

CVDA values are as follows:

CICSDATAKEY

CICS obtains storage from CICS-key storage.

USERDATAKEY

CICS obtains storage from user-key storage.

The value returned for TASKDATAKEY is taken from the definition of the TRANSACTION that the task is executing. To determine whether storage protection is active (that is, whether user-key has a different value from CICS-key), you need to issue an INQUIRE SYSTEM command with the STOREPROTECT option.

TASKDATALOC(cvda)

Returns a CVDA value indicating whether task-lifetime storage for this task (CICS control blocks for the task such as the EIB and TWA) should be acquired above or below the 16 MB line. CVDA values are as follows:

ANY

Task-lifetime storage can be either below or above the 16 MB line.

BELOW

Task-lifetime storage must be below the 16 MB line.

TCB(cvda)

Returns a CVDA value indicating the type of TCB under which the task is running. The CVDA values are as follows:

CKOPEN

The task is running under a CICS key open TCB.

INTERNAL

The task is running under one of the CICS internal TCBs. An internal TCB can be one of the following:

• The concurrent mode (CO) TCB
• The file-owning mode (FO) TCB
• The resource-owning mode (RO) TCB
• The ONC/RPC mode (RP) TCB
• The sockets listener mode (SL) TCB
• The secure sockets layer mode (SO) TCB
• A sockets mode (S8) TCB
• The FEPI mode (SZ) TCB.

QR

The task is running under the CICS QR TCB.

UKOPEN

The task is running under a user key open TCB.

TCLASS(data-area)

Returns a fullword binary field giving the number of the transaction class to which this task belongs, if it belongs to a numbered transaction class. This option is retained for compatibility with earlier releases, where transaction classes were numbered from 1 to 10. If the task does not belong to such a class, the value returned is zero. (See the TRANCLASS option for more information.)

TRACING(cvda)

Returns a CVDA value indicating the type of tracing in effect for this task. CVDA values are:

SPECTRACE

Tracing for this task is special.

SPRSTRACE

Tracing for this task is suppressed.

STANTRACE

Tracing for this task is standard.

For further information on the types of tracing, see CETR - trace control .

TRANCLASS(data-area)

Returns the 8-character name of the transaction class to which the task belongs. If the task is not assigned to any class, the default class DFHTCL00 is returned. If the task belongs to a numbered class, the value returned is DFHTCLnn, where nn is the 2-digit class number.

TRANPRIORITY(data-area)

Returns a fullword binary field giving the component of the total priority of the task that came from the PRIORITY option in the definition of the TRANSACTION being executed. (See the PRIORITY option of this command also.)

TRANSACTION(data-area)

Returns the 4-character name of the transaction that this task is executing.

TRPROF(data-area)

Returns the 8-character name of the profile definition used for intersystem flows if the task is routed on an ISC link.

TWASIZE(data-area)

Returns a fullword binary field giving the size in bytes of the transaction work area (TWA) for this task.

UOW(data-area)

Returns, as an 8-byte field, the local identifier of the unit of work associated with this task.

USERID(data-area)

Returns the 8-character identifier of the user associated with the task.

Conditions

INVREQ

RESP2 values:

1

SUSPENDVALUE is specified, but significant characters are lost.

3

TCLASS is specified, but the task belongs to a named CLASS, not a numbered CLASS. The user should specify the TRANCLASS option.

10

The requested data is held on a data profile, but the data profile is not available.

NOTAUTH

RESP2 values:

100

The user associated with the issuing task is not authorized to use this command.

TASKIDERR

RESP2 values:

1

The task cannot be found.

2

The task is executing a type of transaction which is not subject to this command.