home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 15 / CDACTUAL15.iso / cdactual / program / basic / QBMAP35.ZIP / QBMAP.DOC next >
Encoding:
Text File  |  1989-05-14  |  18.9 KB  |  488 lines
  1.  
  2. QBMAP.EXE 3.5 (C) 1988-89 Larry B. Crimmins.  All rights reserved.
  3. ==================================================================
  4. 05/14/89
  5.  
  6. Author:  Larry B. Crimmins   (Compuserve: 74745,1630)
  7.          3516 East Oak Street
  8.          Phoenix, Arizona  85008-2121
  9.  
  10.  
  11. NOTE: 1. Significant changes from the previous version of this file are now
  12.          indicated with a ">" in column 1.
  13.  
  14.       2. Throughout this file, the term "QB4+" indicates all versions of
  15.          MS QuickBASIC 4 (i.e. 4.0, 4.00a, 4.00b, 4.5, etc.) as well as
  16.          MS BASCOM 6.0 and it's recent upgrades.
  17.  
  18.  
  19. Let's get the BUSINESS out of the way:
  20. -------------------------------------
  21.  
  22.   QBMAP is NOT placed in the public domain.  It is FREEWARE for personal
  23.   (i.e. nonprofit) use, and SHAREWARE for commercial use.
  24.  
  25.   This means that you may copy, distribute, and/or use QBMAP all you wish,
  26.   as long as the following restrictions are observed:
  27.  
  28.     1. This file, "QBMAP.DOC" (complete and unedited), MUST accompany any
  29.        distributions of QBMAP.EXE.
  30.  
  31.     2. If you are going to distribute QBMAP.EXE, it must not be hacked,
  32.        edited, patched, or otherwise sullied.
  33.  
  34.     3. If you don't profit (financially) from the use of this program, you
  35.        don't owe me anything.  However...
  36.  
  37. >   4. If you use QBMAP in your work, send me $35.00.
  38. >      (Bowing to public pressure, I have increased the charge for QBMAP.
  39. >      Thank you, loyal public.)
  40.  
  41.     5. If you distribute QBMAP for profit, send me one-half of the unit
  42. >      sale price, or $35.00, whichever is greater, for each copy sold.
  43.  
  44.     6. Use/distribution by and for formal educational facilities or users
  45.        groups is exempted from this license fee, as long as fees gained do
  46.        not exceed media and copying expenses.
  47.  
  48.  
  49.   DISCLAIMER:  QBMAP will probably not run on Timex-Sinclairs, Altairs,
  50.   Imsais, or Crays.  In fact, in today's litigious society, I make no claims
  51.   or guarantees for QBMAP at all, and your use of this program indicates
  52.   that you agree to hold me blameless for any nasty things you may experience
  53.   as a result.
  54.  
  55.   However, I do guarantee that QBMAP, as it was created and distributed by me,
  56.   contained no viruses, intentional bad habits, or weird mischief of any sort.
  57.  
  58.  
  59.  
  60. Ok, what is QBMAP?
  61. -----------------
  62.  
  63.   QBMAP is a multi-module (multi-file), BASIC-language, source code mapping
  64.   utility.  Actually, since the use of $INCLUDEs can obscure the identification
  65.   of separately compilable "modules" in a program's structure, QBMAP's output
  66.   report is based on source code "files" rather than discrete "modules".
  67.  
  68.   The term "module-level" is used throughout this document to refer to source
  69.   code statements within a file which are not inside any subprogram or
  70.   function definition block.
  71.  
  72.   Unlike "cross-referencing" utilities, QBMAP doesn't report on variables or
  73.   line numbers.  It scans an unlimited number of BASIC source files, and
  74.   produces a formatted report, by source file, of:
  75.  
  76.     1. Subprogram CALLs at module-level.
  77.          - Identified as INTernal or EXTernal to the file.
  78.          - Both QB3-style "CALLs" and QB4+ "declared subs" (w/o CALLs) are
  79.            supported.
  80.  
  81.     2. FUNCTION calls at module-level.
  82.          - Identified as INTernal or EXTernal to the file.
  83. >        - ALL function definition styles are now supported.
  84.  
  85.     3. CHAINs at module-level.
  86.  
  87.     4. RUNs at module-level.
  88.  
  89.     5. $INCLUDEs at module-level.
  90.  
  91.     6. Subprogram definitions embedded in each file.
  92.  
  93.     7. Function definitions embedded in each file.
  94.  
  95.     8. Items 1 through 5 within the scope of each embedded subprogram.
  96.  
  97.     9. Items 1 through 5 within the scope of each embedded function.
  98.  
  99.  
  100.    New in version 3.0:
  101.  
  102.    10. Other objects (files, subprograms, or functions) which $INCLUDE the
  103.        current file.
  104.  
  105.    11. Other objects which CHAIN TO the current file.
  106.  
  107.    12. Other objects which RUN the current file.
  108.  
  109.    13. Other objects which CALL the current subprogram or function.
  110.  
  111.  
  112.    New in version 3.1:
  113.  
  114.    14. QBMAP now reports subprogram and function call counts.  These counts
  115.        represent the number of times an object calls a particular subprogram or
  116.        function, and the number of times a subprogram or function is called by
  117.        each other file, subprogram, or function.
  118.  
  119.    15. For easier identification of orphan code and other structural problems,
  120.        QBMAP now reports "(none)" under the "CALLED BY", "$INCLUDED BY",
  121.        "CHAINED FROM", and "RUN BY" sections, if no appropriate references
  122.        have been found.
  123.  
  124. >  New in version 3.5:
  125.  
  126. >  16. QBMAP now supports single-line functions.  (And I was surprised at how
  127. >      many people demanded that feature.  Just goes to show...)
  128.  
  129. >  17. QBMAP is now approximately 22% faster overall. (Your mileage may vary.)
  130.  
  131.  
  132.  
  133. Source code restrictions:
  134. -------------------------------------------
  135.  
  136.   I tried not to make any but the most general assumptions about your coding
  137.   style.  But, for efficiency, certain restrictions are required:
  138.  
  139.   Note: Upper or lower case usage is irrelevant to QBMAP.
  140.  
  141.   1. No more than 500 occurrences of each of the detected items are allowed
  142.      within any one subprogram, function, or at the module-level code of any
  143.      one file.
  144.  
  145.      Also, no more than 500 *unique* QB4+ declared subprograms OR 500 *unique*
  146.      QB4+ "FUNCTION" definitions are allowed within all of the source files
  147.      matched by a wildcarded source-filespec.
  148.  
  149.   2. No more than 250 files, subprograms, and functions may CALL, $INCLUDE,
  150.      CHAIN TO, or RUN, any one file, subprogram, or function.
  151.  
  152.   The restrictions in the above two items were chosen somewhat arbitrarily.
  153.   If anyone has a serious problem with either of them, please notify me.
  154.   I *may* be able to squeeze a bit more room for them.
  155.  
  156.   4. For the object of a RUN or CHAIN to be identified, a quoted constant must
  157.      follow the keyword.  In other words,  RUN a$  won't be recognized,
  158.      but  RUN "foobar.exe"  will work just fine.
  159.  
  160. >    A RUN or CHAIN followed by a variable, will now be reported as
  161. >    "(variable)" under the RUN or CHAIN report heading.
  162.  
  163.   5. The extension ".EXE" will be forced on the object of a RUN or CHAIN.
  164.      So,  CHAIN "foobar"  and  CHAIN "foobar.exe"  will both be considered
  165.      CHAINs to  "foobar.BAS"  (see next paragraph).
  166.  
  167.   6. When QBMAP attempts to cross-reference a RUN or CHAIN command, the
  168.      filename is converted to a ".BAS" extension.  If your source code files
  169.      do not use the ".BAS" extension, RUNs and CHAINs will not be properly
  170.      identified.  No other reported objects are affected by this restriction.
  171.  
  172.  
  173.  
  174. General information:
  175. -------------------
  176.  
  177.   QBMAP MAY work for non-Microsoft BASIC source code, but I don't guarantee it.
  178.   If anyone cares to send me a description of the coding syntax for the listed
  179.   items under other compilers, I'd be happy to include support for them in a
  180.   future release.
  181.  
  182.   The number of files matched by a wildcarded source-filespec on the command
  183.   line is practically unlimited.
  184.  
  185.   QBMAP 3.5 is somewhat broadly designed, but the output format is fixed.
  186.   There are currently no options or switches to control output format.
  187.   Version 4.0 may address this issue if alternative formats are requested.
  188.  
  189.   QBMAP 2.0 would directly answer the questions:
  190.    "What does this file (or function or subprogram) CALL/CHAIN/RUN/or INCLUDE?"
  191.    "What subprograms and functions does this file contain?"
  192.    "Which file contains this subprogram or function?"
  193.  
  194.   QBMAP 3.0 additionally answered these questions:
  195.    "What other files (or functions or subprograms) CALL/CHAIN/RUN/or INCLUDE
  196.     *this* file, function, or subprogram?"
  197.    "Where is each subprogram or function which is called by this file,
  198.     subprogram, or function?"
  199.    "Do I have any *orphan* (unused) subprograms or functions?"
  200.  
  201.   QBMAP 3.1 also answered:
  202.    "How many times does this subprogram or function CALL a particular
  203.     subprogram or function?"
  204.    "How many times is *this* subprogram or function CALLED BY a particular
  205.     file, subprogram, or function?"
  206.  
  207.   QBMAP 3.2, 3.3, and 3.4 fixed 2 minor bugs, increased internal workspace,
  208.   and allowed larger QB4 or BC6 systems to be QBMAPed.
  209.  
  210.   QBMAP 3.5 increased the speed of the program overall, and added support for
  211.   single-line functions.
  212.  
  213.   The output report details each file in the order it was encountered in the
  214.   directory.  If you want the files sorted alphabetically (for example),
  215.   sort the directory before running QBMAP.
  216.  
  217.   Embedded subprograms and functions are reported in the order they are
  218.   encountered in their files.  This was done to more closely match the
  219.   report order with the sequence of procedures you have used in your source
  220.   files.
  221.  
  222.  
  223.  
  224. Command line syntax:
  225. -------------------
  226.  
  227.  
  228.   QBMAP [/FxSy] afs ufs
  229.  
  230.  
  231.   Where:
  232.  
  233.   /FxSy  = OPTIONAL QB3 or QB4+ coding syntax options. Default: /F3S3
  234.  
  235.            If options are to be used:
  236.  
  237.               1. "/", "F" (Functions), and "S" (Subprograms) are required.
  238.  
  239.               2. The x and y positions must contain:
  240.  
  241.                  For x: 3 = QB3  "DEF FNname" function definitions only
  242.                         4 = QB4+ "FUNCTION"   function definitions only
  243.                         B = Both
  244.  
  245.                  For y: 3 = QB3  unDECLARED subprograms only - CALL used
  246.                         4 = QB4+   DECLARED subprograms only - no CALLs
  247.                         B = Both
  248.  
  249.            Note: Any use of "4" or "B" will increase processing time.
  250.  
  251.     afs  =   ambiguous filespec (i.e. wildcards ok) - SOURCE code file(s)
  252.     ufs  = unambiguous filespec (i.e. no wildcards) - TARGET map file
  253.  
  254.  
  255.   Upper or lower case are identical in all options and filespecs.
  256.  
  257.  
  258.  
  259. Error messages:
  260. --------------
  261.  
  262.   The following error messages may appear while running QBMAP.  The last
  263.   is my fault, but all the rest indicate problems with your command line
  264.   entry, your hardware, or your source code.
  265.  
  266.  
  267.   "ERROR: No input file(s) found."
  268.  
  269.      Description:  No source code files could be found which match the source
  270.                    filespec (possibly including wildcards) which you entered
  271.                    on the command line.
  272.  
  273.         Solution:  Enter a valid source code filespec on the command line.
  274.  
  275.  
  276.   "ERROR: Invalid option."
  277.  
  278.      Description:  One of the source code format options was entered
  279.                    incorrectly on the command line.
  280.  
  281.         Solution:  Enter the correct 5-position option string: "/FxSy", where
  282.                    "x" and "y" may each be "3", "4", or "B".
  283.                    See "Command line syntax", above.
  284.  
  285.  
  286.   "ERROR: Bad target filename."
  287.  
  288.      Description:  You entered an invalid DOS filespec as the target (output)
  289.                    filespec on the command line.
  290.  
  291.         Solution:  Enter a valid target filespec on the command line.
  292.  
  293.  
  294.   "ERROR: Target disk full."
  295.  
  296.      Description:  The disk identified by your target (output) filespec is
  297.                    full.
  298.  
  299.         Solution:  Clear some space on the target disk, or use another disk.
  300.  
  301.  
  302.   "ERROR: Source disk media error."
  303.   "ERROR: Target disk media error."
  304.  
  305.      Description:  A physical flaw was detected on either your source or
  306.                    target disk.
  307.  
  308.         Solution:  Repair or replace the disk.  Good luck.
  309.  
  310.  
  311.   "ERROR: Source drive not ready."
  312.   "ERROR: Target drive not ready."
  313.  
  314.      Description:  This is (hopefully) a floppy drive error.  Either your
  315.                    source or target floppy disk drive is empty, or the door
  316.                    is open.
  317.  
  318.         Solution:  Put a disk in the drive, or close the door, or both.
  319.  
  320.  
  321.   "ERROR: Out of memory."
  322.  
  323.      Description:  There is not enough free memory to run QBMAP.
  324.  
  325.         Solution:  Install more memory, or remove some memory-resident
  326.                    programs.
  327.  
  328.  
  329.   "ERROR: Source path not found."
  330.   "ERROR: Target path not found."
  331.  
  332.      Description:  DOS was unable to find your source or target path.
  333.  
  334.         Solution:  Correct your command line entry, or create the necessary
  335.                    path.
  336.  
  337.  
  338.   "ERROR: Source path/file access error."
  339.   "ERROR: Target path/file access error."
  340.  
  341.      Description:  DOS choked on your source or target path.
  342.  
  343.         Solution:  Depending on your system setup, the answer could be simple
  344.                    or complex.  Networking issues complicate the matter.  Try
  345.                    using a different path.
  346.  
  347.  
  348.   "ERROR: Target disk is write-protected."
  349.  
  350.      Description:  This is (hopefully) a floppy drive error.  Your target disk
  351.                    is write-protected.
  352.  
  353.         Solution:  Remove the write-protection from the target disk, or use
  354.                    another disk.
  355.  
  356.  
  357.   "ERROR: Target directory full or CONFIG.SYS FILES= too small."
  358.  
  359.      Description:  Your target directory is full; OR, the "FILES=x" entry in
  360.                    your CONFIG.SYS file is too small.  (For reference, QBMAP
  361.                    opens only two (2) files simultaneously.)
  362.  
  363.         Solution:  Specify a non-full target directory; OR, make sure your
  364.                    CONFIG.SYS file contains a "FILES=x" entry, where x is at
  365.                    least 2.  (For most systems, 15 or 20 is optimum.)
  366.  
  367.  
  368.   "ERROR: Item count (500) exceeded for {CALL, FN, RUN, or CHAIN}."
  369.  
  370.      Description:  1. More than 500 CALLs, RUNs, CHAINs, or function calls
  371.                    were encountered in a single subprogram (or function) or in
  372.                    the module-level code of a single file.
  373.  
  374.                    2. If this message was received during the "Scanning" phase
  375.                    of QB4+ processing, it means there are more than 500
  376. >                  *unique* functions OR *unique* declared subprograms in ALL
  377.                    the source files specified by the source filespec on the
  378.                    command line.
  379.  
  380.  
  381.         Solution:  1. The module name shown on the line immediately above this
  382.                    error message is the offending module.  Split it up.
  383.                    It's probably too large to compile anyway.  (However, if
  384.                    you really want a custom version of QBMAP for such
  385.                    extremely large modules, just contact me.  I'm sure we can
  386.                    work something out.)
  387.  
  388. >                  2. If received during "Scanning": The only solution is to
  389. >                  contact me.  I *may* be able to increase the 500 limit
  390. >                  slightly.  Sorry.
  391.  
  392.  
  393.   "ERROR: Weird source code. Cannot process that file."
  394.  
  395.      Description:  This one really isn't my fault.  Really.
  396.  
  397.         Solution:  Maybe one or more of your source files are not ASCII text
  398.                    files.  Other than that, you're on your own.  Sorry.
  399.  
  400.  
  401.   "ERROR: "INTERNAL ERROR # x/y"
  402.  
  403.      Description:  This indicates a real live program bug.  Please notify me
  404.                    if you receive this message.
  405.  
  406.         Solution:  More caffeine.
  407.  
  408.  
  409.  
  410. Revision history:
  411. ----------------
  412.  
  413.     9/88: v1.0 > Initial release.
  414.  
  415.    10/88: v1.1 > Fixed problem with certain BASIC keywords embedded in
  416.                  strings and comments.  Now being skipped properly.
  417.                > Made error messages more meaningful and consistent.
  418.  
  419.    10/88: v1.2 > Subprogram header lines containing no characters after
  420.                  the subprogram name (no STATIC, no parameter list, no
  421.                  comment, no nothing) were choking the program.  Fixed.
  422.  
  423.    10/88: v1.3 > Tabs, line numbers, and line labels were not being handled
  424.                  properly on the same line with certain keywords.  Fixed.
  425.  
  426.    10/88: v2.0 > Added support for QB4/BC6 declared subprograms and
  427.                  function definitions.  Embedded function stats added to
  428.                  report.  Identification of internal/external functions
  429.                  added to report.  Other minor cosmetic changes.
  430.  
  431.     1/89: v3.0 > Added a post-processor phase which resolves "reverse
  432.                  references".  In other words, in addition to reporting which
  433.                  objects are CHAINed TO, $INCLUDEd, RUN, and CALLed by each
  434.                  file, sub, or function, QBMAP now also reports CHAINED FROM,
  435.                  $INCLUDED BY, RUN BY, and CALLED BY objects.
  436.                > Added a location indicator to EACH sub/function call for
  437.                  easier cross-referencing.
  438.  
  439.     1/89: v3.1 > Added a "(none)" line for each of these sections, if empty:
  440.                  CALLED BY, $INCLUDED BY, CHAINED FROM, and RUN BY.
  441.                > Added CALLs and CALLED BY counts for each subprogram and
  442.                  function.
  443.                > Now concatenating "DEF FN" with the trailing function name,
  444.                  if needed.
  445.  
  446.  
  447.     1/89: v3.2 > Fixed a bug in the proper identification of QB4+
  448.                  DECLAREd functions and subprograms.
  449.  
  450.     2/89: v3.3 > Increased internal workspace.
  451.  
  452.     4/89: v3.4 > Fixed a bug which caused QB4+ subprogram "declarations" to
  453.                  be included in the count of subprogram "calls".
  454.                > The QB4+ "scanning" phase was actually limited to far less
  455.                  than the documented 500 declared subprograms or functions due
  456.                  to duplicate definitions being retained until all files were
  457.                  scanned.  QBMAP 3.4 now handles more complex QB4+ systems by
  458.                  eliminating duplicate declares or functions after scanning
  459.                  each file.
  460.  
  461. >   5/89: v3.5 > Added support for single-line functions.
  462. >              > QBMAP is now somewhat faster.  Tests on source code which
  463. >                uses only QB3-style functions and subprograms indicate a
  464. >                22% speed increase.  While tests on source code using QB4+
  465. >                declared functions and implicit calls to subprograms indicate
  466. >                only a 15% speed increase.  Hopefully, your results will at
  467. >                least fall within this range.
  468.  
  469.  
  470. ==========================================================================
  471.  
  472.  
  473. One last item:  QBMAP, version 3.5, is a very busy little program.  It must
  474. cross-check every file, subprogram, and function in your source files.  As
  475. such, it may take awhile to complete its work.  The relatively large system
  476. for which I originally wrote this utility is comprised of over 100 source
  477. files and nearly 100 subprograms and functions.  It totals over 2 megabytes
  478. of source code.  On a 16 Mhz 80386 machine, QBMAP 3.2 took about 10 minutes
  479. to map that system.  It would, of course, take longer on an 8088 or 80286.
  480.  
  481. However, even if QBMAP requires an hour or more to map your source files,
  482. the resulting map report is an extremely helpful document for future
  483. maintenance of your system.  Also, QBMAP isn't the sort of utility you would
  484. need to re-run very often.  So start it up, and go for another cup of coffee.
  485. The longer it takes to run, the more you probably need the break anyway.
  486.  
  487.                               - end -
  488.