%ZTLOAD ICR (10063)

Name

Value

NUMBER

10063

IA #

10063

DATE CREATED

1998/04/20

CUSTODIAL PACKAGE

KERNEL

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

%ZTLOAD

NAME

%ZTLOAD

ORIGINAL NUMBER

10063

GENERAL DESCRIPTION

This routine provides several API's into a task.

STATUS

Active

KEYWORDS

TASKMAN

DURATION

Till Otherwise Agreed

%ZTLOAD

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

%ZTLOAD

Create & Schedule a task

REQ

Requeue a Task (in Task Manager chapter)

KILL

Delete a Task (in Task Manager chapter)

ISQED

Task Queue Status (in Task Manager chapter)

Unschedule a Task (in Task Manager chapter)

$$S(msg)

Check for Task Stop Request (in Task Manager chapter)

VARIABLES	TYPE	VARIABLES DESCRIPTION
msg	Input	(optional) Allows you to leave a message for the creator of the TaskMan task.
$$S	Output	Returns: * 1-Creator of the task that has asked the task to stop. * 0-For all other cases.

STAT

Task Status (in Task Manager chapter)

VARIABLES

TYPE

VARIABLES DESCRIPTION

ZTSK

Both

(required) The task number to look up. It must be
defined on the current volume set.  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" means the task does not exist on
this volume set.

* ZTSK(1) = 1 and ZTSK(2) = "Active: Pending" means the task is scheduled,
waiting for an I/O device, waiting for a volume set link, or waiting for a
partition in memory.

* ZTSK(1) = 2 and ZTSK(2) = "Active: Running" means the task has started
running.

* ZTSK(1) = 3 and ZTSK(2) = "Inactive: Finished" means the task quit
normally after running.

* ZTSK(1) = 4 and ZTSK(2) = "Inactive: Available" means the task was
created without being scheduled or was edited without being rescheduled.

* ZTSK(1) = 5 and ZTSK(2) = "Inactive: Interrupted" means the task was
interrupted before it would have quit normally. Causes can include bad data,
user intervention, hard error, and many other possibilities.

$$TM

Check if TaskMan is Running.  Usage: S X=$$TM^%ZTLOAD

VARIABLES	TYPE	VARIABLES DESCRIPTION
X	Output	If TaskMan is running on the current volume set, 1 is returned; otherwise 0 is returned.

$$PSET(ztsk)

Sets a task as persistent.  A task that is marked as
persistent will be restarted if the Taskmaster finds that the lock on
^%ZTSCH("TASK",tasknumber) has been removed.  This adds the requirement that
the task only use incremental locks, that the entry in ^%ZTSK(task...  be left
in place as this will be used to restart the task, and that the task can be
restarted from the data that is in the ^%ZTSK(task,... global.

Returns 1 if the flag was set, otherwise returns 0.

VARIABLES	TYPE	VARIABLES DESCRIPTION
ZTSK	Input	The task number.
&

PCLEAR(ztsk)

Clears the persistent flag for a task

VARIABLES	TYPE	VARIABLES DESCRIPTION
ztsk	Input	(required) The TaskMan task number.

$$JOB(ztsk)

This extrinsic function returns the job number for a
running TaskMan task.

Format: $$JOB^%ZTLOAD(ztsk)

VARIABLES	TYPE	VARIABLES DESCRIPTION
ztsk	Input	Task Number
$$JOB	Output	Returns the job number for the specified running TaskMan task. If the specified task is not running, it returns null.

DESC

This API finds tasks with a specific description.

VARIABLES	TYPE	VARIABLES DESCRIPTION
description	Input	(required) The TaskMan task description.
list	Output	Returns a list of task(s) with the specified description.

$$ASKSTOP(ztsk)

This extrinsic function asks TaskMan to stop running
a specified task. Also, it checks for the ZTNAME variable, and if defined, it
uses it instead of DUZ to value the STOP FLAG field (#59.1). ZTNAME is
supported by applications calling this API to indicate the process that asked
the task to stop.

VARIABLES

TYPE

VARIABLES DESCRIPTION

output

Output

Returns:

* 0-"Busy". If it returns "Busy" it could mean that the task is locked,
someone else is changing it, or TaskMan is starting to run it.

* 1-"Task missing" or Task "Finished running". If it returns "Task
missing" it could mean that it was an incorrect input task number, but it is
most likely that the task ran and was removed after running.

If it returns "Finished running" it means that the task was finished
running before the API request could go through, so the API could not stop an
already finished task.

* 2-"Asked to stop" or "Unscheduled". If it returns "Asked to Stop" the
task has started running and the stop flag has been set, so if the application
checks ($$S^%ZTLOAD) it should stop.

If it returns "Unscheduled" it was successful and the task is not
scheduled any more.

OPTION(option,list)

This API finds TaskMan tasks for a specific option.

VARIABLES	TYPE	VARIABLES DESCRIPTION
option	Input	(required) The name of the specific option.
list	Output	Returns a list of TaskMan task(s) for the specified option.

RTN(routine,list)

This API finds TaskMan tasks that call a specific
routine.

VARIABLES	TYPE	VARIABLES DESCRIPTION
routine	Input	(required) The name of the specific routine called.
list	Output	Returns a list of TaskMan task(s) that call the specified routine.

ZTSAVE(strvar,kill)

This API stores a string of variables in the ZTSAVE
array.

VARIABLES	TYPE	VARIABLES DESCRIPTION
strvar	Input	(required) Sting of variable names to be stored in the ZTSAVE array.
kill	Input	(optional) Any positive value will first KILL the ZTSAVE array.
ZTSAVE	Output	Stores the string of input variables in the ZTSAVE array.

DATE ACTIVATED

2009/07/08