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

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

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

Description

The $$DEV^XUTMDEVQ extrinsic function encapsulates the logic to handle direct (forced) queuing in a single call and prompts users for a device.

NOTE: This API was released with Kernel Patch XU*8.0*275.

Format

  $$DEV^XUTMDEVQ(ztrtn[,ztdesc][,%var][,%voth][,%zis][,iop][,%wr])

Input Parameters

ztrtn:

(required) The API that TaskMan will DO to start the task. You can specify it as any of the following:

  • "LABEL^ROUTINE"

  • "^ROUTINE"

  • "ROUTINE"
ztdesc:

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

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

(optional) 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.
iop:

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

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

Output Parameter

returns:

Returns:

  • 0—If run ZTRTN without queuing.

  • -1—If unsuccessful device call or failed the %XTLOAD 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:

  1. The first task gathers the information.

  2. The second task prints it.

Use the following APIs:

  1. $$DEV^XUTMDEVQ API to select the device and queue up the print task.

  2. $$NODEV^XUTMDEVQ API to schedule the gather task.

  3. 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
         ;;1.1
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
         Q:X<1
         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.
         S X=$$NODEV^XUTMDEVQ("GATHER^ARHBQQ","ARHB Gather","ARHZTSK",.ARH,1)
         W !,"X=",X
         Q