|
![[skip navigation]](images/clr_pxl.gif){kind=small}
|
|
Reference Type: Supported, Category: Device Handler, ICR#: 10086
The ^%ZIS 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, it 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, see the "Form Feeds" topic in the "Special Device Issues" section in the Kernel 8.0 & Kernel Toolkit 7.3 Developer's Guide.
^%ZIS
Make sure to perform the following steps before calling this API:
| %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 input variable contains:
|
| %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. The possible values are:
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 (#3.5) file. 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.
>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 (#3.5) file are 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 are not 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.) NOTE: If IOP is set to NULL, the device handler defaults to the
HOME device.
>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 (#3.5) file rather than as FREE TEXT. |
| 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.
|
| 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).
|
| 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 APIs. |
| 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 saves 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 APIs. |
| 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 is undefined. NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS APIs. |
| 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 exists temporarily, during spooling, and is KILLed upon normal exit. NOTE: This variable is KILLed when a call is made to ^%ZIS or HOME^%ZIS APIs. |
| IO("T"): |
TaskMan call. |
| IO("ZIO"): |
TERMINAL SERVER PORT—If %ZIS["L", both physical port and server names are returned in IO("ZIO") under Caché. 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 WRITEs 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 (#3.5) file. 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 (#3.5) file. |
| 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 (#3.5) file 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 (#3.2) file. |
| IOST(0): |
SUBTYPE NUMBER—This variable returns the Internal Entry Number (IEN) of the selected device's subtype as recorded in the TERMINAL TYPE (#3.2) file. |
| IOT: |
TYPE OF DEVICE—The DEVICE (#3.5) file 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.
|
| POP: |
EXIT STATUS—When the Device Handler is called, POP is the output variable 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 variable. There are three general conditions for abnormal exit upon which the POP output variable is returned as positive:
The first condition of no device selection is 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 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 (#3.5) file. 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 in the DEVICE file (#3.5) may be NULL. If the exit is abnormal, returning POP with a positive value, the following output parameters are 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. |
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
|
The IOP variable can be defined to pass a string to the Device Handler so that no user interaction is 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]]
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]
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
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.
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
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, see the "Spooling" section in the Kernel 8.0 & Kernel Toolkit 7.3 Systems Management Guide.
In this example:
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 grave accent character (`) followed by the IEN value of 202:
>S IOP="`202" D ^%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 8.0, there are three APIs to
support using more than one additional device simultaneously:
These "multiple device" APIs are described in their own sections.
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,
see the "Host Files" chapter in the Kernel 8.0 & Kernel Toolkit 7.3 Developer's guide.