World of Shareware - Software Farm 2/wosw_2.zip/wosw_2/QBAS/QBTINY11.ZIP/QBTINY.DOC

Text File | 1992-07-28 | 24KB | 610 lines

                      The QBTiny Library                 page 1
                    =--------------------=
                          Version 1.1

       QBTiny  Copyright (c) 1992  Thomas G. Hanlin III



The QBTiny library replaces the default runtime library for
QuickBasic 4.x and PDS 7.x compilers. Using it can reduce the
size of your compiled programs to 20% of their original size.

QBTiny does not support floating point math, event trapping, or
several other BASIC features.  The differences between QBTiny
and the default support library are discussed in this manual.

The QBTiny collection is copyrighted and may be distributed
only according to the following rule:

   All QBTiny files must be distributed together as a unit in
   unmodified form.  No files may be left out or added.

You use QBTiny at your own risk.  It has been tested by me on
my own computers, but I will not assume any responsibility for
any problems it may cause you.  QBTiny is a complex library.
IT QUITE PROBABLY HAS SOME BUGS.  If you come across a problem,
please let me know about it, and I'll do what I can to fix it.

It is expected that if you find QBTiny useful, you will
register your copy. You may not use QBTiny routines in programs
that are intended for distribution unless you have registered.
Registration entitles you to receive the latest version of
QBTiny, complete with full source code in assembly language,
plus a special version of QBTiny for 80286 and later CPUs. The
asm code is designed for MASM 6.0 and may need modifications if
you wish to use it with OPTASM, TASM, or earlier versions of
MASM.  For information on registration, see REGISTER.TXT.  If
your copy of QBTiny is over a year old, it may be obsolete--
see WHERE.BBS for locations which have the current version.

This manual always refers to the default support library as
BCOM45.LIB, which is for QuickBasic 4.5.  If you are using a
different compiler, you will have a different support library:
  BCOM40.LIB    QuickBasic 4.0 (early release)
  BCOM41.LIB    QuickBasic 4.0 (later release)
  BCL70ENR.LIB  PDS 7.0 (normal default)
  BCL71ENR.LIB  PDS 7.1 (normal default)
Substitute the appropriate library for BCOM45.LIB.  Likewise,
when I say QuickBasic, I am also referring to PDS.

The QBTiny library is called QBTINY.LIB.  Registered QBTiny
owners also have QBTINYAT.LIB (for 80286-80486) and QBTINY3.LIB
(for 80386-80486).  The same procedure works for all of them.

                       Table of Contents                 page 2



 Overview and Legal Info ................................... 1

 What Is QBTiny? ........................................... 3

 How to Use QBTiny ......................................... 4

 Compatibility Issues ...................................... 5

 Statements Not Supported .................................. 9

 Crescent's P.D.Q. ........................................ 10

 Which Runtime? ........................................... 11

 Author's Notes ........................................... 12

 The Future ............................................... 13

                       What Is QBTiny?                   page 3



Microsoft's QuickBasic compiler turns your BASIC source code
into an executable (.EXE) file.  It does this by converting the
source code into assembly language.  The simplest statements,
like A% = A% + 1, are converted directly to assembly language.
It would be inefficient to convert more complex statements
directly to assembly language, though, since it would cause a
lot of duplicated code.  Instead of entering complex statements
directly into assembly language, the compiler generates a call
to a standard library routine which takes care of the work.
Most BASIC commands have their own library routines.  For
example, the ASC function causes a call to a library routine
named B$FASC (an abbreviation for Basic Function ASC).  When
you compile a QuickBasic program to a stand-alone .EXE, it
normally uses the BCOM45.LIB library to supply the proper
support code.  The QBTINY.LIB library replaces this.

The first question that might pop into your mind is, why bother
with replacing the default library to begin with?  It's free
with the compiler and seems to work just fine as-is!

Well, the problem with the default library is that it was
developed over a period of many years by many people.  As you
might expect, this is not a particularly efficient way to make
a library-- there are routines in BCOM45.LIB which are never
even called any more!  The modularity of the routines is also
not at its best.  Now, QBTiny does not (yet) support all of the
routines that the default library does, but it was designed
over a period of months by a single expert assembly language
programmer.  This is why the simple program:

   PRINT "Hello, world!"

