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 (206)531-8944 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.