POINT Software Programming/PPROG1.ISO/basic/baswiz19/lib_bi.doc

Text File | 1992-06-24 | 25KB | 547 lines

     LIB_BI.DOC  Copyright (c) 1992  Daniel M. Smith, Jr.

              TOWARD LIBRARIES AND INCLUDE FILES



This document consists of a basic tutorial on BASIC include
files and libraries. It is included with my libraries by the
kind permission of the author. The text has been edited for
consistency with my existing documentation and includes minor
alterations where I considered them helpful.
   -- Thomas G. Hanlin III

While the following might be considered mundane by experienced
programmers, it's always nice to have a good foundation to
begin building on.  With that in mind, the examples and
discussion of topics will be in relatively layman terminology.
To give you an excellent grasp of each idea presented, examples
and step-by-step procedures will be given.  If you are using
any version of QuickBASIC including QBX Professional
Development System, the information presented here is
applicable to all, although some versions may present specific
problems regarding arguments and syntax. In fact, it is
germaine to all higher level languages but specifically to the
many forms of BASIC which is the language we are concerned
about.

Many routines have been developed by programmers to accomplish
tasks within the BASIC environment. Some are simple, yet others
are extremely complex, possibly requiring memory allocation,
etc. Since these routines are already available why waste time
trying to re-invent the wheel so to speak; include the ones you
require into your program with the $INCLUDE Metacommand (hardly
layman language, so let's take time right now to find out about
this special terminology).

Metacommands are special commands that are used to make your
programs perform in a specific fashion. BASIC has three such
commands; two ($DYNAMIC and $STATIC) which deal with allocation
of dimensioned arrays and the $INCLUDE command which provides a
means of incorporating external programs or routines into your
programs. It specifically tells the compiler to stop processing
the current program in favor of the program directed by the
$INCLUDE Metacommand. When the included program ends, execution
returns to the next line of the main program following the
included routine.

We are only concerned here with $INCLUDE since it is the means
by which all external routines are usually made a part of the
main program. There is a specific syntax required with all
metacommands that needs to be emphasized; most curious is that
these commands are always preceded by REM or the apostrophe
character. The following is the correct syntax for $INCLUDE:

   REM $INCLUDE: 'MyFile.BI'
      or
   ' $INCLUDE: 'MyFile.BI'

More than one metacommand can be placed on the same line as
long as they are separated by white space. The other two
metacommands don't require an argument, so no colon (delimiter)
is required when using them. Note that the above argument is
enclosed by single quotation marks (apostrophes).

What is a ".BI" file?  Nothing can be more frustrating than
trying to figure out what constitutes an include file when you
have never been near one before.  Forget trying to track it
down in reference books!! Here it is in a nutshell and will
save you a lot of time.

First, it doesn't have to have the ".BI" extension at all, but
that's the common extension used for BASIC Include files.
Second, no SUB or FUNCTION programming statements are permitted
in the file; and Third, include files must be in ASCII format.
A ".BI" file then is simply the declaration statements
identifying the external subroutine or function that you want
to be included into the main program. The following syntax is
what you could expect to find in a typical ".BI" file. Let's
call it 'WINDO.BI'.

The metacommand is:
   REM $INCLUDE: 'WINDO.BI'

The contents of the file might be:

   DECLARE SUB Windo (TRow%, LCol%, BRow%, RCol%)
   DECLARE SUB Colour (ForeGrd%, BackGrd%, Scrn%)
   DECLARE SUB Border (Style%, Title$)
   DECLARE SUB WritWin (FC%, BG%, Text$)
   ' (etc)

The list could go on to include other windowing capabilities
such as saving the screen the window pops up on, restoring the
screen when the window is closed, etc.  Whatever the routine or
function you wish to include in your program requires a
definition statement similar to the above in the ".BI" file.
The actual program defined is, of course, located in a library
of subroutines; you are only telling the program to expect
these particular subroutines to be called elsewhere in the
program. If it were not for the ".BI" file and the declarations
contained therein, when the program reached the call to the
subroutine a "SUBPROGRAM NOT DEFINED" error message would be
encountered. Every subroutine and function must be defined
either at the beginning of the main module or in the ".BI" file
if it is to be called during program execution.  I should also
point out here that all arguments (ie., those within the
parentheses in the examples above) must be established in your
program before you make the call to the external subroutine.
The % arguments require integers and $ arguments require
strings.

