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

OPEN^%ZISUTL(): Open Device with Handle

Reference Type: Supported, Category: Device Handler, ICR#: 2119

Description

Use the OPEN^%ZISUTL API when you expect to be using multiple output devices. This API, as well as its two companion APIs: RMDEV^%ZISUTL(): Delete Data Given a Handle and CLOSE^%ZISUTL(): Close Device with Handle, makes use of handles to refer to a device. A handle is a unique string identifying the device.

The three ^%ZISUTL APIs are essentially wrappers around the ^%ZIS API. They provide enhanced management of IO variables and the current device, especially when working with multiple open devices. One of three functions that support using multiple devices at the same time.

REF: See also RMDEV^%ZISUTL(): Delete Data Given a Handle and CLOSE^%ZISUTL(): Close Device with Handle APIs.

Format

  OPEN^%ZISUTL(handle[,valiop][,.valzis])

Input Parameters

handle:

(required) A unique FREE TEXT name to associate with a device you want to open.
valiop:

(optional) Output device specification, in the same format as the IOP input variable for the ^%ZIS(): Standard Device Call API. The one exception to this is passing a value of NULL; this is like leaving IOP undefined. With ^%ZIS, on the other hand, setting IOP to NULL specifies the home device. To request the home device, pass a value of "HOME" instead.
valzis:

(optional) Input specification array, in the same format (and with the same meanings) as the %ZIS input specification array for the ^%ZIS(): Standard Device Call API. Must be passed by reference.

NOTE: For more information, see the ^%ZIS(): Standard Device Call API documentation.

Output Variables

IOF:

OPEN^%ZISUTL returns all the same output variables as the ^%ZIS(): Standard Device Call API. OPEN^%ZISUTL serves as a "wrapper" around the ^%ZIS API, providing additional management of IO output variables that ^%ZIS does not (principally to support opening multiple devices simultaneously).
IOM

 
IOSL

 
IO

 
IO(0)

 
IO("Q")

 
IO("S")

 
IO("DOC")

 
IO("SPOOL")

 
IO("ZIO")

 
IO("HFSIO")

 
IO(1,$I)

 
IOST

 
IOST(0)

 
IOT

 
ION

 
IOBS

 
IOPAR

 
IOUPAR

 
IOS

 
IOHG

 
IOXY

 
POP

 

Example

ZXGTMP  ; ISC-SF/doc %ZISUTL sample ;11-oct-94
        ;;1.0;;
EN      ;
        K A6AZIS S A6AZIS("A")="Enter the printer to output first 40 chars in each line: "
        D OPEN^%ZISUTL("PRT1","",.A6AZIS) Q:POP
        K A6AZIS S A6AZIS("A")="Enter the printer to output chars 41
to end of line: "
        D OPEN^%ZISUTL("PRT2","",.A6AZIS) I POP D CLOSE^%ZISUTL("PRT1") Q
        S I=""  F  S I=$O(^TMP($J,"DOC",I)) Q:I']""  S X=^(I) D
        .D USE^%ZISUTL("PRT1") U IO W $E(X,1,40),!
        .D USE^%ZISUTL("PRT2") U IO W $E(X,41,$L(X)),!
        D CLOSE^%ZISUTL("PRT1"),CLOSE^%ZISUTL("PRT2")
        Q