I/O Device Guide
I/O Devices and Commands
This chapter describes how to work with I/O devices within InterSystems IRIS Data Platform™ applications and at the InterSystems IRIS prompt. It assumes your devices have been set up properly, as described in the About I/O Devices
chapter. For additional information about specific devices, see the other chapters in this guide.
The I/O commands allow you to own, use, read from, write to, and close devices. To direct I/O operations to a device, first issue the following commands:
Issue an OPEN command to establish ownership, unless the device is your principal device.
Issue a USE command to make the device the current device.
Subsequent READ and WRITE commands read from and write to that device.
A CLOSE command releases ownership of the device so that other processes can use the device.
The following sections give an overview of the InterSystems IRIS I/O commands.
The following general syntax applies to I/O commands that support I/O command keywords in ObjectScript:
where paramlist is either a single parameter, or a list of parameters enclosed in parentheses and separated by colons:
A parameter can either be a positional parameter or a keyword parameter. A keyword parameter has the following syntax:
The leading slash distinguishes a keyword parameter from a positional parameter value. The meaning of a positional parameter value is derived from its position in the colon-delimited list. The meaning of a keyword parameter value is derived from the specified keyword.
Note that both positional and keyword parameters can be specified in the same paramlist. For example, the following example mixes positional and keyword parameters to open a new file named test.dat in write/sequential mode with JIS I/O translation:
OPEN establishes ownership of, and opens an I/O channel to, the device specified. This ownership persists until you issue a CLOSE command, your process terminates, or some physical operation closes the device. For physical I/O devices or for interprocess communications (such as TCP connections), this ownership prevents all other processes from accessing the device. For logical I/O devices (such as sequential files), this ownership may allow other processes some form of shared access to the file. The handling of multiple processes that open the same sequential file is highly platform-dependent. Use of the LOCK command to restrict access to sequential files is strongly advised.
||The desired device name, ID number, or mnemonic. The maximum length of device is 256 characters.
||Optional One or more parameters specifying additional information necessary for some devices. This parameter list is enclosed in parentheses, and the parameters in the list are separated by colons. The individual parameters are listed in tables in the Interprocess Communications, Sequential File I/O, and Terminal I/O chapters.
||Optional The number of seconds to wait for the request to succeed. The preceding colon is required.timeout must be specified as an integer value or expression. If timeout is set to zero (0), OPEN will make a single attempt to open the file. If the attempt fails, the OPEN immediately fails. If the attempt succeeds it successfully opens the file. If timeout is not set, InterSystems IRIS will continue trying to open the device until the OPEN is successful or the process is terminated manually.
||Optional The name of the mnemonic space that contains the control mnemonics to use with this device, specified as a quoted string. You can use these control mnemonics with the WRITE /mnemonic command when directing I/O to this device.
For further details, refer to the OPEN
command in the ObjectScript Reference
These examples show how to use the OPEN command on different platforms. They may be typed at the command line or used in routines. When used in routines, you may want to replace platform-specific items with variables.
This command opens outbound Telnet connections from a Windows system to a terminal server:
where node is the node name and port is the IP port on the server.
This command opens an I/O channel to an existing Windows file:
This command opens an I/O channel to the UNIX® terminal device /dev/tty06:
This command makes the specified device the current device, and sets the special variable $IO to that device. To USE a device other than your principal device, you must first issue an OPEN command for it; otherwise, you will receive a <NOTOPEN> error. Arguments have the same meaning as in the OPEN command.
||The desired device name, ID number, or alias. The maximum length of device is 256 characters.
||Optional Additional information necessary for some devices. These are listed in the command keyword tables in the Interprocess Communications, Sequential File I/O, and Terminal I/O chapters.
||Optional Name of the InterSystems IRIS routine containing the definition of the control mnemonics you can use with the WRITE /mnemonic command when directing I/O to this device.
For further details, refer to the USE
command in the ObjectScript Reference
These examples show how to use the USE command on different platforms. They may be typed at the command line or used in routines. When used in routines, you may want to replace platform specific items with variables.
This Windows example shows the commands you would use to connect via TCP to a time-of-day server on remote host larry. It uses the service name daytime, which the local system resolves to a port number. The USE command replaces the OPEN C mode with PSTE mode and turns off any user terminators:
This UNIX® example shows the commands you would use to open an I/O channel to device /dev/tty06 and establish it as your current device with the option of using WRITE /mnemonic with the X364 terminal mnemonics.
This command reads data from the current device. For some devices, arguments that begin with asterisks return ASCII numeric information; for others, they indicate control functions.
For further details, refer to the READ
command in the ObjectScript Reference
This command writes data to the current device. For some devices, arguments that begin with asterisks let you write ASCII characters using their ASCII numeric values; for others, they indicate control functions. For some devices, arguments that begin with the # character indicate the number of times to write that character.
/mnemonic syntax allows you to control a device with mnemonics which are defined in InterSystems IRIS code in a mnemonic space. The mnemonic space is an InterSystems IRIS routine that must be made active in an OPEN
command, or configured as a default for the device using the Management Portal. To learn how to define and activate mnemonic spaces, see the section Defining Default Mnemonic Spaces
For further details, refer to the WRITE
command in the ObjectScript Reference
To move the cursor to column 1, line 2 on a terminal screen using the predefined ^%X364 mnemonic space, issue the command:
The CLOSE command releases ownership of the specified device. CLOSE reverses the effect of the OPEN command.
If you issue a CLOSE command for your principal device, the principal device remains assigned to your process until you log off.
Several other conditions can affect the behavior of CLOSE:
If output to a device is stopped for some reason, InterSystems IRIS may be unable to finish output to that device, in which case you cannot close it, and may not be able to halt. For example, if a terminal sends a Ctrl-S to the operating system to tell it to stop output to the terminal, you must resume output to the terminal by pressing Ctrl-Q.
If you close the current device, CLOSE changes the value of the system variable $IO to that of the principal device. The CLOSE command releases ownership of the current device only after all output to that device is complete.
When a process halts, the system automatically closes all devices the process opened while in InterSystems IRIS.
If output to the device is stopped for some reason, InterSystems IRIS may be unable to finish output to that device, in which case you may not be able to close it or be able to halt.
For further details, refer to the CLOSE
command in the ObjectScript Reference
When you develop InterSystems IRIS applications or work with I/O devices at the InterSystems IRIS programmer's prompt, there are two ways to specify I/O devices:
Call the %IS utility, which allows you to specify the device by using a mnemonic defined in the %IS global.
Issue the I/O commands OPEN, USE, and CLOSE, using InterSystems IRIS device numbers or operating system file specifications for the devices.
%IS is a general device selection utility for character-based applications. You can use the built-in %IS utility to allow users to select a device to which to direct I/O operations. Whenever a device is to be selected, the application program should call the %IS utility. This utility allows the user to specify the device to be used and the appropriate OPEN command parameters, opens the selected device, then returns device-specific information to the calling program. Users enter a mnemonic that has been defined in the ^%IS global. %IS relies upon IO configuration defaults established in the Management Portal.
This section addresses the following topics:
When you call the %IS utility, InterSystems IRIS prompts for a device name. You respond in one of the following ways:
Enter the desired device name or ID number.
Enter a mnemonic for the device.
Press Enter to select the current device.
%IS responds as follows:
If you enter a device mnemonic, %IS finds the corresponding device in the ^%IS global and opens it.
If you enter a device name, %IS issues an OPEN command to that device.
If the device is an InterSystems IRIS device ID, %IS checks the device table to see if that number is remapped to another actual device number. %IS then issues an OPEN for the device.
See the discussion Alternate Devices that is part of %IS Mnemonics
section below for information about using alternate devices.
If the device you specify is a terminal, the utility prompts you with a default right margin. Press Enter to select that margin or type a different value. If a program later attempts to write past the specified right margin, the operating system inserts a CR LF (carriage return and line feed) when the margin is reached. If you select a device other than a terminal, the utility asks other types of secondary questions.
In the following example, the user presses Enter to specify the terminal. The utility prompts for a right margin, suggesting a default value of 80. At the => prompt the user enters 132 as the new margin setting.
Right margin: 80 => 132
%IS Sets the Variable IO and Returns Values of Other Variables
When you select a device, %IS sets the variable IO to the device name or number used in the OPEN command. %IS also returns the values of the variables listed in the following table:
%IS Device Variable Values
||Generic dialog answer.
||Device number or device mnemonic of selected device.
||Form feed. WRITE # issues a form feed and changes $Y. WRITE @IOF should be used to form feed.
||Backspace. WRITE $CHAR(8) issues a backspace and changes $X. WRITE *8 issues a backspace but does not change $X. WRITE @IOBS should be used to backspace.
||Device subtype (VT220 in this example).
||Any other OPEN parameters.
||Type of system (such as UNIX®, Windows NT).
||If not zero, specifies that no device was selected. That is, the user entered STOP in response to Device: prompt.
By default, the OPEN command uses the specifications for the device defined in the ^%IS global. You can override these settings by specifying other settings when you use %IS.
Issue a USE Command
After running %IS, the application must issue a USE command to the device opened by %IS. You can use the variable IO, as long as you understand that its value changes every time you call %IS. Then, subsequent InterSystems IRIS I/O commands, such as READ and WRITE, refer to that device.
Issue a CLOSE Command
The user or application developer must close devices opened with the %IS utility.
%IS has several features to simplify its use. For example, if you want to send I/O to your own terminal, simply press Enter at the Device prompt. You can also use built-in default mnemonics or new mnemonics you define yourself.
It is useful to have mnemonics for the various devices and, in some cases, to have more than one mnemonic for a single device. Multiple mnemonics allow you to specify different device characteristics for the device and vary characteristics according to the manner in which the device is used. For example, a terminal that is normally used for data entry, and thus has the characteristics of a terminal, may have an auxiliary printer attached. By assigning a different mnemonic that opens the same device with different characteristics, you can treat the terminal/printer combination as a printer when you want hard copy.
You can configure device mnemonics and characteristics using the Management Portal. To learn how to define and activate mnemonic spaces, see the section Defining Default Mnemonic Spaces
The ^%IS global is initialized at installation with several default mnemonics. For instance, there are two default mnemonics, SPOOL and 2, for the InterSystems IRIS spooler. Simply type 2 or SPOOL to send output to the InterSystems IRIS spooler.
If you are logged in on an RT:, LT:, or VT: type device, and your terminal is the current device, %IS will accept 0, , or the value of IO in response to the Device prompt. It will use the appropriate template (RT0:, LT0: or VT0:) for your terminal type to generate the information for your terminal.
If users enter an A at the Device prompt, output goes to the alternate device defined for the current device. Usually, users expect the alternate device to be a printer. Instead of defining a separate alternate device for each device in the system, you can create a device, pointing to a printer, with the mnemonic A. Then, when users enter A at the %IS Device prompt, output goes to that device.
CURRENT^%IS Entry Point
CURRENT is an internal entry point within the %IS utility that you can use to obtain the device parameters of the current device. This call to %IS returns the values of different variables, so you can keep one set of parameters for your principal device and a different set for a device with different characteristics. Ordinarily, you make a call to this internal entry point when you log in, to allow the application access to the device characteristics of the principal device. CURRENT^%IS returns the values of the variables listed in the table below:
CURRENT Return Values
||WRITE @FF should be used for form feed on this device
||WRITE @BS should be used to backspace
||(see Example below)
||Set $X to DX and $Y to DY to perform direct cursor positioning
After calling CURRENT^%IS, set $X and $Y to DX and DY to position the cursor.
IN^%IS Entry Point
IN is an internal entry point within %IS that can be called by routines that only plan to do input from the device. This entry point can be used to ensure that you do not select an output-only device such as a printer.
%SYS> Do IN^%IS
Right margin: 132= <RETURN>
[you can't read from this device]
Right margin: 80= <RETURN>
OUT^%IS Entry Point
OUT is an internal entry point within %IS that can be called by routines that only plan to do output to the device.
InterSystems IRIS spooling is independent of the spooling performed by your operating system. Spooling in InterSystems IRIS is a technique that lets you automatically save the output of a program in a global instead of printing it immediately. You can print the output later by sending the contents of the global to the printer.
The mnemonic SPOOL is a default mnemonic. To specify spooling, enter SPOOL in response to the Device prompt. The system then asks for a spool file name and description. This is a named used in the ^SPOOL global—not a separate file name at the operating system level.
If any existing file names start with or match the name you specify, they are displayed, and you are asked to choose one. If you select none of the existing files, the system allows you to create a new file with the specified name and description as shown in the following example:
1. 1 TEST 02 Nov 1999 10:17 am First test
2. 2 TEST 02 Nov 1999 10:18 am Second Test
Select one: <Return> not found
Create new document 'TEST'? Yes => yes
Description: Third Test
If you reselect an existing document because you would like to continue adding to an existing file, the system gives you the following options:
Add to the very end of the file;
Restart at the top of the last page, in which case the lines that will be deleted are displayed on the screen;
Restart at page 1 (the beginning).
You can pass the variables listed in the table below to %IS when you call it for spooling.
Spool Variables You Can Pass to %IS
||Document name (when this variable exists and is not a null string all questions are suppressed, and a new document with this name is automatically created).
||Free text description.
||Name of a routine that should be called at print time to allow the user to set up printer for the proper forms alignment.
Further Features of %IS
%IS can also be used to perform the following tasks:
Right margin suppressingIt is possible to set up a terminal line so that whenever that device is selected, the Right margin question is suppressed; the default value is automatically assumed.
Automatic device selection—If the variable IOP exists when the %IS utility is called, the utility automatically tries to open that device rather than ask for a device. If %IS is unsuccessful, it sets the variable POP to 1.
Preconfigured terminals—Using the Management Portal, you can configure a device that does not request any device information from the user.
The %IS global is stored in the %SYS namespace. It contains two subscripts. The first subscript is the mnemonic name configured for the device in the Management Portal. Select System Administration, Configuration, Device Settings, IO Settings to display the default mnemonic for different device types. The second subscript can be 0 or 1.
Contents of Node 0
Node 0 contains the Device panel Location value:
^%IS(mnemonic,0) = Location
Contents of Node 1
Node 1 contains the other Device panel field values separated by a caret (^):
^%IS(mnemonic,1) = Device #^Type^Subtype^Prompt code^not used
^Other Open parameters^Alternate device
In this example, the device with the mnemonic name 2 (which is a default name for the InterSystems IRIS spooler) has a device number of 2, device type of SPL (spool), device subtype of PK-DEC. The other values are not defined for a spool type device.
^%IS(2,1) = 2^SPL^PK-DEC^^^^^
When you use the I/O commands OPEN, USE and CLOSE to process I/O on any device other than the one on which you are working, you must specify an I/O device. You can specify devices in one of three ways, depending on device type, as shown in the table below.
Specifying a Device in an I/O Command
|Type of Specification
||Use for these Devices
|InterSystems IRIS Device Name
||Terminals and Printers
|InterSystems IRIS Device ID or Device Alias
||All devices except sequential files
Note that Windows and UNIX® handle printer I/O differently. For details, refer to the Printers
chapter of this manual.
If your I/O operations are to terminal (or a printer on some platforms), you can use the device name applied by the operating system (UNIX® or Windows) to specify the device. The form is as follows:
OPEN "device" USE "device" CLOSE "device"
||The operating system name of the device, enclosed in quotes. The maximum length of device is 256 characters.
Specifying a Terminal on Windows Systems
To open an I/O device connected to a serial communications port, specify an OPEN command with the following syntax:
where n represents the number of the port to which the device is attached.
||The number of the port to which the device is attached.
Specifying Terminals and Printers on UNIX®
To open an I/O device on a terminal that has the UNIX® device name /dev/tty06, enter the following command
On UNIX® systems, a printer is identified by the name on the OPEN command and is handled as a “character special” file on a tty device. Thus the OPEN and USE command arguments supported are the same as those for terminal I/O, not sequential file I/O. On Windows systems, printer I/O is handled like sequential file I/O.
For compatibility with other InterSystems products and for convenience, you can refer to devices by device numbers (which are stored in the device table). The system manager can link these numbers to devices using the Management Portal. Select System Administration, Configuration, Device Settings, Devices to create a new device or edit an existing device.
The system manager can also cause a translation from one number to another. Thus, you can issue an OPEN 47 and InterSystems IRIS will translate it to OPEN 49.
The following table shows the device numbers.
InterSystems IRIS Device Numbers and Devices
||Principal device (the device on which you logged in).
||InterSystems IRIS spooler. UNIX®: the mnemonic SPOOL applies to this device.
||An invalid device number. Attempting to open it returns a <NOTOPEN> error without waiting for timeout expiration.
||Routine interlock devices.
||Interjob communication devices.
To open the spooler, you issue the command:
You can open a disk file using the operating system file specification enclosed in double quotes.
A Windows file specification has the following format:
A UNIX® file specification has the following format:
Specifying a File on UNIX® Systems
A UNIX® file pathname can include up to 255 characters of any type. While the characters period (.) and underscore (_) can appear anywhere in the filename, you typically use them to divide the name into meaningful parts. For example, you can define a filename pat_rec.dat, using .dat as the file type.
When accessing files in the current UNIX® default directory, you usually need to specify only the name. The system fills in default values for the directory.
If your current default directory on a UNIX® or Windows system is /usr/user, you can open a file named pat_rec.dat stored in your current default directory by specifying:
The system opens the file automatically. For a new file, include the parameter string WN to avoid a hang.
To open a file with the same name, pat_rec.dat, stored in another directory, you must also specify the directory, as follows:
Each Process has a Principal Device
Each InterSystems IRIS process has one principal input device and one principal output device. By default, these are the same device. When you log in at a terminal and activate InterSystems IRIS, that terminal becomes your principal device. Because InterSystems IRIS implicitly issues OPEN and USE commands for that terminal, you can issue READ and WRITE commands to it immediately. The InterSystems IRIS principal device is the one that your operating system has assigned as your principal input device. The $PRINCIPAL special variable contains the device ID of the principal device.
InterSystems IRIS Directs I/O Commands to the Current Device
InterSystems IRIS directs input and output operations, including READ, WRITE, PRINT, and ZLOAD commands, to your current device. Your process' $IO special variable contains the device ID of your current device. When you log in to InterSystems IRIS at a terminal, $IO initially contains your terminal's device name. In other words, your principal device and your current device are the same immediately after you log in. After you issue a USE command, your current device (the one contained in $IO) is normally the one named in the last USE command you executed.
Although you may issue OPEN and USE for a device other than your principal device in programmer mode, each time InterSystems IRIS returns to the > prompt, it implicitly issues USE 0. To continue using a device other than 0, you must issue a USE command in each line you enter at the > prompt.
When Your Principal Device Becomes Your Current Device
Your principal device automatically becomes your current device when you do any of the following:
Sign on for the first time.
Issue a USE 0 command.
Cause an error when an error trap is not set.
Close the current device.
Return to programmer mode.
Exit InterSystems IRIS by issuing a HALT command.
USE 0 Opens the Principal Device
USE 0 implies an OPEN command to the principal device. If another process owns the device, this process hangs on the implicit OPEN as it does when it encounters any OPEN.
Issuing a USE command for any other device that the process does not own (due to a previous OPEN command) produces a <NOTOPEN> error.
An OPEN command with no timeout returns control to the process only when the process acquires the device. You can interrupt the open command by a keyboard interrupt command like Ctrl-C. An OPEN that cannot succeed because of a protection problem or an invalid device name hangs forever. When you specify a timeout in the OPEN command, the OPEN returns control to your process when the timeout expires.
Use the Null Device to Redirect I/O
If your application generates extraneous output which you do not want to appear on your screen, you can direct that output to the null device. You specify the null device by issuing an InterSystems IRIS OPEN command with the appropriate argument (see table). InterSystems IRIS treats it as a dummy device.
Null Device Arguments
||Null Device Argument
Subsequent READ commands immediately return an empty string. Subsequent WRITE commands immediately return success. No actual data is read or written. The NULL device bypasses UNIX® open, write, and read system calls entirely.
If you open the NULL device other than from within InterSystems IRIS (for example, by redirecting InterSystems IRIS output to /dev/null from the UNIX® shell), the UNIX® system calls do occur as they would for any other device.
Jobbed Processes Use the Null Device
When one process starts another with the JOB command, the default principal input and output device of the jobbed process is the null device.
Only one process can own a device at a time, except sequential files.
In other words, after a process successfully issues an OPEN command for a device, no other process can open that device until the first process releases it. A process releases the device in any of the following ways:
There are a special set of I/O commands to load, edit, print, and save InterSystems IRIS routines. These commands load routines from and save them to the current device; they are summarized in the table below
Application Development I/O Commands
|ZLOAD [ routine ]
||The ZLOAD command, without arguments, loads an InterSystems IRIS routine from the current device. You can use ZLOAD with OPEN and USE to output or input routines from different devices. ZLOAD ends when it receives a null line from terminal input or reaches the end of the file.
|Prints the routine in memory to the current device. It writes an empty line after the last line of the routine. Optional arguments let you control the number of lines you print.
||ZSAVE writes the routine in memory back to disk, giving it the name you supply. If you do not provide a name, it uses the name of the routine you loaded with ZLOAD.
Some I/O commands affect the value of certain system variables. This section defines these variables and tells why you might want to use them. These variables are changed only when an I/O command is issued to the current device. These device special variables are summarized in the table below:
Device Special Variables
||Contains the device ID of the current device, to which all output operations are directed. InterSystems IRIS sets the value of $IO to the principal output device at login, and only the USE and CLOSE commands, a BREAK command, or a return to programmer mode can change this value.
||Contains a running total of printable characters written since the last carriage return on the current device. This number ranges from 0 to the width of the device.
||Contains a running total of line feeds written since the last form feed on the current device. This number ranges from 0 to the length of the device.
||Contains READ status information after a READ command to a terminal device.
||Contains the character sequence or event ended the last READ operation on the current device.
||Contains the parameters you used with the OPEN or USE command for the current device.
are useful in formatting printed output. For more information on them, see the chapter Terminal I/O
. See individual chapters of this document for device-specific information about $ZA
A mnemonic space is an InterSystems IRIS routine that performs device control actions, such as cursor movement and device attributes. Each action is associated with a label. These labels are the mnemonics used in the WRITE /mnemonic command. For more information on the WRITE /mnemonic syntax, see the WRITE command description for each device type in the other chapters of this document.
InterSystems IRIS provides predefined mnemonic spaces described in the table below.
Predefined Mnemonic Spaces
Set Up Default Mnemonic Spaces
You can change the mnemonic space that is a default for the following device types in the Management Portal. Select System Administration, Configuration, Device Settings, IO Settings. This displays the mnemonics for the following:
After a default mnemonic space is defined, the control mnemonics in the default mnemonic space for the current device are used if a WRITE /mnemonic command is issued, unless the default mnemonic space is overridden by a mnespace argument to the OPEN or USE command for the current device.
You can create your own mnemonic space routines. For example, you might want to create your own for terminal I/O.
Create an InterSystems IRIS routine containing the control mnemonics you want. Keep in mind the following points about your routine:
The entry points in this routine must be uppercase. These entry points are the mnemonics you reference in WRITE /mnemonic commands.
Some entry points may require arguments. The code in the mnemonic space at an entry point performs an action on the current device.
Cursor movement routines do not move the cursor past the edge of the screen in any direction, nor do they wrap the cursor.
To make this mnemonic space available to all users, give the InterSystems IRIS routine a name that begins with % and put it in the system manager's namespace (%SYS).
Before you issue WRITE /mnemonic commands to a device, you decide whether you want to use the default mnemonic space for the device type as specified in the Management Portal configuration setting.
When using the default mnemonic space, do not include a mnespace parameter when you issue OPEN or USE commands for the device.
To use another mnemonic space, specify its name in the mnespace parameter of the OPEN or USE command you issue for the device.
For information on using the mnespace
parameter, see the OPEN
command and the USE
command, as well as the chapters on individual device types.
Content Date/Time: 2019-08-16 05:39:10