Setting Watchpoints

Use watchpoints to monitor the value of a variable or memory range. (See “Examining Registers ” for information on monitoring registers.) Values are displayed in the Data Watchpoint dialog box as well as in the debugger output area.

When you create a watchpoint, you specify the expression or address range to monitor, and a granularity. The granularity specifies how often the value should be reported: on procedure entry, on procedure exit, on procedure entry and exit, at every statement, at every machine instruction, or whenever the program stops and returns control to the debugger.

The default granularity is to stop and report value changes only when the target program itself stops and returns control to the debugger. If you needed to monitor a variable more closely, you could specify a instruction- or statement-level granularity. At instruction-level granularity, for example, the value of a variable is checked after every assembly instruction executes. Execution of the target program stops when the value changes.

For performance purposes, you should set the granularity as coarsely as possible. For example, if you only need to know the value of the monitored expression each time you enter a procedure, there is no sense in monitoring it after every assembly instruction. Typically you would locate a problem by using a granularity of procedure entry/exit to narrow the source of the problem down to one procedure. Once the problem is localized, use a finer granularity (such as instruction or statement) but limit it to a particular procedure by entering the procedure name in the When In input box in the Data Watchpoint Set/Change dialog box.

Viewing and Modifying Watchpoints

The following sections describe some of the methods for setting watchpoints. When you set a watchpoint by any method, the Data Watchpoints dialog box is displayed (you can also invoke it by selecting Watch:Values Display). See Figure 3-3 “The Data Watchpoints Dialog Box ”.

Figure 3-3 The Data Watchpoints Dialog Box

The Data Watchpoints dialog box shows detailed information on each watchpoint and it allows you to manipulate both the watchpoints and the display itself.

Each watchpoint displays the variables or memory area it is attached to. The data display highlights when the data being watched is modified. Complete watchpoints can be hidden by selecting the down arrow button next to the watchpoint. Select the button again (which is now the ëëright arrow button) to redisplay the watchpoint.

Individual elements in a watchpoint (such as some elements in an array) can be hidden by selecting them and selecting Selected -> Hide. Select Watchpoint -> Show All Hidden Values to redisplay them.

Compound objects (such as arrays or structures) can be collapsed to simplify the display, either by double-clicking the beginning of the compound object, or by selecting it and choosing Selected -> Collapse. Double-click the collapsed object, or choose Selected -> Expand, to display the entire object.

To modify the watchpoint, choose Watchpoint -> Change. The Data Watchpoints dialog box is displayed, allowing you to modify all editable attributes of the watchpoint.

To change the Active/Suspend status of a watchpoint, use the Data Watchpoints dialog box. You can also activate or suspend all watchpoints by selecting the Activate All or Suspend All buttons in the Data Watchpoints window, or by choosing the Watch: Suspend ALL or Watch: Activate ALL menu selections.

Use Watchpoint -> Delete to eliminate a watchpoint.

Using Command Buttons

The following buttons are located below the source file display area:

Watch(): Set a watchpoint on the contents of the ( ): input box. Check the watchpoint whenever the debugger stops.
Watch*(): Set a watchpoint on the location pointed to by the pointer in the ( ): input box. Check the watchpoint whenever the debugger stops.

An easy way to enter tokens in the ( ): input box is to use the mouse to highlight expressions in the source display. Highlight by dragging with the left mouse button depressed. When you release the left mouse button, the expression appears in the ( ): input box.

Use Options:User Configurable Buttons to modify the default behavior of the command buttons.

Using the Watch Menu

A variety of watchpoint commands are available from the Watch menu. Many entries on the Watch menu allow you to set a watchpoint associated with an expression entered in the ( ): input box.

As Figure 3-4 “The Watch Menu ” shows, the Watch menu is a Tear-off Menu. When you click on the dashed line at the top of the Watch menu, the menu is displayed in its own window. The menu persists so that you can invoke commands from it without having to redisplay it. You can also move the menu to a convenient place in your workspace.

Figure 3-4 The Watch Menu

Using the Data Watchpoint Set/Change Dialog Box

The Data Watchpoint Set/Change dialog box allows you to specify all aspects of a watchpoint. Invoke it by selecting Watch:Set. The dialog box in Figure 3-5 “The Data Watchpoint Set/Change Dialog Box ” appears.

Figure 3-5 The Data Watchpoint Set/Change Dialog Box

From the Data Watchpoint Set/Change dialog box, you can:

Select the type of watchpoint.
The area under the Select Watchpoint Type radio buttons changes to reflect the information needed by the watchpoint type. Enter the appropriate information for the selected watchpoint type.
Note that you use the Print ( ) button on the expression &var to find the address of the variable var.
Select the granularity (how often the value is checked).
The default, Every Stop, causes the debugger to check values only when target program execution stops for some event like a breakpoint.
If you want target program execution to stop whenever the value changes, choose Statement granularity. Be aware, however, that Statement granularity can slow down performance of the target program.
You can also restrict a watchpoint to be active only in a specified block.
In C++ programs, you can specify how many levels of inherited data members should be included.
Control whether or not messages appear when a watchpoint is hit.
Temporarily disable or re-activate watchpoints.
Specify the format in which the value is displayed. The default is to display the value as it is declared.
Specify debugger commands to execute when a watchpoint is hit.

To see a listing of watchpoints, select Watch:Show.

Using the watchpoint Command

The following command sets a watchpoint on the variable idx. By default, the watchpoint is in effect at every statement in the program; that is, the debugger checks the value of idx after each program statement executes, and it stops program execution if the value of idx changes.

watchpoint idx
The initial value of \\test\print_msg\idx is 0
go
The value of \\test\print_msg\idx has changed from 0 to 9.
Stopped at: \\test\print_msg\28

See Monitoring Memory Ranges in the online help for information on monitoring addresses with the watchpoint command.

Setting Watchpoints

Technical documentation

» Table of Contents

» Glossary

» Index

Viewing and Modifying Watchpoints

Using Command Buttons

Using the Watch Menu

Using the Data Watchpoint Set/Change Dialog Box

Using the watchpoint Command