copyright (c) 1995, 1999 Paul Wheaton The ANSI-BBS industry is riddled with conflicts. Since the true ANSI standard has not been strictly followed, a plethora of variations have evolved. Some have become popular. This document spells out what BananaCom uses for it's terminal emulation: A mish-mash of ANSI, VT100, pseudo-ANSI and pseudo-VT100 that tries to follow what most modem services expect and use. Perhaps this will help to make BBS's and communication programs work together with a little less research and programming effort. Note that some features of BananaCom are intentionally undocumented. This has mostly to do with VT100 stuff which is well documented in other places AND, I think, the use of which should be discouraged. Terminal sends: All ASCII characters from 1 to 127 are sent as is. If somebody wants to feed a special character that comes through as a character 128 through 255, send that through too. Note that "Doorway mode" is a simple, beautiful thing developed by Marshall Dudley that allows a user calling a modem service to run DOS programs on the modem service! Look for DRWY*.* on your favorite modem service or call Marshall Dudley's support BBS at (615)675-3282. While BananaCom is in Doorway Mode, all IBM PC extended keys send a NULL character (ASCII value 0) followed by the scan code given by the BIOS. The following keystrokes are well established: Keystroke Sent Doorway mode left arrow key ESC [ D NULL 75 right arrow key ESC [ C NULL 77 up arrow key ESC [ A NULL 72 down arrow key ESC [ B NULL 80 home key ESC [ H NULL 71 end key ESC [ K NULL 79 ^home key ESC [ L NULL 119 ^page up ESC [ M NULL 132 F1 key ESC O P NULL 59 F2 key ESC O Q NULL 60 F3 key ESC O w NULL 61 F4 key ESC O x NULL 62 capital "oh", not a zero^ ^ASCII value 0 All other keys send a NULL character (ASCII value 0) and then the BIOS scan code (as a character, not multi digits representing the number). Note that most com programs will use Alt-A through Alt-Z and Alt-1 through Alt-9 and Alt-0. If there happens to be keys left they will be passed through. Function keys are your best bet and are all passed through Alone Shift Ctrl Alt F1 NULL 84 NULL 94 NULL 104 F2 NULL 85 NULL 95 NULL 105 F3 NULL 86 NULL 96 NULL 106 F4 NULL 87 NULL 97 NULL 107 F5 NULL 63 NULL 88 NULL 98 NULL 108 F6 NULL 64 NULL 89 NULL 99 NULL 109 F7 NULL 65 NULL 90 NULL 100 NULL 110 F8 NULL 66 NULL 91 NULL 101 NULL 111 F9 NULL 67 NULL 92 NULL 102 NULL 112 F10 NULL 68 NULL 93 NULL 103 NULL 113 Some com programs use the Page Up and Page Down keys to initiate a file transfer although this seems to be changing - these keys are of great use to BBS's. Page Up NULL 73 Page Down NULL 81 Insert NULL 82 Note that when you press control-page-down with some terminal programs, they send ESC [ H ESC [ 2 J and a lot of BBS's simply ignore that. ctrl-page-down NULL 118 ctrl-end NULL 117 ctrl-left-arrow NULL 115 ctrl-right-arrow NULL 116 shift-tab NULL 15 Terminal receives: Most ANSI terminals use a screen 80x24 - with the last line reserved for reporting the current status of the terminal program. BananaCom uses this standard. There are a few ASCII characters that have a special effect on the terminal: Dec Hex char function 7 7 ^G beep 8 8 ^H destructive backspace 9 9 ^I tab - move to next tab column (8,16,24,32,40...) 10 A ^J line feed - move down one. Scroll up if needed 12 C ^L clear screen & home cursor (1,1) 13 D ^M return - move cursor to column 1 Note that there is some controversy in the ANSI vs. VT100 worlds about what color (attribute) to use when clearing the screen. From what I could find out, this is the result of "might makes right" introduced by DOS version 3.x. Before DOS 3.x, clear the screen was always "clear to black". DOS 3 used "clear to current attribute background color" - this introduced conflict. Now, some programs clear to black and some clear to the current attribute. The safest thing to do, of course, is to set your background attribute to black before you clear. Earlier versions of BananaCom would clear to black, newer versions clear to current attribute - don't count on this staying this way. HOWEVER! You can count on the "ESC [ b" functions that allow you to color a region, including the whole screen! See below for more details. Note also that in Doorway mode passing through a NULL (ASCII value 0), will force the next character to be displayed on the screen and not interpretted. Example: Sending a ^L that is not preceeded by a NULL character will result in clearing the screen. Sending a NULL character and then ^L while in doorway mode will result in the female symbol appearing at the current cursor location. Escape sequences do not have spaces in them. Spaces have been added here for readability. Anything appearing in angle brackets (less than and greater than signs: "<" and ">") is an escape sequence variable. The angle brackets are not sent. ESC D scroll up ~~~~~~~~~~~~~~~~~~ All of the text on the screen (or the scrolling region, if one is defined) is scrolled up one line. The bottom line is filled with spaces colored according to the current attribute. Note that there is no left bracket "[" between the ESC and the 'D'. Example: ESC D scroll all text up one line ESC M scroll down ~~~~~~~~~~~~~~~~~~~~ All of the text on the screen (or the scrolling region, if one is defined) is scrolled down one line. The top line is filled with spaces colored according to the current attribute. Note that there is no left bracket "[" between the ESC and the 'M'. Example: ESC M scroll all text down one line ESC c reset terminal ~~~~~~~~~~~~~~~~~~~~~~~ This is something of particular use to door programs and internet service providers. Sometimes, a user will go into a door or telnet to an internet service and they will set a variety of bizarre terminal modes that BananaCom (and other COM programs) will retain until told to drop them. If you send this sequence, you can know for certain that you have the defaults and a clean slate. I strongly recommend that modem services, door programs and any on-line utilities use this often. Especially if your service is offered on the internet. ESC [ @ insert char ~~~~~~~~~~~~~~~~~~~~~~ Insert a space into the current line at the current cursor position. The character at column 80 is thrown out. The current attribute is used for the new space. ESC [ A cursor up ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Move the cursor up specified number of lines (default is one). If "ESC [ ? 6 h" has been received since last "ESC [ ; r" then the cursor will not be allowed to move beyond the top of the scrolling region. Example: ESC [ 1 0 A move up ten lines Example: ESC [ A move up one line ESC [ B cursor down ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Move the cursor down specified number of lines (default is one). If "ESC [ ? 6 h" has been received since last "ESC [ ; r" then the cursor will not be allowed to move beyond the bottom of the scrolling region. Example: ESC [ 1 0 B move down ten lines Example: ESC [ B move down one line ESC [ C cursor right ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Move the cursor right specified number of columns (default is one). Example: ESC [ 1 0 C move right ten columns Example: ESC [ C move right one column ESC [ D cursor left ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Move the cursor left specified number of columns (default is one). Cannot move beyond left of screen. Example: ESC [ 1 0 D move left ten columns Example: ESC [ D move left one column ESC [ E line feed ~~~~~~~~~~~~~~~~~~~~~~~~~~ Convert to specified number of line feeds. If the cursor is at the bottom of the screen (or scrolling region if one is defined) text will be scrolled up and the bottom line will be cleared. Example: ESC [ 1 0 E convert and process as ten linefeeds Example: ESC [ E convert and process as onr linefeed (why not just send ^J ?) ESC [ F undefined ESC [ G undefined ESC [ ; H move to ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Move cursor to this position. If "ESC [ ? 6 h" has been received since the last "ESC [ ; r" then the cursor will be positioned relative to the scrolling region. This will perform exactly the same as "ESC [ ; f". Example: ESC [ 1 0 ; 5 H The cursor will be positioned at row 10 and column 5. Example: ESC [ 10 H The cursor will be positioned at row 10 and column 1. Example: ESC [ H The cursor will be positioned at row 1 and column 1. ESC [ I undefined ESC [ J clear all or part of display ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Clear all or part of the screen (or scrolling region if one is defined). Note that VT100 emulations always "clear to black" and most ANSI emulations now "clear to current attribute". BananaCom will "clear to current attribute" if it is not in VT100 mode. Cursor does not move. Example: ESC [ 0 J Clear from cursor to end of screen Example: ESC [ 1 J Clear from beginning of screen to cursor Example: ESC [ 2 J Clear whole screen (note that sending ^L does the same thing) Example: ESC [ J same as "ESC [ 0 J" ESC [ K clear all or part of current line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that VT100 emulations always "clear to black" and most ANSI emulations now "clear to current attribute". BananaCom will "clear to current attribute" if it is not in VT100 mode. Cursor does not move. Example: ESC [ 0 K Clear from cursor to end of line Example: ESC [ 1 K Clear from beginning of line to cursor Example: ESC [ 2 K Clear whole line Example: ESC [ K same as "ESC [ 0 K" ESC [ L insert line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "" blank lines will be inserted at the current cursor location. These lines will have the color of the current attribute. The previous current line and all of the lines below will be moved down. Lines that are scrolled beyond the bottom of the screen (or scrolling region, if one is defined) will be lost. Example: ESC [ 1 0 K insert ten lines Example: ESC [ K insert one line ESC [ M ANSI Music / delete line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is the biggest conflict in ANSI emulation. The actual ANSI standard clearly states that this sequence is to be used for "delete line". The person that came up with "ANSI music" must not have known this. There are still many modem services and mainframe computers that depend on this being "delete line" - however, far more people are served by systems that depend on this being "ANSI music". What this means is that as a programmer, you cannot depend on ESC [ M. Some modem services and com programs will lock up when they expect one thing and receive another. Here is a solution: a) A modem service can send "ESC [ b" to the terminal. If the emulation outlined in this document is supported, 005 will be sent back. If it is not, the terminal will most likely not show the escape sequence and you can then know that ESC [ M should be avoided since its interpretation is unknown and could cause a lockup. b) Use "ESC [ N" for music and "ESC [ Y" for delete line. What BananaCom supports for ESC [ M may change although at the time of this writing, it is used for ANSI music. See "ESC [ N" and "ESC [ Y" for information on how to use ANSI music and delete line. ESC [ N <^N> ANSI music ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is provided with BananaCom as a substitute to the traditional ANSI music sequence of "ESC [ M" since that sequence has conflicts. For complete information on how to use ANSI music, look for the file BBSAMT*.* (BBS ANSI Music Tutor) by Linda Bloom. This file is available on the Montana Banana BBS (406)543-8234 and Bloomunit BBS (407)687-8712. Example: ESC [ N E 8 G 8 G 8 G 8 F 4 E 8 G 2 ^N this will belt out the first few notes of "Popeye the Sailor". "ESC [ N" starts the music sequence and the control-N character finishes. What's in between are all of the notes and how long each note lasts. Further details of the music may be provided as specified in BBSAMT. Note that this is not an ANSI or VT100 standard, but something that is in BananaCom. I hope other com program folks do the same. ESC [ O undefined ESC [ P delete char ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Delete the character at the current cursor position. All characters to the right of the cursor will be shifted one to the left. The right most character on the screen will be converted to a space and will have the same attribute as the character that used to be there. Example: ESC [ 1 0 P delete ten characters Example: ESC [ P delete one character ESC [ Q undefined ESC [ R undefined ESC [ S scroll up ~~~~~~~~~~~~~~~~~~~~ see ESC D ESC [ T scroll down ~~~~~~~~~~~~~~~~~~~~~~ see ESC M ESC [ U clear ~~~~~~~~~~~~~~~~ Clear the screen with the "normal" attribute and home the cursor. New text will use the previously defined attribute. Note that this does the exact same thing as ^L. ESC [ V undefined ESC [ W undefined ESC [ X undefined ESC [ Y delete line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This command is provided with BananaCom as a substitute to the traditional delete line sequence of "ESC [ M" since that sequence has conflicts. "" lines will be deleted at the current cursor location. Lines from below will be scrolled up. The blank lines inserted at the bottom of the screen (or scrolling region, if one is defined) will be colored with the current attribute. Example: ESC [ 1 0 Y delete ten lines Example: ESC [ Y delete one line Note that this is not an ANSI standard, but something that is in BananaCom. I hope other COM program folks do the same. ESC [ Z back tab ~~~~~~~~~~~~~~~~~~~ Relocate the cursor to the previous tab. Tabs are located at columns 1, 8, 16, 24, 32, 40, 48, 56, 64, 72 and 80. So, if your cursor is currently located at column 10 and a "ESC [ Z" is received, the cursor will be moved to column 8. ESC [ a undefined ESC [ b Banana ANSI ~~~~~~~~~~~~~~~~~~~~~~ There are several different functions that can be accessed through this sequence. ESC [ 0 b ESC [ b Banana ANSI query. If a terminal uses everything listed in this document, it will send back 0 0 5 ^M (without spaces) later versions may return 006 or 007 or 008 etc. Some versions of BananaCom support special features that will also be reported. e.g., if the copy of BananaCom being used supports the "JPEG as you download" feature, which includes some special escape sequences for positioning the image, 005j would be returned (note that the "j" is simply appended to the end of the version number). If GIF support is also included, 005jg would be returned. These suffixes include: j - JPEG support g - GIF support k - Kermit and Auto Kermit support x - XModem and Auto XModem support c - BananaCom Custom ESC [ 1 ; ; ; ; b Color box. All parameters are optional. Relative to the scrolling region if one is defined. "ESC [ 1 b" would color the entire screen (or scrolling region, if one is defined) to the current attribute. Note that the default for "High" is 24 or the height of the scrolling region if one is defined. Note that "Att" is a number that represents PC text video attributes. Examples: ESC [ 5 ; 3 0 ; 2 0 ; 1 0 ; 1 6 b This would put a blue box on the screen 20 columns wide and 10 lines high with the upper left corner being in position row 5 and column 30. ESC [ 5 ; 3 0 b This puts a box on the screen colored with the current attribute. The upper left corner is in row 5, column 30 and the lower right corner of the box is in the bottom of the screen (or scrolling region if one is defined) and column 80. ESC [ 2 ; ; ; ; b Draw box. Similar to "ESC [ 1 b" except that a single line box is drawn. ESC [ 3 b Preserve the screen. The entire screen (except for the status line at the bottom) is saved. ESC [ 4 b Restore a preserved screen. Whatever the screen looked like before the last "ESC [ 3 b", is how it will look after this escape sequence. Note that things like cursor location and current attribute are not saved. ESC [ 2 1 b ^M Archive a file. If the file can be found, it will be moved into a directory called "ARCHIVE" that is a subdirectory of the directory the file is in. If the "ARCHIVE" directory does not exist, it will be created. ESC [ 2 2 b Send DOC file CRC - this will send the CRC of the BananaCom DOC file followed by a return. This is especially useful to BananaCom Custom sysops that want to be able to trace where a user might have found their copy of the custom. ESC [ 4 1 b Force BananaCom to hang up from the users end. ESC [ 9 1 b Start a Kermit download. ESC [ 9 2 b Start a Kermit upload. ESC [ 9 3 b ^M Start an XModem download (filename is optional). ESC [ 9 4 b Start an XModem upload. Note that these sequnces are not an ANSI standard, but something that is in BananaCom. I hope other com program folks do the same. ESC [ c VT100 query response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Some modem services use mainframe computers that send this and are looking for some unique response or they will assume your terminal is brain dead. BananaCom sends back "ESC [ ? 1 ; 0 c" and that seems to keep everything happy. NOTE! This sequence will activate the BananaCom VT100 mode which will make some of the escape sequences defined here behave differently. ESC [ d undefined ESC [ e undefined ESC [ f move to ~~~~~~~~~~~~~~~~~~ see "ESC [ H" ESC [ g not used - VT100 tabs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is supported in BananaCom but not typically supported in other com programs. See VT100 manual for details. ESC [ h set options ~~~~~~~~~~~~~~~~~~~~~~ These options include sending an actual question mark or equals sign as part of the sequence: ESC [ ? 6 h certain functions which normally ignore the scrolling region, will now operate relative to the scrolling region. Note that those functions will again ignore the scrolling region the next time the scrolling region is changed. ESC [ ? 7 h Auto word wrap is turned on (it is normally on - this is provided in case you turn it off). ESC [ = 2 5 5 h doorway mode on (default is off). This makes BananaCom disable many user functions so that those keystrokes may be passed through to the modem service - also, all cursor keys that were passed through as an escape sequence, are now passed through as a null sequence (see top of file for more info). ESC [ i print stuff ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ESC [ 5 i redirect everything coming in through the modem to the printer. ESC [ 4 i redirect everything coming in through the modem to the screen. ESC [ j undefined ESC [ k undefined ESC [ l set options ~~~~~~~~~~~~~~~~~~~~~~ These options include sending an actual question mark or equals sign as part of the sequence. They compliment the "ESC [ h" sequences. Note that these seqences end with a lowercase L: ESC [ ? 6 l Negates "ESC [ ? 6 h". This is the default. ESC [ ? 7 l Auto word wrap is turned off. Note that the next time you change the scrolling region, word wrap will be turned on again. ESC [ = 2 5 5 l doorway mode off ESC [ ; ; ... m set video attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set the foreground color, background color and blink attributes for future text. Note that each number may overwrite or enhance a previous number. There are four basic attributes: Foreground color: 8 colors Bright: On or off Background color: 8 colors Blinking: On or off Effects Possible numbers to pass: FC Br BC Bl 0 "normal": gray on black, no blink x x x x 1 bright foreground x 2 regular (non-bright) foreground x 4 underscore if available x 5 Blink on x 6 Blink on (yup, same as 5) x 7 reverse x x 8 invisible text (fore=back) x x x 30 black (+Br=dark gray) x 31 red (+Br=bright red) x 32 green (+Br=bright green) x 33 brown (+Br=yellow) x 34 blue (+Br=bright blue) x 35 magenta (+Br=bright magenta) x 36 cyan (+Br=bright cyan) x 37 gray (+Br=white) x 40 black x 41 red x 42 green x 43 brown x 44 blue x 45 magenta x 46 cyan x 47 gray x Examples: ESC [ 0 ; 1 ; 3 3 m yellow on black with no blink ESC [ 3 3 m use same background as before. no change to blink attribute. foreground is either brown or yellow depending on the bright attribute. ESC [ m use "normal" attribute - gray on black, no blink. ESC [ 6 n report current cursor location ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the cursor is located in the lower-right corner of the screen, BananaCom will respond "ESC 2 4 ; 8 0 R". Many modem services will send "ESC [ 6 n" before asking a user what their name is. When the response is given, the modem service knows that the calling computer supports ANSI terminal emulation. ESC [ 2 5 5 n report screen size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ "ESC 2 4 ; 8 0 R" is always sent back. ESC [ o undefined ESC [ p not used - ANSI keyboard reassignment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ not supported in BananaCom ESC [ q not used - VT100 keyboard lights ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ has to do with turning the VT100 keyboard lights on and off. not supported in BananaCom ESC [ ; r set scroll region ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Define a region of the screen for scrolling. This is usually used for full screen text editors. Some information can be stored on some parts of the screen that will remain for the entire editing session - such as what keys you push to indicate that you are done editing. The scroll region will be where the user types the text of their message. Some commands (escape sequences) always ignore the scrolling region; some default to ignoring the scrolling region, but can work relative to the scrolling region when the "ESC [ ? 6 h" sequence is sent; some always work relative to the scrolling region if one is defined. Example: ESC [ 2 ; 2 3 r leave the first and last lines out of the scrolling region. Example: ESC [ 5 r the first four lines are left out of the scrolling region. Example: ESC [ r turn off scrolling region ESC [ s save current cursor position ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The current cursor position is stored and can be reset with "ESC [ u" ESC [ t undefined ESC [ u restore cursor position from last save ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Restores the cursor position that was stored with "ESC [ s" ESC [ v undefined ESC [ w undefined ESC [ x undefined ESC [ y not used - VT100 tests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ VT100 specs say that this is to invoke certain tests. Not supported in BananaCom. ESC [ z not used - reset ~~~~~~~~~~~~~~~~~~~~~~~~~~~ some "ANSI" terminals use this to reset The information in this document is for programmers writing all sorts of communications software - whether BBS's, door programs, or terminal emulation programs. If you use this, I hope you mention "Banana ANSI" in your documentation. The latest version of this document can be found on www.wresearch.com/bananacom Resources: BBSAMT40.ZIP - ANSI Music Tutorial by Linda Bloom DRWY222.ZIP - Doorway by Marshall Dudley VT101 Video Terminal User Guide - part EK-VT101-UG-003 by Digital Equipment Corporation. VT102 Video Terminal User Guide - part EK-VT102-UG-003 by Digital Equipment Corporation. ANSI.X34 - ANSI X3.64 encodings as interpretted by a BYTE magazine author, April 1984 page 365.