Setting and Modifying Breakpoints

Go Up to How To Use the Debugger

Breakpoints pause program execution at a certain location or when a particular condition occurs. You can set source breakpoints and module load breakpoints in the Code Editor before and during a debugging session. You can set data breakpoints and address breakpoints only when the application is running in debug mode (F9).

Breakpoint Icons

During a debugging session, any line of code that is eligible for a breakpoint is marked with a blue dot in the left gutter of the Code Editor.

You can also set breakpoints on frames displayed in the Call Stack window. The breakpoint icons in the Call Stack window are similar to those in the Code Editor, except that the blue dot in the Call Stack indicates only that debug information is available for the frame, not whether a breakpoint can be set on that frame.

Breakpoints are displayed in the Breakpoint List window, available by selecting View > Debug windows > Breakpoints.

You can drag breakpoint icons and drop them in the Code Editor window; a moved breakpoint retains the settings of the original breakpoint. The following icons are used to represent breakpoints in the Code Editor gutter.

Icon	Description
	The breakpoint is valid and enabled. The debugger is inactive.
	The breakpoint is valid and enabled. The debugger is active.
	The breakpoint is invalid and enabled. The breakpoint is set at an invalid location, such as a comment, a blank line, or an invalid declaration.
	The breakpoint is valid and disabled. The debugger is inactive.
	The breakpoint is valid and disabled. The debugger is active.
	The breakpoint is invalid and disabled. The breakpoint is set at an invalid location.

To set a source breakpoint

1. To prefill the line number in the dialog box, click the line of source in the Code Editor at the point where you want to stop execution.
2. Choose Run > Add Breakpoint > Source Breakpoint to display the Add Source Breakpoint dialog box.

   Tip: To change the Code Editor gutter, choose Tools > Options > Editor Options > Display and adjust the Gutter width option.

3. In the Add Source Breakpoint dialog box, the file name is prefilled with the name of the file, and Pass count is set to 0 (meaning that the breakpoint fires on the first pass). In the Line number field, enter the line in the Code Editor where you want to set the breakpoint.
4. To apply a condition to the address breakpoint, enter a conditional expression in the Condition field. The conditional expression is evaluated each time the breakpoint is encountered, and program execution stops when the expression evaluates to True.
5. To associate the source breakpoint with a breakpoint group, enter the name of a group or select from the Group drop-down list.
6. To set any of the Advanced options, see the Add Address Breakpoint or Add Data Breakpoint for the Add Address Breakpoint or Add Data Breakpoint dialog box.

   Note: To quickly set a breakpoint on a line of source code, click the left gutter of the Code Editor next to the line of code where you want to pause execution.

To set an address breakpoint

1. Run your application in Debug mode (for example, use F9, F8, F7, or F4).
2. Choose Run > Add Breakpoint > Address Breakpoint to display the Add Address Breakpoint dialog box.
3. In the Address field, enter the address in memory (such as $00011111) at which you want to set the breakpoint.
4. To apply a condition to the address breakpoint, enter a conditional expression in the Condition field. The conditional expression is evaluated each time the breakpoint is encountered, and program execution stops when the expression evaluates to true.
5. To specify that the address breakpoint will only fire after a number of passes, enter the number in the Pass count field.
6. To associate the address breakpoint with an existing breakpoint group, enter the group name in the Group field, or select the name of an existing group from the drop-down list.
7. To set any of the Advanced options, see the Add Address Breakpoint or Add Data Breakpoint for the Add Address Breakpoint or Add Data Breakpoint dialog box.

Note: You can also set an address breakpoint in the CPU view or the Disassembly view by clicking in the gutter.

To set a data breakpoint

1. Run your application in Debug mode (for example, use F9, F8, F7, or F4).
2. Choose Run > Add Breakpoint > Data Breakpoint to display the Add Data Breakpoint dialog box.
3. In the Address field, enter the address of the data you want to function as the data breakpoint.
4. In the Length field, specify the length of the data operand that is to constitute the breakpoint. Note that a warning is displayed for the following issues:
   • The length of the data breakpoint should not cross an even-byte boundary. (A data breakpoint with a 1-byte length has no alignment problems, but 2-byte and 4-byte data breakpoints might cover more or fewer addresses than you intend.)
   • The data breakpoint should not be set on a stack location. (The breakpoint might be hit so often that the program cannot run properly.)
5. To apply a condition to the breakpoint, enter a conditional expression in the Condition field. The conditional expression is evaluated each time the breakpoint is encountered, and program execution stops when the expression evaluates to True.
6. To specify that the breakpoint only fires after a number of passes, enter the number in the Pass count field.
7. To associate the data breakpoint with an existing breakpoint group, enter the group name in the Group field, or select the name of an existing group from the drop-down list.
8. To set any of the Advanced options, see Add Address Breakpoint or Add Data Breakpoint.

To set a module load breakpoint

1. Choose Run > Add Breakpoint > Module Load Breakpoint to display the Add Module Load Breakpoint dialog box.
2. Do either of the following:
   • In the Module name field, enter the name of the DLL, package, or other module type that you want to monitor, or select a name from the drop-down list, and click OK.
   • Click Browse to open the Select Module dialog box and browse modules from another target platform. Click the Modules dropdown next to the File Name field, and select the type of modules you want to see:
     • Modules (*.dll, *.ocx, *.bpl, *.exe, *.dylib) {both Windows and Mac modules}
     • Windows Modules (*.dll, *.ocx, *.bpl, *.exe) {only Windows modules}
     • OS X Modules (*.dylib) {only Mac modules}
     • Any file *.*

   Click Open to open the module you want. The name is automatically inserted in the Add or Edit Module Load Breakpoint dialog box.

