Establishes a device as the current device.
||Optional A postconditional expression.
||The device to be selected as the current device, specified by a device ID or a device alias. A device ID can be an integer (a device number), a device name, or the pathname of a sequential file. If a string, it must be enclosed with quotation marks.
||Optional The list of parameters used to set device characteristics. The parameter list is enclosed in parentheses, and the parameters in the list are separated by colons. Parameters can either be positional (specified in a fixed order in the parameter list) or keyword (specified in any order). A mix of positional and keyword parameters is permitted. The individual parameters and their positions and keywords are highly device-dependent.
||Optional The name of the mnemonic space that contains the control mnemonics to use with this device, specified as a quoted string.
establishes the specified device as the current device. The process must have already established ownership of the device with the OPEN
The current device remains current until you issue another USE
command to select another owned device as the current device or until the process terminates.
command can establish as the current device such devices as terminal devices, magnetic tape devices, spool devices, TCP bindings, interprocess pipes, named pipes, and inter-job communications. The USE
command can also be used to open a sequential file. The device
argument specifies the file pathname as a quoted string.
available with the USE
command are highly device-dependent. In many cases the available parameters
are the same as those available with the OPEN
command; however, some device parameters can only be set using the OPEN
command, and other can only be set using the USE
command can specify more than one useargument
, separated by commas. However, you can only have one current device at a time. If you specify more than one useargument
, the device specified in the last useargument
becomes the current device. This form of USE
may be used to set parameters
for several devices, and then establish the last-named device as the current device.
An optional postconditional expression. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions
in Using ObjectScript
The device to be selected as the current device. Specify the same device ID (or other device identifier) as you specified in the corresponding OPEN
command. For more information on specifying devices, refer to the OPEN
The list of parameters used to set operating characteristics of the device to be used as the current device. The enclosing parentheses are required if there is more than one parameter. (It is good programming practice to always use parentheses when you specify a parameter.) Note the required colon before the left parenthesis. Within the parentheses, colons are used to separate multiple parameters.
The parameters for a device can be specified using either positional parameters or keyword parameters. You can also mix positional parameters and keyword parameters within the same parameter list.
In most cases, specifying contradictory, duplicate, or invalid parameter values does not result in an error. Wherever possible, InterSystems IRIS ignores inappropriate parameter values and takes appropriate defaults.
The available parameters are, in many cases, the same as those supported for the OPEN
command. For sequential files, TCP devices, and interprocess communication pipes some parameters can only be set with the OPEN
command; for sequential files some parameters can only be set with the USE
parameters are specific to the type of device that is being selected and to the particular implementation. The USE
command keyword parameters are listed by device type in I/O Devices and Commands
in the I/O Device Guide
If you do not specify a list of USE
parameters, InterSystems IRIS uses the device’s default OPEN
parameters. The default parameters for a device are configurable. Go to the Management Portal
, select [System] > [Configuration] > [Device Settings] > [Devices]
to display the current list of devices. For the desired device, click edit
to display its Open Parameters:
option. Specify this value in the same way you specify the OPEN
command parameters, including the enclosing parentheses. For example, ("AVL":0:2048)
Positional parameters must be specified in a fixed sequence in the parameter list. You can omit a positional parameter (and receive the default value), but you must retain the colon to indicate the position of the omitted positional parameter. Trailing colons are not required; excess colons are ignored. The individual parameters and their positions are highly device-dependent. There are two types of positional parameters: values and letter code strings.
A value can be an integer (for example, record size), a string (for example, host name), or a variable or expression that evaluates to a value.
A letter code string uses individual letters to specify device characteristics for the open operation. For most devices, this letter code string is one of the positional parameters. You can specify any number of letters in the string, and specify the letters in any order. Letter codes are not case-sensitive. A letter code string is enclosed in quotation marks; no spaces or other punctuation is allowed within a letter code string (exception: K and Y may be followed by a name delimited by backslashes: thus: K\name\). For example, when opening a sequential file, you might specify a letter code string of ANDFW (append to existing file, create new file, delete file, fix-length records, write access.) The position of the letter code string parameter, and the meanings of individual letters is highly device-dependent.
Keyword parameters can be specified in any sequence in the parameter list. A parameter list can consist entirely of keyword parameters, or it can contain a mix of positional and keyword parameters. (Commonly, the positional parameters are specified first (in their correct positions) followed by the keyword parameters.) You must separate all parameters (positional or keyword) with a colon (:). A parameter list of keyword parameters has the following general syntax:
The individual parameters and their positions are highly device-dependent. As a general rule, you can specify the same parameters and values using either a positional parameter or a keyword parameter. You can specify a letter code string as a keyword parameter by using the /PARAMS keyword.
The name of the mnemonic space that contains the device control mnemonics used by this device. By default, InterSystems IRIS provides two mnemonic spaces: ^%XMAG for magnetic tape devices, and ^%X364 (ANSI X3.64 compatible) for all other devices and sequential files. Default mnemonic spaces are assigned by device type.
Go to the Management Portal
, select [System] > [Configuration] > [Device Settings] > [IO Settings]
. View and edit the File, MagTape, Other, or Terminal mnemonic space setting.
A mnemonic space is a routine that contains entry points for the device control mnemonics used by READ
commands. The READ
commands invoke these device control mnemonics using the /mnemonic
) syntax. These device control mnemonics perform operations such as moving the cursor to a specified screen location or rewinding a magnetic tape.
Use the mnespace
argument to override the default mnemonic space assignment. Specify an ObjectScript routine that contains the control mnemonics entry points used with this device. The enclosing double quotes are required. Specify this option only if you plan to use device control mnemonics with the READ
command. If the mnemonic space does not exist, InterSystems IRIS issues a <NOROUTINE> error. For further details on mnemonic spaces, see I/O Devices and Commands
in the I/O Device Guide
In this example, the USE
command sets the sequential file "STUDENTS" as the current device and sets the file pointer so that subsequent reads begin at offset 256 from the start of the file.
Device ownership is established with the OPEN
command. The only exception is the principal device, which is assigned to the process and is usually the terminal at which you sign on. If the device specified in the USE
command is not owned by the process, InterSystems IRIS issues a <NOTOPEN> error message.
The current device is the device used for I/O operations by the READ
commands. The READ
command acquires input from the current device and the WRITE
command sends output to the current device.
InterSystems IRIS maintains the ID of the current device in the $IO
special variable. If the USE
request is successful, InterSystems IRIS sets $IO
to the ID of the specified device. The GetType()
method of the %Library.Device
class returns the device type of the current device.
The special device number 0 (zero) refers to the principal device. Each process has one principal device. InterSystems IRIS maintains the ID of the principal device in the $PRINCIPAL
special variable. The principal device is automatically opened when you start up InterSystems IRIS. Initially, the principal device ($PRINCIPAL
) and the current device ($IO
) are the same.
After you issue a USE
command, your current device ($IO
) is normally the one named in the last USE
command you executed.
While many processes can have the same principal device, only one at a time can own it. After a process successfully issues an OPEN
command for a device, no other process can issue OPEN
for that device until the first process releases it, either by explicitly issuing a CLOSE
command, by halting, or because that user ends the session.
Although you can issue OPEN
for a device other than your principal device from the Terminal, 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.
Your principal device automatically becomes your current device when you do any of the following:
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
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
Although USE 0
implies OPEN 0
for the principal device, issuing a USE
command for any other device that the process does not own (due to a previous OPEN
command) produces a <NOTOPEN> error.
While most InterSystems IRIS platforms allow you to close your principal input device, InterSystems IRIS for UNIX® does not. Therefore, when a job that is the child of another job tries to perform I/O on your login terminal, it hangs until you log off InterSystems IRIS. At that time, the output may or may not appear.
Using the Null Device on UNIX®
When you issue an OPEN
command to the null device (/dev/null on UNIX®), InterSystems IRIS treats the null device as a dummy device. Subsequent READ
commands immediately return a null string (""). Subsequent WRITE
commands immediately return success. No actual data is read or written. On systems based on UNIX®, the device /dev/null bypasses the UNIX® open, write, and read system calls entirely.
Processes started by other processes with the JOB
command have a principal device of /dev/null by default.
If you open /dev/null other than within InterSystems IRIS for example, by redirecting InterSystems IRIS output to /dev/null from the UNIX® shell the UNIX® system calls operate as they do for any other device.