In this example, several debugger commands are used on a small MAINSAIL MODULE called SAMPLE. The complete text of SAMPLE appears in Appendix B. This example is intended to be as machine-independent as possible; however, the particular numbers and source file names that appear in the examples may not be the same on your operating system. Such differences as may exist are not important to the substance of the discussion.

Before it can be used with the MAINSAIL debugger, a MODULE must be compiled with the compiler's DEBUG subcommand. Attempting to use the debugger on a MODULE compiled without the DEBUG option results in a message like the following from the debugger:

Could not find intmod for SAMPLE

or, if an old intmod from a debuggable compilation exists, but SAMPLE's objmod is not debuggable:

Cannot ... since object module was not compiled debuggable:
SAMPLE

Compiling SAMPLE with the DEBUG option is accomplished as shown in Example 8–1.

When SAMPLE's source file name is typed in response to the compile (? for help): prompt, it is followed by a comma. The compiler interprets this as a request to enter compiler subcommand mode. It therefore gives the subcommand prompt, a greater-than sign (>). You could type a question mark here to see a list of available compiler subcommands. Instead the word DEBUG is typed, meaning that all subsequent MODULEs should be compiled debuggable. Typing just <eol> to the > prompt means to exit compiler subcommand mode and proceed with the compilation. The new compiler output files replace any files with the same name that may have existed previously; if SAMPLE were run now, the version run would be the debuggable one (unless SAMPLE's object MODULE is also in a objmod library open for execution; see Chapter 21 of the MAINSAIL Utilities User's Guide for the rules governing the search for an object MODULE). The intmod generated for SAMPLE contains the information needed by the debugger to determine the correspondence between source text and object code so that it can correctly display the execution of statements. The execution of debuggable object MODULEs is nearly identical to that of nondebuggable MODULEs, except that the debuggable MODULEs are slightly larger and slower. In the case of a tiny, I/O-bound MODULE like SAMPLE, the difference in execution speed is too small to observe.

To start the debugging session, run the MAINSAIL debugger, MAINDEBUG, by typing its MODULE name (DEBUG) to the MAINSAIL executive.

Next give the name of the MODULE to be debugged with the debugger's M command. It is possible to type a question mark to the MAINDEBUG: prompt to see a list of commands available in the debugger.

The debugger displays the first line of SAMPLE's source file, along with the names of the current MODULE and PROCEDURE (there is no current PROCEDURE in Example 8–2).

Now repeatedly give the debugger's D command, which tells the debugger to position Down one line in the file, until you come to a line of code where it is possible to place a breakpoint. Breakpoints may be placed only on executable MAINSAIL statements (except as noted in Section 4.3.1). After each debugger command, the debugger displays the current source line with a curly-bracket cursor (}) pointing to the current position on the line, as shown in Example 8–3 (no cursor is shown when the current position is on a blank line).

The debugger's B command is used to set a breakpoint on the first statement in the file. This is not the first statement executed by the program, but it is a useful place to break. The B command with no arguments sets a breakpoint at the current cursor position, which must be on the first character of a statement or the E of an END.

The E command now invokes SAMPLE. Refer to Example 8–4.

SAMPLE starts running until it hits the breakpoint, as shown in Example 8–5.

The first command given at the breakpoint is the debugger's V command, which prints out the value of a variable. In this case the variable examined is the STRING s, which is what was typed in response to SAMPLE's Next key to be hashed (<eol> to stop): prompt.

Now use the debugger's S command to step over the first statement in the PROCEDURE where the breakpoint was set. See Example 8–6.

Notice how the debugger's cursor is now positioned at the next statement to be executed. The statement h := length(s) has just been executed. Example 8–7 shows subsequent uses of the single step (S) and examine value (V) commands.

The V command can be used with more than one variable at a time if the variables are in a list separated by commas.

The C command continues execution until the next breakpoint. Here SAMPLE finishes the PROCEDURE in which it originally broke, then returns to the main program and asks for some more input. After the input is typed to SAMPLE, a break is reached again at the original breakpoint, which has not been removed. The debugger displays the source line on which it breaks just as it did the first time it broke there. See Example 8–8.

The first <eol> terminates execution of SAMPLE. Control is now returned to the debugger, and the Q (Quit) command is given. The debugger's Q command requires confirmation to guard against accidental exit from the debugger. If breakpoints remain in any MODULEs, it requires a separate confirmation to remove them (since you may want to resume program execution without the debugger, and later reenter the debugger if the program reaches a breakpoint).

A complete MAINDEBUG sample session without commentary appears in Example 8–9. Instead of using the D command eight times to position to the right line, a count has been given. 7D tells the debugger to perform the D command seven times. Similarly, a count given before an S command means to step that many times; certain other debugger commands also take counts. More complete descriptions of the debugger command syntax appear in Chapter 4.

The +Q variation of the Q command quits the debugger without prompting for confirmation.