Note: You can also use the Modules Window to set a module load breakpoint.

When the module you specify is loaded during program execution, the module load breakpoint is hit, and program execution pauses.

To persist breakpoints from session to session

If you set the Autosave Project desktop option, breakpoints you set for a project will persist from session to session.

1. Set the breakpoints (and watches) that you want to keep from session to session.
2. Select Tools > Options > Environment Options.
3. Enable Autosave Project desktop. When you exit the product or close your project, your desktop settings are saved to a .dsk file. When you reopen your project, the product reads the .dsk file and restores your saved desktop, breakpoints, watches, and open files.

You need to delete the .dsk file when you no longer want the saved set of breakpoints to persist in your project (or any other items controlled by the Autosave Project desktop option).

To modify a breakpoint

1. Open the Breakpoint List Windowby selecting View > Debug Windows > Breakpoints. Right-click the icon for the breakpoint you want to modify. For a source breakpoint, you can right-click the breakpoint icon in the Code Editor gutter, and choose Breakpoint Properties.
2. Set the options in the Breakpoint Properties dialog box to modify the breakpoint. For example, you can set a condition, create a breakpoint group, or specify an action that is to occur when execution reaches the breakpoint.
3. Click Help for more information about the options in the dialog box.
4. Click OK.

To create a breakpoint group

1. Open the Breakpoints List by choosing View > Debug Windows > Breakpoints .
2. Right-click the breakpoint and choose Breakpoint Properties.
3. To create a breakpoint group, enter a group name in the Group field. To add the breakpoint to an existing group, select a name from the drop-down list box.
4. Click OK.

To enable or disable a breakpoint or a breakpoint group

1. Right-click the breakpoint icon in either the Code Editor or the Breakpoint List Window and choose Enabled to toggle between enabled and disabled. In the Breakpoint List, you can click the checkbox at the left of the icon.
2. To enable or disable all breakpoints, right-click a blank area (not on a breakpoint) in the Breakpoint List window and choose Enable All or Disable All.
3. To enable or disable a breakpoint group, right-click a blank area (not on a breakpoint) in the Breakpoint List window and choose Enable Group or Disable Group.

Tip: You can use either of the following shortcuts to enable/disable breakpoints:

• Ctrl+Click the breakpoint symbol in the Code Editor gutter.

  An enabled breakpoint symbol, such as , changes to a disabled breakpoint symbol, such as , when you use Ctrl+Click to toggle between enabled and disabled.

• Press F5.

  The breakpoint symbol is removed when you press F5 on an enabled breakpoint, but the breakpoint symbol reappears and is enabled when you press F5 again.

Disabling a breakpoint or breakpoint group prevents it from pausing execution, but retains the breakpoint settings, so that you can enable it later.

To create a conditional breakpoint

1. Choose Run > Add Breakpoint and select the type of breakpoint you want from the submenu.
2. Complete the fields in the dialog box as described in the procedure given earlier for that breakpoint type.
3. In the Condition field, enter a conditional expression to be evaluated each time this breakpoint is encountered during program execution. The breakpoint pauses execution when the expression evaluates to True.
4. Complete other fields as appropriate.
5. Click OK.

Conditional breakpoints are useful when you want to see how your program behaves when a variable falls into a certain range or what happens when a particular flag is set.

If the conditional expression evaluates to True (or not zero), the debugger pauses the program at the breakpoint location. If the expression evaluates to False (or zero), the debugger does not stop at the breakpoint location.

To set a breakpoint on a specific thread

1. Choose Run > Add Breakpoint and select the type of breakpoint you want from the submenu.
2. Complete the fields in the dialog box as described in the procedure given earlier for that breakpoint type.
3. In the Thread field, enter or select the thread number (for numbered threads) or thread name (for named threads).
4. Complete other fields as appropriate.
5. Click OK.

To associate actions with a breakpoint

1. On the Breakpoint List Window, right-click the breakpoint and choose Breakpoint Properties.
2. Click Advanced to display additional options.
3. Check the actions that you want to occur when the breakpoint is encountered.For example, you can specify an expression to be evaluated and write the result of the evaluation to the Event Log.
4. Click OK.

To change the color of the text at the execution point or the color of breakpoints

1. Choose Tools > Options > Editor Options > Color.
2. In the code sample window, select the appropriate language tab. For example, to change the breakpoint color for Delphi code, select the Delphi tab.
3. Scroll the code sample window to display the execution and breakpoint icons in the left gutter of the window.
4. Click anywhere on the execution point or breakpoint line that you want to change.
5. Use the Foreground Color and Background Color drop-down lists to change the colors associated with the selected execution point or breakpoint.
6. Click OK.

Note: You can also set breakpoints in the Breakpoint List, the CPU window (and the Disassembly view), the Call Stack view, and the Modules window.

See Also

• Add Address Breakpoint or Add Data Breakpoint
• Add or Edit Module Load Breakpoint
• Add Source Breakpoint
• Breakpoint List Window
• CPU Windows
• Modules Window
• Call Stack Window