REQ^%ZTLOAD: Requeue a Task

Reference Type: Supported, Category: TaskMan, Integration Agreement: 10063

Description

This 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, programmers 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 of the following variables.
   
   
2. Set the input variables you want changed.
   
   
3. Call the API.

If you do not follow these steps, the variables could unintentionally assume the values of the variables of the current running task.

Input Variables

Output Variable

Example

This example is a job that consists of gathering information and then printing it. Assume that the gathering takes a few hours. We do not want the device that the user selects to be tied up for that time, so we divide the job into two tasks. The first task gathers the information and the second task prints it. We use the ^%ZIS API to select the device, the ^%ZTLOAD API to queue the print task, and the ^%ZTLOAD API to schedule the gather task. We 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//