Using the Debugger

The debugger includes menu items, windows, and dialog boxes. You can obtain help on any window, dialog box, or control by selecting the item and pressing F1. You can drag and drop to move debug information between interface elements.

  • Execution Control
  • Attaching to a Running Program or Multiple Programs
  • Breakpoints
  • Inspecting Your Program


Execution Control

The debugger provides powerful commands for controlling the execution of your application. Using debugger commands, you can:

  • Start execution
  • Break execution
  • Stop execution
  • Step through your application
  • Run to a desired location
    • Run to a specified function
    • Run to the cursor location
  • Set the execution point


Starting Execution

To start debugging

  • From the Debug menu, choose Start, Step Into, Step Over, or Run to Cursor.

If you choose Start, your application starts up and runs until it reaches a breakpoint. You can break execution at any time to examine values, modify variables, and otherwise examine the state of your program.

If you choose Step Into, your application starts up and executes its first statement, then breaks. If the first statement is a function call, execution breaks inside the called function, just before the first statement in that function.

If you choose Step Over, your application starts up and executes its first statement. If that statement is a function call, the application executes the entire function call and execution breaks in the main program just after the call statement.

If you choose Run to Cursor, your application starts up and runs until it reaches a breakpoint or the cursor location, whichever comes first. You can set the cursor location in a source window. In some cases, a break does not occur. This means that execution never reached the code where the cursor is set.


Stopping Execution

Stopping execution means terminating the program you are debugging and ending the debugging session. It should not be confused with breaking execution, which temporarily halts execution of the program you are debugging but leaves the debugging session active.

To stop debugging

  • From the Debug menu, choose Stop Debugging.

If you want to stop the run you are currently debugging and immediately begin a new run, you can use the Restart command.

To stop debugging and restart

  • From the Debug menu, choose Restart.


Breaking Execution

When you are debugging an application with the debugger, your application is either running (executing) or it is in break mode. Many debugger features are available only in break mode.

You can break execution manually at any time.

To break execution of your program manually

  • From the Debug menu, choose Break.

    The debugger stops execution of your program, but the program does not exit and you can resume execution at any time. The debugger and your application are now in break mode.

If you are debugging multiple programs, a Break command or breakpoint normally affects all programs being debugged. You can change this default if you want to break only the current program.

To change break behavior when debugging multiple programs

  1. From the Tools menu, choose Options.
  2. In the Options dialog box, select the Debugging folder.
  3. In the Debugging folder, select the General page.
  4. In the General group, select or clear In break mode, only stop execution of the current program.


Stepping

One of the most common debugging procedures is stepping — executing code one unit (statement or line) at a time. With the debugger, you can choose the step unit you want to use — a language statement, a source line, or a machine instruction.

To change the step unit

  • From the Debug menu, choose Step By and select Statement, Line, or Instruction.

The Debug menu provides three commands for stepping through code:

  • Step Into
  • Step Over
  • Step Out

Step Into and Step Over differ in only one respect — the way they handle function calls. Either command instructs the debugger to execute the next unit of code. If the next unit contains a function call, Step Into executes only the call itself, then halts at the first unit of code inside the function. Step Over executes the entire function, then halts at the first unit outside the function. Use Step Into if you want to look inside the function call. Use Step Over if you want to avoid stepping into functions.

On a nested function call, Step Into steps into the most deeply nested function. If you use Step Into on a call like Func1(Func2), the debugger steps into the function Func2. If you want to select which nested function to step into, use the Step Into Specific Function command from the shortcut menu.

Use Step Out when you are inside a function call and want to return to the calling function. Step Out resumes execution of your code until the function returns, then breaks at the return point in the calling function.

You cannot access the Step commands if your application is running. Step commands are valid only in break mode or before you start the application.

To step into a program that is not yet executing

  • From the Debug menu, choose Step Into.

To step while debugging

  1. The debugger must be in break mode.
  2. From the Debug menu, choose Step Into, Step Out, or Step Over.


Run to a Specified Function

You can command the debugger to run your application until it reaches a specified function. You can specify the function by name (using the toolbar) or you can choose it from the call stack.

To run to a specified function in an open source file

  1. On the standard toolbar, type the function name in the Find box and press ENTER. This moves the cursor to the specified function or a call to that function.
  2. Repeat step 1, if necessary.
  3. From the Debug menu, select Run To Cursor.

To run to a function on the call stack

  1. The debugger must be in break mode.
  2. Open the Call Stack window, if necessary. (Choose Call Stack from the Debug menu, Windows submenu.)
  3. In the Call Stack window, click a function name to select it.
  4. From the Debug menu, choose Run To Cursor.


Run to the Cursor Location

You can command the debugger to run your application until it reaches the location where the cursor is set. This location may be in a source window. (The cursor means the insertion point you set by clicking the window with the mouse.)

To run to the cursor in a source window

  1. The debugger must be in break mode.
  2. In a source file, click a source line to move the cursor to that point.
  3. From the Debug menu, select Run To Cursor.

    The break location depends on the step unit chosen through the Step By command on the Debug menu. If the step unit is line, execution breaks at the first statement on the line. If the step unit is statement, execution breaks at the statement containing the cursor.


Running to a Specified Location

Sometimes, while debugging, you will want to execute to a certain point in code, then break. If you have a breakpoint set at that location, click Start or Continue from the Debug menu. You do not need to set a breakpoint in all cases, however. The debugger provides specific commands to run to the cursor location or to a specified function.


Setting the Execution Point

In the debugger, you can move the execution point to set the next statement of code to be executed. An arrowhead in the margin of a source window marks the current location of the execution point. By moving the execution point, you can skip over a portion of code or return to a line previously executed. This can be useful in some situations — for example, if you want to skip a section of code that contains a known bug and continue debugging other sections.

Caution Changing the execution point causes the program counter to jump directly to the new location. Use this command with caution. Note that:

  • Instructions between the old and new execution points are not executed.
  • If you move the execution point backwards, intervening instructions are not undone.
  • Moving the execution point to another function or scope usually results in call-stack corruption, causing a run-time error or exception. If you try moving the execution point to another scope, the debugger opens a dialog box that gives you a warning and a chance to cancel the operation.

You cannot set the execution point while your application is actively running. To set the next statement, the debugger must be in break mode.

To set the next statement to execute

  1. In a source window, click to select the statement you want to execute next.
  2. From the Debug menu, choose Set Next Statement.

If the current execution point is in the same source file as the statement you want to set, you can move the execution point by dragging the marker arrow:

To set the next statement to execute (alternative method)

  • In a source window, click the execution point marker (yellow arrowhead) and drag it to a location in the same source file where you want to set the next statement.


Attaching to a Running Program or Multiple Programs

The debugger has the ability to attach to a program that is running in a process outside of the environment. You can use this attach capability to:

  • Debug a program that was not created in Microsoft Office.
  • Debug multiple programs simultaneously.
  • Start the debugger automatically when a program crashes while running outside of the environment (just-in-time debugging).

Once you have attached to a program, you can use debugger execution commands, inspect the program state, and so on. Your ability to inspect the program may be limited, of course, depending on whether the program was built with debug information and whether you have access to the program's source code.

To attach to a running program

  1. From the Debug menu, choose Programs.
  2. In the Programs dialog box, find the program you want to attach to from the Available Processes list..
  3. Click the Attach button.
  4. In the Attach to Process dialog box, make sure Script is selected in Choose the program types that you want to debug .
  5. Click OK.
  6. At the bottom of the Programs dialog box is a drop-down list box labeled When debugging is stopped. Choose the behavior you want to occur when you stop debugging the selected program. In most cases, it is okay to terminate the program when debugging stops, but you may want to keep it running (for example, so that you can attach to it again in the future.) If you attach to a system process, be especially careful. Terminating a system process can have sudden and undesirable effects, including crashing the system. If you do not want the program to terminate when the debugging session ends, choose Detach from this process rather than Terminate this process.
  7. Click OK.

The Available processes list is displayed automatically when you open the Programsdialog box. Processes can start and stop in the background while the dialog box is open, however, so the contents may not always be current. You can refresh the list at any time to see the current list of processes.

To refresh the Programs list

  • Click the Refresh button.

You can be attached to multiple programs when you are debugging, but only one program is active in the debugger at any given time. You can set the active program in the Debug Location toolbar.

All Debug menu execution commands affect the active program. If you choose Break from the Debug menu, the debugger breaks the active program. You can break any debugged program, active or inactive, from the Programsdialog box.

To break a program being debugged

  1. In the Programs dialog box, locate the process you want to break to in the Debugged Programs list.
  2. Click the Break button.

When you are finished debugging an attached program, you can detach from the program.


Setting the Current Program

To set the current program

  • On the Debug Location toolbar, select the Program list box and choose the program you want to make current.


Just-In-Time Debugging

Just-in-time debugging is a technique for debugging a program that is started outside of the environment. You can run a program created in Office outside of the environment. If you have enabled Just-in-time debugging, the program will bring up a dialog box when a crash occurs. This dialog box will ask if you want to debug the program and which debugger you want to use.

To enable Just-In-Time debugging

  1. From the Tools menu, select Options.
  2. In the Options dialog box, select the Debugging folder.
  3. In the Debugging folder, select the General page.
  4. Under Just-In-Time Debugging, click Settings.
  5. In the JIT Debugging Settings dialog box, you can enable or disable Just-In-Time debugging for script by selecting or clearing the Enable JIT debugging option.
  6. Click Close, and then click OK.


Breakpoints

A breakpoint tells the debugger that an application should break (pause execution) at a certain point or when a certain condition occurs. When a break occurs, your program and the debugger are said to be in break mode.

The debugger has three types of breakpoints:

  • A function breakpoint causes the program to break when execution reaches a specified location within a specified function.
  • A file breakpoint causes the program to break when execution reaches a specified location within a specified file.
  • An address breakpoint causes the program to break when execution reaches a specified memory address.
  • To provide greater power and flexibility, you can modify the behavior of a breakpoint by adding these properties:
  • A Hit Count property, which determines how many times a breakpoint must be hit before execution breaks. (By default, execution breaks every time a breakpoint is hit.)
  • A Condition, which is an expression that determines whether the breakpoint is hit or skipped.

The Breakpoints window lists all breakpoints currently set in your program and displays their properties. In the Breakpoints window, you can set (create) new breakpoints, delete breakpoints, enable or disable breakpoints, edit a breakpoint's properties, or go to the source code corresponding to a breakpoint.

The source windows show the location of a breakpoint by coloring the text where the breakpoint is located and displaying a symbol or glyph in the left margin.

Glyph | State | Meaning
 | Enabled | A normal or active breakpoint. This is where execution will break if the breakpoint condition and hit count settings are met.
 | Disabled | A breakpoint that will be ignored by the debugger. It does not affect execution until reenabled.
 | Error | A breakpoint cannot be set because the location or condition is not valid.
 | Warning | A breakpoint cannot be set because the code at this location is not loaded. If the code is loaded in the future (for example, when a class or DLL is loaded), the breakpoint becomes an enabled breakpoint.
 | Mapped | A breakpoint is set in ASP code, and a corresponding breakpoint is set in the generated HTML page.

A breakpoint that is set and enabled appears as a solid red disk. A breakpoint that is disabled appears as an empty red circle. A breakpoint that is currently unavailable to the debugger (such as a breakpoint in a DLL that is not loaded) appears as a solid gray dot. You can set, enable, disable, edit, or delete these breakpoints in the source window. For details, see Breakpoint Operations in a Source Window.

You can remove all breakpoints from the Debug menu.


Hit Count

The hit count is the number of times a breakpoint is hit. For a location breakpoint, this is the number of times execution reaches the specified location (and satisfies the break condition, if one is attached).

The Hit Count property determines how many hits occur before execution breaks.

