PreQLB 2.0
Copyright (c) 1989-1991 MicroHelp Inc.

Licensing:
This program is Copyrighted by MicroHelp Inc. and was originally
released in our QB-Pro Volume 8. It is now being placed into the
Public Domain to assist you in creating your quick libraries.
This program can be freely distributed as long as it is not modified
in any way. The PreQLB.zip file should contain the current executable
file and this PREQLB.DOC file. If you discover any problems with this
program we definitely want to know about them; however, only registered
users of MicroHelp products can receive tech support on this program.

If you want further information on our line of BASIC add-in libraries
and other products, please call us at 1-800-922-3383 or in GA at
(404) 552-0565. If you discover a problem with PreQLB, you can write
to us at 4636 Huntridge Dr. Roswell, GA 30075.


Creating Quick Libraries with PREQLB

PREQLB.EXE is used to automatically build a Quick
library containing all the "external" routines needed by a
specific program.

PREQLB parses the specified BASIC source code file(s),
checking for statements that identify the names of external
routines used in your program. The external references are
placed into a special object module, having a ".BQL"
extension.

All of the externals that are required by your program are
extracted from a list of specified .LIB files to create the
Quick library. In addition, you can pass to it the names of
object modules that should be included in the QLB, using the
#TrailingObject command described below.

PREQLB can be operated from the command line or via dialog
mode.

PREQLB and Command Line Mode

The syntax for command line mode is:

PREQLB [?] [Filename] [/L] [/Q]

Passing the "?" will display a help screen that gives the
proper syntax and a brief usage summary.

"Filename" is the name of your BASIC source file. It must
be in "text" format, as opposed to "fast-load" format. You
may omit the extension (.BAS) if your program has that
extension, or if there is a ".MAK" file associated with
"Filename".

PREQLB looks for files in the following order:

\ Filename.MAK - If found, PREQLB will process every
module listed in the file, including the main program.

\ If a .MAK file is not found, PREQLB looks for
Filename.BAS. If your file has an extension other than .MAK
or .BAS, you must pass the complete file name on the command
line, including the extension.

\ Additionally, PREQLB will look for a Filename.CFG file.
This configuration file is created when you use Dialog Mode
(explained under PREQLB and Dialog Mode on page 3) and
contains the names of the source file (or .MAK file), the
Quick library support library, the Quick library name, and
up to twenty additional LINK libraries, along with their
respective paths.

While parsing the file(s), PREQLB looks for three special
pre-processing commands embedded in a REMark, just like
metacommands. Here's the syntax for the commands, shown in
example form:

'#Libraries: 'C:\PDS\LIB\MUSCLE'
'#SupportLib: 'C:\PDS\LIB\QBXQLB'
'#TrailingObject: 'C:\PDS\OBJ\MHSUPFR'

CAUTION: The apostrophes (') surrounding file names are
required.

'#Libraries

The #Libraries command refers to LINK libraries (.LIB file
extension), that contain the external routines referenced in
your program.

You may specify up to 20 #Libraries in your source files.
Those in excess of 20 are ignored.

'#SupportLib

The #SupportLib command refers to the Quick library
support library. See page the on-line help screens for the
name to use with your compiler.

If there is more than one #SupportLib statement, only the
last one is used.

'#TrailingObject

The #TrailingObject command allows you to pass the name of
any object modules that are to be unconditionally included
in your Quick library. You can use this command to include
customized object modules for individual programs, without
having to remove the object module with the same name from
your LINK library.

You may specify up to 20 #TrailingObject modules in your
source files. Those in excess of 20 are ignored.

Switches

The /L switch causes PREQLB to create an ASCII text file
containing the names of all the external routines in your
program. This list file will have the same name as
"Filename" (your program), with an extension of ".LST".

The /Q switch instructs PREQLB to process $INCLUDE files
only once. If your program has multiple modules, and the
same $INCLUDE file is specified in more than one of the
modules, the /Q switch tells PREQLB to search for externals
in this $INCLUDE file only the first time that it is
processed. If you receive an "Unresolved External" error
message from the linker when building the .QLB, try running
PREQLB without the /Q switch.

PREQLB and Dialog Mode

If you run PREQLB with no command line information, PREQLB
will prompt you for the information it needs to build a
Quick library for you.

The only fields that must be filled in are the source file
name and the support library name. All other fields are
optional.

