Escape Sequences

An escape sequence is a series of characters that performs a control function on the terminal, such as moving the cursor forward or backward or erasing part of the screen. The first character of an escape sequence is an ESC. The ESC character is a prefix that causes the terminal to treat subsequent characters as a command instead of echoing them on the screen.

One common use of escape sequences is cursor control. Cursor control is a feature of many video terminals, including the VT100-, VT200-, and VT300-family terminals. As its name suggests, cursor control allows a program to manipulate the screen cursor. Cursor control is often used with the RSTS/E echo control feature in data entry applications.

This section:

o Summarizes commonly-used escape sequences for the VT100-, VT200-, and VT300-family terminals.

o Shows how to use ANSI-compatible escape sequences to control the cursor and use two graphics features: reverse video and double-height characters. (The example is intended to show the technique, not to be a practical application.)

o Explains how the system handles input and output escape sequences for all types of terminals.

_________________________________________________________________

VT100-, VT200-, and VT300-Family Escape Sequences

VT100-, VT200- and VT300-family terminals can operate in either VT52-compatible mode or ANSI-compatible mode. Each mode has a different set of escape sequences.

_________________________________________________________________

VT52-Compatible Mode

In VT52-compatible mode, the VT100-, VT200- and VT300-family terminal responds to escape sequences like a VT52 terminal. VT52-compatible escape sequences let you execute programs on the VT100-, VT200- and VT300-family terminals that are written for the VT52 terminal. However, they do not let you take advantage of advanced features, such as reverse video. In addition, VT52-compatible escape sequences are not ANSI-standard.

If you write programs for the VT52 as well as the VT100-, VT200- and VT300-family terminals, or if you are converting from the VT52 to a more advanced terminal, be aware of differences between the terminals. For example:

o The \"home\" cursor position differs among the VT100-, VT200- and VT300-family terminals and the VT52. Home, which is the top left corner of the screen, is:

_ (1,1) for the VT100-, VT200- and VT300-family terminals in ANSI-compatible mode

_ (32,32) for the VT52 and the VT100-, VT200- and VT300- family in VT52-compatible mode

o When you use cursor control functions on the VT52 or the VT100-, VT200- and VT300-family terminal in VT52-compatible mode, you must output the line and column
positions as one-byte ASCII values. (You can use the CHR$ function to perform the necessary conversion.)

On the other hand, when you use cursor control functions on the VT100-, VT200- and VT300-family terminals in ANSI-compatible mode, you output line and column positions as string data. No conversion is necessary.

See the appropriate hardware manuals for a complete discussion of terminal hardware and software.

_________________________________________________________________
ANSI-Compatible Mode

Table 4-4 summarizes the VT100-, VT200- and VT300-family ANSI-compatible escape sequences that move the cursor, erase all or part of the screen, and control line size and character attributes (bold, underscore, blink, and reverse video). Table 4-4 uses the symbols Pl, Pc, and Pn:

Pl means line number.

Pc means column number.

Pn is a decimal parameter expressed as a string of ASCII digits. The parameter\'s meaning for each escape sequence is explained in Table 4-4. Separate multiple parameters with a semicolon (;). If you omit a parameter or specify 0, the terminal uses the default parameter value for that escape sequence.

