



                               TSR_IN_BASIC

                                  ver 2.1
                                written by
                                 G.M.McKay




     These programs allow you to write "Terminate and Stay Resident" (TSR)
programs in all forms of the BASIC language - BASIC, BASICA, GWBASIC,
QBASIC, and QUICK BASIC. No longer are TSR programs restricted to the very
difficult to use Assembly Language - the ease of use of BASIC saves weeks
of programming time.



***** IMPORTANT ******************************************* IMPORTANT *****
*****                                                                 *****
*****     YOU WILL BE COMBINING THESE PROGRAMS INTO YOUR OWN, SO      *****
*****     AS A FIRST STEP MAKE BACKUP COPIES IN CASE OF ACCIDENTAL    *****
*****     ERASURE :                                                   *****
*****                    "COPY TSR*.BAS TSR*.BK"                      *****
*****                                                                 *****
***** IMPORTANT ******************************************* IMPORTANT *****





1. DISTRIBUTION :



     This software is being distributed under the SHAREWARE system - I
encouraged you to distribute this program unaltered to your friends,
business associates, and bulletin boards. This system allows you to try out
the software to make sure it works on your computer and fills your needs.
However, it is copyrighted and is not free. If you are still using the
software after a two week evaluation period, you must "buy" it by
registering your copy with its inventor. As an incentive to do this, on
full registration I will send you :

          i)  a registered copy of the latest version.

         ii)  a full description on how to use the keyboard
              interrupt to call your TSR programs using "hotkeys".

        iii)  documentation and explanation of the machine language
              programs called by the TSR_IN_BASIC routines.

         iv)  the latest version of the popular FIVE HUNDRED CARD GAME
              software (which uses mouse control). 

          v)  the latest version of the COPY_DIR program - a file copying
              utility which allows you to copy large directories onto
              multiple different sized floppy disks.

     This is an honour system - if you use this program without paying for
it, may all your programs fail to Stay Resident.

     You should have these files if you have a complete copy of the 
TSR_IN_BASIC program:

          TSR.BAS - base TSR program for GWBasic
     TSRQUICK.BAS - base TSR program for QuickBasic
        TSRQB.EXE - TSR program for Qbasic
           CS.COM - internally used memory allocation program
          TSR.TXT - this help manual
       README.BAT - program to read help manual
         LIST.COM - program to read help manual
         REGO.FRM - registration form
        DEMO1.BAS - demonstration program
        DEMO2.BAS - demonstration program
        DEMO3.BAS - demonstration program
        DEMO4.BAS - demonstration program
        DEMO5.BAS - demonstration program
        DEMO6.EXE - demonstration program






