OPEN and USE Commands

OPEN Command

Establishes ownership of the terminal. An optional parameter list can set the right margin, specify device protocols, and specify one or more termination characters. Following the parameter list, you can optionally specify a timeout argument, and/or a mnespace argument. The mnespace argument specifies the InterSystems IRIS routine where control mnemonics for use with WRITE /mnemonic are defined.

OPEN pauses the process until the system finishes opening the device. If you press Ctrl-C to interrupt the OPEN command, a <NOTOPEN> error results.

OPEN retains control until the opening of the device is complete, unless you specify a timeout. With a timeout, if InterSystems IRIS cannot open the device in the number of seconds you specify, it sets $TEST to 0 and returns control to the process. Even if a device is unavailable at the operating-system level, OPEN keeps trying to obtain the device until it succeeds or the timeout expires.

OPEN Syntax

The OPEN command takes the following arguments:

OPEN terminal:(margin:protocols:terminator:portstate:baud):timeout:"mnespace"

Only the terminal argument is required. The terminal argument can be an expression whose value is the name of a terminal device. Zero (0) is the process’s principal device. $IO is the current device. The maximum length of terminal is 256 characters.

Arguments are separated by colons (:). If you omit an argument within the list, you must specify the colon as placeholder. However, trailing colons are not permitted; you must not end either the command or its parameter list with a colon.

The optional parameter list is enclosed in parentheses and can contain the following optional parameters:

margin is an integer that specifies the number of characters per line by specifying the right margin.
protocols is one or more letter codes that specify terminal options.
terminator is a string of one or more characters that terminate a READ operation. These characters supplement the termination characters that are defined for a specific protocols.
portstate is a string that specifies the COM port state.
baud is an integer that specifies the baud rate for a COM port.

You can specify these optional parameters as either positional parameters (in the order shown), or as keyword parameters with the syntax /KEYWORD=value. Keyword parameters may be specified in any order; because InterSystems IRIS executes parameters in left-to-right order, interactions between parameters may dictate a preferred order in some cases. You can mix positional parameters and keyword parameters in the same parameter list. The enclosing parentheses are required if you specify more than one parameter.

The following parameter lists are equivalent:

   OPEN $IO:(80:"BFU":$CHAR(13)) 
    ; all positional
   OPEN $IO:(80::$CHAR(13):/PARAMS="BFU") 
    ; mixed positional and keyword, using the /PARAMS keyword
    ; to specify a protocol letter code string.
   OPEN $IO:(/MARGIN=80:/TERMINATOR=$CHAR(13):/BREAK:/FLUSH:/UPCASE)
    ; all keyword, using separate keywords 
    ; for each protocol letter code.

Following the parameter list (or a placeholder colon, if no parameter list is specified), you can specify an optional timeout in seconds, and a mnespace argument to specify the routine that contains the control mnemonics for this device.

For more information, see OPEN in the ObjectScript Language Reference.

USE Command

Makes the specified terminal the current device. In programmer mode, all subsequent I/O commands on the same line of code refer to that device. In application mode, the device you name in a USE command remains the current device until the next USE command.

USE Syntax

The USE command takes the following arguments:

USE terminal:(margin:protocols:terminator):"mnespace"

The terminal argument can be an expression whose value is the name of a terminal device. Zero (0) is the process’s principal device. $IO is the current device. The maximum length of terminal is 256 characters.

Arguments are separated by colons (:). If you omit an argument, you must specify the colon. You must not end either the command or its parameter list with a colon.

The optional parameter list is enclosed in parentheses and can contain the margin, protocols, and terminator parameters. You can specify the optional margin, protocols, and terminator parameters as either positional parameters (in the order shown), or as keyword parameters with the syntax /KEYWORD=value. Keyword parameters may be specified in any order; because InterSystems IRIS executes parameters in left-to-right order, interactions between parameters may dictate a preferred order in some cases. You can mix positional parameters and keyword parameters in the same parameter list. The enclosing parentheses are required if you specify more than one parameter.

