QBMAP.EXE 3.5 (C) 1988-89 Larry B. Crimmins. All rights reserved.
==================================================================
05/14/89

Author: Larry B. Crimmins (Compuserve: 74745,1630)
3516 East Oak Street
Phoenix, Arizona 85008-2121


NOTE: 1. Significant changes from the previous version of this file are now
indicated with a ">" in column 1.

2. Throughout this file, the term "QB4+" indicates all versions of
MS QuickBASIC 4 (i.e. 4.0, 4.00a, 4.00b, 4.5, etc.) as well as
MS BASCOM 6.0 and it's recent upgrades.


Let's get the BUSINESS out of the way:
-------------------------------------

QBMAP is NOT placed in the public domain. It is FREEWARE for personal
(i.e. nonprofit) use, and SHAREWARE for commercial use.

This means that you may copy, distribute, and/or use QBMAP all you wish,
as long as the following restrictions are observed:

1. This file, "QBMAP.DOC" (complete and unedited), MUST accompany any
distributions of QBMAP.EXE.

2. If you are going to distribute QBMAP.EXE, it must not be hacked,
edited, patched, or otherwise sullied.

3. If you don't profit (financially) from the use of this program, you
don't owe me anything. However...

> 4. If you use QBMAP in your work, send me $35.00.
> (Bowing to public pressure, I have increased the charge for QBMAP.
> Thank you, loyal public.)

5. If you distribute QBMAP for profit, send me one-half of the unit
> sale price, or $35.00, whichever is greater, for each copy sold.

6. Use/distribution by and for formal educational facilities or users
groups is exempted from this license fee, as long as fees gained do
not exceed media and copying expenses.


DISCLAIMER: QBMAP will probably not run on Timex-Sinclairs, Altairs,
Imsais, or Crays. In fact, in today's litigious society, I make no claims
or guarantees for QBMAP at all, and your use of this program indicates

that you agree to hold me blameless for any nasty things you may experience
as a result.

However, I do guarantee that QBMAP, as it was created and distributed by me,
contained no viruses, intentional bad habits, or weird mischief of any sort.



Ok, what is QBMAP?
-----------------

QBMAP is a multi-module (multi-file), BASIC-language, source code mapping
utility. Actually, since the use of $INCLUDEs can obscure the identification
of separately compilable "modules" in a program's structure, QBMAP's output
report is based on source code "files" rather than discrete "modules".

The term "module-level" is used throughout this document to refer to source
code statements within a file which are not inside any subprogram or
function definition block.

Unlike "cross-referencing" utilities, QBMAP doesn't report on variables or
line numbers. It scans an unlimited number of BASIC source files, and
produces a formatted report, by source file, of:

1. Subprogram CALLs at module-level.
- Identified as INTernal or EXTernal to the file.
- Both QB3-style "CALLs" and QB4+ "declared subs" (w/o CALLs) are
supported.

2. FUNCTION calls at module-level.
- Identified as INTernal or EXTernal to the file.
> - ALL function definition styles are now supported.

3. CHAINs at module-level.

4. RUNs at module-level.

5. $INCLUDEs at module-level.

6. Subprogram definitions embedded in each file.

7. Function definitions embedded in each file.

8. Items 1 through 5 within the scope of each embedded subprogram.

9. Items 1 through 5 within the scope of each embedded function.


New in version 3.0:

10. Other objects (files, subprograms, or functions) which $INCLUDE the
current file.

11. Other objects which CHAIN TO the current file.

12. Other objects which RUN the current file.

13. Other objects which CALL the current subprogram or function.


New in version 3.1:

14. QBMAP now reports subprogram and function call counts. These counts
represent the number of times an object calls a particular subprogram or
function, and the number of times a subprogram or function is called by
each other file, subprogram, or function.

15. For easier identification of orphan code and other structural problems,
QBMAP now reports "(none)" under the "CALLED BY", "$INCLUDED BY",
"CHAINED FROM", and "RUN BY" sections, if no appropriate references
have been found.

> New in version 3.5:

> 16. QBMAP now supports single-line functions. (And I was surprised at how
> many people demanded that feature. Just goes to show...)

> 17. QBMAP is now approximately 22% faster overall. (Your mileage may vary.)



Source code restrictions:
-------------------------------------------

I tried not to make any but the most general assumptions about your coding
style. But, for efficiency, certain restrictions are required:

Note: Upper or lower case usage is irrelevant to QBMAP.

1. No more than 500 occurrences of each of the detected items are allowed
within any one subprogram, function, or at the module-level code of any
one file.

Also, no more than 500 *unique* QB4+ declared subprograms OR 500 *unique*
QB4+ "FUNCTION" definitions are allowed within all of the source files
matched by a wildcarded source-filespec.

2. No more than 250 files, subprograms, and functions may CALL, $INCLUDE,
CHAIN TO, or RUN, any one file, subprogram, or function.

The restrictions in the above two items were chosen somewhat arbitrarily.
If anyone has a serious problem with either of them, please notify me.
I *may* be able to squeeze a bit more room for them.

