This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see How to Migrate to InterSystems IRIS, available on the WRC Distributions page (login required).


abstract class %Library.Device extends %SYSTEM.Help

Method Inventory (Including Private)


classmethod Broadcast(terminal As %String, message As %String, level As %Integer = 0) as %Status

The Broadcast class method has two syntactic forms. The first sends a message to the specified terminal, and can optionally time out. The second sends a message to the operator console (specified by the null string), and also logs the message.

Broadcast(terminal,message) passes the message to the specified terminal. If you specify your own principal device, your message appears on your terminal screen.

Broadcast("",message) passes the message to the operator console, logging it in the console log file. By default, the console log file is cconsole.log, which can be accessed via the System Management Portal System Logs option. This default console log file location is configurable. Go to the Management Portal, select [Home] > [System Administration] > [Configuration] > [Additional Settings] > [Advanced Memory]. View and edit the current setting of ConsoleFile. By default this setting is blank, routing console messages to cconsole.log in the MGR directory. If you change this setting, you must restart the system for this change to take effect.
Broadcast does not add any carriage control to the message it sends. To include any carriage control (carriage returns or line feeds), you must include them in the message, using $CHAR(10) and $CHAR(13).

Broadcast returns 1 if successful; 0 if not successful.


The device name of the terminal to which you want to send a message, specified as a quoted string. Specify the null string ("") to send the message to the system console.

The message to send, specified as a quoted string.

when used with named terminal only ? A timeout in seconds. If Broadcast is not able to send the message during the period of the timeout, it ceases attempts to send the message after the timeout expires.
when used with operator console only ? The log level you want to assign to the message.

You can use the following values:
0 = Send the message to the following locations: Operator console log file, Caché console.
1 = Send the message to the following locations: Operator console log file, Caché console, System-wide operator console facility.
classmethod ChangePrincipal() as %Status
The ChangePrincipal() class method makes the current device (last device specified in a USE command) be the principal I/O device (referenceable by USE 0 or USE $PRINCIPAL.) This method makes the current device the principal I/O device, while leaving the former principal I/O device open, and thus capable of being used explicitly by name.

ChangePrincipal() takes no arguments. It returns 1 on success, 0 on failure.
classmethod Get(Prompt As %String, ByRef Value As %String, ByRef Help As %String, Flag As %Integer = 0, Timeout As %Integer = 0, IOFlag As %Integer = 1, ByRef IOSL As %String, ByRef IOM As %Integer, ByRef IOF As %String, ByRef IOBS As %String, ByRef IOPAR As %String, ByRef IOT As %String, ByRef IOST As %String, ByRef ANS As %String, ByRef RMSDF As %String, ByRef IODOC As %String, ByRef IODES As %String)
Get and open an INPUT or OUTPUT device.
Input Parameters:
Prompt - Prompt to be displayed
Value - Default value
Help - Array of help text
Flag - From
- $$$DisableBackupCharMask - Disable entry of the backup character
- $$$TrapCtrlCMask - Trap CTRL/C and return CTRL/C status
- $$$EnableQuitCharMask - Enable quit and return Quit status
- $$$DisableHelpCharMask - Disable entry of the help character
- $$$TrapErrorMask - Trap errors and return error status
TimeOut - Timeout for prompt
IOFlag - Mask containing one of the following values
- 1= Get input or output device (Default)
- 2= Get input device
- 4= Get output device
- 8= Open passed in Value without prompting

Output parameters:
Status - One of the following from %syPrompt:
$$$SuccessResponse - Successful entry, Value contains valid open device
$$$BackupResponse - Backup character entered
$$$QuitResponse - Quit character entered if $$$EnableQuitCharMask set
$$$CtrlCResponse - CTRL/C entered if $$$TrapCtrlCMask set
$$$ErrorResponse - Error during entry if $$$TrapErrorMask set
$$$HelpResponse - Help character entered if $$$DisableHelpCharMask set

Value - Open device name
IOSL - Number of lines per screen
IOM - Right margin
IOBS - Backspace character
IOPAR - IO parameters
IOT - Device type
IOST - Expanded device type
ANS - Device typed in by user
RMSDF - Default RMS parameters
IODOC - Spool file name
IODES - Spool file description

