Setting Breakpoints

A breakpoint stops execution of a program when a specific location is reached, if a variable or expression changes its value, or if a certain condition is met. Breakpoints are events that Prism uses to control execution of a program. This section describes the methods available in Prism for setting a breakpoint.

You can set a breakpoint

• By using the line-number region

• By using the Event Table and the Events menu

• From the command window, by issuing the command stop or when

You'll probably find it most convenient to use the line-number region for setting simple breakpoints; however, the other two methods give you greater flexibility--for example, in setting up a condition under which the breakpoint is to take place.

In all cases, an event is added to the list in the Event Table. If you delete the breakpoint using any of the methods described in this section, the corresponding event is deleted from the event list. If you set a breakpoint at a program location, a B appears next to the line number in the line-number region.

Using the Line-Number Region

To use the line-number region to set a breakpoint, the line at which you want to stop execution must appear in the source window. If it doesn't, you can scroll through the source window (if the line is in the current file), or use the File or Func selection from the File menu to display the source file you are interested in.

To set a breakpoint in the line-number region:

1. Position the mouse pointer to the right of the line numbers; the pointer turns into a B.

2. Move the pointer next to the line at which you want to stop execution.

3. Left-click the mouse.

4. A B is displayed, indicating that a breakpoint has been set for that line.

   A message appears in the command window confirming the breakpoint, and an event is added to the event list.

   The source line you choose must contain executable code; if it does not, you receive a warning in the command window, and no B appears where you clicked.

   Shift-click on the letter in the line-number region to display the complete event (or events) associated with it.

See " Using the Line-Number Region" for more information on the line-number region.

See " Using the Line-Number Region in MP Prism" for a discussion of the line-number region in MP Prism.

Deleting Breakpoints via the Line-Number Region

To delete the breakpoint, left-click on the B that represents the breakpoint you want to delete. The B disappears; a message appears in the command window, confirming the deletion.

What Happens in a Split Source Window

As described in " Moving Through the Source Code", you can split the source window to display source code and the corresponding assembly code.

You can set a breakpoint in either pane of the split source window. The B appears in the line-number region of both panes, unless you set the breakpoint at an assembly code line for which there is no corresponding source line.

Deleting a breakpoint from one pane of the split source window deletes it from the other pane as well.

Using the Line-Number Region in MP Prism

MP Prism provides variations on the way that the line-number region displays breakpoints and tracepoints. In MP Prism:

• It displays a B next to a line number if all processes in the current pset have a breakpoint set at that line.

• It displays a b if some but not all of the processes in the current pset have a breakpoint set at that line.

• It displays a T if all processes in the current pset have a tracepoint set at that line.

• It displays a t if some but not all of the processes in the current pset have a tracepoint set at that line.

If there is a mixture of breakpoints and tracepoints set on the line, Prism uses the B-b-T-t sequence to determine what letter to display. For example, if a line has a breakpoint set in one process and a tracepoint set in all processes, Prism displays a b.

As in scalar Prism, you can shift-click on the letter in the line-number region to display the complete event (or events) associated with it.

Using the Event Table and the Events Menu

To set a breakpoint, choose the Stop <loc> or Stop <var> selection from the Events menu. These choices are also available as Common Events buttons within the Event Table itself; see " Adding an Event".

• Stop <loc> prompts for a location at which to stop the program. You can also specify a function or procedure; the program stops at the first line of the function or procedure.

Figure 4-3 Stop <loc> Dialog Box

• Stop <var> prompts for a variable name. The program stops when the variable's value changes. The variable can be an array, in which case execution stops any time any element of the array changes. This slows execution considerably.

In addition, Stop <cond> is available as a Common Events button. It prompts for a condition, which can be any expression that evaluates to true or false; see " Writing Expressions in Prism" for more information on expressions. The program stops when the condition is met. This slows execution considerably.

You can also use the Event Table to create combinations of these breakpoints; for example, you can create a breakpoint that stops at a location if a condition is met. In addition, you can use the Actions field of the Event Table to specify the Prism commands that are to be executed when execution stops.

Deleting Breakpoints via the Event Table

To delete a breakpoint, choose the Delete selection from the Events menu, or use the Delete button in the Event Table itself. See " Deleting an Existing Event".

Using Commands

Issue the command stop (or when, which is an alias for stop) from the command line to set a breakpoint. The syntax of the stop command is also used by the stopi, trace, and tracei commands, which are discussed below. The general syntax for all the commands is:

command [variable | at line | in func] [if expr] [{cmd[; cmd...]}] [after n]

where

• command - As mentioned above, can be stop, stopi, when, trace, or tracei.

• variable - Is the name of a variable. The command is executed (in other words, the event takes place) if the value of the variable changes. If the variable is an array, an array section, or a parallel variable, the command is executed if the value of any element changes. This form of the command slows execution considerably. You cannot specify both a variable and a program location.

• line - Specifies the line number where the stop or trace is to be executed. If the line is not in the current file, use the format:

at "filename":line-number

• func - Is the name of the function or procedure in which the stop or trace is to be executed.

• expr - Is any language expression that evaluates to true or false. This argument specifies the logical condition, if any, under which the stop or trace is to be executed. For example,

if a .GT. 1

This form of the command slows execution considerably, unless you combine it with the at line syntax. See " Writing Expressions in Prism" for more information on writing expressions in Prism.

• cmd - Is any Prism command (except attach, core, detach, load, return, run, or step). This argument specifies the actions, if any, that are to accompany the execution of the stop or trace. For example, {print a} prints the value of a. If you include multiple commands, separate them with semicolons.

• n - Is an integer that specifies how many times a triggering condition is to be reached before the stop or trace is executed; see " Overview of Events" for a discussion of triggering conditions. This is referred to as an after count. The default is 1. Once the stop or trace is executed, the count is reset to its original value. Note that if there is both a condition and an after count, the condition is checked first.

The first option listed (specifying the location or the name of the variable) must come first on the command line; the other options, if you include them, can be in any order.

For the when command, you can use the keyword stopped to specify that the actions are to occur whenever the program stops execution.

When you issue the command, an event is added to the event list. If the command sets a breakpoint at a program location, a B appears in the line-number region next to the location.

Examples

To stop execution the tenth time in function foo and print a:

stop in foo {print a} after 10

To stop at line 17 of file bar if a is equal to 0:

stop at "bar":17 if a == 0

To stop whenever a changes:

stop a

To stop the third time a equals 5:

stop if a .eq. 5 after 3

To print a and do a stack trace every time the program stops execution:

when stopped {print a; where}

For Machine Instructions

To set a breakpoint at a machine instruction, issue the stopi command, using the syntax described above, and specifying a machine address. For example,

stopi at 0x1000

stops execution at address 1000 (hex).

The history region displays the address and the machine instruction. The source pointer moves to the source line being executed.

Deleting Breakpoints via the Command Window

To delete a breakpoint via the command window, first issue the show events command. This prints out the event list. Each event has an ID number associated with it.

To delete one or more of these events, issue the delete command, listing the ID numbers of the events you want to delete; separate multiple IDs with one or more blank spaces. For example,

delete 1 3

deletes the events with IDs 1 and 3. Use the argument all to delete all existing events.