4. For the object of a RUN or CHAIN to be identified, a quoted constant must
follow the keyword. In other words, RUN a$ won't be recognized,
but RUN "foobar.exe" will work just fine.

> A RUN or CHAIN followed by a variable, will now be reported as
> "(variable)" under the RUN or CHAIN report heading.

5. The extension ".EXE" will be forced on the object of a RUN or CHAIN.
So, CHAIN "foobar" and CHAIN "foobar.exe" will both be considered
CHAINs to "foobar.BAS" (see next paragraph).

6. When QBMAP attempts to cross-reference a RUN or CHAIN command, the
filename is converted to a ".BAS" extension. If your source code files
do not use the ".BAS" extension, RUNs and CHAINs will not be properly
identified. No other reported objects are affected by this restriction.



General information:
-------------------

QBMAP MAY work for non-Microsoft BASIC source code, but I don't guarantee it.
If anyone cares to send me a description of the coding syntax for the listed
items under other compilers, I'd be happy to include support for them in a
future release.

The number of files matched by a wildcarded source-filespec on the command
line is practically unlimited.

QBMAP 3.5 is somewhat broadly designed, but the output format is fixed.
There are currently no options or switches to control output format.
Version 4.0 may address this issue if alternative formats are requested.

QBMAP 2.0 would directly answer the questions:
"What does this file (or function or subprogram) CALL/CHAIN/RUN/or INCLUDE?"
"What subprograms and functions does this file contain?"
"Which file contains this subprogram or function?"

QBMAP 3.0 additionally answered these questions:
"What other files (or functions or subprograms) CALL/CHAIN/RUN/or INCLUDE
*this* file, function, or subprogram?"
"Where is each subprogram or function which is called by this file,
subprogram, or function?"
"Do I have any *orphan* (unused) subprograms or functions?"

QBMAP 3.1 also answered:
"How many times does this subprogram or function CALL a particular
subprogram or function?"
"How many times is *this* subprogram or function CALLED BY a particular
file, subprogram, or function?"

QBMAP 3.2, 3.3, and 3.4 fixed 2 minor bugs, increased internal workspace,
and allowed larger QB4 or BC6 systems to be QBMAPed.

QBMAP 3.5 increased the speed of the program overall, and added support for
single-line functions.

The output report details each file in the order it was encountered in the
directory. If you want the files sorted alphabetically (for example),
sort the directory before running QBMAP.

Embedded subprograms and functions are reported in the order they are
encountered in their files. This was done to more closely match the
report order with the sequence of procedures you have used in your source
files.



Command line syntax:
-------------------


QBMAP [/FxSy] afs ufs


Where:

/FxSy = OPTIONAL QB3 or QB4+ coding syntax options. Default: /F3S3

If options are to be used:

1. "/", "F" (Functions), and "S" (Subprograms) are required.

2. The x and y positions must contain:

For x: 3 = QB3 "DEF FNname" function definitions only
4 = QB4+ "FUNCTION" function definitions only
B = Both

For y: 3 = QB3 unDECLARED subprograms only - CALL used
4 = QB4+ DECLARED subprograms only - no CALLs
B = Both

Note: Any use of "4" or "B" will increase processing time.

afs = ambiguous filespec (i.e. wildcards ok) - SOURCE code file(s)
ufs = unambiguous filespec (i.e. no wildcards) - TARGET map file


Upper or lower case are identical in all options and filespecs.



Error messages:
--------------

The following error messages may appear while running QBMAP. The last
is my fault, but all the rest indicate problems with your command line
entry, your hardware, or your source code.


"ERROR: No input file(s) found."

Description: No source code files could be found which match the source
filespec (possibly including wildcards) which you entered
on the command line.

Solution: Enter a valid source code filespec on the command line.


"ERROR: Invalid option."

Description: One of the source code format options was entered
incorrectly on the command line.

Solution: Enter the correct 5-position option string: "/FxSy", where
"x" and "y" may each be "3", "4", or "B".
See "Command line syntax", above.


"ERROR: Bad target filename."

Description: You entered an invalid DOS filespec as the target (output)
filespec on the command line.

Solution: Enter a valid target filespec on the command line.


"ERROR: Target disk full."

Description: The disk identified by your target (output) filespec is
full.

Solution: Clear some space on the target disk, or use another disk.


"ERROR: Source disk media error."
"ERROR: Target disk media error."

Description: A physical flaw was detected on either your source or
target disk.

Solution: Repair or replace the disk. Good luck.


"ERROR: Source drive not ready."
"ERROR: Target drive not ready."

Description: This is (hopefully) a floppy drive error. Either your
source or target floppy disk drive is empty, or the door
is open.

Solution: Put a disk in the drive, or close the door, or both.


"ERROR: Out of memory."

Description: There is not enough free memory to run QBMAP.

Solution: Install more memory, or remove some memory-resident
programs.


"ERROR: Source path not found."
"ERROR: Target path not found."

Description: DOS was unable to find your source or target path.

Solution: Correct your command line entry, or create the necessary
path.


"ERROR: Source path/file access error."
"ERROR: Target path/file access error."