By default, execution breaks every time a breakpoint is hit. If you specify a Hit Count property, you can choose to:

  • Break always (the default).
  • Break when the hit count equals a specified value.
  • Break when the hit count equals a multiple of a specified value.
  • Break when the hit count is greater or equal to a specified value.

You can specify a hit count for any type of breakpoint: function, file, or address.

To specify or edit the Hit Count property, you must open the Hit Count dialog box.

If you specify a Hit Count property for a breakpoint, you can open the Hit Count dialog box to view or reset the current hit count at any time while your program is running.

Tip The debugger does not keep track of the current hit count if the default mode (break always) is selected. If you want to break every time the breakpoint is hit, but you also want to keep track of the hit count in the dialog box, you must choose break when the hit count is a multiple of 1.


Opening the Hit Count Dialog Box

To specify or change a hit count when creating a new breakpoint

  • In the New Breakpoint dialog box, click the Hit Count button.

To specify or change a hit count for an existing breakpoint

  1. In the Breakpoints window, select the breakpoint you want.
  2. In the toolbar at the top of the window, select the Properties tool.
  3. In the Breakpoint Properties dialog box, click the Hit Count button.

To specify or change a hit count for an existing breakpoint in a source or Call Stack window

  1. Right-click the breakpoint and choose Breakpoint Properties from the shortcut menu.
  2. In the Breakpoint Properties dialog box, click the Hit Count button.


Condition

A break condition is an expression that gets evaluated when the breakpoint is reached. The result of the evaluation determines whether the breakpoint is hit. If the breakpoint is hit (and the hit count is correct), the debugger breaks execution.

To specify or change a breakpoint condition, you must open the Breakpoint Condition dialog box.

The condition can be any valid expression recognized by the debugger.

You can specify how the condition is satisfied:

  • When the expression is true (is true in the Breakpoint Condition dialog box)

- or -

  • When the value of the expression changes (has changed in the Breakpoint Condition dialog box)

    Note When you first set a breakpoint that uses has changed, the expression has no value. When the breakpoint is reached, the expression is evaluated and stored. The debugger does not consider that evaluation and store to be a change, so the debugger does not stop the first time the breakpoint is reached.


Opening the Breakpoint Condition Dialog Box

To specify or change a breakpoint condition when creating a new breakpoint

  1. In the Breakpoints window, select the breakpoint you want.
  2. On the toolbar at the top of the window, click the Properties tool.
  3. In the New Breakpoint dialog box, click the Conditions button.

To specify or change a breakpoint condition when creating a new breakpoint from a source or Call Stack window

  1. Right-click the breakpoint and choose Properties from the shortcut menu.
  2. In the Breakpoint Properties dialog box click the Conditions button.


Inserting a New Breakpoint from the Debug Menu

No matter which window you are using, you can insert a new breakpoint of any type by selecting New Breakpoint from the Debug menu.

To insert a new breakpoint

  1. On the Debug menu, click New Breakpoint. The New Breakpoint dialog box appears.
  2. Click the Function, File, Address, or Data tab, depending on the type of breakpoint you want to set.
  3. Set the properties on the chosen tab.
  4. Click the Condition or Hit Count button, if you want to add either of those properties.
  5. Click OK.

    Note If you switch tabs any time prior to clicking OK, the breakpoint will be set according to the settings on the last tab selected.


Removing All Breakpoints

To remove all breakpoints in your project

  • On the Debug menu, click Clear All Breakpoints. The breakpoint symbols vanish. So do all breakpoints in the Breakpoints window and everywhere else in your solution.


Breakpoint Operations in a Source Window

In a source window, you can view, set, enable, disable, delete, or edit a file, function, or address breakpoint..

The following list shows the breakpoint operations you can perform from a source window:

  • Insert a file breakpoint
  • Insert a function breakpoint
  • Insert an address breakpoint
  • Delete a breakpoint
  • Enable or disable a breakpoint
  • Edit a breakpoint


Inserting a Function Breakpoint in a Source Window

To insert a function breakpoint

  1. In the source window, select the name of the function where you want to insert a breakpoint.
  2. Select New Breakpoint from the shortcut menu.

    The New Breakpoint dialog box appears with the Function tab enabled. The name of the function you selected appears in the Function box and the language the function is written in appears in the Language box. By default, the Line and Character columns are set to 1. If you accept these default values, the breakpoint will be set at the beginning of the function.

  3. Edit the Line and Character settings if you want to place the breakpoint at another location in the function.
  4. Click OK.


Inserting a File Breakpoint in a Source Window

The most intuitive type of breakpoint in a source window is the file breakpoint. A file breakpoint is set at a location in the source file.

File breakpoints can be set on a source line or a statement. If the step unit is set to Line, the breakpoint is set at the beginning of the line and corresponds to the first complete statement on the line. If the step unit is set to Statement, the breakpoint is set at the specified character on the line and corresponds to the statement at that location.

To insert a file breakpoint in a source window

  1. In the source window, click the line and character where you want to insert the breakpoint.
  2. On the Debug toolbar, click the Insert Breakpoint button.

    -or-

    Right-click and choose Insert Breakpoint from the shortcut menu.

    Note If you try to set a breakpoint on a line that does not contain executable code, the debugger automatically moves the breakpoint to the next line that contains executable code. (If debugging is stopped, this movement does not occur until you start debugging.) You cannot set a breakpoint inside an attribute. If you try to set a breakpoint on an attribute, the debugger automatically moves the breakpoint to the next line that contains executable code.


Deleting a Breakpoint in a Source Window

In a source window, you can view file, function, or address breakpoints as symbols in the left margin. You can delete these breakpoints using the procedure given below.

To delete a file, function, or address breakpoint

  1. Right-click the line containing the breakpoint symbol (a solid dot or empty circle, depending on the breakpoint state).

    Note If the breakpoint was set on a specific character (with Step By set to statement), you must right-click the exact character where the breakpoint is set.

  2. From the shortcut menu, choose Remove Breakpoint.


Editing a Breakpoint in a Source Window

In a source window, you can view file, function, or address breakpoints as symbols in the left margin. You can edit the properties of these breakpoints using the procedure given below.

To edit a file, function, or address breakpoint

  1. Right-click the line containing the breakpoint symbol (a solid dot or empty circle, depending on the breakpoint state).

    Note If the breakpoint was set on a specific character (with Step By set to statement), you must right-click the exact character where the breakpoint is set.

  2. From the shortcut menu, choose Breakpoint Properties.

    The Breakpoint Properties dialog box appears.

  3. In the Breakpoint Properties dialog box, edit the breakpoint properties you want to change.


Enabling/Disabling a Breakpoint in a Source Window

In a source window, you can view file, function, or address breakpoints as symbols in the left margin. You can enable or disable these breakpoints using the procedures given below.

When you set a breakpoint, it is enabled by default. The breakpoint remains enabled until you disable it.

To disable a file, function, or address breakpoint

  1. Right-click the line containing an enabled breakpoint symbol (a solid dot).
  2. From the shortcut menu, choose Disable Breakpoint. The breakpoint symbol becomes an empty circle.

Once you have disabled a breakpoint, you can reenable it by similar procedure.

To enable a file, function, or address breakpoint

  1. Right-click the line containing an enabled breakpoint symbol (an empty circle).
  2. From the shortcut menu, choose Enable Breakpoint. The breakpoint symbol becomes a solid dot.


Deleting a Breakpoint in the Call Stack Window

In the Call Stack window, breakpoint symbols appear in the left margin next to the name of the function call where they are set. You can delete a breakpoint using the procedure given below.

To delete a breakpoint in the Call Stack window

  1. Right-click the line containing the breakpoint symbol (a solid dot or empty circle, depending on the breakpoint state).
  2. From the shortcut menu, choose Remove Breakpoint.


Enabling/Disabling a Breakpoint in the Call Stack Window

In the Call Stack window, breakpoint symbols appear in the left margin next to the name of the function call where they are set. You can disable or enable a breakpoint using the procedure given below.

To disable a breakpoint in the Call Stack window

  1. Right-click the line containing a disabled breakpoint symbol (a solid dot).
  2. From the shortcut menu, choose Disable Breakpoint. The breakpoint symbol becomes an empty circle.

Once you have disabled a breakpoint, you can reenable it with a similar procedure.

To enable a file, function, or address breakpoint

  1. Right-click the line containing a disabled breakpoint symbol (an empty circle).
  2. From the shortcut menu, choose Enable Breakpoint. The breakpoint symbol becomes a solid dot.


Editing a Breakpoint in the Call Stack Window

In the Call Stack window, breakpoint symbols appear in the left margin next to the name of the function call where they are set. You can edit the properties of a breakpoint using the procedure given below

To edit a breakpoint

  1. Right-click the line containing the breakpoint symbol (a solid dot or empty circle, depending on the breakpoint state).
  2. From the shortcut menu, choose Breakpoint Properties.

    The Breakpoint Properties dialog box appears.

  3. In the Breakpoint Properties dialog box, edit the breakpoint properties you want to change.
  4. Click OK.


Using the Breakpoints Window

The Breakpoints Window lists all breakpoints currently set in your program and displays their properties. In the Breakpoints window, you can set (create) new breakpoints, delete breakpoints, enable or disable breakpoints, edit a breakpoint's properties, or find the source code corresponding to a breakpoint.

To display the Breakpoints window

  • From the Debug menu, choose Windows and click Breakpoints.

Viewing Breakpoint Information

The Breakpoints window contains a list of all breakpoints currently set in your program. This list contains three columns of information by default. You can view additional information by adding more columns.

To display additional columns

  • In the toolbar at the top of the Breakpoints window, click the Columns tool and select the name of the column you want to display.

To widen or narrow a column

  • Click the column divider and drag the divider left or right.

To hide a column

  • In the toolbar at the top of the Breakpoints window, click the Columns tool and deselect the name of the column you want to hide.

    -or-

  • Drag the column divider to narrow the column width to zero.

To rearrange the order of the columns

  • Drag and drop the column header.

Enabling/Disabling Breakpoints

A check box appears in the Name column next to each breakpoint. The state of this check box tells you whether the breakpoint is enabled or disabled.

To enable or disable a single breakpoint

  • Select or clear the check box next to that breakpoint.

Setting, Deleting, and Editing Breakpoints

To set a new breakpoint

  1. In the toolbar at the top of the Breakpoints window, choose the New Breakpoint icon.
  2. In the New Breakpoint Dialog Box, choose the type of breakpoint and the options you want.
  3. Click OK.

To delete a breakpoint

  1. In the Breakpoints window, click the breakpoint you want to delete.
  2. In the toolbar at the top of the window, choose the Delete tool.

To edit a breakpoint

  1. In the Breakpoints window, click the breakpoint you want to edit.
  2. In the toolbar at the top of the window, choose the Properties tool.
  3. In the Breakpoint Properties dialog box, choose the type of breakpoint and the options you want.
  4. Click OK.

Viewing The Location Of a Breakpoint

For breakpoints that are set on a source file location or memory address, you can view the breakpoint location in the source file.

To view the location of a breakpoint in the source code

  1. In the Breakpoints window, click the breakpoint you want to view.
  2. In the toolbar at the top of the window, choose the Go To Source Code tool.

    For breakpoints without locations, the Go To Source Code tool is disabled.


Why Do Breakpoints Fail when Multiple Source Files Have the Same Name?

If two or more source files in the project have the same name, the debugger may have trouble determining which file the breakpoint is set in. This often happens if you create a module with the same name as a component of the Debug library you are linking to.

To fix this problem, enter the full pathname for the source file. You can change the file name on the File tab of the Breakpoint Properties dialog box.


Inspecting Your Program

The primary purpose of any debugger is to display information about the state of the program being debugged and, in some cases, to modify that state. The debugger provides a variety of tools for inspecting and modifying the state of your program.