Let's assume you have a key trapped that directs your program
to a label called WIN. We would expect to find something like
the following:

   WIN:
      TRow% = 8: LCol% = 20: BRow% = 18: RCol% = 60
      BackGrd% = 2: ForeGrd% = 15: Scrn% = 0
      Style% = 1: Title$ = "TEST WINDOW"

Now that the parameters are established:

   Border Style%, Title$
   Colour ForeGrd%, BackGrd%, Scrn%
   Windo TRow%, LCol%, BRow%, RCol%

The parameters can be set when the function is used, for
example:

   LOCATE 10, 25
   WritWin 14, 4, "This is only a test!"

By the way, why use Colour instead of Color, or Windo instead
of Window? Because COLOR and WINDOW are BASIC keywords! We
can't use them, since they are already defined to mean
something else. Sometimes you have to be careful with names.

Declaration is not required for GOSUB, since you never have to
pass any arguments explicitly.  The GOSUB statement is kind of
a specialized version of GOTO, not a subroutine in the sense
that a SUB or FUNCTION is.

Hopefully, this will help you to a proper perspective of ".BI"
files.

NOW!! Here comes the big one. We will step through this very
slowly because libraries are the backbone of programming. Each
time a programmer prepares a method to accomplish a certain
job, it becomes candidate for retention, since the same routine
might be required again (either by himself or other persons who
program in the same language).  These routines are normally
placed in libraries. It could be a small library, or, if many
routines have been created, it could be quite large. The term
"library" is very appropriate, because (like books) routines
can be removed from programming libraries and used when you
need them, but do not need to be kept in your program when you
don't. Much work and research go into solving specific tasks or
coming up with better and more efficient ways of doing a
particular job. Making these great routines available to others
makes programming so much easier because you won't have to
waste time trying to come up with the same routine again. Just
extract it from the provided library and place in a new library
you are going to use. Very easily said, but it takes
considerable doing. This is exactly what we are going to
examine now.

We will step through the entire procedure for creating a new
library exactly in the same order as you should every time you
decide to use someone else's library routines. Please keep in
mind that these instructions are given from a QuickBASIC
viewpoint. With other versions of BASIC you will have to make
substitutions or modifications in the syntax where required.

First you must decide which routines you are going to need from
the library. Make a list of the names of each routine on paper
leaving room on the right for additional information.  You will
realize the advantage of doing this shortly.

Next, you must have a listing (.LST) file of the library to
find out the specific module file the routine is located in.
When .OBJ files are placed in libraries they no longer have an
extension associated with them; they are merely modules within
the library. However, when they are extracted (as we will see
later) they are given the .OBJ extension once again by LIB.EXE
which is the default. Programmers often place related routines
in one module file within the library. If a routine exists in
its own module file then extracting that module file will
provide you with that particular routine; however if several
routines exist in one module file you can't extract a specific
routine you must extract the entire module file.  Therefore,
just because we know the name of a routine does not necessarily
give us access to that routine because it could be in a module
file with an entirely different name. When you see your first
listing file you will more readily discern what I mean. If the
routines are contained in one library and the programmer has
provided both ".QLB" and ".LIB" files you will not need a list
file if you use the programmers libraries. Otherwise, if no
listing (.LST) file exists for the library it will be necessary
to create one.

That brings us to our next step, creating a .LST file.

LIB.EXE is the library management tool that comes with most of
the versions of BASIC that include a compiler.  Some
programmer's huge libraries may be too large for some older
versions of LIB.EXE and if so the programmer will make you
aware of that in his readme file or other documentation.
QuickBASIC 4.5 and PDS/QBX 7.x seem quite up to tackling all
library tasks. To create the .LST file enter:

   LIB LIBRARY.LIB

