First, invoke the standard MAINSAIL bootstrap mainsam located on the MAINSAIL installation directory. This bootstrap differs from the mainsa bootstrap in that it has an FLI to Motif linked with it.

Compile the file sample.msl located on the MAINSAIL directory. Compile it using the DEBUG subcommand so that MAINDEBUG can step through it and examine data in it. Assuming that the MAINSAIL directory is installed under the environment variable name $MSL:

% $MSL/mainsam<eol>
MAINSAIL (R) Version 16.20.<release> (? for help)
Revision: <date>
Copyright (c) 1984-1998 by XIDAK, Inc., Point Arena,
 California, USA.
*compil<eol>

MAINSAIL (R) Compiler
Copyright (c) 1984-1998 by XIDAK, Inc., Point Arena,
 California, USA.
compile (? for help): $MSL/sample.msl,<eol>
> debug<eol>
> <eol>
Opening intmod for $SYS from ...

$MSL/sample.msl 1 2
Objmod for SAMPLE stored on sample-usp.obj
Intmod for SAMPLE stored on sample-usp.int

compile (? for help): <eol>
*

Now at the MAINEX asterisk prompt, invoke the MODULE MTFEXE, the Motif-based executive that includes the debugger:

*mtfexe<eol>

The debugger brings up a window that looks like Figure 2–1.

The debugger's rectangular cursor is placed in the upper left corner under the Opening intmod line (which you can ignore). Above that is a heavy horizontal line with the name CMDLOG in the middle. CMDLOG is the MAINEDIT buffer to which all terminal interaction with your program is directed while the debugger is running; the name is derived from “cmdFile/logFile”, those being the names of MAINSAIL's standard input and output files.

The columns of lettered buttons to the left are labeled with the keyboard shortcuts for various debugger commands. Many debugger commands can be invoked in 3 different ways:

1. By selecting their menu items,

2. By typing their keyboard shortcuts, and

3. By clicking on the button labeled with their keyboard shortcuts.

(This sample session shows only the use of menu items, because the menu items are the easiest to remember. However, the keyboard shortcuts are displayed in the menus themselves; for example, the first item on the Action menu is:

Invoke module...        Meta E

If you hold down the META key (often labeled META or ALT, although on Sun workstations the default META key is labeled with a diamond shape) at the same time as the E key (case is not distinguished), you get the same dialog as if you had invoked the menu item.)

Now, before running the MODULE SAMPLE that you just compiled debuggable, set a breakpoint in SAMPLE. In order to do that, you have to make SAMPLE available by setting the debugger's MODULE context to SAMPLE. From the Access menu at the top of the window, select Open module.... The dialog window appears as in Figure 2–2. Type sample into the text box where the cursor appears.

Now press the RETURN key, or click on the OK button. The dialog box goes away, the debugger writes some information about the intmods (symbol tables) that it opens in order to be able to debug SAMPLE, and then it brings the source text for SAMPLE into the window. The result looks as in Figure 2–3.

The heavy horizontal line containing the file name in upper case marks the top of the area containing SAMPLE's source text. The RO on the heavy line means “read-only”; you cannot alter this buffer (to ensure that the debugger's information about source file positions remains correct). The first page of SAMPLE consists of comments and a legal notice, so is not very interesting. Use the scroll bar to the right of SAMPLE's source text area to move back and forth to examine the whole file.

Put a breakpoint on the PROCEDURE hash in SAMPLE. Slide the scroll bar back up to the top (so that you can you can practice searching for hash from the beginning of the file), and click the Select mouse button (usually the leftmost mouse button) on the first character of the file. The debugger cursor moves there. The debugger cursor point is the point from which searches are done.

Now select Search... from the Edit menu. The search dialog box looks as in Figure 2–4.

Type hash and then RETURN. The debugger cursor moves to the first instance of the text “hash” in SAMPLE's source text. This is a few lines above the PROCEDURE hash, where you will set the breakpoint. Click to move the debugger cursor on the first character of the line three below the PROCEDURE header for hash. This is the first statement in hash, which reads:

h _ length(s); i _ h MIN 4; j _ 1;

The screen should look as in Figure 2–5.

