USING THE ANSI DRIVER
by
C. Scot Giles
875 Lake Street
Oak Park, Illinois   60301

This essay is an attempt to explain how I use the ANSI.SYS driver to configure 
the function keys on my computer, and to control the screen.  I have used these
techniques on my PC and AT for years, and find them to be convenient and 
effective.  ANSI is not widely used by microcomputer fans because the 
documentation supplied by IBM on how to send control codes to the ANSI driver 
is among the most cryptic ever produced by IBM.  I learned them by reading 
computer magazines, and slowly figured out how it could be done.  I am not a 
professional computer programmer (indeed I am a clergyman), so some of my 
technical observations might be in error.  But everything here works, and I 
have retested it before finishing this essay.

This essay covers only IBM Personal Computers (PC, XT or AT) running DOS 2.n or
greater.  I have no experience with compatibles, so you are on your own if you
try to use these techniques on one.

LOADING THE ANSI DRIVER
In order to use any of the techniques in this essay, you must first have loaded
the ANSI.SYS driver into your computer's memory using your CONFIG.SYS file. 
You do this my adding the line, DEVICE=ANSI.SYS somewhere in the CONFIG.SYS
file and rebooting your computer.

KEYBOARD REASSIGNMENT WITH ANSI
Before we get to specific ways to send control codes to the (now loaded) ANSI 
driver, you must first know what those codes mean.  For the function keys the 
codes are listed on the chart below which first appeared in SOFTALK magazine. 
Each function key is assigned an "extended function code" which DOS will use to
recognize that a function key has been pressed and in what shifted mode, if 
any.  Each number is expressed as a 0 followed by a semi-colon, then the number
from the chart below.

KEY     NORMAL  SHIFT   CONTROL  ALT
F1      59      84      94      104
F2      60      85      95      105
F3      61      86      96      106
F4      62      87      97      107
F5      63      88      98      108
F6      64      89      99      109
F7      65      90      100     110
F8      66      91      101     111
F9      67      92      102     112
F10     68      93      103     113

Accordingly, the way to designate the F5 key would be 0;63 while the F10 key 
would be designated by 0;68 or 0;113 if shifted with the ALT key.

If you examine the DOS Technical Reference Manual (not the Technical Manual for
PC hardware), you will find a section on SCREEN/KEYS.  This section was 
contained in the DOS 2.0 documentation, but IBM removed it in later editions. 
Here is a summary of its contents relative to keyboard redefinition.

To change one key to have the meaning of another, enter:

ESC [#;#p

where the first # is the ASCII value of the key being changed and the second #
is the ASCII value of the new definition.  For example, "A" has the ASCII value
of 65 and "Q" has the value of 81.  So:

ESC [65;81p

will result in "A" being redefined as "Q."  It is also possible to redefine a 
key to have the meaning of a string of characters.  This is done by enclosing 
the string in quotes.  So:

ESC [65;"Hi there"p

would change the "A" key to have the meaning of "Hi there."  If the first value
for the first # is a 0 however, DOS knows that what is being changed is not an
ASCII value but the meaning of an extended function code.  So if you were to
enter:

ESC [0;68;"Hi there"p

DOS would know to change the meaning of the function key (in this case F10) to 
the sting enclosed in quotes.  This is the key to redefining your function keys
to perform much used commands: like DIR, CHKDSK, COPY *.* B: etc. or to load
programs from disk.

There is a final trick here.  If you end the escape command sequence with the 
characters ";13p" instead of just "p" the command will self-execute, just as if
you pressed the [enter] key.

The IBM documentation tells the user to preface each command by an ESC command,
and I have represented this in the above paragraphs by writing the characters
"ESC." at the start of each control code sequence mentioned.  Most users assume
that this means to press the ESC key on the keyboard when entering the
commands.  Not so.  To get the Escape Sequence to the ANSI driver you must
enter it using a prompt command or write a .COM file.  For example to configure
the F1 key (extended function code 59) to have the meaning in DOS of "autoexec"
with an [enter] command at the end of it you cannot type:

ESC [0;59;"autoexec";13p

as the ESC will not be recognized by DOS as an escape sequence.  What DOS will 
recognize as an escape sequence is the characters "$e" although this surely 
looks strange at first.  Users familiar with the PROMPT command will notice 
that the "$" character is what the PROMPT command uses as an escape sequence, 
and that is precisely how we will get the redefinition to be recognized by DOS.
If you enter the following command:

PROMPT $e[0;59;"autoexec";13p

you will see that it works perfectly.  You now have the secret to redefining 
the function keys in DOS.  Simply write and run a batch file with a list of 
PROMPT commands and you will have done it.  One precaution, ECHO must be ON, 
otherwise DOS will suppress the PROMPT command and the escape sequences will 
not get through.

As an example, let's create a batch file called KEYON.BAT that will set F1 as 
EDITOR [enter], F2 as PC-FILE [enter], F3 as PC-CALC [enter], F4 as PC-GRAPH 
[enter], F5 as PC-TALK [enter], F6 as PC-WRITE [enter], F7 as BASICA [enter], 
F8 as DIR without the [enter], F9 to run a batch file called MENUOFF.BAT 
[enter] and F10 to run a batch file called MENUON.BAT [enter].  It would be as 
follows:

echo on
PROMPT $e[0;59;"EDITOR";13p
PROMPT $e[0;60;"PC-FILE";13p
PROMPT $e[0;61;"PC-CALC";13p
PROMPT $e[0;62;"PC-GRAPH";13p
PROMPT $e[0;63;"PC-TALK";13p
PROMPT $e[0;64;"PC-WRITE";13p
PROMPT $e[0;65;"BASICA";13p
PROMPT $e[0;66;"DIR"p
PROMPT $e[0;67;"MENUOFF";13p
PROMPT $e[0;68;"MENUON";13p
prompt
cls

You would also want to create another file called KEYOFF.BAT which resets the 
function key definitions to DOS normal.  The format would be:

echo on
PROMPT $e[0;59;0;59p
PROMPT $e[0;60;0;60p
PROMPT $e[0;61;0;61p
PROMPT $e[0;62;0;62p
PROMPT $e[0;63;0;63p
PROMPT $e[0;64;0;64p
PROMPT $e[0;65;0;65p
PROMPT $e[0;66;0;66p
PROMPT $e[0;67;0;67p
PROMPT $e[0;68;0;68p
prompt
cls

I should mention that the purpose of the final blank PROMPT command in each of 
these batch files is to reset the DOS prompt to A> or whatever your default 
prompt is.  It serves no redefinition purpose, but does keep the screen looking
clean.

USING DEBUG TO LOAD THE ANSI DRIVER
While there is no reason why we could not continue to configure our function 
keys by batch files consisting of lists of PROMPT commands, this is a clumsy 
way to proceed.  It is easier to use the DEBUG utility supplied with DOS to 
create a .COM file that will do the job for us quickly and directly, without 
sending any input to screen.  To my knowledge this technique was first 
published by Michael J. Grabel in the December 1984 edition of PC WORLD.

Place a formatted DOS disk containing the DEBUG utility in the default drive, 
and follow the script below.  As you do so hexadecimal numbers will appear on 
the left hand side of your screen.  These numbers will vary depending on the 
configuration of your system.  For our purposes here I will represent the 
numbers in the form xxxx:nnnn.  What you will see on your screen will be 
different.

A>DEBUG [enter]
-A 100 [enter] MOV AH,9 [enter] MOV DX,109 [enter] INT 21 [enter] INT 20
[enter] xxxx:nnnn DB 1B'[0;59;"EDITOR";13p' [enter] xxxx:nnnn DB
1B'[0;60;"PC-FILE";13p' [enter] xxxx:nnnn DB 1B'[0;61;"PC-CALC";13p' [enter] 
xxxx:nnnn DB 1B'[0;62;"PC-GRAPH";13p' [enter] xxxx:nnnn DB
1B'[0;63;"PC-TALK";13p' [enter] xxxx:nnnn DB 1B'[0;64;"PC-WRITE";13p' [enter] 
xxxx:nnnn DB 1B'[0;65;"BASICA";13p' [enter] xxxx:nnnn DB 1B'[0;66;"DIR"p'
[enter] xxxx:nnnn DB 1B'[0;67;"MENUOFF";13p' [enter] xxxx:nnnn DB
1B'[0;68;"MENUON";13p' [enter] xxxx:nnnn DB 1B '$' [enter]

As soon as you have entered the previous line, your computer will respond
with a number in the form of xxxx:nnnn.  Copy down the portion of the
number that is being represented here as "nnnn" as you will need it
later.  Once you have copied the number down, press [enter]

xxxx:nnnn [enter]
-N KEYON.COM [enter]
-R BX [enter]

When you have entered the command above, your computer will respond with
the following line and a colon as a prompt.  At this prompt enter 0 and
press [enter].

BX:0000
:0 [enter]
-R CX [enter]

When you enter the R CX command above, the computer will respond with the
following line and a colon as a prompt.  At this prompt enter the number,
"nnnn" you copied down above and press [enter].


CX 0000
:nnnn [enter]
-W [enter]

The computer will respond with the following.

WRITING nnnn bytes
-Q [enter]

As soon as you enter the Q command (for Quit) you will be back at the DOS 
prompt, and there will be a new file on disk called KEYON.COM.  Simply type it 
at the DOS prompt and your function keys will be configured.  It is a good idea
to use this same procedure to write another .COM file called KEYOFF.COM which
will restore the keys to their native DOS definitions.  The procedure for this
is the same as the above, except that the definition section should be:

xxxx:nnnn DB 1B'[0;59;0;59p' [enter] xxxx:nnnn DB 1B'[0;60;0;60p' [enter] 
xxxx:nnnn DB 1B'[0;61;0;61p' [enter] xxxx:nnnn DB 1B'[0;62;0;62p' [enter] 
xxxx:nnnn DB 1B'[0;63;0;63p' [enter] xxxx:nnnn DB 1B'[0;64;0;64p' [enter] 
xxxx:nnnn DB 1B'[0;65;0;65p' [enter] xxxx:nnnn DB 1B'[0;66;0;66p' [enter] 
xxxx:nnnn DB 1B'[0;67;0;67p' [enter] xxxx:nnnn DB 1B'[0;68;0;68p' [enter] 
xxxx:nnnn DB 1B '$' [enter]

If you find that KEYON.COM doesn't work correctly, reboot the machine to clear 
the definitions and try again.  The most common mistakes are typing errors (I 
often enter a colon when I wanted a semi-colon).  Another source of difficulty 
will arise if you have another file on disk to start with called KEYON.COM or 
KEYOFF.COM.  DEBUG bypasses the normal file allocation of DOS and writes 
directly to the disk.  If you have another file on disk with the same name, 
DEBUG will overwrite it, but unless the other file was exactly the same size as
the new one or smaller, there may be a piece of the old file left over attached
to the end of the new one.  As a precaution, always erase old versions of the
.COM files, or better yet give each one a unique name and rename it later using
the DOS Rename command.

SOME ADDITIONAL TRICKS
Here are some additional control codes for the ANSI driver, summarized from the
IBM material.


1. CURSOR POSITIONING

To move the cursor to a specified position: ESC [#;#h where the first #
is the desired line number and the second the desire column.

To move the cursor up without changing columns: ESC [#a where # specifies
the number of lines moved.

To move the cursor to a specified horizontal and vertical position: ESC
[#;#f where # means first the line number and secondly the column number.

To get a device status report: ESC [6n

To get a cursor position report: ESC [#;#r where the first # specifies
the current line and the second # specifies the current column

To move the cursor down: ESC [#b where # specifies the number of lines
moved down.

To move the cursor forward: ESC [#C where # specifies the number of
columns moved.

To move the cursor backward: ESC [#d where # specifies the number of
columns moved.

To save the cursor position: ESC [s and to restore it: ESC [u.

2. ERASING

To do a CLS (erase screen move cursor to home position): ESC [2j

To erase from cursor to end of line: ESC [k


3. COLOR GRAPHICS

To set the color/graphics attributes, enter ESC [#;#m where the first #
is the desired foreground color and the second is the desired background
color.  Select colors from the list below:

30  black foreground
31  red foreground
32  green foreground
33  yellow foreground
34  blue foreground
35  magenta foreground
36  cyan foreground
37  white foreground
40  black background
41  red background
42  green background
43  yellow background
44  blue background
45  magenta background
46  cyan background
47  white background

To set additional attributes enter: ESC [#m where # is the number of the
desired attribute.  Select attributes from the list below:

0  all attributes off (white on black)
1  bold on
4  underscore (on IBM Monochrome Display)
5  blink
7  reverse video
8  invisible

To give an example of what can be done with these additional codes, a batch 
file called MENUOFF.BAT containing only the line:

PROMPT $e[2J$e[30;40m$h

would blank a color display completely.  It does a CLS, sets the display to a 
black foreground and background and the with the "$h" performs a backspace to 
erase the blinking cursor (the "$h command is documented in the DOS manual 
under PROMPT).  Another batch file called MENUON.BAT containing the lines:

PROMPT $e[0m
prompt
cls

Would reset a color display to restore the screen after MENUOFF.BAT had been 
run.

Enjoy ANSI!  It is a wonderful tool, and can be a lot of fun to use.  It's not 
a keyboard enhancer, and if you load it up with too many keyboard redefinitions
at one time you will run out of environment space.  This is harmless and simply
means that ANSI is full.  But it will work fine to define your function keys
and control your screen.

******************************************************************************
                         How to add Music to your RBBS
                                By John Belew

         One of the nicest features I like about RBBS is the option to  add
    music and color to  your menus and welcome  messages. I just wish  more
    SysOp's would add this feature to their system. Well, this bulletin  is
    intended to help SysOp's in doing this.

         Adding music is quite simple, much like writing PLAY statements in
    basic. The only difference is that the command string is heading by  an
    (Esc)[ and you end the command string with an Ascii 14 which look  like
    this, "". The sytax used in the command string is a follows...

             A-G [#,+,-]  - A-G  are notes.  # or  + following a
                            note  produces a sharp; - produces a
                            flat.
             L(n)         - Sets the lenght of each  note. L4 is
                            a quarter note, L1  is a whole  note,
                            and so on. n may be from 1 to 64.
             MF           - Play  music in  foreground.  Nothing
                            will happen while music is playing.
             MB           - Play music in  background,  continue
                            printing text. NOTE: So far, no comm
                            program  supports  this  command. It
                            does read  it but only treats it the
                            same as MF.
             MN           - Play notes at  normal  lenght, seven
                            eights of the time determined by L.
             ML           - Music legato. Each  note plays  full
                            period set by L.
             MS           - Music  staccato.  Each  note   plays
                            three quarters of the time.
             O(n)         - Set octave. There are 7  octaves. (0
                            through 6).
             P(n)         - Pause (rest), P may range from 1-64.
             T(n)         - Tempo. T sets number  of L4's  a mi-
                            nute. P may range from 32-255.

          A sample string of music would look something like this...

                          (Esc)[MFMST255L4O1CDEFGAB

                 The above string would play a simple scale.

         A FEW TIPS FOR ADDING MUSIC - For the Sysop's out there who  don't
    really want to spend all there  time coding music, there's an easy  way
    out.  Just  steal  a  few  lines  from  you  favorite basic program and
    translate them over. Very simple. Be careful not to get to carried away
    though. Weird things happen  when the lines go  past 255 chrs. To  make
    the music  sound smother,  break the  lines apart  at rests.  For small
    lines, 80 columns and under, the pause between lines at 1200b is  about
    one count.  for lines  over 80  colums, account  for a  two beat  loss.
    Account for  ther pauses  by removing  the necessary  beats at  the end
    rest. One problem about music is that you can only listen to it if  you
    feed it back through you comm program. The only way to do it is to call
    your local RBBS, upload it, then  download it back under ascii. It's  a
    pain, but it's the only way I know of. I hope this file has helped. If
    you need any extra guidence, don't hesitate in leaving a comment or
    message to the SysOp.

                     [+=:=:=:=:=:=:=:=:=:=:=:=:=:=:=:=+]
                      |    The SDA Associates RBBS    |
                      |         (415)794-9624         |
                      |   24hrs a day, 7 days a week  |
                     [+=:=:=:=:=:=:=:=:=:=:=:=:=:=:=:=+]
