3.1. Invoking the MODULE MAINPM

When you execute your program while running MAINPM, MAINSAIL gathers statistics and writes them to a data file created by MAINPM. The logical name of the statistics file is (pm statistics file). This logical name is ordinarily entered by means of a subcommand to the MAINSAIL executive in the configuration file (see Section 21.2.19 of the MAINSAIL Utilities User's Guide). If you wish to use a different file name from the usual one for the statistics file, specify it by means of the ENTER subcommand when you invoke MAINPM, as follows:

*mainpm,<eol>
>enter (pm statistics file) foo.stat<eol>
><eol>
MAINPM (type ? for help)

MAINPM:

• the entities to be monitored,

• the kinds of monitoring to be done,

• the invocation of MODULEs,

• the kinds of statistics reported, and

• the level of detail to which the statistics are broken down (i.e., MODULE, PROCEDURE, or statement).

Enter commands one per line, each followed by <eol>. Upper and lower case are not distinguished in commands. You need type only as many characters of a command as are needed to distinguish it from other commands.

Table 3–1 contains a quick summary of MAINPM commands.

3.2.1. Specifying What to Monitor

• Statement counts and PROCEDURE call counts: counting the number of statements executed, the number of times a given statement is executed, and the number of times each PROCEDURE is called. Statement and PROCEDURE count monitoring requires some compiler subcommands as shown in Table 3–2, but no MAINPM command need be given before the monitored program is executed.

• MODULE and PROCEDURE timing: counting the time (usually CPU time) used by every specially compiled MODULE and/or PROCEDURE. This kind of monitoring requires some compiler subcommands as shown in in Table 3–2, but no MAINPM command need be given before the monitored program is executed.

  As an alternative to CPU time, you can count the incrementing and decrementing of a user-specified variable. This kind of monitoring requires some code in the program to manipulate the variable and some compiler subcommands as shown in Table 3–2, and the TIMING USER command needs to be given before the monitored program is executed; see Chapter 6.

• Chunk, STRING, and static space monitoring: counting the use of chunk space (for dynamic objects), STRING space, and static space. No compiler subcommands need be given for the monitored MODULEs, but the MAINPM SPACE command must be given before the monitored program is executed; see Chapter 4.

• PC-sampled times: periodically interrupting the program and seeing which PROCEDURE is executing. No compiler subcommands need be given for the monitored MODULEs, but the MAINPM PC command must be given before the monitored program is executed; see Chapter 5.

• Chunk allocation history tracing: recording where every dynamic object allocation and deallocation occurred in the program. Various compiler subcommands create an intmod with sufficient information to support this kind of tracing; ALIST, DEBUG, and PERSTMT are all sufficient. The MAINPM TRACECHUNKS command must be given before the monitored program is executed; see Chapter 7.

The types of monitoring are summarized in Table 3–2.

More than one kind of monitoring can take place on the same program execution. In the above list, only MODULE and PROCEDURE CPU timing and MODULE and PROCEDURE user-defined timing are mutually exclusive; either one can be performed simultaneously with any combination of the other three kinds of monitoring, depending on the compiler subcommands and MAINPM commands given.

For chunk, STRING, and static space monitoring, the MONITOR and NOMONITOR commands provide additional control of what is to be monitored by allowing monitoring only of specified areas, MODULEs, or objmod libraries. The MONITOR and NOMONITOR commands must be given before the monitored program is executed; see Chapter 4 for details.

The per-MODULE, per-PROCEDURE, and per-statement statement counts are often measured in conjunction with the per-MODULE and per-PROCEDURE timings. For this reason, the compiler subcommand MONITOR turns on all five compiler subcommands relevant to these kinds of monitoring.

PC-sampled time provides a method of measuring CPU time usage that is an alternative to per-MODULE and per-PROCEDURE timings. The chief differences between the two are:

• PC-sampled time is usually a more accurate method of gathering timing statistics than per-MODULE and per-PROCEDURE timings.

• However, on some platforms, PC-sampled time may not be available because the operating system does not provide sufficient facilities to allow MAINSAIL to implement it.

MAINPM reports timing information unless you specify the NOTIMING command. It reports statement counts unless you specify the NOCOUNTS command. It reports how many times each PROCEDURE is called unless you specify the NOCALLS command. It reports unexecuted PROCEDUREs or statements only if you specify the UNEXECUTED command.

MAINPM reports PROCEDURE call counts, unexecuted PROCEDUREs, or statements only for MODULEs in which statement counts at the PROCEDURE or statement level were gathered, so if you want this information reported, be sure to specify the appropriate subcommand when you compile your MODULEs (see Section 2.1).

3.2.4. Specifying Level of Detail

If none of these commands is specified, MAINPM breaks the statistics down to the lowest level for which statistics are available, based on the compiler subcommands with which the MODULEs of the monitored program were compiled. Otherwise it breaks them down to the level corresponding to the last command specified. If no statistics of a given kind are available at that level for a given MODULE, MAINPM uses the statistics at the lowest level available. In particular, since timing information is not available at the statement level, the lowest level to which timing information is ever broken down is the PROCEDURE level.

3.2.5. Including Commands Read from a File

For example, the command:

MAINPM: include mycmds.txt<eol>

executes the MAINPM commands in mycmds.txt.

3.2.6. Writing to the Report File

If a parameter follows the word LIST, MAINPM uses it as the name of the report file to which it writes the report. Otherwise, it uses the name in the most recently specified LIST command. If no LIST command has been specified, MAINPM prompts you for the name of a file that it creates and subsequently uses as the current report file.

MAINPM closes its report file after each LIST command. If a subsequent LIST command directs more output to the same file, MAINPM reopens the file and positions to its end of file before writing more statistics.

If you want to separate the report into two (or more) parts, then for each part:

• Specify the kinds of statistics and level of detail you wish to see.

• Generate that part of the report by means of the LIST command.

MAINPM remembers the kinds of statistics and level of detail to report from one part of a report to the next.

Below is a dialogue between a user and MAINPM that results in a report consisting of two parts. The first part shows each PROCEDURE's shallow and deep time, and the second part shows the number of statements executed in each PROCEDURE:

MAINPM: procedure<eol>
MAINPM: nocounts<eol>
MAINPM: list report<eol>
MAINPM: counts<eol>
MAINPM: notiming<eol>
MAINPM: list<eol>

In order to combine statistics from different runs, the run your program (or programs) repeatedly under MAINPM. After each execution of the monitored program, the save that run's statistics in a different file with the STORE command. After gathering and saving the statistics for each run, combine them by means of the LOAD and ADD commands; use the LOAD command to restore the statistics for the first run, and a sequence of ADD commands to combine the statistics for subsequent runs.

Once the statistics are combined, they can be reported with the LIST command as if they were gathered during a single execution, or they can be saved in a file by means of the STORE command.

3.2.7.1. Portability of Statistics Files

The target system number is used when the contents of two statistics files are merged by means of MAINPM's ADD command. If the two files have different target system number fields, MAINPM issues an error message.

Statistics can be gathered for a program on one system and the program's statistics can be reported on a different system, as long as the necessary intmods from the first system are available on the second system.

3.2.8. Displaying Current MAINPM Status

• when m is disposed by means of the STRING or MODULE form of dispose (but not the POINTER form of dispose) during the execution of a MODULE from MAINPM.

• when m is still allocated and a report file is generated by the MAINPM LIST command.

• when m is still allocated and MAINPM exits after running a MODULE but without having generated a report file.

Once a MODULE's statistics are written to the statistics file, the state of its statistics is reset to what it was when the MODULE was first allocated. This means that if several MODULEs are run in turn during a single MAINPM session, and a report is generated after each run, the statistics for any MODULEs that were present for more than one run will reflect only their activities during the run associated with each report file.

A MODULE's statistics reflect all instances of the MODULE that may have been active. The statistics are not broken down across different data sections of the same MODULE.