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

^%ZIS: Standard Device Call

Reference Type: Supported, Category: Device Handler, Integration Agreement: 10086

Description

This API allows you to select a device.

All input variables are optional. Non-namespaced variables that are defined and later KILLed by ^%ZIS include: %A, %E, %H, %X, and %Y.

If device selection is successful, characteristics of the output device are returned in a number of different variables. If selection is unsuccessful, ^%ZIS returns the POP output variable with a positive number. So, checks for an unsuccessful device selection should be based on the POP input variable as a positive number.

Device selection can be done as shown in the example that follows.

NOTE: For a discussion of form feeds, please refer to the "Form Feeds" topic in the "Special Device Issues" chapter in the Kernel Developer's Guide.

Format

  ^%ZIS

Input Variables

%ZIS:

(optional) The %ZIS input variable is defined as a string containing one or more single-character flags that act as input specifications. The functions of each of the flags that can be included in the string are described below. If the %ZIS variable contains:

  • M—RIGHT MARGIN: The user will be prompted with the right margin query.

  • N—NO OPENING: The Device Handler will return the characteristics of the selected device without issuing the OPEN command to open the device.

  • P (obsolete)—CLOSEST PRINTER: The closest printer, if one has been defined in the DEVICE file (#3.5), will be presented at the default response to the device prompt.

  • Q—QUEUING ALLOWED: The job can be queued to run at later. There is no automatic link between the Device Handler and the TaskMan. If queuing is allowed, just before the Device Handler is called, the application routine must set the %ZIS variable to a string that includes the letter "Q". For example:
      >S %ZIS="MQ" D ^%ZIS
    If the user selects queuing, the Device Handler will define the IO("Q") variable as an output variable, to indicate that queuing was selected. If queuing is selected, the application should set the needed TaskMan variables and call the TaskMan interface routine ^%ZTLOAD.

    NOTE: For further details on how to call the TaskMan interface, please refer to the "TaskMan: Programmer Tools" chapter in the Kernel Developer's Guide.

  • 0—DON'T USE IO(0): The Device Handler will not attempt to use IO(0), the home device at the time of the call to ^%ZIS.

  • D—DIRECT PRINTING: If the selected device is unavailable, it returns a positive number in POP.

  • L—RESET IO("ZIO"): If %ZIS contains L, the IO("ZIO") output variable will be reset with the static physical port name (e.g., the port name from a terminal server). It is useful when the $I of the M implementation.
%ZIS("A"):

(optional) Use this variable to replace the default device prompt.

%ZIS("B"):

(optional) If %ZIS is defined, HOME is presented as the default response to the device prompt. Use %ZIS("B") to replace this default with another response.

>S %ZIS("B")=""
(If you do not want to display any default response.)
%ZIS("HFSMODE"):

(optional) Use this variable to pass the Host file access mode to %ZIS. A value of "RW", which may not work in all environments, represents READ/WRITE access, "R" represents READ Only access, "W" represents WRITE access, and "A" represents Append mode. For example:

>S  %ZIS("HFSMODE")="R"
%ZIS("HFSNAME"):

(optional) Use this variable to pass the name of a Host file to %ZIS. For example:

>S  %ZIS("HFSNAME")="MYFILE.DAT"
%ZIS("IOPAR"):

(optional) Use this input variable to pass open command variables to the Device Handler. If defined, the value of this input variable is used instead of any value specified in the OPEN PARAMETERS field of the DEVICE file (#3.5). The Device Handler uses the data from either this input variable or from the OPEN PARAMETERS field whether or not the device type is TRM.

On some M systems, Right Margin is an OPEN PARAMETERS. Therefore, any value for Right Margin in the DEVICE file (#3.5), TERMINAL TYPE file (#3.2), or user response can be ignored when this variable is used.

To set OPEN PARAMETERS for the tape drive device, a device with $I=47 and device name of MAGTAPE, the following code could be used:

>S %ZIS("IOPAR")="(""VAL4"":0:2048)"

>S IOP="MAGTAPE" D ^%ZIS

NOTE: The specific variables you pass may not be functional for all operating systems. Use of this feature should be limited to local development efforts.

%ZIS("IOUPAR"):

(optional) Use this input variable in the same way as %ZIS("IOPAR"), but for variables to the USE (rather than OPEN) command. Any USE PARAMETERS specified in the DEVICE file (#3.5) will be overridden. For example:

>S %ZIS("IOUPAR")="NOECHO"

>S IOP="C72" D ^%ZIS
%ZIS("S"):

(optional) Use this variable to specify a device selection screen. The string of M code this variable is set to should contain an IF statement to set the value of $T. Those entries that the IF sets as $T=0 will not be displayed or selectable. Like comparable VA FileMan screens, %ZIS("S") should be set to sort on nodes and pieces, without using variables like ION or IOT. As with VA FileMan, the variable "Y" can be used in the screen to refer to the Internal Entry Number (IEN) of the device. Also, the M naked indicator is at the global level ^%ZIS(1,Y,0). An example to limit device selection to spool device types (SPL) only might be coded as follows:

>S %ZIS("S")="I $G(^(""TYPE""))=""SPL"""
IOP:

(optional) Use the IOP variable to specify the output device. There is no user interaction when IOP is defined to specify an output device; the device name (.01 field) is the usual value of IOP. You can also set IOP to Q and P. (The value of IOP must not be $I).

You can request queuing by setting IOP="Q". The user is then asked to specify a device for queuing. To pre-select the device, set IOP="Q;device"; the device specified after the semicolon is selected and IO("Q") is set.

You can request the closest printer, as specified in the DEVICE file (#3.5), by setting IOP="P" or IOP="p". If there is not a closest printer associated with the home device at the time of the call, device selection fails and POP is returned with a positive value.

You can now also pass the Internal Entry Number (IEN) of the desired device through IOP. For instance, to select a device with an IEN of 202, you can set IOP to an accent grave character followed by the IEN value of 202 before the call to ^%ZIS. The following example illustrates the above call:

>S IOP="`202" D ^%ZIS

Using the IEN rather than device name can be useful when applications have the desired device stored as a pointer to the DEVICE file (#3.5) rather than as FREE TEXT.

Output Variables

IO:

If a device is successfully opened, IO is returned with the device $I value of the selected device. If an abnormal exit occurs, POP is returned with a positive numeric value and IO is returned as NULL.

CAUTION: Because the returned value of IO can be changed, since December 1990, developers have been advised to check for a positive value in POP rather for IO equal to NULL when determining if an abnormal exit occurred.

IO(0):

HOME DEVICE—Contains the $I value of the home device at the time of the call to the Device Handler. Since it is defined at the time of the call, there is obviously no restoration after the call.

IO(1,$I):

OPENED DEVICES—This array contains a list of devices opened for the current job by the Device Handler. The first subscript of this array is "1". The second subscript is the $I value of the device opened. The data value is NULL. The Device Handler sets, KILLs, and checks the existence of IO(1,IO).

NOTE: This array should not be altered by applications outsideof Kernel.

IO("CLNM"): This variable holds the name of the remote system. It is defined via the RPC Broker.
IO("CLOSE"):

Device closed.

IO("DOC"):

SPOOL DOCUMENT NAME—If output has been sent to the spool device, this output variable holds the name of the spool document that was selected.

NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS.

IO("HFSIO"):

HOST FILE DEVICE IO—This is defined by the Device Handler when a user queues to a file at the host operating system level (of a layered system) and selects a file name other than the default. This Host file system device variable should have the same value as that stored in the IO output variable. If IO("HFSIO") exists when the TaskMan interface is called, the interface will save IO("HFSIO") and IOPAR so that the scheduled task opens the appropriate Host file.

NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS.

IO("IP"): This variable holds the Internet Protocol (IP) of the remote system.
IO("P"):

This variable holds data about the new syntax requested.

IO("Q"):

OUTPUT WAS QUEUED—If queuing is allowed (%ZIS["Q") and an output device for queuing is selected, this output variable is returned with a value of 1: IO("Q")=1. Otherwise, it will be undefined.

NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS.

IO("S"):

SLAVED DEVICE—When a slaved printer is selected, the Device Handler uses this output variable to save the subtype specification for the home device so that the appropriate close printer logic can be executed with X ^%ZIS("C").

IO("SPOOL"):

SPOOLER WAS USED—The existence of this output variable indicates that output was sent to the spool device. It will exist temporarily, during spooling, and is KILLed upon normal exit.

NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS.

IO("T"):

TaskMan call.

IO("ZIO"):

TERMINAL SERVER PORT—If %ZIS["L", both physical port and server names are returned in IO("ZIO") under DSM for OpenVMS and MSM-DOS. This information is useful on M implementations where the value of $I does not represent a port on a terminal server.

IOBS:

BACKSPACE—The code for backspace, usually $C(8), is returned in this output variable. This code is used to WRITE a backspace with W @IOBS.

IOCPU:

CPU INDICATOR—If the selected device is on another CPU, this output variable is returned with the other CPU reference, obtained from the VOLUME SET (CPU) field in the DEVICE file (#3.5). The IOCPU input variable is used by TaskMan as an indicator of where the job should ultimately be run.

IOF:

FORM FEED—This output variable is used to issue a form feed when writing its value with indirection; that is, W @IOF.

IOM:

RIGHT MARGIN—The right margin is commonly set to either 80 or 132 columns.

ION:

DEVICE NAME—This variable returns the device NAME (.01 field) as recorded in the DEVICE file (#3.5).

IOPAR:

OPEN PARAMETERS—This variable returns any OPEN PARAMETERS that may have been defined for the selected device, for example, a magnetic tape drive. If the OPEN PARAMETERS variable has not been defined, IOPAR is returned as NULL.

NOTE: When a device is closed, this variable gets set to null.

IOUPAR:

USE PARAMETERS—This variable returns any USE PARAMETERS that may have been defined for the selected device. If the USE PARAMETERS variable has not been defined, IOUPAR is returned as NULL.

NOTE: When a device is closed, this variable gets set to null.

IOS:

DEVICE NUMBER—The DEVICE file (#3.5) Internal Entry Number (IEN) for the selected device.

IOSL:

SCREEN/PAGE LENGTH—The number of lines per screen or page is defined with this variable. The page length of a printing device is usually 66 lines. The screen length of a display terminal is usually 24 lines.

IOST:

SUBTYPE NAME—This variable returns the NAME (.01 field) of the selected device's subtype as recorded in the TERMINAL TYPE file (#3.2).

IOST(0):

SUBTYPE NUMBER—This variable returns the Internal Entry Number (IEN) of the selected device's subtype as recorded in the TERMINAL TYPE file (#3.2).

IOT:

TYPE OF DEVICE—The DEVICE file (#3.5) holds an indication of Type for all devices. IOT returns the value of the device type (e.g., TRM for terminal, VTRM for virtual terminal, and HFS for Host file server).

IOXY:

CURSOR POSITIONING—This output variable returns the executable M code that allows cursor positioning, given the input variable DX and DY. The column position is passed in DX and the row position is passed in DY.

NOTE: The system special variables $X and $Y are not necessarily updated.

POP:

EXIT STATUS—When the Device Handler is called, pop is the output parameter that indicates the outcome status. If device selection is successful, POP is returned with a value of zero (POP=0). Abnormal exit returns a positive number in the pop input parameter.

There are three general conditions for abnormal exit upon which the pop output parameter is returned as positive:

  • The first case is one in which a device is not selected.

  • The second concerns unavailable devices.

  • The third situation arises when a device is identified but is unknown to the system.

The first condition of no device selection will be met if the user types a caret ("^") or times out at the device prompt. Exceeding the TIMED READ at the right margin or address/parameters prompts will have the same result.

The second condition, unavailability, is met if the Device Handler cannot open the selected device. The selected device may also have existed on another computer but queuing was not requested or perhaps not permitted (%ZIS had not contained Q).

Finally, the selected device may not exist in the DEVICE file (#3.5) XE "DEVICE File (#3.5)"  XE "Files:DEVICE (#3.5)". A device name may have been used that is not found as a .01 field entry. If the device is selected with P for the closest printer, the CLOSEST PRINTER field XE "CLOSEST PRINTER Field"  XE "Fields:CLOSEST PRINTER"  in the DEVICE file (#3.5) XE "DEVICE File (#3.5)"  XE "Files:DEVICE (#3.5)"  may be NULL.

If the exit is abnormal, returning POP with a positive value, the following output parameters will be restored with their values before the call to the Device Handler (before D ^%ZIS): ION, IOF, IOSL, IOBS, IOST(0), IOST, IOPAR, IOUPAR, IOS, and IOCPU.

NOTE: If IOF had been NULL before the call, it is returned with the pound sign as its value (IOF="#"). For backward compatibility, IO is currently returned as NULL (IO=""). However, the returned value of IO may change in future Kernel versions.

Example 1

This following is a simplified example; the process of issuing form feeds is not shown.

SAMPLE   ;SAMPLE ROUTINE
   ;
   S %ZIS="QM" D ^%ZIS G EXIT:POP
   I $D(IO("Q")) D  Q
   .S ZTRTN="DQ^SAMPLE",ZTDESC="Sample Test routine"
   .D ^%ZTLOAD D HOME^%ZIS K IO("Q") Q
DQ U IO W !,"THIS IS YOUR REPORT"
   W !,"LINE 2"
   W !,"LINE 3"
   D ^%ZISC
EXIT     S:$D(ZTQUEUED) ZTREQ="@" K VAR1,VAR2,VAR3 Q

Example 2

The IOP variable can be defined to pass a string to the Device Handler so that no user interaction will be required for device selection information. The following is the general format for defining IOP:

>S IOP=[Q[;]][DEVICE NAME][;SUBTYPE][;SPOOL DOCUMENT NAME][;RIGHT MARGIN[;PAGE LENGTH]]

Example 3

If the SPOOL DOCUMENT NAME is included, then the RIGHT MARGIN and PAGE LENGTH are ignored. Therefore, use the following format if a spool device is desired:

>S IOP=[Q[;]][DEVICE NAME][;SUBTYPE][;SPOOL DOCUMENT NAME]

Example 4

The following shows how a device named "RXPRINTER" in the DEVICE file (#3.5) can be opened without user interaction:

>S IOP="RXPRINTER" D ^%ZIS Q:POP

Example 5

When setting the IOP variable, you can include the right margin:

>S IOP=ION_";"_IOM  or  S IOP=";120"

or

>S IOP="RXPRINTER;120"

In this example, ION is the local variable that contains the name of the device to be opened and the IOM variable contains the value of the desired right margin.

Example 6

The IOP variable can be set to force queuing by starting the string with "Q":

>SET IOP="Q;"_ION_";"_IOM  ... etc.

In order to force queuing and prompt the user for a device:

>SET IOP="Q" D ^%ZIS Q:POP

Example 7

A spool document name can be passed to the Device Handler:

>S IOP=DEVNAM_";"_IO("DOC") D ^%ZIS Q:POP

or

>S IOP="SPOOL;"_IO("DOC")

or

>S IOP=DEVNAM_";"_IOST_";"_IO("DOC")

or

>S IOP="SPOOL;P-OTHER;MYDOC"

NOTE: For more information, please refer to the "Spooling" chapter in the Kernel Systems Manual.

In this example, DEVNAM contains the name of the device to be opened. IO("DOC") contains the spool document name, and IOST contains the name of the desired subtype. "SPOOL" is the actual name of a device entry that corresponds to the spool device, "P-OTHER" is the desired subtype, and "MYDOC" is the name of the spool document.

Example 8

Finally, the IOP variable can be used to select a device by the device's Internal Entry Number (IEN). To select a device with an IEN of 202, set IOP to an accent grave character followed by the IEN value of 202:

>S IOP="`202" D ^%ZIS

Multiple Devices and ^%ZIS

Beyond the home device, the ^%ZIS API is not designed to open more than one additional device at a time.

For interactive users, the home device should already be open and defined in the Kernel environment. ^%ZIS should only be used to open one additional device at a time for interactive users. For a task, you can use ^%ZIS to open one additional device beyond the task's assigned device.

Beginning with Kernel V. 8.0, there are three APIs to support using more than one additional device simultaneously:

These "multiple device" APIs are described later in this chapter.

Host Files and ^%ZIS

Although it is possible to use the ^%ZIS API to manipulate Host files, the Host file API (in ^%ZISH) offers more robust Host file functionality.

NOTE: For more information on using the Host file API, please refer to the "Host Files" chapter in the Kernel Developer's guide.

 


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

Reviewed/Updated: August 23, 2012

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.