To specify COM port state and baud rate with the USE command, use the appropriate keyword parameters.

Following the parameter list (or a placeholder colon, if no parameter list is specified), you can specify an optional mnespace argument, which identifies an ObjectScript routine where control mnemonics for use with WRITE /mnemonic are defined.

For more information, see USE in the ObjectScript Language Reference.

Positional Parameters for OPEN and USE Commands

The following positional parameters are available for the OPEN and USE commands. You can set these parameters for a device in either the OPEN or USE command, or take the defaults configured in the Management Portal. These parameters are positional; if you omit a parameter, you must include its preceding colon as a placeholder.

margin

The 1st positional parameter: An integer value specifying the right margin (and thus the number of characters per line). Values from 1 to 255 set the right margin for output; any other value disables the right margin. An empty string leaves the margin setting unchanged. On Windows platforms, you cannot use “:n” to control the print margin used. Such notation is ignored by InterSystems IRIS. Code such as “|PRN| :121” is ignored. To control the printer width, send the appropriate control characters for that printer. The notation does work on other platforms.

The default margins for various terminal types are defined in the Management Portal. Select System Administration, Configuration, Device Settings, Device Subtypes. When you click on “Edit” for each listed device subtype, it displays a Right Margin: default option.

protocols

The 2nd positional parameter: A string of letter code characters enclosed in quotation marks (for example, "BNFU”), where each letter enables one of the terminal’s rules for communicating. Letter codes are not case-sensitive. Letter codes may be specified in any order; because InterSystems IRIS executes them in left-to-right order, interactions between letter codes may dictate a preferred order in some cases. For a table of letter codes, see Letter Code Protocols.

A preceding plus or minus affects protocols as follows:

No preceding plus or minus: New string replaces prior protocols string.
Plus (+) precedes letter code string: Protocols in new string are added to prior protocols string.
Minus (-) precedes letter code string: Protocols in new string are turned off, but other protocols remain in effect.

The + and – options for turning protocols on and off are not available in DSM-11 compatibility modes.

terminator

The 3rd positional parameter: A string of up to eight characters, any of which will terminate a READ. These terminators are in addition to those built into the protocols. See Using Terminators to End I/O Operations.

portstate

The 4th positional parameter: A string of up to eight bytes in positional order that govern the COM port state. The portstate bytes are as follows (bytes are numbered from 1 in left-to-right order):

Byte	Meaning	Values
1	Disconnect	D=disconnect (hangup) the port. blank=do not disconnect the port.
2	Modem Control	1=use modem control. 0=do not use modem control. blank=no change to modem control.
3	Data Bits	5=five data bits. 6=six data bits. 7=seven data bits. 8=eight data bits. blank=no change to data bit setting.
4	Parity	0=no parity. 1=odd parity. 2=even parity. 3=mark parity. 4=space parity. blank=no change to parity setting.
5	Stop Bits	1=one stop bit. 5=1.5 stop bits. 2=two stop bits. blank=no change to stop bit setting.
6	Flow Control	X=use Xon/Xoff flow control. C=use CTS/RTS flow control. D=use DSR/DTR flow control. N=disable flow control. blank=no change to flow control.
7	DTR Setting	0=disable DTR (set it off, keep it off). 1=enable DTR (set it on, keep it on). blank=no change to DTR state.
8	$ZA Error Reporting	0=disable $ZA error reporting (default). 1=enable $ZA error reporting. blank=no change to $ZA error reporting.

The following example shows a COM port state string:

  OPEN "COM2":(:::" 0801x0")

The string values are: blank (do not disconnect the port); 0 (do not use modem control); 8 (eight data bits); 0 (no parity); 1 (one stop bit); X (use Xon/Xoff flow control); 0 (disable DTR); default (disable $ZA error reporting).

The Disconnect parameter performs a hangup on modem-controlled ports by lowering the DTR signal for two seconds and then restoring it. A disconnect does not close the port; following a disconnect you can dial out again without reopening the COM device.

The Modem Control parameter determines how InterSystems IRIS responds to the state of the RLSD (Received Line Signal Detector) pin, also known as the DCD (Data Carrier Detect). If the line is modem controlled (modem control=1), InterSystems IRIS monitors the state of the RLSD, and generates an <ENDOFFILE> error if a READ command is issued when carrier is not present. InterSystems IRIS does not generate an error when a WRITE command is issued when carrier is not present. This is because it must be possible to send the dial command to the modem prior to a connection being established. InterSystems IRIS modem control can be enabled (1) or disabled (0) at any time. It is suggested that you disable modem control while sending commands to the modem, then enable modem control once carrier is detected and connection has been established.

The DTR Setting parameter is used to control login from an attached modem. If the DTR setting is 0 (zero), the DTR control signal is off, and modems cannot communicate with the computer. This prevents a dial-in connection from occurring. If the DTR setting is 1 (one), the DTR control signal is on, and modems can communicate with the computer. A dial-in connection can occur. If you configure DTR as off (0), then you must set it to on (1) with the OPEN command or USE command to be able to dial out using a connected modem. In most cases, the DTR setting is unimportant when using a null modem cable to connect directly to a terminal device or a serial printer. This is because the null modem cable should force the DTR control pin on.

The $ZA Error Reporting parameter enables reporting of the status of modem control pins to the $ZA special variable. This checking can be done regardless of the Modem Control byte setting for the COM port. If $ZA error reporting is enabled, COM port errors are cleared with a call to the Windows ClearCommError() function. The port error state is reported in the $ZA bits 16 through 22. For a table of $ZA bit values, refer to $ZA in the ObjectScript Reference.

baud

The 5th positional parameter: an integer value that specifies the desired COM port baud rate. The following baud rates are supported: 110, 300, 600, 1200, 4800, 9600, 14400, 19200, 38400, 56000, 57600, 115200, 128000, 256000.

Keyword Parameters for OPEN and USE Commands

The following table describes the keyword parameters for controlling terminal devices with both OPEN and USE commands. For each keyword, the table lists the corresponding Letter Code Protocols for OPEN and USE. Additional information on the use of these protocols can be found in the Letter Code Protocols table.

OPEN and USE Keyword Parameters for Terminal Devices

Keyword	Default	Letter Code Protocols	Description
/BAUD=n			Corresponds to the baud positional parameter. /BAUD=n sets the modem baud rate for a port. Supported values depend on the operating system support. /SPEED is an alias for /BAUD.
/BREAK[=n] or /BRE[=n]	0	B	/BREAK or /BREAK=n for nonzero values of n enable the protocol. /BREAK=n for a zero value of n disables the protocol.
/COMPARAMS=str			Corresponds to the portstate positional parameter. (This keyword provides a way to specify a COM port state byte code string in a position-independent way.) The portstate byte codes that you can include in str, are listed in a table in earlier on this page.
/COMPRESS=str	""		Specifies the stream data compression type. You can enable a compression type of ZLIB or ZSTD. You can specify /COMPRESS="" to disable compression. /COMPRESS="zlib" is equivalent to /GZIP=1. To compress a string, use %SYSTEM.Util.Compress()Opens in a new tab.
/CRT[=n]	Depends on the operating system terminal setting	C and P	Associated with the C and P protocols. /CRT or /CRT=n for nonzero values of n enable the C protocol and disable the P protocol. /CRT=n for a zero value of n disables the C protocol and enables the P protocol.
/DATABITS=n			Sets the number of data bits for a serial port. Valid values are 5, 6, 7, or 8.
/DISCONNECT			Corresponds to 1st byte of the portstate positional parameter. /DISCONNECT disconnects (hangs up) the COM port. It does not close the port; you can dial out again without reopening the COM device.
/ECHO[=n]	1	S	/ECHO or /ECHO=n for nonzero values of n disable the protocol. /ECHO=n for a zero value of n enables the protocol.
/EDIT[=n]	0	R and N	/EDIT or /EDIT=n for nonzero values of n enable the R protocol and disable the N protocol. /EDIT=n for a zero value of n disables the R protocol and enables the N protocol.
/FLOW=str			Specifies the type of flow control to use for a serial port. Valid values are NONE and XON. Some operating systems also support RTSCTS.
/FLUSH[=n] or /FLU[=n]	0	F	/FLUSH or /FLUSH=n for nonzero values of n enable the protocol. /FLUSH=n for a zero value of n disables the protocol.
/GZIP[=n]	1		Specifies GZIP-compatible stream data compression. /GZIP or /GZIP=n (for nonzero values of n) enables compression on WRITE and decompression on READ. /GZIP=0 disables compression and decompression. Before issuing /GZIP=0 to disable compression and decompression, check the $ZEOS special variable to make sure that a stream data read is not in progress. /GZIP compression has no effect on I/O translation, such as translation established using /IOTABLE. This is because compression is applied after all other translation (except encryption) and decompression is applied before all other translation (except encryption).
/IMAGE[=n] or /IMA[=n]	0	I	/IMAGE or /IMAGE=n for nonzero values of n enable the protocol. /IMAGE=n for a zero value of n disables the protocol.
/IOTABLE[=name] or /IOT[=name]	If name is not specified, the default I/O translation table for the device is used.		Corresponds to the K\name\ protocol, which establishes an I/O translation table for the device.
/MARGIN=n or /MAR=n	0 (no margin)		Corresponds to the margin positional parameter, which sets the right margin for the terminal device.
/MODE=n	No default		Resets protocols and sets the terminal mode according to the value of n. n=0 sets LF and ESC as default terminators. n=1 is the same as mode 0 and enables the S protocol. n=2 is the same as mode 0 and enables the T protocol.
/NOXY [=n]	0		No $X and $Y processing: /NOXY or /NOXY=n (for nonzero values of n) disables $X and $Y processing. This can substantially improve performance of READ and WRITE operations. The values of the $X and $Y variables are indeterminate, and margin processing (which depends on $X) is disabled. /NOXY=0 enables $X and $Y processing; this is the default.
/OBUFSIZE=nnn	256		Specifies the size of the terminal output buffer in bytes. Increasing the output buffer size can improve performance of screen painting with telnet over wide area networks with high latency. Valid values for /OBUFSIZE are 256 through 65536. The default is 256.
/PARAMS=str or /PAR=str	No default		Corresponds to the protocols positional parameter. (This keyword provides a way to specify a protocols letter code string in a position-independent way.) For a table of letter codes that you can include in str, see Letter Code Protocols.
/PARITY=str			Specifies the type of parity checking for a serial port. Valid values are NONE, EVEN, ODD. Some operating systems also support MARK and SPACE.
/SPEED=n			/SPEED is an alias for /BAUD.
/STOPBITS=n			Sets the number of stop bits for a serial port. Valid values are 1 or 2.
/TERMINATOR=str or /TER=str	No default		Corresponds to the terminator positional parameter, which establishes user-defined terminators. To compose str, see Using Terminators to End I/O Operations.
/TPROTOCOL[=n] or /TPR[=n]	0	T	/TPROTOCOL or /TPROTOCOL=n for nonzero values of n enable the protocol. /TPROTOCOL=n for a zero value of n disables the protocol.
/TRANSLATE[=n] or /TRA[=n]	1	K	/TRANSLATE or /TRANSLATE=n for nonzero values of n enable I/O translation for the device. /TRANSLATE=n for a zero value of n disables I/O translation for the device.
/UPCASE[=n] or /UPC[=n]	0	U	/UPCASE or /UPCASE=n for nonzero values of n enable the protocol. /UPCASE=n for a zero value of n disables the protocol.
/XYTABLE[=name] or /XYT[=name]	If name is not specified, the default $X/$Y action table for the device is used.	Y\name\	Corresponds to the Y\name\ protocol, which establishes a $X/$Y action table for the device.

Testing the Success of OPEN Commands

To determine whether an OPEN command succeeded, your code should test $TEST and/or $ZE. $TEST is only set if the OPEN command was specified with a timeout argument. A <NOTOPEN> error occurs only when Ctrl-C interrupts an OPEN command. Therefore, your code must not depend on <NOTOPEN> errors.

Letter Code Protocols for OPEN and USE

Special situations or terminals can require different protocols. With the protocols letter code parameter (or the corresponding keyword parameters) you can change the rules by which InterSystems IRIS communicates with the terminal. Protocols affect normal and single-character reads alike.

Normal mode, with all special protocols disabled, suffices for most terminal I/O. In normal mode InterSystems IRIS echoes each incoming ASCII character, sending it back to appear on the terminal. A Return, or a valid escape sequence, ends a READ command.

Issuing OPEN for a terminal turns off all previous protocols, except when you use the + and - options.

The following table describes valid protocols characters and their effects.

Letter Code Protocols for OPEN and USE

Protocol Character	Name	Definition
B	BREAK	If breaks are enabled (+B), Ctrl-C interrupts a running routine with an <INTERRUPT> error. If breaks are disabled (-B), Ctrl-C does not cause an interrupt and “^C” is not displayed. The use of this protocol is dependent upon the BREAK command default established by the login mode, as follows: If you log in as programmer mode, interrupts are always enabled (BREAK 1). The B (or /BREAK) protocol specified in an OPEN or USE command has no effect. If you log in as application mode, BREAK 0 is the default, and interrupts can be enabled or disabled by the B (or /BREAK) protocol specified in the OPEN or USE command.
C	CRT terminal	C mode accepts all eight bit characters as data, except for the following six: ASCII 3, 8, 10, 13, 21, and 127. The ASCII 127 Delete character echoes as a destructive backspace, that is, it backspaces and erases the preceding character. ASCII 21 (Ctrl-U) echoes enough destructive backspaces to bring the cursor to the start of the READ. If the setting for the right margin, or the nature of the terminal, forces echoed characters to begin a new line, Ctrl-U can erase only the characters on the last physical line. In any case, Ctrl-U cancels all input since the start of the READ. C is mutually exclusive with the P protocol.
F	Flush	Flush (empty) the input buffer before each READ. You can flush the input buffer to prohibit the user from typing ahead of READ operations on the terminal, because InterSystems IRIS discards anything typed between READ operations. Note that the command WRITE *–1 flushes the input buffer at any time, regardless of the F protocol.
I	Image mode	I mode accepts all 256 eight bit characters as data, treating none as a READ terminator, except the termination character(s) (if any) that you explicitly specify in the terminator parameter. If you do not explicitly specify termination characters, you should use only single character and fixed length READ operations. Without defined termination characters, an ordinary READ results in a <TERMINATOR> error. Image mode (I) protocol can be combined with other protocol characters. In image mode, InterSystems IRIS ignores the protocol characters P, C and B. In image mode, the protocol characters F, N, R, S, and T remain in effect. When not in image mode, the device is in N (normal) mode.
K\name\ or Knum	I/O Translation Mode	When you use the K protocol for a device, I/O translation will occur for that device if translation has been enabled system-wide. You identify the previously defined table on which the translation is based by specifying the table’s name. (The older form Knum, where “num” represents the number of the slot the table is loaded in, is being phased out but is still supported.)
N	Normal mode	N mode accepts all eight bit characters as data, except for the following six: ASCII 3, 8, 10, 13, 21, and 127. These implicit terminator and command line editing control characters, are described later on this page. If R (read line recall) protocol is enabled, N disables R protocol. This mode is the default if no protocols value is specified.
P	Print device	The ASCII Delete character echoes as a backslash (\), and Ctrl-U echoes as “^U” followed by a carriage return and line feed. When you issue an OPEN command for a terminal, InterSystems IRIS invokes the protocol C or P automatically, depending on the operating system terminal setting. These protocols remain in effect until you change the protocols for the device explicitly. A protocol string containing neither C nor P does not cancel this protocol.
R	Enable read line recall mode	The R protocol enables read line recall mode for that device. To activate read line recall for the current process, use the LineRecall()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. To set the system-wide read line recall default, use the LineRecallOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class. The R protocol overrides these default settings for the specified device. To change read line recall for an already-open device, you must explicitly specify another OPEN command to that device. Read line recall is disabled by specifying the N protocol.
S	Secret input	Nothing echoes on a READ. READ commands do not change $X and $Y. Read line recall is disabled.
T	Terminator	T mode does not treat any control characters as data. The following are control characters: ASCII characters with decimal values from 0 to 31 and 127 to 159. Most of these control characters are treated as READ terminator characters. The exceptions are the following control characters, which perform other control operations: ASCII 3 (Ctrl-C), ASCII 8 (backspace), ASCII 17 (Ctrl-Q), ASCII 19 (Ctrl-S), ASCII 21 (Ctrl-U), ASCII 24 (Ctrl-X), ASCII 27 (ESC), and ASCII 127 (DEL). When T mode is combined with I mode (IT protocol) all control characters (ASCII 0 to 31 and 127 to 159) are treated as READ terminator characters, with the exceptions of the output control characters Ctrl-Q (XOFF), and Ctrl-S (XON), and the input control characters Ctrl-H and Ctrl-Y. Output control characters Ctrl-Q and Ctrl-S are intercepted by most terminals and do not terminate a READ even in IT mode.
U	Upcase mode	U mode converts all input letters to upper case.
Y\name\ or Ynum	$X/$Y Action Mode	When you use the Y protocol for a device, the system uses the named $X/$Y Action Table. You identify a previously defined $X/$Y Action Table on used to translate by specifying the table name. $X/$Y action is always enabled. If Y is not specified and a system default $X/$Y is not defined, a built in $X/$Y action table is used. The + option works for turning on the Y protocol, but the - option does not. In order to disable a $X/$Y association, you can issue the command: USE 0:(:"Y0") (The older form Ynum, where num represents the number of the slot the table is loaded in, is being phased out but is still supported.)

Examples of Protocol Strings

The following series of examples show how protocol strings function. Each of the following USE commands builds on the protocol established by the preceding USE commands:

   USE 0:(80:"BP" )

The letter codes BP turn on the B and P protocols. This example enables breaks (B) and tells InterSystems IRIS to treat the terminal as a printing device (P).

   USE 0:(80:"P")

When it follows the USE command in the example just above, this command leaves the P protocol in effect, but turns off the B protocol.

   USE 0:(80:"+R" )

+R turns on read line recall, without affecting other protocol settings.

   USE 0:(80:"")

The empty string turns off all protocols. However, the P or C protocol remains in effect.

   USE 0:(80)

Omitting the protocol parameter leaves the protocol and explicit terminators unchanged.

Protocol Terminator Characters

OPEN and USE protocols define what READ input characters, control sequences, and keystrokes are treated as implicit terminator characters. These four protocols are I (image mode), N (normal mode (the default)), R (read line recall mode), and T (terminator mode):

I (image mode) accepts all 256 eight bit characters as data, treating none as a READ input terminator or a command line editing character. Because of this, you should use only single character or fixed length READ operations in image mode. Without defined termination characters, an ordinary READ results in a <TERMINATOR> error.
N (normal mode) and C (CRT mode) accept all characters as data except the following six: ASCII 3, 8, 10, 13, 21, and 127. Two of these, ASCII 10 (linefeed) and 13 (carriage return) terminate READ and submit input. ASCII 3 (Ctrl-C) discards input and issues an <INTERRUPT> error if BREAK is enabled. ASCII 8 (backspace) and 127 (delete) perform a single-character backspace erase then continue READ. ASCII 21 performs a multi-character backspace, erasing all prior characters, then continues READ.

R (read line recall mode) accepts all characters as data except the following twenty: ASCII 1 through 8, 10 through 14, 16, 18, 21, 23, 24, 27, and 127. ASCII 10 (linefeed) and 13 (carriage return) terminate READ and submit input. ASCII 3 (Ctrl-C) discards input and issues an <INTERRUPT> if BREAK is enabled. The other characters perform the following command line editing functions:

1   ^A = beginning of line
2   ^B = back word
3   ^C = interrupt
4   ^D = delete current character
5   ^E = end of line
6   ^F = forward word
7   ^G = delete to beginning of word ("wipe word backward")
8   ^H = BS = destructive backspace
9   ^I = HT = horizontal tab (echoed as a SPACE)
10  ^J = LF = end of input
11  ^K = VT = forward character
12  ^L = FF = erase to end of line
13  ^M = CR = end of input (same as LF)
14  ^N = recall next input line
16  ^P = recall previous input line
18  ^R = back char (reverse)
21  ^U = erase to start of line
23  ^W = delete to end of word "gobble word forward")
24  ^X = erase entire line
27  ESC lead character for arrow and function keys
127 DEL = destructive backspace (same as BS)

