Skip to main content
Previous sectionNext section

I/O Devices and Commands

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.

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 sections give an overview of the Caché I/O commands.

General I/O Syntax

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")
Copy code to clipboard

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 (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.

Syntax

OPEN device{:{(parameters)}{:{timeout}{:"mnespace"}}}
Argument Description
device The desired device name, ID number, or mnemonic. The maximum length of device is 256 characters.
parameters 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.
timeout 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.
mnespace 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 Caché ObjectScript Reference.

Examples

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:

  OPEN "|TNT|node:port"
Copy code to clipboard

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"
Copy code to clipboard
Example of OPEN on UNIX® Systems

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

   OPEN "/dev/tty06/"
Copy code to clipboard

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.

Syntax

USE device:(args):"mnespace"
Argument Description
device The desired device name, ID number, or alias. The maximum length of device is 256 characters.
args 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.
mnespace Optional — Name of the Caché 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 Caché ObjectScript Reference.

Examples

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:

   OPEN "|TCP|4":("larry":"daytime":"C")
   USE "|TCP|4":(::"PSTE")
Copy code to clipboard
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.

   OPEN "/dev/tty06"
   USE "/dev/tty06"::"^%x364"
Copy code to clipboard

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.

Syntax

READ variable:timeout

For further details, refer to the READ command in the Caché ObjectScript Reference.

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 /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 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 the section Defining Default Mnemonic Spaces.

Syntax

WRITE variable

For further details, refer to the WRITE command in the Caché ObjectScript Reference.

Example

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)
Copy code to clipboard

CLOSE Command

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

Syntax

CLOSE device[:params] 
Argument Description
device The desired device name, ID number, or mnemonic.
params
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.

For further details, refer to the CLOSE command in the Caché ObjectScript Reference.

Specifying I/O Devices

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 global.

  • Issue the I/O commands OPEN, USE, and CLOSE, using Caché device numbers or operating system file specifications for the devices.

Allowing Users to Specify a Device

%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:

How %IS Works

Device Prompt

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.

  • Press Return 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 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.

See the discussion “Alternate Devices” that is part of %IS Mnemonics section below for information about using alternate devices.

Additional Questions

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.

Examples

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.

%SYS>DO ^%IS
Device: <RETURN>
Right margin: 80 => 132
%SYS>
Copy code to clipboard

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.

%SYS>DO ^%IS
Device: 57
Parameters? ("auv":0:2048) => <RETURN>
Rewind? No => <RETURN>
%SYS>
Copy code to clipboard

%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
Variable Example Description
%ANS Yes Generic dialog answer.
IO 64 Device number or device mnemonic of selected device.
IOF # Form feed. WRITE # issues a form feed and changes $Y. WRITE @IOF should be used to form feed.
IOBS *8 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.
IOM 80 Right margin.
IOSL 66 Screen/page length.
IOT TRM Device type.
IOST C-VT220 Device subtype (VT220 in this example).
IOPAR ("auv":0:2048) Any other OPEN parameters.
MSYS M/WNT Type of system (such as UNIX®, Windows NT).
POP 0 If not zero, specifies that no device was selected. That is, the user entered STOP in response to Device: prompt.
RMSDF RW Read/Write permissions.

OPEN Parameters

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 Caché 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 Mnemonics

%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.

Device Mnemonics

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.

Default Mnemonics

The ^%IS 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” or “SPOOL” 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.

Alternate Devices

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
Variable Example Description
FF 3 WRITE @FF should be used for form feed on this device
BS *8 WRITE @BS should be used to backspace
RM 80 Right margin
SL 24 Screen/page length
SUB C-VT100 Device subtype
XY (see Example below) Set $X to DX and $Y to DY to perform direct cursor positioning

Example

After calling CURRENT^%IS, set $X and $Y to DX and DY to position the cursor.

  DO CURRENT^%IS
  WRITE *27,*61,*DY+32,*DX+32 
  SET $X=DX,$Y=DY
Copy code to clipboard

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

