Kernel APIs: EN^XUTMDEVQ

EN^XUTMDEVQ(): Run a Task (Directly or Queued)

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

Description

The EN^XUTMDEVQ API encapsulates the logic to handle both direct printing and queuing in a single call.

EN^XUTMDEVQ calls ^%ZIS to query the user for device selection. The user can choose a device on which to run the job directly or choose to queue the job.

After calling ^%ZIS, EN^XUTMDEVQ looks to see if the queuing was chosen. If so, EN^XUTMDEVQ uses the values from the ztrtn, ztdesc, and ztsave input parameters to queue the job to the chosen device. If the user did not choose to queue, EN^XUTMDEVQ runs the job directly using the ztrtn input parameter. Thus, EN^XUTMDEVQ provides a simple way to facilitate both queuing and running a job directly.

If the IOP variable is defined before calling EN^XUTMDEVQ, it has the same effect as it does if defined before a ^%ZIS call.

If the ZTPRI or ZTKIL variables are defined before calling EN^XUTMDEVQ, they have the same effect as they do if defined before an ^%ZTLOAD call. Other ^%ZTLOAD input variables have no effect, however.

You do not need to "USE IO" in the routine specified in the ztrtn input parameter; IO is the current device, whether the job is queued or run directly. Also, you do not need to pass Q in the top-level of the %ZIS input array; if the top-level of the array does not contain Q, Q is appended to it (to allow queuing).

Format

  EN^XUTMDEVQ(ztrtn,ztdesc,.ztsave[,.%zis][,retztsk])

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:	(required) Task description, up to 200 characters describing the task, with the software application name at the front.
.ztsave:	(required) Pass by reference. Set up this array in the same format as the ztsave input array is set up for the ^%ZTLOAD TaskMan API. The array you set up in ztsave is passed directly as ztsave to TaskMan if the user chooses to queue the job.
.%ZIS:	(optional) Pass by reference. String containing input specifications for the Device Handler. Set up the array in the same way as the %ZIS array is set up for the ^%ZIS Standard Device Call API. The array you set up in the %zis input parameter is passed directly as %ZIS to the Device Handler. All %ZIS subscripts from the regular ^%ZIS call ("A", "B", "HFSMODE", etc.) can be passed in the %ZIS input array.
retztsk:	(optional) This is the return task number (i.e., ZTSK). Put a number in this parameter, such that $G(RETZTSK), then ZTSK exists as an output variable. Otherwise, ZTSK does not exist as an output variable.

Output Variable

ZTSK:

If a number is entered in the retztsk input parameter, the task number assigned to a task is returned.

Example

Sample report:

ZZYZOPT     ;ISC-SF/doc 
     ;;1.0;;
EN   ;
     N ZZEN K X,DIC S DIC=9.6,DIC(0)="AEMO" D ^DIC
     Q:+Y'>0  S ZZEN=+Y
     ;
     K ZTSAVE S ZTSAVE("ZZEN")=""
     D EN^XUTMDEVQ("P^ZZYZOPT","Print from BUILD File",.ZTSAVE)
     Q
P    ;
     ; code for printout
     ;
     W !,"Here goes the body of the report!"
     W !,"ZZEN = ",ZZEN
     Q