2. INTRODUCTION :



     Terminate and Stay Resident programs (TSR's) are an important part of
DOS operating systems because DOS is not truly multi-tasking. While other
operating systems like UNIX can handle many different tasks at once, DOS
can only handle one main program, but can be temporarily diverted to other
programs in its memory in response to certain stimuli. These stimuli are
called "Interrupts". So TSR's are programs which are "installed" by running
them normally, but when they stop (terminate) they stay in the computer's
memory (stay resident). The computer knows that they are there and does not
load other programs on top of them, but otherwise ignores them. If you want
to see the TSR's that are currently in your computer's memory you can enter
"MEM/C | MORE" if you have DOS 5.0 or higher (the popular menu program
POWERMENU also lists TSR's). The initial installation of these TSR's is
usually in your AUTOEXEC.BAT or CONFIG.SYS files - look at these files to
compare them with what has stayed resident eg. MOUSE.COM. Each of these
TSR's is constantly being reactivated by different Interrupts (not all of
which are available for us to call), and in nearly all cases you are not
aware that they have taken some action.

     Basic is a high level language which is not only easy to use (for a 
computer language), but is powerful and traditionally associated with PC's
(in fact PC's were available running Basic before they had DOS). A "Basic
Interpreter" (like Microsoft or Compaq Basic, BasicA, GWBasic, or the newer
QBasic) interprets each line of a Basic program into machine language,
executes it, then looks at the next line - rather like translating a line
in a French construction manual into English, following the instruction,
then returning to the next French line. QuickBasic is a "Basic Compiler"
which compiles the whole Basic program into Machine Language which can then
be run (the advantage in this is that it runs about 7 time faster than
Interpreted Basic as the machine language program is effectively "ready for
use"). This manual assumes that you have a working knowledge of the form of
Basic that you will be using - it is not an instruction manual on how to
program in Basic.

     GWBasic is the best form of BASIC to use with TSR_IN_BASIC as it does
not care what version of DOS you are using. If you particularly wanted to
use Basic or BasicA you should be using DOS version 3.3. If you are not
using ver 3.3, you can fool the computer into thinking that you are, by
installing SETVER in your CONFIG.SYS file and including BASICA.COM 3.3 in
the SETVER list - refer to your DOS manual or on line help.

     Never before could Basic programs be run as TSR's. This means that
TSR's have had to be written in Machine Language or Assembly Language (one
level higher than Machine Language) which is very space efficient, but is a
very laborious and complicated way to program. Now every program you have
written in Basic can be made to reside in the background in memory (ie. as
a TSR) and can be restarted at will.


     The TSR's currently running on your computer do a number of important
jobs. TSR's you may care to write and install, may do similarly important
jobs or may be more frivolous. Examples of these are pull down help menus,
disabling Ctrl Break or Prt Scrn keys, assign new meanings to certain keys, 
produce sounds, produce new colours (like ANSI), grab screens, random
novelty messages, alarm timer calls, hotkey calculator.

     "Interrupts" can be caused by hardware (eg. pressing a keyboard key or
pressing Ctrl Break), or by software (eg. called from running program), or
by a PC internal device (eg. the PC timer calls an Interrupt 18.2 times per
second).








3. GENERAL PROGRAM STRUCTURE :



     TSR_IN_BASIC is principally designed for use with Basic, BasicA, and
GWBasic Interpreters (as this gives the smallest TSR programs of this
class) and the routines for these Interpreters are identical. A second set
of routines is required for running compiled ( .EXE ) programs made in
QuickBasic. These .EXE programs are relatively small and fast, but
QuickBasic is a commercial Microsoft product, so is not available to
everyone. A third set of routines is required for running with QBasic.
Running with QBasic is the least desirable of these three options, as it
occupies a large amount of memory and allocates its memory in a different
way to the other Interpreters. So it has only been included here in a
limited form for people who have become so used to the newer QBasic that
they cannot revert to the simpler GWBasic.

***** IMPORTANT ******************************************* IMPORTANT *****
*****                                                                 *****
*****     These instructions have been broken up into three separate  *****
*****     categories to cover these three separate sets of routines.  *****
*****     You can avoid  wholesale confusion  by reading  only the    *****
*****     sections that apply to the Interpreter that you are using.  *****
*****                                                                 *****
***** IMPORTANT ******************************************* IMPORTANT *****

3.1                      BASIC , BASICA , GWBASIC

     Basic, BasicA, and GWBasic all use the same TSR_IN_BASIC routines.
This takes the structure of a Basic program (eg. MYPROG.BAS) which is made
up of the supplied TSR.BAS base program with your own lines added into it.
When it is initially run (eg. "GWBASIC MYPROG"), it temporarily calls a
small program CS.COM to help it know how much memory the program needs.
CS.COM must be in the current directory. Then the whole program and the
Basic Interpreter Terminates and Stays Resident.

     Take a print out of the base program (eg. "PRINT TSR.BAS") to refer to
while reading the following explanation of the program.

  i)  The first section consists of Basic commands executed before setting
up the TSR routine. These might be introductory statements, or setting up
variables for later use. You add all of this section ( at lines 6-6996 ).

 ii)  The second section consists of the commands to install the Machine
Language portion of the program into the GMMCKAY%() variable array. It also
sets up the Interrupts, which will recall the program, and then terminates
the program leaving it in memory. This is part of the base program - you
only change it to pick which Interrupts are called (this section is at
lines 7000-9060).

iii)  The third section is the program you input which acts when called by
the Interrupts. This program can look at which of the three possible
Interrupts recalled the program and act accordingly. (line numbers 10002-
19996).

 iv)  The fourth section ends the TSR routine and returns control back to
the program that was operating when the Interrupt transfered control to
your program. In doing this, it is careful to make sure that all of the CPU
registers and the stack are exactly as they were (which is how the original
program expects them to be). You have a choice of ways of returning to the
original program - you can transfer control to the routine that the
Interrupt would have called if you had not put in your Interrupt routine
(eg. a keyboard examining routine must continue with the expected routine
to process keystrokes), or you can return control directly, bypassing the
expected routine. This section is at lines 20000-20100.

  v)  The last section is a series of data statements which make up the
