
╔════════════════════════════════════════════════════╗
║    ASSEMBLY-LANGUAGE TOOLBOX FOR MICROSOFT BASIC   ║
╟────────────────────────────────────────────────────╢
║   This is a library of machine code routines that  ║
║   can be called from your QuickBASIC programs to   ║
║   perform a number of useful functions. To use it  ║
║   you should select those procedures your program  ║
║   requires from the TOOLBOX.DEF definition file,   ║
║   and then link the source code with TOOLBOX.LIB   ║
║   after it has been compiled.  Note that the same  ║
║   functions are also available in a Quick Library  ║
║   TOOLBOX.QLB, which can be used when trying out   ║
║   your programs in the QuickBASIC environment.     ║
╚════════════════════════════════════════════════════╝


The TOOLBOX.LIB procedures which you intend to call
should be declared at the beginning of your program.
A complete set of prototype DECLARE statements is
contained in the file TOOLBOX.DEF which is supplied
with this package.

This edition contains the following functions and
procedures:







┌────────────────────────────────────────────────────┐
│             Change background colour.              │
└────────────────────────────────────────────────────┘

This procedure changes the display attributes of the
characters contained within the screen rectangle you
specify, without overwriting the text itself.

DECLARE SUB BackFill (R%, C%, H%, W%, A%)

R% = Top-left row of the rectangle to be coloured.
C% = Top-left column of the rectangle.
H% = Height of the rectangle in rows.
W% = Width of the rectangle in columns.
A% = Display attribute to use for colouring.


┌────────────────────────────────────────────────────┐
│            Get or set CAPS LOCK state.             │
└────────────────────────────────────────────────────┘

Toggles CAPS LOCK on or off or, alternatively, reads
the current CAPS LOCK key setting.

DECLARE FUNCTION CapsLock% (BYVAL Switch%)

Switch% = 0  Turns CAPS LOCK off
        = 1  Turns CAPS LOCK on

Any other value just returns the current CAPS status.


┌────────────────────────────────────────────────────┐
│        Encipher or Decipher a string of text.      │
└────────────────────────────────────────────────────┘

This routine requires that you supply two strings of
characters. The first is the text to be encrypted, and
the second is one or more keywords which are used to
encipher the text. Thereafter, the text cannot be
decrypted until you supply the same key string again.

DECLARE SUB Cipher (Text$, KeyWord$)

The encryption algorithm XORs (eXclusive ORs) the key
string with string to be encrypted. This allows you to
reverse the procedure and decrypt the text, simply by
calling the routine a second time.

┌────────────────────────────────────────────────────┐
│    Clear to end of the current line or display.    │
└────────────────────────────────────────────────────┘

Blank spaces of the display attribute specified are
printed, starting at the current cursor position and
continuing to the end of the line or, optionally, to
the end of the screen.

DECLARE SUB ClearEnd (BYVAL Switch%, BYVAL Attr%)

Switch%   0 = clear to the end of the line.
          1 = clear to the end of the screen.



Attr%     display attribute (1 - 255). If zero is
          specified then the attribute of the
          character under the cursor is used.

Example:  ClearEnd 1, 0

Clears from the current cursor position to the bottom
of the screen. The area cleared takes the background
colour of the character under the cursor. The cursor,
itself, is not updated.





┌────────────────────────────────────────────────────┐
│               System-independant pause.            │
└────────────────────────────────────────────────────┘
This procedure is like the QuickBASIC SLEEP statement,
except that it allows you to specify an interval in
seconds and fractions (accurate to 1/18 sec.) instead
of just whole seconds. The delay will be exactly the
same on a 4.77 MHz original IBM-PC as it would be on
the latest 33 MHz 80486 machine.

DECLARE SUB Delay (Seconds!)

Possible values for Seconds! are between .05 and 1800.

See the PAUSE routine (below) for a similar procedure
which allows you to specify a delay in PC clock ticks.


┌────────────────────────────────────────────────────┐
│      Return current BIOS video mode number.        │
└────────────────────────────────────────────────────┘

Reads the current video display mode using the IBM ROM
BIOS numbering system.

DECLARE FUNCTION DisplayMode% ()

The ScreenMode% function can be used to return the
equivalent QuickBASIC SCREEN mode number.



┌────────────────────────────────────────────────────┐
│        Return current video display page.          │
└────────────────────────────────────────────────────┘

