Kernel 8.0 APIs Banner
Office of Information and Technology (OIT) Banner
[skip navigation]

REQ^%ZTLOAD: Requeue a Task

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

Description

The REQ^%ZTLOAD API unschedules, edits, and reschedules a task. Unscheduling ensures the task is not pending but does not stop it from running. Editing is limited to the API, start time, description, and I/O device. Rescheduling is optional. However, if the task is not rescheduled, it is vulnerable to the Task File Cleanup option. The entire procedure is referred to as requeuing.

CAUTION: Because requeuing does not involve stopping a running task, it is possible to wind up with the same task running in two different partitions if the algorithm is not designed carefully. This is not supported by TaskMan; thus, developers should use requeuing very carefully. Queuing a new task is usually a better way to accomplish the same goals.

NOTE: Tasks can reschedule themselves through use of the ZTREQ output variable.

Format

  REQ^%ZTLOAD

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

  1. NEW all non-namespaced variables.

  2. Set all input variables.

  3. Call the API.

Input Variables

ZTSK:

(required) The task number of the task to edit. It must be defined on the current volume set for the edit to succeed. It is strongly recommended that this task not be currently running.
ZTDESC:

(optional) New description for the task. It should describe the task and name the software application that created the task.
ZTDTH:

(optional) New start time for the task. Pass this as a date and time in VA FileMan or $HOROLOG format. If not passed, the original start time is used again. If passed as @, the task is not rescheduled.

The ZTDH input variable can also be passed as a rescheduling code. This code is a number followed by an S (seconds), an H (hours), or a D (days). This code represents an interval of time (e.g., 60S is 60 seconds) that is added to the current time (for seconds or hours) or the original start time (for days) to produce the new start time.
ZTIO:

(optional) New I/O device for the task. It is used to set IOP in the ^%ZIS API, and can take all of IOP's format specification strings.

If the ZTIO variable is set to @, the task is rescheduled for no I/O device.

If the ZTIO variable is set to NULL or it is not passed, the originally requested I/O device is used.

  • ZTIO("H")—If not set, it is set to the value of the IO("HFSIO") variable in the ^%ZIS API.

  • ZTIO("P")—If not set, it is set to the value of the IOPAR variable in the ^%ZIS API.
ZTRTN:

(optional) The API TaskMan will DO to start the task. You can specify it as any of the following:

  • "LABEL^ROUTINE"

  • "^ROUTINE"

  • "ROUTINE"

If it is not passed, the original API is used.
ZTSAVE:

(optional) Input variable array. An array whose nodes specify input variables to the task beyond the usual set all tasks receive. It is set up in the same format as the ZTSAVE input variable for the ^%ZTLOAD API.

Output Variable

ZTSK(0):

Returns:

  • 1—Task is defined.

  • 0—Task is not defined or ZTDTH was passed in a bad format.

Example

This example is a job that consists of gathering information and then printing it. Assume that the gathering takes a few hours. You do not want the device that the user selects to be tied up for that time, so divide the job into two tasks:

Use the ^%ZIS API to select the device, the ^%ZTLOAD API to queue the print task and schedule the gather task. Use the REQ^ZTLOAD API to schedule the print task when the gather task finishes.

NOTE: This process is made easier by using the $$QQ^XUTMDEVQ and $$REQQ^XUTMDEVQ APIs.

Sample Code:

ARHBQQ   ;SFVAMC/GB - Demo of 'gather' and 'print' in 2 tasks ;1/19/06  08:31
         ;;1.1