New with version 2.0 is the dialog box interface. To change
fields use the TAB key to move "forward", Shift-TAB to move
"backwards" or ALT-[highlighted letter] to jump to a specific
field. The "Build QLB" command button is highlighted by default,
and pressing the enter key at any time will cause the Quick Library
to be built. For Help, you can press ALT-H or click on the Help
command button. Pressing the ESCape key or clicking on the Cancel
command button will exit PreQLB.

You can enter the name of the source or .MAK file,
the QLB support library, up to five link libraries, and the
output QLB name. If you do not enter a name for the Quick
Library, it will named the same as your source/make file with
the .QLB extension.

The source file is the name of your source or .MAK file,
including the path, if desired. If your source code has a
.BAS or .MAK extension, then the extension is not required.

You can also select the /Q and /L option switches
explained under "Switches", above.

You can save the current configuration information as your
"Master" configuration file by selecting the "Save as Master
CFG" command button on the bottom of the screen. This command
button can be selected by moving to the field with the TAB
button and pressing enter, pressing ALT-M or placing the mouse
cursor over the command button and pressing the left mouse button.
A file named PREQDFLT.CFG will be created in the same directory as
PREQLB.EXE saving the Link and support library information. If you
start PreQLB from the command line, it will check for the presence
of this file and use these values as its default. If you are using
the pre-processing commands mentioned above, they are handled in
the following manner. '#SupportLib will overwrite any existing
values with the LAST '#SupportLib value encountered being used. Any
'#Libraries or '#TrailingObject variables encountered will be
APPENDED to whatever may exist in the default configuration file.

Whenever PreQLB parses a module(s), it creates a configuration
file for that program with the name of .CFG. This
configuration file will contain all of the information passed to
the linker in the PREQLB.RSP file, which is a combination of what
was passed in the default configuration file (if any) and the
information entered in the dialog box. This allows you to run
PreQLB from the command line, bypassing the dialog box input and
speeding up your processing time.

Pressing the enter key or selecting the Build QLB command button
causes PREQLB to begin processing. It then analyzes your source
module(s) and builds the Quick library. The program will check
to make sure it can find the support and LINK libraries in the
path provided or in the path defined by the LIB environment
variable. If any library is not be found, an error message will
appear and you will remain in dialog mode. You will then be prompted
to provide the correct path or to update your LIB environment variable.

When PreQLB has processed your file(s), it will list on the display
all of the routines that were DECLAREd in each module but never used,
and any BASIC procedures in the module(s) that were never used. Since
this information may scroll off the screen too quickly for you to
read, PreQLB places this information in a file with the name
.EXT in your current directory.

What PREQLB Does

If PREQLB encounters an $INCLUDE statement in a module,
and the specified file includes a path name, that path will
be searched for the file. If no path name is included,
PREQLB will search the current directory for the specified
file. If the $INCLUDE file is not located, PREQLB will check
the DOS environment for the presence of the "INCLUDE"
environment variable. If found, PREQLB can search the
appropriate directories for $INCLUDE files.

In preparation for building the QLB, PREQLB will create
two files called PREQLB.RSP and PQ.BAT. The PQ.BAT batch
file is executed by PREQLB. The batch file invokes the LINK
program and the response file PREQLB.RSP provides all the
necessary information required to build the QLB. These files
are not deleted when the operation is finished unless you select
those options in the dialog box, so you can use them to rebuild
the library again, without running PREQLB.

PREQLB Speed Tips

\ Use the pre-processing commands in your code to
identify the support library, LINK libraries and any special
object modules your QLB will need. Then type:

PREQLB Filename

PREQLB will obtain all the information it needs
directly from your source code.

Using the pre-processing commands also means you will
have a permanent reference of what libraries and files are
needed for your program.

\ If you have a multi-module program where more than one
module uses the same $INCLUDE file(s), and the $INCLUDE
file(s) need only to be processed once, then make sure you
use the /Q switch. This switch can be passed on the command
line:

"PREQLB /Q"

or saved in a .CFG file from the dialog screen. If you
use this switch and receive an "Unresolved External" error
message from the linker, run PREQLB again without the /Q
switch and the Quick library should be created successfully.

\ If you are building QLB's for large programs that
utilize several LINK libraries and you have a RAM disk, copy
your LINK libraries, source code and PREQLB.EXE to the RAM
disk and run the program from that drive. The speed increase
can be very significant. To automate this process, create a
small batch file that copies the necessary files to the RAM
disk and optionally starts PREQLB.