All video cards except the Monochrome Display Adaptor
(MDA) are capable of switching between two or more
pages of display memory. This function returns the
number of the current video page, use the QuickBASIC
SCREEN statement to select the page you require.

DECLARE FUNCTION DisplayPage% ()

Page Number can be a value between 0 and 7, depending
upon the current video mode and the amount of display
memory installed.


┌────────────────────────────────────────────────────┐
│    Get current Operating System (DOS) version.     │
└────────────────────────────────────────────────────┘

The version is returned as a string in the form "3.20"
(for DOS 3.2) and also in a pair of numeric variables,
with MAJOR% holding the  Major version number (3), and
MINOR% holding the Minor version number (20).

DECLARE FUNCTION DosVersion$ ()

Example:      DOS$ = DosVersion$

This function does not require any calling parameters.

┌────────────────────────────────────────────────────┐
│      Fast String Output to the Video Display.      │
└────────────────────────────────────────────────────┘
This procedure can be used to display a string of text
directly to video memory.  It is much  faster than the
normal DOS services and does not update the cursor.

DECLARE SUB FastPrint (Row%, Col%, Message$, Attr%)

Row%        is the row where printing is to start.
Col%        is the column where printing is to start.
Message$    is the string of text to be printed.
Attr%       is the video attribute given to the text.

Row% and Col% follow the usual convention of numbering
screen rows from 1 to 25 and columns from 1 to 80.

┌────────────────────────────────────────────────────┐
│                  File Finder.                      │
└────────────────────────────────────────────────────┘

FINDFILE$ is a mixed QuickBASIC and assembly function,
which helps you locate a particular file, on any drive
or in any directory of the system. It will accept wild
card characters as part of the pathname to search,  in
which case the function will report all matching files
and allow you to select one from the list.

DECLARE FUNCTION FindFile$ (FileSpec$)

FILESPEC$ can contain drive identifier, directory path
legal filenames and the wildcard characters * and ?


Example:   Path$ = FindFile$("B:\DATA\*.DAT")

On entry, FILESPEC$ should contain the pathname to be
searched. If the pathname is ambiguous the function
presents a directory listing, in a popup window, of
all files which match and allows the user to select
the actual one required. If the pathname is explicit,
the procedure just checks if it actually exists. On
return, FINDFILE$ contains the full pathname of the
required file, or a null string if it was not located.




┌────────────────────────────────────────────────────┐
│                   System Flags.                    │
└────────────────────────────────────────────────────┘
These flags are situated in the Intra-Application
Communications area, an area reserved by DOS for user
programs to signal to each other.

DECLARE FUNCTION GetFlag% (Flag%)

Returns the current setting of the flag specified.

DECLARE SUB SetFlag (Flag%, Value%)

This routine is used to set one of the sixteen system
flags to a value of between 0 and 255. FLAG% is the
flag number (1-16), VALUE% is the value to set it to.
┌────────────────────────────────────────────────────┐
│           Context-sensitive Help system.           │
└────────────────────────────────────────────────────┘

Provides a context-sensitive on-line Help facility in
your QuickBASIC programs.

DECLARE SUB HelpMate (Context%, Topic$)

Context%  is the context-sensitive flag. If set to 1,
          then the routine attempts to load the file
          specified by ...

Topic$    A legal DOS filename (up to 8 characters
          without extension), specifying the name of
          the Topic file to be displayed.

If Context% is not set, (or Topic$ is a null string),
then the routine displays a list of topics, from which
you can make your own selection.

If  Context% is set,  HELPMATE will display the  first
page of the Topic file specified,  otherwise it begins
by  overlaying the current screen with a popup  window
on which is listed those HELP topics available.

The first topic in the list is highlighted and you can
move the highlight around the menu with the arrow keys
Highlight the topic you want,  then press the <RETURN>
key. The first page of that topic will be displayed in
the HELP window.


Page backwards and forwards through the file using the
<PG UP> and <PG DN> keys.  If you page past the end of
the file you will be returned to the topic list, where
you can either select another topic, or press <ESC> to
return to the Q-BASIC program. On return, the original
screen and all current variables are restored, intact,
and program execution will continue with the statement
following the procedure call.







┌────────────────────────────────────────────────────┐
│               Read Keyboard flags.                 │
└────────────────────────────────────────────────────┘

Returns a 16-bit unsigned number which is bit-encoded
with the current status of the CTRL, ALT, INSERT and
other keyboard control keys. See the KEYFLAGS topic
for a full description of the meaning of this value.

