It is not possible to show the response to individual editor keystrokes on a piece of paper. Nor is it possible to fit a “snapshot” of a standard-size terminal screen on the page. What this sample session shows are snapshots on a very small terminal screen (fifty-eight characters wide by eight lines high). The cursor is marked by an underline. The snapshots are of selected moments in the course of the debugging session. The commands typed by the user to get from one snapshot to the next are described in the text. To be sure, there is no substitute for actually doing something; it is suggested that you follow along by performing the steps described below on a terminal while reading the script.

To begin with, you must enter the editor by following the directions found in the relevant part of the MAINSAIL System-Specific User's Guides. You must use the display MODULE appropriate to the type of terminal you have. It is assumed here that you have already invoked MAINEDIT, with MAINED as the default front end, and that your screen presently contains a single window with a buffer called FOO in it, as in Example 9–1. The debugger uses the display interface if it is invoked from the editor (unless you have a special configuration bit set in the MAINSAIL bootstrap; see Chapter 6 of the MAINSAIL Utilities User's Guide.

It is assumed that you have compiled the MODULE SAMPLE debuggable as shown in the line-interface sample session.

Now invoke the MAINSAIL debugger with the MAINED command QE. The QE command writes the prompt Module or file name: on the message line at the top of the screen. Type debug<eol>. The buffer CMDLOG is then created if it does not already exist. In this example it is assumed that CMDLOG does not exist before the QE command.

The debugger now prints out a herald and waits for input. See Example 9–2.

Notice that the buffer CMDLOG is now in escape mode (E appears at the top of the buffer), indicating that the debugger program is expecting input. Since the MODULE SAMPLE has already been compiled debugged, you can now give the debugger's M command. As soon as you type the M key, the debugger writes a prompt on the top line of the screen; see Example 9–3.

Were you to decide at this point that you did not want to debug a MODULE after all, but rather go do something else, you could type the <abort> key (as described in Table 1–1 of the MAINEDIT User's Guide). The debugger would beep and return the cursor to its original position in CMDLOG. You could then hit the <ecm> key and give any number of editor commands. You could create files, edit a document, or perform any other operations permitted by MAINEDIT. The debugger would still be waiting in the background for you to give the MAINED E command. When you did so, you would again be talking to the debugger, and could type in any debugger command. The debugger would be in precisely the same state as when you left it; that is, it would have exactly the same context.

For the sake of practice, type <abort><ecm> right here. The mode character for CMDLOG becomes C. Give the QY command to MAINED, which makes the current buffer fill the entire screen (that is, it gets rid of the window into the buffer FOO). See Example 9–4.

Now you type MAINED's E command, and you are talking to the debugger again (notice how the mode character changes from C to E). Once again type the debugger's M command, but this time type the MODULE name in response to the prompt: sample<eol>. See Example 9–5. The end-of-line after the file name echoes as a backslash (\) character.

Now position the cursor to the line where you set the breakpoint, as in the line-oriented interface example. You cannot use the debugger's D command since the editing commands used by the line-oriented interface debugger are not available with the editor interface. If you type D to the debugger in the display interface it prompts:

nothing or P or 'V type id1,...':

meaning that you can type here <eol> to use the debugger's D command, P to use the DP command, or V to use the DV command. Using the D or DP command, however, does nothing but print out the message:

Not available in the display debugger

All cursor motion is performed by using the appropriate MAINED commands instead of the line-interface debugger commands. Therefore, in this case, type <ecm> to get back to MAINED's command mode, then use the down arrow key (or the editor's \ command) to go down to the line (eight lines below the current line) where you wish to set a break. You can, of course, use any other MAINED command to position to the desired place, including the T, G, and W commands.

On terminals with arrow keys, the arrow keys are usually defined by default in such a way that it is not necessary first to type <ecm> and use them in MAINED's command mode. They may be used while in escape mode; the debugger passes the arrow key codes automatically to the editor. The same is not true of other editor commands, e.g., the T, G, and W commands.

After going down eight lines, the screen looks as in Example 9–6.

Now to return to escape mode so that you are talking to the debugger instead of the editor, give MAINED's E command. If you forget to do this, and go on to the next step and type the B command, MAINED beeps instead of performing the “Break line” command. This is because the debugger has set the buffer containing SAMPLE to be read-only to prevent inadvertent modification of the buffer. If you change a buffer while it is being debugged, the positions that the debugger uses to keep track of source text are no longer correct for the MODULE you are debugging, and the debugger gets lost. Therefore, do not modify a buffer during a debugging session if you intend to continue debugging a MODULE with a source file in that buffer.

MAINED's E command (E is for “Escape”) takes you back to the debugger. Now give the debugger's B command. When you type the B key, the debugger responds immediately by prompting:

{@{m.}{pi}{[cond]}{:cmds}:

In the usual case you just want to set an unconditional break at the current cursor position, which you do by typing <eol> to this prompt. The debugger then prints out the location where the break was set (see Example 9–7).

Now that the breakpoint has been set in SAMPLE, you are ready to execute the MODULE. To do this, use the debugger's E command. This command executes another MODULE. If the MODULE name is not given, it recursively invokes MAINSAIL. The E command prompts:

module or file or <eol>:

to which you type just <eol>. The result of this maneuver is shown in Example 9–8.

You are now in insert mode, talking to the MAINSAIL executive. This executive was invoked from the debugger, which was invoked from the editor, which was invoked from yet another executive in the dim and distant past. You can see why it is important to remember the program to which you are giving commands at any given time!

Now make the CMDLOG window a little taller, so as to have some breathing room. Type <ecm>Q+1Y, which increases the size of the current window by one line. Now type the I command to get back into insert mode, and then type sample<eol>, which begins the execution of that MODULE. See Example 9–9.

Next type in the number 131, then end-of-line, just as in the nondisplay debugger example. The program then prompts:

Next key to be hashed:

You can type in any STRING here. Try the STRING “Hello”, then type end-of-line. What happens now is that the execution of SAMPLE reaches the breakpoint you set in the PROCEDURE hash, since this is the first call to that PROCEDURE. The debugger positions the cursor to the place in the SAMPLE buffer where the break was set, and the resulting display is shown in Example 9–10.

When you reach the breakpoint, the mode character is automatically set to E. This means you can now give debugger commands, since you are talking to the debugger again. Give the debugger's S (single Step) command. The cursor jumps from the beginning of the statement h := length(s) to the beginning of the statement i := h MIN 4. Give the S command again, and the cursor jumps to the beginning of the next statement to be executed. On each step, the statement that was jumped over has just been executed.

If your screen is as small as the one in the examples, you do not have the next statement visible on the screen at this moment. Therefore, if you give the S command again, the screen scrolls in order to display the point at which execution stops. In general, when the debugger needs to position the cursor on a statement, it scrolls the screen, creates new windows on the screen, or even creates a new buffer automatically if necessary in order to position the cursor correctly.

Now you have given the S command three times since the breakpoint at the beginning of the PROCEDURE, and you are sitting on the WHILE-clause of the iterative statement (see Example 9–11).

At this point the PROCEDURE's three local variables have been initialized, so you can usefully examine their values. Type the debugger's V (Value) command. The debugger immediately prompts at the top of the screen:

e1,e2,...:

You may now give a list of MAINSAIL expressions (variable names in this case), and the debugger prints out the value of each variable, usually to CMDLOG. For example, suppose you just want to see the value of the variable h. Then you respond h<eol> to the V command's prompt. The result appears in Example 9–12.

If you want to see the values of h, i, j, and s, then you can type h,i,j,s<eol> in response to the V command prompt. The result is shown in Example 9–13. Alternatively, you could use the .SF command to show all local variables of the current PROCEDURE.

Notice that the CMDLOG buffer has been scrolled to display the values of all the variables; in fact, the values of h and i have scrolled right off the screen. You can go back and look at these values simply by using MAINED commands to scroll backwards through the CMDLOG buffer. Type <ecm> to talk to MAINED again, then give MAINED's .Y (go to other window) command. You may use the up-arrow key (or MAINED's ^ command) or MAINED's -W command to move backwards through CMDLOG and see the values of the variables that were scrolled off the screen. After doing this the situation might look as in Example 9–14.

You can now type the E command to get back to the debugger. The cursor does not have to be in the SAMPLE buffer, in which you were positioned when last talking to the debugger; in fact, the SAMPLE buffer need not even be visible. You can still give any debugger command that does not depend on the cursor position. If you give a command that needs to position the cursor in the SAMPLE buffer, then that buffer is made visible if necessary, and the cursor is positioned there automatically.

Now type the debugger's C command to continue the execution of SAMPLE. The result is shown in Example 9–15. The program has printed out 96 (the value of the hash code for the STRING “Hello”) and is prompting for the next STRING to hash. The I mode character indicates that the program is waiting for input in insert mode.

You could, of course, type in another STRING. You would break again at the breakpoint set earlier in the PROCEDURE hash. You could then step some more, set or clear breakpoints, examine variables, or even execute other MODULEs and then return to debugging SAMPLE. However, these projects are left to your imagination. You are now going to terminate execution of SAMPLE by typing <eol> to the program's prompt; see Example 9–16.

You are returned to the MAINSAIL executive's asterisk prompt. This executive is the one created by the debugger. You could here type the name of another MODULE, but instead type <eol> again and return to the debugger; see Example 9–17. Note how the mode letter changes from I to E; it is no longer possible to type program input into CMDLOG, since there is no program waiting for input from CMDLOG. You can type only debugger commands, except that if you type <ecm> you may then type editor commands.

Now give the debugger's Q (Quit) command. The debugger prompts:

Want to return from debugger (Yes/No<eol>):

Type y<eol>. You may now continue whatever you were doing in the editing session before starting to debug SAMPLE, or you may exit from the editor altogether with the MAINED's QF command. The situation after exiting the debugger is shown in Example 9–18. Note how the mode character changes again from E to C; it is no longer possible to give debugger commands, since the debugger has exited. If you attempt to use MAINED's E command now, it complains Nothing to escape to. You may always restart the debugger by using the QE command as you did at the beginning of this example.

It should be noted that it is possible to give the debugger's Q command before the MODULE (in this case, a MAINSAIL executive) invoked by the debugger has finished execution, provided you are at a breakpoint. If this is done, the debugger prompts:

At a break in SAMPLE -- want to quit (Yes/No<eol>):

Responding affirmatively to this prompt results in the termination of the execution of SAMPLE and a return to control by the debugger.

If you give the +Q command, you exit the debugger unconditionally, i.e., with no prompting.

Alternatively, you may give MAINED's QF command during the debugger's execution at any time if you first get into command mode (the one with the C mode letter). If you give this command, the editor recognizes that the debugger is still running and prompts:

Invoked from debug: want to abort it (Yes No)?

If you answer affirmatively in this case, you are prompted to save altered buffers before returning to the operating system.