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

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

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

Description

The $$QQ^XUTMDEVQ extrinsic function encapsulates the logic to handle direct queuing in a single call. This extrinsic function does a double queuing:

If it takes 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.

NOTE: This API was released with Kernel Patches XU*8.0*275 and updated with Kernel Patch XU*8.0*389.

Format

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

Input Parameters

%rtn:

(required) First task that TaskMan runs, 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 any of the following:

  • "LABEL^ROUTINE"

  • "^ROUTINE"

  • "ROUTINE"

The [tag]^routine that TaskMan runs.
%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 is used to SET ZTSAVE(). It can be a string of variable names separated by ";". Each ;-piece is 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, and 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 is 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; is added.
%wr:

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

(required) Second task that TaskMan runs, usually a print process (i.e., print data). The API that TaskMan will DO to start the task. You can specify it as any of the following:

  • "LABEL^ROUTINE"

  • "^ROUTINE"

  • "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 is used to S ZTSAVE(). It can be a string of variable names separated by ";". Each ;-piece is 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, and ZTSAVE. For example:

  %VOTH("ZTDTH")==$H

NOTE: If %voth1("ZTDTH") is passed, it is 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. You do not want the device that the user selects to be tied up for that time, so you divide the job into two tasks. The first task gathers the information, and the second task prints it. Use $$QQ^XUTMDEVQ to select the device, schedule the gather task, and queue the print task. 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