Reference Type: Supported, Category: TaskMan, Integration Agreement: 10063
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
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.
Make sure to perform the following steps before calling this API:
(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.
(optional) New description for the task. It should describe the task and name the software application that created the task.
(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 will not be rescheduled.
(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 it is not passed, the originally requested I/O device is used.
(optional) API for TaskMan to use for the task. If it is not passed, the original API is used.
(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.
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
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
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.
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
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
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//
August 26, 2011