23. Controlling and Configuring the Debugger

Chapter 8, "Testing an Application," presents an overview of the Digital Mars C++ debuggers and explains how to perform typical debugging tasks.

Chapter 24, "Commands Available in Debugging Mode," describes the commands and the functionality of each of the debug windows that you can open from the Views palette.

Commands on the Debug Menu

[Figure 23-1 Debug menu commands

This section describes the commands in the Debug menu in the order shown in Figure 23-1.

Note: Frequently used debugging commands are available from the Debug toolbox. See "Debug Toolbox Icons" in this chapter to learn how to use the Debug toolbox.

Start/Restart Debugging

Note: If you need to specify command-line parameters in your application, you can do so in the Run Arguments dialog box, available by choosing the Arguments command from the IDDE's Project menu.

If debugging is in progress, choosing Start/Restart Debugging restarts the application.

Note: If you want to run the program without debugging it, choose the Execute Program from the Project menu.

Stop Debugging

Step Into

If Step Into is used on a procedure or function call, the debugger steps into the first statement of the function only if tracing is enabled for the module containing that function. For more information, see "The Project Window," in Chapter 24, "Commands Available in Debugging Mode."

If the Assembly window is the active window, this command executes to the next assembly (as opposed to source level) instruction. If the assembly window is open but is not the active window when you use this command, it updates to show the next instruction to be executed.

Step Over

If the Assembly window is the active window, this command executes the program to the next assembly instruction without tracing into function calls. If the current instruction is a call to a function, the program executes to the assembly instruction following the call.

Return from Call

Go until Breakpoint

Go until Next Function

Go until End

Break

Animate

To set the animation delay time, choose the Animate Delay command from the Settings submenu of the Debug menu (see the section "Animate delay," later in this chapter).

Stop Animate

Settings

General

[Figure 23-2 General page of the Debugger Settings dialog box

Flip screen

When Flip Screen is turned on, the application gets control of the screen each time it runs. When Flip Screen is turned off, the debugger does not activate the application to bring it to the foreground each time the debugger gives control to the application.

Animate delay

The Animate Delay dialog box lets you specify the delay in milliseconds. For example, to pause for one second between steps, specify 1000; the default is one-half second (500 milliseconds) delay.

Load symbols when editing

Debug application startup

If you check this option, the debugger automatically sets a fixed breakpoint at the main entry point and lets you trace through the application's startup code. If not, the debugger starts tracing from WinMain() or main() onward.

Automatic switch to debug workspace

Automatic check of project dependencies

Show local data on start debugging

Enable C++ class display

Alternate class display

Source search path

Working directory

Exceptions (32-bit IDDE only)

Exceptions presented on this page are NT exceptions, which are part of the Structured Exception Handling mechanism of Win32. NT exceptions comprise both hardware exceptions (such as access violations, division by zero, or stack overflow) and software exceptions (explicitly initiated either by Win32 APIs— HeapAlloc, for instance— or by your own code). However, C++ exceptions are also accommodated on the Exceptions page. When you throw a C++ exception in a Win32 program, an NT exception is raised. The exception code of the NT exception is the same value, unique to Digital Mars C++, regardless of which C++ exception was thrown.

Note: For more information on Structured Exception Handling, see Microsoft Win32 Programmer's Reference, Volume 2.

You can specify whether or not the debugger should stop on a particular exception, or should stop only if you have not provided a handler for it. (Uses of these options are discussed below.) The Exceptions page is shown in Figure 23-3.

[Figure 23-3 Exceptions page of the Debugger Settings dialog box

Number:

Contains an exception code— a DWORD that uniquely identifies an exception. Exception codes are displayed and entered in the Number field as eight-digit hexadecimal numbers. Symbolic constants for the exception codes of predefined NT exceptions can be found in include\win32\winnt.h, located beneath the directory in which you installed Digital Mars C++.

The layout of an exception code's 32 bits is summarized in a comment in the header file include\win32\winerror.h. If you define your own exceptions, your exception code should adhere to that format.

Name:

Contains a descriptive string. No restrictions are placed on the contents of this field.

Action:

This drop-down list box contains two choices: Stop if not Handled, and Always Stop. For both actions, the debugger stops before the operating system itself responds to the exception.

Stop if not handled:

The debugger stops only if no outstanding __try/__except or __try/catch block will handle this exception.

Always stop:

The debugger stops, whether or not the exception will be handled.

If you have written a handler for a particular exception, you can choose to always stop on that exception to determine the point at which it was raised. If an exception occurs that you have not anticipated and for which you have not written a handler, either Action will make the debugger stop. You can then diagnose the cause of the exception by examining values of variables and the call chain. Stop if not Handled can also be used to debug existing exception handlers. It assists you in diagnosing situations where an exception for which you have written a handler is being raised, but which none of your handlers is catching.

Add:

Adds a new exception to the list contained in the main pane, as specified in the Number, Name, and Action fields. The Number field must contain a value not used by any exception already in the list.

Replace:

Replaces information for the currently selected exception in the main pane with the contents of the Number, Name, and Action fields. This button is disabled if the Number field contains a value different from the Number (exception code) of the selected exception.

Remove:

Deletes the currently selected exception from the list in the main pane.

Reset:

Undoes any changes to the built-in exception entries, without altering any added exceptions. If any built-in exception entries have been deleted, they are restored; all Actions and Names for built-in exception entries are reset.

Multiple EXE/DLL debugging

[Figure 23-4 Multiple EXE/DLL page of the Debugger Settings

Single executable:

Debugs only the executable file. Does not debug DLLs called by the executable.

All loading EXE/DLLs:

Debugs the executable file and all DLLs or EXEs called or spawned by the executable, including DLLs loaded at run-time via explicit calls to the LoadLibrary API.

Specific EXE/DLLs:

Debugs the executable file and specific DLLs or EXEs. Select those you want in the Specify Libraries and/or Modules to Debug portion of the dialog box (enabled only when this radio button is selected).

Calling program:

For a DLL project, this textbox lets you specify the application that calls the DLL.

Debug Toolbox Icons

Figure 23-5 Debug toolbox icons

Working with Breakpoints

• Unconditional
• Conditional
• Delayed

Unconditional breakpoints

You set unconditional breakpoints using the Set Breakpoint or the Set/Clear Breakpoint command (F9) in the Source, Assembly, Function, Data/Object, or Breakpoint windows (as well as in the Spy window when debugging a Windows application). After setting an unconditional breakpoint, choose the Go until Breakpoint command from the IDDE's Debug menu to execute your program until it reaches the breakpoint. When the breakpoint is reached, the program halts and returns control to the debugger.

Note: While in debugging mode, you can also set an unconditional breakpoint by double-clicking in the left margin of the Source window at the line where you want execution to stop.

Conditional and delayed breakpoints

• Stop the execution of the program only when a specified condition evaluates to TRUE
• Stop the execution of the program only when it encounters a breakpoint a specified number of times (this is a delayed breakpoint)
• Evaluate an expression at a breakpoint
• Add code to the program without recompiling

Note: When you choose Set Conditional Breakpoint in the Breakpoint window, the Expression dialog box is displayed first. Enter the address or procedure name (for example) where you want to set the breakpoint. The Set Code Breakpoint dialog box is then displayed to allow you to specify the kind of breakpoint to set.

[Figure 23-6 Set Code Breakpoint dialog box

The debugger automatically sets the Line, Address, and Procedure fields, based on the location of the breakpoint.

Limit:

Use this field to reach the breakpoint a specified number of times before the debugger stops program execution. This sets a delayed breakpoint.

Condition:

Use this field when you want an expression to be evaluated every time execution of the program reaches this breakpoint. If the expression evaluates to TRUE (nonzero), the debugger performs the action( s) specified in the Actions group. In the Condition field, enter the expression to be evaluated.

Evaluate:

Check this option if you want the debugger to evaluate the next field's expression whenever the program reaches this breakpoint. If you use the Condition field, a breakpoint is triggered only if the Condition evaluates to TRUE.

This field allows you to insert into your code a statement that you had neglected to include, or to test (in the debugger) that a modification works before editing, compiling, and linking.

Note: Please refer to Appendix A, "Expression Evaluation," for more information about expressions.

Break:

Check this option if you want the debugger to stop execution of the program whenever the program reaches this breakpoint. If you use the Condition field, the debugger stops execution on reaching this breakpoint only if the Condition evaluates to TRUE.

Examples of conditional breakpoints

Example 1

The debugger executes your program and evaluates the condition every time it executes the line on which the breakpoint is set. If the condition specified does not evaluate to TRUE, the debugger continues to execute your program. As soon as the value of i + j exceeds 2000 when this line is executed, the debugger stops executing the program and regains control.

Example 2

Set a conditional breakpoint on the line and specify the Evaluate option, as shown in Figure 23-7.

[Figure 23-7 Setting a breakpoint in your code

Every time the debugger reaches this line and i + j > 2000 is TRUE, it calls RESULTS.AddRes(i). However, it does not stop executing your program because you did not check the Break check box.

For information on breakpoint and watchpoint commands in windows, see "The Command Window," in Chapter 24, "Commands Available in Debugging Mode."

Working with Watchpoints

You can set watchpoints using the debugger. First, highlight either a variable in the Data/Object window or a memory location in the Memory window, then execute the Set Watchpoint command in that window's Watch menu. You need not specify an address for the watchpoint. The debugger sets the watchpoint on the address of the highlighted variable or on the highlighted location in memory.

Digital Mars C++ uses the debugging capabilities of the 80386 and higher microprocessors to provide full-speed execution of watchpoints. These microprocessors relieve the debugger of the need to check for the use of watchpoint locations when certain instructions or functions are executed. Watchpoints implemented with hardware assistance are called hardware watchpoints, in contrast to the slower software watchpoints that debuggers must implement in the absence of hardware support.

Setting watchpoints

[Figure 23-8 Set Watchpoint dialog box

You can set up to four 1-byte watchpoints. You can also set four 2-byte watchpoints if all the addresses in memory for which the watchpoints are set are word aligned.

Use watchpoints on local variables with caution

	Warning: Setting a watchpoint on stack memory