Typical usage is as follows: s Status=##Class(%Library.Device).Get("Device:",.Value,,$$$TrapCtrlCMask+$$$EnableQuitCharMask,,IOFlag,.IOSL,.IOM)
i (Status=$$$CtrlCResponse)||(Status=$$$QuitResponse) q
i (Status=$$$BackupResponse) g PreviousPrompt
use Value
w !,"Right margin is "_IOM
w !,"Lines per page is "_IOSL
close Value
classmethod GetBackSpace() as %String
Return the Back Space string for the process principal device.
classmethod GetClearScreen() as %String
Return the Clear Screen (Form Feed) string for the process principal device.
classmethod GetCurrent(ByRef IO As %String, ByRef SL As %String, ByRef RM As %String, ByRef FF As %String, ByRef BS As %String, ByRef SUB As %String, ByRef XY As %String)
Get current device info from %IS global.
Get current device info from %IS global and set default FormFeed and Backspace strings for the process based on information in the %IS global.
Return Values:
IO - Device name
SL - Number of screen lines of the device
RM - Right margin of the device
FF - Form feed character of the device
BS - Back space character of the device
SUB - Device subtype
XY - XY cursor positioning string
This method replaces the CURRENT^%IS call.
classmethod GetMnemonicDirectory() as %String
Return the write mnemonic space routine directory for the current device.
classmethod GetMnemonicRoutine() as %String
Return the write mnemonic space routine name for the current device.
classmethod GetNullDevice() as %String
Return the name of the null device for the platform.
classmethod GetPrinters() as %List
Return a list of printers that the system recognizes.

This method is supported only for Windows platform, for non Windows platform it always returns a null string.

It returns a null string when there is no printer recognized by the system.
Use $LISTLENGTH function to get number of printers in the returned list. Use $LIST function to get each printer name in the list. Note that you need to add "|PRN|" at beginning of each printer name in order to use OPEN command to open the printer device.
classmethod GetReadTerminators() as %String
Return the read terminator string for the current device.
Does not apply to some devices.
classmethod GetRightMargin() as %Integer
Return the right margin setting for the current device.
This only applies to terminals.
classmethod GetType() as %Integer
Returns an integer which specifies the type of device.
0 - sequential file
1 - terminal
2 - spool device (device #2)
3 - magnetic tape (device numbers 47-50)
4 - system operator's console (device 1)
5 - pseudo-device (device numbers 20-46)
6 - Null device
7 - spooled virtual console
8 - IJC device (devices 224-255)
9 - TCP device
11 - NetBIOS NTI device
12 - Named Pipe device
13 - Memory-mapped device
14 - XDEV extensible device
classmethod InstalledPrinters(n As %Integer) as %DataType
The InstalledPrinters() class method returns the number of printers currently installed on your system, counting from 1.

The InstalledPrinters(n) method, where 1 <= n <= InstalledPrinters(), returns the pathname of the printer currently installed on your system that corresponds to n. The system counts printers from 1, and assigns a sequential integer to each. If n is a number that does not correspond to a printer, the system issues a error.
classmethod ReDirectIO(n As %Boolean) as %Boolean
The ReDirectIO() class method returns the status of the I/O redirection switch for the current device.

The ReDirectIO(n) class method sets the I/O redirection switch for the current device according to the boolean value n. It returns the previous setting of this switch.
classmethod SetFFBS(ff As %String, bs As %String) as %Status
The SetFFBS class method specifies the form feed or backspace control code sequence used by printers.

ff : The new value for the form feed control code sequence. If omitted, the system default, as defined for Device 0, is used. May not be omitted if the bs parameter is present.
bs : The new value for the backspace control code sequence. If omitted, the system default, as defined for Device 0, is used.

This function is used to change the form feed and backspace control code sequences.
SetFFBS(ff,bs) sets form feed control sequence to ff and backspace control sequence to bs.
SetFFBS(ff) sets form feed control sequence to ff and backspace control sequence to system default.
SetFFBS() sets the printer form feed and backspace control sequences to system default.

Inherited Members

Inherited Methods (Including Private)