Now from the Breaks menu select Set breakpoint at cursor. The debugger draws a box around the statement where the breakpoint is, as in Figure 2–6.

Now that the breakpoint is set, you can invoke the MODULE SAMPLE and let it run until the debugger hits the breakpoint.

From the Execution menu, select Invoke module.... Type sample in the dialog box; see Figure 2–7. Then type RETURN or click on the OK button.

After you type RETURN or press OK, the dialog box goes away and SAMPLE starts executing. SAMPLE is a line-oriented program; the first thing it does is write a prompt to cmdFile and read a response from logFile. The prompt is:

Size of hash bucket:

It appears in the CMDLOG MAINEDIT buffer, which you can think of as a terminal emulator. The debugger automatically moves the cursor to CMDLOG, so that if you type something, it is echoed and the program sees it as input. See Figure 2–8.

Answer the prompt by typing 131, followed by RETURN.

The program then prompts:

Next key to be hashed (eol to stop):

Type abc, followed by RETURN.

The debugger reaches your breakpoint. At this point, the debugger wants to display the local variables of the current PROCEDURE. To do this, it needs to create a data browser window. The data browser window appears (unless you have set up your X resources otherwise) in the upper left corner of the screen. It may wind up on top of the main debugger window; if so, move it out of the way for the moment. On the top line in the main window, the debugger prints out that it has reached the breakpoint; the message looks like:

Break at SAMPLE.HASH.number

The main window now looks as in Figure 2–9.

The data browser window looks as in Figure 2–10. It shows the local variables h, i, j, and s for hash, and also SAMPLE's outer variable bucketSize. The variables h, i, and j are uninitialized; since the program is compiled debuggable, their values are zero until something in the program sets their values.

You can look at the entire PROCEDURE call stack, as well as the local variables for the current PROCEDURE. Click the stack button in the data browser to replace the local and OWN variable display with a display of the entire stack, which looks like Figure 2–11. You may need to scroll through the stack frames of the debugger (on top of the stack) to get down to SAMPLE's stack frames.

You can click on the button to the left of each PROCEDURE name shown in the stack display to change the debugger's command context to that PROCEDURE invocation. Click on the button to the left of SAMPLE.INITIALPROC in the stack display and notice how the cursor in the main window moves to the line in SAMPLE's INITIAL PROCEDURE where hash is called:

ttyWrite(hash(s),eol & eol) END END;

Click on the button next to SAMPLE.HASH to return the command context to the PROCEDURE hash.

You can use the data browser window to display arbitrary MAINSAIL expressions, and to cause the debugger to break when certain conditions are satisfied or when an expression changes value.

In the wide text widget on the top line of the data browser (next to the watch obj button), type:

s = "c"

Then click the watch expr button. The above expression now becomes a watched expression, and the data browser displays the watched expressions list. The expression is FALSE because s still has the value "abc".

Now you want to cause the debugger to break when the expression becomes TRUE, that is, when s acquires the value "c". To do this, first click the button to the left of the expression in the watched expressions display. The Watch Expr window comes up with its description of the expression.

In the Watch Expr window, click on the button labeled NonZero (TRUE) to the right of the Break if: label. This will make the debugger break when the expression:

s = "c"

becomes TRUE.

Click on OK to confirm the breakpoint and make the Watch Expr window go away.

In the main window, choose Continue->From break from the Execution menu. You reach the breakpoint you just set: on the message line, there appears the text:

Watch expr is nonZero (TRUE) at SAMPLE.HASH.252: s = "c"

and in the data browser window, the expression is shown as having the value TRUE.

Now you want to see the local and OWN variables display in the data browser window without hiding the watched variables display. To do this, split the data browser display into two panes by clicking Create Pane. Adjust the size of the lower pane by dragging the sash box (the box towards the right side on the line between the two panes), so that the two panes are roughly equal in size. The lower (newer) pane should still be the current one (the highlighted one).

Click on the first button, which goes to the first object that was displayed in the data browser, which was the local and OWN variable display.

This debugger sample session has shown off many (but by no means all) the capabilities of the GUI debugger. It should at least give you an idea of how to start debugging your programs using the GUI.

To leave the GUI, select Exit from the File menu in the main window. Click OK in the confirmation dialog box to exit MAINSAIL.