ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/PROG/BASIC/LIBWIZ11.ZIP/LIBWIZ.DOC

Text File | 1991-03-31 | 13.0 KB | 274 lines

                 The Library Wizard's *BASIC Library Manager*           page 1
                 =------------------------------------------=
                                  Version 1.1

               LIBWIZ  Copyright (c) 1991  Thomas G. Hanlin III



This is LIBWIZ, a collection of utilities for managing BASIC libraries.  It
allows you to customize your libraries, selecting just the routines you want.
As well as creating a new library, LIBWIZ creates a corresponding "include"
file and a quick reference of the routines in the library.

LIBWIZ requires a special description file to work with a library.  My own
libraries come complete with description files (BASWIZ as of v1.5, PBClone as
of v1.4).  The LIBWIZU utility assists in creating description files for
libraries which don't have them.  The UNLIB utility allows you to extract all
.OBJ files from a .LIB, since LIBWIZ needs to work with the .OBJs directly.

The LIBWIZ collection is copyrighted and may be distributed only under the
following conditions:

   1) No fee of over $10.00 may be charged for distribution.  This
      restriction applies only to physical copies and is not meant to
      prevent distribution by telecommunication services.

   2) All LIBWIZ files must be distributed together in original, unaltered
      form.  This includes FILES.LST, LIBWIZ.DOC, LIBWIZ.EXE, LIBWIZ.NEW,
      LIBWIZU.EXE, LIB2OBJ.BAT and UNLIB.EXE.

You use these utilities at your own risk.  They have been tested by me on my
own computer, but I will not assume any responsibility for any problems which
they may cause you.  If you do encounter a problem, please let me know about
it, and I will do my best to verify and repair the error.

                              Table of Contents                         page 2



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

 The LIBWIZ Library Manager ............................................. 3

 The LIBWIZU .INF Maker ................................................. 5

 Merging Libraries ...................................................... 6

 Miscellaneous .......................................................... 7

                          The LIBWIZ Library Manager                    page 3



A library is a collection of routines, or partial programs, which can be used
directly as if they were part of the language itself.  A library may be
considered as a language extender.  Since library routines can be written in
a variety of languages, they may provide capabilities that are impossible
using the target language alone.  Even if the routines do something that is
within the capabilities of the target language, they are valuable in that
they are already tested and provide a standardized approach to whatever they
do.  The flexibility of libraries is a part of their power... and a problem!

The sheer number and variety of libraries available for BASIC is staggering.
Many libraries contain hundreds of different routines of all descriptions!
Sifting out just the routines you need is a hassle.  It's rarely practical to
combine entire libraries, either due the presence of routines by the same
name in different libraries or simply memory limitations.  In fact, my
shareware libraries BASWIZ and PBClone have each grown too large for BASIC to
deal with comfortably!

LIBWIZ provides a solution.  It allows you to choose just the routines you
want from a library, either individually or by category.  It resolves any
interdependencies to make sure the library contains all the routines it needs
to function.  As well as customizing the library itself, LIBWIZ creates new
"quick reference" and "include" files.

In order to do its stuff, LIBWIZ needs a ".INF" file which tells it about the
library to be customized.  Appropriate files are included with the current
versions of my own libraries.  The LIBWIZU utility can be used to create .INF
files for other libraries.  Aside from the .INF file, LIBWIZ needs to have
access to all of the .OBJ files that make up the library.  If your library
didn't come with the separate .OBJ files, you can usually extract them from
the .LIB using UNLIB.EXE and LIB2OBJ.BAT:

   UNLIB LibName
   LIB2OBJ

Note that I said "usually"!  On occasion, LIB refuses to recognize an object
name that UNLIB specifies.  I've inspected the library in these cases and the
object name appears correct.  I'm not sure why LIB doesn't cooperate.  The
problem is uncommon, however, and you'll probably never run across it.

                          The LIBWIZ Library Manager                    page 4



To use LIBWIZ, move to the directory which holds the .OBJ files and the .INF
file for the library you wish to customize.  The syntax is:

   LIBWIZ InfName LibName

...where "InfName" is the name of the .INF file and "LibName" is the name of
the desired .LIB library.  The option "/B" can be used to force a monochrome
display, although LIBWIZ will usually detect mono displays by itself.  I
don't -think- any further instructions are needed, as picking the routines is
a fairly simple process-- give it a go. If I've blundered in this regard,
please let me know, and I'll try to provide more detailed instructions!

When you are done, provided that you told LIBWIZ to go ahead and create a
library, it will create a number of files: an "include" (.BI) file, a revised
library info (.INF) file, a batch file (.BAT) and response file (.IN) to
actually make the library, and a quick reference (.REF) file.  These files
will all take the name you specified as "LibName".

LIBWIZ doesn't actually create a library itself, as mentioned above.  It
makes a batch file which tells LIB.EXE to create the desired library.  Only
the .LIB form of the library will be created.  This is the form of library
used when compiling from the command line or compiling to an .EXE from inside
the QuickBASIC environment.  If you expect to use the library inside the
QuickBASIC environment, you will need to make one in .QLB form as well.  This
can be done by typing something like the following:

   LINK Libname.LIB/Q/SE:512,,NUL,BQLB45;

The "BQLB45" part is only for QuickBASIC 4.5.  For QuickBASIC 4.0, you would
use either "BQLB40" or "BQLB41", depending on the particular QuickBASIC
revision-- use "DIR BQLB*" wherever your QuickBASIC libraries are kept to
find out which.  The BQLBxx.LIB file is provided with QuickBASIC.

If you are using the BASCOM "Professional Development System" v7.x, specify
"QBXQLB" instead of BQLBxx.



At the moment, LIBWIZ can handle up to 1,023 routines per library; up to 4
categories per routine; up to 255 categories total.