T (terminator mode) accepts all characters as data except the 65 control characters: ASCII 0 through 31 and ASCII 127 through 159. Most of these characters are treated as READ termination characters. This includes the tab character (ASCII 9), which is treated as a data character in all other protocols. A few characters are treated as command line control characters: ASCII 3 (Ctrl-C) discards input and issues an <INTERRUPT> if BREAK is enabled. ASCII 8 (backspace) and 127 (delete) perform a single-character backspace erase then continue READ. ASCII 21 (Ctrl-U) and ASCII 24 (Ctrl-X) perform a multi-character backspace, erasing all prior characters, then continues READ. ASCII 27 is the Escape character.
IT (image mode + terminator mode) accepts all characters as data except the 65 control characters: ASCII 0 through 31 and ASCII 127 through 159. It treats all of the control characters as READ terminator characters.

In any of these modes you can explicitly specify additional terminator characters using the terminator parameter. Because image mode is commonly used for bit stream data, designation of any character as a terminator is usually avoided.

Explicit Terminator Characters

The terminator parameter in the OPEN or USE command lets you define specific characters as terminators for a READ or WRITE command. These explicit terminators can be used to supplement the terminator characters supplied by the specified protocol. The terminator parameter can also be used to override the designation of a character by the protocol, and instead designate it a terminator character. The exceptions to this ability to redefine a character as a terminator are: ASCII 0 (NULL), ASCII 3 (Ctrl-C), and the two output control characters Ctrl-Q (XON) and Ctrl-S (XOFF). These retain their functionality, and cannot be redefined as terminator characters.

