Debugger Environment

This chapter describes the interactions you need in order to use the debugger. Topics include the interface in general:

as well as the windows and menus that are widely used:

Debugger windows

The debugger displays its information in windows. You can use a mouse or the keyboard to access all the features in the user interface.

Note: In Photon, wd's windows appear as character panels in a graphical window. Don't resize the graphical window, as wd won't refresh its character panels properly.

A sample of a wd window is shown below:

fig: ./images/wd_window.gif

Window controls

Each window has the following controls:

The Minimize button is the down-arrow button on the top right corner of the window. When you click onit, the window becomes an icon at the bottom of the screen.
The Maximize button is the up-arrow button on the top right corner of the window. When you click on it, the window fills the whole screen.
The Restore button appears only when the window is maximized, replacing the Maximize button. It's an up-and-down arrow. Click on it to put the window back to its original size.
Each window has a Close button in the top left corner. Double-click on this button to close the window.
System menu
The System menu contains these items that operate on the window:
  • Restore
  • Move
  • Size
  • Minimize
  • Maximize

You can activate a window's System Menu by clicking once on the close button.

Scroll Bars
Windows that contain information that can't fit in the window have scroll bars. Use the scroll bars to reposition the window so the information you want to see is visible. The small box in the scroll bar indicates the current scroll position in the window.
Each window is titled so that you know what information it contains. The title appears in the bar at the top of the window.
Many windows have small buttons on the left hand side. These buttons are short forms for performing the most common operations.

Current window

The current window is the one whose title bar is colored. Press Ctrl-Tab to move from window to window.

Controlling the size and location of windows

Moving windows
To move a window, click in the Title bar and drag it to a new location. You can also choose Move from the System Menu - use the cursor keys to reposition the window, then press Enter when the window's in the right spot.
Resizing windows
Move the cursor to any corner of the window. Hold the left mouse button down, and drag the mouse to resize the window.

You can also choose Size from the System Menu to change the size of a window. Use the cursor keys to resize the window, and press Enter when the window is the right size.

Note: When you use the Size command, only the right and bottom sides of the window can be moved.

Zooming windows
Choose Zoom from the Window menu to toggle a window between its maximized and normal sizes.
Context-sensitive popup menus
The debugger has context-sensitive popup menus for each window in the application. You can access the menu either by pressing the right mouse button in the window or by typing the period (.) key. You can then choose a menu item by typing the highlighted character or by clicking on it. You can close the menu without choosing an item by pressing Esc.

If you've memorized the highlighted menu character, you can bypass the menu and activate the menu item directly by pressing the Ctrl key in conjunction with that character. The items that appear in the menu depend on the current window. These menus are described in detail throughout this manual.

Note: In Photon, the combinations Ctrl-C, Ctrl-H, and Ctrl-I don't work. All the other shortcuts work.

Note: The Action item in the main menu is identical to the context-sensitive popup menu for the current window, so you can use whichever is more convenient.

Text selection
Some windows, such as the Source and Assembly windows, allow you to select text. For example, you might want to select a variable name or expression. Menu items act on the selected item.

You can select text with either the left or right mouse button. If you use the right button, the popup menu appears when you release the button. With the keyboard, hold Shift while using the cursor keys. You can select a single character, and the debugger automatically extends the selection to include the entire surrounding word.

Note: You can use the Shift key to select text only if wd is running on a console device.


You'll find a number of menu items at the top of the debugger window. You can select a menu item with the mouse, or with the Alt key and the highlighted character from the menu title. Use the cursor keys to move between menus and menu items. To select an item, press Enter; to close a menu without choosing an item, press Esc.

Many menu items have accelerators or keyboard equivalents. They appear to the right of the menu item. As you learn the debugger, take time to learn the accelerators - they'll help you use the debugger more effectively.


fig: ./images/dialog.gif

Dialogs appear when you choose a menu item that doesn't perform an immediate action. They allow you to make choices and set options. To give focus to an item in a dialog, click on it, or use Tab or Shift-Tab to move to it. The dialogs contain the following:

Edit fields
These are fields in which you can type information.
You can click on buttons to perform actions. The keyboard shortcut for the button is highlighted.
Default button
The default button in a dialog is highlighted. You can select this button by pressing Enter.
All dialogs contain a cancel button. Choose the Cancel button or press Esc to leave a dialog without saving or implementing the changes you've made to the dialog.
Check Boxes
Check boxes are used to control settings in the debugger. Press Space to toggle the option between on and off.
Radio Buttons
Radio buttons are a group of check boxes. Use the cursor keys to move to a button to turn it on. One radio button must be on at all times. When you click on one, the others in the group are turned off.
List boxes
A list box contains a list of applicable items.
Drop-down List boxes
A drop-down list box is a list that doesn't appear on the screen until you click on the down arrow on the right of the box. You may then select from a list of options.


Accelerators are keys that you can press instead of selecting a menu item or typing commands. The debugger comes with a standard set of accelerators that you can view by choosing Accelerators from the Window menu.

If you're used to the CodeView debugger, you should be comfortable with the Watcom Debugger's default set of accelerators. If you're used to using Turbo Debugger, you can select accelerators that are similar to its accelerator definitions. To select Turbo accelerators, choose Accelerator from the Window menu, then select TD Keys from the Action menu.

Default Accelerators

AcceleratorEquivalent command
CTRL-\Search/Next (see note below)
?add a new expression to the Watch window
F1invoke the Help facility
F3toggle between source level and assembly level debugging
F8Run/Trace Into
F10Run/Step Over
SHIFT-F9 add a new item to the watch window
CTRL-F4 close the current window
CTRL-F5 restore the current window to its normal size
CTRL-F6 rotate the current window
CTRL-F9 minimize the current window
CTRL-F10 maximize the current window
ALT-F10 display the floating popup menu for the current window
CTRL-TAB rotate the current window
CTRL-UP Undo/Unwind Stack
CTRL-DOWN Undo/Rewind Stack
ALT-5 Data/Memory at...
ALT-6 Data/Memory at...
ALT-7 Data/Registers
ALT-8 Data/80x87 FPU
ALT-9 File/Command...
SPACERun/Step Over
. display the floating popup menu for the current window
bBreak/At Cursor
eData/Memory at...
gRun/Execute to...
hmove cursor left one
iRun/Trace Into
jmove cursor down one
kmove cursor up one
lmove cursor right one
xRun/Next Sequential

Note: Don't use the CTRL-\ accelerator in a pterm window; it kills wd.

Turbo Emulation Accelerators

AcceleratorEquivalent command
F4Run/Run to Cursor
F7Run/Trace Into
F8Run/Step Over
ALT-F2 Break/New...
ALT-F3 close the current window
ALT-F4 Undo/Undo
ALT-F5 Window/Application
ALT-F7 trace one assembly instruction
ALT-F8 Run/Until Return
ALT-F9 Run/Execute to...
ALT-F10 activate the popup menu for the current window
CTRL-F2 Run/Restart
CTRL-F4 open a new watch window
CTRL-F7 add a new item to the watch window

Status window

The Status window appears at the bottom of the debugger screen. As you drag the mouse over a menu item, descriptive text about that menu item appears in the status window. Messages about the current status of the program and debugger warning messages also appear in the status window.

Action menu

Most windows in the debugger have a context-sensitive popup menu. The Action menu contains the same menu items as the current window's popup menu. It may be used as an alternative to the popup menus. Instead of selecting text with the right mouse button and using the popup menu, you can select text with the left mouse button or keyboard and use the Action menu.

Log window

fig: ./images/log.gif

Choose Log from then Data menu to see the Log Window. The Log Window displays several different types of messages, including:

  • status messages such as breakpoint notification
  • warning and error messages
  • output from debugger commands

You can send the contents of any window to the log window by selecting To Log from the Window menu. You can then review the information later.

Window menu

The Window menu allows you to control and arrange the windows on your screen.

The Window menu contains the following items:

Switch to the output screen of the application. Press any key to return to the debugger.
To Log
Save the current window's contents to the log window. Open the Log Window to see the contents.
To File
Save the contents of the current window to a file. You must enter a filename and choose the directory in which you want to save the information. This is useful for comparing the program state between debugging sessions.
Change the size of the current window. Zoom toggles the current window between its normal and maximum sizes.
Rotate through the windows, choosing a new current window.
Open the Accelerator window. This window allows you to inspect and modify the debugger's keyboard shortcut keys.

This menu also contains a list of the wd windows. Choose a window to give it focus; a check mark indicates which window currently has focus.

Help menu

The Help menu contains the following items that let you use the online help facility:

Show the main table of contents of the online help information. This is equivalent to pressing F1.
Display the copyright and version information for the debugger.

File menu

The File menu contains items that allow you to perform these file operations:

Start debugging a new program, or to restart the current program with new arguments.
Display a file in a window.
Enter a debugger command. For a description of debugger commands, refer to Appendix A: Debugger Commands.
Set the global debugging options. For a full description of these options, refer to the section ``Options dialog.''
Window Options
Set the options for the debugger's various windows. For a full description of these options, refer to the section ``Window options dialog.''
Save Setup
Save the debugger's current configuration. This saves the positions and sizes of all windows as well as all options and settings. By default, this information is saved in the file setup.dbg, but you can save this information in another file to create alternate debugger configurations. If you want to save the file in a directory other than the one displayed, type its pathname in the File Name field.

For more information on configuration files, see the section ``Customizing the Watcom Debugger'' in the chapter Starting Up the Debugger.

Load Setup
Load a configuration previously saved using Save Setup.
Source Path
Modify the list of directories that are searched when the debugger is searching for source code files.
Spawn a new operating system shell.
Note: If you need another shell, you can also switch consoles in character-mode, or open a new pterm window in Photon.

Close the debugger.

Options dialog

fig: ./images/options.gif

The Options dialog allows you to change the following settings:

Auto configuration save
When this option is on, the debugger automatically saves its configuration on exiting.
Warning Bell
When this option is on, the debugger beeps when a warning or error is issued.
Implicit Invoke
If this option is on, the debugger treats an unknown command as the name of a command file and automatically tries to invoke it. If this option is off, you must use the Invoke command to invoke a command file.
Caution: Under QNX, a conflict is possible when Invoke is on. A path specified for a command filename is confused with the short form of the DO command (/).

Recursion Check
Use this option to control the way tracing over recursive function calls is handled. When this option is on, and you trace over a function call, the debugger won't stop if the function executes recursively.
Screen flip on execution
Use this option to control whether the debugger automatically flips the display to the application's screen upon execution.
Ignore case
This option controls whether case is ignored or respected when the debugger is searching for a string.
Default Radix
Use this option to define the default radix used by the debugger. The debugger associates a radix with each action automatically. For example, if you're asked to enter an address, the debugger assumes base 16. If you double-click on a decimal value, you're prompted for a decimal replacement value, but there are occasions when the debugger must use the default radix. If you add an arbitrary expression to the Watches window, the default radix is used when interpreting that expression. You can specify any radix from 2 to 36, inclusive.
Double click mS
This option sets the amount of time in milliseconds allowed between two clicks for the debugger to accept it as a double click. Enter a larger value if you're having trouble with double clicks.

Window options dialog

fig: ./images/woptions.gif

Use the Window Options dialog to define options related to the debugger's various windows. All of these options appear in a dialog when you choose Window Options from the File menu.

The Window Options dialog allows you to set options for the following windows:

  • Assembly
  • Local
  • Variable
  • Watch
  • 80x87 FPU
  • Source
  • Registers
  • Functions
  • Globals
  • Modules

Assembly options

The Assembly options allow you to define how your assembly code appears. You can set the following options:

Show Source
Turn on this option if you want source code intermixed with assembly code.
Upper Case
Turn on this option if you want instructions and operands to appear in upper case.
Index Inside
Turn on this option to display an alternate form of indexing. -4[bp] is displayed as [bp-4].
Turn on this option if you want immediate operands and values to be displayed in hexadecimal.

Variables options

Use the Variable options to set display options and to specify which members of a class you want displayed when a structure or class is expanded. You can set:

Whole Expression
Turn this option on to show the whole expression used to access fields and array elements instead of just the element number or field name itself.
Display C++ member functions in expanded classes.
Display inherited members in expanded classes.
Display the compiler-generated members. You won't usually want this option turned on.
Display members of the C++ this pointer as if they were local variables declared within the member function.
Display private members in expanded classes.
Display protected members in expanded classes.

FPU options

Turn on the hexadecimal option to display the floating-point registers in raw 10-byte hexadecimal format instead of the usual floating-point notation.

File options

You can set the display width of a tab in the File options section. This value defaults to 8 spaces.

Registers options

Use the Registers options to set:

Turn this option on to display the register values in hexadecimal instead of decimal.
386 Registers
Turn this option on if you're debugging a 16-bit application and want to see the full 32-bit register set.