machine language program (line 30998-31059).

3.2                         QUICKBASIC Compiled

     The form of a program compiled with QuickBasic is similar to the
GWBasic case except the base program is TSRQUICK.BAS (not TSR.BAS). You add
your own lines and compile it as a stand alone program (eg. MYPROG.EXE).
When run, it temporarily calls CS.COM which must be in the current
directory, and then the whole MYPROG.EXE becomes a TSR. This program is
designed for QuickBasic version 4.0 (different versions of QuickBasic are
not compatible and reflect how Basic has evolved over time eg. version 2.0
does not work with this routine)

     Do not use the program in the QuickBasic environment, but only
compiled as a stand alone program. Start QuickBasic with the /LQB switch to
allow it to call machine language routines - QuickBasic files QB.LIB and
QB.QLB must be in the current directory.

     The structure of TSRQUICK.BAS is the same as items i) to v) in the
GWBasic section (see chapter 3.1) - print out a copy of TSRQUICK.BAS (eg.
PRINT TSRQUICK.BAS), and read items i) to v).

3.3                               QBASIC

     This is only included to add some ability to use QBasic - it is not
recommended. You initialised the TSR by running TSRQB.EXE, which installs
itself as a small TSR. When TSRQB.EXE is activated by pressing the "Prt
Scrn" key, it issues the command "QBASIC.EXE /RUN \TEST.BAS" which loads
QBASIC and TEST.BAS into memory (if there is enough room - you need approx
300Kb). This means that QBASIC.EXE must be in the current directory or in
your PATH (which it usually is) and your program (which must be called
TEST.BAS) must be in the root directory of the drive you are in when the
"Prt Scrn" key is pressed. The TEST.BAS program can have any form you want
(ie. there is no base program).

     Because of QBasic's memory management, this routine can only be
activated by "Prt Scrn" when another program is running, ie. not when you
are at the DOS prompt. If you press the "Prt Scrn" key when at the DOS
prompt, it will not activate and will also remove the program's ability to
be called at all - you will have to run TSRQB.EXE again (for those
interested, the technical reason for this is that all these TSR programs
have anti-nesting checks, ie. you cannot call the TSR from within the TSR -
the abnormal termination occurring when the "Prt Scrn" key is pressed from
the DOS prompt sets this anti-nesting check to permanently on and so it
resists any attempt to call it).










4. SPECIFIC PROGRAM USE :



     As discussed earlier, separate programs are provided for GWBasic and
compiled QuickBasic - this reflects the subtle differences in the Basic
language dialects - particularly the format for calling machine language
routines. The structure of the QBasic routines is very different.

4.1                      BASIC , BASICA , GWBASIC

                            program section i).

     Section 7 of this manual contains a checklist to make sure that the
program is set up correctly to run as a TSR. However you must ensure that
the portions of the program that you have added, do want you want them to.
Debugging the program in its final form is extremely tedious as after it is
run once and installed as a TSR, it cannot be removed, and you cannot enter
GWBasic again. (If you are running with a QuickBasic compiler, you cannot
enter Basic again, but you can install as many TSR's as will fit in the
memory.) To remove it from memory to alter it, you must re-boot the
computer (Ctrl-Alt-Del). So it is very important to write the initial Basic
program - section i) line numbers 6-6996 - and the routine which runs as a
TSR - section iii) line numbers 10002-19996 - as a normal Basic program,
fully debug it, save it in ASCII format (eg. SAVE "MYPROG",A ), then merge
the TSR setup program into it.

     Make sure all variable names which are used in the TSR section of the
program (section iii) are referred to here.

                           program section iii)

     In writing your routine to execute as a TSR when called - section iii)
line numbers 10002-19996 - you can set it up so that it behaves differently
depending on which Interrupt was called to transfer control to your TSR.
You may set a maximum of 3 Interrupts - so you can have the TSR doing the
job of 3 TSR's. If the first Interrupt (specified in line 7520) is
called,the variable GMMCKAY%(600) is set to 1. If the second Interrupt
(specified in line 7620) is called , GMMCKAY%(600)=2. Similarly the third
Interrupt (line 7720) sets GMMCKAY%(600)=3. You can use this variable to
alter the routine run and the mode of exiting, but remember that whichever
Interrupt causes the TSR to operate, it will start running at line 10000.
In this section do not change the value of any of the GMMCKAY%() array ,ie.
you can read them but do not change them.

     If you call any graphics functions (eg. CIRCLE or PSET), Basic must
