Kernel V. 8.0 APIs Banner [skip navigation]
VHA Office of Information - Health Systems Design and Development (HSD&D) Banner

$$QQ^XUTMDEVQ(): Double Queue—Direct Queuing in a Single Call

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

Description

(Added with Kernel Patch XU*8.0*275 and updated with Kernel Patch XU*8.0*389.) This extrinsic function encapsulates the logic to handle direct queuing in a single call. This extrinsic function does a double queuing:

If it will take a long time to gather and print data, users should split the job into two tasks:

  1. Gather Data—The first task gathers the data.

  2. Print Data—The second task prints the data.

Separating the data gathering task from the data print task helps avoid unnecessarily tying up a printer while large amounts of data are gathered.

The task number of the second task (i.e., print data) is added to the saved variables with the name XUTMQQ. This makes it easier to schedule the second task when the first task (i.e., gather data) has finished.

To schedule the second task to run at the end of the first task, you must call the $$REQQ^XUTMDEVQ API.

Format

  $$QQ^XUTMDEVQ(%rtn[,%desc][,%var1][,%voth1][,%zis][,iop][,%wr],
%rtn2[,%desc2][,%var2][,%voth2])

Input Parameters

%rtn:

(required) First task that TaskMan will run, usually a search and build sorted data type process (i.e., gather data). The API that TaskMan will DO to start the task. You can specify it as "LABEL^ROUTINE" or "^ROUTINE" or "ROUTINE". [tag]^routine that TaskMan will run.
%desc:

(optional) First task description, up to 200 characters describing the task, with the software application name at the front. Defaults to name of [tag]^routine.
%var1:

(optional) ZTSAVE values for the first task. Single value or passed by reference, this will be used to SET ZTSAVE(). It can be a string of variable names separated by ";". Each ;-piece will be used as a subscript in ZTSAVE.
.%voth1:

(optional) First task other parameter. Passed by reference, %voth(sub)="" or explicit value sub—this is any other %ZTLOAD variable besides ZTRTN, ZTDESC, ZTIO, ZTSAVE. For example:

  %VOTH("ZTDTH")==$H
%zis:

(optional) Default value "MQ". Passed by reference, standard %ZIS variable array for calling the Device Handler. Except for one difference, the second task of the job will be tasked to this device call.

Exception:

  • IF $D(%ZIS)=0 then default value is "MQ" and call the Device Handler.

  • IF $D(%ZIS)=1,%ZIS="" then queue the second task also with ZTIO="" (i.e., do not do the Device Handler call).
iop:

(optional) The IOP variable as defined in Kernel's Device Handler. Default value "Q"—if IOP is passed and IOP does not start with "Q;" then "Q;" will be added.
%wr:

(optional) If %WR>0 then write text to the screen as to whether or not the queueing was successful.
%rtn2:

(required) Second task that TaskMan will run, usually a print process (i.e., print data). The API that TaskMan will DO to start the task. You can specify it as "LABEL^ROUTINE" or "^ROUTINE" or "ROUTINE".
%desc2:

(optional) Second task description, up to 200 characters describing the task, with the software application name at the front. Default to name of [tag]^routine.
%var2:

(optional) ZTSAVE values for the second task. Single value or passed by reference, this will be used to S ZTSAVE(). It can be a string of variable names separated by ";". Each ;-piece will be used as a subscript in ZTSAVE.

  • If %var1 is not passed and $D(%VAR), then also send %VAR data to the second task.

  • If $D(%VAR1), then do not send %VAR data to the second task.
.%voth2:

(optional) Second task other parameter, usually not needed. Passed by reference, %voth(sub)="" or explicit value sub—this is any other %ZTLOAD variable besides ZTRTN, ZTDESC, ZTIO, ZTSAVE. For example:

  %VOTH("ZTDTH")==$H

NOTE: If %voth1("ZTDTH") is passed, it will be ignored as it is necessary to S ZTDTH="@" for the second task—this creates the task but does not schedule it.

Output

returns:

Returns:

  • ztsk1^ztsk2—If successfully queued:
    • ztsk1 = ZTSK value of first task.

    • ztsk2 = ZTSK value of second task.

  • -1—If unsuccessful device call or failed the %ZTLOAD call.

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 $$QQ^XUTMDEVQ to select the device, schedule the gather task, and queue the print task. We use the $$REQQ^XUTMDEVQ API to schedule the print task when the gather task finishes.

NOTE: This is the easiest way to divide a job into two tasks.

ARHBQQ   ;SFVAMC/GB - Demo of 'gather' and 'print' in 2 tasks ;1/19/06  08:31
         ;;1.1
QQ       ;
         N X
         S X=$$QQ^XUTMDEVQ("GATHERQ^ARHBQQ","ARHB Gather",,,,,1,"PRINTQ^ARHBQQ","ARHB Print")
         W !,"X=",X
         Q
GATHERQ  ;
         N ARHJ,X
         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!
         ; XUTMQQ holds the ZTSK of the print task
         S X=$$REQQ^XUTMDEVQ(XUTMQQ,$H,"ARHJ") ; Schedule print task to start
         Q
PRINTQ   ;
         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

 

VA (Internet) / VA (Intranet) / OI / HSD&D / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: January 20, 2006

If you have questions, need more information, or are having accessibility problems with this website, please contact us by E-Mail: Webmasters, Phone: 510-768-6800, or FAX: 510-768-6850.