DECLARE FUNCTION KeyFlags% ()

See the CAPSLOCK, NUMLOCK and SCRLOCK functions for
a method of setting or reading the status of specific
control keys.


┌────────────────────────────────────────────────────┐
│        Clear the keyboard type-ahead buffer.       │
└────────────────────────────────────────────────────┘

This procedure flushes the keyboard type-ahead buffer
and discards any keystrokes which have not yet been
processed. 

DECLARE SUB KeyFlush ()







┌────────────────────────────────────────────────────┐
│               Wait for a Keypress.                 │
└────────────────────────────────────────────────────┘
Similar to the QuickBASIC INKEY$ function, except that
it waits for a keypress instead of returning at once
if none is available. 

DECLARE FUNCTION KeyIn% ()

The function returns a numeric value between 0 and 255
which represents the ASCII code of the key pressed. If
one of the function keys (F1 to F12) or a special key
such as PAGEUP or one of the cursor arrows is pressed,
then a negative value is returned. Converting this 
number to its absolute equivalent produces the scan
code of the key.

Example:  KeyPress% = KeyIn%
          IF KeyPress% < 0 THEN
             ScanCode% = ABS(KeyPress%)
          ELSE
             AsciCode% = KeyPress%
          END IF

See the ASCICODE topic for a list of ASCII codes and
their equivalent printable characters. The SCANCODE
topic lists the scan codes returned by the various
function and control keys.




┌────────────────────────────────────────────────────┐
│         Check if a key has been pressed.           │
└────────────────────────────────────────────────────┘

This function tests to see if a keystroke is waiting
to be read. It does not read or remove the keystroke 
from the typeahead buffer, use KEYIN% or INKEY$ to do
this.

DECLARE FUNCTION KeyStat% ()

KEYSTAT% returns -1 (logical TRUE) if a keystroke is
waiting to be collected or 0 (logical FALSE) if the
typeahead buffer is empty.


┌────────────────────────────────────────────────────┐
│          Translate numeric date to words.          │
└────────────────────────────────────────────────────┘

This function accepts a three-part numeric date and
transcribes it into a string, containing the date in
words. This includes the day of the week, which is
obtained by calling the MS-DOS internal time and date
services. 

DECLARE FUNCTION LongDate$ (Day%, Month%, Year%)

The function will reject illegal dates (ie. 29/2/89)
and returns a null string if one is presented.


┌────────────────────────────────────────────────────┐
│                Error Alert Window.                 │
└────────────────────────────────────────────────────┘

Displays an error message you supply in a popup window
and pauses execution until the user presses the <ESC>
key. The window is drawn in bright yellow characters
on a red background (inverse-video on mono displays).

DECLARE SUB MisTake (Message$)

Before returning, the procedure erases the window and
restores the screen to its previous state.



┌────────────────────────────────────────────────────┐
│               Test for Novell Network.             │
└────────────────────────────────────────────────────┘

This function is used to detect if the program which
calls it is running under a Novell Network. It can be
used to decide if file or record locking is required.

DECLARE FUNCTION NetTest% ()

Returns -1 (logical TRUE) if the Network shell is
present and 0 (logical FALSE) if not. Note that the
function cannot distinguish between programs running
on a local or network drive under NetWare.


┌────────────────────────────────────────────────────┐
│            Get or set NUM LOCK state.              │
└────────────────────────────────────────────────────┘

Toggles NUM LOCK on or off or, alternatively, reads
the current NUM LOCK key setting.

DECLARE FUNCTION NumLock% (BYVAL Switch%)

Switch% = 0  Turns NUM LOCK off
        = 1  Turns NUM LOCK on

Any other value returns the current NUM LOCK status.



┌────────────────────────────────────────────────────┐
│     Copy graphics display to and from a string.    │
└────────────────────────────────────────────────────┘
This procedure emulates the QuickBASIC PCOPY statement
which is available only on EGA and VGA monitors and
makes it available to computers fitted with CGA which
use SCREEN modes 1 and 2.

DECLARE SUB PageFlip (Buffer$, BYVAL Switch%)

Buffer$   The name of a string variable to hold the
          contents of the screen. It must be at least
          16384 bytes long or the routine will fail.

Switch%   1 = save graphics screen to the string.
          2 = Restore string contents to the screen.
┌────────────────────────────────────────────────────┐
│             Screen panels and boxes.               │
└────────────────────────────────────────────────────┘