where LIBRARY.LIB is the name of the library requiring the
listing file. The .LIB extension is not really required, since
LIB.EXE knows it will be working with a .LIB file. NOTE:
LIBRARY.LIB is always replaced with the actual name of a
library in the following examples; xx in a QB .LIB file name is
replaced with the actual number of your version.

LIB.EXE and the library must be in the same directory. To make
everything simple I usually create a special subdirectory for
the library and copy LIB.EXE to it along with the library files
I intend to use. Also copy LINK.EXE to the same subdirectory
for future use. There will be quite a bit of activity in this
directory; this will keep everything a little organized. If
something goes wrong it's easy to identify the erroneous files
and start over again without having to search for the files we
created and maybe erase something inadvertantly.

After pressing enter in example above you will see the following:

   Operations:        press Enter to continue
      Since we did not define any operation on the command line
      LIB is prompting for direction; none is required at this
      time.

Next you see:

   List file:         type LIBRARY.LST and press Enter
      You can name the list file anything you wish but it would
      be advisable to name it the same as the library to avoid
      confusion.

The .LST file will be created in the current subdirectory. You
can use any text editor to view the file. It may be quite long
so I would not use the DOS TYPE command except to redirect it
to the printer. Make sure you have sufficient paper and that
the printer is on and ready. To redirect the list file to
printer, type the following:

   TYPE LIBRARY.LST >PRN

List files are in two columns. Each column has two text entries
divided by dots. The left entry is the subroutine name; the
right is the module file to which it belongs. Some module file
names are really quite cryptic; also as mentioned before some
have the same name as the subroutine. Related routines will
probably be in a single module file.

Using the example .BI file we looked at before, you might see
this in the listing file of the library containing those
subroutines.

   WINDO...............wnd
   COLOR...............wnd
   BORDER..............wnd
   WRITWIN..........writwn

Please note that all of the above could have been in the same
module or in all different modules. Notice also that the module
file "writwn" is not spelled the same as the subroutine.
Programmers may change the name of .OBJ files, sometimes just
by abbreviating the name of the routine.

Now that we have the .LST file we can really get down to work.
First we must select the routines that will be needed for
inclusion into the main program and identify the module(s) to
which they belong. We will continue to use the WINDO example
throughout this instruction.

The next step is to copy the module files from the Library. The
.LST file has shown us the names of the module files we need to
make our imaginary window. We need to extract WND and WRITWN.
Recall that when they are extracted they will be given the .OBJ
extension by default.

LIB.EXE can do this. Just type the following:

   LIB LIBRARY.LIB  *WND.OBJ *WRITWN.OBJ

The "*" tells LIB to copy the module files only.  The original
modules will remain in the library.

There are several operators that tell LIB what to do and I will
briefly describe some here:

   +   preceding the .OBJ file means add to library
   -   preceding a module name removes it
   -+  preceding a module removes original and replaces it with
       the updated version. Be sure the new version is
       available to LIB because removal action is always first
       in order.

There are more but the above gives ample ability to manipulate
libraries. Consult your manual on others.

After doing the above example, you would have all of the
required .OBJ files in the current subdirectory.  You could
verify their existence by typing DIR at the DOS prompt.  When
there are more than a few .OBJ files, it may help to keep a
notepad handy to keep track of them.

If we needed .OBJ files from a second library we would again
use LIB.EXE to extract those files from that particular
library. There would then be .OBJ files from two different
libraries; these can be easily combined into a new library
specific to the needs of the main program.

As mentioned before, QuickBASIC uses two types of Library
files: the normal .LIB files at linking time and .QLB
(QuickLibrary) files when programming in the QuickBASIC
environment. Certainly you want to see your program run, if
possible, prior to compiling an .EXE file so all bugs can be
removed.  Notice I said "if possible". There may be occasions
when running a program is not possible because of conflict with
the environment.  If this should happen, you will have to
create the .EXE file from the DOS command line or determine the
cause of the conflict and correct it.  Refer to your QuickBASIC
guide book for the proper syntax for BC and LINK. I will also
describe them briefly after we create these new libraries.  If
you do run into this type situation I suggest you get the rest
of your program functioning the way it should; then make the
.EXE file to check the end result. Then you can work with the
sticky subroutine; any error subsequent to that would
definitely suggest the problem is with that subroutine.

