INQUIRE TASK

Retrieve information about a user task.

Syntax

INQUIRE TASK

Conditions: TASKIDERR

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

Description

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

Many of the options that are available on this command are the same as those that are available on the INQUIRE TRANSACTION command, because a task obtains most of its characteristics from the definition of the transaction that it is executing. However, these properties are determined when the task is initiated. If the transaction definition is changed after the task begins, the task possibly can have a different value for a property from the value that the current transaction definition has. Task values can also be changed with a SET TASK command or its CEMT equivalent.

In addition, the INQUIRE TASK command always returns information about the task that 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 possibly can 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, a matching task exists on the remote system. The task on the originating system takes its characteristics from the definition on that system of the transaction that it is to execute. If routing takes place, or the task issues distributed program links, the corresponding task on the remote system takes its characteristics from the transaction definition on the remote system that the originating system tells the remote system to use. This remote transaction possibly can have different properties from those of the transaction that is on the originating system. (Also, it possibly can have a different name. In the case of static transaction routing, the name of the transaction that is in the remote system comes from the Remote Transaction Code option of the transaction definition that is in the local system.)

Therefore, an inquiry about the task on the originating system possibly can return entirely different results from those of an inquiry about the corresponding task on the remote system. For the same reason, a task that issues distributed program links possibly can get a different result from an INQUIRE TASK about itself (taking the task number from the executive interface block (EIB)) in a program that is running remotely, from the result that it would get from the same command in a program that is running locally.

Options

CMDSEC(cvda)

Returns a CVDA value that indicates whether the definition of the transaction that the task is executing specifies command security. The CVDA values are:

CMDSECNO: Command security is not specified. TXSeries for Multiplatforms always returns this value.
CMDSECYES: Command security is specified.

CURRENTPROG(data-area)

Returns the eight-character name of the program that is being run in this task.

DTB(cvda)

Returns a CVDA value that indicates how uncommitted changes that are made to recoverable resources by this task are handled if the task fails. The CVDA values are:

BACKOUT: Uncommitted changes are backed out. TXSeries for Multiplatforms always returns this value.
COMMIT: Uncommitted changes are committed.
WAIT: The disposition of uncommitted changes is deferred until further information is available; locks on the changed resources are held until the disposition is resolved.

DTIMEOUT(data-area)

Returns a 32-bit binary field that gives giving the deadlock timeout interval, in seconds.

DUMPING(cvda)

Returns a CVDA value that indicates whether CICS is to take a transaction dump if the task terminates abnormally. The CVDA values are:

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 four-character name of the facility that is 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 null. The FACILITYTYPE option specifies the type of facility that initiated the task, and therefore what FACILITY represents.

FACILITYTYPE(cvda)

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

DEST: CICS initiated the task to process a transient data queue that had reached the value that is given in the TRIGGERLEVEL option; the FACILITY option returns the name of the 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 a null value 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 that is named in TERMID.

ISOLATEST(cvda)

Returns a CVDA value that indicates whether the task is defined as isolated. Isolation limits the access, for both read and write, of user-key programs to task storage. The CVDA values are:

ISOLATE: The task is defined as isolated.
NOISOLATE: The task is defined as not isolated.

The value that is returned is based on the setting of the SafetyLevel attribute in the Resource Definition (RD) stanza.

PRIORITY(data-area)

Returns a 32-bit binary field that gives the total priority of the task. Total priority is the sum of the priority of the user that is associated with the task, the priority of the terminal that is the principal facility, and the priority of the transaction that is being executed (see the TRANPRIORITY option).

PROCESSID(data-area)

Returns a 32-bit binary value that indicates the process ID of the process that is running the transaction that is associated with the task.

PROFILE(data-area)

Returns the eight-character name of the PROFILE for the transaction that this task is executing. TXSeries for Multiplatforms always returns a null for this value.

PROGRAM(data-area)

Returns the eight-character name of the program that was executed first in this task.

PURGEABILITY(cvda)

Returns a CVDA value that indicates 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. The CVDA values are:

NOTPURGEABLE: The task cannot be purged.
PURGEABLE: The task can be purged.

The PURGEABILITY value is set initially by the PURGEABILITY option in the transaction definition (TD) of the transaction that is being executed by this task.

RECUNITID(data-area)

Returns the eight-byte identifier of the current unit of recovery in this task.

REMOTENAME(data-area)

Returns the four-character name that is assigned in the RemoteName attribute of the TD. When CICS routes a task statically, the REMOTENAME option is the name of the transaction that the partner task on the remote system executes. Consequently, the REMOTENAME option has meaning to the task about which you are inquiring only if it is subject to routing.

CICS returns a null value if the TD does not specify a RemoteName attribute.

REMOTESYSTEM(data-area)

Returns the four-character name that is assigned in the RemoteSysID attribute of the TD. When CICS routes a task statically, the REMOTESYSTEM option is the name of the communications definition (CD) stanza of the system to which the task is routed. Like the REMOTENAME option, the REMOTESYSTEM option is significant to the task about which you are inquiring only if it is subject to routing.

CICS returns a null value if the transaction definition does not specify a System ID.

RESSEC(cvda)

Returns a CVDA value that indicates whether the transaction definition specifies resource-level security checking. The CVDA values are:

RESSECNO: Resource-level security is not specified.
RESSECYES: Resource-level security is specified.

ROUTING(cvda)

Returns a CVDA value that indicates whether the transaction that this task is executing specifies dynamic routing and whether a dynamic-routing user exit exists. Dynamic routing occurs just before the initial dispatch of a task; therefore, this value indicates whether dynamic routing has occurred (if the task is already in execution) or is yet to occur (if it has not yet been dispatched). The CVDA values are:

DYNAMIC: Dynamic routing applies.
STATIC: Dynamic routing does not apply.

RTIMEOUT(data-area)

Returns a 32-bit binary field that gives the read timeout interval, in seconds. TXSeries for Multiplatforms always returns zero for this value.

RUNAWAY(data-area)

Returns the time that this task can be a runaway task. A runaway task is one that has been dispatched and does not return control to CICS because the program that it is using is looping between two CICS requests. The time value is returned in milliseconds, as a 32-bit binary value.

RUNSTATUS(cvda)

Returns a CVDA value that indicates the dispatch status of the task. The CVDA values are:

DISPATCHABLE: The task is ready to run.
RUNNING: The task is running. TXSeries for Multiplatforms always returns this value.
SUSPENDED: The task is not ready to run.

SCRNSIZE(cvda)

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

ALTERNATE: Alternate screen size applies.
DEFAULT: Default screen size applies. TXSeries for Multiplatforms always returns this value.

The SCRNSIZE value is set by the Use Alternate Screen Size option of the transaction definition.

STARTCODE(data-area)

Returns up to a two-character value that indicates 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 that contains 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.
SD: Another task initiated this one, using a START command that passed data in the FROM option.
TO: The task was initiated to process unsolicited input from a terminal (or another system), and the transaction that is to be executed was determined from the input.
TP: The task was initiated in response to a RETURN IMMEDIATE command in another task.
U: CICS created the task internally.

STORAGECLEAR(cvda)

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

CLEAR: Storage is to be cleared.
NOCLEAR: Storage is not to be cleared. TXSeries for Multiplatforms always returns this value.

SUSPENDTIME(data-area)

Returns a 32-bit binary field that gives 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 zero. TXSeries for Multiplatforms always returns zero for this value.

SUSPENDTYPE(data-area)

Returns an eight-character text string that indicates why this task is suspended, if it is. (A null value is returned for tasks that are running or dispatchable.) See the SUSPENDVALUE option also. TXSeries for Multiplatforms always returns a null for this value.

SUSPENDVALUE(data-area)

Returns the eight-character name of the resource for which this task is waiting. For example, it can return the name of the file if the task is enqueued on a record. SUSPENDVALUE applies only to suspended tasks; if the task is running or dispatchable, a null value is returned. TXSeries for Multiplatforms always returns a null for this value.

TASK(data-value)

Specifies the unsigned 32-bit binary sequence number of the task about which you are inquiring.

COBOL:       PIC S9(7) COMP-3.
C:           char task_num[4];
PL/I:        FIXED DEC(7,0)

TASKDATAKEY(cvda)

Returns a CVDA value that indicates the storage key in which CICS obtains storage for this task.

The CVDA values are:

CICSDATAKEY: CICS obtains storage from CICS-key storage. TXSeries for Multiplatforms always returns this value.
USERDATAKEY: CICS obtains storage from user-key storage.

TASKDATALOC(cvda)

Returns a CVDA value that indicats whether task-lifetime storage for this task is to be acquired above or below the 16 MB line. The CVDA values are:

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. TXSeries for Multiplatforms always returns this value.

TCLASS(data-area)

Returns a 32-bit binary field that gives the number of the transaction class to which this task belongs, if it belongs to a numbered transaction class. If the task does not belong to such a class, the value returned is zero.

TRACING(cvda)

Returns a CVDA value that indicates the type of tracing that is in effect for this task. The CVDA values are:

SPECTRACE: Tracing for this task is special. TXSeries for Multiplatforms never returns this value.
SPRSTRACE: Tracing for this task is suppressed.
STANTRACE: Tracing for this task is standard.

For further information about the types of tracing, see Types of trace information.

TRANCLASS(data-area)

Returns the eight-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 that is returned is DFHTCLnn, where nn is the two-digit class number (01through10).

TRANPRIORITY(data-area)

Returns a 32-bit binary field that gives the component of the total priority of the task that came from the Priority option in the transaction definition. (See the PRIORITY option of this command also.)

TRANSACTION(data-area)

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

TRPROF(data-area)

Returns the eight-character name of the profile definition that is used for intersystem flows if the task is routed on an intersystem communication (ISC) link. The value of the SNAModeName attribute from the TD stanza definition for the transaction is returned. If no value is defined for the SNAModeName attribute, a null value is returned.

TWASIZE(data-area)

Returns a 16-bit binary field that gives the size, in bytes, of the transaction work area (TWA) for this task.

UOWSTATE(cvda)

Returns a CDVA value that indicates the unit of work (UOW) state in the named task. Note that UOW is synonymous with Logical Unit of Work (LUW). The CVDA values are:

INFLIGHT: No attempt has been made to commit any changes that have possibly occurred to protected resources during the current UOW for the task.
INDOUBT: The task has sent a message that requests that changes to remote resources be committed, but has not yet received a message that indicates that these changes were either committed or backed out (that is, a request commit message has been sent, but a committed or backout reply has not yet been received). During this interval, the task remains in doubt as to what has happened to changes that were made to local resources by this task.
WAITFORGET: The task has sent a committed message that indicates that the changes to the local resources have been committed, but has not yet received a forget reply to this message. The next unit of work cannot be started until a reply is received.

Note: The INDOUBT and WAITFORGET values can occur only when the two-phase commit process is used for syncpoint processing.

USERID(data-area)

Returns the eight-character identifier of the user that is associated with the task.

Conditions

TASKIDERR

RESP2 values:

The task cannot be found (RESP2=1).