comes out to 12,308 bytes when linked with BCOM45, but only
2,550 bytes when linked with QBTiny.  Yep, the QBTiny version
is a mere 21% of the size of the BCOM45 version!  The more
complex MWORD demo (linked with my BasWiz and PBClone libraries
as well as QBTiny) comes out to 8,716 bytes with QBTiny, as
compared to 34,662 bytes when linked with BCOM45.  You won't
always get savings of this magnitude, but for most small to
medium programs the size difference is quite dramatic.

With a few exceptions that will be noted later on, you will not
take any performance penalties for using QBTiny instead of
BCOM45, either.  In fact, many QBTiny routines are faster than
the equivalent routines in the default support library.

When you register QBTiny, you also get QBTINYAT.LIB (for 80286
and later processors) and QBTINY3.LIB (for 80386 and later
processors).  If you don't need to support older machines, you
can use these new libraries for even smaller and faster code!

QBTiny does not support all of the routines that the default
library does. In a few cases, it supports a routine, but not in
quite the same way.  These differences are discussed later.

                      How to Use QBTiny                  page 4



Before using QBTiny, you must compile your program from the
command line.  The /o switch is required to tell the compiler
to create an .OBJ which can become a stand-alone EXE file.  Few
of the other switches are compatible with QBTiny.  Compilation
goes like this:

   BC program/o;

That's the standard way of compiling from the command line--
nothing new there.  The differences come in at LINK time.
Instead of your old LINK syntax, which may have looked a bit
like this:

   LINK program/EX;

you would use a special syntax, like so:

   LINK program/NOD/EX,,NUL,QBTINY;

Note that the /EX (sometimes abbreviated /E, which isn't quite
safe) usually makes QuickBasic programs smaller.  LINK isn't
too bright, though, and will apply /EX whether or not it really
shrinks the program.  In the case of QBTiny, you'll sometimes
get better results by leaving the /EX off-- try it both ways to
be sure.  Most programs do benefit from the /EX switch.

If LINK reports "unresolved externals" errors, you are using
capabilities which QBTiny doesn't provide.  LINK will tell you
what routine names are missing.  Use SYMDEX to find out what
BASIC statement uses these routines.  If you're not sure where
in your program this BASIC statement is, try creating a pseudo
ASM listing-- BC.EXE will show you the code it generates in
assembly language form, more or less, if you ask politely:

   BC program/O/A,program,program;

This creates a program.LST file which will help you track down
where the problem lies.

If you have the registered version of QBTiny and are using the
QBTINYAT.LIB (286+) or QBTINY3.LIB (386+) libraries with PDS,
be sure to compile your BASIC programs using the /G2 switch.
That tells PDS to create code for the 80286 and later CPUs.

                      Compatibility Issues               page 5



The QBTiny library is designed to mimic the default support
library as closely as possible.  However, it is still a work in
progress, and differences remain.  There are slight differences
in the handling of some individual routines and certain types
of routines are not yet supported at all.

QBTiny does not support floating point math.  It does not allow
single-precision or double-precision numbers or any routines
which require them.  It does not support event trapping-- no ON
COM, ON ERROR, ON KEY, ON PEN, ON STICK, ON STRIG, or ON
UEVENT.  It does not yet support dynamic arrays, READ/DATA,
RANDOM file mode, INPUT, or many graphics statements.

It will be wise to debug your programs with the default support
library before using QBTiny.  In the interest of efficiency,
QBTiny does little error checking on items that are assumed to
be within the control of the programmer.  For instance, QBTiny
will not know if you use an invalid display page with SCREEN.
However, it will report an error if there is a problem with
OPEN or PRINT#, for example.

Still with me?  That may have seemed like a lot, I know.  Many
of these capabilities will be added in later versions of
QBTiny.  There are also new capabilities provided by QBTiny
which provide alternatives to the missing routines which are
actually more convenient than the originals.  For instance,
although ON ERROR isn't allowed, the ERR variable is still
updated as you'd expect.  You don't need slow and bulky error
trapping to check for errors with QBTiny!

You can also use the QBTiny library along with other libraries,
which can more than make up for any missing routines.  So you
can't use RANDOMIZE and RND?  No problem!  The RAND function in
my PBClone library is faster, smaller, and easier to use.

