

---------------------------------------------------------------------
                The Complete Escape Codes
        for Sirius 1/Victor 9000, the Apricots, and Vicki
                by Friedman Wagner-Dobler
---------------------------------------------------------------------


Escape sequences are special codes used to manipulate the display of a
microcomputer -- to move the cursor around the screen, to display text or
graphics in reversed video or with highlighting, and so on.

The Sirius and Apricot use escape sequences which are based on older terminals,
the DEC VT52 and the Zenith/Heathkit H19. But many codes have been added --
which means there are now some 200 different codes to confuse the programmer.

Worse still, the documentation for escape sequences has not always been decent,
complete, honest and truthful. This guide is as complete as we can make it ...

Novice programmers often find it difficult to come to terms with the concept of
escape codes. And if you're used to smaller home computers such as those from
Commodore or Sinclair, you'll probably be puzzled by the apparent complexities
of controlling the screen of an Apricot or Sirius.

On many machines -- especially on home computers -- you can just use a CLS
command to clear the screen. On the Sirius or Apricot, you'd have to say PRINT
CHR$(27)"E" if you program in Microsoft Basic. 

Similarly, several computers have a statement something like LOCATE 1,1 to move
the cursor to the second column of the second line -- on the Sirius you have to
use something like ...

PRINT CHR$(27)"Y"CHR$(33)CHR$(33)



The reason why ...
---------------------------------------------------------------------
The reason for this awkwardness is that the Sirius and subsequently the Apricot
were conceptually divided into two separate pieces of equipment by their
designers. One of them is the central processing unit or 'Mainframe' (ever
wondered why the serial numbers on the system unit/disk drive box begin with an
'M'?). The other is a 'terminal' consisting of a keyboard and a screen; and this
terminal is connected by a two-way link which carries single characters from the
keyboard to the Mainframe or from the Mainframe to the screen.

Ordinarily any code which travels from the Mainframe to the conceptual screen is
interpreted by the display as a printable character -- a letter, number,
punctuation mark, or an arithmetic or other symbol. If the Mainframe sends code
65 to the screen, it will display a capital 'A': code 66 is a capital 'B' ...
and so it goes on -- a list of the ASCII character set will show you which code
corresponds to which letter (ASCII is an industry standard matching printable
characters with codes, and most computers more or less follow its conventions at
least for alphanumerics).

The trouble starts when you want to do more than just display printable
characters: clearing the screen for instance. Obviously what the Mainframe needs
to do is to send a special code down the line which means 'clear the screen'. In
fact some computers interpret code 12 (known as 'FF' or 'form feed' in the ASCII
convention) as doing just that. But this approach only works with a restricted
number of commands; and because of historical limitations, fewer than 30 of the
standard set of ASCII codes can be used in this way.

The solution is to introduce so-called 'escape' codes consisting of two
characters. The first of these is always code 27 -- the ASCII code for the
'escape' character itself; the second indicates the function to perform. For
example CHR$(27)"E" clears the screen and moves the cursor to the top left: the
first code, 27, tells the conceptual terminal that a command will be specified;
the second, "E", tells the terminal to clear the screen.

Incidentally, you can use either the character generated or the code itself. An
alternative to CHR$(27)"E" is CHR$(27)CHR$(68). Not as easy or as legible,
though, is it?

Some escape sequences consist of more than two characters. This is necessary
where a function requires additional information before it can be performed. To
move the cursor to a specific location on the screen, for instance, the line and
column of the new cursor position must be given: so the 'move cursor' sequence
consists of two-lead in characters (the first of them being the escape code)
followed by two more characters which indicate the line and column respectively.



Conventions in the tables       
---------------------------------------------------------------------
Table 2 summarizes the control codes found on the Sirius and ACT's machines:
Table 3 lists the escape codes. Both tables are given in ascending order of
codes for ease of reference.

You should be aware of some of the conventions we've used. For a start our
numbering of lines and columns assumes that the first position is 0, not 1. So
the top left of the screen (the 'home position') is at 0,0; the rightmost column
is 79, the bottom line is 24.

The letters X, Y, Z and S in the second column of the tables indicate an
argument. In this case, the Action column will give details of the meaning and
range of the argument.



Access from Basic               
---------------------------------------------------------------------
Letters enclosed in single quotes -- as, for example, 'X' -- refer to the
corresponding ASCII code. In Basic, use double quotes to generate the correct
code. Thus, ESC 'E'  should be expressed in a Basic PRINT statement as PRINT
CHR$(27)"E"; as a string expression it would be CHR$(27)+"E".

