Skip to main content

Terminal I/O

This page discusses terminal I/O in InterSystems IRIS® data platform.

Overview

ObjectScript provides commands that support serial asynchronous ASCII terminals. You can also use these commands with console I/O.

Using Terminal I/O, your routine can:

  • Enable or disable the echo of incoming characters.

  • Send and receive ANSI-standard escape sequences.

  • Control keyboard interruptions and program special user interactions, including formatted screens, reverse video, and special keys for skipping fields.

  • Enable and disable recognition of Ctrl-C interrupts.

  • Control the flow of incoming and outgoing data by XON (Ctrl-Q) and XOFF (Ctrl-S).

  • Specify COM port state parameters and modem baud rate.

  • Conform to foreign protocols when you specify your own set of termination characters.

  • Communicate with non-terminal devices, such as automated instruments.

Printers are handled as terminal I/O devices on most platforms. UNIX® systems always handle a printer as a terminal I/O device. On Windows, a printer connected through a serial communications port is handled as a terminal I/O device. Otherwise, Windows systems handle printers as sequential file I/O devices. For further details, see Printers.

Your Login Terminal or Console is Your Principal Device

The terminal or console on which you log in to InterSystems IRIS is your principal device. You need not open your principal device. If you have not issued an OPEN and a USE, the first time a process issues a READ or WRITE, the system opens your principal device automatically, and establishes it as the current device, as if you had issued OPEN 0 USE 0 explicitly.

Note:

Through the rest of this page, the word terminal is used to refer to both terminals and consoles.

Special Variables Show I/O Conditions

I/O commands can affect the values of special variables. You can test these variables to determine I/O conditions:

  • $IO contains the name of the current device.

  • $TEST contains a boolean value that shows whether the most recent timed operation was successful.

  • $X and $Y show the position of the cursor.

  • $ZA, $ZB, and $KEY show information about READ operations. $ZB and $KEY are similar, but not identical.

See Introduction to I/O for more information on the device-independent $IO special variable. The next sections describe terminal-specific information about the remaining special variables.

$X and $Y and Cursor Position

$X contains the horizontal position and $Y the vertical position of the cursor or print head. $X=0,$Y=0 denotes the upper left corner of the CRT screen or the printed page. InterSystems IRIS calculates both $X and $Y modulo 256; that is, they range from 0 to 255 and then begin again at 0.

The following table shows the effects of writing or echoing the characters

Effects of Echoing Characters
Character ASCII Code Effect on $X Effect on $Y
Form Feed 12 $X=0 $Y=0
Return 13 $X=0 $Y=$Y
Line Feed 10 $X=$X $Y=$Y+1
Backspace 8 $X=$X-1 $Y=$Y
Tab 9 $X=$X+1 $Y=$Y
Any printable ASCII character 32 through 126 $X=$X+1 $Y=$Y

The S protocol of OPEN and USE turns off the echo. This protocol also disables the changing of $X and $Y during input, so that they truly indicate the cursor’s position.

WRITE * and $X and $Y

WRITE * does not change $X and $Y. Thus, you can send a control sequence to your terminal and $X and $Y will still reflect the true cursor position. Some control sequences do move the cursor, so you can set $X or $Y directly when you need to.

$X and $Y Example

In the following example, a control sequence moves the cursor in a VT100 terminal to line 10, column 20, and sets $X and $Y accordingly.

 ; set DY and DX to desired 
 ; values for $Y and $X 
 SET DY=10
 SET DX=20
 ; ...
 ; escape sequence moves
 ; cursor to desired position
 WRITE *27, *91, DY+1, *59, DX+1, *72
 ; ...
 ; updates $X and $Y
 SET $Y=DY
 SET $X=DX

Effect of Escape Sequences on $X and $Y Varies

Escape sequences can alter the effect of echoing on the values of $X and $Y. Three factors control this effect:

Escape Sequences Affect $X and $Y on Windows and UNIX® Systems