Device: 3 
Right margin: 132= <RETURN>
[you can't read from this device] 
Device: <RETURN>  
Right margin: 80= <RETURN>
%SYS>
Copy code to clipboard

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. This entry can be used to check such conditions as whether a magnetic tape is write enabled.

%SYS>DO OUT^%IS

Device: 47 
Parameters: ("AUS":0:2048)
Rewind? No= Y
[Tape is write locked] 
Device: 
%SYS>
Copy code to clipboard

Spooling

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 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:

Device: SPOOL
Name:TEST
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
Copy code to clipboard

If you reselect an existing document because you would like to continue adding to an existing file, the system gives you the following options:

  1. Add to the very end of the file;

  2. Restart at the top of the last page, in which case the lines that will be deleted are displayed on the screen;

  3. 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
Variable Function
IODOC 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).
IODES Free text description.
IOPGM 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 suppressing—It 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.

Structure of ^%IS Global

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, 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
Copy code to clipboard

In this example, the device with the mnemonic name 47 was given the Device panel Location of “Magnetic tape”:

^%IS(47,0) = Magnetic tape
Copy code to clipboard

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
Copy code to clipboard

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^^^^^
Copy code to clipboard

Specifying Devices in I/O Commands

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
Caché Device Name Terminals and Printers
Caché Device ID or Device Alias All devices except sequential files
File Name 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"
Parameter Description
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:

OPEN "comn:"

where n represents the number of the port to which the device is attached.

Parameter Description
n The number of the port to which the device is attached.
   OPEN "com1:"
Copy code to clipboard

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

   OPEN "/dev/tty06"
Copy code to clipboard

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.

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 System, 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.

Caution:

You must use Caché device numbers when referring to magnetic tape devices.

The following table shows the device numbers.

Caché Device Numbers and Devices
Device Numbers Devices
0 Principal device (the device on which you logged in).
2 Caché spooler. UNIX®: the mnemonic SPOOL applies to this device.
3 An invalid device number. Attempting to open it returns a <NOTOPEN> error without waiting for timeout expiration.
47-60 Magnetic tape devices.
63 View buffer.
20-46, 200-223 Routine interlock devices.
224-255 Interjob communication devices.

Examples

To open a magnetic tape device, you issue a command such as:

   OPEN 47
Copy code to clipboard

To open the spooler, you issue the command:

   OPEN 2
Copy code to clipboard

Specifying Files on Disk

You can open a disk file using the operating system file specification enclosed in double quotes.

A Windows file specification has the following format:

device:\directory\file.type
Copy code to clipboard

A UNIX® file specification has the following format:

/directory/name
Copy code to clipboard

For further details, refer to Specifying a File in the “Sequential File I/O” chapter of this manual.

UNIX Examples

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:

   OPEN "pat_rec.dat"
Copy code to clipboard

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:

   OPEN "/usr/elsewhere/pat_rec.dat"
Copy code to clipboard

Processes and Devices

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 and USE commands for that terminal, you can issue READ and WRITE 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, 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 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 and USE 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 “>” 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.

  • Issue a call to the ChangePrincipal() method of the %Library.Device class.

  • Cause an error when an error trap is not set.

  • Close the current device.

  • Return to programmer mode.

  • Exit Caché 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.

The Null Device

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
Platform Null Device Argument
UNIX® /dev/null/
Windows //./nul

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.

Note:

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 command.

  • By halting.

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
Command Description
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.
PRINT [args]
or
ZPRINT [args]
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 [routine] 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.

Device Special Variables

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
Variable Purpose
$IO 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.
$X 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.
$Y 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.
$ZA Contains READ status information after a READ command to a terminal device.
$ZB Contains the character sequence or event ended the last READ operation on the current device.
$ZMODE Contains the parameters you used with the OPEN or USE command for the current device.

$X and $Y 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 and $ZB.

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
Routine Name Device Type Default Description
^%MAGTAPE Magnetic tape Mnemonic space for magnetic tape. For information, see “Magnetic Tape Mnemonic Space for WRITE /mnemonic ”.
^%X364 Terminals, Sequential files, Other devices Mnemonic space for X3.64 (ANSI) terminals. For information, see “Mnemonic Space for X3.64”.
^%XDTM DTM PC Console Mnemonic space for DTM PC Console. For information, see “Mnemonic Space for DTM PC Console”.

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, Configuration, Device Settings, IO Settings. This displays the mnemonics for the following:

  • Terminals

  • Magnetic tape

  • Sequential files

  • Other

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.

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.

  1. 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 /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.

  2. 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).

Select a Mnemonic Space

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.

  USE "device"::"^%X364"
Copy code to clipboard

For information on using the mnespace parameter, see the OPEN command and the USE command, as well as the chapters on individual device types.