To avoid having to write CHR$(27) each time you use an escape sequence you can
define the escape code at the beginning of a program. You can do that for
instance with the line ...

        10 E$=CHR$(27): REM escape code

Subsequently you can use E$ instead of CHR$(27), and E$"E" instead of
CHR$(27)"E". Further, it's good practice to do this for all the escape sequence
you'll want to employ frequently -- define them as strings at the beginning of a
program.

There are two reasons for this. Legibility is improved: if you define a string
as CLS$=E$+"E" you can subsequently use PRINT CLS$; to clear the screen, which
will make your program more readable. 

Second, if you move your program to another machine it will probably utilise
totally different escape sequences. Defining the escape sequence in a separate
and clearly defined portion of your program will make it much easier to handle
the re-customisation when you do move the program to a different computer.



Caveat  
---------------------------------------------------------------------
A word of warning here: escape sequences do not always work as advertised. We've
tested most of those listed to make sure they do actually perform, but sometimes
certain escape sequences don't work with early releases of an operating system. 

The tables are based on the Sirius MS-DOS BIOS version 2.61, version 1.2 of the
132-column program, and the Apricot MS-DOS BIOS version 2.4: the information for
the Apricot F1 and Portable is based on preliminary technical documentation.



Quick reference by function
---------------------------------------------------------------------
While Tables 1 and 2 are useful for reference in most cases you'll want to find
an escape code by the function it performs. The following paragraphs list escape
codes by function; you should still check the tables for further information and
to see whether the code actually works on your particular hardware.


        Erasing         

The erase functions are quite straightforward, for they simply place spaces in
the area indicated. The functions which erase to or from a particular location
also erase the character under the cursor.

ESC 'E'         erase entire screen
ESC 'b'         erase from beginning of screen
ESC 'J'         erase to end of screen
ESC 'o'         erase from beginning of line
ESC 'K'         erase to end of line
ESC 'l'         erase current line
ESC 'z'         reset screen
ESC '+'         erase foreground [not on F1 or Portable]
ESC '-'         erase background [not on Sirius or F1 or Portable]