Functions and Globals options

For both Functions and Global Variables windows, you can turn on the Typed symbols option. This restricts the list of symbols to those defined in modules compiled with full debugging information (d2 option).

Modules options

You can turn on Show All to allow the modules window to display all modules in your program, not just those that have been compiled with the d2 option.

Accelerator window

fig: ./images/accel.gif

The Accelerator window allows you to control the accelerators or keyboard equivalents used by the debugger. Choose Accelerator from the Window menu to open this window. The window displays four items relating to each accelerator definition:

  • key name
  • window to which the accelerator applies
  • type of action that the accelerator defines
  • specifics of that action.

Accelerators may apply either to all windows or to a specific window. You could define F2 to perform a different action depending upon which window is current. Accelerators that apply to all windows have a window type of all.

An accelerator can define one of three action types:

Activate a popup menu item in the current window.
Activate an item from the main menu.
Perform an arbitrary debugger command.

You can modify an element of an accelerator definition by double-clicking on it, or by cursoring to it and pressing Enter. Press the right mouse button to access the following menu items:

Change the currently selected element of an accelerator assignment:
  • If the key name is selected, you're prompted to type a new key.
  • If the window name is selected, you're presented with a list of possible window classes.
  • If the action type or details are selected, you're presented with a menu in order to pick the menu item that's attached to the accelerator.
Add a new accelerator assignment. You'll be prompted for all details.
Delete the selected accelerator.
TD Keys
Use an approximation of Borland Turbo Debugger's accelerators.
WD Keys
Use the default set of accelerators. If you're familiar with CodeView, you'll be comfortable with these key assignments.

Code menu

The Code menu allows you to display windows that show different information related to your code:

Open the source window. It shows source code at the currently executing location. See the section ``Source Window'' in the Navigating Through a Program chapter.
Display a sorted list of modules contained in the current program. See the section ``Modules Window'' in the Navigating Through a Program chapter.
Open a sorted list of all functions in the program. See the section ``Functions Window'' in the Navigating Through a Program chapter.
Open the call history window. This window displays the program's call stack. See the section ``Calls Window'' in the Controlling Program Execution chapter.
Open the assembly window. It shows assembly code at the currently executing location. See the section ``Assembly Window'' in the Assembly-level Debugging chapter.
Open a list of all threads in your program and their current state. See the section ``Threads Window'' in the Controlling Program Execution chapter.
Open a list of the executable images that are related to the program being debugged. This includes a list of all loaded shared libraries and Dynamic Link Libraries (DLLs). See the section ``Images Window'' in the Navigating Through a Program chapter.
Open the program execution replay window. This window allows you to restart your application and replay your debugging session to any point. See the section ``Replay Window'' in the Controlling Program Execution chapter.

Data menu

The Data menu contains a number of windows that you can open to view the state of your program's data:

Open a watches window. You can add and delete variables from the watches window and use it to evaluate complex expressions and perform typecasting. See the section ``Variable and Watch Windows'' in the Examining and Modifying the Program State chapter.
Open a Locals window. It displays the local variables of the currently executing function. See the section ``Variable and Watch Windows'' in the Examining and Modifying the Program State chapter.
File Variables
Open a File Variables window. It contains a list of variables defined at file scope in the current module. See the section ``Variable and Watch Windows'' in the Examining and Modifying the Program State chapter.
Open a sorted list of all global variables in your program. Values aren't displayed (because of the overhead to update), but you can select variables from this window and add them to a Watches window. See the section ``Globals Window'' in the chapter Navigating Through a Program.
Displays the CPU registers and their values. See the section ``Register Window'' in the Assembly-level Debugging chapter.
80X87 FPU
Displays the 8087 registers and their values. See the section ``80x87 FPU Window'' in the Assembly-level Debugging chapter.
Displays memory at the stack pointer. See the section ``Memory and Stack Windows'' in the Examining and Modifying the Program State chapter.
I/O Ports
Open a window that lets you manipulate the I/O address space of the machine. See the section ``I/O Ports Window'' in the Assembly-level Debugging chapter.
Memory at...
Display memory at a given address. See the section ``Memory and Stack Windows'' in the Examining and Modifying the Program State chapter.
Displays debugger messages and the output from debugger commands. See the section ``Log Window'' in the chapter The Debugger Environment.