have been told that a graphics screen is in operation (it is not good
enough that the current screen mode when the TSR is recalled actually is a
graphics screen). The usual place for this is in program section i) (if
leaving a graphics screen in place when the program terminates and stays
resident is OK), or in program section iii). This command would usually be
something like " SCREEN 9 ". Even when all of this has been done correctly,
the effect that you want will not always happen - if the screen in
operation at the time of the TSR recall is a text screen the graphics
operation will not be carried out (but the program will not bomb), if it is
a graphics screen then it may or may not work depending on the type of
screen and whether it is compatible with the BASIC SCREEN command or not.

     If you use the random function "RND" in the TSR you will find that it
always gives the same number. The reason for this is that it does not
recognise previously called "RANDOMIZE X" commands, so gives the same
"random" number each time. To overcome this the "RANDOMIZE X" command must
be in the TSR, but this presents a problem as "X" cannot be a constant. You
can use "RANDOMIZE TIMER", except when the timer Interrupt (number 28) is
the Interrupt which recalls the TSR. However if Interrupt 28 does recall
the TSR, the best that can be done is the line from the DEMO2.BAS program :
               RANDOMIZE CSRLIN ^ 1.2 * POS(0) ^ 2.4

     Do not introduce any new variable names which have not been introduced
before in this section. If you want to use a new variable, set it to a
dummy value before line 6996 (in the introduction non-TSR part of the
program) so that the program can recognise it as a variable and allow
memory space to store it before becoming a TSR, 
     eg.       1000 NEWVAR%=0

     If you want to print onto the screen, remember that BASIC keeps track
of its own cursor position (not where the cursor really is). This means
that printing may not start at the position of the cursor on the screen.
See DEMO4.BAS in chapter 6 for an easy way to get around this. After you
stop printing, DOS and BASIC will agree on the cursor position.

     The COLOR command will not affect the current colour after returning
from the TSR.

     "ON ERROR" routines in Basic, BasicA, GWBasic programs work as long as
they are initialised each time the TSR is called, ie. have the line "ON
ERROR GOTO 50000"  as the first line of the TSR section. It is not good
enough to have it in the setup part of program (an exception here is
QuickBasic compiled programs which may be initialised in the program
setup). Of course after an error has been trapped the TSR must be exited in
the standard way.

     The key to TSR programs is to leave everything as you found it - this
is part of the cleverness of the TSR_IN_BASIC program, but it also applies
to your part of the program. You may encounter problems if you change the
screen mode or open or close files (remember that the foreground program
may have already open a file with the file number you want to use).

                            program section ii)

     To run with the GWBasic Interpreter use TSR.BAS as the base program.
To run compiled in QuickBasic, use TSRQUICK.BAS. 

     Merge your program with the setup program

eg.       GWBASIC
          LOAD "MYPROG.BAS"
          MERGE "TSR.BAS"
          SAVE "FINAL.BAS",A

If you have used the correct line numbers, section ii) will have slotted
between the sections i) and iii) you wrote (with QuickBasic you will have
to move these sections to the correct place yourself). You may now
carefully edit section ii) to tell it which Interrupts you want called (see
the list of useful Interrupts in chapter 5). Note the Interrupt numbers
referred to here are decimal numbers, if you are used to dealing with
Interrupts you will know that they are usually referred to by their
hexadecimal number, however decimal is used exclusively here for the sake
of simplicity - Ctrl Break interrupt = 27 = 1B hex.

     Set the first Interrupt at line 7500-7540, the second at line 7600-
7640, and the third at line 7700-7740. Remove the " ' " symbol at the start
of lines 7600 - 7640 if you want to use the second Interrupt, and at lines
7700 - 7740 if you want to use the third Interrupt. Leaving the " ' " in
place means that the line is a comment line and will not be acted upon, so
leave them in place if you only want one Interrupt called. Only call
Interrupts that you are familiar with, otherwise don't be surprised when
the computer locks up. The Interrupt numbers are set in the GMMCKAY%(598)
variable, eg  GMMCKAY%(598)=5 calls Interrupt 5.   Leave GMMCKAY%(597) =
1,2, or 3.

                            program section iv)

     You may now edit the fourth section to decide whether you want to exit
