Principal Device, Current Device, and 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.
Each Process has a Principal Device
Each InterSystems IRIS 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 InterSystems IRIS, that terminal becomes your principal device. Because InterSystems IRIS implicitly issues OPEN and USE commands for that terminal, you can issue READ and WRITE commands to it immediately. The InterSystems IRIS 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.
InterSystems IRIS Directs I/O Commands to the Current Device
InterSystems IRIS directs input and output operations, including READ, WRITE, PRINT, and ZLOAD commands, to your current device. The $IO special variable contains the device ID of your current device. When you log in to InterSystems IRIS 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 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.
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 or USE $principal command.
-
Issue a call to the ChangePrincipal()Opens in a new tab method of the %Library.DeviceOpens in a new tab class.
-
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 command.
Explicitly Using the Principal Device
USE 0 or USE $principal implicitly issues an OPEN command to the principal device for the process. 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.
Options for Working with the Principal Device
Depending on the nature of the principal device, you can specify additional device-specific arguments, which are different for pipes (interprocess communications), files, and Terminal I/O. For example, you can open the principal device with the TLS connection:
USE $principal:(::/TLS=ConfigName)
Where ConfigName is the name of a TLS configuration defined in the same instance.
The Null Device
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 an InterSystems IRIS OPEN command with the appropriate argument (see table). InterSystems IRIS treats it as a dummy device.
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.
If you open the NULL device other than from within InterSystems IRIS (for example, by redirecting InterSystems IRIS output to /dev/null from the UNIX® shell), the UNIX® system calls do occur as they would for any other 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.