This chapter describes how to work with I/O devices within Caché applications and at the Caché 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.
commands read from and write to that device.
command releases ownership of the device so that other processes can use the device.
The following sections give an overview of the Caché I/O commands.
The following general syntax applies to I/O commands that support I/O command keywords in ObjectScript:
is either a single parameter, or a list of parameters enclosed in parentheses and separated by colons:
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:
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 (such as magnetic tape drives) 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, Magnetic Tape I/O,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, Caché 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.
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.
Examples of OPEN on Windows systems
This command opens outbound Telnet connections from a Windows system to a terminal server:
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
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.
Examples of USE on Windows systems
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® systems
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.
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 Caché code in a mnemonic space. The mnemonic space is a Caché 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
To move the cursor to column 1, line 2 on a terminal screen using the predefined ^%X364 mnemonic space, issue the command:
command releases ownership of the specified device. CLOSE
reverses the effect of the OPEN
||The desired device name, ID number, or mnemonic.
The parameter K
closes the device at the Caché level without closing it at the operating system level.
The K 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, Caché 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 Caché.
If output to the device is stopped for some reason, Caché 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.
When you develop Caché applications or work with I/O devices at the Caché 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
Issue the I/O commands OPEN
, and CLOSE
, using Caché device numbers or operating system file specifications for the devices.
Allowing Users to Specify a Device
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
relies upon IO configuration defaults established in the Management Portal
This section addresses the following topics:
When you call the %IS
utility, Caché 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.
to select the current device.
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 a Caché 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.
If the device you specify is a terminal, the utility prompts you with a default right margin. Press Return
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 Return
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
In the following example, the user specifies magnetic tape unit 57. The utility suggests default parameter values, which the user accepts by pressing Return
. The utility then suggests the rewind default, and the user presses Return
to accept the default that the tape is not to be rewound at end-of-tape.
Parameters? ("auv":0:2048) => <RETURN>
Rewind? No => <RETURN>
%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
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
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 Caché I/O commands, such as READ
, refer to that device.
The user or application developer must close devices opened with the %IS
has several features to simplify its use. For example, if you want to send I/O to your own terminal, simply press Return
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
global is initialized at installation with several default mnemonics. For instance, there are two default mnemonics, SPOOL and 2, for the Caché spooler. Simply type 2
to send output to the Caché 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 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
to DX and DY to position the cursor.
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>
is an internal entry point within %IS
that can be called by routines that only plan to do output to the device. This entry can be used to check such conditions as whether a magnetic tape is write enabled.
Rewind? No= Y
[Tape is write locked]
Caché spooling is independent of the spooling performed by your operating system. Spooling in Caché 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
globalnot 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.
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 selectionIf 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
Preconfigured terminalsUsing the Management Portal
, you can configure a device that does not request any device information from the user.
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 [Home] > [Configuration] > [Device Settings] > [IO Settings]
to display the default mnemonic for different device types. The second subscript can be 0 or 1.
Node 0 contains the Device panel Location value:
^%IS(mnemonic,0) = Location
In this example, the device with the mnemonic name 47 was given the Device panel Location of Magnetic tape
^%IS(47,0) = Magnetic tape
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 Caché 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^^^^^
Specifying Devices in I/O Commands
When you use the I/O commands OPEN
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
|Caché Device Name
||Terminals and Printers
|Caché 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.
Specifying Terminals and Printers by Device Name
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:
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
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.
Specifying Devices by Caché ID
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 [Home] > [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 Caché will translate it to OPEN 49
You must use Caché device numbers when referring to magnetic tape devices.
The following table shows the device numbers.
Caché Device Numbers and Devices
||Principal device (the device on which you logged in).
||Caché 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.
||Magnetic tape devices.
||Routine interlock devices.
||Interjob communication devices.
To open a magnetic tape device, you issue a command such as:
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:
Principal Device and Current Device
Each Process has a Principal Device
Each Caché 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 Caché, that terminal becomes your principal device. Because Caché implicitly issues OPEN
commands for that terminal, you can issue READ
commands to it immediately. The Caché 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.
Caché Directs I/O Commands to the Current Device
Caché directs input and output operations, including READ
, 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 Caché 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
for a device other than your principal device in programmer mode, each time Caché 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 >
When Your Principal Device Becomes Your Current Device
Your principal device automatically becomes your current device when you do any of the following:
USE 0 Opens the Principal Device
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.
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 a Caché OPEN
command with the appropriate argument (see table). Caché treats it as a dummy device.
Null Device Arguments
||Null Device Argument
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 Caché (for example, by redirecting Caché 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.
One Process Owns a 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:
By explicitly issuing a CLOSE
Application Development I/O Commands
There are a special set of I/O commands to load, edit, print, and save Caché 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 a Caché 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. Caché 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
Controlling Devices with Mnemonic Spaces
A mnemonic space is a Caché 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.
Predefined Mnemonic Spaces
Caché 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 [Home] > [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
command for the current device.
Creating a Mnemonic Space
You can create your own mnemonic space routines. For example, you might want to use a predefined mnemonic space for magnetic tape but create your own for terminal I/O.
Create a Caché 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
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 Caché 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
When using the default mnemonic space, do not include a mnespace parameter when you issue OPEN
commands for the device.
To use another mnemonic space, specify its name in the mnespace parameter of the OPEN
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.