By default on UNIX® and Windows, when writing or echoing any string that includes the ASCII Escape character (decimal value 27), InterSystems IRIS updates $X and $Y just as it does for any other character sequence. Thus, ANSI standard control sequences, which the terminal acts on, but does not display, can upset the relationship of $X and $Y to the cursor’s position.

The easiest way to avoid this problem is to use the DX() method to alter the behavior (see the next section). Alternatively, you can use the ASCII value of each character in the string in a WRITE * statement.

Control Sequence Example

Instead of using the code:

%SYS>WRITE $CHAR(27)_"[lm"

you can use the following equivalent statement that does not update $X and $Y:

%SYS>WRITE *27,*91,*49,*109
Switches Control Updates of $X for Escape Sequences

To select non-default behavior for updating $X for your process, issue the DX(n)Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class.

The system manager can alter the system-wide default behavior by setting the DXOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class.

In both cases, n has a value from 0 through 4, as follows:

Value Default Behavior for Updating $X
0 Default for InterSystems IRIS
1 DSM behavior
2 DTM/MSM behavior

For more information, see $X in the ObjectScript Language Reference.

$TEST Shows Timed Operation Results

The $TEST special variable is set by commands that take a timeout value. These commands include OPEN and READ. The value of $TEST can be set to 1 or 0:

  • $TEST is set to 1 if the timed command succeeded before the timeout expired.

  • $TEST is set to 0 if the timeout expires on a timed command.

Note:

OPEN and READ commands without a timeout have no effect on $TEST.

For more information, see $TEST in the ObjectScript Language Reference.

$ZA Shows READ Status

The $ZA special variable contains a number of bit flags that show the status of the last READ on the current device. You cannot set $ZA; InterSystems IRIS controls its value. $ZA remains valid until the next READ. $ZA contains the sum of the values listed in the table, which shows how your program can test this variable. ($ZA also contains bit flags for modem connection status, which are not listed here. For a complete list of $ZA bit flag values, see $ZA in ObjectScript Language Reference.)

$ZA Read Status Values
Value Test Meaning
1 $ZA#2 A Ctrl-C arrived, whether or not breaks were enabled.
2 $ZA\2#2 The READ timed out.
256 $ZA\256#2 InterSystems IRIS detected an invalid escape sequence.
512 $ZA\512#2 The hardware detected a parity or framing error.

While many of the conditions that $ZA shows are errors, they do not interrupt the program’s flow by trapping to the $ZTRAP special variable. Programs that are concerned with these errors must examine $ZA after every READ. Of course, a Ctrl-C with breaks enabled will trap to $ZTRAP. For more on error trapping and $ZTRAP, see Error Processing and $ZTRAP in the ObjectScript Language Reference.

$ZB Shows What Ended a READ

$ZB shows what character sequence or event ended the last READ operation on the current device. You cannot set $ZB; InterSystems IRIS sets the value of $ZB each time you perform a READ. You can use this value to act on non-printable characters such as the up arrow key or function keys.

$ZB can contain any of the following:

  • A termination character, such as a carriage return

  • An escape sequence

  • Character number y of a fixed-length READ x#y

  • The single character of READ *x

  • An empty string after a timed READ expires

$ZB never contains more than 64 characters. A longer escape sequence is invalid.

$ZB Example

The following example assigns the user-specified input characters to the READ command variable x, and assigns the input terminator (usually the Return character) to the $ZB special variable. When issuing this command from the terminal prompt, you need to set a variable to trap the value of $ZB on the same command line as the READ command. This is because the line return used to issue a command line is written to $ZB as a terminator character. This example uses ZZDUMP to display the value of the characters trapped by $ZB.

USER>READ x SET y=$ZB
USER>ZZDUMP y

0000: 0D 
USER>

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:

  1. Clears its list of explicit terminators.

  2. Sets protocols according to the protocol string.

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

