Terminal I/O

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.

$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

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.

$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:

• Your operating system, which sets the default behavior.

• Whether /NOXY (which disables $X and $Y processing) was specified in the OPEN or USE command.

• You can set how $X handles escape sequences for the current process using the DX()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the DXOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class.

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.

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

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 the Error Processing chapter of Using ObjectScript 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 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.

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=don't disconnect the port.
2	Modem Control	1=use modem control. 0=don't 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 (don't disconnect the port); 0 (don't 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.

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.

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.

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.

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 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:

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:

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.

Syntax

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

where

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)

Syntax

CLOSE device

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

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.

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

Syntax

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

where

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

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:

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.