This procedure is used to produce rectangular panels,
upon the video display, of various shapes and colours.
The calling program should supply the row/column co-
ordinate of the top left-hand corner of the required
panel, its height in rows and width in columns. You
should also specify the display attribute that the
panel will be displayed in and a switch to determine
if it should have a single or double-lined border.





DECLARE SUB Panel (R%, C%, H%, W%, B%, A%)

R% =  Top-left row of the panel to be drawn.
C% =  Top-left column of the panel.
H% =  Height of the panel in rows.
W% =  Width of the panel in columns.
B% =  Border type (1 = single line, 2 = double line).
A% =  Display attribute to use for colouring.

Note: specifying a border type other than 1 or 2 will
      produce a rectangle without borders.




┌────────────────────────────────────────────────────┐
│         Machine-independent timing loop.           │
└────────────────────────────────────────────────────┘

This routine is used to generate machine-independent
timing loops. It simply pauses until the specified
number of clock ticks have elapsed. 

DECLARE SUB Pause (BYVAL Ticks%)

There are 18.2 clock ticks per second on all PCs, no
matter what the processor or processor speed.




┌────────────────────────────────────────────────────┐
│                   Popup Windows.                   │
└────────────────────────────────────────────────────┘

What are Windows?  Well, if you've used the QuickBASIC
environment at all then you've used Windows. When you
press <ALT><F> to bring down the File Menu, the list
of options presented there is in a window. Notice how
any characters which were concealed when the File Menu
appeared, are restored, intact, after you've made your
choice. Windows are areas of the screen which are used
to hold transient data and messages to the user. They
make the most of the limited display space available
and remove the need to constantly rebuild the screen,
each time your program communicates with the world.


DECLARE SUB PopUp (Y%, X%, H%, W%, A%, B%, S%, Z%)

Opens a popup window at the screen location specified.

Where:    P1%  is the top-left row co-ordinate
          P2%  is the top-left column co-ordinate
          P3%  is the height (in rows) of the window
          P4%  is the width (in columns) of the window
          P5%  is the display attribute or colour
          P6%  is the border style (0 = no border)
          P7%  is the shadow switch (0 = no shadow)
          P8%  is the zoom switch (0 = no zoom)

DECLARE SUB ShutUp () closes the last window opened.

┌────────────────────────────────────────────────────┐
│              Printer Control Menu.                 │
└────────────────────────────────────────────────────┘
Most modern printers have a variety of useful styles
and fonts which you can select by setting dip switches
or sending the appropriate control codes from the
computer. Unfortunately this is not always convenient,
especially when you are in the middle of a program and
have to duck out to set up the proper print size.                  
                                                    
These utilities make font selection easy.

DECLARE SUB PrintEps (Attr%, Printer%)  Epson printers
DECLARE SUB PrintIBM (Attr%, Printer%)  IBM printers
DECLARE SUB PrintOki (Attr%, Printer%)  OKI printers
DECLARE SUB PrintTRS (Attr%, Printer%)  Tandy printers
┌────────────────────────────────────────────────────┐
│         Test the status of the Printer.            │
└────────────────────────────────────────────────────┘

DECLARE FUNCTION PrinTest% (Printer%)

Example:  Status% = PrinTest%(DaisyWheel%)
          IF Status% = 144 OR Status% = 208 THEN
             Ready% = TRUE
          ELSE
             Ready% = FALSE
          END IF
This function tests the current status of the parallel
printer specified. The value returned is tested as
follows :

   Bit     Wanted    Meaning
─────────────────────────────────────────────────────
    7        1       Printer not busy (0 = busy)
    6        0       Printer acknowledges
    5        0       Out-of-paper
    4        1       This printer selected
    3        0       I/O error
    2        0       Not used
    1        0       Not used
    0        0       Time-out occurred
─────────────────────────────────────────────────────
   90 Hex  144 (Decimal)

Note:     Some printers also set the acknowledgement
          bit. If so, the value returned will be 208
         (D0 Hex) instead of 144.
┌────────────────────────────────────────────────────┐
│       Return current QuickBASIC SCREEN number.     │
└────────────────────────────────────────────────────┘

Reads the current display mode, using the QuickBASIC
numbering system. See the entry for SCREEN in the
QuickBASIC Language Reference for a description of the
various screen numbers.

DECLARE FUNCTION ScreenMode% ()

The DISPLAYMODE% function (see above) returns this
same information using the ROM-BIOS numbering system.