One of the least obtrusive tools is the DataTips pop-up information box. When the debugger is in break mode, you can view the value of a variable within the current scope by placing the mouse pointer over the variable in a source window. A DataTips pop-up box appears. To view the value of an expression, select the expression. DataTips pop-up information is not available for expressions outside the current scope or invalid expressions, such as division by zero.

For more detailed inspection of your program, the debugger provides a variety of windows and dialog boxes:

You can use... | To view...
Autos window
  • Variables in the current statement and previous statement
Locals window
  • Local variables
QuickWatch dialog box
  • Variables
  • Any valid expression recognized by the debugger
Watch window
  • Variables
  • Any valid expression recognized by the debugger
Call Stack window
  • Names of functions on the call stack
  • Parameter types
  • Parameter values
Running Documents Window | A list of documents, script code, that are loaded into the current process.


Using the QuickWatch Dialog Box

To open the QuickWatch dialog box

  • From the Debug menu, choose QuickWatch. (The debugger must be in break mode.)

    — or —

  • In a source window, right-click a variable name and choose QuickWatch from the shortcut menu. This automatically places the variable into the QuickWatch dialog box. (The debugger must be in break mode.)

As the name implies, you can use QuickWatch to quickly evaluate a variable or expression.

QuickWatch is a modal dialog box. You cannot leave it open to watch a variable or expression while you step through your program. If you need to do that, you can add it to the Watch window.

The QuickWatch dialog box is resizable.

To resize the QuickWatch dialog box

  • Click the lower-right corner of the dialog box and drag it.


Evaluating an Expression in the QuickWatch Dialog Box

To evaluate a variable or expression

  1. In the QuickWatch dialog box, type or paste the variable or expression into the Expression text box.
  2. Click Recalculate.
  3. The value appears in the Current value box.
  4. If you typed the name of an array or object variable in the Expression box, a tree control appears next to the name in the Current value box. Click the plus (+) or minus (–) in the Name column to expand or collapse the variable.

To save the trouble of retyping a previous expression, you can choose it from the drop-down list attached to the Expression box.

To reenter a previous expression

  1. Click the down arrow at the right of the Expression box.
  2. Choose the expression from the drop-down list.
  3. Click Recalculate.


Editing a Value in QuickWatch

To change the value of a variable

  1. Type the variable name in the Expression text box.
  2. Click Recalculate.
  3. If you typed the name of an array or object variable in the Expression box, a tree control appears next to the name in the Current value box. Click the plus (+) or minus (–) in the Name column to expand or collapse the variable to find the element whose value you want to edit.
  4. Double-click the Value column of the Current value box to select the value.
  5. Use the mouse and keyboard to edit the value.
  6. Press ENTER.

    Caution Editing floating-point values can result in minor inaccuracies due to decimal-to-binary conversion of fractional components. Even a seemingly innocuous edit can result in changes to some of the least significant bits in a floating-point variable.


Adding a QuickWatch Expression To the Watch Window

To add a variable or expression to the Watch window

  1. In the QuickWatch dialog box, enter the variable or expression in the Expression box.
  2. Click the Add Watch button.


Using the Watch Window

To display the Watch window

  • From the Debug menu, choose Windows and click Watch. (The debugger must be running or in break mode.)

You can use the Watch window to evaluate variables and expressions and keep the results.

Tip The QuickWatch dialog box provides a quicker, simpler way of evaluating or editing a single variable or expression.


Evaluating an Expression in the Watch Window

To evaluate a variable expression

  1. The debugger must be in break mode.
  2. In the Watch window, double-click an empty row in the Name column.
  3. Type or paste the variable or expression in the selected row.

    Tip You can use the context operator to specify the exact context of a variable or expression. This can be useful, for example, if you want to watch a variable outside the current scope.

  4. Press ENTER.
  5. The result appears in the Value column. If you typed the name of an array or object variable, a tree control appears next to the name in the Name column. Click the plus (+) or minus (–) in the Name column to expand or collapse the variable.
  6. The expression remains in the Watch window until you remove it or until you end the debugging session.


Editing a Value in the Watch Window

To evaluate a variable or expression

  1. The debugger must be in break mode.
  2. If you typed the name of an array or object variable in the Expression box, a tree control appears next to the name in the Current value box. Click the plus (+) or minus (–) in the Name column to expand or collapse the variable to find the element whose value you want to edit.
  3. Double-click the Value column, in the row corresponding to the variable or expression whose value you want to change.
  4. Use the mouse and keyboard to edit the value.
  5. Press ENTER.

You cannot edit the value of const variables.


Using the Locals Window

To display the Locals window

  • From the Debug menu, choose Windows and click Locals. (The debugger must be running or in break mode.)

The Locals window displays variables local to the current context. The default context is the function containing the current execution location. You can choose an alternative context to display in the Locals window.

To choose an alternative context

  • Use the Debug Location toolbar to select the desired function or program.

To view or modify information in the Locals window, the debugger must be in break mode. If you choose Continue, some information may appear in the Locals window while your program executes, but it will not be current until the next time your program breaks (in other words, it hits a breakpoint or you choose Break from the Debug menu).

To modify the value of a variable in the Locals window

  1. The debugger must be in break mode.
  2. In the Locals window, select the value you want to edit by double-clicking on it or by using the TAB key.
  3. Type the new value, and press ENTER.

    Caution Editing floating-point values can result in minor inaccuracies due to decimal-to-binary conversion of fractional components. Even a seemingly innocuous edit can result in changes to some of the least significant bits in the floating-point variable.


Using the Autos Window

To display the Autos window

  • From the Debug menu, choose Windows and click Autos. (The debugger must be running or in break mode.)

The Autos window displays variables used in the current statement and the previous statement. The current statement is the statement at the current execution location (the statement that will be executed next if execution continues). The debugger identifies these variables for you automatically, hence the window name.

Structure and array variables have a tree control that you can use to display or hide the elements.

To modify the value of a variable in the Autos window

  1. The debugger must be in break mode.
  2. Display the Autos window, if necessary.
  3. In the Value column, double-click the value you want to change

    -or-

    Single-click to select the line, then press the TAB key.

  4. Type the new value, and press ENTER.

    Caution Editing floating-point values can result in minor inaccuracies due to decimal-to-binary conversion of fractional components. Even a seemingly innocuous edit can result in changes to some of the least significant bits in the floating-point variable.


Using the Call Stack Window

To display the Call Stack window

  • From the Debug menu, choose Windows and click Call Stack. (The debugger must be running or in break mode.)

Using the Call Stack window, you can view the function or procedure calls that are currently on the stack. The Call Stack window displays the name of each function and the programming language it is written in. The function or procedure name may be accompanied by optional information, such as module name, line number, byte offset, and parameter names, types, and values. The display of this optional information can be turned on or off:

To change the optional information displayed

  • Right-click the Call Stack window and set or clear Show <the desired information> from the shortcut menu.

    The Call Stack window allows you to run to a specific function or set a breakpoint on the exit point of a function call.


Using the Running Documents Window

The Running Documents window is useful for script debugging. It displays a list of documents that are currently loaded into the program you are debugging. For example, if you add an HTML frameset, the Running Documents window shows you which pages are currently loaded in the browser.

In the Running Documents window you can:

  • Double-click a document to display an editor window for that document.
  • Expand and collapse the list to see the pages or documents within the top-level documents.


Debugging User Interface Reference

The following table shows the windows and dialog boxes you can use for debugging your application.

  • Attach To Process dialog box
  • Locals window
  • Autos window
  • New Breakpoint dialog box
  • Breakpoint Condition dialog box
  • Programs dialog box
  • Breakpoint Hit Count dialog box
  • QuickWatch dialog box
  • Breakpoint Properties dialog box
  • Running Documents window
  • Breakpoints window
  • Watch window
  • Call Stack window


Attach To Process Dialog Box

The Attach to Process dialog box opens when you select a program from the Available Processes box in the Programs dialog box and choose Attach.

Process

The path name for the executable from which the process was created.

Choose Program Types

In this box, select or clear the check boxes next to the program types you want to be able to attach to for debugging.

All

Choose this button to enable attaching to all program types.

None

Choose this button to disable attaching to any program type.

Existing programs that will be debugged

This box shows all program types that are currently running and available for debugging based on the types chosen in Choose Program Types.


Autos Window

To open the Breakpoints window, you must be debugging. From the Debug menu, choose Windows, and then choose Autos.

The Autos window contains the following information:

Name

The names of all variables in the current statement and the previous statement. The current statement is the statement at the current execution location, which is the statement that will be executed next if execution continues. Structure and array variables have a tree control that you can use to show or hide the elements.

Value

The value contained by each variable. By default, integer variables are represented in decimal form. You can change the representation to hexadecimal in the Tools dialog box or by right-clicking the Autos window and choosing the Hexadecimal Display option from the shortcut menu.

Type

The data type of each variable listed in the Name column.


Breakpoint Condition Dialog Box

The Breakpoint Condition dialog box opens when you select the Condition button from a New Breakpoint or Breakpoint Properties dialog box.

Use the Breakpoint Condition dialog box to attach a condition to a breakpoint, or to remove or change a condition previously attached. The condition can be any valid expression accepted by the debugger. The evaluation of this expression determines whether program execution breaks when the breakpoint is hit.

To set or modify a breakpoint condition, use the following controls:

Condition check box

Use this check box to turn the condition on or off. The condition has no effect if this box is cleared.

Condition edit box

Type any valid expression in this box.

Is true

If this button is selected, the debugger evaluates the condition by checking to see if the expression is true. If the expression is true, the condition is satisfied and program execution breaks.

Has changed

If this button is selected, the debugger evaluates the condition by checking to see if the value of the expression has changed since the last time the breakpoint was hit. If the value has changed, the condition is satisfied and program execution breaks.


Breakpoint Hit Count Dialog Box

The Breakpoint Hit Count dialog box opens when you choose the Hit Count button from the New Breakpoint or Breakpoint Properties dialog box.

The Breakpoint Hit Count dialog box enables you to specify a hit count property for a breakpoint. A breakpoint without a hit count causes program execution to break each time the breakpoint is hit. A breakpoint with a hit count property causes execution to break only on the specified number of hits.

To set or modify a hit count property, use the following controls:

When the breakpoint is hit

This setting determines how the breakpoint should behave when it is hit. You can choose to:

  • Break always, regardless of hit count. This is the default option. This option has the least effect on program performance, since the debugger does not actually bother to compare the values.
  • Break when the hit count is equal to the counter.
  • Break when the hit count is a multiple of the counter.
  • Break when the hit count is greater than or equal to the counter.

If you choose any option other than the default, an edit box appears next to the list control. Edit the value in this list box to set the hit count value. For example, you might choose break when hit count is equal to and enter 12. This causes execution to stop the 12th time the breakpoint is hit, not on any other hit.

Current hit count

This value shows the number of times the breakpoint has been hit. The debugger keeps track of this value, if you have chosen a setting other than the break always default for When the breakpoint is hit. You can open the Breakpoint Properties dialog box and choose Hit Count to view the current hit count while your program is executing. If you want to break every time the breakpoint is hit, but you also want to keep track of the hit count in the dialog box, choose break when the hit count is a multiple of 1.

Reset hit count

This button resets the value shown for the Current hit count to 1.


Breakpoint Properties Dialog Box

The Breakpoint Properties dialog box opens when you choose the Breakpoint Properties tool from the Breakpoints window or the Breakpoint Properties command from the shortcut menu. With this dialog box, you can edit the properties that define the breakpoint.

When this dialog box opens, you will see one or more tabs. One tab will be active, depending on the type of breakpoint you are editing. The following table shows the tabs in the Breakpoint Properties dialog box.

To | See
Set properties for a breakpoint on a function at the beginning of the function or at an offset from the beginning | Function, Breakpoint Properties Dialog Box
Set properties for a breakpoint on a source file | File, Breakpoint Properties Dialog Box
Set properties for a breakpoint on a memory location | Address, Breakpoint Properties Dialog Box
Set properties for a breakpoint on a variable | Data, Breakpoint Properties Dialog Box