ZTLOAD   ;
         N ARH,ARHZTSK,X,ZTSAVE,%ZIS,ZTSK,ZTDTH,ZTRTN,ZTDESC,ZTIO,POP
         W !,"Queue the second task (the print task) first.",!
         ;Let's deal with the second task first.
         ;The user doesn't know it, but he's actually queuing the second task,
         ;the "print" portion of the job.  The only question the user will be
         ;asked is to select the device.
         ;
         S %ZIS="QM"
         S IOP="Q" ;Force queuing.
         D ^%ZIS Q:POP  ; Select Device
         W !,"Finished with %ZIS."
         ;
         S ZTDTH="@" ;Don't schedule the task to run, we'll do it later
         ;If we didn't need to set ZTDTH, we could use EN^XUTMDEVQ, but that
         ;API 'new's ZTDTH, so we can't set it.
         ;
         ;BTW, Did you know that there's a 5th parameter in EN^XUTMDEVQ?
         ;Usually, EN^XUTMDEVQ will 'new' ZTSK, so you can't get to it.
         ;If you put "1" as the 5th parameter, ZTSK will exist when EN returns.
         ;D EN^XUTMDEVQ("PRINT^ARHBQQ","ARHB Print",.ZTSAVE,.%ZIS,1)
         ;
         S ZTRTN="PRINT^ARHBQQ"
         S ZTDESC="ARHB Print"
         D ^%ZTLOAD
         D HOME^%ZIS
         W !,"ZTSK=",$G(ZTSK)
         Q:'$D(ZTSK)
         S ARHZTSK=ZTSK
         ;
         N ZTSAVE,%ZIS,ZTSK,ZTDTH,ZTRTN,ZTDESC,ZTIO,IOP
         W !,"Now queue the first task (the gather task).",!
         ;Now queue the first task, the "gather" portion of the job.
         ;Since we don't need a device,
         ;the user will only be asked when to start the task.
         ;(I wasn't able to get EN^XUTMDEVQ to work for me.  I tried setting
         ;IOP="Q;" to let it know that it should be queued and it didn't need
         ;a device, but it did nothing, and returned a null ZTSK.)
         F I="ARHZTSK" S ZTSAVE(I)="" ; Save the ZTSK of the "print" task.
         S ZTIO="" ; We don't need a device.
         S IOP="Q" ; Force queuing.
         S ZTRTN="GATHER^ARHBQQ"
         S ZTDESC="ARHB Gather"
         D ^%ZTLOAD
         D HOME^%ZIS
         W !,"ZTSK=",$G(ZTSK)
         Q
GATHER   ;
         N ARHJ
         S ZTREQ="@"
         S ARHJ="ARHB-QQ"_"-"_$J_"-"_$H ; namespace + unique ID
         K ^XTMP(ARHJ) ; Use ^XTMP to pass a lot of data between tasks.
         S ^XTMP(ARHJ,0)=$$FMADD^XLFDT(DT,1)_U_DT ; Save-thru and create dates.
         S ^XTMP(ARHJ)="HI MOM!" ; Pretend this is a lot of data.
         D SPRINT
         Q
SPRINT   ; Now schedule the "print" task to run.
         N ZTSK,ZTDTH,I,ZTRTN,ZTDESC,ZTIO,ZTSAVE ; Very important to NEW the
         ; input variables to REQ^%ZTLOAD, otherwise they retain the values of
         ; the currently running task, and you could unintentionally change the
         ; "print" task to rerun the "gather" task.
         F I="ARHJ" S ZTSAVE(I)="" ; Let the "print" task know the "$J" value.
         S ZTSK=ARHZTSK
         S ZTDTH=$H
         D REQ^%ZTLOAD
         ;Instead of the above 8 lines we could have simply:
         ;S X=$$REQQ^XUTMDEVQ(ARHZTSK,$H,"ARHJ")
         Q
PRINT    ;
         S ZTREQ="@"
         U IO ; Don't need this if invoked using a ^XUTMDEVQ API.
         W !,"The secret message is: '",$G(^XTMP(ARHJ)),"'"
         K ^XTMP(ARHJ)
         Q

 

Code Execution:

VAH>D ZTLOAD^ARHBQQ
     
Queue the second task (the print task) first.
QUEUE TO PRINT ON
DEVICE: HOME// P-MESS

 1 P-MESSAGE-ENGWO-HFS-VXD   HFS FILE ==> MAILMESSAGE
 2 P-MESSAGE-HFS-VXD   HFS FILE ==> MAILMESSAGE
Choose 1-2> 2 <Enter>  P-MESSAGE-HFS-VXD  HFS FILE ==> MAILMESSAGE

Subject: MY PRINT

     Select one of the following:

          M         Me
          P         Postmaster

From whom: Postmaster// <Enter>
Send mail to: KRNUSER,ONE// <Enter>  KRNUSER,ONE
Select basket to send to: IN// <Enter>
And Send to: <Enter>
Finished with %ZIS.
ZTSK=2921497
Now queue the first task (the gather task).

Requested Start Time: NOW// <Enter>  (JAN 25, 2005@11:30:35)
ZTSK=2921499

 

Output:

Subj: MY PRINT  [#28881111] 01/25/05@11:30  2 lines
From: POSTMASTER (Sender: BEUSCHEL,GARY - COMPUTER SPECIALIST)  In 'IN' 
basket.
Page 1  *New*
-------------------------------------------------------------------------------

The secret message is: 'HI MOM!'

Enter message action (in IN basket): Ignore//