Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/MAPOVLAY.ZIP/MAP.DOC

Text File | 1986-05-23 | 7.5 KB | 130 lines

Documentation for MAP.PAS
-------------------------

Version 1.7 for CP/M 80 and PC/MS-DOS Turbo Pascal Version 3
  by Scott Bussinger -- May 1986
     Professional Practice Systems, Inc.
     110 S. 131st Street
     Tacoma, WA  98444
     [phone]
     Compuserve [72247,2671]

What it does
------------
  MAP.PAS is a program which analyzes a Pascal program and provides the
programmer with information on the sizes of each of the overlay routines.
This information can be useful in several ways.  For example, since an overlay
group occupies only as much space as its largest member you can determine
which routines should be worked on in order to save code space.  The current
version is configurable for either CP/M 80 or PC/MS-DOS Turbo Pascal version 3.

How to use it
-------------
  MAP.PAS can be either command line or prompt driven.  There are four pieces
of information which can be provided to the program.  All but one of these has
default values.  Command Line options are separated by spaces.
  The first command line parameter is the name of the main Pascal source file.
The default extension is .PAS.  If no parameters are entered on the command
line, you will be asked for the file name.
  The second command line parameter, if entered, is the output file name.  The
file name can include drive/path references or be one of the standard logical
devices used by Turbo Pascal (i.e. LST: or CON:).  If prompted, the default
selection is the console.
  The third command line parameter, if entered, is the output sorting option.
The choices are N (for not sorted), A (for alphabetic sorting of routine
names) and S (for sorting by size of routine).  The default choice if not
entered is not sorted in which case the output is in the same sequence as
defined in the source code.  Only the first letter of the option is significant
but extra letters do no harm.  If the program is prompting, then it asks first
if the output is to be sorted and if so, the sequence to use.  The responses to
these questions are single letters without hitting the RETURN key.
  The fourth command line parameter is the number of lines per page.  If not
entered on the command line, there is no prompting and the default of 66 lines
per page is used.
  The last parameter is the number of lines to be used for the top and bottom
page margins.  Again, if not entered on the command line, there is no prompt
and the default of 6 lines (1 inch) is used.
  The source code for the entire program must be online just as it would be
during compilation.  The program must be compiled to a .COM file before MAP is
run and the resulting overlay files left on the drive where the compiler put
them.  In other words, the time to run MAP is immediatly after compiling the
program to be tested to a .COM file.  MAP should only be run on files which
have been successfully compiled without errors.

What it generates
-----------------
  The output from the program is a formatted text file suitable for printing
or viewing with a TYPE command.  The defaults for the number of lines per page
and top and bottom margins are correct for standard 8 1/2" x 11" paper.  All
lines are less than 80 characters long.  For each overlay group in the program
being analyzed, the output will start on a new page.  The first line shows the
overlay group number and the amount of space reserved in memory (not on the
disk) for this overlay group.  The space reserved is given in both bytes and
records.  Turbo Pascal overlay areas are always rounded up to the next
256 (DOS) or 128 (CP/M) byte boundary and a record is one of these even-sized
chunks.  Because of this, an overlay 129 bytes long reserves exactly as much
space as one which is 255 bytes long.  The number of records required for the
group will be equal to that of its longest member routine.
  The rest of the page consists of a list of each of the member routines of
the overlay group.  The order of this list is either the order they were
defined in the source code, alphabetically by routine name, or by size from
largest to smallest.  Each entry consists of the routine name, the exact length
of the overlay in bytes, the number of 256 (128) byte records required for the
routine, the number of bytes left unused by this routine within the overlay
area and a indication of how much of the available area was used (expressed as
a percentage used).  Note that the bytes to spare equals the total bytes
reserved by the overlay group less the length of the individual routine.  Below
this numeric information is a bar graph showing the percentage used, where a
full line of X's represents 100%.

Using the output
----------------
  Probably the most effective way to use the output to help squeeze some more
code space out of your already overlayed program.  Since the amount of space
occupied in memory is dependent only the largest overlay routine in an
overlay group, it does no good to spend time making the other routines in the
overlay group smaller.  By either sorting the output by size, you can
concentrate your work on the largest routines.  Often splitting the offending
routine in two or moving it to a different overlay area can free up a great
deal of code space with very little effort.  Be careful however not to violate
Turbo Pascal's rules against calling routines in the same overlay group either
directly or indirectly.  Also note that the size of nested overlay areas is
included in the size of an overlay routine.

How to compile the program
--------------------------
  To compile the program you need the mainline source file MAP.PAS and one of
the configuration files.  For PC-DOS or MS-DOS use MAPDOS.PAS and for CP/M,
CP/M Plus or MP/M use MAPCPM.PAS.  About 16 lines into the file MAP.PAS is a
line consisting of an include directive and a note pointing it out.  For DOS
users, use the Turbo editor to set this line to {$I MAPDOS.PAS}.  A CP/M user
should set this line to {$I MAPIBM.PAS}.  Set the compiler options to generate
a .COM file, and set the Main file name to MAP.PAS.  After compiling, the
resulting MAP.COM is complete.

How it works
------------
  MAP.PAS is essentially a very simple recursive descent parser which scans
your source code looking for overlay routine definitions.  When a routine is
found, the program scans the compiled overlay files and determines the size
of the compiled object code.  It does this by knowing that compiled overlay
routines always start on a record (256 or 128 byte) boundary and that the last
record is padded out with $00 bytes.  Furthermore, overlay routines in the
same overlay group are butted up against each other in the same order as
defined in the source code.  The program looks at the overlay code and tries
to guess what comprises each of the overlay routines.  It is possible for
the overlay files to fool the program if the random bytes in the code
generated happens to look like a "real" end of overlay pattern.  The program
will notice that the entire overlay file was not used however and retry the
analysis until it succeeds in analyzing the file.

Caveats
-------
  There appears to be a slight bug in the Turbo Pascal compiler (noticed in
version 3.01A for PC-DOS, but possibly in others as well) which causes an
extra record of all $00's to be included in the overlay file if the preceeding
routine ended exactly on a record boundary.  This extra 256 bytes is added
(incorrectly) to the length of the next routine.  I left MAP.PAS this way
since it is hard to tell whether future or past versions of the compiler will
handle have the problem.