Below the tabs, you will see the following buttons:

Condition

By default, execution of your program breaks every time the breakpoint is hit. A breakpoint may have a condition that will be tested each time the breakpoint is hit. If the condition is satisfied, your program breaks. Otherwise, execution continues. Choose this button to edit the condition or specify a new condition.

Hit Count

By default, execution of your program breaks every time the breakpoint is hit. A breakpoint can have a specified hit count property. In that case, execution breaks only if the hit count has a specified value. The hit count is the number of times the breakpoint is hit. Choose Hit Count to edit the hit count property or specify a new hit count.


Address, Breakpoint Properties Dialog Box

The following controls allow you to set properties for a breakpoint on a memory location:

Address

This box contains the memory address where the breakpoint is set, in decimal or hexadecimal. By default, hexadecimal numbers must be preceded by 0x, for example, 0x1002A. The address must be an integer constant. However, you do not have to use the 0x prefix for hexadecimal numbers, if you have chosen the Hexadecimal Display option in the Options dialog box on the Tools menu.

Language

This box should show the programming language for that address. If it is not correct, choose the correct language from the drop-down list.


Data, Breakpoint Properties Dialog Box

The following controls allow you to set properties for a breakpoint on a variable. The program will break execution when the value of the specified variable changes.

Variable

Enter the name of the variable. You can use the context operator to specify a variable outside the current scope.

Items

If the variable is an array or dereferenced pointer, this value specifies the number of elements to watch. Execution breaks if the value of any specified element changes.

Language

This box should show the programming language for the variable. If it is not correct, choose the correct language from the drop-down list.


File, Breakpoint Properties Dialog Box

The following controls allow you to set properties for a breakpoint on a source file location:

File

The name, and optional path, of the file in which the breakpoint is set.

Line

The source-code line number, measured from the start of the function, at which the breakpoint is set. If this value is 1, the breakpoint is set at the start of the file.

Character

The character within the source-code line where the function is set. If you think of the line number as a row number, the character number would be a column number. In most cases, you can leave this value set to 1, which sets the breakpoint at the start of the line. Sometimes, however, you may have more than one statement on a line. In that case, you can use the Character value to set the breakpoint on a specific statement within the line.


Function, Breakpoint Properties Dialog Box

The following controls allow you to set properties for a breakpoint on a function:

Function

The name of the function on which the breakpoint is set. For a member function, use both the class name and the function name, for example Classy::function.

Line

The source-code line number, measured from the start of the function, at which the breakpoint is set. If this value is 1, the breakpoint is set at the start of the function.

Character

The character within the source-code line where the function is set. If you think of the line number as a row number, the character number would be a column number. In most cases, you can leave this value set to 1, which sets the breakpoint at the start of the line. Sometimes, however, you may have more than one statement on a line. In that case, you can use the Character value to set the breakpoint on a specific statement within the line.

Language

This box should show the programming language that the function is written in. If it is not correct, choose the correct language from the drop-down list.


Breakpoints Window

To open the Breakpoints window, from the Debug menu, choose Windows, and then choose Breakpoints.

The Breakpoints window contains a toolbar and a list of breakpoints currently set in your program. The toolbar contains the following tools:

New (Breakpoint)

Opens a dialog box that gives you complete options for creating a new breakpoint.

Delete

Removes whatever breakpoint is currently selected. You cannot undo this operation.

Go to Source Code

Opens a source window, if necessary, and shows you the location where the breakpoint is set.

Columns

Selects the informational columns that appear in the breakpoint list.

Properties

Opens a dialog box that allows you to edit any breakpoint property.

The list contains three columns of information by default:

Name

A descriptive name for the breakpoint, created by the debugger based on the breakpoint's location or other properties. The Name allows you to distinguish between breakpoints and select the one you are interested in.

A check box appears before the name. You can use this check box to enable or disable the breakpoint.

Condition

An optional property that determines whether your program breaks when the breakpoint is reached. The condition can be any valid expression recognized by the debugger. The debugger evaluates the condition and breaks execution only if the condition is satisfied.

Hit Count

Another optional property that determines whether your program breaks when the breakpoint is reached. If this property is not set, the debugger stops each time the breakpoint is hit, assuming that the expression shown in Condition column is satisfied. The hit count can notify the debugger to break on the nth time the breakpoint is reached, or on every multiple of N hits, or on the Nth hit and every time thereafter.

The following columns are not shown by default, but you can add them using the Columns tool:

Language

For a breakpoint set on a variable, which is a data breakpoint, the language in which the debugger evaluates the variable.

Function

The name of the function where the breakpoint is set and the location within the function.

File

The name of the file where the breakpoint is set and the location within the function.

Address

The memory address where the breakpoint is set.

Data

For a breakpoint set on a variable, which is a data breakpoint, the name of the variable.

Program

The name of the program in which the breakpoint is set.


Call Stack Window

To open the Call Stack window, you must be debugging. From the Debug menu, choose Windows and choose Call Stack.

The Call Stack window enables you to view the names of functions on the call stack, parameter types, and parameter values. Call stack information is shown only when the program being debugged is in a break state.

Name column

Shows the name of each function name on the call stack. To allow you to distinguish between various calls to the same function, each name is decorated with the following optional information:

  • module name
  • parameter name
  • parameter type
  • parameter value
  • line number
  • byte offset

Language column

Shows the language from which the call to the function is made.


Debugger Properties On <Machine> Dialog Box

The Debugger Properties On <Machine> dialog box opens when you choose Properties in the Programs dialog box.

Program Types

The types of programs that can be debugged.

Enable Attach

Set to enable the environment to attach to the selected program type for debugging. Clear to disable attaching to the selected program type.


General, Debugging, Options Dialog Box

The General pane of the Options dialog box allows you to set general debugging options.

Hexadecimal display

Select this option to display integers in hexadecimal format rather than binary.

Allow hexadecimal input without prefix

Select this option if you want the debugger information windows to accept input as hexadecimal as default (without the 0x prefix).

Warn if no symbols on launch

Select this option to display a dialog box warning you when you try to debug a program for which the debugger has no symbolic information.

Confirm correct file was found when finding source

Select this option to display a dialog box asking you to confirm that the debugger found the correct source file.

In break mode, only stop execution of the current program

Allows other attached programs to continue running when you break the current program.

Color text of current statement and breakpoints

Uses color to call out the current statement and statements where breakpoints are set.

Use CodeSense to verify breakpoints

Uses CodeSense to verify that breakpoints are valid.

Insert breakpoints in Active Server Pages for breakpoints in client script

When a breakpoint is set in a client script, inserts a corresponding breakpoint in the associated Active Server Page.

Just-In-Time Debugging/Attach On This Machine

Select to choose the types of applications (Win32 or COM+, for example) that can be attached for debugging (including just-in-time debugging).


Locals Window

To open the Locals window, you must be debugging. From the Debug menu, choose Windows, and then choose Locals.

The Locals window contains three columns of information:

Name

This column contains the names of all local variables in the current scope. Structure and array variables have a tree control that you can use to display or hide the elements.

Value

This column shows the value contained by each variable. By default, integer variables are represented in decimal form. You can change the representation to hexadecimal in the Tools dialog box or by right-clicking the Locals window and choosing the Hexadecimal Display option from the shortcut menu.

Type

This column identifies the data type of each variable listed in the Name column.


New Breakpoint Dialog Box

The New Breakpoint dialog box opens when you choose the New Breakpoint command from the Debug menu or the New Breakpoint tool from the Breakpoints window. With this dialog box, you can create a new breakpoint of any type, such as function, file, address, or data.

This dialog box contains four tabs, each of which contains controls for setting a specific type of breakpoint. The following table shows the tabs in the New Breakpoint dialog box.

To | See
Set a breakpoint on a function at the beginning of the function or at an offset from the beginning | Function, New Breakpoint Dialog Box
Set a breakpoint at a specific location within a specified file | File, New Breakpoint Dialog Box
Set a breakpoint at a specific memory location | Address, New Breakpoint Dialog Box
Set a breakpoint on a variable | Data, New Breakpoint Dialog Box

Below the tabs, you will see the following buttons:

Condition

By default, execution of your program breaks every time the breakpoint is hit. If you choose this button, you can specify a condition that will be tested each time the breakpoint is hit. If the condition is satisfied, your program breaks. Otherwise, execution continues.

Hit Count

By default, execution of your program breaks every time the breakpoint is hit. Choose this button if you want execution to break on a specified hit count instead.


Address, New Breakpoint Dialog Box

The following controls allow you to set properties for a breakpoint on a memory location:

Address

This box contains the memory address where the breakpoint is set, in decimal or hexadecimal. By default, hexadecimal numbers must be preceded by 0x, for example, 0x1002A. The address must be an integer constant. You do not need to use the 0x prefix for hexadecimal numbers, however, if you have chosen the Hexadecimal Display option in the Options dialog box found on the Tools menu.

Language

This box should show the programming language for that address. If it is not correct, choose the correct language from the drop-down list.


Data, New Breakpoint Dialog Box

The following controls allow you to set properties for a breakpoint on a variable. The program will break execution when the value of the specified variable changes.

Variable

Enter the name of the variable. You can use the context operator to specify a variable outside the current scope.

Items

If the variable is an array or dereferenced pointer, this value specifies the number of elements to watch. Execution breaks if the value of any specified element changes.

Language

This box should show the programming language for the variable. If it is not correct, choose the correct language from the drop-down list.


File, New Breakpoint Dialog Box

The following controls allow you to set properties for a breakpoint on a source file location:

File

The name and optional path of the file in which the breakpoint is set.

Line

The source-code line number, measured from the start of the function, at which the breakpoint is set. If this value is 1, the breakpoint is set at the start of the file.

Character

The character within the source-code line where the function is set. If you think of the line number as a row number, the character number would be a column number. In most cases, you can leave this value set to 1, which sets the breakpoint at the start of the line. Sometimes, however, you may have more than one statement on a line. In that case, you can use the Character value to set the breakpoint on a specific statement within the line.


Function, New Breakpoint Dialog Box

The following controls allow you to set properties for a breakpoint on a function:

Function

The name of the function on which the breakpoint is set. For a member function, use both the class name and the function name, for example Classy::function.

Line

The source-code line number, measured from the start of the function, at which the breakpoint is set. If this value is 1, the breakpoint is set at the start of the function.

Character

The character within the source-code line where the function is set. If you think of the line number as a row number, the character number would be a column number. In most cases, you can leave this value set to 1, which sets the breakpoint at the start of the line. Sometimes, however, you may have more than one statement on a line. In that case, you can use the Character value to set the breakpoint on a specific statement within the line.

Language

This box should show the programming language that the function is written in. If it is not correct, choose the correct language from the drop-down list.


Processes Dialog Box

The Programs dialog box opens when you select Programs from the Debug menu.

The Programs dialog box enables you to view and manipulate programs. Using this dialog box, you can debug multiple programs at the same time.

Properties

Allows you to enable or disable attaching to script.

Available Processes

This group displays information on all programs available for debugging.

Process

The program or process name, which is usually an .exe file.

Id

The process identification number assigned by the operating system.

Title

The title in the program's title bar, if any. This title also appears in the taskbar.

Type

The type of program, such as Win32 or COM+.

Debugger

If the program is currently being debugged, this identifies the debugger and the machine the debugger is running on, for example, debugger on BensMachine.

Attach

Choose to debug the program selected in Available Processes. This brings up the Attach to Process dialog box.

Refresh

Because programs can start and stop in real time while the Programs dialog box is open, the Available Processes list may not be up to date. Choose this button to refresh the list.

Debugged Processes

This group displays information on all processes currently attached for debugging.

Machine

