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

$$DEV^XUTMDEVQ(): Force Queuing—Ask for Device

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


(Added with Kernel Patch XU*8.0*275.) This extrinsic function encapsulates the logic to handle direct (forced) queuing in a single call and prompts users for a device.



Input Parameters


(required) The API that TaskMan will DO to start the task. You can specify it as "LABEL^ROUTINE" or "^ROUTINE" or "ROUTINE".


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


(optional) ZTSAVE values for the 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.


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


(optional) Default value "MQ". Passed by reference, standard %zis variable array for calling the Device Handler.


(optional) The IOP variable as defined in Kernel's Device Handler.


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

Output Parameter



  • 0—If run ztrtn without queuing.

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


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 $$DEV^XUTMDEVQ API to select the device and queue up the print task, and the $$NODEV^XUTMDEVQ API to schedule the gather task. We use the REQ^%ZTLOAD API to schedule the print task when the gather task finishes.

NOTE: You could also use the $$REQQ^XUTMDEVQ API to schedule the print task.

ARHBQQ   ;SFVAMC/GB - Demo of 'gather' and 'print' in 2 tasks ;1/19/06  08:31
DEV      ;
         N ARH,ARHZTSK,X
         ;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 ARH("ZTDTH")="@" ;Don't schedule the task to run, we'll do it later.
         ;In the following, the "Q" sets IOP=Q, which forces queuing.
         S X=$$DEV^XUTMDEVQ("PRINT^ARHBQQ","ARHB Print",,.ARH,,"Q",1)
         W !,"X=",X
         N ARH
         ;Now queue the first task, the "gather" portion of the job.  The user
         ;won't be asked any questions.
         S ARHZTSK=X ; Save the ZTSK number of the "print" task.
         S ARH("ZTDTH")=$H ; Force the task to start now.
         ;To ask the user the start time, comment out the above line.
         W !,"X=",X


VA (Internet) / VA(Intranet) / OI / PD / Site Map / Terms of Use / VA Privacy Policy / Accessibility

Reviewed/Updated: August 26, 2011

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.