Reads from 0 to 32 KB from the keyboard into the named variable. The timeout argument is optional. The command cannot end with a pound sign (#) or colon (:)

Syntax

READ variable:timeout                                             ; Variable-length read
READ variable#length:timeout  ; Fixed-length read
READ *variable:timeout                                           ; Single-character read

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

Examples

The following table gives several examples of how you use these arguments.

READ Command Arguments: Examples
Example Effect
READ ^GLO Reads characters from the current device until it finds a terminator, and puts the resulting string in the global ^GLO.
READ X:60 Reads from the current device until it finds a terminator, and puts the string read into the variable X. Waits up to 60 seconds for the input to end before timing out. Striking a key does not reset the timeout value.
READ *X Reads a single character from the current device and puts its decimal value in the local variable X.
READ X#1 Reads a single character from the current device and puts its string value into the local variable X.
READ X#45:60 Reads up to 45 characters from the current device and puts the string value into the local variable X. Waits up to 60 seconds for the input to end before timing out.

Read Line Recall

Read line recall mode provides line recall of editable lines as input for READ operations from a terminal. These recallable lines include both previous READ input lines and previous command lines. Echoing of input lines is a necessary precondition for read line recall.

InterSystems IRIS supports read line recall for both variable-length terminal reads (READ variable) and fixed-length terminal reads (READ variable#length). InterSystems IRIS does not support read line recall for single-character terminal reads (READ *varaiable). Read line recall supports the optional timeout argument.

For a fixed-length terminal read, the recalled line is truncated to one character less than the number of characters specified in the READ. This final READ character position is reserved for typing a line termination character, specifying an edit character, or adding one more data character.

When read line recall is active, you can provide input to a READ by using the Up Arrow and Down Arrow keys to recall a previous terminal input line. You can then use the Left Arrow, Right Arrow, Home, and End keys to position the cursor for editing the recalled line. You can use the Backspace key to delete a character, Ctrl-X to delete the entire line, or Ctrl-U to delete all of the line to the left of the cursor.

When read line recall is not active, the four Arrow keys, the Home key, and the End key all issue a line termination character. You can use the Backspace key to delete a single input character, and Ctrl-X (or Ctrl-U) to delete the entire input line.

You can use the OPEN or USE command to activate read line recall by specifying the R protocol, or to deactivate read line recall by specifying the N, I, S, or T protocol.

Special Protocol Characters Affect Terminal I/O

Each operating system intercepts certain protocol characters (UNIX®) or key combinations (such as CTR-ALT-DEL on Windows platforms), preventing these characters from affecting InterSystems IRIS. The console for Windows makes no attempt to override these operating system characteristics.

Other special characters can alter the way your routines execute, but do not appear in the READ command variable. Operating your terminal in image mode cancels these effects and causes InterSystems IRIS to treat these characters like any others.

READ is affected by output and input control characters. READ simply reads all other control characters, except termination characters. It does not echo them.

Output control characters affect both the flow and the output of a routine. These are described in the following table:

Output Control Characters
Output Control Character Decimal Value Definition
Ctrl-C 3 If breaks are enabled, Ctrl-C interrupts a routine’s execution. The routine behaves as though an <INTERRUPT> error has occurred. If breaks are disabled, Ctrl-C causes InterSystems IRIS to discard anything entered thus far in the current READ. You can use Ctrl-C to interrupt global module requests that require network operations. To trap Ctrl-C, set the special variable $ZTRAP. For additional information, see the section on enabling breaks.
Ctrl-S 19 Ctrl-S suspends output to the terminal. Output to the terminal resumes when InterSystems IRIS encounters a Ctrl-Q.
Ctrl-Q 17 Ctrl-Q resumes output suspended by Ctrl-S.

Input control characters affect input. Image mode (I protocol) treats these characters as data, but in normal mode they affect input to the current READ command. These characters are described in the following table:

Input Control Characters
Input Control Character Decimal Values Definition
Delete 127 The Delete character removes the last character entered. If you press Delete repeatedly, you remove characters from right to left, but not beyond the beginning of the current READ. Delete uses a backspace to erase the last character on a CRT screen. Delete echoes as a backslash character ("\") on a printing terminal (such as a teletype).
Ctrl-U 21 Deletes either all characters you have entered since the start of the current READ or the contents of theUNIX® type-ahead buffer until the last carriage return. Ctrl-U erases the deleted characters on a CRT; on a printer it echoes ^U and sends a Return and LineFeed To flush the typeahead buffer completely, use Ctrl-X.
Ctrl-H 8 Performs the same function as Delete on some systems.
Return 13 A carriage return ends a READ in all protocols except “I” (image mode).
Escape 27 Begins an escape sequence. The sequence itself ends the READ, and $ZB contains the full sequence, including the leading Escape. InterSystems IRIS does not echo the characters of the sequence, but it does change $X and $Y unless you include the escape sequence in a WRITE * command. See $X and $Y and Cursor Position earlier on this page. An invalid escape sequence sets bit 8 of $ZA. Consider the example, READ X. After you enter the characters “AB”, Escape, and “E”, X will contain the two characters “AB”, while $ZB contains the two characters Escape E. $X increases by two for the AB, but does not increase for the E.
LineFeed 10 InterSystems IRIS interprets LineFeed as a terminator for all terminal I/O.
Tab 9 Tab is a data value that echoes as a space, increases $X by one, and is stored as a Tab character in the string returned by the READ. This is true for all protocols except “T” (terminator). In “T” protocol, a tab is a terminator control character.

Disabling UNIX® Job Control

Using the UNIX® job control character, Ctrl-Z, within InterSystems IRIS can cause serious problems. For this reason, InterSystems IRIS disables Ctrl-Z automatically when you enter InterSystems IRIS on platforms whose UNIX® shell supports job control. InterSystems IRIS reenables Ctrl-Z when you exit InterSystems, and when you issue a $ZF(-1) call to execute a UNIX® shell command.

How the READ Command Processes Input

The READ command processes each character as it arrives from the input buffer. The following table shows how this processing occurs in normal mode. The figure below shows how the READ command processes image mode data.

READ Command Processing Normal (Non-Image) Mode
flowchart: output ctrl char? processing ESC seq? explicit terminator? input ctrl char? control char and 'T'? Store in
READ Command Processing Image Mode
flowchart: explicit terminator or control char and 'T'? If Y, terminate, store in $ZB, no echo. If N, store in READ v

WRITE Command

Writes zero or more characters to the terminal.

Syntax

WRITE *variable 
WRITE *-n
WRITE # 
WRITE /mnemonic

where

Argument Definition
(none) WRITE with no arguments writes all local variables on the current device.
*variable WRITE *variable writes one character, whose decimal value equals x. The value of variable should be an integer in the range 0 to 255 for ASCII characters, and >255 for Unicode characters. By convention, values from 0 to 127 signify 7 bit ASCII characters, while 128 to 255, which represent the extended ASCII character set, relate to the application itself. If the hardware and software are properly set, InterSystems IRIS can handle 8 bit data. Example : You can use the eighth bit to represent international character sets. InterSystems IRIS routines often use WRITE * to send control characters for device dependent functions. Example : WRITE *27,*91,*50,*74 clears the terminal screen. WRITE * does not change $X or $Y; the assumption is that WRITE * output is highly specific to the output device.
*-1

WRITE *-1 clears the input buffer when the next READ is issued. It clears any characters that are pending for the next READ command. Thus all type-ahead characters are cleared.

An input buffer holds characters as they arrive from the keyboard, even those you type before the routine executes a READ command. Thus you can answer questions even before they appear on the screen. When the READ command takes characters from the buffer, InterSystems IRIS echoes them back to the terminal so that questions and answers appear together. When a routine detects errors, it may issue WRITE *-1 to cancel these answers.

*-10

WRITE *-10 clears the input buffer immediately. It does not wait for the next READ command. Thus it clears all type-ahead characters issued before the WRITE *-10; type-ahead characters issed after the WRITE *-10 remain in the input buffer for use by the next READ.

# Issuing WRITE # to a CRT terminal clears the screen and sends the cursor to the home (0,0) position. For a hardcopy terminal, it writes a Carriage Return and Form Feed. WRITE # sets $Y to 0.
/mnemonic Issuing WRITE /mnemonic causes InterSystems IRIS to interpret mnemonic as defined in the active mnemonic space. If there is no active mnemonic space, an error results. You can specify the active mnemonic space in two ways: By naming a default mnemonic space for each device type using the Namespace and Network Configuration editor by specifying a mnemonic space in the OPEN or USE command for the device. For more information, see Controlling Devices with Mnemonic Spaces.

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

Examples

In the following example, WRITE * rings the bell on the user’s terminal, displays a prompt, and clears the input buffer of any characters received but not yet used.

   SET eek="No. I can't accept that reply" 
   WRITE *7,eek,*-10

The following two examples show the difference between WRITE *-1 and WRITE *-10. In both cases, the user responds to the first READ and presses ENTER, then types ahead during the two pauses caused by the HANG commands:

  READ "type:",x HANG 4 WRITE *-1 HANG 4 READ "type:",y

In the above example, InterSystems IRIS clears the input buffer when the second READ is issued. Thus any text typed during either HANG is cleared from the buffer.

  READ "type:",x HANG 4 WRITE *-10 HANG 4 READ "type:",y

In the above example, InterSystems IRIS immediately clears the input buffer when WRITE *-10 is issued. Thus any text typed during the first HANG is cleared, but any text typed during the second HANG is supplied to the second READ command.

In the following example, WRITE /mnemonic uses the control mnemonic CUP (CUrsor Position) to move the cursor to the third column of the fourth line on the Terminal. In this example, the predefined mnemonic space ^%X364 is specified in the USE command, and the name of an open Terminal device is specified using the terminal variable. See Predefined Mnemonic Spaces for Terminals for a description of ^%X364.

   USE terminal:(80:"BP"):"%X364"
   SET %1=3,%2=4
   WRITE /CUP(%1,%2)

CLOSE Command

Releases ownership of the device, which is gained with an OPEN command.

Syntax

CLOSE device

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

Predefined Mnemonic Spaces for Terminals

InterSystems IRIS provides two predefined mnemonic spaces for use with terminals:

  • ^%X364 for ANSI X3.64 terminals

  • ^%XDTM for DTM PC Console

If you make one of these mnemonic spaces active, you can use the control mnemonics associated with them in WRITE /mnemonic commands. You can also create your own mnemonic spaces. See Controlling Devices with Mnemonic Spaces for more information on mnemonic spaces.

The following sections describe the control mnemonics for these mnemonic spaces.

Mnemonic Space for X3.64

InterSystems IRIS provides a built-in mnemonic space for the ANSI X3.64 definition. This mnemonic space is the InterSystems IRIS routine %X364 in the manager’s namespace. To use routine %X364, either:

  • Have your InterSystems IRIS system manager enter %X364 as the default mnemonic space in the IO Settings configuration setting. From the Management Portal, select System Administration, Configuration, Device Settings, IO Settings.

  • Issue an OPEN command specifying this mnemonic space:

     OPEN "terminal"::"^%X364"

The following table lists the mnemonics.

Control Mnemonics for %X364 Mnemonic Space
Calling Sequence Name System Variable Affected
APC Application Program Command
BEL Ring the bell
CBT(%1) Cursor Backward Tabulation $X
CCH Cancel Character
CHA(%1) Cursor Horizontal Absolute $X
CHT(%1) Cursor Horizontal Tabulation $X
CNL(%1) Cursor Next Line $X,$Y
CPL(%1) Cursor Preceding Line $X,$Y
CPR Cursor Position Report
CTC(%1,%2,%3,%4, %5,%6,%7,%8,%9) Cursor Tabulation Control
CUB(%1) Cursor Backward $X
CUD(%1) Cursor Down $Y
CUF(%1) Cursor Forward $X
CUP(%1,%2) Cursor Position $X, $Y
CUU(%1) Cursor Up $Y
CVT(%1) Cursor Vertical Tabulation $Y
DA Device Attributes
DAQ(%1,%2,%3,%4, %5,%6,%7,%8,%9) Define Area Qualification
DCH(%1) Delete Characters
DCS Device Control String
DL(%1) Delete Lines
DMI Disable Manual Input
DSR(%1) Device Status Report
EA(%1) Erase in Area
ECH(%1) Erase Characters
ED(%1) Erase in Display
EF(%1) Erase in Field
EL(%1) Erase in Line
EMI Enable Manual Input
EPA End of Protected Area
ESA End of Selected Area
FNT Font Selection
GSM Graphic Size Modification
GSS Graphic Size Selection
HPA(%1) Horizontal Position Attribute $X
HPR(%1) Horizontal Position Relative $X
HTJ Horizontal Tab with Justify $X
HTS Horizontal Tab Set $X
HVP(%1,%2) Horizontal and vertical position $X, $Y
ICH(%1) Insert Characters
IL(%1) Insert Lines
IND Index $Y
INT Interrupt
JFY Justify
MC Media Copy
MW Message Waiting
NEL Next Line $X, $Y
NP(%1) Next Page
OSC Operating System Command
PLD Partial Line Down $Y
PLU Partial Line Up $Y
PM Privacy Message
PP(%1) Preceding Page
PU1 Private Use 1
PU2 Private Use 2
QUAD QUAD
REP(%1) REPEAT $X, $Y
RI Reverse Index $Y
RIS Reset to Initial State $X=0 $Y=0
RM(%1,%2,%3,%4,% 5,%6,%7,%8,%9) Reset Mode
SEM Select Editing Extent Mode
SGR(%1,%2,%3,%4, %5,%6,%7,%8,%9) Select Graphic Rendition
SL Scroll Left
SM(%1,%2,%3,%4,% 5,%6,%7,%8,%9) Set Mode
SPA Start of Protected Area
SPI Spacing Increment
SR Scroll Right
SS2 Single Shift Two
SS3 Single Shift Three
SSA Start of Selected Area
ST String Terminator
STS Set Transmit State
SU Scroll Up
TBC Tabulation Clear
TSS Thin Space Specification
VPA(%1) Vertical Position Attribute $Y
VPR(%1) Vertical Position Relative $Y
VTS Vertical Tab Set

Mnemonic Space for DTM PC Console

InterSystems IRIS provides the InterSystems IRIS routine %XDTM to match the mnemonics used in developing applications for DTM. This mnemonic space is available but is not set up as the default mnemonic space for terminals. If you port applications created for DTM to InterSystems IRIS, you can either:

  • Configure ^%XDTM as the default mnemonic space for terminals (MnemonicTerminal) in the Management Portal, or

  • Reference the ^%XDTM mnemonic space in the OPEN or USE command.

DTM Examples

UNIX®

  OPEN "/dev/tty04/"::"^%XDTM"

Windows

  OPEN "c:\sys\user"::"^%XDTM"

Then InterSystems IRIS can correctly interpret the DTM control mnemonics in WRITE /mnemonic commands, shown in the following table.

Control Mnemonics for DTM PC Console
Mnemonic Description
AA Normal mode
AB Bold mode
AC Underlined mode
AD Bold, underlined mode
AE Reverse video
AF Reverse video/Bold mode
AG Reverse video/Underline mode
AH Reverse video/Bold, underlined mode
AI Blink mode
AJ Bold, blink mode
AK Underlined, blink mode
AL Bold, underlined, blink mode
AM Reverse video / Bold, blink mode
AN Reverse video / Bold, blink mode
AO Reverse video / Underlined, blink modes
AP Reverse video / Bold, underlined, blink modes
AZ Mode Z
B(%1,%2) Set video attributes: %1 provides attribute for characters, %2 provides attribute for clearing frames
BOX Draw a window-relative utility box
C(%1,%2) Position cursor at column %1, line %2
CLR Clear current frame
COLOR(%1,%2) Set IBM PC Color: Foreground %1, Background %2
DC(%1) Delete %1 characters
EC(%1) Erase %1 characters
EF Erase to end of frame
EL Erase to end of line
F(%1,%2,%3, %4,%5) Fill rectangular area with $CHAR(%1) at upper left corner, %4 columns wide by %5 lines high
GETCUR Return terminal cursor position
HF Screen half bright off
HIDECURSOR Hide mouse cursor
HN Screen half bright
IC(%1) Insert %1 characters
LF Disable literal mode
LN Enable literal mode, which displays control characters graphically on a PC screen.
MARK(%1) Make mark on screen
NORM Enable normal display attributes
PAD(%1) Write %1 NULLS for padding
PF Pause off
PN Pause on
RF Screen reverse video off
RN Screen reverse video
SD(%1,%2,%3) Scroll current frame down by %3 lines
SHOWCURSOR Show mouse cursor
SU(%1,%2,%3) Scroll current frame up by %3 lines, starting at line %1 down to but not including line %2
VF Visible cursor off
VN Visible cursor on
WBOX Draw a screen-relative utility box
WCLOSE Close utility window
WINDOW Set scrolling window
WOPEN Open utility window
Y(%1) Set binary frame attribute

PRINT and ZPRINT Commands

Writes one or more lines of the currently loaded InterSystems IRIS routine to the current device.

ZPRINT has the same effect and arguments as PRINT.

Syntax

PRINT 
ZPRINT 
PRINT x 
ZPRINT x 
PRINT x:y 
ZPRINT x:y

where

Argument Definition
(none) The PRINT or ZPRINT command with no arguments prints the entire routine.
x,y The variables x and y indicate the range of lines to print. They can be either a line reference of the form TAG+OFFSET, or a line number of the form +7. Referring to a line not in the routine implies the empty line following the routine’s last line. x = First or only line to print. y = Last line to print.

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

Example

This example prints the first line of the current routine, four lines starting at INIT, and all the lines from FINI to the end:

INIT
  SET a=1
  SET b=2
  SET c=3
  SET d=4
FINI
  SET x=24
  SET y=25
  SET z=26
  PRINT +1,INIT:INIT+3,FINI:+9999

Programming Your Terminal

Using InterSystems IRIS to Program Formatted CRT Screens

Several features of Terminal I/O aid in programming formatted screens:

  • Use WRITE * to send control sequences easily.

  • Use READ to receive escape-sequence responses.

  • Use SET $X = expression and SET $Y = expression to update the current cursor position.

Fixed-length READ and programmer-specified termination characters make it convenient to read individual fields. You can use the Secret protocol to make passwords invisible.

Remember that WRITE * does not change $X or $Y. If you want to change them, use WRITE $C(X), or simply set them explicitly.

Example

This example sets the VT100 cursor to line 10, column 20

%SYS>SET DY=10,DX=20
%SYS>WRITE *27,*91,DY+1,*59,DX+1,*72 SET $Y=DY,$X=DX

Use CURRENT^%IS to Set Variables

The utility routine CURRENT^%IS sets some useful local variables to work for the current device. To call this routine, enter:

%SYS>DO CURRENT^%IS

This command sets the variables indicated in the following table.

Features Enabled By CURRENT^%IS
Code Definition
W @FF Clears the screen and moves the cursor to the upper left corner (column 0, line 0) leaving $X=0, $Y=0.
S DX=42,DY=10 X XY Moves the cursor directly to column 42, line 10, leaving $X=42, $Y=10.

Programming Escape Sequences

The ANSI standard for escape sequences makes programming of smart terminals practical. The Escape character and all characters after it in a string do not display on the screen, but do update $X and $Y. Send escape sequences to the terminal with WRITE * statements and keep $X and $Y up to date by setting them directly.

The ANSI standard establishes a standard syntax for escape sequences. The effect of a particular escape sequence depends on the type of terminal you are using.

Look for incoming escape sequences in $ZB after each READ. InterSystems IRIS puts ANSI-standard escape sequences and any others that use the ANSI forms in $ZB. InterSystems IRIS recognizes two forms of escape sequence:

Regular form

  • An ESC.

  • Optionally the character “O” (the letter), decimal value 79.

  • Zero or more characters with decimal values 32–47.

  • One character with decimal value 48–126.

Control form

  • The ESC character, decimal value 27.

  • The “[” character, decimal value 91.

  • Zero or more characters with decimal values 48–63.

  • Zero or more characters with decimal values 32–47.

  • One character with decimal value 64–126.

Furthermore, the sequence can be no longer than 16 characters. Escape sequences that violate these forms or rules set bit 8 of $ZA, whose value is 256.

Example

Assume that you are programming a terminal whose Help key sends the two-character sequence Escape-? (? has a decimal value of 63)

%SYS>SET HELP=$C(27,63)
ASK READ !,"Enter ID: ",X I $ZB=HELP Do GIVEHELP GoTo ASK

Your routine can detect nonstandard escape sequences as follows:

  1. Make ESC a terminator.

  2. When ESC appears in $ZB:

    1. Disable echo with the Secret protocol to prevent modification of $X/$Y.

    2. Read the rest of the sequence with READ *;

    3. Turn off Secret to re-enable echo.

      In the following figure, the user is asked to enter an ID. If the user presses Esc-?, a Help screen appears. The subroutine ESCSEQ assumes that nonstandard escape sequences end with an asterisk “*”.

DEMOS 
  SET HELP=$C(27,63) ;Get Help with <ESC>?
    SET ESC=$C(27) USE 0:("":"":ESC) ; Make <ESC> a READ terminator
                                     ; character
ASK READ !,"Enter ID: ",X I $ZB=ESC Do ESCSEQ G:SEQ=HELP ASK 
    . ;Input ID. Handle Help request. 
    .
    Quit
HELPSCR  ;Process Help request 
    . 
    Quit
ESCSEQ  USE 0:("":"S") SET SEQ=ESC ;Set terminal to no echo,init SEQ 
    FOR I=1:1 {
      READ *Y 
      SET SEQ=SEQ_$C(Y)
      QUIT:Y=42 }
    ; Read in Escape sequence, 
    ; end at "*" 
    USE 0:("":"":ESC) Quit ;Redefine terminator

InterSystems IRIS Supports Full or Half Duplex and Echo

InterSystems IRIS prefers that you use full duplex terminals; in other words, your keyboard should operate independently from your printer or screen.

Full duplex means simultaneous and independent transmission in both directions. Half duplex means transmission in only one direction at a time. Duplex has nothing to do with echo, although you may see a terminal marked full duplex for remote echo and half duplex for local echo. This designation means that the terminal displays the characters you type and does not expect InterSystems IRIS to echo them.

Set your terminal to local echo off or full duplex, letting InterSystems IRIS provide the echo. The echo comes not when the computer receives the character, but when the READ command takes it from the input buffer; therefore, the prompts and answers of a dialog keep their intended positions on the screen regardless of whether the user types ahead.

Some public networks provide their own echo to the terminal.

On Windows systems, consoles do not permit local echo setup changes. For terminals attached via a terminal emulator (e.g., VT220), refer to your terminal emulator documentation for instructions to disable local echo.

On UNIX® systems, use the stty command to avoid double echoes while keeping $X and $Y in agreement with the cursor’s position.

InterSystems IRIS Supports Intercomputer Links and Special Devices

InterSystems IRIS provides flexible protocols and large independent buffers enable routines to deal with unusual devices and their protocols. For example, InterSystems IRIS easily supports full duplex communication between two computers on a terminal-to-terminal link. Two InterSystems IRIS systems require only a physical connection, the right protocols, and identical settings of speed, parity, and character length. With the aid of external converters, InterSystems IRIS communicates with IBM ports as a synchronous EBCDIC terminal.

Keep these points in mind when designing an intercomputer link:

  • Turn off echo at both ends by including the S protocol in OPEN or USE, or by using the operating system’s terminal parameters.

  • Unless your communication protocol supports XON/XOFF flow control (Ctrl-Q and Ctrl-S), be sure it limits unacknowledged transmissions to the limit of the operating system’s input buffering; otherwise you may lose data.

  • In image mode, InterSystems IRIS does not support XON/XOFF. In nonimage (normal) mode, the operating system’s terminal parameters determine whether the computer issues an XOFF if the operating system’s input buffer is almost full. If XOFF and XON are not supported, make the buffer large enough that you do not need them.

  • Test $ZA after read operations to detect transmission errors such as parity or data overrun conditions.

FeedbackOpens in a new tab