^%ZTLOAD: Queue a Task

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

Description

^%ZTLOAD is the main API used to create and schedule tasks (commonly referred to as "queuing"). Queuing tells TaskMan to use a background partition to DO a certain API at a certain time, with certain other conditions established as described by the input variables.

This API, as used in code, behaves consistently so most queuers strongly resemble one another. The queuer can be written so that it is either interactive with the user or so that it is not interactive. The standard variations on this structure deserve attention.

Format

  ^%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 Variables

Interactive Use of ^%ZTLOAD

The VistA Standards and Conventions require that anywhere you let a user pick the output device you also let the user choose to queue the output.

Often one part of the queuer is a call to ^%ZIS (the Device Handler). When you set up the variables for your call, include a "Q" in the variable ^%ZIS so the Device Handler will let the user pick queuing. After the Device Handler call (and after you check POP to ensure that a valid device was selected), you can check $DATA(IO("Q")) to see whether the user chose to queue to that device. If so, then you must queue the printout you were about to do directly, and your software should branch to the code to set up the task. A sample of the code for this kind of print queuer looks something like this:

SELECT	;select IO device for report
		S %ZIS="Q" D ^%ZIS
		I POP D CANCEL Q
		I $D(IO("Q")) D QUEUE Q
		D PRINT,^%ZISC Q
		;
QUEUE 	;queue the report
		S ZTRTN="PRINT^ZZREPORT"
		S ZTDESC="ZZ Application Daily Report 1"
		S ZTSAVE("ZZRANGE")=""
		D ^%ZTLOAD
		I $D(ZTSK)[0 W !!?5,"Report canceled!"
		E  W !!?5,"Report queued!"
		D HOME^%ZIS Q

The code to set up the task after the call to ^%ZIS has four steps. First, it sets the ^%ZTLOAD input variables to define the task. Second, it calls ^%ZTLOAD to queue the task. Third, it checks $DATA(ZTSK)#2 to find out whether a task was really queued and provides appropriate feedback. Fourth, it calls HOME^%ZIS to reset its IO variables.

NOTE: This queuer did not define ZTIO. Print queuers can take advantage of the fact that they directly follow a ^%ZIS call that sets up all the IO variables they need. Under these conditions, the queuer code can rely on ^%ZTLOAD to identify the task's IO device from the IO variables, thus, saving the programmer the work of building the correct ZTIO string.

Notice also that when queuing output, we need not call ^%ZISC to close the IO device because when the user chooses to queue output the Device Handler does not open the device. Thus, all we need to do here is reset our IO variables with a HOME^%ZIS call.

As usual in these kinds of queuers, we did not define ZTDTH, but instead let ^%ZTLOAD ask the user when the report should run.

Finally, notice that we tell the task to begin at PRINT, the same tag used by the trigger code to start the foreground print when the user chooses not to queue. Under most circumstances, print queuers can use most of the same code for their tasks that the foreground print uses.

Non-interactive Use of ^%ZTLOAD

Under certain conditions, queuers must create and schedule their tasks with no interaction with the user. Examples include queuers operating out of tasks or queuers that need to run without the users' knowledge. Only two items must be changed from interactive queuers to make non-interactive queuers work:

1. ZTDTH must be passed to ^%ZTLOAD, and must contain a valid date/time value.
   
   
2. If the code to queue the task does not follow a call to ^%ZIS, you must define ZTIO yourself. Either set it, or allow it to be built from the current I/O variables (if those I/O variables describe the proper device).

After the call to ^%ZTLOAD, you may (or may not) want to issue feedback messages.

Queuing Tasks Without an I/O Device

Certain tasks need no IO device. These include primarily tasks that rearrange large amounts of data but produce no report, such as filing and compiling tasks. Two different kinds of non-IO tasks exist:

• Concurrent—Those that can run concurrently.
  
  
• Sequential—Those that must run sequentially.

Queuers for concurrent non-IO tasks need only set ZTIO to NULL, and TaskMan will run the task, with no IO device.

For sequential non-IO tasks, queuers must set ZTIO to the name of a resource type device. TaskMan will then ensure that the tasks run single file, one after the other in order by requested start time. Applications that need sequential non-IO tasks should instruct system managers in the Package Installation Guide to create a resource device with the desired characteristics so that these queuers can safely queue their tasks to them. Such devices should be namespaced by the software application that uses them. SYNC FLAGs can also be used to allow the next task in a series to start only if the previous task in the series completed successfully.

NOTE: For more information on SYNC FLAGs, please refer to the "Using SYNC FLAGs to Control Sequences of Tasks" topic in the "TaskMan Programmer Tools" chapter inn the Kernel Programmer Manual.

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//