ESC '+' and ESC '-' can be quite useful for data entry. (They don't work on the
F1 or portable, though, and ESC '-' doesn't work on the Sirius.) 'Erase
foreground' examines every character on the screen and erases it if it is
displayed in high intensity: 'erase background' does the same thing for
characters displayed in low intensity.

Only ESC 'E' and ESC 'z' change the location of the cursor; all the other
functions leave the cursor where it is.


        Inserting               

Inserting characters in the middle of a line is usually done in 'insert mode' --
any printable character is inserted at the current cursor position, and the
characters pushed to the right are lost. ESC 'L' and ESC 'P' are independent of
insert mode.

ESC '@'         enter insert mode
ESC 'O'         exit insert mode
ESC 'L'         insert blank line
ESC 'P'         insert one character


        Deleting                

There are only two sequences for deleting, one for lines and the other for
single characters. (The standard ASCII delete character (code 127) has no
effect.)

ESC 'M'        deletes current line
ESC 'N'        deletes character


        Moving the cursor       

The cursor movement functions are more plentiful. They include some of the
classic ASCII-standard control characters such as CR (carriage return) and LF
(line feed).

ESC 'A'         move cursor up
ESC 'B'         move cursor down
ESC 'C'         move cursor right
ESC 'D'         move cursor left (with no wraparound)
BS              move cursor left (with wrapping possible)
LF              line feed
HT              horizontal tab
ESC 'h'         reverse horizontal tab
CR              move cursor to column 0
ESC 'I'         reverse line feed
ESC ';'         move cursor to status line
ESC 'H'         move cursor to home position
ESC 'Y' X Y     move cursor to specified position
ESC 'j'         save cursor position
ESC 'k'         move cursor to saved position


        Moving lines            

There's a solitary escape sequence which can be used to move lines around the
screen. ESC 'X' swaps the current line with a line which is remembered
internally in the 'terminal'. Initially, the stored line is blank, so the first
time you issue ESC 'X', the current line disappears. The second use of ESC 'X'
makes the old line re-appear. 

This sequence does not work on the Apricot.


        Display attributes              

The attributes with which characters are displayed on the screen can be
controlled with four pairs of escape codes.

ESC '0'         turn underlining on
ESC '1'         turn underlining off
ESC 'p'         turn reverse display on
ESC 'q'         turn reverse display off
ESC '('         turn high-intensity display on
ESC ')'         turn high-intensity display off
ESC '9'         turn overstrike on
ESC ':'         turn overstrike off

You can combine attributes freely. For instance, to print a reverse message
highlighted, use 10 PRINT E$"p"E$"(".  

All attributes are cancelled by the reset function, ESC 'z' -- note that merely
clearing the screen (with ESC 'E') does not clear any of the attributes.


        Cursor format           

The attribute escape sequences affect all characters printed after the sequence
has been issued; they do not affect the way the cursor itself is displayed. For
that you need the following escape sequences:

ESC '2'         set blinking cursor
ESC '3'         set solid cursor
ESC 'x' '4'     set block cursor
ESC 'y' '4'     set underline cursor
ESC 'x' '5'     set cursor invisible (off)
ESC 'y' '5'     set cursor visible (on)

Again, the cursor attributes can be combined -- to make the cursor a solid
underline, for instance, use PRINT E$"x4"E$"3".


        Keyboard input          

Some of the escape sequences cam report back information from the screen. This
they do by inserting characters into the console input stream, which is
equivalent to the user typing at our conceptual terminal's keyboard: an
application program can't tell the difference between what the user types and
what the 'transmit' escape sequences report back. Here's what the various
sequences send:

ESC '#'         sends the whole screen excluding status line
ESC '$'         sends character under cursor
ESC '%'         sends current line
ESC ']'         sends status line
ESC 'Z'         sends VT52 identification
ESC 'n'         sends current cursor position
ESC 'i'         sends the Apricot BIOS version

Take the sequence ESC '$': it places the character that is currently under the
cursor into the keyboard buffer. Thus if the character under the cursor was the
letter 'B', this bit of Basic will assign 'B' to A$:

        20 PRINT E$"$";
        30 A$=INPUT$(1)

ESC 'n' reports back the cursor position. It does so in the form required to
position the cursor, so this will work:

        20 PRINT E$"n";
        30 A$=INPUT$(4)
        40 PRINT:PRINT:PRINT:PRINT
        50 PRINT "BACK TO"
        60 PRINT A$;"BASE"

(Actually in this particular case it would probably have been easier to use a
combination of ESC 'j' and ESC 'k'.)


        Character sets          

The Sirius and Apricot normally have a single character set, but they can be
configured with two character sets. Even the standard character set cannot
normally displayed in its entirety, however, because some of the characters are
interpreted as control codes and therefore ignored. The following codes offer
remedies for these two problems:

SO              select character set 2
SI              select character set 1
ESC 'F'         enter graphics mode
ESC 'G'         exit graphics mode
ESC '8'         set literal mode for next character
ESC '*'         select alternate font


        Scrolling               

Typically you scroll the screen up or down only when you use LF or ESC 'I',
though some inadvertent scrolling does of course happen when you insert or
delete lines or characters. In addition, though, the Apricot has some fancy
sequences to perform multiple scrolls:

ESC 'Q' X       scroll left the specified number of columns
ESC 'R' X       scroll right the specified number of columns
ESC 'S' X       scroll up the specified number of lines
ESC 'T' X       scroll down the specified number of lines
ESC 'x' 'E'     fast scrolling [F1 only]
ESC 'y' 'E'     smooth scrolling [F1 only]


        Wrapping                        

A character printed at column 79 on a line will normally cause the next
character to be displayed at column 0 of the next line: this is known as
'wrapping' and it can be switched on or off. 

Note that the wrap status also affects the backspace control character: if wrap
is enabled, a backspace in column 0 will move the cursor to the last column of
the previous line. The 'cursor left' and 'cursor right' commands never wrap.

ESC 'v'         wrap at end of line
ESC 'w'         discard at end of line


        CR and LF                       

Ordinarily, the function of a carriage return (CR) is to move to column 0, while
a line feed (LF) is a cursor down movement (with an upward scroll if necessary).
This is not necessarily the way other computers see it, so there are sequences
to combine the functions of CR and LF.

ESC 'x' '8'     automatic LF after CR
ESC 'y' '8'     no automatic LF after CR
ESC 'x' '9'     automatic CR after LF
ESC 'y' '9'     no automatic CR after LF


        Sound           

Most of the sound-related functions are only marginally useful, but here they
are anyway:

BEL             ring bell
ESC 'x' '2'     turn on key click 
ESC 'y' '2'     turn off key click 
ESC 'x' 'A'     increase volume
ESC 'y' 'A'     decrease volume
ESC 'x' 'F'     increase bell volume
ESC 'y' 'F'     decrease bell volume
ESC 'x' 'H'     increase click volume
ESC 'y' 'H'     decrease click volume
ESC 'x' '7'     turn on margin bell
ESC 'y' '7'     turn on margin bell


        Hold mode               

'Hold mode' on the Sirius appears to allow you to stop a program from outputting
to the screen. The only real use for this function is probably in local mode,
where it could be used to stop and start the screen in a manner similar to the
Apricot's STOP key.

Local mode means that you can define a key on the Sirius keyboard which will
send an escape sequence directly to the screen without the operating system
noticing. For instance, if have a Sirius with the standard keyboard definition
when you press ALT-CLR the screen will be reset. But an application program
running at the same time will not even notice the fact you've pressed a key.

ESC '['         set hold
ESC '\'         clear hold
ESC '^'         toggle hold
ESC 'x' '3'     hold screen on
ESC 'y' '3'     hold screen off


        The keyboard            

Under some circumstance you may want to lock the keyboard. That prevents the
user from interrupting the program; it doesn't of course guard against the user
pressing the reset button -- and also you must make sure that the program re-
enables the keyboard at a later stage (otherwise you'll be driven to the reset
button yourself).

Some of the other keyboard functions are mythical. The useful one is ESC '4',
which allows you to change the ASCII value associated with a particular key. It
is however machine-dependent: keys are referred to by 'logical key number', and
the logical key numbers used by the Sirius and Apricot differ.

ESC '{'         lock keyboard
ESC '}'         unlock keyboard
ESC '4' X Y Z   change key value
ESC 't'         enter keypad shift mode
ESC 'u'         exit keypad shift mode
ESC '='         switch alternate keypad on
ESC '>'         switch alternate keypad off
ESC '?'         enter calculator [Apricot PC only]


        Print functions         

Only the Apricot allows you to dump the contents of the screen to the system
printer. The sequence ESC '&' first issues a form feed to the printer and then
prints the entire screen; ESC ''' does not issue a form feed and prints only the
line under the cursor.

ESC '&'         print the entire screen
ESC '''         print current line


        The MicroScreen         

Here's everything you need to play with the Apricot PC's MicroScreen. (In
addition, the functions marked [M] in table 3 also work with the MicroScreen.)

ESC '/' X       set MicroScreen LEDs
ESC '<'         display date and time
ESG 'g'         disable date and time display
ESC 'U'         enable dual output to MicroScreen and main 
                display
ESC 'V'         disable dual output to MicroScreen and main 
                display
ESC 'W'         output to Microscreen only
ESC 'c'         disable MicroScreen scroll
ESC 'd'         enable MicroScreen scroll
ESC 'e'         switch underline cursor on
ESC 'f'         switch underline cursor off
ESC 'r'         enable MicroScreen echo
ESC 's'         disable MicroScreen echo


The ESC '/' function sets the LEDs on the Microscreen. X is a bit map
representing the LED status; bit 0 is the left hand LED, bit 5 the rightmost.
Alternatively X can be calculated by adding the following values:


         left                                right
LED no.  1       2       3       3       5       6
--------------------------------------------------
value    1       2       4       8      16      32


        Viewports               

The Apricot allows 'viewports', which means that a limited area on the screen
can become a terminal within a terminal: all scrolling and clearing takes place
within that area only.

ESC ',' X Y Z S         set viewport
ESC '.'                 reset viewport

X and Y respectively are the top and bottom lines of the viewport area, Z and S
the lefthand and righthand columns.


        Colour                  

The Apricot F1 and portable have escape codes to control colour. 

ESC '5' X               set foreground colour
ESC '6' X               set background colour
ESC 'x' 'G'             reset colour palette
ESC 'y' 'G' X Y         set palette colour

A 'palette' is used to specify the foreground and background colours. That means
you do not specify a colour directly: instead you request, say, colour 0. The
colour which will be displayed is determined by the ESC 'y' 'G' command, which
for instance allows you to request that colour 0 be red.


        Using 132 columns               

The following sequences are only used by or for the Sirius 132-characters-per-
line utility:

ESC 'm' '1' X Y         set cell size
ESC 'm' '2' X Y         set screen size
ESC '|'                 switch 132 columns on

X specifies the width in dots for the cell size, the top line for screen size; Y
specifies depth of the cell or the bottom line for the screen.


        The status line         

The 25th line on the display, the 'status' line, is not affected by most of the
escape sequences and control codes. For instance, if the screen scrolls only the
first 24 lines will move; the status line stays where it is. Likewise if a line
is inserted in the middle of the screen, the status line is unaffected. Even the
clear screen sequence ESC 'E' does not clear the status line.

Two steps are necessary to put something on the status line. First you must
enable it with the sequence ESC 'x' '1' -- unless you have used that, the cursor
cannot move to the status line. Next you have to move the cursor into the status
line with a cursor movement command such as ESC 'Y' '8' ' ': that places the
cursor at the first column (' ') of the status line ('8'). You can now use the
status line to your heart's content.

Once you're there, most of the escape sequences which apply to the screen
operate in an equivalent way on the status line. But there are exceptions.
Because there is only one status line, commands such as 'insert line' (ESC 'L')
and 'delete line' (ESC 'M') will simply clear the status line. And the status
line never scrolls -- so a line feed is treated simply as a carriage return.
Similarly printing at the end of the status line will return you to the
beginning of that line.


        Screen contrast and brightness          

These codes replicate the ALT/cursor key effects:

ESC 'x' 'B'     increase brightness
ESC 'y' 'B'     decrease brightness
ESC 'x' 'C'     increase contrast
ESC 'y' 'C'     decrease contrast


        Miscellaneous           

The following sequences perform more or less useful functions which do not fall
under any of the other headings.

ESC '7' X       set screen mode
ESC '_'         mythical debug toggle
ESC '`'         save environment
ESC 'a'         restore environment
ESC 'i' X       display banner [Sirius only]


        Reset           

The sequence ESC 'z' not only clears the screen, it also sets various parameters
to their power-on value. It's generally a good idea to use ESC 'z' once at the
beginning of a program to make sure the screen is in a known state.



Coming soon -- ANSI codes
---------------------------------------------------------------------
Most of these escape sequences are specific to the Sirius and Apricot. They will
not work on most other machines, including the IBM PC. 

There is, however, a set of escape sequences which will work on IBM's PC-DOS 2
as well as the Apricot (unfortunately they have not been implemented on the
Sirius). These were defined by the American National Standards Institute and are
hence known as ANSI codes. 

ANSI codes differ considerably from the standard Apricot/Sirius codes in
philosophy -- for a start, parameters are expressed as integer numbers rather
than 8-bit codes. So we'll present them in a future article. Watch this space
(ASCII code 32).




Table 1 -- the standard ASCII codes


Code          Character
-----------------------
00              NUL             
01              SOH             
02              STX
03              ETX
04              EOT
05              ENQ
06              ACK
07              BEL
08              BS
09              HT
10              LF
11              VT
12              FF
13              CR
14              SO
15              SI
16              DLE
17              DC1
18              DC2
19              DC3
20              DC4
21              NAK
22              SYN
23              ETB
24              CAN
25              EM
26              SUB
27              ESC
28              FS
29              GS
30              RS
31              US
32              space
33              !
34              "
35              #
36              $
37              %
38              &
39              '
40              (
41              )
42              *
43              +
44              ,
45              -
46              .
47              /
48              0
49              1
50              2
51              3
52              4
53              5
54              6
55              7
56              8
57              9
58              :
59              ;
60              <
61              =
62              >
63              ?
64              @
65              A
66              B
67              C
68              D
69              E
70              F
71              G
72              H
73              I
74              J
75              K
76              L
77              M
78              N
79              O
80              P
81              Q
82              R
83              S
84              T
85              U
86              V
87              W
88              X
89              Y
90              Z
91              [
92              \
93              ]
94              ^
95              <
96              `
97              a
98              b
99              c
100             d
101             e
102             f
103             g
104             h
105             i
106             j
107             k
108             l
109             m
110             n
111             o
112             p
113             q
114             r
115             s
116             t
117             u
118             v
119             w
120             x
121             y
122             z
123             {
124             |
125             }
126             ~
127             delete


The first 32 ASCII codes are non-printable characters that were originally
intended for use as control codes -- mostly for communications, some for printer
and screen control. These are included in Table 2 to indicate how they affect
the Apricot and Sirius.

Code 27, the escape code, is of course included in this collection. It's called
'escape' incidentally because it was originally intended to halt a program
prematurely -- to 'escape' from the program, just as the ESC key might abort a
function or a program.

Note that ASCII is an American code, and does not include a Sterling sign as
standard. Most British implementations use code 35 and replace the hash mark
with a pound sign, which is why British keyboards and printers find it difficult
to do both ...



