Black Box 4/BlackBox.cdr/progbas/qb4tb520.arj/READ.ME

Text File | 1991-08-25 | 8.7 KB | 180 lines

             Assembly-Language Toolbox for QuickBASIC
             ────────────────────────────────────────

                       By Christy Gemmell


The fifth edition of the Assembly-Language Toolbox has many new features.
EMS support has been added with a full set of routines for reading and
writing to LIM 3.2/4.0 Expanded Memory. Other routines enable you to
control the DOS print spooler and, thanks to Neil Carter, it now has a
complete set of Mouse functions.

High-resolution graphics, a previously neglected area in the Toolbox, have
at last been tackled and this release provides facilities for scrolling,
panning, and controlling the intensity of graphics displays. The routines
for loading and saving high-resolution screens to disk files have been
rewritten in pure assembly-language and are, consequently, much smaller
and faster. In addition I have added routines for drawing and scaling
high-resolution text in any combination of colours that your video card is
capable of displaying. This includes computers fitted with CGA, MCGA, EGA
and VGA adaptors. Hercules graphics cards are not, as yet, supported.

As in previous releases, two versions of the Toolbox library are included.
The first, TOOLBOX.LIB, is intended for linking with stand-alone programs
which are run from the DOS command line. To do this you must first compile
your program using BC's /O switch, eg:

    BC /O YOURPROG.BAS;

where YOURPROG.BAS is, of course, the name of your program.

The resulting object file should then be linked to the library using the
version of LINK.EXE which came with your QuickBASIC compiler, viz:

    LINK YOURPROG,,,TOOLBOX.LIB;

This will produce an executable program, YOURPROG.EXE, which can be run
completely stand-alone, without the need for the QuickBASIC support module
BRUN45.EXE to be present at runtime. It can, therefore, be distributed
freely without the need for royalty payments.


TOOLBOX.QLB, the second version of the library, is used for developing
programs in the QuickBASIC environment. To load it, use the following
command when starting up QuickBASIC:

    QB YOURPROG /L TOOLBOX.QLB

Thereafter your program can call any of the Toolbox functions and
procedures, provided that it includes the appropriate DECLARE statements
at the beginning of its' code.

DECLARE statements are prototype descriptions of the SUB programs and
FUNCTION procedures which your program will call. The QuickBASIC compiler
uses them to determine the number of arguments that need to be passed and
how the routines are to be called. Once declared, a library routine needs
only to be named for it to be executed and becomes, in effect, an
extension to the QuickBASIC language.  To use the Toolbox FASTPRINT
routine, for example, add the following lines to your program:

DECLARE SUB FastPrint (BYVAL Row%, BYVAL Col%, Message$, BYVAL Attribute%)

FastPrint 25, 34, "Hello World!", 48

This will print 'Hello World!' at the centre of the bottom screen row,
using black characters on cyan background (assuming that you have a colour
monitor).  Notice that you don't even have to use a CALL statement to
invoke FastPrint and that the parentheses around the argument list are not
required.

DECLARE statements have another use when you are building stand-alone
programs with LINK.EXE. They tell the linker to attach only the modules
containing the declared library routines to your program, and no others.
This helps keep your .EXE files smaller by preventing them from being
burdened with unneccessary code. The file TOOLBOX.DEF contains a full set
of DECLARE statements for all the library routines on this disk. Just
paste the ones you need into your current program.

If you have been using a previous version of the Toolbox, please note that
many of the DECLARE statements for previously existing routines have been
changed. In particular, a number of arguments which were previously passed
by reference are now passed BY VALue. Others have been given additional
parameters. Before you link existing code to the new version of
TOOLBOX.LIB, you should check with TOOLBOX.DEF that your DECLARE
statements are still valid.

The \HELP subdirectory contains a number of ASCII topic files which are
used by DEMON.EXE, the Toolbox demonstration program, to provide context-
sensitive help. If you are copying the Toolbox package to your hard disk,
be aware that not all of these are visible to normal directory listings
(see the HELPMATE documentation for more information). You may also need
to set up a DOS environment variable to point to the subdirectory you
transfer the topic files to, otherwise DEMON may not find them, eg:

    SET HELP=C:\QB45\HELPTEXT

With this release I have also provided the source code for DEMON as a
guide to using Toolbox routines in your own programs. Feel free to copy
or modify any part of it as you see fit.


TOOLBOX.HLP is an on-line help database which includes full descriptions
of all Assembly and Mixed-Language functions in the Toolbox. It is fully
compatible with QH.EXE, the QuickHelp utility program supplied with all
recent versions of Microsoft languages (including the BASIC 7, C 6 and
MASM 6 Professional Development Systems). Alternatively you can append it
to the Microsoft Advisor help database supplied with your compiler and
access it directly from within the QuickBASIC or Extended QuickBASIC
environments. Do this by typing, from the DOS command line :

    COPY BAS7QCK.HLP /B + TOOLBOX.HLP /B     (for BASIC 7 PDS)

    COPY QB45QCK.HLP /B + TOOLBOX.HLP /B     (for QuickBASIC 4.5)

(Back up your original QuickHelp file before doing this, just in case
something goes wrong.)

Thereafter you will be able to obtain information on any Toolbox routine
by placing your cursor on any reference to it in your source code and
then pressing <F1> or clicking the right mouse button, just as you would
with any other QuickBASIC keyword. You will also be able to paste examples
and DECLARE statements from the Toolbox Advisor, directly into your
program.

This ShareWare version of the Assembly-Language Toolbox for QuickBASIC is
provided, free of charge, to any QuickBASIC programmer who can find a use
for it. You are encouraged to copy it, upload it to Electronic Bulletin
Boards or pass it on to friends, provided only that you make no charge for
doing so and that all the files on the disk are preserved intact. You may
freely include Toolbox routines in your own programs, both for private use
and for commercial distribution, without payment to me.

If you intend to use the Toolbox on a regular basis, however, I would ask
you to register your copy with me, the author. For a modest fee, this will
bring you a copy of the Professional version of the Toolbox, complete with
all the source code, object modules for building your own custom libraries
and many additional features. Registration also entitles you to a free
upgrade to Release 6 of the Toolbox, when it becomes available, and to
subsequent releases at a greatly reduced price. Full Hotline support is
also included, at no extra charge.

Christy Gemmell                                              February 1991

                ────────────────────────────────────────────

                    For more information contact:

James Kreyling      Club PC, 1217 Crescent Drive,
                    Smithfield, Va. 23430, U.S.A.

          Tel:      [phone]

Neil Carter         ARDEN SOFTWARE, 115/117 Barkby Road,
                    Leicester LE4 7LG, England

          Tel:      [phone]    Fax:    [phone]


┌──────────────────────────── F L A S H ! ───────────────────────────────┐
│                                                                        │
│    ASSEMBLY-LANGUAGE TOOLBOX FOR BASIC 7.1 PROFESSIONAL DEVELOPMENT    │
│                          SYSTEM NOW AVAILABLE                          │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Christy Gemmell, the author of this package, is also major author of the
definitive textbook on QuickBASIC programming, the QuickBASIC BIBLE, which
is published by Microsoft Press, in association with the Waite Group, at
£24.95 ($27.95 US) ISBN 1-55615-262-0. Its thousand pages are packed with
information, tips and example programs which you wont find anywhere else.
Look out for it in your local bookstore.

The Assembly-Language Toolbox for QuickBASIC is used by thousands of
programmers in Great Britain, Europe, the USA and Canada, Australasia and
Japan, to build fast and powerful QuickBASIC programs. It has been shown
at COMDEX and was featured in the November 1990 issue of BYTE magazine.