No need to search through your existing programs to figure out
whether they'll work with QBTiny as-is.  When you link them
with QBTiny, LINK itself will tell you which routines it was
expecting that are not provided by QBTiny.  The SYMDEX utility
(included) translates routine names to the names of the BASIC
statements to which they refer.  BASDEX converts the other way.
Between the two, you will be able to cross-reference BASIC
statements with their symbols. We'll get into more details on
that presently.  Right now, let's take a look at any individual
differences between QBTiny and the default support library.

                      Compatibility Issues               page 6



Graphics

The QBTiny graphics handler is unlike BCOM45 in a number of
respects.  It does not provide a simulated cursor, allow
graphics paging, or set a default palette on entering a mode.



Keyboard

If input is not redirected, keyboard handling is done through
BIOS calls.  The keyboard handler relies on 0000:0496h bit 4 to
tell it whether an enhanced keyboard driver is available.  This
may be incorrectly set on some old PC clones, making keyboard
input unavailable.  If you have this problem, please get in
touch, and I'll try to find a work-around for your machine.
This problem brought to you courtesy of Microsoft, which did
not see fit to provide DOS with enhanced keyboard support,
giving me no alternative but to go with direct machine access.



KILL

The QBTiny version of KILL does not support wildcards.



LINE

The QBTiny version of LINE does not support patterns in quite
the same way as QuickBASIC.  QuickBASIC always draws lines from
left to right, but does up and down according to the order of
the coordinates you give it.  QBTiny always sorts the
coordinates and goes from the smaller coordinates to the larger
coordinates.  In addition, QuickBASIC uses a somewhat peculiar
procedure for handling patterns when drawing box frames, and
ignores patterns when drawing filled boxes.  QBTiny handles
patterns for box frames more the way you'd expect and supports
patterns for filled boxes.

The current QBTiny LINE support is based on the BIOS and is
very compact but also quite slow.  It will be converted to
larger but much faster methods in later versions.  The method
of pattern handling will also be changed.



LONG math

The QBTiny library does not support division or MOD for LONG
integers, unless you are using QBTINY3.LIB (the 386 version).
I'll fix this when I come up with a reasonably efficient way of
implementing 32-bit division on a 16-bit processor.

                      Compatibility Issues               page 7



OPEN

The QBTiny version of OPEN does not support the RANDOM file
mode.  It does not support BASIC devices (COMn:, CONS:, KYBD:,
LPTn:, SCRN:).  However, DOS devices (AUX, COMn, CON, LPTn,
PRN) are supported.  Note that INPUT# and LINE INPUT# are not
yet available, so the INPUT file mode is rather limited.



PALETTE

The QBTiny version of PALETTE does not support the version of
PALETTE without parameters.



SETMEM

Since QBTiny only uses as much memory as it needs, unlike
BCOM45 (which allocates all base memory), the SETMEM function
has no real purpose in QBTiny.  This may change when support
for dynamic arrays is added.  In the meantime, the parameter
passed to SETMEM is meaningless and is ignored.



SWAP

The QBTiny version of SWAP does not allow you to swap normal
strings with other data types (such as fixed-length strings or
TYPEd variables).



TIMER

The BASIC function TIMER is designed to use floating point,
then convert the result to the appropriate numeric type.  The
QBTiny version has been modified to skip the floating point
handling, and only supports TIMER for long integers.

To make sure TIMER returns a long integer, you should enclose
it in CLNG unless it is returning the result directly to a
variable.  For example, these are ok:

   A& = TIMER
   PRINT CLNG(TIMER)

But not this, since the type isn't apparent (and is assumed to
be floating point):

   PRINT TIMER

                      Compatibility Issues               page 8



WIDTH

The QBTiny version of WIDTH supports 40 and 80 column modes. It
ignores attempts to change the number of rows, however.  While
it does support changing the width of open files, it does not
allow you to change the width of BASIC devices (QBTiny supports
only DOS devices, not BASIC devices).



VAL

The BASIC function VAL is designed to use floating point, then
convert the result to the appropriate numeric type.  The QBTiny
version has been modified to skip the floating point handling,
and only supports VAL for integers and longs.  One side effect
is that the QBTiny version won't always detect VAL overflows.