┌────────────────────────────────────────────────────┐
│    Return number of rows on the current display.   │
└────────────────────────────────────────────────────┘

Returns the height of the current screen, in rows, as
set by the last WIDTH statement or when starting up
the QuickBASIC environment (default = 25).

DECLARE FUNCTION ScreenRows% ()

The number returned may be 25, 43 or 50, depending on
the capabilities of your display adaptor.




┌────────────────────────────────────────────────────┐
│  Return number of columns on the current display.  │
└────────────────────────────────────────────────────┘

Returns the width of the current screen, in columns,
as set by the last WIDTH statement.

DECLARE FUNCTION ScreenWidth% ()

Possible return values are 40 and 80 (default = 80).






┌────────────────────────────────────────────────────┐
│          Get or set SCROLL LOCK state.             │
└────────────────────────────────────────────────────┘

Toggles SCROLL LOCK on or off or, alternatively, reads
the current SCROLL LOCK key setting.

DECLARE FUNCTION ScrLock% (BYVAL Switch%)

Switch% = 0  Turns SCROLL LOCK off
        = 1  Turns SCROLL LOCK on

Any other value returns the current SCROLL LOCK state.



┌────────────────────────────────────────────────────┐
│               Selective Scrolling.                 │
└────────────────────────────────────────────────────┘
Scrolls the contents of a screen rectangle a specified
number of lines, blank lines of the background colour
specified are scrolled in to replace them. 

DECLARE SUB Scroll (S%, Y1%, X1%, Y2%, X2%, L%, A%)

S%  =  Scroll direction (0 = down, 1 = up).
Y1% =  Top-left row of rectangle to be scrolled.
X1% =  Top-left column of rectangle.
Y2% =  Bottom-right row of rectangle.
X2% =  Bottom-right column of rectangle
L%  =  Number of lines to scroll.
A%  =  Display attribute of blank lines scrolled in.
┌────────────────────────────────────────────────────┐
│            Return the size of a file.              │
└────────────────────────────────────────────────────┘

This function reports the size of file(s) which you
specify. The filename can include a directory path and
may be ambiguous, using the wildcard characters '*' or
'?'. SIZEOF returns the size of the file, in bytes or,
if more than one match is found, the total size of all
the files. 

DECLARE FUNCTION SizeOf& (FileSpec$)

If a size of zero is returned, the file does not exist
(at least not in the directory which is specified).

┌────────────────────────────────────────────────────┐
│               Status Line Message.                 │
└────────────────────────────────────────────────────┘

DECLARE FUNCTION StatusLine% (Message$)

This procedure displays the message supplied on the
bottom line of the display, prompts the user for a
keypress, waits until it is received and then returns,
restoring the screen to its former state. The  ASCII
value of the keypress is returned in the variable that
you assign to the function.




┌────────────────────────────────────────────────────┐
│                    Verify Box.                     │
└────────────────────────────────────────────────────┘

DECLARE FUNCTION Verify% (Row%, Prompt$)

This function opens a window, centered at the screen
row specified, in which is displayed a prompt supplied
by the caller. The routine adds a further Y/N prompt,
and then waits for a keypress. Only <Y/N> responses
(in upper or lower case) are accepted and the value
that is returned evaluates to Boolean TRUE (-1), if a
Y(es) response was entered, and Boolean FALSE (0) if
the reply was N(o). The screen is restored to its
previous state on exit from the function.

┌────────────────────────────────────────────────────┐
│    Test video capabilities of the host computer.   │
└────────────────────────────────────────────────────┘
This function calls the ROM-BIOS to check the type and
capabilities of the display adaptor fitted to the host
computer system. 

DECLARE SUB VideoMode (Colour%, MaxRes%, VideoRam%)

The three arguments return the following information:

Colour%   -1 = Colour adaptor  Indicates the presence
           0 = Monochrome      of a colour monitor in
                               EGA system. Returns -1
                               for CGA even if a mono
                               monitor is being used.

MaxRes%    highest SCREEN      Highest graphic screen
           resolution          which can be set. This
                               is the same as SCREEN
                               numbers in QuickBASIC.
                               MDA only uses SCREEN 0
                               and CGA 0, 1 and 2.
                          N.B. MaxRes% = 10 indicates
                               EGA with mono monitor.
                               This means SCREEN 9 can
                               NOT be used.

VideoRam%  in kilobytes        The amount of dedicated
                               video memory installed.
