Kernel APIs: STAT^%ZTLOAD

STAT^%ZTLOAD: Task Status

Reference Type: Supported, Category: TaskMan, ICR#: 10063

Description

The STAT^%ZTLOAD API looks up tasks and retrieves their current status. The status of a task returned by STAT^%ZTLOAD is expressed in the general terms of whether the task:

Ran.
Is running.
Runs.

ZTSK(1) and ZTSK(2) return the code and text of the current status. This status is an abstraction based on the more complex system used by TaskMan.

An active task is one that either is expected to start or is currently running. An inactive task does not start in the future without outside intervention; this can be because it:

Has already completed.
Was never scheduled.
Was interrupted.

The "running" status is not based on direct examination of the system tables but is inferred from TaskMan's information about the task.

When interpreting the output of STAT^%ZTLOAD, consider that:

If a task is transferred to another volume set, it becomes undefined on the original volume set.
A status of "running" is a guess.
"Finished" does not necessarily mean the task accomplished what it set out to do.
An interrupted task may or may not run correctly if edited and rescheduled.

Format

  STAT^%ZTLOAD

Make sure to perform the following steps before calling this API:

NEW all non-namespaced variables.
Set all input variables.
Call the API.

Input Variables

ZTSK:

(required) The task number to look up. It must be defined on the current volume set.

Output Variables

ZTSK(0):

Returns:

1—Task is defined.
0—Task is not defined.

ZTSK(1):

Numeric status code from 0 to 5 indicating the status of the task.

ZTSK(2):

Status text describing the status of the task. Its value corresponds with the status code in ZTSK(1). The possible values and their meanings are as follows:

ZTSK(1) = 0 and ZTSK(2) = "Undefined"—Task does not exist on this volume set.
ZTSK(1) = 1 and ZTSK(2) = "Active: Pending"—Task is:
- Scheduled.
- Waiting for an I/O device.
- Waiting for a volume set link.
- Waiting for a partition in memory.
ZTSK(1) = 2 and ZTSK(2) = "Active: Running"—Task has started running.
ZTSK(1) = 3 and ZTSK(2) = "Inactive: Finished"—Task quit normally after running.
ZTSK(1) = 4 and ZTSK(2) = "Inactive: Available"—Task was created without being scheduled or was edited without being rescheduled.
ZTSK(1) = 5 and ZTSK(2) = "Inactive: Interrupted"—task was interrupted before it would have quit normally. Causes can include:
- Bad data.
- User intervention.
- Hard error.
- Many other possibilities.