If you are processing a large library, have patience!  LIBWIZ has a lot of
work to do and may take a while to write all the files for a big library.
I'll improve its efficiency further in later versions.

                        The LIBWIZU .INF Maker                          page 5



The LIBWIZ library manager requires an .INF file to tell it about a library.
This file specifies routine names, categories, object modules, declarations
and descriptions.  If you don't have an .INF file for your library, the
LIBWIZU utility will handle most of the work of creating it for you.

To use LIBWIZU, move to the directory which holds the .OBJ files and .BI
(declaration) file for your library.  Type:

   LIBWIZU LibName

...where LibName is the name of the .BI file.  After chugging through the
declaration and object files, LIBWIZU will create an .INF file for the
library.  It will also report on Public routines (routines listed in the
declaration file, which are evidently intended for public use), Private
routines (routines which can be accessed but are not in the declaration file
and are assumed to be private for use by the public routines), and Orphans.
Private routines will not be shown by LIBWIZ, but will be pulled into a
library if needed by a public routine that was selected. Orphans are routines
which are listed in the declaration file but which do not appear in the
object files.  If there are any orphans, ORPHAN.LST will contain their names.

The .INF file created by LIBWIZU is not complete.  You must fill it in using
a text editor.  A description for each routine is a good idea, though not
strictly mandatory.  A description may be no longer than 70 characters.  Each
routine must be in at least one category or it is assumed to be private.  A
category can be as many as 16 characters.  A routine may be in up to four
categories (list them on the same line, separated by spaces).

Here's a sample entry for a routine (taken from PBCLONE.INF):

Name: CLOCK
Mod : CLOCK.OBJ
Decl: DECLARE SUB Clock (BYVAL DisplayOn%)
Type: Display Time
Desc: Keep a clock displayed on the screen

The entries are created in this order by default, but may be in any order as
long as the "Name:" definition is first.  If you would like to enter comments
into the file, use "Note:".  Such notes will be ignored by LIBWIZ.

If you need information in the .BI file other than just DECLAREs, such as
perhaps TYPE definitions, DEFINT or other statements, you must create an
additional file with an .HDR (header) extension.  If LIBWIZ detects the file
InfName.HDR, it will copy that file to LibName.HDR and "REM $INCLUDE" it in
LibName.BI before the DECLAREs for the library.

                               Merging Libraries                        page 6



In order to combine two libraries, you must have both libraries in .LIB form.
A new, combined .LIB can be created with the LIB.EXE utility that comes with
BASIC:

   LIB NewLib,+LibOne.LIB+LibTwo.LIB;

A combined .QLB can be created using LINK:

   LINK LibOne.LIB+LibTwo.LIB/Q/SE:512,NewLib.QLB,NUL,BQLB45;

As noted earlier, you may need to use a different name than "BQLB45".  If you
have QuickBASIC 4.0, it will be either "BQLB40" or "BQLB41".  If you have
BASCOM 7.x ("Professional Development System"), it will be "QBXQLB".

The /SE option is used to tell LINK it may have to deal with a lot more
routines than it expected by default.  If you get an overflow error, there
are too many routines than will fit into the .QLB library.  Take some out.

If both libraries have a routine by the same name, there will be a conflict.
You can fix this by changing the name of the routine in one of the libraries.
My OBJTOOL utility (available elsewhere) allows you to do this.

OBJTOOL, like LIBWIZ and LIBWIZU, expects to deal with .OBJ files rather than
with .LIB or .QLB files.  If you only have a .QLB library, there's nothing
you can do about this.  If you have a .LIB library, however, you can use the
LIB.EXE utility to remove .OBJ files from the library.

When LIB gives you the "Operations" prompt, use:

   *ObjName     to copy an .OBJ file from the library onto your disk
   -ObjName     to delete an .OBJ from the library
   +ObjName     to add an .OBJ to the library
   -+ObjName    to update an .OBJ file in the library from your disk

If you don't know the names of the .OBJ modules, ask LIB.  Just press <enter>
when it asks for Operations, then give it the name of a file when it prompts
for a "List file".  The resulting file will contain a list of the modules in
the library and what routines are in each module.

When combining libraries, don't forget to combine their .INF files as well!
It takes no more than joining the two files:

   COPY LibOne.INF+LibTwo.INF NewLib.INF

You can join the .REF and .BI files the same way, or use LIBWIZ to generate
new .REF and .BI files from the new .INF file.

                                 Miscellaneous                          page 7



Note that LIBWIZ places certain limitations on the valid routine names in
order to make it possible to screen out names that are in BASIC's runtime
libraries.  Names may not contain dollar signs, start with underscores, end
with "QQ", or contain lowercase letters.  It is important to understand that
BASIC normally converts routine names to uppercase and removes any type
specifiers from function names, so BASIC is not normally capable of
generating routine names that would break these restrictions (except for
routines ending in QQ, of course).  This is more of a caution for routines
that may have been written in other languages, such as assembly or C.

The LIBWIZ utilities were written using QuickBASIC 4.5 and routines from my
BASWIZ and PBClone libraries.  They were linked with Crescent's PDQ library,
which made the .EXE files much smaller.

This initial version of LIBWIZ is somewhat rudimentary.  The interface will
improve in later versions.  I also have additional functions and utilities
planned.  Of course, I will be delighted to hear your ideas on how to make
LIBWIZ better.  Let me hear from you!

Sampler disks are available from me for $5.00.  These disks contain the
latest versions of many of my shareware and free works, including BASWIZ,
LIBWIZ, OBJTOOL and PBClone.  Please specify disk size.

   Thomas G. Hanlin III
   3544 E. Southern Ave. #104
   Mesa, AZ 85204