9.1. $startMonitoring and $stopMonitoring

Two system PROCEDUREs, $startMonitoring and $stopMonitoring, allow users to monitor portions of a program's execution rather than all of it.

A user who wants to monitor portions of a program's execution runs the program from MAINPM, as usual. By default, monitoring is on when the program is running; the programmer must arrange to call $stopMonitoring at the start of the portions where monitoring is to be turned off and $startMonitoring at the end of each such portion. If no call to $startMonitoring or $stopMonitoring occurs, monitoring is on throughout the program's execution.

If two successive calls to $startMonitoring occur with no intervening call to $stopMonitoring, the statistics gathered by MAINPM between the two calls are discarded. If a call to $startMonitoring occurs in the program's execution before any call to $stopMonitoring, all statistics gathered before the call to $startMonitoring are discarded. If more than one pair of calls to $stopMonitoring and $startMonitoring occur during a program's execution, MAINPM reports the sum of the statistics gathered during the monitored intervals.

$startMonitoring and $stopMonitoring can be called either by embedding the calls within the program or, if the program's MODULEs were compiled debuggable, by executing the program under control of the debugger after setting breakpoints at the places in the program where monitoring is to start and stop. When the breakpoints occur, the appropriate PROCEDURE can be called by means of the debugger's XS (execute statement) command, e.g.:

xs $startmonitoring

Using the debugger as suggested above could add some overhead to the statistics gathered by MAINPM, so it would be a poor method if the portion of the program being monitored executes quickly. If the portion to be monitored executes much more quickly than, say, a second, using the debugger is probably a bad idea. If, however, the portion to be monitored takes much more than a few seconds to run, then using the debugger probably would not skew the measurements noticeably.

$startMonitoring and $stopMonitoring are meant to be invoked from a program that has been invoked from MAINPM, or in which $executeMainpmCommands("START") has been called.

9.2. $executeMainpmCommands

The MAINPM interface PROCEDURE $executeMainpmCommands executes arbitrary MAINPM commands from a program. MAINPM also supports two commands, START and STOP, which may be useful when invoked through $executeMainpmCommands.

$executeMainpmCommands allows programs to be monitored even if they are not invoked directly from the MODULE MAINPM. Call $executeMainpmCommands with the argument START when statistics should start being gathered and then again with the argument STOP when statistics should stop being gathered.

The cmds parameter is a STRING that contains exactly what would be typed by a user giving commands to MAINPM interactively, including the <eol> characters separating the commands. If f is not Zero, then commands are read from f once cmds is exhausted. $executeMainpmCommands returns FALSE as soon as an error is encountered. Otherwise it returns TRUE either when the QUIT command is specified or when both cmds and f are exhausted.

MAINPM reinitializes itself only after a QUIT command; it does not reinitialize itself each time $executeMainpmCommands is called. Thus, the commands specified by different calls to $executeMainpmCommands are considered to be within the same MAINPM “session” until a QUIT command is specified.

In the call to $executeMainpmCommands that starts gathering statistics, the last MAINPM command specified should be the command START. In the call that stops gathering statistics, the first MAINPM command should be the command STOP. The actions taken by MAINPM for the START and STOP commands correspond, respectively, to the actions taken for the EXECUTE command before and after the MODULE to be executed is invoked. Any commands that would normally be specified before the EXECUTE command (e.g., PC) should be specified before START. Likewise, any commands that would normally be specified after the EXECUTE command (e.g., LIST, STORE, or ADD) should be specified after STOP. The commands specified before START or after STOP need not be specified in the same $executeMainpmCommands call that specifies START or STOP.

For example, if you wanted to gather PC monitoring statistics for a particular operation in some program that was not going to be invoked from MAINPM, and wanted to have the results written to the file pcstats.lst, you would execute the following just before starting the operation:

$executeMainpmCommands(
    "pc" & eol &
    "start");

and would execute the following just after finishing the operation:

$executeMainpmCommands(
    "stop" & eol &
    "list pcstats.lst" & eol
    "quit");

9.3. How to Control Monitoring from a Program: The Differences between $executeMainpmCommands("START") and $startMonitoring, and between $executeMainpmCommands("STOP") and $stopMonitoring

1. Interactively: you invoke the MODULE MAINPM directly, and use MAINPM's EXECUTE command to start the execution of your program.

2. Non-interactively: you run your program without first invoking MAINPM, but the program contains calls to the PROCEDUREs $executeMainpmCommands, $startMonitoring, and $stopMonitoring to cause MAINPM to gather performance statistics about your program.

It is intended that you call $executeMainpmCommands("START") only when your program is not run from MAINPM's EXECUTE command. Typically, you will do this only once during the execution of your program. When you are all done with gathering the statistics, you should call $executeMainpmCommands("STOP") before specifying the LIST and QUIT commands (and any other commands you would like to issue) to $executeMainpmCommands.

Pairs of $stopMonitoring and $startMonitoring calls can appear between $executeMainpmCommands("START") and $executeMainpmCommands("STOP") (if running non-interactively) or between the time you issue MAINPM's EXECUTE command and the time your program finishes (if running interactively). $stopMonitoring turns off monitoring temporarily, and $startMonitoring resumes it.

No nesting count of monitoring commands is maintained for you. This means you should be careful about calling $startMonitoring when monitoring is already in effect, since it has the result of discarding statistics since monitoring last started.

9.4. $statisticsInfo

The PROCEDURE $statisticsInfo returns a POINTER to a record summarizing the program's current statistics and then clears the current statistics so that any statistics reported for the rest of the program do not include the statistics that were just summarized. Before calling $statisticsInfo, the program should call $stopMonitoring.

The POINTER returned by $statisticsInfo is of the following CLASS:

    CLASS $statisticsInfoCls (
        LONG INTEGER    $totalStmts,
                        $totalCpuTime,
                        $totalRealTime,
                        $totalChunkSpace,
                        $totalStringSpace,
                        $totalStaticSpace,
                        $totalMonitoredPcs;
        );

The fields are:

• $totalStmts: Total number of monitored statements executed. Only statements for MODULEs compiled with the MONITOR, PERSTMT, PERPROC, or PERMOD compiler option are counted.

• $totalCpuTime: Total CPU time used by program, in CPU “ticks”. The predefined LONG INTEGER variable $cpuTimeResolution indicates the number of CPU ticks per second.

• $totalRealTime: Total elapsed time in seconds.

• $totalChunkSpace: Total amount of chunk space allocated, in storage units. Only the space allocated while the MAINPM command SPACE was in effect is counted.

• $totalStringSpace: Total amount of STRING space allocated, in character units. Only the space allocated while the MAINPM command SPACE was in effect is counted.

• $totalStaticSpace: Total amount of static space allocated, in storage units. Only the space allocated while the MAINPM command SPACE was in effect is counted.

• $totalMonitoredPcs: If the program was run with PC monitoring in effect, the total number of PC interrupts that occurred.

If si is NULLPOINTER, $statisticsInfo allocates a new dynamic record in which to summarize the statistics. Otherwise, it reuses the record pointed by si.

It is up to the calling program to dispose of the $statisticsInfoCls record returned by $statisticsInfo.

If $statisticsInfo is unable for some reason to obtain a summary of the program's statistics, it sets msg to a STRING indicating the reason for the failure, and returns NULLPOINTER. If the errorOK bit was not specified in the ctrlBits parameter, $statisticsInfo also displays a message to the console, typically by calling errMsg. If $statisticsInfo is successful, msg is set to the empty STRING.

$statisticsInfo should be called only from a program that is being executed under control of MAINPM. The program need not have been compiled with any monitoring options enabled.