by :

     1.  continuing the Interrupt routine that would have been called if
         your routine had not hijacked control of the Interrupt.
   or

     2.  return immediately to the calling program.

If you want option 1. include the line
          20000 GMMCKAY%=437
in the exit routine.

If you want option 2. include the line
          20000 GMMCKAY%=551
in the exit routine.

     It is permissible for the mode of exit to be decided within the
program. Both the following examples illustrate this.

A.   20000 IF TIME$>"12:00:00" THEN GMMCKAY%=437 ELSE GMMCKAY%=551

or

B.   20000 IF GMMCKAY%(600)=1 THEN GMMCKAY%=437
     20001 IF GMMCKAY%(600)=2 THEN GMMCKAY%=437 ELSE GMMCKAY%=551
          (remember that GMMCKAY%(600) is set by a TSR_IN_BASIC routine to
tell us which Interrupt caused the program to activate)

     Ensure that under all circumstances the routine is exited with
GMMCKAY% set to either 437 or 551. DO NOT exit by STOP , END , SYSTEM , or
"just running through the routine".

                            program section v)

     Do not change this part of the program (lines 31000-31055). If you
want to add your own DATA statements for other READ routines, ensure that
they are exactly finished so that the TSR routine at line 7340 reads the
correct data statements starting at the first element at line 31001 - any
slight deviation could lock up the computer.



4.2                         QUICKBASIC Compiled

     The steps to follow are the same as for GWBasic in 4.1 remembering to
use the base program TSRQUICK.BAS. Debugging is easier to do in the
QuickBasic environment - but only if you fully understand the structure of
the program and do not run a machine language part of the program until it
is completely debugged and compiled.

     If you want to make your compiled program smaller, there is some scope
to do this by using LINK's built in features, eg once your .OBJ file has
been created try manually creating the .EXE file with

               LINK MYPROG+QB.LIB/CP:1/ST:500

This will run without problems as long as you have not got a complicated
program which needs a lot of storage space for variables. It may be reduced
to half the size of the usual .EXE program.

     Read section 4.1  i) to v)


4.3                               QBASIC

     As neither the QBasic Interpreter nor your own program (TEST.BAS) is
actually run as a TSR, but merely called into memory by a TSR, the base
program is very easy to write and debug. It may have any form you wish -
remembering only that other programs will be running so conflicting with
them is possible. End the program with the "SYSTEM" command to exit QBasic.

     Remember that your QBasic program must be called TEST.BAS and be in
the root directory of the drive you are in when the "Prt Scrn" key is
pressed.

     The key to TSR programs is to leave everything as you found it - this
is part of the cleverness of the TSR_IN_BASIC program, but it also applies
to your part of the program - you may encounter problems if you change the
screen mode or open or close files (remember that the foreground program
may have already opened a file with the file number you want to use).










5. INTERRUPTS :



     As discussed previously, Interrupts are an integral part of DOS,
designed to allow compatibility between different versions by setting easy
to find pointers to certain defined routines. There are up to 128 of these
pointers, but only a few which may be profitably called to run our Basic
TSR's. These Interrupts are listed here with their decimal number.

  No.   Activated                     Action
           by
 ---   ----------                   ----------
  5    pressing      If the printer is turned on, the screen is
       Prt Scrn      printed (if it is a graphics screen, GRAPHICS.COM
         key         must have been run). If the printer is turned
                     off there is no action.

  9    pressing      Examines the key pressed and passes control
         any         to Interrupt 22 to act on the key.
         key

  27   pressing      It activates the Ctrl Break routine to
        Ctrl         terminate programs. It transfers control
        Break        to the DOS response at Interrupt 35 (which
       (Pause)       cannot be used here as it is reset after
         key         each program terminates).

  28  computer's     Updates parameters like Basic's TIME$ and
      internal       DOS's TIME and DATE. It is activated 18.2
       clock         times per second.

     There are many other Interrupts which may be called, but if you call
them without knowing exactly what they do, you can expect to be resetting
your computer often.

     Interrupt 27 can readily be used to transfer control to a routine
Compiled by QuickBasic, but NOT by a Basic , BasicA , GWBasic , or QBasic
Interpreted program as these have their own Ctrl Break routines.







6. DEMONSTRATIONS :



     Included with this software are some demonstration programs which