So, a .QLB library is the first one we need to see how the
program will function.  LINK.EXE will provide the means to do
this job. LINK.EXE has a special switch (/Q) which tells the
program to make the .QLB library. If the switch is omitted
QuickBASIC will not be able to load the library when instructed
to do so with the /L switch because of improper format.

The following syntax for LINK will provide a .QLB library:

   LINK /Q WND.OBJ WRITWN.OBJ, MYNEW.QLB,,BQLBxx.LIB;

LINK.EXE will combine the .OBJ files into the new .QLB library
using QuickBASICs provided library for support routines.
Naturally if you were using some other version of BASIC you
would use the library provided to support the specific
environmental library. NOTE: When using the /L swith to load
QuickBASIC only one .QLB file can be specified. This means one
thing, ALL external routines must be in the same .QLB library.
Also, .QLB libraries are not manageable as .LIB libraries are,
therefore it is important to have identified all routines
required prior to creating the .QLB library. If you forget one
you will have to LINK all .OBJ files again to include the
one(s) you forgot.  I should mention that it is possible to do
these tasks within the QuickBASIC environment in which case
.QLB libraries can be manipulated but only by changing the
resulting library to a different name which basically means you
are redoing everything again anyway. An advantage of this
method is that the parallel .LIB file will be created at the
same time. Consult your manual if you opt for this method.
It is desirable to know how to do it from the command line.

You should copy the .BI and .QLB file now to your program
directory. The following syntax will make your new library
available to the main program when you are ready to try the
external routines.  It is assumed of course that you have
entered the $INCLUDE metacommand into your program (preferably
ahead of other DECLARE statements) and that subroutine arguments
have been entered or will be entered before the call is made to
a particular routine:

   QB /L MYNEW.QLB

or, if you wish to load the program at the same time:

   QB YOURPROG /L MYNEW.QLB


Your program is up and running now and you have presumably
ironed out all the bugs and are ready to create the .EXE file.
Whether it is a standalone executable or one requiring the run
library your external routines must be supported by parallel
.LIB files. These parallel files contain the same object code
as the .QLB files but in entirely different format. If, when
creating the .EXE file, these files are not found they will be
omitted from the .EXE program. Hence a certain function may not
work at all even though the rest of the program is perfect. For
this reason it is always a very good idea to create the .LIB
file at the same time you create the .QLB file. For purposes of
illustration I will repeat the syntax for creating the .QLB
file so that you may see both of these commands together and
their relationship to each other:

   LINK /Q WND.OBJ WRITWN.OBJ, MYNEW.QLB,,BQLBxx.LIB;

and here is the command to create the parallel .LIB file:

   LIB MYNEW.LIB+WND.OBJ+WRITWN.OBJ;

LIB will create MYNEW.LIB in the current directory as the
parallel file of MYNEW.QLB. It should be copied also to your
program directory when it is created along with the .BI and
.QLB files.

The semicolon at the end of these commands tells LIB that no
other directions are necessary. Omitting the semicolon will
cause LIB to prompt you for additional information. Try it if
you're curious. If you type LIB alone on the command line the
program will prompt you for each entry. You are allowed 127
characters on the command line, so if you have a considerable
number of .OBJ files to list, using LIB alone on the command
line is advisable, since you are not limited to the number of
.OBJ files you can list. When you run out of space on the first
line, just type an ampersand (&) at the end of the line and
press Enter. The Operations prompt will be repeated and you can
continue entering information.

