Introduction to I/O

Introduction

InterSystems IRIS® data platform provides support for many different kinds of devices, both logical and physical. The supported logical devices include:

• The principal device

• Files

• Pipes

• TCP connections

• Interjob communication (IJC) devices to communicate between InterSystems IRIS processes

• The InterSystems Spooler

The supported physical devices include:

• Terminals

• Printers

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:

OPEN device:paramlist:timeout:"mnespace"
USE device:paramlist:"mnespace"
CLOSE device:paramlist

where paramlist is either a single parameter, or a list of parameters enclosed in parentheses and separated by colons:

 parameter  (parameter:parameter[:...]) 

A parameter can either be a positional parameter or a keyword parameter. A keyword parameter has the following syntax:

/keyword[=value] 

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 "test.dat":("NWS":/IOTABLE="JIS")

OPEN Command

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.

OPEN device{:{(parameters)}{:{timeout}{:"mnespace"}}}

Examples of OPEN on Windows systems

This command opens outbound Telnet connections from a Windows system to a terminal server:

  OPEN "|TNT|node:port"

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:

   OPEN "c:\abc\test.out":"WS"

Example of OPEN on UNIX® Systems

This command opens an I/O channel to the UNIX® terminal device /dev/tty06:

   OPEN "/dev/tty06/"

USE Command

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.

USE device:(args):"mnespace"

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:

   OPEN "|TCP|4":("larry":"daytime":"C")
   USE "|TCP|4":(::"PSTE")

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.

   OPEN "/dev/tty06"
   USE "/dev/tty06"::"^%x364"

READ Command

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.

READ variable:timeout

WRITE Command

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.

WRITE variable

WRITE /mnemonic

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:

   WRITE /CUP(1,2)

CLOSE Command

The CLOSE command releases ownership of the specified device. CLOSE reverses the effect of the OPEN command.

CLOSE device[:params]