Description: DOS choked on your source or target path.

Solution: Depending on your system setup, the answer could be simple
or complex. Networking issues complicate the matter. Try
using a different path.


"ERROR: Target disk is write-protected."

Description: This is (hopefully) a floppy drive error. Your target disk
is write-protected.

Solution: Remove the write-protection from the target disk, or use
another disk.


"ERROR: Target directory full or CONFIG.SYS FILES= too small."

Description: Your target directory is full; OR, the "FILES=x" entry in
your CONFIG.SYS file is too small. (For reference, QBMAP
opens only two (2) files simultaneously.)

Solution: Specify a non-full target directory; OR, make sure your
CONFIG.SYS file contains a "FILES=x" entry, where x is at
least 2. (For most systems, 15 or 20 is optimum.)


"ERROR: Item count (500) exceeded for {CALL, FN, RUN, or CHAIN}."

Description: 1. More than 500 CALLs, RUNs, CHAINs, or function calls
were encountered in a single subprogram (or function) or in
the module-level code of a single file.

2. If this message was received during the "Scanning" phase
of QB4+ processing, it means there are more than 500
> *unique* functions OR *unique* declared subprograms in ALL
the source files specified by the source filespec on the
command line.


Solution: 1. The module name shown on the line immediately above this
error message is the offending module. Split it up.
It's probably too large to compile anyway. (However, if
you really want a custom version of QBMAP for such
extremely large modules, just contact me. I'm sure we can
work something out.)

> 2. If received during "Scanning": The only solution is to
> contact me. I *may* be able to increase the 500 limit
> slightly. Sorry.


"ERROR: Weird source code. Cannot process that file."

Description: This one really isn't my fault. Really.

Solution: Maybe one or more of your source files are not ASCII text
files. Other than that, you're on your own. Sorry.


"ERROR: "INTERNAL ERROR # x/y"

Description: This indicates a real live program bug. Please notify me
if you receive this message.

Solution: More caffeine.



Revision history:
----------------

9/88: v1.0 > Initial release.

10/88: v1.1 > Fixed problem with certain BASIC keywords embedded in
strings and comments. Now being skipped properly.
> Made error messages more meaningful and consistent.

10/88: v1.2 > Subprogram header lines containing no characters after
the subprogram name (no STATIC, no parameter list, no
comment, no nothing) were choking the program. Fixed.

10/88: v1.3 > Tabs, line numbers, and line labels were not being handled
properly on the same line with certain keywords. Fixed.

10/88: v2.0 > Added support for QB4/BC6 declared subprograms and
function definitions. Embedded function stats added to
report. Identification of internal/external functions
added to report. Other minor cosmetic changes.

1/89: v3.0 > Added a post-processor phase which resolves "reverse
references". In other words, in addition to reporting which
objects are CHAINed TO, $INCLUDEd, RUN, and CALLed by each
file, sub, or function, QBMAP now also reports CHAINED FROM,
$INCLUDED BY, RUN BY, and CALLED BY objects.
> Added a location indicator to EACH sub/function call for
easier cross-referencing.

1/89: v3.1 > Added a "(none)" line for each of these sections, if empty:
CALLED BY, $INCLUDED BY, CHAINED FROM, and RUN BY.
> Added CALLs and CALLED BY counts for each subprogram and
function.
> Now concatenating "DEF FN" with the trailing function name,
if needed.


1/89: v3.2 > Fixed a bug in the proper identification of QB4+
DECLAREd functions and subprograms.

2/89: v3.3 > Increased internal workspace.

4/89: v3.4 > Fixed a bug which caused QB4+ subprogram "declarations" to
be included in the count of subprogram "calls".
> The QB4+ "scanning" phase was actually limited to far less
than the documented 500 declared subprograms or functions due
to duplicate definitions being retained until all files were
scanned. QBMAP 3.4 now handles more complex QB4+ systems by
eliminating duplicate declares or functions after scanning
each file.

> 5/89: v3.5 > Added support for single-line functions.
> > QBMAP is now somewhat faster. Tests on source code which
> uses only QB3-style functions and subprograms indicate a
> 22% speed increase. While tests on source code using QB4+
> declared functions and implicit calls to subprograms indicate
> only a 15% speed increase. Hopefully, your results will at
> least fall within this range.


==========================================================================


One last item: QBMAP, version 3.5, is a very busy little program. It must
cross-check every file, subprogram, and function in your source files. As
such, it may take awhile to complete its work. The relatively large system
for which I originally wrote this utility is comprised of over 100 source
files and nearly 100 subprograms and functions. It totals over 2 megabytes
of source code. On a 16 Mhz 80386 machine, QBMAP 3.2 took about 10 minutes
to map that system. It would, of course, take longer on an 8088 or 80286.

However, even if QBMAP requires an hour or more to map your source files,
the resulting map report is an extremely helpful document for future
maintenance of your system. Also, QBMAP isn't the sort of utility you would
need to re-run very often. So start it up, and go for another cup of coffee.
The longer it takes to run, the more you probably need the break anyway.

- end -