To make sure VAL returns an integer or long integer, you should
enclose it in CINT or CLNG unless it is returning the result
directly to a variable.  For example, these are ok:

   A% = VAL(St$)
   A% = CINT(VAL(St$)
   PRINT CINT(VAL(St$))

But not this, since the type isn't apparent (and is assumed to
be floating point):

   PRINT VAL(St$)

The QBTiny version of VAL does not mimic certain BASIC bugs
which appear with hex and octal numbers.  It won't gratuitously
sign-extend long integer hex and octal, either.  For example:

   Function              QBTiny Result     BASIC Result
   -------------        ---------------   -------------------
   VAL("&H")                   0                 203
   VAL("-&1")                  0          Type Mismatch Error
   CLNG(VAL("&HFFFF"))       65535                -1

                   Statements Not Supported              page 9



Floating point:

 ATN       CDBL      COS       CSNG      CVD       CVDMBF
 EXP       INT       FIX       LOG       MKD$      MKDMBF$
 MKS$      MKSMBF$   RANDOMIZE RND       SIN       SOUND
 SQR       TAN



Graphics:

 CIRCLE    GET       PAINT     PMAP      PUT       VIEW
 WINDOW



Event trapping:

 COM       KEY       PEN       PLAY      STRIG     TIMER
 UEVENT

 ON ERROR GOTO



Miscellaneous:

 CHAIN     CLEAR     DATA      DRAW      ENVIRON   ERASE
 ERDEV     ERDEV$    ERL       FIELD     FILES     INPUT
 INPUT#    IOCTL     IOCTL$    KEY ON    LINE INPUT#
 LOCK      LPRINT USING        PLAY      PRINT USING
 PRINT# USING        READ      REDIM     RESTORE   RESUME
 RUN       SHELL     TROFF     TRON      UNLOCK    VARPTR$



 DIM           (for $DYNAMIC arrays)
 OPEN          (for RANDOM)
 MOD or \ with LONG integers (only allowed with QBTINY3.LIB)
 Floating point math



PDS:

 CVC       EVENT     MKC$      PRESERVE  STACK

 Far strings
 Currency math
 ISAM support

                      Crescent's P.D.Q.                 page 10



Many of you are probably familiar with Crescent Software's
P.D.Q. library.  P.D.Q. is similar to QBTiny in that it is a
replacement for the default support library.  P.D.Q. provides
some powerful advantages which QBTiny does not have, including
the ability to make TSRs and interrupt handlers.  Crescent also
provides printed manuals, phone tech support, and support for
BASCOM/PDS as well as QuickBasic.  P.D.Q. runs about $150.
Crescent Software is available at the following:

   800-35-BASIC    orders only, voice line | 9:00-5:00 EST
   203-438-5300    tech info, voice line   | (Connecticut)

   11 Bailey Avenue
   Ridgefield, CT 06877

It must be noted that QBTiny provides the first competition for
P.D.Q., which has had the market to its own for quite some
years now.  In consequence, perhaps it is not surprising that
QBTiny provides much better QuickBasic compatibility than
P.D.Q. and also results in smaller .EXE files.  Still, each
product has its advantages, and you will not do badly with
P.D.Q. if price is no object and you need the capabilities it
provides which QBTiny lacks.  Crescent Software provides one of
the better commercial outlets for BASIC libraries.

Late-breaking news: I am led to understand that P.D.Q. actually
can produce smaller .EXE files than QBTiny, although it takes
considerably more effort.  By linking in appropriate "stub"
files (out of several dozen Crescent provides) and using
Crescent's .EXE compression utility, you can reduce the size of
an .EXE below even what QBTiny can create.  Well, we'll just
have to see about that <grin>.

                        Which Runtime?                  page 11



It is possible for your program to automatically detect which
of the three runtime libraries (default, P.D.Q., QBTiny) it is
using.  Of course, the program is unlikely to compile if it
uses a feature that isn't provided by the specified library.
Still, since there are differences in the way each library
handles specific routines, it may be helpful to know which one
is being used.