illustrate how to use TSR_IN_BASIC. Examine them carefully and understand
how they work before writing your own programs. 

     DEMO1.BAS, DEMO2.BAS, DEMO3.BAS, DEMO4.BAS and DEMO5.BAS are written
for GWBasic, BasicA, or Basic so enter :

          GWBASIC DEMO1.BAS
     or   GWBASIC DEMO2.BAS
     or   GWBASIC DEMO3.BAS
     or   GWBASIC DEMO4.BAS
     or   GWBASIC DEMO5.BAS

     DEMO6.EXE is written and compiled using QuickBasic. The .BAS source
code is included in the package you will receive on registration. To run
it, enter from the DOS prompt :

          DEMO6


     Remember that only one GWBasic program can be in memory at the one
time - so between running different programs, you will have to reboot
(Ctrl-Alt-Del) to remove it from memory. After installing each program you
cannot enter Basic or run a QuickBasic compiled program without rebooting.



                                 DEMO1.BAS

     DEMO1.BAS installs a routine which is recalled by pressing the Prt
Scrn key (Interrupt 5). It is a very simple demonstration of a TSR_IN_BASIC
routine.

line    1-6999   = introductory routine.
line 7425-7760   = points to Interrupt 5 as the only Interrupt called
line 9999-19999  = the TSR routine which prints a message and the
                   time. It then asks whether you want to continue
                   with the Prt Scrn routine or not (turn on the
                   printer to see the difference).
line 20000-20100 = exits the TSR.

     Once installed this can be recalled as many times as you want to press
Prt Scrn (except when the routine is "nested" ie. while the TSR is
operating and has control of what the computer is doing, a Prt Scrn does
not restart the TSR routine - you have to wait until the TSR no longer has
control before the TSR can be called again).


                                 DEMO2.BAS

     This program is called by pressing the Prt Scrn key and is also called
by the timer Interrupt (18.2 times per second). It is a demonstration of
how the one program can do the same job as two separate TSR's, ie. it
behaves totally differently depending on which Interrupt activated it.

line     1-6999  = introductory routine.
line  7425-7760  = sets up calls to Interrupt 5 and 28.
line  9999-19999 = the TSR routine which prints a "print screen"
                   message if the Prt Scrn key is pressed, and moves
                   the cursor to a random position on your screen if the
                   timer Interrupt is called.
line 20000-20100 = exits the TSR.

     The cursor is moved to a random point on the screen for each character
input, but DOS still accepts the input as a normal command (as if no one
had been monkeying with the cursor).


                                 DEMO3.BAS

     This program is run from Basic, BasicA, or GWBasic. It demonstrates
that screen manipulation is possible, despite the fact that when a
TSR_IN_BASIC routine is recalled it may not be aware of what the screen is
displaying at that time. After installing the program, you can recall it by
pressing the "Prt Scrn" key. If the screen is in TEXT mode (not GRAPHICS),
DEMO3.BAS swaps alternate lines on the screen. Press the "Prt Scrn" key
again to see the lines swap back. It works by directly accessing the
EGA/VGA TEXT screen memory at address 4B80:0000 for colour monitors
(4B00:0000 for monochrome monitors). (If you are not familiar with memory
addresses - the address 4B80:0000 is expressed in hexadecimal with 4B80
being called the segment address and 0000 being the offset address - this
refers to the memory byte 4B80hex*10hex+0000hex=4B800hex from the start).

line     1-6999  = introduction routine. Memory double byte at address
                   0040:0063 (hex) records if it has a colour or mono
                   monitor and sets MYVAR1% to the appropriate video
                   segment address.
line  7000-7760  = sets up call to Interrupt 5.
line  9999-19999 = TSR program. MYVAR4% looks at memory 0040:004E (hex) to 
                   see the offset address of the video page currently being
                   displayed. Thus the video memory can be read starting at
                   MYVAR1%:MYVAR4%. Each character is stored as 2 bytes -
                   the ASCII value, followed by the colour, so 80
                   characters per line equates to 160 bytes per line.
line 20000-20100 = exit the TSR without continuing the Prt Scrn routine.


                                 DEMO4.BAS

     This program is a simple demonstration of how your TSR_IN_BASIC can
recognise where the current cursor position is. It is recalled by the timer
Interrupt (number 28) 18.2 times per second, but only reacts after 182 of
these clock ticks (ie. 10 seconds). It reacts by reading the current cursor
position from the BIOS variable stored in memory at address 0040:0066, and
putting a box around it. It then returns to that cursor position. The TSR
finishes by continuing the Interrupt 28 call to any other functions which
may use it.