You can now create the .EXE version of your program. From
within the QuickBASIC environment you determine the type of
executable program you desire. BC will compile your program
using defaults based on it's analysis of the program and
automatically enter the LINK phase. If you choose an executable
requiring the run time library LINK will use BRUNxx.LIB in
conjunction with your .LIB file(s) to create the .EXE file.
Advantages are smaller code which may be desirable with larger
programs; disadvantages are slower execution and BRUNxx.LIB
must be in the same directory or available to the program to
provide support routines. If you choose the standalone
executable version LINK will use BCOMxx.LIB and your .LIB
file(s) to create the .EXE file.  Standalone executables are
larger but run faster and are self- supporting. Additionally,
using command line compiling and linking, certain options can
be used to decrease program size depending on the requirements
of your program. You must consult your manual for this
information; they are usually .OBJ files that can be linked
with your program to curtail specific unnecessary functions. To
use these you MUST link from the command line.

As I mentioned above, sometimes it may be necessary to create
the .EXE file from the command line. In earlier versions of
QuickBASIC it was advisable to do so since smaller .EXE files
could be obtained. Version 4.5 seems to do fine; QBX 7.x is
even better.

First you must invoke the QuickBASIC Compiler (BC) to compile
the program. The default syntax for QuickBASIC 4.x follows:

For .EXE requiring run time support:

   BC YOURPROG.BAS;

For .EXE as a standalone program:

   BC YOURPROG.BAS/O;

You will need to add /E or /V if you use ON ERROR in your
program-- BC will tell you if you forget.  Add /C:512 if you
use communications, to set the comm buffer size.

There are alternative methods which may be used and they are:

   BC     (and answer the following prompts:

      Source Filename: [.BAS]: YOURPROG.BAS
      Object Filename: [YOURPROG.OBJ]:   press Enter
      Source Listing: [NUL.LST]:    press Enter

Result: all error messages will be printed on screen and may
scroll out of sight.

You may have many object files.  If you run out of space on a
line, just type a plus (+) at the end and the prompt will be
repeated on the next line.

   BC YOURPROG.BAS;

Result: all errors will be printed on screen and may scroll out
of sight.

   BC YOURPROG.BAS; >YOURPROG.ERR

Result: all errors will be printed to a file in the current
directory with name following ">". Redirection to the printer
would be more functional and would not clutter up the directory
as follows:

   BC YOURPROG.BAS; >PRN

Result: a printout of the errors which you can refer to while
entering the proper operations which really means in the end
you will be using one of the first two examples to tell the
compiler what to do.

It is possible to use the same switches as the compiler. When
you reach your final compilation from within the environment,
use the "MAKE EXE AND EXIT" function. The options used by the
QB environment will remain on the screen.  Write them down and
use those options (except the /T) when you must compile from
the command line.  This method is not recommended, since QB
uses a lot more options than is usually necessary, which
results in your programs being larger and slower than need be.
Still, it's an easy way to get running in a hurry.

NOTE: Do not use /T since it turns off error messages and is
only used by default within the QB environment because all
possible errors have, presumably, been eliminated.

When you have successfully created YOURPROG.OBJ you are ready
to use the linker (LINK.EXE). Linking is pretty straightforward
as you will see. The syntax is:

   LINK YOURPROG.OBJ/EX;

If you have multiple object files and libraries:

   LINK YOURPROG.OBJ+ANY.OBJ/EX, YOURPROG.EXE, NUL, MYNEW.LIB;

Again you are limited to 127 characters on the command line. It
might be more convenient to just type:

   LINK /EX   (the /EX option is desirable for optimization)

and answer the following prompts:

   Object Modules [.OBJ]: YOURPROG.OBJ+ANY.OBJ+NEXT.OBJ
   Run File [YOURPROG.EXE]:        press Enter if no change
   List File [NUL.MAP]:            press Enter for no map
   Libraries [.LIB]: MYNEW.LIB+ANY.LIB

If you run out of room on a line just type "+" at the end of
the line and the specific prompt will be repeated.

This was not intended to be a complete documentation of the
special features of LIB.EXE, BC,EXE and LINK.EXE, but rather
specific knowledge about common application of the programs
with regards to BASIC programming and the use of third party
subroutines therein.  Knowing how to manipulate libraries is an
important investment of time for anyone considering creating
programs no matter what particular language is used.  The
knowledge gained is applicable to all.