Example

This example defines Z, Backspace and Tab as terminators for the principal device. The underscore is the concatenate operator.

  USE 0:("":"":"Z"_$CHAR(8,9))

By issuing an OPEN command for an unowned terminal, you implicitly clear the InterSystems IRIS internal list of explicit terminators. When a protocol string appears, InterSystems IRIS then does the following:

Clears its list of explicit terminators.
Sets protocols according to the protocol string.
Copies a terminator string, if any, into the internal list of explicit terminators.
The following table gives examples of explicit terminator strings.

Terminator Strings: Examples

Terminator String	Definition
USE 0:(80:"C":$CHAR(27))	The Escape character terminates a READ rather than beginning an escape sequence.
USE 0:(80:"C":"")	The empty string clears all terminators.
USE 0:(80:"C")	Omitting the terminator parameter when you specify protocol clears all terminators.
USE 0:(80) or U 0:80	Omitting both protocol and terminator leaves terminators unchanged.

Summary of Protocols and Terminators in Read Operations

The following characters end a normal (nonimage) mode READ:

Enter
Any character in the terminator string except ASCII NUL and the characters Ctrl-C, Ctrl-O, Ctrl-Q, and Ctrl-S.
With the T protocol in effect, any control character except the output control characters. Control characters are nonprinting characters with decimal values 0 to 31 and 127 to 159.
Any escape sequence.
Character number y of a fixed-length READ x#y.

The following characters end an image-mode READ:

Any character specified in the terminator string except ASCII NUL.
With the T protocol in effect, any control character.
Character number y of a fixed-length READ x#y.

READ Command

Special Variables Show I/O Conditions