line     1-6999  = introductory routine, variables initialised.
line  7425-7760  = sets up call to Interrupt 28
line  9999-19999 = the TSR routine which keeps track of the clock ticks,
                   reads the cursor position, changes colour, puts a box
                   around the cursor, and restores the cursor position.
line 20000-20100 = exits the TSR to other timer functions.




                                 DEMO5.BAS

     DEMO5 shows how programs can be recalled by the function keys (or any
key you can trap using Basic). This program tells you when you have pressed
the F1, F2, or F3 keys by printing a message at the top of the screen.

     The ON KEY(1) statement is used in the program set up section, but the
Basic Interpreter will only react to it when it is actively looking for it.
So the TSR has to be activated to allow it to see if the key has been
pressed. This is done in this program by being recalled by the Timer
Interrupt 18.2 times per second. If the ON KEYs have not been pressed the
TSR exits immediately - you are not aware that it had been activated and
minimum time is spent in the routine. Programs that you run after
installing DEMO5.BAS may trap these same function keys, so deactivate your
routine.

line     1-6999  = introductory routine, ON KEY routines set up.
line  7425-7760  = sets up call to Interrupt 28
line  9999-19999 = the TSR routine exits immediately. This section also
                   contains the subroutines executed by the ON KEY GOSUB
                   command.
line 20000-20100 = exits the TSR to other timer functions.



                                 DEMO6.EXE

     DEMO6.EXE was written for QuickBasic and was then compiled into a
stand alone .EXE executable file. The same code that was used to produce
DEMO6.EXE may have been used to give a GWBasic format.

     The program is activated by typing           DEMO6
from the DOS prompt. On installation it asks you which keyboard key you
want trapped (A-Z). DEMO6 then installs itself to be recalled by Interrupt
9, which means that it inspects the keys that the keyboard says that you
have pushed. Whenever it comes across the key that you have nominated it
converts it from upper case to lower case (or vice versa). Typically, this
does not affect the operation of DOS at all, but makes an interesting
effect. Press the "Prt Scrn" key to choose a different key to trap.

     The routine also beeps through the PC speaker when the "space bar" is
pressed.

     This routine does not use the ON KEY routine (as is used in
DEMO5.BAS), but is recalled directly by the action of pushing a key. This
means that it does not slow the computer down slightly, as DEMO5.BAS does.
It also means that every key stroke is examined, not just certain trapped
keys.




7. CHECK LIST :


     This is a final check list to ensure that your program has the maximum
chance of working. Take a hard copy of either this instruction file or your
Basic program and go through this list point by point.

7.1                        BASIC,BASICA,GWBASIC

i).  Your introduction routine must be between line numbers 6 and 6996 and  
     must be debugged.

ii). Your routine to run as a TSR must be between line numbers 10002 and    
     19996 and be debugged.

iii).Have you chosen the correct Interrupts to call at line numbers 7000 to 
     7760 ?

iv). Is the exiting variable GMMCKAY% at line 20000 set to 437 or 551 under 
     all possible circumstances ?

v).  No GMMCKAY%() array variable must be changed at any stage other than
     is specified in the base program.

vi). Was TSR.BAS used as the base program ?

vii).Ensure the TSR routine (lines 10002-19996) does not introduce any new  
     variables which have not been mentioned before.

iix).Make sure TIME$ and DATE$ are not referenced if the TSR is recalled by 
     Interrupt 28.

ix). If you use a "SHELL" command in the TSR part of the program, this will
     only work if the TSR is recalled while a program is running - not from
     the DOS prompt.

x).  If you are using a graphics function, the SCREEN command should be
     used to set the graphics screen eg. in the initial set-up part of the
     program.


xi). If you use the "RND" function in the TSR, "RANDOMIZE X" should also be
     in the TSR.

xii).If you have added your own data statements, they must be exactly
     finished so the READ at line 7340 works correctly.

xiii.There must be enough room in memory to run the TSR (this is not        
     usually a problem, but enough room in memory to run whatever
     application you like after the TSR is installed may be a problem).

xiv).Save the program (preferably in ASCII format) before running it.

xv). CS.COM must be in the same directory that you are operating from.


7.2                         QUICKBASIC COMPILED