The VAL function is implemented differently by each library.
The P.D.Q. version has an incompatibility in the way it handles
spaces.  The QBTiny version does not mimic certain obscure bugs
that are present in the default library.  The following program
fragment makes use of these differences to identify which
runtime library is in use:

   IF CINT(VAL("1 2")) = 1 THEN   ' P.D.Q. stops at spaces
      PRINT "PDQ.LIB"
   ELSEIF CINT(VAL("&H")) THEN    ' BCOM45 has a hex bug
      PRINT "BCOM45.LIB"
   ELSE                           ' otherwise, must be QBTiny
      PRINT "QBTINY.LIB"
   END IF

                        Author's Notes                  page 12



Perhaps the most striking thing I found about writing QBTiny is
that it was so easy.  Oh, I don't mean that it didn't take a
lot of work-- QuickBasic has a lot of complexities, and QBTiny
has corresponding depths to it.  I'm sure assorted bugs and/or
incompatibilities will surface in the coming months.  Still, it
involved more of massive work than of programming difficulty.

QBTiny is a product which, aside from an essential skeleton, is
no different than any other BASIC library.  Simply by arriving
at this conclusion first, Crescent Software managed to steal
several years on its competition.  By virtue of being the
frontrunner, they had a tough path to beat.  I had it easier,
and I can certainly appreciate that-- I am grateful for their
excellent work, although I hope to surpass it.  "If I have seen
farther than others, it is because I have stood on the
shoulders of giants."  Of course, the game of life is a totem
pole, and today's giants are tomorrow's dwarves...

In examining Microsoft's work, I have found many things
astonishing.  Sometimes I have been stunned by the delightful
elegance of their design, other times by the thoughtless jumble
that confronted me.  The default support library is a product
born of genius, fools, and the hurry to get a product out.  It
has some of the best and worst programming I have seen.  I've
learned considerably in studying it, and have become a much
better programmer thereby; and will no longer castigate
Microsoft for some decisions which, although they might seem
awful to the uninitiated, really do make sense when all is
understood.  Then again, some of the best of the odd things
they do in BASIC are only necessary because of severe lacks in
DOS itself, which Microsoft also designed... but perhaps I will
understand these problems better when I have completed DosTiny!

If you wish to become an expert in the ways of BASIC and have a
better comprehension of its varied history along these many
years, I can recommend few better approaches than studying the
QBTiny source code, which brings a single understanding to the
support library which underlies the whole of Microsoft's BASIC.

Crescent Software charges $150 for their P.D.Q., as of this
writing.  I charge only $35 for QBTiny.  I don't think you'll
find a better value anywhere.

                          The Future                    page 13



One of the great mistakes that Crescent made, I think, was in
giving in to the urge to improve on Microsoft's failures.
Sure, there are many obvious errors in Microsoft's design,
especially in retrospect <smile>.  Still, current programs are
written using that design, however flawed it may be. Crescent
Software's P.D.Q. causes more chaos than anything else when it
attempts to both solve the problems and provide compatibility.
QBTiny was designed with the idea of QuickBasic compatibility
*paramount*.  You will find it little effort to convert from QB
to QBTiny, as long as a few basic rules are followed.  There
will be even less work involved as QBTiny progresses.

However, there are other directions which may be taken as well.
QBTiny follows Microsoft even if the path leads over a bridge.
Later, I will introduce another library which will diverge from
the Microsoft standard where it makes sense to do so.

For instance, have you considered the COLOR statement?  In
graphics modes, the existing COLOR doesn't set foreground and
background statements.  In fact, it *never* sets the background
color.  Frequently, it serves as a palette changer, which would
seem to be better handled by PALETTE.  Wouldn't it be nice to
have both foreground and background colors in graphics modes?
No problem!  ...but that's not compatible with QuickBasic!  Too
bad?  Not really.  With one of my future libraries, you will be
able to use COLOR the way it *ought* to be used, PALETTE
likewise, DIM arrays in EMS and XMS memory, and otherwise gain
advantages which current BASIC versions don't provide.

QB limitations will be forgotten when you can replace the very
foundation library for BASIC itself.  QBTiny proves it can be
done.  Future replacement libraries based on the QBTiny idea
need not follow Microsoft so slavishly.

As a library writer, I have been confounded by some of the
limitations Microsoft has placed on the ways subprograms and
functions can access strings and arrays.  These limitations
will be removed by my library replacements in the future.  I
intend to document the improvements so that all programmers
will be able to take advantage of them.

In short, BASIC is in for a wild ride, and we're going to have
fun!  Stay tuned!