vt102(7) vt102(7)NAME vt102 - provides protocols for VT102 terminals DESCRIPTION The primary use for a conventional terminal is to allow users to enter text data and to provide display feedback so that users can see and correct typing errors. This feedback is facilitated by a cursor, a special display symbol that can appear superimposed over another character as necessary. The cursor shows the user where the next character typed will appear. These data entry actions also require the support of software running on the host computer. The host software communicates frequently with the terminal. For example, it can send an acknowledgment that it has received each character that is typed. Occasionally it sends its own messages for the terminal to display, such as the password: prompt. Data sent to a VT102 terminal device is handled in a consistent fashion as ensured by VT102 conventions as well as the ANSI and ISO standards with which the VT102 protocols conform. These conventions specify display character sets and special setup sequences, and specify the way keys are mapped to displayable or nondisplayable characters, or character sequences. The VT102 protocols described in this manual page are used both by VT102 terminals and by Macintosh computers running software that emulates a VT102 device. For example, a Macintosh emulates a VT102 device when A/UX is running and CommandShell is the active application, or when the active application is MacTerminal. Each time a nondisplayable character is received, the VT102 device (or Macintosh emulating such a device) must take an appropriate action, such as deleting a character upon receipt of the delete control code. If an escape control code is received, the terminal must gather subsequent characters to determine which control sequence, as defined by protocols, is being transmitted. It then performs the action specified by that control sequence. (The escape sequences defined by the VT102 protocols are described later in the ``Description'' section.) When included in escape sequences, characters that are normally displayed are interpreted as elements of a nondisplayable sequence. A simple protocol applies for handling displayable characters that the terminal receives from the host. A character is inserted at the current cursor position; then the cursor is advanced to the next available character January 1992 1
vt102(7) vt102(7)column. This protocol is repeated with each displayable character that is received from the host computer. Each time a key is pressed, the terminal could process the character locally before sending the code to the host software for processing. Such a protocol is established by a setting known as local echo. Because it allows the host software more control over terminal behavior, a full duplexrsetting is preferred to local echo for UNIX programs. Fordetails on these protocol mechanisms, refer to a reference book describing VT102 conventions. A table of all the standard single-character codes that can be transmitted or received can be found in the ascii(5) manual page. This set of codes is called the ASCII American Standard Code for Information Interchange character set. The ASCII set of codes includes all 33 nondisplayable (control) character codes, as well as 95 displayable character codes. For VT102 devices, the 95 displayable character codes can be mapped to any one of five sets of displayable characters. The 95 display characters shown within ascii(5) are the VT102 standard designated as the United States character set. Certain control codes, such as a newline and tab, are used so often that dedicated keys are assigned to generate them. The User Perspective From the perspective of a user, the keys used to generate displayable characters and the control codes are most important. On most keyboards, the keys that are dedicated to the generation of specific control codes are easily recognized by their names: ⊕ ESCAPE ⊕ TAB ⊕ DELETE ⊕ RETURN or ENTER The 29 remaining control codes are generated by two-key combinations that include the CONTROL key. Note that there are ways of using key combinations to generate the control codes that have been assigned to the dedicated keys. For example, you can generate a tab control code by pressing CONTROL-I. Next in importance from a user perspective are the cursor- motion keys, numeric-keypad keys, and function keys (if included on the keyboard). These keys generate escape 2 January 1992
vt102(7) vt102(7)sequences that may be supported by host software applications. An escape sequence begins with an escape control code followed by a prescribed sequence of characters. Note that most UNIX applications, including command shells and the vi full-screen editor, do not support the cursor- motion or function keys. See vi(1) for a description of the cursor-motion keys you can use from vi command mode. Next in importance from a user perspective are the key combinations that generate control codes. They are generated by holding down the CONTROL key while pressing another key. For example, key combinations enable all users to perform these tasks: ⊕ Abort a currently running command, by pressing CONTROL-C before the shell offers a new command prompt. ⊕ Freeze a sequence of text lines that are scrolling, by pressing CONTROL-S. ⊕ Restart the scrolling of display lines after it was temporarily stopped, by pressing CONTROL-Q. ⊕ Indicate the end of a data stream when a UNIX program is reading multiple-line input directly from the terminal, by pressing CONTROL-D. ⊕ Generate a backspace control code, by pressing CONTROL-H. (This should not normally be a ``destructive'' backspace as is generated by the DELETE key.) While most of these actions are defined by the VT102 conventions, some are supported conventions of the UNIX utility programs. In the latter cases, the specified action is supported only when UNIX programs are processing the data communications from the terminal. Certain escape sequences can also be used by the terminal operator as a means to configure terminal settings. However, for users of CommandShell, the graphic Macintosh buttons and dialog boxes (described in CommandShell(1)) provide a much easier way to set these configuration parameters. Terminal settings are set independently for each CommandShell window because there is a separate terminal emulation taking place for each open CommandShell window. For each window, CommandShell uses the settings specified in the Preferences dialog box, which can be saved when the window is closed. If no settings have been saved for a January 1992 3
vt102(7) vt102(7)window, CommandShell uses its default VT102 terminal settings. For further details, see CommandShell(1). The ability to choose one of the five sets of displayable characters may be of interest to the normal user. (These character sets are described later in the ``Description'' section.) If the software application that is processing the data communications from your terminal (or CommandShell window) is a UNIX shell, its current settings can affect the interpretation of most key characters and control codes. See stty(1), sh(1), csh(1), and ksh(1). The Advanced User Perspective From the perspective of an advanced user of A/UX, a number of additional features supported by the VT102 protocols may be of interest. Most of these features are enabled by escape sequences, some of which are described in greater detail later in the ``Description'' section. Although they are not a VT102 standard, the Sun Tools escape sequences might be of interest also, since they allow access to certain CommandShell functions (primarily windowing functions) from the command line, or from shell scripts, as described in CommandShell(1). The more advanced VT102 features that a sophisticated user may want to use include ⊕ generating a system beep. ⊕ generating the cursor-motion sequences that will relocate the cursor to a particular screen location. ⊕ switching between block and underline cursors as a way to indicate that a specialized program or task is being run, or to suit one's own cursor preference. ⊕ switching to smooth line scrolling as a way to reduce eye fatigue for applications that are meant to scroll data for extended periods of time, or to suit one's own scrolling preference. ⊕ switching to 132-column mode for applications that display many columns of data. ⊕ switching to no-line-wrapping mode for applications that display many columns of data. ⊕ enabling keyboard keys to repeatedly enter characters if the key is held down continuously, or disabling this 4 January 1992
vt102(7) vt102(7)feature. ⊕ enabling the number and operator (plus, minus, and so forth) keys located in the numeric keypad to produce the same character codes as the corresponding keys located at the q-w-e-r-t-y positions. ⊕ enabling the numeric-keypad keys to generate escape sequences so that those keys can initiate application- specific functions, whenever a particular host application is running that supports them. The Programmer Perspective From the programmer's perspective, the VT102 protocols can be used to ⊕ generate a system beep, using a (CONTROL-G) control code, in order to call the user's attention to an obvious error or to the fact that a waiting period has elapsed. ⊕ override the operator's settings for various configuration parameters in order to help present custom on-screen forms with a consistent interface. ⊕ send an escape sequence to reset the terminal to the user's preferred configuration parameters. ⊕ use the clear-to-end-of-line or end-of-screen feature for applications that would otherwise leave the display in a messy state. ⊕ take advantage of the character attribute modes that can be established for characters subsequently sent, such as underline, blink, bold (high intensity), and reverse video. Character Sets The VT102 protocol supports the United States and the United Kingdom character sets, which are identical except that the number or pound symbol (#) in the U.S. character set is replaced by the Brittish pound sign. The VT102 protocol also supports two unspecified character sets: ⊕ alternate ROM ⊕ alternate ROM special The fifth character set supported by the VT102 protocol is the Special Characters and Line-Drawing Character Set. It differs from the United States character set in that it replaces the lowercase alphabetic characters (and several others) with symbol characters. Here is a summary of the January 1992 5
vt102(7) vt102(7)differences between the Special Characters and Line-Drawing Characters set and the U.S. character set. R S Replaced by a blank character. ` Replaced by a diamond symbol. a Replaced by a checkerboard symbol. For line-monitoring purposes, this symbol is used as an error indicator. b through e Replaced with a set of symbols used mostly for line- monitoring purposes. Normally control characters have no display symbol associated with them. The characters b through i are remapped to symbols for the following control characters: tab, form feed, carriage return, and line feed. f Replaced with a degree symbol. g Replaced with a plus/minus symbol (+). h and i Replaced with two more symbols used for line-monitoring purposes. The character h is replaced with a newline symbol and the character i is replaced with a vertical tab symbol. j through x Replaced with a set of symbols used for line-drawing purposes. The characters j ank k are the lower- and upper-right corner marks, and l and m are the lower- and upper-left corner marks. The character n is a ``crossing-lines'' symbol. The characters o through s are horizontal lines starting at the top, next-to-top, midline, next-to-bottom, and bottom positions within a line. The characters t and u are left and right `T' joints. The characters v and w are bottom and top `T' joints. The character x is replaced by a vertical line. y Replaced with the less-than-or-equal-to symbol. z Replaced with the greater-than-or-equal-to symbol. { Replaced with the pi symbol. | Replaced with the not-equal symbol. } Replaced with the United Kingdom pound sign. Replaced with a small bullet (⊕) .~6 January 1992
vt102(7) vt102(7)Escape Sequences Associated With Cursor-Motion Keys Certain keys do not have dedicated ASCII codes associated with them, so by convention each generate a code sequence that starts with the escape control code. These are the escape sequences that the cursor-motion keys produce while in the mode called Cursor Key Mode Reset: Up Arrow key esc [A Down Arrow key esc [B Right Arrow key esc [C Left Arrow key esc [D These are the escape sequences that the cursor-motion keys produce while in the mode called Cursor Key Mode Set: Up Arrow key esc OA Down Arrow key esc OB Right Arrow key esc OC Left Arrow key esc OD Escape Sequences Associated With Numeric Keypad While the numeric keys do have dedicated ASCII codes associated with them, the VT102 terminal can also be set to a mode known as Application Keypad Mode, in which each numeric key generates a code sequence that starts with the escape control code. These are the escape sequences the numeric keypad keys when in this mode. (The codes associated with PF1 through PF4 do not change from mode to mode.) 0 esc Op 1 esc Oq 2 esc Or 3 esc Os January 1992 7
vt102(7) vt102(7)4 esc Ot 5 esc Ou 6 esc Ov 7 esc Ow 8 esc Ox 9 esc Oy - esc Om , esc Ol . esc On ENTER esc OM (When Application Keypad Mode is not active, this key generates the same ASCII control code as does RETURN.) PF1 esc OP or CLEAR (in Application Keypad mode) PF2 esc OQ (in Application Keypad mode) = (in Numeric Keypad mode) PF3 esc OR (in Application Keypad mode) / (in Numeric Keypad mode) PF4 esc OS (in Application Keypad mode) * (in Numeric Keypad mode) CLEAR does the same as the ``Redraw Screen'' item in the Commands Menu when in the Numeric Keypad mode. Escape Sequences Used to Select Character As described earlier in the ``Description'' section, five character sets can be associated with the 95 displayable ASCII characters. The VT102 terminal allows two of these character sets to be active at any one time. A single control code, known as Shift-in (described in ``si'' in ascii(5)), causes the secondary character set to be switched on. Another control code, known as Shift-out (described in ``so'' in ascii(5)), causes the secondary character set to be switched off, reactivating the primary character set. These escape sequences allow you to select the primary and secondary character sets (or active character sets): 8 January 1992
vt102(7) vt102(7)esc (A Specifies the United Kingdom character set as the primary set. esc (B Specifies the United States character set as the primary set. esc (0 Specifies the Special Characters and Line-Drawing character set as the primary set. esc (1 Specifies the Alternate ROM character set as the primary set. esc (2 Specifies the Alternate ROM special character set as the primary set. esc )A Specifies the United Kingdom character set as the secondary set. esc )B Specifies the United States character set as the secondary set. esc )0 Specifies the Special Characters and Line-Drawing character set as the secondary set. esc )1 Specifies the alternate ROM character set as the secondary set. esc )2 Specifies the alternate ROM special character set as the secondary set. To permit rapid switches between character sets, the following escape sequences select the secondary (also called G2 default) character set and tertiary character set (also called G3 default) for only one character before switching back to the primary character set: esc N Specifies the secondary (G2 default) character set to be used for the next character received. esc O Specifies the tertiary (G3 default) character set to be January 1992 9
vt102(7) vt102(7)used for the next character received. Escape Sequences for Terminal Control In the following notations describing escape sequences, replace the placeholder esc with the escape control code. Other placeholders should be replaced with numbers specified as one or more octal digits. esc [?4h Specifies smooth scroll. esc [?4l Specifies jump scroll. esc [ first-line-to-scroll;last-line-to-scrollr Causes one portion of the screen to become a scrolling region in terms of the top and bottom margins specified. esc [?6h Causes the home cursor position to become the upper- left character of the scrolling region that has been established. (See the preceding escape sequence.) esc [?6l Causes the home cursor position to be set to the upper-left corner of the screen (the default home position). esc [ number-of-lines-upA Specifies cursor movement up the specified number of lines from its current location. esc [ number-of-lines-downB Specifies cursor movement down the specified number of lines from its current location. esc [ number-of-columns-forwardC Specifies cursor movement forward the specified number of columns from its current location. esc [ number-of-columns-backwardD Specifies cursor movement backward the specified number of columns from its current location. esc [ line;columnH Specifies cursor movement to the location specified. esc [H Specifies cursor movement to the home location. (See also the preceding escape sequences that can reset the home position.) 10 January 1992
vt102(7) vt102(7)esc [ line;columnf Specifies cursor movement to the location specified. esc [f Specifies cursor movement to the home location established by origin mode. (See also the relevant escape sequences that follow.) esc D Specifies cursor movement down one line, causing scrolling if necessary. esc M Specifies cursor movement up one line, causing scrolling if necessary. esc E Specifies cursor movement to the beginning of the next line, causing scrolling if necessary. esc 7 Saves cursor position, character attribute, character set, and origin mode for later restoration. (See the next escape sequence.) esc 8 Restores the previously saved cursor position, character attribute, character set, and origin mode for later restoration. (See the previous escape sequence.) esc [?3h Specifies 132 columns per line. esc [?3l Specifies 80 columns per line. esc [?7h Specifies automatic line wrap. Any display characters received when the cursor is at the end of a line appear on the following line, causing scrolling if necessary. esc [?7h Removes automatic line wrap. Any display characters received when the cursor is at the end of a line overwrite the character at the last column position of the line. esc [?5h Specifies a white screen background with black characters. esc [?5h January 1992 11
vt102(7) vt102(7)Specifies a black screen background with white characters. esc [20h Specifies a mode where the cursor is advanced to the beginning of the next line when form feed, line feed, or vertical tab control characters are received. The RETURN key causes both a carriage return and a line feed control character to be transmitted. esc [20h Specifies a mode where the cursor is advanced to the next line at the same column position when form feed, line feed, or vertical tab control characters are received. The RETURN key causes the transmission of a carriage-return control code only. esc [2h Causes the keyboard to be turned off. esc [2l Causes the keyboard to be turned on. esc [?8h Establishes the automatically repeating mode for all keyboard keys. If the key is pressed for more than one-half second, the character is generated repeatedly. esc [?8h Removes the automatically repeating mode for all keyboard keys. esc [12h Establishes full duplex mode. The terminal transmits characters to the host computer, which must send them back before they are displayed on the screen. esc [12l Establishes local echo mode. Displayable characters are displayed at the same time that they are sent to the host computer. esc [?1h Establishes a mode of operation (Cursor Key Mode Reset) in which the cursor-motion keys generate escape codes that start with ESCAPE O. esc [?1l Establishes a mode of operation (Cursor Key Mode Set) in which the cursor-motion keys generate escape codes that start with ESCAPE [. 12 January 1992
vt102(7) vt102(7)esc = Establishes a mode of operation (Application Keypad Mode) in which the numeric keypad keys generate escape codes that start with ESCAPE O. esc > Establishes a mode of operation (Numeric Keypad Mode) in which the numeric-keypad keys generate the same ASCII codes as the corresponding keys located in the q-w-e-r-t-y layout and that produce single ASCII codes. esc [m esc [0m Switch off any character attributes that might be in effect (see escape sequences that follow), such as blink, bold, underline, and reverse video. esc [1m Switches on the bold character attribute for all subsequently received characters. esc [4m Switches on the underline character attribute for all subsequently received characters. esc [5m Switches on the blinking character attribute for all subsequently received characters. esc [7m Switches on the reverse video character attribute for all subsequently received characters. esc H Establishes a horizontal tab at the current cursor position. esc [g esc [0g Remove (clear) a horizontal tab at the current cursor position. esc [3g Removes (clears) all horizontal tabs. esc #3 Converts the line containing the cursor into the upper half of a double-height, double-width (scrollable) line. This sequence should be paired with the following sequence. esc #4 January 1992 13
vt102(7) vt102(7)Converts the line containing the cursor into the lower half of a double-height, double-width (scrollable) line. This sequence should be paired with the preceding sequence. esc #5 Converts the line containing the cursor into a single- width, single-height line. This mode is the default for all new lines displayed on the screen. esc #6 Converts the line containing the cursor into a double- width, single-height line. If the line was being displayed normally, then all characters to the right of center screen disappear. esc [K esc [0K Erase displayed characters from the current cursor position to the end of line. esc [1K Erases displayed characters from the beginning of the line containing the cursor to the character at the current cursor position. esc [2K Erases all characters that are on the same line as the cursor. esc [J esc [0J Erase displayed characters starting from the current cursor position, across and down to the lower-right corner of the screen. esc [1J Erases displayed characters starting from the current cursor position, across and up to the upper-left corner of the screen. esc [2J Erases all of the displayed characters, creating a blank screen, with the cursor location unchanged. esc [number-of-charsP Deletes the specified number of characters, starting with the current cursor position, shifting any unerased characters left, and creating blank spaces at newly unoccupied positions at the right margin. esc [number-of-linesL 14 January 1992
vt102(7) vt102(7)Inserts the specified number of lines after the line containing the cursor, shifting any lines after the cursor-containing line down, and losing lines that no longer fit on the screen. (This sequence is not honored when the cursor is outside the scrolling region.) esc [number-of-linesM Deletes the specified number of lines, starting after the line containing the cursor, shifting any remaining unerased lines at the bottom of the screen upwards, and adding blank lines at the bottom of the screen with the same attributes as the last line that moved up. (This sequence is not honored when the cursor is outside the scrolling region.) esc [4h Establishes insert mode. Each new displayable character that is received causes the old character to the right of the cursor to be shifted right, making room for one new character. Each new character is deposited at the current cursor location, after any shift that must take place; then the cursor advances one column. Characters shifted past the right margin are lost. esc [4h Establishes replace mode, switching insert mode off. Each new displayable character that is received replaces any old character that resides at the current cursor position. esc [i esc [0i Print the current contents of the screen. You can specify that only the scrolling region should be printed, by first establishing the proper printer- extent mode. (See the two sequences that follow.) esc [6n Requests a report from the terminal regarding the location of the cursor. The terminal reply is of the following format: esc [line;columnR Indicates the cursor location in terms of the line and the column where it currently resides. esc [c esc [0c Request a report from the terminal regarding its terminal type. Here is the VT102 terminal reply: January 1992 15
vt102(7) vt102(7)esc ]?6c Signifies a VT102 terminal. esc #8 Displays a full screen of E characters for alignment and adjustment purposes. esc c Resets the terminal to its initial state (reestablishing the terminal settings that were saved by the user, if any differed from the defaults). To avoid losing data characters during the reset, you should enable the automatic XON/XOFF protocol so that the terminal sends an XON control code after the reset, indicating readiness to communicate once again. A delay of 10 seconds is otherwise necessary so that the terminal self-tests have ample time. FILES Systemfolder/Extensions/CommandShell VT102 Executable file SEE ALSO CommandShell(1) in A/UX Command Reference Inside the Macintosh Communications Toolbox 16 January 1992