Be sure to include the left square bracket ([) in the escape sequence prefix where Table 4-4 indicates. Note that escape sequences cannot contain embedded spaces. See the VT100 User Guide for a complete description of VT100 escape sequences. See the VT220 User Guide, VT240 User Guide, or VT241 User Guide, for a complete description of VT200-family escape sequences. See the VT330/VT340 Programmer Reference Manual, Part I and Part II, for a complete description of VT300-family escape sequences.

Table 4-4: ANSI-Compatible Escape Sequences: VT100-, VT200- and VT300-Family Terminals
________________________________________________________________
Escape
Sequence Description
________________________________________________________________
Cursor Movement
________________________________________________________________

ESC[PnA Moves the cursor up n lines without affecting the column position. The parameter Pn specifies the number of lines. The default value is one line.

ESC[PnB Moves the cursor down n lines without affecting the column position. The parameter Pn specifies the number of lines. The default value is one line.

ESC[PnC Moves the cursor forward (right) n columns without affecting the line position. The parameter Pn specifies the number of columns. The default value is one column.

ESC[PnD Moves the cursor backward (left) n columns without affecting the line position. The parameter Pn specifies the number of columns. The default value is one column.

ESC[Pl;PcH Direct cursor address. Moves the cursor to the specified line and column position. If you do not specify a line or column position, the cursor moves to the home position, which is the top left corner of the screen.

ESCD Index. Moves the cursor to the current column position on the next line.

ESCM Reverse index. Moves the cursor to the current column position on the preceding line.

ESCE Moves the cursor to the first column position on the next line.

________________________________________________________________
Erasing
________________________________________________________________

ESC[K or Erases from the current cursor position to the
ESC[0K end of the line.

ESC[1K Erases from the beginning of the current line to the cursor.

ESC[2K Erases the entire line containing the cursor.

ESC[J or Erases from the current cursor position to the
ESC[0J end of the screen.

ESC[1J Erases from the beginning of the screen to the current cursor position.

ESC[2J Erases the entire screen.

ESC[PnM VT200- and VT300-family terminals only. Erases multiple lines below the cursor. As lines are deleted, the remaining lines move up. The parameter Pn specifies the number of lines.

ESC[PnP Erases multiple character to the right of the cursor. As characters are deleted, the remaining characters move to the left.

________________________________________________________________
Line Size (Double Height and Double Width)
________________________________________________________________

ESC#3 Changes the current line to the top half of a double-height, double-width line.

ESC#4 Changes the current line to the bottom half of a double-height, double-width line.

ESC#5 Changes the current line to a single-width, single-height line.

ESC#6 Changes the current line to a double-width, single-height line.

To display double-height characters, use the ESC#3 and ESC#4 sequences as a pair on adjacent lines and send the same characters
to both lines. The use of double-width characters reduces the number of characters on each line by half.

________________________________________________________________
Character Attributes (Require Advanced Video Option on VT100)
________________________________________________________________

ESC[Pn;Pn;Pn;...Turns bold, underscore, blink, and reverse video attributes ON and OFF. Pn can have the following values:

0 or All attributes OFF
none Bold ON
1 Underscore ON
4 Blink ON
5 Reverse video ON
7

For VT300-family terminals only:

8 Invisible

22 Bold OFF

24 Underline OFF

25 Blink OFF

27 Reverse video OFF

28 Invisible OFF

The terminal executes the parameters in order and ignores any other parameter values. Unlike line size commands, which affect only the current line, the character attributes affect the entire screen. Remember to turn them OFF before ending your program.

________________________________________________________________
Status Line Control (VT300-Family Only)
________________________________________________________________

ESC[Pn$} Controls the destination of data sent to the terminal.

Pn = 0-send data to screen

1-send data to status line only

ESC[Pn$- Controls type of status line.

Pn = 0-no status line

1-terminal indicator status line

2-host writable status line

_________________________________________________________________

Output Escape Sequences

When you send an escape sequence to a terminal, use the value CHR$(155%) for the escape character if the terminal is in normal output mode. Do not use CHR$(27%), which is the ASCII decimal code for the ESC character, unless you are using transparent control character mode. The system translates CHR$(27%) to CHR$(36%), the dollar sign ($) character. CHR$(155%), an ESC with the high order bit set, is a special value that prevents the system from translating the ESC character to a $ character. When you use CHR$(155%), it causes the real CHR$(27%) to be sent, allowing the terminal to in terpret the transmitted escape sequence. See the section, \"Transparent Control Character Output: RECORD 16384% and MODE 16384%\" for more information.

In processing output escape sequences, the system counts the escape characters along with the other characters to be output. This causes lines to wrap prematurely on video terminals. To avoid this line wrap, open the terminal in MODE 4% (suppress automatic CR/LF).

_________________________________________________________________

Input Escape Sequences

Under RSTS/E, terminals can operate in either escape sequence mode or no escape sequence mode. Digital recommends that you set escape sequence mode by using MODE 256% in the OPEN statement (see the section \"Escape Sequence Mode: MODE
256%\"). For compatibility with existing applications, you can set either mode with the Set Terminal Characteristics SYS call (SYS 16), or the SET TERMINAL command (see the RSTS/E System User\'s Guide). New applications should use MODE 256%.

When a terminal is in normal mode, the system recognizes an incoming ESC character, CHR$(27%), as a delimiter and echoes a CHR$(36%), the $ character. When a terminal is in escape sequence mode, however, the system does special processing of input escape sequences. This special processing is useful for applications such as reading input from keypad function keys.

NOTE

To cause a terminal to send escape sequences instead of numbers when keypad keys are pressed, you must send an escape sequence to the terminal. For the VT100 in ANSI-compatible mode, this escape sequence is \"ESC=\". See the appropriate hardware manual for details.

When a terminal is in escape sequence mode, the system processes input escape sequences so that:

o The characters in the escape sequence do not echo on the terminal.

o A BASIC-PLUS program can read and test escape sequences.

Input escape sequences are processed after Ctrl/S and Ctrl/Q (if the TTSYNC characteristic is set) but before private delimiters and all other characters. In brief, the system moves the ESC character from the beginning to the end of the escape sequence so that BASIC-PLUS can recognize the ESC character as a delimiter. The program receives the escape sequence as follows:

1.A CHR$(128%) value

2.The characters in the ESC sequence (minus the ESC character that started the sequence) without normal data conversions

3.A CHR$(155%) value, which signals the end of the escape sequence

Figure 4-1 shows an example of this conversion process.

Figure 4-1: Input Escape Sequence Processing
_____________________________________________________________
See the manual
_____________________________________________________________

Use GET statements to read incoming escape sequences, not INPUT or INPUT LINE statements. Unlike INPUT and INPUT LINE, GET does not strip the high order bit or discard nulls.

It is also a good idea to cancel type ahead right after you change a terminal\'s escape sequence characteristic or open a terminal in escape sequence mode (see SYS call 11, Cancel All Type Ahead). Canceling type ahead makes sure that the terminal\'s type ahead buffer does not contain a mixture of data processed in normal and escape sequence modes.

VT52 and VT100 ANSI-compatible escape sequences are defined so that matching keys on each terminal send escape sequences that end with the same character. Thus, you can use the same code to read incoming escape sequences from both terminals, regardless of whether the VT100s are in ANSI- or VT52-compatible mode.

For example, the up arrow key on a VT52 terminal (and a VT100 terminal in VT52-compatible mode) sends the sequence ESC+\"A\". Your program receives this sequence as CHR$(128%)+\"A\"+CHR$(155%). The up arrow key on a VT100 terminal in ANSI mode sends the sequence ESC+\"[A\"; your program receives this sequence as CHR$(128%)+\"[A\"+CHR$(155%). By checking for an \"A\", your program can recognize the up arrow key from both terminals. Incoming escape sequences for other keys follow the same pattern. When you use this technique:

o Use MODE 256% to set escape sequence mode instead of setting the terminal\'s escape sequence characteristic. The system handles escape sequences that end with P differently for each method. See the section \"Escape Sequence Mode: MODE 256%\" for more information.

o Remember that it works only for reading incoming escape sequences; on output, your program must distinguish between a VT100 and a VT52. See the section \"VT100-, VT200- and VT300-Family Escape Sequences\" for more information.

The rest of this section provides more detailed information on how the system processes escape sequences in escape sequence mode.

In escape sequence mode, an incoming ESC character CHR$(27%) sets a flag indicating that an escape sequence follows. The system does not echo the ESC character as a $ character and does not echo other characters in the sequence except for certain control characters. The terminal handles the characters in the escape sequence as follows:

1.The ASCII control characters (CHR$(0%) through CHR$(31%) and CHR$(127%)) are processed first. Except for DELETE CHR$(127%)) and Ctrl/U (CHR$(21%)), their functions do not change. The terminal discards DELETE and Ctrl/U and does not pass them to the user. The control character CHR$(27%) (escape) starts a new escape sequence.

Note that control characters in escape sequences violate the ANSI standard and should not be used.

2.Normal data conversion, such as translating lowercase letters to uppercase letters, is not done for characters inside an escape sequence.

3.The system resumes normal data conversions after it terminates the escape sequence.

Table 4-5 describes how the system terminates the escape sequence when it receives one of the escape sequence terminators.

Table 4-5: Escape Sequence Terminators
________________________________________________________________
Sequence Examples Comments
________________________________________________________________

Y<2 characters> Y<LINE#><COL#THE VT52 terminal uses this escape sequence for direct cursor addressing.

O OP The modifier can be any ? ?M character except a control character. VT52 and VT100 terminals transmit escape sequences of this type when the terminal is in keypad application mode and a keypad key is pressed.

P - The modifier can be any character except a control character. The system recognizes this sequence as an escape sequence terminator when you set the terminal\'s ESC SEQUENCE characteristic but not when you open the terminal with MODE 256%. See the section Escape Sequence Mode: MODE 256%.[1]

P P The system recognizes P as OP an escape sequence terminator when you open the terminal with MODE 256% but not when you set the terminal\'s ESC SEQUENCE characteristic. See the section Escape Sequence Mode:

MODE 256%.[1]

[<TERMINA[5A The filler characters must [10;15H be in the range CHR$(32%) through CHR$(63%). The terminator character must
be in the range CHR$(64%) through CHR$(128%). These are ANSI-compatible escape sequences.

<TERMINAT#4 The filler characters must be in the range CHR$(32%) Q through CHR$(47%). The terminator character must be in the range CHR$(48%) through CHR$(126%). These are ANSI-compatible escape sequences. Some VT52 escape sequences, such
as Q (red key), are also recognized by this rule.

[1]As an alternative to MODE 256%, an optional patch is available that causes the system to recognize \"P\" as an escape sequence terminator. Unlike MODE 256%, this patch affects all terminals on the system. See the RSTS/E Maintenance Notebook for details.

_________________________________________________________________

The system starts another escape sequence whenever it receives another ESC character. If the ESC character precedes or is embedded in one of the character sequences in Table 4-5, the system does not append the CHR$(155%) value to the escape sequence it was processing before it starts processing the next one.