PROBE
=====

By
Colin J. Stearman
[71036,256]

PURPOSE

To analyze the performance of a program to determine where
optimization will be of the most benefit.

FEATURES

* Samples user program every 55 milli-seconds(using the DOS timer)
* Monitors routine currently being executed
* Displays results to screen or file
* Displays results by address and by decending use frequency
* Works with all memory model types
* Independent of source language type
* Allows user to specifically exclude counting any modules
* User settable timer interrupt number

OPERATION

PROBE is invoked with the following command:

PROBE [/I:n] PROG_NAME.[EXE|COM] PROG_ARG1 ... PROG_ARGn

The optional /I:n argument allows the user to select the interrupt
number for the sample timer. 'n' is in hexadecimal. On normal DOS/IBM
machines this will be 8. If you do not understand this argument leave
it out. It is provided to allow non-standard machines to select other
interrupt numbers for the sample timer. Whenever the PC activates
this interrupt the program being probed is sampled to find out which
routine it is in. The more frequent the interrupts the greater the
sample number and the better the results.

It is essential that the program to be probed be given with its full
extension. Any arguments it requires can then follow. The simplest
form of command line is:

PROBE PRTEST.EXE

This will analyze PRTEST.EXE which does not require any arguments. This
happens to be a test program included with this package.

PROBE must have available to it the following files in the default
directory:

COMLOAD.COM
EXELOAD.EXE
progname.MAP

An exclusion file may also be optionally available to PROBE and must
have the name:

progname.EXC


The first 2 programs are used to determine where DOS will
load the program to be probed. The last is a map file created by the
Microsoft linker LINK when it linked the programto be probed. The
"/m" switch must be used when linking the program to provide a full
map of the program. For example, the PRTEST program was linked with:

LINK PRTEST/m;

As PROBE runs, it first determines where the user program will be
loaded and reports this to the user. Then it asks for the destination
of the resulting data. This can be a file or the CRT screen. If a filename
is provided with no extension, .PRB is automatically added.

PROBE then reads the program MAP file and stores the data on the
program modules. It then looks for an exclusion file containing
module names to be excluded from the analysis. The file name must
have the same name as the program and map file, but with an extension
of .EXC. The format of this file is:

; This is a module exclusion list for PROBE
module_name1 any comment

module_name2
module_name3
; end of exclusion file

The module name must be the first word on the line but may have
leading spaces. The case must be exactly as it appears on the MAP
file. Blank lines are ignored, as are lines starting with a
semicolon, thus allowing comment lines.

If no exclusion file is found, the PROBE announces this and
proceeds normally.

PROBE then runs the user program and passes it any supplied arguments.
As the program runs, PROBE is activated by the system clock and a
note is made every 55mS of the routine or module currently being executed.

When the user program terminates, the PROBE results are written to
the chosen output. First a table of results is generated in address
order and then another table in decreasing count frequency order.

One temporary file is created by PROBE. It is name "REGISTER"
and is deleted when PROBE terminates normally. Also various
self-expanatory error message may be issued during abnormal PROBE
operation.


ANALYZING RESULTS

The routines or modules at the top of the second table are
there because PROBE found them active more frequently then those
below them. This suggests that improving their efficiency will have
the most effect on overall program performance.

Beware of input/output routines when analyzing results. If
the program waits for user input, PROBE will obviously find the
program frequently in the associated routines. Thus these results can
be misleading. Routines which deliberately waste time should also be
indentified when analyzing results. Such modules as these can be
included in the optional EXCLUSION FILE so that they are not
considered during the analysis.

EXAMPLE PROGRAM

The program PRTEST supplied in this package was used to test
PROBE. It is written in C and calls 5 routines each which "waste"
twice as much time as the previous. A sixth routine is included (but
never called) to check for bugs in identifying probed routines.

The typical results from the command:

PROBE PRTEST.EXE

are:

PROBE Program Performance Analyzer V2.00
Written by Colin Stearman [71036,256]

PROBE: Reading program map file . . .
PROBE: Map symbol count: 117
PROBE: Map table size: 1053 bytes
PROBE: Symbols processed: 000117
PROBE: Probe of program PRTEST.EXE
PROBE: Program's base code segment is 696A
PROBE: Enter results filename [.PRB] ( for screen)?
PROBE: Executing PRTEST.EXE . . .
============================================================

test1(these lines output by PRTEST)
test2( " " " " " )
test3( " " " " " )
test4( " " " " " )
test5( " " " " " )

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

PROBE: PRTEST.EXE terminated(0)

PRTEST.EXE Page 1 04-18-1990 11:45:00pm

PROBE results by SYMBOL ADDRESS

ADDRESS | SYMBOL | COUNT
===========|===================================|========
0000:0058 | _test1 | 14
0000:0084 | _test2 | 28 (Excluded)
0000:00B0 | _test3 | 43
0000:00DC | _test4 | 56
0000:0108 | _test5 | 70 (Excluded)
========================================================


PRTEST.EXE Page 2 04-18-1990 11:45:00pm

PROBE results by COUNT

COUNT | SYMBOL |PERCENT
===========|===================================|========
56 | _test4 | 49.56%
43 | _test3 | 38.05%
14 | _test1 | 12.39%
========================================================


End of PROBE analysis report

As expected, the second report indicates that most time was spent in
"_test5" with decreasing amounts through to "_test1". As "_test6"
was not called it does not appear.

CONCLUSION

You should have the following files in the ZIP file:

PROBE.EXE
COMLOAD.COM
EXELOAD.EXE
PRTEST.EXC
PRTEST.MAP
PRTEST.EXE
PROBE.PRB
PRTEST.C
PROBE.DOC


If you find this program useful I would be pleased to hear from you. Leave
me some EMAIL. Any comments on improvements or changes would be
welcome.

ACKNOWLEDGEMENTS

PROBE is based on a program I found on CompuServe called
PROFILE. I do not know the name of the author but wish to acknowledge
his efforts.

COLIN STEARMAN [71036,256]

====*****====

Version 2.00 Changes.

1. Memory usage has been improved so that approximately 10 times as
many function identifiers can be processed from the MAP file. Memory
usage for the identifier table is now displayed.

2. The feature has been modified. The calls to excluded
functions are now counted but not included in the second report or in
the percentage calculation for the second report. The first report
shows those functions being excluded.

3. A bug has been fixed which caused incorrect results to be
returned when programs had a large number of function identifiers.

4. COMLOAD.COM has been rewritten to make it smaller.

====*****====