Introduction to I/O
This page describes — at a high level — how to work with I/O devices within InterSystems IRIS® data platform applications and at the InterSystems IRIS prompt.
InterSystems IRIS® data platform provides support for many different kinds of devices, both logical and physical. The supported logical devices include:
The supported physical devices include:
Overview of I/O Commands
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 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 available parameters are different for pipes (interprocess communications), files, and Terminal I/O.
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.
Examples of OPEN on Windows systems
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:
Example of OPEN on UNIX® Systems
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 — 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.
Examples of USE on Windows
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:
Examples of USE on UNIX®
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.
For further details, refer to the WRITE command in the ObjectScript Reference.
WRITE /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 or USE command, or configured as a default for the device using the Management Portal. To learn how to define and activate mnemonic spaces, see Defining Default Mnemonic Spaces.
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.
The desired device name, ID number, or mnemonic.
The parameter K closes the device at the InterSystems IRIS level without closing it at the operating system level.
TheK parameter has no effect on Windows systems. The file is closed at the operating system level.
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.