For a debugged process, this identifies the machine the process is running on.

Port

For a debugged process, this identifies the port through which the machine is attached.

Break

Choose to break execution of the program selected in Debugged Processes.

Detach

Choose to stop debugging, or detach from, the program selected in Debugged Processes.

Terminate

Choose to terminate the program selected in Debugged Processes.

When debugging is stopped

For the program selected in Debugged Processes, this setting determines whether the program terminates or merely detaches from the debugger and continues to run when you stop debugging.


QuickWatch Dialog Box

The QuickWatch dialog box opens when you choose QuickWatch from the Debug menu. The debugger must be in a break state.

The QuickWatch dialog box enables you to view variables. You can also view Script expressions.

In addition, you can use the QuickWatch dialog box to change the value of any variable.

The Current Value box displays the value and type for variables and expressions you have specified. You can add a variable or expression to this box by typing it in the Expression box.

Expression

In this box, you can type a variable name or any valid expression recognized by the debugger. The drop-down list contains previously entered expressions that you can select to save the trouble of retyping.

Recalculate

Click this button to evaluate the variable or expression in the Expression box and display the results in Current value.

Add Watch

Click this button to add the contents of the Expression box to the Watch window.

Current value

When you choose Recalculate, this box displays the expression from the Expression box in the Name column, the value of the expression in the Value column, and the data type of the value in the Type column.


Running Documents Window

To open the Running Documents window, you must be debugging. From the Debug menu, choose Windows and choose Running Documents.

The Running Documents window is useful for script debugging. It displays a list of documents that are currently loaded into the process you are running.

Documents List

A hierarchical list of documents and their paths.


Watch Window

To open the Watch window, the debugger must be running or in a break state. From the Debug menu, choose Windows and choose Watch.

Name

In this column you can type any valid expression recognized by the debugger.

Value

The debugger evaluates the expression and places the result in this column. If the expression is a variable name, you can edit the value in this column to change the contents of the variable. You cannot edit const variables.

Type

This column displays the data type of the variable or expression.


Using the Threads Window

To display the Threads window

  • From the Debug menu, choose Windows and click Threads. (The debugger must be running or in break mode.)

With the Threads window, you can examine and control threads in the program you are debugging. A thread is a sequence of executable instructions created by a program. By default, a program has a single thread. Multithreaded programs create additional threads. One thread is active at a time. The active is the thread that is currently able to run.

From the Threads window, you can set the active thread. In addition, you can freeze or thaw the execution of each individual thread. Freezing prevents the execution of a thread. Thawing allows it to continue. "Frozen" and "thawed" are states set by the debugger.

To set an active thread

  • In the Threads window, right-click a thread and choose Switch to Thread from the context menu.

    -or-

  • On the Debug Location toolbar, select the Program list box and choose the program you want to make current.

To freeze (prevent execution of) a thread

  • In the Threads window, right-click a thread and choose Freeze from the shortcut menu.

To thaw (allow execution of) a thread

  • In the Threads window, right-click a thread and choose Thaw from the shortcut menu.

You can suspend or resume thread execution using calls to SuspendThread and ResumeThread. In MFC, you can use CWinThread::SuspendThread and CWinThread::ResumeThread.

These calls change the Suspend Count shown in the Threads window. To execute, a thread must be unfrozen and have a Suspend Count of zero. You cannot change the Suspend Count or resume a suspended thread from the Threads window.

Tips for Debugging Threads

  • You can set the thread name in an unmanaged C/C++ program using the SetThreadName API. For an example , see Setting a Thread Name.
  • When debugging native Win32 code, you can view the contents of the Thread Information Block by entering the pseudoregister @TIB in the Watch window or QuickWatch dialog. For information on Thread Information Blocks, see "Under the Hood" in the May 1996 edition of the Microsoft Systems Journal.
  • When debugging native Win32 code, you can view the last error code for the current thread (the value returned by a call to GetLastError) by entering the pseudoregister @Err in the Watch window or QuickWatch dialog.
  • For an example showing how to use CRT functions for debugging a multithreaded application, see the code in the CRT topic _malloc_dbg.


Using the Disassembly Window

To display the Disassembly window

  • From the Debug menu, choose Windows and click Disassembly. (The debugger must be running or in break mode.)