i).  Your introduction routine must be between line numbers 6 and 6996 and  
     must be debugged.

ii). Your routine to run as a TSR must be between line numbers 10002 and    
     19996 and be debugged.

iii).When merging files in QuickBasic, remember that line numbers do not
     automatically order themselves as happens in GWBasic. Ensure that
     sections i, ii, iii are manually placed in the correct order, so that
     all line numbers are sequential.

iv). Have you chosen the correct Interrupts to call at line numbers 7000 to 
     7760 ?

v).  Is the exiting variable GMMCKAY% at line 20000 set to 437 or 551 under 
     all possible circumstances ?

vi). No GMMCKAY%() array variable should be changed at any stage other 
     than is specified in the base program.

vii).Was TSRQUICK.BAS used as the base program ?

iix).Ensure the TSR routine (lines 10002-19996) does not introduce any new  
     variables which have not been mentioned before.

ix). Make sure TIME$ and DATE$ are not referenced if the TSR is recalled by 
     Interrupt 28.

x).  If you use a SHELL command in the TSR part of the program, this will
     only work if the TSR is recalled while a program is running - not from 
     the DOS prompt.

xi). If you are using a graphics function, the SCREEN command should be    
     used to set the graphics screen eg. in the initial set-up part of the  
     program.

xii).If you have added your own data statements, they must be exactly
     finished so the READ at line 7340 works correctly.

xiii.There must be enough room in memory to run the TSR (this is not
     usually a problem, but enough room in memory to run whatever
     application you like after the TSR is installed may be a problem).

xiv).Save the program (preferably in ASCII format) before running it.

xv). CS.COM must be in the same directory that you are operating from.

xvi).QuickBasic must be started with the /LQB switch eg.

                              QB MYPROG /LQB

xvii.The program must be compiled as a stand alone .EXE program using
     QuickBasic Ver 4.x before running it.


7.3                               QBASIC

i).  Ensure your QBasic program has been debugged.

ii). The program should end with "SYSTEM".

iii).Your QBasic program must be called TEST.BAS and be located in the root
     directory of the drive you will be in when the "Prt Scrn" key is
     pressed.

iv). CS.COM must be in your current directory.

v).  Enough memory must be available to call QBasic into memory on pressing
     the "Prt Scrn" key.

vi). Remember that once you install TSRQB.EXE , you should only press the 
     "Prt Scrn" key when a program is running (not at the DOS prompt).





8. REGISTRATION :

     This program is distributed under the Shareware system, which means
that you are expected to register it if you have a use for it. As a further
incentive to register, I will send you :

          i)  a registered copy of the latest version.

         ii)  a full description on how to use the keyboard
              interrupt to call your TSR programs using "hotkeys".

        iii)  documentation and explanation of the machine language
              programs called by the TSR_IN_BASIC routines.

         iv)  the latest version of the popular FIVE HUNDRED CARD GAME
              software (which uses mouse control) . 

          v)  the latest version of the COPY_DIR program - a file copying
              utility which allows you to copy large directories onto
              multiple different sized floppy disks.

     You are obviously a keen BASIC programmer to use this program, and you
know the benefits of the Shareware distribution system to you. Remember
also that it is an honour system and should be of benefit to the author as
well. You must register it if you wish use it. If you are impressed enough
to want to distribute programs based on TSR_IN_BASIC (whether commercially,
by Shareware, or by Public Domain), you must register your copy, obtain my
written permission, and acknowledge TSR_IN_BASIC in your distribution. I
would also appreciate feed back on the successes and failures of the
program - being an early version, I am sure that there are going to be
problems that I haven't ironed out.


---------------------------------------------------------------------------

                               TSR_IN_BASIC

        Name:     _________________________________  Date: ____/____/____

        Address:  _______________________________________________________

        City:     _______________________  State: _____  Code: __________

        Country:  _______________________

        Version:  _2.1__  My Copy From: ______________________

        Computer: ________________   Floppy (eg. 1.44MB,1.2MB): _________

        Type of Basic used:  ________________

        Registration . . . . . .  $----- ($20)
        Latest version + Extras   $----- ($5)
                           total  $----- ($25)

                I will be grateful for any suggestions, comments, or
        information on problems with the program you may have. 


---------------------------------------------------------------------------

        SEND THE FORM TO:
                              G.M.McKAY
                               29 Melissa St.
                                Strathmore
                                 Victoria , 3041
                                  Australia