The Disassembly window shows assembly code corresponding to the instructions created by the compiler. In addition, it can show the following optional information:

  • Memory address where each instruction is located. (For native applications, this is the actual memory address. For Visual Basic, C#, or managed code, it is an offset from the beginning of the function.)
  • Source code from which the assembly code derives
  • Code bytes (byte representations of the actual machine or IL instructions)
  • Symbols names for the memory addresses
  • Line numbers corresponding to the source code

To turn optional information on or off

  • Right-click the Disassembly window and set or clear the desired options in the shortcut menu.

A yellow arrow in the left margin shows the location of the current execution point. For native code, this corresponds to the CPU's program counter. This location shows the next instruction that will be executed in your program.

Navigating the Memory Space

To page up or down in the memory space

  • Click the vertical scrollbar, above or below the thumb.

In native code applications, you can't scroll by dragging the thumb up or down, as you can with ordinary scrollbars. Due to the huge size of the memory space on modern computers, scrolling would likely cause you to overshoot any area of memory you were looking for. So, the thumb acts as if it were spring-loaded and always remains in the center of the scrollbar.

In managed applications, disassembly is limited to one function and you can scroll normally.

Notice that higher memory addresses appear at the bottom of the window, so if you want to view a higher address, you must page down.

To move up or down one instruction

  • Click the arrow at the top or bottom of the vertical scrollbar.


Topic Not Found

The link you just clicked was not able to connect to the target page. Some possible reasons and remedies are as follows:

Reason | Remedy
The URL of the destination topic is incorrect or has changed. | Use the index or the search function instead.
Problems with the Help installation. | Uninstall Help and then rerun Setup.


Attribute Limitations

Edit and Continue does not regenerate IDL files; therefore, changes to IDL attributes will not be reflected while you are debugging. To see the result of changes to IDL attributes, you must stop debugging and rebuild your application. Edit and Continue does not generate an error or warning if IDL attributes have changed.


Using Run-Time Checks Without the C Run-Time Library

If you link your program without the C run-time library (using /NODEFAULTLIB) and want to use run-time error checks, you must link with RunTmChk.lib.

_RTC_InitBase initializes your program for run-time error checks. If you do not link with the C run-time library, you must check to see whether your program is compiled with run-time error checks before calling _RTC_InitBase:

#ifdef __MSVC_RUNTIME_CHECKS
   _RTC_InitBase();
#endif

If you do not link with the C run-time library, you must also define a function called _CRT_RTC_INIT. _CRT_RTC_INIT installs your user-defined function as the default error reporting function:

// C version
_RTC_error_fn __cdecl _CRT_RTC_INIT(void *res0, void **res1, int res2, int res3, int res4);
{
   return &MyErrorFunc; // set the error handler
}

// C++ version
extern "C" _RTC_error_fn __cdecl _CRT_RTC_INIT(void *res0, void **res1, int res2, int res3, int res4);
{
   return &MyErrorFunc; // set the error handler

}

After you have installed the default error reporting function, you can install additional error reporting functions with _RTC_SetErrorFunc.


Displaying Elements of a Custom Data Type

Native Only When you are using interface elements such as the Watch window, the Visual Studio debugger automatically expands common data types to show their most important elements. If you have your own custom data types that you want the debugger to autoexpand, you can add rules to the file autoexp.dat, which is located in the \bin directory. Instructions on how to write autoexp rules are located in the file itself. The structure of this file and the syntax of autoexp rules may change from one release of Visual Studio to the next.

See Also

Inspecting Your Program


Customizing CRT Error Checking

The C run-time library provides run-time error checking when you compile with /RTC (run-time checks) or use the run-time_checks pragma. In some cases, you may want to customize CRT run-time error checking:

  • To route run-time error messages to a file or destination other than the default.
  • To specify an output destination for run-time error messages under a third-party debugger.
  • To report run-time error messages from a program compiled with a release version of the C run-time library. (Release versions of the library do not use _CrtDbgReport to report run-time errors. Instead, they display an Assert dialog box for each run-time error.)

To customize run-time error checking, you can:

  • Write Your Own Function to Report Run-Time Errors
  • Customize the Error Message Destination
  • Query for Information about Run-Time Check Errors

Writing a Run-Time Error Reporting Function

A custom reporting function for run-time errors must have same declaration as _CrtDbgReport. It should return value of 1 to the debugger.

The following example shows how to define a custom reporting function:

int errorhandler = 0;
void configureMyErrorFunc(int i)
{
   errorhandler = i;
}

int MyErrorFunc(int errorType, const char *filename, int linenumber, const char *moduleName, const char *format, ...)
{
   switch (errorhandler)
   {
   case 0:
   case 1:
      printf("Error type %d at %s line %d in %s",errorType. filename, linenumber, moduleName);
   case 2:
   case 3:
      fprintf(stderr, "Error type);
   }
}

The following example shows a more complex custom reporting function. In this example, the switch statement handles various error types, as defined by the reportType parameter of _CrtDbgReport. Since you are replacing _CrtDbgReport, you cannot use _CrtSetReportMode. Your function must handle the output. The first variable argument in this function takes a run-time error number.

#include <windows.h>
#include <stdarg.h>
#pragma runtime_checks("", off)
int Catch_RTC_Failure(int errType, const char *file, int line, const char *module, const char *format, ...)
{
   // Prevent re-entrancy
   static long running = 0;
   while (InterlockedExchange(&running, 1))
      Sleep(0);
   // Now, disable all RTC failures
   int numErrors = _RTC_GetNumErrors();
   int *errors=_alloca(numErrors);
   for (int i = 0; i < numErrors; i++)
   errors[i] = _RTC_SetErrorType(i, _RTC_ERRTYPE_IGNORE);

   // First, let's get the rtc error number from the var-arg list...
   va_list vl;
   va_start(vl, format);
   _RTC_ErrorNumber rtc_errnum = va_arg(vl, _RTC_ErrorNumber);
   va_end(vl);

   char buf[512];
   const char *err = _RTC_GetErrDesc(rtc_errnum);
   sprintf(buf, "%s\nLine #%d\nFile:%s\nModule:%s",
      err,
      line,
      file ? file : "Unknown",
      module ? module : "Unknown");
   int res = (MessageBox(NULL, buf, "RTC Failed...", MB_YESNO) == IDYES) ? 1 : 0;
   // Now, restore the RTC errortypes
   for(i = 0; i < numErrors; i++)
      _RTC_SetErrorType(i, errors[i]);
   running = 0;
   return res;
}
#pragma runtime_checks("", restore)

Use _RTC_SetErrorFunc to install your custom function in place of _CrtDbgReport. The _RTC_SetErrorFunc return value is the previous reporting function, which you can save and restore if necessary:

int main()
{
   _RTC_error_fn oldfunction, newfunc;
   oldfunction = _RTC_SetErrorFunc(&MyErrorFunc);
   // run some code...
   newfunc = _RTC_SetErrorFunc(oldfunction);
   // newfunc == &MyErrorFunc;
   // run some more code...
}

Customizing the Error Message Destination

If you use _CrtDbgReport to report errors, you can use _CrtSetReportMode to specify the destination of error messages.

If you use a custom reporting function, use _RTC_SetErrorType to associate an error with a report type.

Querying for Information about Run-Time Error Checks

_RTC_NumErrors returns the number of error types detect by run-time error checks. To get a brief description of each error, you can loop from 0 to (_RTC_NumErrors –1) return value, passing the iteration value to _RTC_GetErrDesc on each loop.


Limitations of Edit and Continue

Edit and Continue places a limit of 64 bytes on the total size of the new variables you can add to an active function. (An active function is any function on the call stack — the current function or one of its callers.) If you exceed this limit, the code changes will be applied the next time the function is called. There is no new-variable limit for functions not currently on the call stack.

Edit and Continue does not handle some types of code changes. The following changes cannot be applied during the debugging session:

  • Changes to resource files
  • Changes to code in read-only files
  • Changes to optimized code (code compiled with /O1, /O2, /Og, /Ox, /Ob1, or /Ob2)
  • Changes to exception-handling blocks
  • Changes to data types, including class, structure, union, or enumeration definitions
  • Removal of functions
  • Most changes to global or static code
  • Changes to executables that are copied from another machine and not built locally

If you make one of these changes and then try to apply code changes or use an execution command, an error message appears in the Output window. Changes to data type definitions and changes to function prototypes produce a compiler error message (C1092).

In some cases, Edit and Continue cannot apply code changes to the executable immediately, but may be able to apply the code changes later if you continue debugging. This occurs if you edit a function that calls the current function or if you add more than 64 bytes of new variables to a function on the call stack. When this happens, the original code continues to execute until the function exits and is called again. Edit and Continue updates the call at that time. Until the call exits, the source window shows the original code in gray. Because this code has been superceded by code changes, it is outdated or stale. You cannot edit stale code. The debugger warns you about stale code, by default. You can turn the warning off, if you prefer.

To enable/disable the stale code warning

  1. From the Tools Menu, click Options.
  2. In the Options dialog box, select the Debugging folder.
  3. In the Edit and Continue group, select or clear the Warn me about stale code check box.
  4. Click OK.

    Tip You can change the color that source windows use to display stale code.

To change the color of stale code

  1. From the Tools menu, choose Options.
  2. In the Options dialog box, open the Environments folder and choose Fonts and Colors.
  3. In the Show settings for box, choose Text Editor.
  4. In the Display items box, choose Stale Code.
  5. In the Item foreground box, choose any color.
  6. Click OK.


Limitations on Automatic Relinking

By default, Edit and Continue relinks your program at the end of a debugging session to create an up-to-date executable.

Edit and Continue cannot relink your program if you are debugging it from a location other than the original build location. A message tells you that you need to rebuild manually.

Edit and Continue does not rebuild static libraries. If you make changes to a static library using Edit and Continue, you need to manually rebuild the library and relink applications using it.

Edit and Continue does not invoke custom build steps. If your program uses custom build steps, you may want to rebuild manually so that custom build steps can be invoked. In that case, you can disable relinking after Edit and Continue to ensure that you are prompted to manually rebuild.

To disable relinking after Edit and Continue

  1. From the Tools menu, click Options.
  2. In the Options dialog box, select the Debugging folder and the Edit and Continue group.
  3. Clear the Relink after debugging check box.
  4. Click OK.

In addition, certain linker options disable Edit and Continue.


Linker Options that Disable Edit and Continue

The following linker options disable Edit and Continue.

  • Setting /OPT:REF, /OPT:ICF, or /INCREMENTAL:NO disables Edit and Continue with the following warning:
    LINK : warning LNK4075: ignoring /EDITANDCONTINUE due to /OPT specification
  • Setting /PROFILE, /ORDER, /RELEASE, /FORCE, or /DEBUGTYPE:COFF disables Edit and Continue with this warning:
    LINK : warning LNK4075: ignoring /INCREMENTAL due to /option specification
  • Setting any option that prevents the creation of a program database (.PDB) file disables Edit and Continue with no specific warning.


Linking Limitations

Edit and Continue has two types of linker limitations:

  • By default, Edit and Continue relinks your program at the end of a debugging session to create an up-to-date executable. There are some Limitations on Automatic Relinking.
  • Some linker options disable Edit and Continue.


Precompiled Header Limitations

By default, Edit and Continue loads and processes precompiled headers in the background to speed up processing of code changes. Loading precompiled headers requires allocation of physical memory, which can be a problem if you are compiling on a machine with limited RAM. Under Windows NT or Windows 2000, you can determine if this might be a problem by using the Windows NT Task Manager to determine the amount of available physical memory while you are debugging. If this amount is greater than the size of your precompiled headers, Edit and Continue should have no problem. If the amount is less than the size of your precompiled headers, you can prevent Edit and Continue from loading precompiled headers in the background.

To disable background loading of precompiled headers for Edit and Continue

  1. From the Tools menu, click Options.
  2. In the Options dialog box, select the Debugging folder and the Edit and Continue group.
  3. Clear the Allow Precompiling check box.
  4. Click OK.


Stepping Into a Specific Function

When you are stepping into a nested function call, you can use Step Into Specific Function, located on the shortcut menu, to choose which function you want to step into. For example, on a call to Func1(Func2), you could choose to step into Func1 or Func2. This command works for any number of nesting levels.

You cannot use Step Into Specific Function with C++ virtual functions.

To step into a specific function

  1. Advance the execution point to the function call you want to step into. (You might use a breakpoint, Step Into, Step Over, or Run To Cursor.)
  2. Right-click the source window to open the shortcut menu.
  3. From the shortcut menu, click Step Into Specific Function and choose the function you want from the submenu.

    The debugger executes the function call and breaks at the beginning of the selected function.

    The Step Into Specific Function command appears on the shortcut menu only if the execution point is located immediately before to a nested function.


Edit and Continue

Edit and Continue enables you to change your source code and apply those changes (with some limitations) while your program is running under the Visual Studio debugger (or in break mode). Not only does this save time, it also gives you the chance to see the effect of changes during the current conditions under which your program is running. When you install Visual Studio, Edit and Continue is turned on by default. You can turn it off if you prefer.

To enable/disable Edit and Continue

  1. From the Tools Menu, click Options.
  2. In the Options dialog box, select the Debugging folder.
  3. In the Edit and Continue group, select or clear the Enable Edit and Continue check box.
  4. Click OK.

When you edit code during you are debugging, Edit and Continue can apply the changes:

  • Explicitly, when you select Apply Code Changes from the Debug menu

    -or-

  • Automatically, when you select a Go or Step command.

When you apply code changes explicitly, Edit and Continue updates the compiled code you are debugging, but does not step or resume execution.

If you prefer, you can disable the automatic invocation of Edit and Continue by Go and Step commands. You might do this if you are making edits to the code that you do not want applied during the current debugging session.

To enable/disable automatic invocation of Edit and Continue

  1. From the Tools Menu, click Options.
  2. In the Options dialog box, select the Debugging folder.
  3. In the Edit and Continue group, select or clear the Invoked by debug commands check box.

    Note You also have the option of having the debugger ask you before applying code changes prior to a debug command. If you want to be asked, select the Ask me first check box.

  4. Click OK.

Because Invoked by debug commands is a tools option, altering this setting affects all projects you work on. You do not need to rebuild your application after changing this setting. You can change the setting even while debugging. If you build your application from the command line or from a makefile but debug in the Visual C++ environment, you can still use Edit and Continue if you set the /ZI option.

Caution Do not enable Edit and Continue (/ZI) if you are debugging optimized code. Edit and Continue is incompatible with compiler optimizations. The result is a compiler error.

Some code changes cause the point of execution to move to a new location when Edit and Continue applies the changes. Edit and Continue places the point of execution as accurately as possible, but the results may not be correct in all cases. A dialog box informs you when the point of execution changes. You should verify that the location is correct before you continue debugging. If it is not correct, use the Set Next Statement, as described in Setting the Execution Point.


Using the Memory Window

Note This feature is not available for languages such as script and SQL that do not support the concept of memory.

You can use a Memory window to view large buffers, strings, and other data that do not display well in the Watch or Variables window. In the Visual Studio debugger, you can open up to four Memory windows.

To display a Memory window

  • From the Debug menu, choose Windows, then Memory, and click Memory 1, Memory 2, Memory 3, or Memory 4. You can open these memory windows in any order; it doesn't matter. (The debugger must be running or in break mode.)

When viewing memory contents in a Memory window, you can use the vertical scrollbar to move up or down in the memory space. You will notice that the higher addresses appear at the bottom of the window. To view a higher address, you must move down, not up.

To page up or down in memory

  • To page down (move to a higher memory address), click the vertical scrollbar below the thumb.
  • To page up (move to a lower memory address), click the vertical scrollbar above the thumb.

You will also notice that the vertical scrollbar operates in a nonstandard fashion. The address space of a modern PC is huge, and it would be easy to get lost by grabbing the scrollbar thumb and dragging it to a random location. For this reason, the thumb is "springloaded" and always remains in the center of the scrollbar. You can page up or down, but cannot scroll about freely.

If you want to move instantly to a selected location in memory, you can do so by using drag and drop or editing the value in the Address box.

The Address box accepts expressions as well as numeric values. By default, the Memory window treats an Address expression as a live expression, which is reevaluated as your program executes. Live expressions can be quite handy. For example, you can use them to look at the memory that is touched by a pointer.

In native code applications, you can also use register names as live expressions. You can use the stack pointer to follow the stack, for example.

If you do not want the contents of the Memory window to change as your program executes, you can turn off live expression evaluation.

You can customize the way the Memory window shows memory contents. By default, memory contents appear as long data types in hexadecimal format, and the number of columns is determined automatically by the current width of the window.

You can hide or display the toolbar at the top of the Memory window. (You will not have access to Address box or other tools while the toolbar is hidden.)


Using the Registers Window

To display the Registers window

  • From the Debug menu, choose Windows and click Registers. (The debugger must be running or in break mode.)

    Note Register information is available for native-code applications only.

The Registers window displays register contents. If you keep the Registers window open as you step through your program, you can see register values change as your code executes. Values that have changed recently appear in red.

To reduce clutter, the Registers window organizes registers into groups. You can display or hide groups as you see fit. The Registers window displays SSE, SSE2, and 3DNow! registers in the following way:

3DNow! Registers

The debugger splits each MMX register into two 32-bit floats of the form MMnm, where n is the MMX register number, and m is zero or one for each half. 3DNow! registers are available on the AMD (Athlon) K6 and K7 processors.

SSE Registers

The debugger splits each XMM register into four 32-bit floats of the form XMMnm, where n is the XMM register number and m is 0-3 to denote which part of the register is used. These registers are available on Katmia (Pentium III) and WNI processors.

SSE2 Instructions Registers

The debugger splits each XMM register into two halves, both as integer and floating point. The notation is XMM followed by the register number, then D (for double, then L (low half) or H (high half). SSE2 integer registers (I registers) do not appear in the Registers window. To view I registers, enter the register name in the Watch window. These registers are available on WNI processors.

You can edit the value of a register in the Registers window. If you choose to display the register flags group, you can edit register flags. For Intel x86 processors, you can set the following register flags:

Register Window Flags

Flag | Set Value
Overflow | O = 1
Direction | D = 1
Interrupt | I = 1
Sign | S = 1
Zero | Z = 1
Auxiliary carry | A = 1
Parity | P = 1
Carry | C = 1


Breakpoint Operations in the Call Stack Window

(Feature not available for T-SQL)

In the Call Stack Window, you can set a breakpoint on a specific function call on the stack. The breakpoint is set at the end of the function call. When the selected call ends, the breakpoint will be hit.

To set a breakpoint on a function call

  • In the Call Stack window, right-click the function call and choose Insert Breakpoint from the shortcut menu. (The debugger must be in break mode.)

    A breakpoint symbol appears in the left margin next to the function call name. The symbol is a solid red dot.

When you view the breakpoint properties, this breakpoint appears as an address breakpoint with a memory location corresponding to the end point of the function.

In addition, you perform these other breakpoint operations in the Call window:

  • Delete a breakpoint
  • Enable or disable a breakpoint
  • Edit a breakpoint


Breakpoint Operations in the Disassembly Window

In the Disassembly Window, you can view, set, enable, disable, delete, or edit a file, function, or address breakpoint. You can insert a data breakpoint, but data breakpoints do not appear in the Disassembly window. Once you have created a data breakpoint, you cannot view, set, enable, disable, delete, or edit it from the Disassembly window. If you need to perform one of those operations on a data breakpoint, use the Breakpoints window.

The following list shows the breakpoint operations you can perform from this window:

  • Insert a file breakpoint
  • Insert a function breakpoint
  • Insert an address breakpoint
  • Insert a data breakpoint
  • Delete a breakpoint
  • Enable or disable a breakpoint
  • Edit a breakpoint


Choosing the Startup Project

The startup project is the project in a Visual Studio solution that starts when you choose an execution command such as Start from the Debug menu.

To choose a startup project

  • In the Solution Explorer window, right-click a project name and choose Set as StartUp Project from the shortcut menu.


Customizing the Memory Window Display

To change the format of the memory contents

  1. Right-click the Memory window.
  2. From the shortcut menu, choose the format you want.

To change the number of columns in the Memory window

  1. In the toolbar at the top of the Memory window, locate the Columns list.
  2. From the Columns list, choose the number of columns you want to display or choose Auto for automatic adjustment to fit the width of the window.


Deleting a Breakpoint in the Disassembly Window

In the Disassembly window, you can view file, function, or address breakpoints as symbols in the left margin. You can delete these breakpoints using the procedure given below. You cannot view data breakpoints in the Disassembly window, so you cannot delete a data breakpoint from the Disassembly window. To delete a data breakpoint, use the Breakpoints window.

To delete a file, function, or address breakpoint

  1. Right-click the line containing the breakpoint symbol (A solid dot or empty circle, depending on the breakpoint state).
  2. From the shortcut menu, choose Remove Breakpoint.


Detaching Programs

To detach a program that you have attached to for debugging, you must be running the Visual Studio Debugger Proxy (dbgproxy) service. You cannot run dbgproxy in a Terminal Server session, so if you run Visual Studio in a Terminal Server window, you will not be able to detach programs.

To install dbgproxy

  1. Locate dbgproxy.exe. In your Visual Studio directory, find the subdirectory \Common7\Packages\Debugger. You should find dbgproxy.exe there.
  2. From the Windows command prompt, install dbgproxy.exe using the following syntax:
    dbgproxy.exe -install

To run dbgproxy

  1. From the Start menu, click Settings and choose Control Panel.
  2. In the Control Panel window, double-click the Administrative Tools icon.
  3. In the Administrative Tools window, double-click Services.
  4. In the Services dialog box, right-click Visual Studio Debugger Proxy and choose start from the shortcut menu.

If you attach to a program on a remote machine, you must be running the dbgproxy service on the remote machine.

To detach from a program

  1. In the Processes dialog box, locate the process you want to attach to in the Debugged Programs list.
  2. Click the Detach button.

To detach from all programs simultaneously

  • From the Debug menu, choose Detach All.

If you detach all processes, the debugger session ends automatically.

Caution Detaching from a program does not terminate the program. The program continues running on its host machine even though it is no longer attached to the debugger. To make sure the active program terminates, use the Stop Debugging command from the Debug menu. Be careful about stopping system processes, however, which can have sudden, adverse results, including system crashes.


Displaying/Hiding Register Groups

To display or hide register groups

  1. Right-click the Registers window.
  2. From the shortcut menu, select the register groups you want to show or hide.

    Register groups not supported by the hardware you are debugging are disabled on the shortcut menu and cannot be selected.


Editing a Breakpoint in the Disassembly Window

In the Disassembly window, you can view file, function, or address breakpoints as symbols in the left margin. You can edit the properties of these breakpoints using the procedure given below. You cannot view data breakpoints in the Disassembly window, so you cannot edit their properties from the Disassembly window. To edit a data breakpoint, use the Breakpoints window.

To edit a file, function, or address breakpoint

  1. Right-click the line containing the breakpoint symbol (A solid dot or empty circle, depending on the breakpoint state).
  2. From the shortcut menu, choose Breakpoint Properties.

    The Breakpoint Properties dialog box appears.

  3. In the Breakpoint Properties dialog box, edit the breakpoint properties you want to change.
  4. Click OK.


Editing a Register Value

To change the value of a register

  1. In the Registers window, use the TAB key or the mouse to move the insertion point to the value you want to change. When you start to type, the cursor must be located in front of the value you want to overwrite.
  2. Type the new value.
  3. Press ENTER.

    Caution Changing register values (especially in the EIP and EBP registers) can affect program execution.

    Caution Editing floating-point values can result in minor inaccuracies due to decimal-to-binary conversion of fractional components. Even a seemingly innocuous edit can result in changes to some of the least significant bits in a floating-point register.


Enabling/Disabling a Breakpoint in the Disassembly Window

In the Disassembly window, you can view file, function, or address breakpoints as symbols in the left margin. You can enable or disable these breakpoints using the procedures given below. You cannot view data breakpoints in the Disassembly window, so you cannot enable or disable data breakpoints from the Disassembly window. To enable or disable a data breakpoint, use the Breakpoints window.

When you set a breakpoint, it is enabled by default. The breakpoint remains enabled until you disable it.

To disable a file, function, or address breakpoint

  1. Right-click the line containing an enabled breakpoint symbol (A solid dot).
  2. From the shortcut menu, choose Disable Breakpoint.

    The breakpoint symbol becomes an empty circle.

Once you have disabled a breakpoint, you can reenable it by similar procedure:

To enable a file, function, or address breakpoint

  1. Right-click the line containing an enabled breakpoint symbol (An empty circle).
  2. From the shortcut menu, choose Enable Breakpoint.
  3. The breakpoint symbol becomes a solid dot.


Following a Pointer Through Memory

To follow a pointer through memory

  1. In the Memory window Address box, type a pointer expression. The pointer variable must be within the current scope. Depending on the language, you may need to dereference it.
  2. Press ENTER.

    Now, when you use an execution command, such as Step, the memory address displayed will automatically change as the pointer changes.


Inserting an Address Breakpoint in the Disassembly Window

To insert an address breakpoint in the Disassembly window

  1. In the disassembly code, right-click the line where you want to set the address breakpoint.
  2. From the shortcut menu, choose Insert Breakpoint.


Installing the Remote Debug Monitor

For remote debugging, you must install the Remote Debug Monitor on the remote machine. The Remote Debug Monitor is a small program that communicates with the debugger host and controls the execution of the program you are debugging.

To install the Remote Debug Monitor

  • Run the Visual Studio Setup CD-ROM on the remote machine and choose the appropriate options in the setup wizard.

The Remote Debug Monitor installs the following files during setup.

File | Windows 95 | Windows 98 | Windows NT 4 | Windows 2000
msvcmon.exe | X | X | X | X
natdbgdm.dll | X | X | X | X
natdbgtlnet.dll | X | X | X | X
msvcr70.dll | X | X | X | X
msdis130.dll | X | X | X | X
msvc70.dll | X | X | X | X
psapi.dll |  |  | X |
msdbg2.dll | X | X | X | X
mdm.dll | X | X | X | X
cpde.dll | X | X | X | X
pdm.dll | X | X | X | X
metade.dll | X | X | X | X
shmetapdb.dll | X | X | X | X
msvb7.dll | X | X | X | X
Dbghelp.dll | X | X | X |
C++/C# EE (filename TBD) | X | X | X | X
PDB symbol handler (filename TBD) | X | X | X | X

The Remote Debug Monitor runs as a console application that you can launch from the Start menu.

Note The following message might appear when you try debugging a remote machine:

The VC++ Debug Monitor is not correctly installed and running on machine "remotemachine".

This message means that the debugger did not find the debug monitor running on the remote machine. Start the debug monitor on the remote machine before beginning the debug process.

Note Another message you might receive when you try debugging a remote machine is:

Cannot open file "G:\<filename>" on remote machine.

Verify the filename and check to be sure the file path is correct on the remote target machine.


Selecting a Memory Location

To select a memory location using drag and drop

  1. From any window, select a memory address or pointer variable containing a memory address.
  2. Drag the address or pointer to the Memory window, and drop it.

To select a memory location by editing

  1. In the Memory window, select the Address box.
  2. Type or paste the address you want to see and press ENTER.


Selecting a Remote Machine

To select a remote machine

  1. In the Processes dialog box, select the machine you want to connect to from the Machine list. If you do not find the machine you want on the list:
    1. Check the Transport box and make sure you have the proper transport selected. Default is the correct setting for most programs. Select Native-only TCP/IP if you are debugging a native program and you cannot use DCOM for some reason.
    2. Click the Ellipsis ( [image]) button next to the Machine list.
    3. In the Browse for Computer dialog box, use the tree control to locate the computer you want on the selected transport.
    4. Click OK.
    5. The computer you selected in the Browse for Computer dialog box should now appear in the Machine list. Makes sure it is selected.
    6. Click OK.


Starting Execution Of a Selected Project

To select a project and start execution

  1. In the Solution Explorer window, right-click the project you want to start.
  2. From the shortcut menu, choose Debug and Step Into.
  3. (This feature may not work with all project types.)


Toggling Live Evaluation in the Memory Window

To toggle live evaluation on or off

  1. Right-click the Memory window.
  2. From the shortcut menu, click Reevaluate Automatically.

    If live evaluation is on, the option will be checked, and clicking it turns live evaluation off. If live evaluation is off, the option is not checked, and clicking it turns live evaluation on.


Toggling the Memory Window Toolbar

To toggle the toolbar

  1. Right-click the Memory window.
  2. From the shortcut menu, click Toolbar.

    The toolbar appears or disappears, depending on its previous state.


Using the This Window

To display the This window

  • From the Debug menu, choose Windows and click This. (The debugger must be running or in break mode.)

Using the This window, you can examine the data members of the object associated with the current method (called this in C++ and C# or Me in Visual Basic).

To modify the value of a variable in the This window

  1. The debugger must be in break mode.
  2. In the This window, select the value you want to edit by double-clicking on it or by using the TAB key.
  3. Type the new value, and press ENTER.

    Caution Editing floating-point values can result in minor inaccuracies due to decimal-to-binary conversion of fractional components. Even a seemingly innocuous edit can result in changes to some of the least significant bits in the floating-point variable.


Registers Window

Note This feature is available for native-code applications only.

To open the Registers window, you must be debugging. From the Debug menu, choose Windows and choose Registers.

The Registers window displays register contents. If you keep the Registers window open as you step through your program, you can see register values change as your code executes. Values that have changed recently appear in red.


Crash Dump Module Loading

When Visual Studio loads a crash dump, it loads the binaries (modules) for the crash dump by matching the module name, linker timestamp, and file size. The module name is the base name, so exmpl will match either exmpl.exe or exmpl.dll. When Visual Studio loads a minidump, the name is the basename and the extension, so exmpl.dll will match exmpl.dll only.

Visual Studio assumes that modules are located in the same location as the crash dump and begins searching from that location. Suppose the crash dump exmpl.dmp is found in this location:

C:\qa\dumps\exmpl.dmp

Visual Studio searches the following locations:

C:\qa\dumps\exmpl.exe
C:\qa\dumps\exmpl\exmpl.exe
C:\qa\dumps\qa\exmpl\exmpl.exe
D:\qa\exmpl\exmpl.exe
C:\qa\dumps\exmpl.dll
C:\qa\dumps\exmpl\exmpl.dll
C:\qa\dumps\qa\exmpl\exmpl.dll
D:\qa\exmpl\exmpl.dll
C:\qa\dumps\kernel32.dll
C:\qa\dumps\system32\kernel32.dll
C:\qa\dumps\win2k\system32\kernel32.dll
D:\win32\system32\system32\kernel32.dll

Additional Module Search Paths

You can specify additional module search paths for a specific crash dump.

To tell Visual Studio about a nonstandard extension, you must specify it in the Command Arguments grid of the Property Pages dialog box. The syntax looks like this:

MODPATH =c:\temp\xyz,d:\temp, f:\abc\temp

When you load a crash dump, arguments specified in Command Arguments affect the loading of the crash dump. They do not affect the program being debugged. Most command arguments are ignored. MODPATH affects the loading of crash dump modules but does not affect the loading of files by the program being debugged.

The MODPATH example tells Visual Studio to look for modules in the these directories:

C:\temp\xyz\ntdll.dll
D:\temp\ntdll.dll
F:\abc\temp\ntdll.dll
C:\qa\dumps\ntdll.dll
C:\qa\dumps\system32\ntdll.dll
C:\qa\dumps\win2k\system32\ntdll.dll
D:\win32\system32\system32\ntdll.dll

Nonstandard Extensions

When reading a crash dump, Visual Studio automatically loads modules with standard extensions (DLL or EXE), but you must tell it about any nonstandard extensions that need to be loaded. For example, if xyz.pkg was loaded in memory when the crash occurred, you must tell Visual Studio about the nonstandard extension PKG.

To tell Visual Studio about a nonstandard extension, you must specify it in the Command Arguments grid of the Property Pages dialog box. The syntax looks like this:

EXTS=.pkg,.drv,.xyz

This example specifies three nonstandard extensions, pkg, drv, and xyz. The period or dot before the extension name is required. Visual Studio searches for modules in the order specified. So, if you have both exmpl.pkg and exmpl.drv, Visual studio will find and load exmpl.pkg rather than exmpl.drv.

You can use MODPATH with EXTS, as show here:

MODPATH=c:\xyz, a:\xyz;EXTS=.pkg,.drv


Crash Dumps

When debugging a native Win32 program, you can save a crash dump file for debugging at a later time, possibly on another machine. If you have just-in-time debugging enabled, you can save a crash dump even if the crash occurs while running outside of Visual Studio. A dialog box gives you the options of saving the crash dump or debugging immediately. Crash dumps can be especially useful if you are testing a program on a machine that does not have source files, PDBs, or Visual Studio installed.

The machine you debug the crash dump on must have access to the binaries for the program and the PDB files. Visual Studio can cope with missing binaries for some modules, however, as long as it has enough modules to generate valid call stacks. The message "No matching binary found" appears in the Modules window. (See Crash Dump Module Loading for details.)

Crash dumps can be useful if you are testing the program on a machine that does not have source files or PDBs installed. When the crash occurs, you can save a crash dump file and debug it later on the machine that has the source files and PDBs.

To save a crash dump file

  • From the Debug menu, choose Save As CrashDump.

To open a crash dump file

  1. From the File menu, choose Open and click File.
  2. In the Open File dialog box, locate and select the crash dump file. (It will have a .dmp extension.)
  3. Click OK.

In addition, Visual Studio can read crash dumps created by the Microsoft Office Doctor Watson utility or userdump.exe, as well as minidumps generated by minidump.dll version 42899 or higher.


Setting a Thread Name

Unmanaged C/C++ only

To set a thread name in your program, use the SetThreadName function, as shown in the following example:

//
// Usage: SetThreadName (-1, "MainThread");
//
typedef struct tagTHREADNAME_INFO
{
   DWORD dwType; // must be 0x1000
   LPCSTR szName; // pointer to name (in user addr space)
   DWORD dwThreadID; // thread ID (-1=caller thread)
   DWORD dwFlags; // reserved for future use, must be zero
} THREADNAME_INFO;

void SetThreadName( DWORD dwThreadID, LPCSTR szThreadName)
{
   THREADNAME_INFO info;
   info.dwType = 0x1000;
   info.szName = szThreadName;
   info.dwThreadID = dwThread;
   info.dwFlags = 0;

   __try
   {
      RaiseException( 0x406D1388, 0, sizeof(info)/sizeof(DWORD), (DWORD*)&info );
   }
except(EXCEPTION_CONTINUE_EXECUTION)
{
}
}


Debugging Multiple Programs

With Visual Studio.NET, you can debug multiple programs in a single solution. There are two ways to debug multiple programs in the Visual Studio debugger:

  • Start debugging the first project, and then start the additional project from Solution Explorer.
  • Start debugging the first project, and then attach to a program that is running outside of Visual Studio.

Attaching is discussed in another section.

To start a project in Solution Explorer

  1. In the Solution Explorer window, select the project you want to start debugging.
  2. Right-click the project name or icon.
  3. From the shortcut menu, choose Debug and click Step Into.

When you are debugging two or more or more projects in a solution, you can switch back and forth between them in either of two ways:

To switch between projects while debugging

  • In the Solution Explorer window, select the project you want to switch to.

    -or-

  • On the Debug Location toolbar, select the program you want to switch to from the Program list box.

Switching to a project makes it the chosen project for debugging purposes. Any command you select from the Debug menu (such as Break or Continue) will affect the chosen project.


Debugging, Options Dialog Box

  • General, Debugging, Options Dialog Box
  • Edit and Continue, Debugging, Options Dialog Box
  • Find Source, Debugging, Options Dialog Box
  • Find Symbol, Debugging, Options Dialog Box
  • Native, Debugging, Options Dialog Box


Edit and Continue, Debugging, Options Dialog Box

The Edit and Continue pane of the Options dialog box allows you to set options for Edit and Continue.

Enable Edit and Continue

Select this box to enable Edit and Continue.

Invoked by Debug Commands

When this box is selected, execution commands such as Step can invoke Edit and Continue.

Ask me first

When this box is selected, execution commands open a dialog box before invoking Edit and Continue. This dialog box gives you a chance to cancel Edit and Continue.

Warn me about stale code

In some cases, Edit and Continue cannot apply code changes to the executable immediately, but may be able to apply the code changes later if you continue debugging. This occurs if you edit a function that calls the current function or if you add more than 64 bytes of new variables to a function on the call stack. When this happens, the original code continues to execute until the function exits and is called again. Edit and Continue updates the call at that time. Until the call exits, the source window shows the original code in gray. Because this code is has been superceded by code changes, it is outdated or stale. You cannot edit stale code. The debugger warns you about stale code, by default. You can turn the warning off, if you prefer.

Relink after debugging

Edit and Continue does not invoke custom build steps. If your program uses custom build steps, you may want to rebuild manually so that custom build steps can be invoked. In that case, you can disable relinking after Edit and Continue to ensure that you are prompted to manually rebuild.

Allow Precompiling

By default, Edit and Continue loads and processes precompiled headers in the background to speed up processing of code changes. Loading precompiled headers requires allocation of physical memory, which can be a problem if you are compiling on a machine with limited RAM. Under Windows NT or Windows 2000, you can determine if this might be a problem by using the Windows NT Task Manager to determine the amount of available physical memory while you are debugging. If this amount is greater than the size of your precompiled headers, Edit and Continue should have no problem. If the amount is less than the size of your precompiled headers, you can prevent Edit and Continue from loading precompiled headers in the background


Edit and Continue Dialog Box

This dialog box appears when you have edited code while debugging and Edit and Continue recognizes that it can apply code changes.

Don't show me this dialog again

If you select this checkbox, Edit and Continue will apply code changes without asking permission in the future. You can turn this warning on again by going to the Options dialog box, opening the Debugging Folder, Edit and Continue category, and selecting Invoked by debug commands and Ask me first.

Warn me about stale code.


Executable for Debugging Session Dialog Box

This dialog box appears when you try to debug a DLL for which no executable is specified. Visual Studio cannot launch a DLL directly. Instead, it will launch the specified executable. You can debug the DLL when it is called by the executable.

Executable file name

Enter the path name to an executable that calls the DLL you are debugging.

URL where the project can be accessed (ATL Server only)

If you are debugging an ATL Server DLL, enter the URL where the project can be found.

Once entered, these settings are stored in the project Property Pages, so you will not need to enter them again for subsequent debugging sessions. If you need to change the settings, you can open the Property Pages and change the values.


Failed to Apply Code Changes Dialog Box

Edit and continue could not apply the changes you made to your code. This may be a temporary condition. Sometimes Edit and Continue cannot apply code changes immediately, but can apply them later during the debugging session (for example, after completion of the current call to the procedure now executing). For more information, see Limitations of Edit and Continue.

Rebuild

Click this button to terminate the debugging session and build your code with the changes.

Ignore

Click to ignore the message and continue debugging. Code changes will not be applied immediately, but may be applied at a later point during the run of the program (for example, after the current call).

Cancel

Cancel the Step operation that was being performed.


Find Source, Debugging, Options Dialog Box

The Find Symbol pane of the Options dialog box specifies where the debugger will look for source files when debugging the solution.

Look for source files in the following directories

This box contains a list of directories in which the debugger searches for source files when debugging the solution.

Do not look for these source files

In this box, you can enter the names of any source files that you do not want the debugger to read. If the debugger finds one of these files in one of the directories specified above, it will ignore it.


Find Symbol, Debugging, Options Dialog Box

The Find Symbol pane of the Options dialog box specifies where the debugger will look for symbols when debugging the solution.

Look for symbol files in the following directories

This box contains a list of directories in which the debugger searches for symbol files when debugging the solution.

Do not look for these symbol files

In this box, you can enter the names of any files that you do not want the debugger to read symbols from. If the debugger finds one of these files in one of the directories specified above, it will ignore it.


Microsoft Visual Studio Debugger (Exception Thrown) Dialog Box

An exception has occurred in your program. You can choose between the following options for handling the exception:

Break

Execution will break into the debugger. The exception handler is not invoked prior to the break. If you continue from the break, the exception handler will be invoked.

Continue

Allows execution to continue, giving the execution handler a chance to handle the exception. This option may be disabled for certain types of exceptions.

Ignore

Allows execution to continue without invoking the execution handler. Because the exception handler is not invoked, this can lead to further consequences, including additional exceptions and errors. This option may be disabled for certain types of exceptions.


Native, Debugging, Options Dialog Box

The Native pane of the Options dialog box allows you to set the following options for debugging native Win32 applications.

RPC Debugging

Select this control if you want to step into COM remote procedure calls when debugging.

Load COFF and Exports

Select this box to load COFF-format debugging information or DLL export tables. COFF is a format used by some other debuggers. You can find COFF-format information in the MSVBVM50.DBG file shipped provided with Visual Basic 5.01, for example. Symbolic information from DLL export tables can be useful if you are working with Windows 95/98 system DLLs, Windows messages, Windows procedures (WindowProcs), COM objects, or marshalling. Reading COFF and DLL export information entails some overhead, so this capability is turned off by default.

To see whether a DBG file contains CodeView- or COFF-format information, use dumpbin /headers. Look in the Debug Directories section of the output file for COFF (coff) or CodeView (cv) entries.

To see what symbols are available in the export table of a DLL, use dumpbin /exports. Symbols are available for any 32-bit system DLL. By reading the dumpbin /exports output, you can see the exact function name, including non-alphanumeric characters. This is useful for setting a breakpoint on a function. Function names from DLL export tables may appear truncated elsewhere in the debugger. The calls are listed in the calling order, with the current function (the most deeply nested) at the top


No Symbolic Information Dialog Box

This dialog box appears when you attempt to debug a project that has no symbolic debug information available. This may happen if:

  • You attempt to debug a Retail configuration of a project rather than the Debug configuration.
  • You have changed the Debug configuration settings in the Property Pages dialog box.
  • You are opening an .exe as a project.

Don't show this dialog again

This turns off display of this dialog box. You can turn it on again by going to the Options dialog box, opening the Debugging Folder, General category, and selecting Warn if no symbols on launch.


Stale Code Warning Dialog Box

This dialog box appears when you have made code changes that Edit and Continue could not immediately apply. As a result, some code in the current stack frame is now out of date (stale).

Don't show me this dialog again

If you select this checkbox, Edit and Continue will apply code changes without asking permission in the future. You can turn this warning on again by going to the Options dialog box, opening the Debugging Folder, Edit and Continue category, and selecting Warn about stale code.