Index of Topics

- " -

"operator" Functions in the C++ Grammar
The "this" Operator for the C++ Grammar

- A -

Accelerate
The Accelerator Window
Accelerators
The Action Menu
Ambiguity Resolution in the C++ Grammar
Arithmetic/Logical Shift Operators for the C Grammar
Arithmetic/Logical Shift Operators for the FORTRAN Grammar
Assembly Level Debugging
The Assembly Options
The Assembly Window
Assignment Operators for the C Grammar
Assignment Operators for the FORTRAN Grammar

- B -

Binary Address Operator for the C Grammar
Binary Address Operator for the FORTRAN Grammar
Binary Arithmetic Operators for the C Grammar
Binary Arithmetic Operators for the FORTRAN Grammar
Bit Operators for the C Grammar
Bit Operators for the FORTRAN Grammar
Break
The Break Menu
The Break Window
The Breakpoint Dialog
Breakpoints
Buttons

- C -

Call
The Calls Window
CAPture
Change Directory - CHDIR, CD
Character Constant (C Only)
Character String Constant (FORTRAN Only)
Clearing, Disabling, and Enabling Breakpoints
The Code Menu
Command Summary
Common Menu Items
Common Switches
Compiler Debugging Options
Complex Constant (FORTRAN Only)
Concatenation Operator for the FORTRAN Grammar
COnfigfile
Constants
Constructor/Destructor Functions in the C++ Grammar
Context Sensitive Menus
Context Sensitive Pop-up Menus
Controlling Program Execution
Controlling the Size and Location of Windows
Copy Files - COPY
The CPU Register Window
The Current Window

- D -

The Data Menu
Debugger Commands
Debugger Settings
Debugger Windows
Debugging 32-bit DOS Extender Applications
Debugging a Novell NLM
Debugging CauseWay 32-bit DOS Extender Applications
Debugging DOS/4G(W) 32-bit DOS Extender Applications
Debugging Dynamic Link Libraries
Debugging Graphics Applications
Debugging Phar Lap 32-bit DOS Extender Applications
Debugging Under Linux
Debugging Under QNX
Debugging Under QNX Using the Postmortem Dump Facility
Debugging Windows 3.x Applications
Default Accelerators
Dialogs
Disabling Use of 386/486 Debug Registers
Display
Display File Contents - TYPE
DO (or /)
DOS
DOS and Windows Options
DOS Specific Options

- E -

Entering Search Strings
Environment Variables
Erase File - ERASE, DEL
ERror
Examine
Examining and Modifying the Program State
Exit from RFX - EXIT

- F -

The File Menu
The File Options
The File Window
Flip
Following Linked Lists
FOnt
The FPU Registers Window
The Functions and Globals Options
The Functions Window

- G -

General Rules of Expression Handling
The Globals Window
Go

- H -

Help
The Help Menu
HOok
How to Use Breakpoints during a Debugging Session

- I -

The I/O Ports Window
IF
The Images Window
Integer Constants
Interrupting a Running Program
INvoke (or <)

- L -

Language Independent Variables and Constants
Line Numbers
Link Descriptions
Linker Debugging Options
Linux
Linux Options
List Directory - DIR
Log (or >)
The Log Window
Logical Operators for the C Grammar
Logical Operators for the FORTRAN Grammar

- M -

Make Directory - MKDIR, MD
The Memory and Stack Windows
Memory References
Menus
The MMX Registers Window
MOdify
The Modules Options
The Modules Window
Moving Windows

- N -

Navigating Through a Program
NET (NetBIOS)
NetWare
NEW
New Features
NMP (Named Pipes)
NOV (Novell SPX)

- O -

Open Watcom Debugger Command Line
The Open Watcom Debugger Environment
Open Watcom Debugger Expression Handling
Operating System Specifics
Operators for the C Grammar
Operators for the C++ Grammar
Operators for the FORTRAN Grammar
The Options Dialog
OS/2
Overview

- P -

PAint
PAR (Parallel)
Parallel Port Wiring Considerations
Predefined Debugger Variables
Predefined Symbols
Preparing a Program to be Debugged
Primary Expression Operators for the C Grammar
Primary Expression Operators for the FORTRAN Grammar
Print (or ?)

- Q -

QNX
QNX Options
Quit

- R -

Real Constants
RECord
Register
Register Aggregates
Relational Operators for the C Grammar
Relational Operators for the FORTRAN Grammar
REMark (or *)
Remote Debugging
Remote File Operations (DOS, NT, OS/2 Only)
Remove Directory - RMDIR, RD
Rename - RENAME, REN
Replay
The Replay Window
Resizing Windows
Reverse Execution
RFX Commands
RFX Sample Session
The Run Menu

- S -

Scope Operator "::" for the C++ Grammar
The Search Menu
Search Order for Open Watcom Debugger Support Files under Linux
Search Order for Open Watcom Debugger Support Files under QNX
SER (Serial)
Serial Port Wiring Considerations
Set
Set Current Drive - drive:
Setting Simple Breakpoints
SHow
Simplified Breakpoints
SKip
The Source Window
Special Unary Operators for the C Grammar
Special Unary Operators for the FORTRAN Grammar
Specifying Files on Remote and Local Machines
Stack Unwinding
STackpos <intexpr>
Starting Up the Debugger
The Status Window
Symbol Names
Syntax Definitions
SYstem (or !)

- T -

TCP/IP (Internet Packets)
Text Selection
THread (or ]
The Thread Window
The Toolbar
Trace
Traversing Arrays
Turbo Emulation Accelerators

- U -

Unary Arithmetic Operators for the C Grammar
Unary Arithmetic Operators for the FORTRAN Grammar
Undo
The Undo Menu
User Interface

- V -

Variable and Watch Windows
The Variables Options
VDM (Virtual DOS Machine)
View

- W -

WD Environment Variable
WD Environment Variable in Linux
WD Environment Variable in QNX
While
WIN (Windows 3.x/9x Virtual DOS Machine)
WIndow
Window Controls
The Window Menu
The Window Options Dialog
Windows 3.x
Windows NT, Windows 95
Windows Specific Options
Wiring For Remote Debugging

- X -

The XMM Registers Window

- Z -

Zooming Windows

Overview

• DOS
• CauseWay DOS Extender
• Tenberry Software DOS/4G Extender
• Phar Lap DOS Extender
• Windows 3.x
• Windows NT/2000/XP
• Windows 9x
• 16 and 32-bit OS/2
• GNU/Linux
• QNX 4
• QNX 6 (Neutrino)
• Novell NetWare

New Features

User Interface

Reverse Execution

Replay

Stack Unwinding

Simplified Breakpoints

Context Sensitive Menus

Buttons

Common Menu Items

Inspect

Inspect displays the selected item.  The debugger determines how to best display the selected item based on its type.   If you inspect a variable or an expression, the debugger opens a new window showing its value.  If you inspect a function, the debugger positions the source code window at the function definition.  If you inspect a hexadecimal address from the assembly window, a window showing memory at that address is opened, and so on.  Experimenting with inspect will help you learn to use the debugger effectively. 

Modify

Modify lets you change the selected item.  You will normally be prompted for a new value.  For example, select the name of a variable from any window and choose Modify to change its value. 

New

New adds another item to a list of items displayed in a window.  For example, choosing New in the Break Point window lets you create a new breakpoint. 

Delete

Delete removes the selected item from the window.  For example, you can use Delete to remove a variable from the Watches window. 

Source

Source displays the source code associated with the selected item.  The debugger will reposition the source code window at the appropriate line.  Selecting a module name and choosing Source will display the module's source code. 

Assembly

Assembly positions the assembly code window at the code associated with the selected item. 

Functions

Functions shows a list of all functions associated with the selected item or window.  For example, choose Functions in the source window to see a list of all functions defined in that module. 

Watch

Watch adds the selected variable or expression to the Watches window.  This allows you to watch its value change as the program runs.  Note that this is not a watchpoint.  Execution will not stop when the variable changes.   See the chapter entitled Breakpoints for information about setting watchpoints. 

Break

Break sets a breakpoint based on the selected item.  If a variable is selected, the program will stop when the variable is modified.  If a function is selected, the program will stop when the function executes. 

Globals

Globals shows a list of global variables associated with the selected item. 

Show

Show will present a cascaded menu that let's you show things related to the selected item.  For example, you can use Line from the Show menu in the source code window to see the line number of the selected line. 

Type

Type will present a cascaded menu that allows you to change the display type of the window or selected item.

Preparing a Program to be Debugged

1. specify the correct compiler options when you compile, and
2. specify the correct linker options when you link.

Compiler Debugging Options

d0

The d0 option will generate no debugging information.  This is the default option.

d1

The d1 option will generate debugging information for global symbols and line numbers.

d1+

The d1+ option will generate debugging information for global symbols and line numbers, and typing information for local structs and arrays.

d2

The d2 option will generate the most debugging information that is normally needed, including global information, line numbers, types, and local variables.

d2i

The d2i option is identical to d2 but does not permit inlining of functions.  This option can result in larger object and/or executable files (we are discussing both "code" and "file" size here).

d2t

The d2t option is identical to d2 but does not include type name debugging information.  This option can result in smaller object and/or executable files (we are discussing "file" size here).

d3

The d3 option will generate all debugging information generated by d2.  In addition, it will generate information about all types defined in a compilation unit, regardless of whether they are used in that compilation unit.  This option will create very large objects and executable files.  Do not use it unless you want to have access to types that have no variables associated with them.

Linker Debugging Options

DEBUG ALL

DEBUG DWARF

DEBUG WATCOM LINES

global names, source line numbers

DEBUG WATCOM ALL

global names, source line numbers, local variables, typing information

Debugger Settings

Starting Up the Debugger

• Open Watcom Debugger Command Line
• Common Switches
• DOS and Windows Options
• DOS Specific Options
• Windows Specific Options
• Linux Options
• QNX Options
• Environment Variables

Open Watcom Debugger Command Line

binw\wd.exe

This is the DOS character-mode debugger.

binw\wdc.exe

This is the Windows 3.x character-mode debugger.

binw\wdw.exe

This is the Windows 3.x windowed (GUI) debugger.

binnt\wd.exe

This is the Windows NT/9x character-mode debugger.

binnt\wdw.exe

This is the Windows NT/9x windowed (GUI) debugger.

binp\wd.exe

This is the OS/2 character-mode debugger.

binp\wdw.exe

This is the OS/2 windowed (GUI) debugger.

wd

This is the name of the debugger used on UNIX platforms.

Common Switches

/TRap=trap_file[;trap_parm]

specifies an executable helper program that the debugger uses to control the application being debugged, or to communicate across a remote link.  It is called a "trap file" since the interrupts used for debugging are sometimes called "traps".  The trap option selects the appropriate trap file to use.  This option must be specified when remote debugging, debugging DOS extender applications or debugging OS/2 exception handlers.
The remote trap files themselves have startup parameters.  This is specified following the semi-colon.  See Remote Debugging.  Normally you do not have to specify a trap file.  If you do not specify the trap option, the default trap file that supports local debugging is loaded.  There are several exceptions.

1. To debug a CauseWay 32-bit application, you must use /TRAP=CW.
2. To debug a Tenberry Software 32-bit DOS/4G(W) application, you must use /TRAP=RSI.
3. To debug a Phar Lap 32-bit application, you must use /TRAP=PLS.
4. To debug an OS/2 exception handler, you must use /TRAP=STD 2 which tells the debugger to catch exceptions only on the second chance (normally it would be the debugger that traps the exception).
5. To debug an OS/2 16-bit application under Phar Lap's RUN286 DOS extender, you must use /TRAP=STD16.

/LInes=n

controls the number of lines used by a character mode debugger.  The number of lines available depends on the operating system and your video card.  The values 25, 43 and 50 are often supported.

/COlumns=n

controls the number of columns used by a character mode debugger.  The number of columns available depends on the operating system and your video card.  If your system does not support the requested number of columns, this option is ignored

/Invoke=file

may be used to specify an alternate name for the debugger configuration file which is to be used at start-up time.  The default file name is "WD.DBG".  Debugger configuration files are found in the current directory or one of the directories in your PATH.

/NOInvoke

specifies that the default debugger configuration file is not to be invoked.

/NOMouse

requests that the debugger ignore any attached mouse.  This may be necessary if you are trying to debug mouse events received by your application.  This option ensures that the debugger will not interfere with the mouse.

/DYnamic=number

specifies the amount of dynamic storage that the debugger is to set aside for its own use on startup.  The default amount that is set aside is 500K bytes.  The larger the amount, the less memory will be available for the application to be debugged.  You only need to use this option if the debugger runs out of memory, or is causing your application to run out of memory.  If you are using the remote debugging feature, the debugger will use as much available memory as available.

/NOExports

specifies that no exports (system symbols) should be loaded.  It helps to speed up load time when debugging remotely and marginally so when debugging locally.

/LOcalinfo=local_file

is used primarily, but not exclusively, in conjunction with the remote debugging capabilities of the debugger.  It causes the debugger to use one or more local files as sources of debugging information if the right conditions are met.  When the debugger observes that an executable file or Dynamic Link Library (DLL) is being loaded with the same name (i.e., the path and extension have been stripped) as one of the /localinfo files, then the named local file is used as a source of debugging information.  The named file can be an executable file, a DLL file (.dll), a symbolic information file (.sym), or any other file with debugging information attached.
Example:

     wd /local=c:\dlls\mydll.sym /local=c:\exes\myexe.exe /tr=par myexe

In the above example, the debugger would obtain debugging information for any executable or DLL called myexe or mydll from c:\exes\myexe.exe or c:\dlls\mydll.sym respectively.  Note that no path searching is done for local files.  The debugger tries to open the file exactly as specified in the localinfo option.

See the section entitled Remote Debugging for an explanation of remote debugging.

/DOwnload

specifies that executable file to be debugged is to be downloaded to the task machine from the debugger machine.  The debugger searches for the executable file in the local path, and downloads it to the debug server's current working directory on the remote machine before starting to debug.  Debugging information is not downloaded, but is obtained locally, as in the localinfo option.  Note:  Only the executable is downloaded; any required DLLs must be present on the remote machine.  Downloading is relatively fast if you are using one of the TCP/IP (TCP) or Netware (NOV) remote links.  Be sure to specify the file extension if it is not ".exe".
Example:

     wd /tr=nov;john /download sample.exe
     wd /tr=nov;john /download sample.nlm

The debugger does not erase the file when the debugging session ends.  So if you debug the application again, it will check the timestamp, and if the file is up-to-date, it doesn't bother re-downloading it.

See the section entitled Remote Debugging for an explanation of remote debugging.

/REMotefiles

is used in conjunction with the remote debugging capabilities of the debugger.  It causes the debugger to look for all source files and debugger files on the remote machine.  When remotefiles is specified, all debugger files (except "trap" files) and application source files are opened on the task machine rather than the debugger machine.  The trap file must be located on the debugger machine.
The PATH environment variable on the task machine is always used in locating executable image files.  When remotefiles is specified, the debugger also uses the task machine's PATH environment variable to locate debugger command files.  See the section entitled Remote Debugging for an explanation of remote debugging.  See the section entitled Specifying Files on Remote and Local Machines for an explanation of remote and local file names.

/NOFpu

requests that the debugger ignore the presence of a math coprocessor.

/NOSYmbols

requests that the debugger omit all debugging information when loading an executable image.  This option is useful if the debugger detects and tries to load debugging information which is not valid.

/DIp=dipname

used to load a non-default Debug Information Processor (DIP).  This option is generally not needed since the debugger loads all DIPs that it finds by default.  See The Images Window.

DOS and Windows Options

/Monochrome

When two display devices are present in the system, this option indicates that the Monochrome display is to be used as the debugger's output device, leaving the Color display for the application to use.  Use this option in conjunction with the Two option described below.

/Color, /Colour

When two display devices are present in the system, this option indicates that the Colour display is to be used as the debugger's output device.  This option is used in conjunction with the Two option described below.

/Ega43

When an Enhanced Graphics Adapter (EGA) is present, 43 lines of output are displayed by a character mode debugger.

/Vga50

When a Video Graphics Array (VGA) is present, 50 lines of output are displayed by a character mode debugger.

/Overwrite

specifies that the debugger's output can overwrite program output.  In this mode, the application and the debugger are forced to share the same display area.
Do not use this option if you wish to debug a DOS graphics-mode application.

/Two

specifies that a second monitor is connected to the system.  If the monitor type (Monochrome, Color, Colour, Ega43, Vga50) is not specified then the monitor that is not currently being used is selected for the debugger's screen.  If the monitor type is specified then the monitor corresponding to that type is used for the debugger's screen.  This option may be used when debugging a DOS graphics-mode application on the same machine and a second monitor is available.

DOS Specific Options

/Page

specifies that page 0 of screen memory is to be used for the application's screen and that page 1 of screen memory should be used for the debugger's screen.  This option may be selected when using a graphics adapter such as the CGA, EGA or VGA.  Using the Page option results in faster switching between the application and debugger screens and makes use of the extra screen memory available with the adapter.  This is the default display option.  Do not use this option if you wish to debug a DOS graphics-mode application.

/Swap

specifies that the application's screen memory and the debugger's screen memory are to be swapped back and forth using a single page.  The debugger allocates an area in its own data space for the inactive screen.  This reduces the amount of memory available to the application.  It also takes more time to switch between the application and debugger screens.   This option MUST be used when debugging a DOS graphics-mode application and a second monitor is not available.
The default display options are:

1. If you have a two display system, the debugger uses both displays with the program output appearing on the active monitor and the debugger output appearing on the alternate monitor.  In other words, the Two option is selected by default.
2. If you have one of the CGA, EGA or VGA graphics adapters installed in your system then the debugger selects the Page option by default.
3. Under all other circumstances, the debugger selects the Swap option by default.

/CHecksize=number

specifies the minimum amount of storage, in kilobytes, that the debugger is to provide to DOS for the purpose of spawning a program while the debugger is active.  This option is useful when the application that is being debugged uses up most or all of available storage, leaving insufficient memory to spawn secondary programs.  In order to provide the requested amount of free memory to DOS, the debugger will checkpoint as much of the application as required.
Checkpointing involves temporarily storing a portion of the memory-resident application on disk and then reusing the part of memory that it occupied for the spawned program.  When the spawned program terminates, the checkpointed part of the application is restored to memory.

The default amount is 0K bytes.  In this case, the spawned program may or may not be run depending on how much free storage is available to DOS to run the program.

Warning:

If the application being debugged installs one or more interrupt handlers, the use of this option could hang your system.   Your system could lock up if the debugger checkpoints a portion of the application's code that contains an interrupt handler.

/NOCHarremap

turns off the character re-mapping that the DOS debugger uses for displaying dialogs and window frames.  Use this option when trying to debug in an environment where character remapping is not available.  Windowed DOS boxes under OS/2 do not support character re-mapping.

/NOGraphicsmouse

Turn off the graphics mouse emulation code that makes the mouse cursor look like an arrow instead of a block.  Use this option if the mouse cursor appears as 4 line drawing characters instead of an arrow.

Windows Specific Options

/Fastswap

specifies that Windows 3.x screen memory and the debugger's screen memory are to be swapped back and forth using a technique that is faster than the default method of screen swapping but not guaranteed to work for all video adapters.  This option applies to Windows 3.x only.  By default, the Windows 3.x version of the debugger uses a more conservative (and slower) method that works with all video adapters.

Linux Options

-Console=console_spec

specifies the virtual console to use for debugger windows.  This may be a console number as in the following example.
Example:

     -console=2

You may also use a full device name.

Example:

     -console=/dev/tty

In this case, the debugger will use that device for its input and output.  The debugger/application screen flipping features will be disabled.

You can also optionally follow the device name with a colon and a terminal type.

Example:

     -con=/dev/tty:vt240

This will let the debugger know what kind of terminal it's talking to so it can initialize the user interface appropriately.

-COlumns=n

specifies the number of columns of the screen/window that the debugger should attempt to establish.

-XConfig=string

specifies a set of X Windows configuration options to pass to xterm.  The following example sets the xterm font size to 12 point.
Example:

     -xc=-fs -xc=12

QNX Options

-Console=console_spec

specifies the virtual console to use for debugger windows.  This may be a console number as in the following example.
Example:

     -console=2

You may also use a full device name.

Example:

     -console=//23/dev/ser1

In this case, the debugger will use that device for its input and output.  The debugger/application screen flipping features will be disabled.

You can also optionally follow the device name with a colon and a terminal type.

Example:

     -con=/dev/ttyp1:vt240

This will let the debugger know what kind of terminal it's talking to so it can initialize the user interface appropriately.

-COlumns=n

specifies the number of columns of the screen/window that the debugger should attempt to establish.

-XConfig=string

specifies a set of X Windows configuration options to pass to xqsh.

Environment Variables

WD Environment Variable

WD Environment Variable in Linux

WD Environment Variable in QNX

The Open Watcom Debugger Environment

Debugger Windows

Window Controls

Minimize, Maximize, Restore

You can control the size of each window using the Minimize, Maximize, and Restore buttons.  The buttons appear on the top right corner of the window.  The Minimize button is the down arrow.  When you click on the down arrow, the window becomes an icon at the bottom of the screen.  The Maximize button is the up arrow.  When you click on the up arrow, the window fills the whole screen.  The Restore button appears only when the window is maximized.  It is an up and down arrow.  Click on the Restore button to put the window back to its original size.

Close

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 menu items that operate on the window.  It contains:

• Restore
• Move
• Size
• Minimize
• Maximize

You can activate the System Menu of the main window by clicking once on the System Menu button (top, left-hand corner) or by typing ALT-Space.  For Microsoft Windows, you can type ALT-Hyphen to activate a child window's System Menu.

Scroll Bars

Windows that contain information that cannot 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.

Title

Each window is titled so that you know what information it contains.  The title appears in the bar at the top of the window.

Buttons

Many windows have small buttons on the left hand side.  These buttons are short forms for performing the most common operations.

The Current Window

Controlling the Size and Location of Windows

• Moving Windows
• Resizing Windows
• Zooming Windows
• Context Sensitive Pop-up Menus
• Text Selection

Moving Windows

Resizing Windows

Zooming Windows

Context Sensitive Pop-up Menus

Note

The Action item in the main menu is identical to the the context sensitive pop-up menu for the current window and may be used instead of pop-up menus.

Text Selection

Menus

The Toolbar

• Go from the Run menu
• Step Over from the Run menu
• Trace Into from the Run menu
• Until Return from the Run menu
• Undo from the Undo menu
• Redo from the Undo menu
• Unwind Stack from the Undo menu
• Rewind Stack from the Undo menu
• Home from the Undo menu

Dialogs

Edit fields

These are fields in which you can type information.

Buttons

You can click on buttons to perform actions.

Default button

The default button in a dialog is highlighted.  You can select this button by pressing ENTER.

Cancel

All dialogs contain a cancel button.  Choose the Cancel button or press ESC to leave a dialog without saving or implementing changes you have made to the dialog.

Check Boxes

Check boxes are used to control settings in the debugger.  Click on the field, or TAB to it and press SPACE to toggle the option between on and off.

Radio Buttons

Radio buttons present a set of mutually exclusive choices.  Click on a radio button to turn it on or press TAB to move to the group of radio buttons and use the cursor keys to select a radio button.  If this does not work, use the accelerator key to turn on the desired radio button.  Only one radio button is on at all times.  When you select a different radio button, the currently selected one is 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 does not 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

Default Accelerators

/

Search/Find...

ALT-/

Search/Next

CTRL-\

Search/Next

?

add a new expression to the Watch window

F1

invoke help facility

F2

Data/Registers

F3

toggle between source level and assembly level debugging

F4

Window/Application

F5

Run/Go

F6

Window/Next

F7

Run/Run to Cursor

F8

Run/Trace Into

F9

Break/Toggle

F10

Run/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 pop-up menu for the current window

CTRL-TAB

rotate the current window

CTRL-LEFT

Undo/Undo

CTRL-RIGHT

Undo/Redo

CTRL-UP

Undo/Unwind Stack

CTRL-DOWN

Undo/Rewind Stack

CTRL-BACKSPACE

Undo/Home

ALT-1

Data/Locals

ALT-2

Data/Watches

ALT-3

Code/Source

ALT-4

File/View...

ALT-5

Data/Memory at...

ALT-6

Data/Memory at...

ALT-7

Data/Registers

ALT-8

Data/80x87 FPU

ALT-9

File/Command...

CTRL-z

Window/Zoom

SPACE

Run/Step Over

.

display the floating pop-up menu for the current window

:

File/Command...

=

Search/Match

n

Search/Next

N

Search/Previous

u

Undo/Undo

U

Undo/Redo

b

Break/At Cursor

e

Data/Memory at...

g

Run/Execute to...

h

move cursor left one

i

Run/Trace Into

j

move cursor down one

k

move cursor up one

l

move cursor right one

t

Break/Toggle

x

Run/Next Sequential

Turbo Emulation Accelerators

F2

Break/Toggle

F3

Code/Modules

F4

Run/Run to Cursor

F5

Window/Zoom

F6

Window/Next

F7

Run/Trace Into

F8

Run/Step Over

F9

Run/Go

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 pop-up 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

The File Menu

Open

Start debugging a new program, or to restart the current program with new arguments. 

View

Display a file in a window. 

Command

Enter a debugger command.  For a description of debugger commands, refer to the section entitled Debugger Commands.  

Options

Set the global debugging options.  For a full description of these options, refer to the section entitled The Options Dialog.  

Window Options

Set the options for the debugger's various windows.  For a full description of these options, refer to the section entitled The 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 into the file setup.dbg, however, you can save this information into another file to create alternate debugger configurations. 

Load Setup

Load a configuration previously saved using Save Setup. 

Source Path

Modify the list of directories which will be searched when the debugger is searching for source files. 

System

The menu item appears only in the character-based version of the debugger.  It spawns a new operating system shell. 

Exit

Close the debugger.

The Options Dialog

Auto configuration save

When this option is on, the debugger automatically saves its configuration upon exit. 

Warning Bell

When this option is on, the debugger will beep when a warning or error is issued. 

Implicit Invoke

If this option is on, the debugger will treat an unknown command as the name of a command file and automatically try to invoke it.  If this option is off, you must use the invoke command to invoke a command file.
Under UNIX, a conflict is possible when Invoke is on.  A path specified for a command file name is confused with the short form of the DO command (/).  A similar problem occurs under DOS, OS/2, Windows 3.x, Windows NT, or Windows 95 when a drive specifier forms part of the file name. 

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 will not stop if the function executes recursively. 

Break on write (not change)

Use this option (if available with the selected trap) to enable true break-on-write breakpoints.  This will break on any write access; not just when a watch point has changed.

Screen flip on execution

Use this option to control whether the debugger automatically flips the display to the application's screen upon execution.   Leave this option on if you are using the character mode debugger to debug a Windows 3.x application.

Ignore case

This option controls whether or not case is ignored or respected when the debugger is searching for a string.

Do not expand hex numbers

This option controls whether or not hexadecimal values are displayed in their natural size (zero preceded) or displayed in their most compact form.  The default is to display the value in its full natural size. 

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 are asked to enter an address, the debugger assumes base 16.  If you double click on a decimal value, you will be 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 between 2 and 36.

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 are having trouble with double clicks.

The Window Options Dialog

• Source
• Modules
• Functions
• Assembly
• Watches
• Locals
• File Variables
• Globals
• Variable

The Assembly Options

Show Source

Turn on this option if you want source code intermixed with assembly code.

Hexadecimal

Turn on this option if you want immediate operands and values to be displayed in hexadecimal.

The Variables Options

Protected

Display protected members in expanded classes.

Private

Display private members in expanded classes.

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.

Functions

Display C++ member functions in expanded classes.

Inherited

Display inherited members in expanded classes.

Compiler

Display the compiler-generated members.  You will usually not want this option turned on.

Members

Display members of the 'this' pointer as if they were local variables declared within the member function.

Static

Display static members.

The File Options

The Functions and Globals Options

The Modules Options

The Code Menu

Source

Open the Source window.  It shows source code at the currently executing location.  See The Source Window.  

Modules

Display a sorted list of modules contained in the current program.  See The Modules Window.  

Functions

Open a sorted list of all functions in the program.  See The Functions Window. 

Calls

Open the Call History window.  This window displays the program's call stack.  See The Calls Window.  

Assembly

Open the Assembly window.  It shows assembly code at the currently executing location.  See The Assembly Window.  

Threads

Open a list of all threads in your program and their current state.  See The Thread Window.  

Images

Open a list of the executable images which are related to the program being debugged.  This includes a list of all loaded DLLs.  See The Images Window. 

Replay

Open the program execution Replay window.  This window allows you to restart your application and replay your debugging session to any point.  See The Replay Window.

The Data Menu

Watches

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 Variable and Watch Windows. 

Locals

Open a Locals window.  It displays the local variables of the currently executing function.  See Variable and Watch Windows.  

File Variables

Open a File Variables window.  It contains a list of variables defined at file scope in the current module.  See Variable and Watch Windows. 

Globals

Open a sorted sorted list of all global variables in your program.  Values are not displayed since it would make this window very expensive to update, but you can select variables from this window and add them to a Watches window.  See The Globals Window. 

Registers

Displays the CPU registers and their values.  See The CPU Register Window. 

FPU Registers

Displays the FPU registers and their values.  See The FPU Registers Window. 

MMX Registers

Displays the MMX (multi-media extension) registers and their values.  See The MMX Registers Window.  

XMM Registers

Displays the XMM (SSE) registers and their values.  See The XMM Registers Window.  

Stack

Displays memory at the stack pointer.  See The Memory and Stack Windows.  

I/O Ports

Open a window that lets you manipulate the I/O address space of the machine.  See The I/O Ports Window.  

Memory at...

Display memory at a given address.  See The Memory and Stack Windows. 

Log

Displays debugger messages and the output from debugger commands.  See The Log Window.

The Window Menu

Application

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 file name and choose the drive and directory to which you want to save the information.  This is useful for comparing program state between debugging sessions. 

Zoom

Change the size of the current window.  Zoom toggles the current window between its normal and maximum sizes. 

Next

Rotate through the windows, choosing a new current window. 

Accelerator

Open the Accelerator window.  This window allows you to inspect and modify the debugger's keyboard shortcut keys.

The Action Menu

The Help Menu

Contents

Show the main table of contents of the on-line help information.  This is equivalent to pressing F1. 

On Help

Display help about how to use the on-line help facility.  This menu item is not available in character-mode versions of the debugger. 

Search

Search the on-line help for a topic.  This menu item is not available in character-mode versions of the debugger. 

About

Display the "about box".  It contains the copyright and version information of the debugger.

The Status Window

The Log Window

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

The Accelerator Window

pop-up

Activate a pop-up menu item in the current window.

menu

Activate an item from the main menu.

command

Perform an arbitrary debugger command.

Modify

Change the currently selected element of an accelerator assignment.  If the key name is selected, the you will be prompted to type a new key.  If the window name is selected, you will be presented with a list of possible window classes.  If the action type or details are selected, you will be presented with a menu in order to pick the menu item which will be attached to the accelerator. 

New

Add a new accelerator assignment.  You will be prompted for all details. 

Delete

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 are familiar with CodeView, you will be comfortable with these key assignments.

Navigating Through a Program

The Search Menu

Find

Search the current window for the first appearance of a given string.  You will be prompted for the string.  See Entering Search Strings. 

Next

Find a subsequent occurrence of a search string. 

Previous

Find a previous occurrence of a search string. 

All Modules

This will search through the source code of all the modules contained in your program for a given string.  See Entering Search Strings.  

Match

Find a string in a sorted window by incremental matching.  Once you select match, the text you type appears in the status window, and the window you are searching repositions itself as you type each character.  Press ESC to leave this mode.

Entering Search Strings

Enter Search String

Enter the string to be found in this edit box.  The larger list below shows other strings that you have searched for during this debugging session.  You can select these by clicking on them or by using the up and down arrow keys.  The most recent search string appears at the top of the list.

Regular Expression

Check this box if the string is to be interpreted as a regular expression.  You can click on the Edit button to edit the set of regular expression characters that will be used.  For a description of regular expressions, see the Editor manual.

Ignore Case

Check this box if you want the debugger to match the search string regardless of case.

The Source Window

Inspect

Inspect the selected item in an appropriate window.  You can select function names, variable names, or any valid expression.  

Run to Cursor

Resume program execution until the selected line is executed. 

Break

Add a breakpoint based on the selected text.  If a variable is selected, the program will stop when its value changes.   If a function name is selected the program will stop when that function is executed.  This does not set a break at the current line.  Use Toggle from the Break menu or At Cursor from the Break menu to set a breakpoint at the current line. 

Enter Function

Resume program execution until the selected function is entered. 

Watch

Add the selected item to the Watches window for further inspection or modification. 

Find

Search for other occurrences of the selected string in the Source window. 

Home

Reposition the window to show the currently executing location.  The cursor will move to the next line of the program to be executed. 

Show/Assembly

Show the assembly code associated with the selected line. 

Show/Functions

Show the list of all functions contained in the source file. 

Show/Address

Reposition the window at a new address.  You will be prompted for an expression.  Normally you would type a function name but you can type any expression that resolves to a code address.  For example, you might type the name of a variable that contains a pointer to a function.  See Open Watcom Debugger Expression Handling.  

Show/Module

Show the code for a different module.  You will be prompted for its name in a dialog.  As a shortcut, you can type the beginning of a module name and click the Module...  button.  This will display a list of all modules that start with the text you typed. 

Show/Line

Move to a different source line.  You can also find out what line you are looking at.  The edit field will be initialized with the current line number.

The File Window

The Modules Window

Source

Show the source code associated with the selected module. 

Assembly

Show the assembly code associated with the selected module. 

Functions

Show the list of all functions contained in this module. 

Break All

Set a breakpoint at each function in this module. 

Clear All

Delete all breakpoints which are set at addresses with this module.  This does not affect break-on-write break points.  

Show All

Toggle between showing all modules and just modules which were compiled with full debugging information (d2).  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The Globals Window

Watch

Add the selected variable to the Watches window. 

Raw Memory

Display the memory associated with the selected variable. 

Typed Symbols

Toggle between showing all symbols and just those defined in modules compiled with the d2 option.  Variables from the C/C++ library and assembly code are suppressed.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The Functions Window

Break

Set a breakpoint at the selected function.  A dialog will appear so that you can fill in detailed breakpoint information.   For more information, refer to the section entitled The Breakpoint Dialog. 

Source

Show the source code for the selected function. 

Assembly

Show the assembly code associated with the selected function. 

Typed Symbols

Toggle between showing all symbols and just those defined in modules compiled with the d2 option.  Variables from the C/C++ library and assembly code are suppressed.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The Images Window

DWARF

This information is generated by the Open Watcom compilers.

Watcom

This information is optionally generated by the Open Watcom compilers.

CodeView

In addition to Open Watcom compilers, several other products, including Microsoft's, can generate CodeView style information.

MAPSYM

This information is generated by Microsoft's or IBM's MAPSYM utility.  MAPSYM processes linker map file and outputs a .sym file.  Symbol files in MAPSYM format are often available for OS/2 system DLLs.  MAPSYM files only contain information about global symbols, but usually provide much more detail than just exports information.

EXPORTS

This information is contained in the executable file itself, and is used by the operating system.  Under OS/2, Windows and Windows NT, DLLs have export tables which define the names and addresses of entry points.  Exports information lets you see the names of system entry points and APIs.  Novell NLMs also have entry point tables.  In addition, they may have Novell style debugging information, created with Novell's linker (NLMLINK) or using the Open Watcom Linker's "debug novell" option.  This information is made available to the debugger.

New Symbols

Add symbolic debugging information for the selected image.  This is useful if you know that a separate debug information file contains the appropriate debugging information that was not found by the debugger. 

Delete Symbols

Delete any symbolic debugging information associated with the selected image. 

Modules

Show a list of modules contained in the selected image. 

Functions

Show a list of functions contained in the selected image. 

Globals

Show a list of all global variables contained in the selected image.

Controlling Program Execution

The Run Menu

Go

Start or resume program execution.  Execution resumes at the current location and will not stop until a breakpoint is encountered, an error occurs, or your program terminates. 

Run to Cursor

Resume program execution until it executes the location of the cursor in the Source or Assembly window.  Execution will stop before the cursor position if a breakpoint is encountered or an error occurs. 

Execute to

Resume program execution until it executes a specified address.  You will be prompted to enter an address.  It can be the name of a function or an expression that resolves to a code address.  See Open Watcom Debugger Expression Handling.   In the dialog, you can click the Symbols...  button as a shortcut.  You can type a partial symbol name like foo and the Symbol button will show you a list of symbols that start with foo.  You can then choose one of these symbols by clicking on it or hitting ENTER.  Note that the first time you use the Symbols...  in a debugging session, it will take a while as the debugger sorts the symbol table for the program.
If your program encounters a breakpoint or an error occurs before the specified address is executed, your request to stop at the given address is ignored. 

Step Over

Trace a single source or assembly line depending on whether the source or assembly window is current.  Step Over will not step into any function calls. 

Trace Into

This is similar to Step Over except that it will step into any function calls. 

Next Sequential

Run until the program executes the next sequential source line or assembly instruction.  This is useful if the program is executing the last statement in a loop and you wish to execute until the loop terminates.  When using this command, be sure that the execution path will eventually execute the next statement or instruction.  If execution fails to reach this point then the program may continue to execute until completion.  This situation is like setting a breakpoint at a statement or assembly instruction which will never be executed and then issuing a GO command.  In this situation, the application would execute until an error occurred or another breakpoint was encountered. 

Until Return

Resume program execution until the currently executing function returns.  Execution terminates prior to this if an error occurs or a breakpoint is encountered. 

Skip to Cursor

Reposition the instruction pointer at the cursor position, "skipping" all instructions in between.  When you continue execution, the program continues from this point.  This is useful if you want to skip an offending line or re-execute something.  Use this menu item with caution.  If you skip to an instruction which is not in the current function or skip to code that expects a different program state, your program could crash. 

Restart

Restart your program from the beginning.  All breakpoints in your program will be preserved.  Breakpoints in DLLs will not be preserved. 

Debug Startup

Restart your program from the beginning but stop before system initialization.  Normally the debugger puts you at the main (fmain, winmain, etc.) entry point in your application.  This option will allow you to break much earlier in the initialization process.  This feature is useful for debugging run-time startup code, initializers, and constructors for static C++ objects.
For DOS, Windows 3.x and Netware, the debugger will put you at the assembly entry point of your application (i.e., it doesn't run the "progstart" hook).

Windows 3.x runs each DLL's startup code as it loads it, and the static DLLs are really loaded by the run-time startup code, so, to debug the startup code for a statically linked Windows 3.x DLL, you need to do the following.

1. Select Debug Startup from the Run menu.
2. Select On Image Load from the Break menu.  Type the name of the DLL in which you are interested.
3. Select Go from the Run menu

For OS/2 and Windows NT, the debugger will put you at a point after all DLLs have been loaded, but before any DLL initialization routines are called.  This enables you to set breakpoints in your statically referenced DLL's startup code.

If you have hard-coded int3 instructions in your DLL startup, the debugger will skip them, unless you use Debug Startup from the Run menu.

All breakpoints in your program will be preserved.  Breakpoints in DLLs will not be preserved. 

Save

Save the current debugging session to a file.  The file contains commands that will allow the debugger to play your debugging session back to its current point in a later session.  See The Replay Window. 

Restore

Restore a saved debugging session.  If you run the program with different input or if the program is a multi-threaded application, this option may not work properly since external factors may have affected program execution.  See The Replay Window.

The Undo Menu

Undo

Browse backwards through the program execution history. 

Redo

Browse forward through the program execution history. 

Unwind Stack

Move up the call stack one level. 

Rewind Stack

Move down the call stack one level. 

Home

Return to the currently executing location, reversing the effects of all Undo and Unwind operations.

The Replay Window

Goto

Replay the program until it returns to the selected level in the replay history. 

Source

Position the source window at the selected line. 

Assembly

Show the assembly code for the selected line.

The Calls Window

Unwind

Unwind the stack to the level of the selected code.  This is equivalent to using Unwind from the Undo menu or Rewind from the Undo menu. 

Break

Set a breakpoint at the return from the selected call. 

Goto

Execute until the program returns from the selected call.

The Thread Window

current

This is the thread that was running when the debugger was entered.  It is the thread that hit a break point or error.   When you trace through the application, only the current thread is allowed to run.

runnable

This thread will be allowed to run whenever you let your program run, but will not run when you trace the program.

frozen

This thread will not be allowed to run when you resume your program.

dead

Under some operating systems, threads that have been terminated still show up in the list of threads.  A dead thread will never execute again.

Switch to

Make the selected thread current. 

Freeze

Change the state of the selected thread to be frozen.  You cannot freeze the current thread. 

Thaw

Change the state of the selected thread to be runnable..  The current thread is always runnable.

Examining and Modifying the Program State

• Variable and Watch Windows
• The Memory and Stack Windows

Variable and Watch Windows

• Locals
• File Variables
• Watches
• Variable

Locals

Contains the list of variables which are local to the current routine.  Choose Locals from the Data menu to open this window.

File Variables

Contains a list of all variables which are defined at file scope in the current module.  This includes external and static symbols.  Choose File Variables from the Data menu to open this window.

Watches

The Watches windows allows you to add and delete variables and expressions.  In other windows you can choose Watch from the pop-up menu.  This will open the watches window add the text which is selected in another window to the watches window.  You can use New from the pop-up menu to add any expression to the Watches window.  Once entered, you can choose Edit from the pop-up menu to edit the expressions or typecast the variables.

Variable

This is another instance of a Watches window.  A variable window is created when you select a variable or expression in a window and use Inspect from the pop-up menu.

structs (classes) (unions)

Structures may be opened and closed by clicking on the button at the left.  When you open a structure or class, one line is added to the window for each field of the structure.  These new lines are indented.  If you click on the button again, the structure is closed and the window is returned to its original state.

arrays

Like structs, arrays may be opened and closed.  When you open an array, one line is added to the window for each element of the array.  The debugger will display at most 1000 elements of an array.  If it contains more you can use Type/Array...  to open different ranges.  Multi dimensional arrays are treated like an array of arrays.   When you open the first dimension, the lines that are added will also be arrays which you can open.

pointers

When the variable is a pointer, you can click on the button and the debugger will follow the pointer and change the line to represent the item which is the result of the pointer reference.  For example, if you have a pointer to an integer and click on the button, the integer value will be displayed.  The button then changes to indicate so that you can undo the operation by clicking on it again.
In the case of pointers to pointers, clicking on the button will follow the pointers one level each time you click on the button until a non-pointer value is reached.  Clicking on the button at this point will undo take you back to the original state.  When the pointer points to a struct, the structure will automatically be opened when you click on the button.  If a pointer is really an array, you can use Type/Array...  from the pop-up menu to open it as an array.

Modify...

Modify the value of the selected item. 

Break

Set a breakpoint so that execution stops when the selected item's value changes.  This is the same as setting a breakpoint on the object.  See Breakpoints.

--------

Inspect

Open a new Variable window containing the selected item.  If the item is a compound object (array, class, or structure), it will be opened automatically. 

Watch

Add the selected item to the Watch window. 

Show/Raw Memory

Display raw memory at the address of this variable.  This lets you examine the actual binary representation of a variable.  

Show/Pointer Memory

Display the memory that the item points to.  This is useful when you have a pointer to a block of memory that does not have a type associated with it. 

Show/Pointer Code

Display the code that the variable points to.  If the item being displayed is a pointer to function, you can use this menu item to see the definition of that function. 

Show/Type

Display the type of the variable in an information message box.  Select "OK" to dismiss the information box and resume debugging.

--------

Edit

Open a dialog box in which you can edit an expression in the Watch window.  This is useful for typecasting variables or evaluating expressions.  See Open Watcom Debugger Expression Handling.  

New

Add a new variable or expression to the window.  You will be prompted for the expression to add. 

Delete

Delete the selected item from the window.

--------

FieldOnTop

Display the value of this member at the top of the structure/class.  You can selectively add or remove items from the list that is displayed "on top".  For example, say you have a struct Point displayed as:
     
     [-] point
       x      10
       y      30
       other  "asdf"

If you toggle FieldOnTop for both x and y then point would be displayed like this:

     
     [-] point { 10, 30 }
       x      10
       y      30
       other  "asdf"

Furthermore, if you closed the struct (or pointer to struct) then you would see:

     
     [+] point { 10, 30 }

This carries to structs containing structs (and so on) as shown in the following struct containing two Point structures.

     
     [-] rect { { 10, 10 }, { 30, 30 } }
       top_left { 10, 10 }
       bot_right { 30, 30 }

If you close it, then you will see:

     
     [+] rect { { 10, 10 }, { 30, 30 } }

Class/Show Functions

Display function members of this object.  If this option is not selected, no functions are displayed.  This option works in conjunction with other Class selections to display "Inherited", "Generated", "Private" and "Protected" functions. 

Class/Show Inherited

Display inherited members of this object.  To see inherited functions, you must also select Class/Show Functions.  

Class/Show Generated

Display compiled-generated members of this object.  To see generated functions, you must also select Class/Show Functions. 

Class/Show Private

Display private members of this object.  To see private functions, you must also select Class/Show Functions.  

Class/Show Protected

Display protected members of this object.  To see protected functions, you must also select Class/Show Functions.  

Class/Show Static

Display static members of this object. 

Type/All Hex

This item is only available when the display item is an array or a fake array (a pointer changed to display as if it were an array using Type/Array ).  Change the value of all sibling array entries to be displayed in hexadecimal.  

Type/Hex

Change the value to be displayed in hexadecimal. 

Type/All Decimal

This item is only available when the display item is an array or a fake array (a pointer changed to display as if it were an array using Type/Array ).  Change the value of all sibling array entries to be displayed in decimal.  

Type/Decimal

Change the value to be displayed in decimal. 

Type/Character

Change the value to be displayed as a single character constant.  This useful when you have a one byte variable that really contains a character.  The debugger will often display it as an integer by default. 

Type/String

The debugger automatically detects pointers to strings in the variable windows and displays the string rather than the raw pointer value.  In the string is not null terminated, contains non-printable characters, or is not typed as a pointer to 'char', this mechanism will not work.  Type/String overrides the automatic string detecting and displays the pointer as a string regardless of its type. 

Type/Pointer

This will undo the effects of Type/String or Type/Array.  It will also let you see the raw pointer value when the debugger has automatically displayed a pointer to char as a string. 

Type/Array...

Use this menu item to display a pointer as if it were an array, or to display ranges of an array's elements.  You will be prompted for the first and last element to display. 

Options/Whole Expression

Select this option to show the whole expression used to access fields and array elements instead of just the element number or field name itself. 

Options/Expand 'this'

Do not display members of the 'this' pointer as if they were local variables declared within the member function.

The Memory and Stack Windows

Modify

Modify the value at the selected address.  You will be prompted for a new value.  You should enter the value in the same radix as the window is currently displaying.  You are not limited to typing constants values.  You can enter an arbitrary expression to be used for the new value. 

Break on Write

Set a breakpoint to stop execution when the selected value changes.  See Breakpoints.

--------

Near Follow

Displays the memory that the selected memory points to, treating it as a near pointer.  The new offset to be displayed will be xxxx where xxxx is the word under the cursor.  DGROUP will be used as the segment if it can be located.  The program's initial stack segment will be used otherwise.  When you are debugging a 16-bit or 32-bit application, the appropriate word size is used. 

Far Follow

Displays the memory that the selected memory points to, treating it as a far pointer.  The new address to be displayed will be the the segment and offset found at the cursor location.  Note that pointers are stored in memory with the offset value first and the segment value second. 

Segment Follow

Display the segment that the selected memory points to, treating it as a segment selector.  The new address to be displayed will be xxxx:0 where xxxx is the two byte word under the cursor. 

Cursor Follow

Make the selected position the new starting address in the window.  This means that the first byte in the memory window will become the byte that the cursor was pointing to.  This is useful for navigating through an array when no debugging information is available. 

Repeat

Repeat the previous Follow operation.  The new address that will be used is at the same offset relative to the beginning of the window as it was in the original Follow operation.  Repeating a pointer or segment follow is a linked list traversal.   Repeating a Cursor Follow operation advances to the next element in an array. 

Previous

Back out of a Follow or Repeat operation.  This will display the memory window you were previously viewing.  Essentially, this undoes a Follow operation.  You can back all the way out to the first memory location you were examining. 

Home

Undo all Follow and Repeat operations.  This will take you back to the very first location window you were examining.   It is equivalent to using Previous repeatedly.

--------

Left

Scroll the window backward through memory by the size of the displayed memory items. 

Right

Scroll the window forward through memory by the size of the displayed memory items.

--------

Address

Position the window at a new address.  You will be prompted to type in a new address.  You can type an arbitrary expression.  See Open Watcom Debugger Expression Handling.  If you type the name of a variable, the address of that variable is used.  If the expression you type does not contain a segment value DGROUP will be used as the segment if it can be located.  The program's initial stack segment will be used otherwise. 

Assembly

Position the assembly window to the address of the memory under the cursor.  This is useful if you have incorrectly displayed a pointer as data and wish to look at the code instead. 

Type/Byte

Display as hexadecimal bytes. 

Type/Word

Display as hexadecimal 16-bit words. 

Type/Dword

Display as hexadecimal 32-bit words. 

Type/Qword

Display as hexadecimal 64-bit words. 

Type/Char

Display as signed 8-bit integers. 

Type/Short

Display as signed 16-bit integers. 

Type/Long

Display as signed 32-bit integers. 

Type/__int64

Display as signed 64-bit integers. 

Type/Unsigned Char

Display as unsigned 8-bit integers. 

Type/Unsigned Short

Display as unsigned 16-bit integers. 

Type/Unsigned Long

Display as unsigned 32-bit integers. 

Type/Unsigned __int64

Display as unsigned 64-bit integers. 

Type/0:16 Pointer

Display as 16-bit near pointers (16-bit offset). 

Type/16:16 Pointer

Display as 32-bit far pointers (16-bit segment, 16-bit offset). 

Type/0:32 Pointer

Display as 32-bit near pointers (32-bit offset). 

Type/16:32 Pointer

Display as 48-bit far pointers (16-bit segment, 32-bit offset). 

Type/Float

Display as 32-bit floating-point values. 

Type/Double

Display as 64-bit floating-point values. 

Type/Extended Float

Display as 80-bit floating-point values.

Following Linked Lists

Traversing Arrays

Breakpoints

• Break-on-execute refers to the traditional breakpoint
• Break-on-write refers to the traditional tracepoint
• A traditional watchpoint is a break-on-execute or break-on-write that is coupled with a condition

• the location in the program where the breakpoint occurs
• the condition under which the breakpoint is triggered
• the action that takes place when the breakpoint triggers

• program execution is stopped (a breakpoint)
• an expression is executed (code splice)
• a group of breakpoints is enabled or disabled

How to Use Breakpoints during a Debugging Session

• Setting Simple Breakpoints
• Clearing, Disabling, and Enabling Breakpoints

Setting Simple Breakpoints

• enabled
• disabled
• cleared (non-existent)

Note:

Some lines in your program do not contain any machine code to execute and therefore, you cannot set a breakpoint on them.   The compiler does not generate machine code for comments and some C constructs.  All lines of code in your program that can have a breakpoint on them have a button to the left of the source line.  You can click on them to change their current status.

Clearing, Disabling, and Enabling Breakpoints

• enabled
• disabled
• cleared (non-existent)

The Break Menu

Toggle

Change the status of the breakpoint at the current line in the source or assembly window.  The status alternates between enabled, disabled and cleared.  The button on the source or assembly line will be updated to reflect the status of the breakpoint.

Note:

Disabled and cleared breakpoints are not the same.  If you disable a breakpoint, you can re-enable it and retain the information about the breakpoint (i.e., conditions, countdown, and actions).  When you clear a breakpoint, you lose all information about the breakpoint.  If you disable a breakpoint, and press F9 twice to enable, you will lose the information about the breakpoint because you cleared it before you re-enabled it.  To enable a disabled breakpoint without losing the breakpoint information, use the Breakpoint Option dialog or the Breakpoint window.

At Cursor

Set a breakpoint at the current line in the source or assembly window.  If the current line does not contain any executable code, the breakpoint is set on the closest preceding line of code that does contain executable code.  When you choose At Cursor, the Breakpoint dialog appears. 

New

This allows you to create any type of breakpoint using a dialog.  You must specify the address in the dialog. 

On Image Load...

Cause program execution to stop when an executable image (DLL) is dynamically loaded.  The menu item is only available when debugging an Win32 or OS/2 executable.  A dialogue will appear allowing you to add and delete image names from the list.  You only need to type a substring of the actual image name.  You can identify the file "C:\PATH\IMAGE.DLL" with any substring, for example "IMAGE", "IMAGE.DLL" or "ATH\IMAGE.DLL".  Case is ignored in the image names. 

On Debug Message

When checked, cause program execution to stop whenever Windows 3.1, Windows NT, or Windows 95 prints a debug string.  A debug string is printed whenever the application or debug Kernel calls the OutputDebugString function.  This option is toggled each time it is selected from the Break menu. 

View All

Open the breakpoint window.  This window will show a list of all breakpoints.  You can use the window to create, delete and modify breakpoints. 

Clear All

Clear all breakpoints. 

Disable All

Disable all breakpoints, but do not delete them. 

Enable All

Enable all breakpoints that are disabled. 

Save

Save all breakpoint information to a file.  This is useful when you are creating complicated breakpoints.  You can save and restore them in a later debugging session. 

Restore

Restore a set of breakpoints that were saved by using Save from the Break menu.

The Break Window

Modify

Change the definition of the selected breakpoint.  The Breakpoint dialog will appear. 

New

Add a new breakpoint.  An empty Breakpoint dialog will appear.  You must specify the address of the new Breakpoint.   Refer to the section entitled The Breakpoint Dialog for a description of the items in the which appear in the dialog. 

Delete

Delete the selected breakpoint. 

Enable

Enable the selected breakpoint. 

Disable

Disable the selected breakpoint. 

Source

Display the source code associated with the break point.  This operation only makes sense for break-on-execute breakpoints.  

Assembly

Display the assembly code associated with the selected line.  This operation only makes sense for break-on-execute breakpoints.

The Breakpoint Dialog

Address

This edit field displays the address tag associated with the selected breakpoint.
When you choose At Cursor this field already contains an address that describes the line of code that the cursor is on.  The format of the address tag is symbol+offset where symbol is the name of the nearest function and offset is distance in bytes past that symbol where the break point is defined.  It is normally best NOT to edit this field.  To change the line of source code, leave the dialog, move the cursor to where you want the breakpoint, and use the At Cursor command again.

When you choose New, this field is empty.  You can type any valid address expression in this field.   It can be the name of a function, global variable.  Refer to the section entitled Open Watcom Debugger Expression Handling for more information about address expressions.  In the dialog, you can click the Symbols...  button as a shortcut.   You can type a partial symbol name like foo and the Symbol button will show you a list of symbols that start with foo.  You can then choose one of these symbols by clicking on it or hitting ENTER.  Note that the first time you use the Symbols...  in a debugging session, it will take a while as the debugger sorts the symbol table for the program.

Note:

Be careful when using local (stack) variables for a break-on-write breakpoint.  As soon as execution leaves the scope of the variable, the memory will change at random since the variable does not really exist any more and the memory will be used for other variables.  Also, if execution enters that variable's scope again, the variable may not have the same memory address.

Condition

Use this field to enter a conditions that must be met before a breakpoint will trigger.  The condition can be an arbitrary debugger expression.  These include statements in the language you are debugging.  A valid example for the C language is i == 1.

Break on Execute

Check this field to create a break-on-execute breakpoints.  If you choose Execute, be sure that the address field contains a code address (function name or code line number) and not a variable address.  Variable are never executed.  If the address field names a variable, the breakpoint will never trigger.

Break on 1 Byte/2 Bytes/4 Bytes/8 Bytes...

Check one of these fields to create break-on-write breakpoints.  If you choose one of these options, be sure that the Address field contains a variable address and not a code address.  A code address will never be written to, so the breakpoint will never trigger.  The size of the memory location is defined by the checkbox you use as follows:

1 Byte

The breakpoint will trigger only when the first byte of the memory address is written to.

2 Bytes

The breakpoint will trigger when either of the first two bytes at the memory address are written to.

4 Bytes

The breakpoint will trigger if any of the first four bytes of the memory address are written to.

8 Bytes

The breakpoint will trigger if any of the first eight bytes of the memory address are written to.  This option is only supported by certain trap files and will be grayed out if the selected trap file does not support it.

Note:

In older versions of the debugger and traps, the break on write feature is really a break on change:  the debugger will only stop execution if the breakpoint is hit and the value of the watched data has been changed.  For the current version of the debugger this is the still the default behaviour but can be modified.  Refer to The Options Dialog to change the breakpoint behaviour to true break-on-write.

Countdown

Use this field to enter the number of times an address must be hit before the breakpoint triggers.  Every time the breakpoint conditions are met, the countdown decreases by one.  The breakpoint will trigger only after the countdown is at zero.   Once the countdown reaches zero, the breakpoint will trigger each time the conditions are met.  If you have also set a condition, the countdown will only decrease by one when the condition is true.

Total Hits

This field displays the total number of times an address has been hit.  This includes the times the breakpoint does not trigger because a condition failed or the countdown has not yet hit zero.

Reset

Click on this button to reset the Total Hits field to zero.

Execute when Hit

Use this field to enter a debugger command.  When the breakpoint is triggered, the debugger will execute this command.   You can use this field to execute arbitrary C statements, change a variable or register, or even set other breakpoints.   For a more detailed description of commands that can be entered in this field, refer to the section called Debugger Commands.   If you want to use this field to execute a statement in the language you are debugging, you need to use a DO command in front of the statement.  For example, you could enter DO i = 10 to have the value of 10 assigned to i each time the breakpoint triggered.

Resume

Check this field if you want the program to resume execution after the Execute when Hit command has been completed.   This capability can be used to patch your code.

Enabled

This field displays the current status of the breakpoint.  If it is checked, the breakpoint is enabled.  If it is unchecked, the breakpoint is disabled.

Value

For Break-on-Execute breakpoints this field displays the source line or the assembly line at which the break point is defined.   For Break-on-Write breakpoints, this field displays the memory contents.

Clear

Click on the clear button to clear the breakpoint and close the dialog.

Assembly Level Debugging

• The CPU Register Window
• The Assembly Window
• The I/O Ports Window
• The FPU Registers Window
• The MMX Registers Window
• The XMM Registers Window

The CPU Register Window

Modify

Change the value of the selected register. 

Inspect

Open a Memory window displaying the memory contents of the address specified by the register.  If a segment register is selected, memory at offset 0 in the segment will be displayed. 

Hex

Toggles the register window display format between hexadecimal and decimal. 

Extended

Displays the Extended 386 register set.  This menu item sets options on a per-window basis, overriding the global settings.   When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The Assembly Window

Inspect

When you selecting a memory address, register or operand and use Inspect, the debugger opens a Memory Window displaying the selected memory address. 

Break

If a code address is selected this command will set a break-on-execute breakpoint at the selected code address.  If a variable address is selected, this command will set a break-on-write breakpoint on the selected address.  this does not set a break at the current line.  Use Toggle from the Break menu or At Cursor from the Break menu to set a breakpoint at the current line. 

Enter Function

Resume program execution until the selected function is executed. 

Show/Source

Display the source code associated with the selected assembly line. 

Show/Functions

Show the list of all functions defined in the current module. 

Show/Address

Reposition the window at a new address.  You will be prompted for an expression.  Normally you would type a function name but you can type any expression that resolves to a code address.  For example, you might type the name of a variable that contains a pointer to a function.  See Open Watcom Debugger Expression Handling.  

Show/Module...

Show a different module.  You will be prompted for its name in a dialog.  As a shortcut, you can type the beginning of a module name and click the Module...  button.  This will display a list of all modules that start with the text you typed. 

Home

Reposition the window to the currently executing location.  The cursor will move to the next line of the program to be executed. 

No source

Toggle the Assembly window display between only assembly code and assembly code intermixed with source lines.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.  

Hex

Toggle the Assembly window display between hexadecimal and decimal.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The I/O Ports Window

Modify

Change the selected item.  You can change either the value field or the address field.  This does not write the value back to the port.  You must choose Write to write to the port. 

New

Add a new line to the window.  You can have several I/O ports displayed at once. 

Delete

Delete the selected line from the window. 

Read

Read the displayed value from the port. 

Write

Write the displayed value to the port. 

Type

Change the display type of the value.  The size of this type determines how much is read from or written to the I/O port.

The FPU Registers Window

Modify

Change the value of the selected register, or bit.  You will be prompted for a new value, unless you are modifying a bit.  A bit will toggle between 0 and 1. 

Hex

Toggle the FPU window display between hexadecimal and floating-point display.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.

The MMX Registers Window

Modify

Change the value of the selected register component.  You will be prompted for a new value.  The same action can be performed by pressing ENTER or double-clicking as described above. 

Inspect

This item has no function in the MMX register window. 

Hex

Toggle the MMX register window display between hexadecimal and floating-point display.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.  

Signed

Toggle the display of the contents of the MMX registers as signed or unsigned quantities.  When "signed" is enabled, each byte, word, doubleword or quadword is displayed as a signed quantity.  When "signed" is disabled, each byte, word, doubleword or quadword is displayed as an unsigned quantity. 

Byte

Display the contents of the MMX registers as a series of 8 bytes. 

Word

Display the contents of the MMX registers as a series of 4 words. 

DWord

Display the contents of the MMX registers as a series of 2 doublewords. 

QWord

Display the contents of the MMX registers as single quadwords. 

Float

Display the contents of the MMX registers as a series of 2 IEEE single-precision floating-point values.

The XMM Registers Window

Modify

Change the value of the selected register component.  You will be prompted for a new value.  The same action can be performed by pressing ENTER or double-clicking as described above. 

Inspect

This item has no function in the XMM register window. 

Hex

Toggle the XMM register window display between hexadecimal and floating-point display.  This menu item sets options on a per-window basis, overriding the global settings.  When you use the menu item to change these settings, they will not be saved between debugging sessions.  To change an option permanently, see The Window Options Dialog.  

Signed

Toggle the display of the contents of the XMM registers as signed or unsigned quantities.  When "signed" is enabled, each byte, word, doubleword or quadword is displayed as a signed quantity.  When "signed" is disabled, each byte, word, doubleword or quadword is displayed as an unsigned quantity. 

Byte

Display the contents of the XMM registers as a series of 16 bytes. 

Word

Display the contents of the XMM registers as a series of 8 words. 

DWord

Display the contents of the XMM registers as a series of 4 doublewords. 

QWord

Display the contents of the XMM registers as a series of 2 quadwords. 

Float

Display the contents of the XMM registers as a series of 4 single-precision floating-point values. 

Double

Display the contents of the XMM registers as a series of 2 double-precision floating-point values.

Remote Debugging

The Debugger

This is the portion of the debugger that contains the user interface.  It is the largest part of the debugger.  Its name is either WD.EXE, WDW.EXE or WDC.EXE

The Debug Kernel

The debugger interprets your requests and sends low level requests to the debug kernel.  It is a small executable that is dynamically loaded by the debugger or a remote debug server and used to control your application.  It can be called STD.TRP, STD.DLL, RSI.TRP or PLS.TRP

Remote Trap Files-

These are versions of the debug kernel file that take requests and send them across a communications link to a remote debug server.  You choose a trap file using the debugger's "trap" option.  See Common Switches.   Trap files have a 3 letter file name that represents the name of the communications layer being used.  The file extension is TRP or DLL.

Remote Debug Servers-

These executable files receive requests from a communications link and pass them to a debug kernel.  Remote debug server names all start with ???SERV.  The first 3 letters represent the communication layer being used and correspond to the trap file that is used on the other side of the link.

1. Connect the two machines with a parallel cable.  See Wiring For Remote Debugging.
2. Start the remote debug server (PARSERV) on one machine.
3. Start the debugger with the option "/trap=PAR" on the other machine.  This causes the debugger to load the remote trap file (PAR).  This will communicate across the remote link to PARSERV.EXE, which will in turn communicate with the debug kernel (STD) in order to debug the application.

NOV

This link uses Novell's SPX layer for communication.  Supported under DOS, OS/2, Windows 3.x, Windows NT/2000/XP and NetWare.

NET

This link uses NetBIOS to communicate.  If your network software supports NetBIOS, you can use this link.  Supported under DOS, OS/2, Windows 3.x, and NetWare.

PAR

This link supports communication using the parallel or printer port.  Several different cable configurations are supported.   See Wiring For Remote Debugging.  Supported under DOS, OS/2, Windows 3.x, Windows 9x, Windows NT/2000/XP, NetWare, Linux and QNX 4.

SER

This link uses a serial port to communicate.  Rates of up to 115K BAUD are supported.  See Wiring For Remote Debugging.   Supported under DOS, OS/2, Windows 9x, Windows NT/2000/XP and QNX 4.

WIN

This link will communicate between two Windows DOS boxes.  Supported under Windows 3.x and Windows 9x (for DOS applications only).

NMP

This link will use Named Pipes to communicate internally between OS/2 sessions.  OS/2, DOS and Win-OS/2 sessions are supported.  If your network supports Named Pipes, and you have at least one OS/2 machine on the network, you can communicate between OS/2, DOS and Windows 3.x machines on the network.  Supported under OS/2 (DOS, OS/2 and Windows 3.x applications).

VDM

This link is a subset of the NMP link.  It is supported under OS/2 and Windows NT.  The application being debugged must be a DOS or seamless Win-OS/2 application.  Supported under OS/2 and Windows NT (DOS, OS/2 and Windows 3.x applications).

TCP

This link will use TCP/IP to communicate internally or over a network between sessions.  Supported under DOS, OS/2, Windows 9x, Windows NT/2000/XP, Linux and QNX.

Link Descriptions

• NOV (Novell SPX)
• NET (NetBIOS)
• PAR (Parallel)
• SER (Serial)
• WIN (Windows 3.x/9x Virtual DOS Machine)
• NMP (Named Pipes)
• VDM (Virtual DOS Machine)
• TCP/IP (Internet Packets)

NOV (Novell SPX)

NET (NetBIOS)

PAR (Parallel)

CW

Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging CauseWay 32-bit DOS Extender Applications for more information on debugging applications that use the CauseWay DOS extender.

RSI

Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging DOS/4G(W) 32-bit DOS Extender Applications for more information on debugging applications that use the DOS/4GW DOS extender.

PLS

One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging Phar Lap 32-bit DOS Extender Applications for more information on debugging applications that use the Phar Lap DOS extender.

SER (Serial)

QNX 4 Note:

Under QNX 4, a node id may be specified followed by a comma if the serial port is not located on the current node.  The command "serserv 3,1.9600" would use the device //3/dev/ser1 at a BAUD rate of 9600.  Alternatively, you can specify a device such as /dev/foobar.  To specify the maximum line speed, you can specify something like /dev/foobar.56.   Of course, you can also include a node id such as //5/dev/foobar.
     
     A>serserv //3/dev/ser2.9600
     B>wd /tr=ser;//5/dev/ser2.9600 app

CW

Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging CauseWay 32-bit DOS Extender Applications for more information on debugging applications that use the CauseWay DOS extender.

RSI

Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging DOS/4G(W) 32-bit DOS Extender Applications for more information on debugging applications that use the DOS/4GW DOS extender.

PLS

One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging Phar Lap 32-bit DOS Extender Applications for more information on debugging applications that use the Phar Lap DOS extender.

WIN (Windows 3.x/9x Virtual DOS Machine)

CW

Both "CWSTUB.EXE" and the loader help file "CWHELP.EXE" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging CauseWay 32-bit DOS Extender Applications for more information on debugging applications that use the CauseWay DOS extender.

RSI

Both "DOS4GW.EXE" and the loader help file "RSIHELP.EXP" must also be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging DOS/4G(W) 32-bit DOS Extender Applications for more information on debugging applications that use the DOS/4GW DOS extender.

PLS

One or more of "RUN386.EXE" (or "TNT.EXE"), "DBGLIB.REX", "PLSHELP.EXP", and "PEDHELP.EXP" must be located in one of the directories listed in the DOS PATH environment variable.  See the section entitled Debugging Phar Lap 32-bit DOS Extender Applications for more information on debugging applications that use the Phar Lap DOS extender.

NMP (Named Pipes)

VDM (Virtual DOS Machine)

1. It does not support network debugging.
2. Under OS/2, the debugger (user interface) must run in an OS/2 (not a DOS) session.  The debugger may also be started under Windows NT but not Windows 95 since it does not support named pipes.
3. Under OS/2, the remote debug server must run in a seamless Win-OS/2 or a DOS session.
4. Under Windows NT, the remote debug server will be run in a Windows NT Virtual DOS Machine.
5. Under Windows 95, the remote debug server can be started but since Windows 95 does not support named pipes it will not work properly.  See the section entitled WIN (Windows 3.x/9x Virtual DOS Machine) for an alternative.
6. If you are running VDMSERVW under Win-OS/2, it must be run as a seamless Windows session.  This is due to the fact that full screen Win-OS/2 sessions may not get any processor time when they are not in the foreground.

TCP/IP (Internet Packets)

OS/2

d:\TCPIP\ETC\SERVICES depending on the drive where TCP/IP is installed

Linux and QNX

/etc/services

Windows 9x

d:\windows\SERVICES depending on the drive and directory where Windows 95 is installed

Windows NT

d:\WINNT\SYSTEM32\DRIVERS\ETC\SERVICES depending on the drive where Windows NT is installed

Specifying Files on Remote and Local Machines

@L

The "@L" prefix is used to indicate that the file resides on the local machine (the one on which the debugger is running).
     
     @L[d:][path]filename[.ext]

When "[path]" is not specified, the current directory of the specified drive of the local machine is assumed.  When "[d:]" is not specified, the current drive of the local machine is assumed.

Example:

     @LOUTPUT.LOG
     @LD:\CMDS
     @LD:\CMDS\DATA.TMP

@R

The "@R" prefix is used to indicate that the file resides on the remote machine.
     
     @R[d:][path]filename[.ext]

When "[path]" is not specified, the current directory of the specified drive of the remote machine is assumed.  When "[d:]" is not specified, the current drive of the remote machine is assumed.

Example:

     @RMYAPPL.DAT
     @RD:\PROGRAMS\EXE\MYAPPL.LNK
     @R\PROGRAMS\SRC
     @R\PROGRAMS\SRC\UILIB.C

1. In the each form, the omission of "[d:]" indicates the current drive.
   
        
        [path]filename[.ext]
        @L[path]filename[.ext]
        @R[path]filename[.ext]
2. In the each form, the omission of "[path]" indicates the current path of the specified drive.
   
        
        [d:]filename[.ext]
        @L[d:]filename[.ext]
        @R[d:]filename[.ext]
   
   Observe that if "[d:]" is omitted also then the following forms are obtained:
   
        
        filename[.ext]
        @Lfilename[.ext]
        @Rfilename[.ext]
3. The special drive prefixes "@L" and "@R" cannot be used in your own application to reference files on two different machines.  These prefixes are recognized by the Open Watcom Debugger only.  Should the situation arise where one of your filenames begins with the same prefix ("@L", "@l", "@R" or "@r") then "@@" can be used.  For example, if your wish to refer to the file on disk called "@link@" then you could specify "@@link@".  Note that ".\@link@" would also suffice.

Interrupting a Running Program

DOS

Windows 3.x

Windows NT, Windows 95

Note:

Under Windows 95, it is very difficult to interrupt a program that is in an infinite loop or spending most of its time in system API's.  Under Windows 95, you can only interrupt a program that is responding to messages (or looping in its own thread code).  If your program is an infinite loop, interrupting the program will likely fail.  The only option in this case is to terminate the program.
This is not an issue under Windows NT which has a superior debug API.

OS/2

NetWare

Linux

QNX

Operating System Specifics

DOS Extender debugging

See the section entitled Debugging 32-bit DOS Extender Applications.

NLM debugging

See the section entitled Debugging a Novell NLM.

Graphics programs

See the section entitled Debugging Graphics Applications.

Windows 3.x debugging

See the section entitled Debugging Windows 3.x Applications.

DLL debugging

See the section entitled Debugging Dynamic Link Libraries.

Disabling 386/486 debug registers

See the section entitled Disabling Use of 386/486 Debug Registers.

Linux debugging

See the section entitled Debugging Under Linux.

QNX debugging

See the section entitled Debugging Under QNX.

Debugging 32-bit DOS Extender Applications

CauseWay DOS Extender

a public domain DOS extender included in the Open Watcom C/C++(32) and Open Watcom FORTRAN 77/32 packages.  Note that this DOS extender is largely compatible with DOS/4GW and can often be used interchangeably.

DOS/4GW

a DOS extender from Tenberry Software, Inc.  DOS/4GW is a subset of Tenberry Software's DOS/4G product.  DOS/4GW is customized for use with Open Watcom C/C++(32) and Open Watcom FORTRAN 77/32 and is included in these packages.

386|DOS-Extender

(version 2.2d or later) a DOS extender from Phar Lap Software, Inc.

Debugging CauseWay 32-bit DOS Extender Applications

Debugging DOS/4G(W) 32-bit DOS Extender Applications

Debugging Phar Lap 32-bit DOS Extender Applications

Debugging a Novell NLM

Debugging Graphics Applications

1. If you only have one monitor attached to your system, use the Swap option.  The Swap option specifies that the application's screen memory and the debugger's screen memory are to be swapped back and forth using a single page.
2. If you have two monitors attached to your system then the Two and Monochrome options should be used.  The Two option specifies that a second monitor is connected to the system.  Note that if the monitor type ( Monochrome, Color, Colour, Ega43, Vga50) is not specified then the monitor that is not currently being used is selected for the debugger's screen.  If you specify Monochrome then the monochrome monitor will be used for the debugger's screen.
3. If you are debugging the graphics application using a second personal computer and the remote debugging feature of the Open Watcom Debugger then the choice of display and operation mode for the Open Watcom Debugger is irrelevant.  If one system is equipped with a graphics display and the other with a monochrome display then you will undoubtedly use the system equipped with the monochrome display to run the Open Watcom Debugger.

Debugging Windows 3.x Applications

1. If you are trying to debug an applications that uses DDE you should not use the GUI debugger.
2. Do not try to use the GUI debugger to debug system modal dialogs.
3. If you hit a break-point in a dialog callback procedure or in your window procedure when it is receiving certain events (e.g., WM_MENUSELECT), the GUI debugger will lock input to itself.  When this happens, you will not be able to switch away from the debugger, and no other application will repaint themselves.  When this happens, pop-up menus will not draw correctly and you will have to use the Action menu instead.  You should not try to quit the debugger when it is in this state.
4. Do not try to use either of the Windows debuggers in a seamless Win-OS/2 session.

Debugging Dynamic Link Libraries

1. You cannot debug your DLL initialization code.  This is the first routine that the operating system runs when it loads the DLL.  This is not normally a problem, since most DLLs do not do much in the way of initialization.
2. When a DLL is loaded dynamically, its debugging information may not be available immediately.  Try tracing a few instructions and it will appear.
3. If you restart an application, you will lose any break points that you had set in dynamically loaded DLLs.  You need to trace back over the call to LoadModule or DOSLoadModule and re-set these break points.

Disabling Use of 386/486 Debug Registers

Debugging Under Linux

Search Order for Open Watcom Debugger Support Files under Linux

1. Open Watcom Debugger command files (files with the ".dbg" suffix).
2. Open Watcom Debugger trap files (files with the ".trp" suffix).
3. Open Watcom Debugger parser files (files with the ".prs" suffix).
4. Open Watcom Debugger help files (files with the ".hlp" suffix).
5. Open Watcom Debugger symbolic debugging information files (files with the ".sym" suffix).

1. the current directory,
2. the paths listed in the WD_PATH environment variable,
3. the path listed in the HOME environment variable
4. the directory where Open Watcom Debugger was started from
5. "../wd" directory relative to the directory where Open Watcom Debugger was started from, and, finally,
6. the "/opt/watcom/wd" directory.

Debugging Under QNX

Debugging Under QNX Using the Postmortem Dump Facility

dumper

is the program name for the QNX postmortem dump program.

-d path

The name of the directory in which postmortem dumps are written.  If not specified, the default is the user's home directory.

-p pid

Save a dump file for this process if it terminates for any reason.  Do not save a dump file for any other process.

&

must be specified so that the shell is rejoined.

wd

is the program name for the Open Watcom Debugger.

-TRap=pmd[

i] must be specified when debugging an application that has terminated and produced a postmortem dump.  The optional ";i" is specified when the modification date of the original program file does not match the information contained in the dumper file.  It indicates that the symbolic debugging information in the program file may be out-of-date.  It instructs the Open Watcom Debugger to ignore the date mismatch.  Depending on the shell that you are using, it may be necessary to place the option specification in quotation marks if you include the optional ";i".
Example:

     $ wd "-trap=pmd;i" myapp

sym_file

is an optional symbolic information file specification.  The specification must be preceded by a colon (":").   When specifying a symbol file name, a path such as "//5/etc/" may be included.  For QNX, the default file suffix of the symbol file is ".sym".

file_spec

is the file name of the dumper file to be loaded into memory.  When specifying a file name, a path such as "//5/etc/" may be included.  If a path is omitted, the Open Watcom Debugger will first attempt to locate the file in the current directory and, if not successful, attempt to locate the file in the default dumper directory:  /usr/dumps.

1. Task execution cannot be restarted using Go from the Run menu.
2. A register can be modified for the purposes of expression evaluation.  You can choose Go from the Run menu to restore the register contents to their original postmortem state.
3. Memory cannot be modified.
4. Memory outside of regions owned by the program cannot always be examined.
5. I/O ports cannot be examined.

Search Order for Open Watcom Debugger Support Files under QNX

1. Open Watcom Debugger command files (files with the ".dbg" suffix).
2. Open Watcom Debugger trap files (files with the ".trp" suffix).
3. Open Watcom Debugger parser files (files with the ".prs" suffix).
4. Open Watcom Debugger help files (files with the ".hlp" suffix).
5. Open Watcom Debugger symbolic debugging information files (files with the ".sym" suffix).

1. the current directory,
2. the paths listed in the WD_PATH environment variable,
3. the path listed in the HOME environment variable, and, finally,
4. the "/usr/watcom/wd" directory.

Open Watcom Debugger Expression Handling

General Rules of Expression Handling

Language Independent Variables and Constants

Symbol Names

Note:

Global and local symbol name debugging information is included in an executable image if you request it of the linker.  However, local symbol information must be present in your object files.  The Open Watcom C, C++ and FORTRAN 77 compilers can include local symbol debugging information in object files by specifying the appropriate compiler option.  See Preparing a Program to be Debugged.

Line Numbers

Note:

Line number debugging information is included in an executable image if you request it of the linker.  However, line number information must be present in your object files.  The Open Watcom C, C++ and FORTRAN 77 compilers can include line number debugging information in object files by specifying the appropriate compiler option.  See Preparing a Program to be Debugged.   You can request line number debugging information when assembling assembly language source files using Open Watcom Assembler The "d1" option must be specified on the command line.

Constants

Integer Constants

Real Constants

(1)

A simple real constant.

(2)

A simple real constant followed by an E or e followed by an optionally signed integer constant.

Note:

The accepted forms of floating-point constants are a subset of that supported by the FORTRAN 77 programming language.  The debugger does not support floating-point constants that begin with a decimal point (e.g., .4352344) or have no decimal point (e.g., 2E6).  However, both forms would be acceptable to a FORTRAN compiler.  Also, the debugger does not support double precision floating-point constants where "D" is used instead of "E" for the exponent part (e.g., 2D6, 2.4352344D6).  All floating-point constants are stored internally by the debugger in double precision format.

Complex Constant (FORTRAN Only)

Character Constant (C Only)

Character String Constant (FORTRAN Only)

Memory References

Predefined Debugger Variables

General Purpose Registers

eax, ax, al, ah, ebx, bx, bl, bh, ecx, cx, cl, ch, edx, dx, dl, dh

Index Registers

esi, si, edi, di

Base Registers

esp, sp, ebp, bp

Instruction Pointer

eip, ip

Segmentation Registers

cs, ds, es, fs, gs, ss

Flags Registers

fl, fl.o, fl.d, fl.i, fl.s, fl.z, fl.a, fl.p, fl.c, efl, efl.o, efl.d, efl.i, efl.s, efl.z, efl.a, efl.p, efl.c

8087 Registers

st0, st1, st2, st3, st4, st5, st6, st7

8087 Control Word

cw, cw.ic, cw.rc, cw.pc, cw.iem, cw.pm, cw.um, cw.om, cw.zm, cw.dm, cw.im

8087 Status Word

sw, sw.b, sw.c3, sw.st, sw.c2, sw.c1, sw.c0, sw.es, sw.sf, sw.pe, sw.ue, sw.oe, sw.ze, sw.de, sw.ie

Miscellaneous Variables

dbg$32, dbg$bottom, dbg$bp, dbg$code, dbg$cpu, dbg$ctid, dbg$data, dbg$etid, dbg$fpu, dbg$ip, dbg$left, dbg$monitor, dbg$ntid, dbg$os, dbg$pid, dbg$psp, dbg$radix, dbg$remote, dbg$right, dbg$sp, dbg$top, dbg$nil, dbg$src, dbg$loaded

Register Aggregates

Operators for the C Grammar

[]

subscripting, substringing

()

function call

.

field selection

->

field selection using a pointer

Assignment Operators for the C Grammar

=

Assignment:  The value on the right is assigned to the object on the left.

+=

Additive assignment:  The value of the object on the left is augmented by the value on the right.

-=

Subtractive assignment:  The value of the object on the left is reduced by the value on the right.

*=

Multiplicative assignment:  The value of the object on the left is multiplied by the value on the right.

/=

Division assignment:  The value of the object on the left is divided by the value on the right.

%=

Modulus assignment:  The object on the left is updated with MOD(left,right).  The result is the remainder when the value of the object on the left is divided by the value on the right.

&=

Bit-wise AND:  The bits in the object on the left are ANDed with the bits of the value on the right.

|=

Bit-wise inclusive OR:  The bits in the object on the left are ORed with the bits of the value on the right.

^=

Bit-wise exclusive OR:  The bits in the object on the left are exclusively ORed with the bits of the value on the right.

<<=

Left shift:  The bits in the object on the left are shifted to the left by the amount of the value on the right.

>>=

Right shift:  The bits in the object on the left are shifted to the right by the amount of the value on the right.  If the object on the left is described as unsigned, the vacated high-order bits are zeroed.  If the object on the left is described as signed, the sign bit is propagated through the vacated high-order bits.  The debugger treats registers as unsigned items.

Logical Operators for the C Grammar

&&

Logical conjunction:  The logical AND of the value on the left and the value on the right is produced.  If either of the values on the left or right is equal to 0 then the result is 0; otherwise the result is 1.

||

Logical inclusive disjunction:  The logical OR of the value on the left and the value on the right is produced.  If either of the values on the left or right is not equal to 0 then the result is 1; otherwise the result is 0.  If the value on the left is not equal to 0 then the expression on the right is not evaluated (this is known as short-circuit expression evaluation).

Bit Operators for the C Grammar

&

Bit-wise AND:  The bits of the value on the left and the value on the right are ANDed.

|

Bit-wise OR:  The bits of the value on the left and the value on the right are ORed.

^

Bit-wise exclusive OR:  The bits of the value on the left and the value on the right are exclusively ORed.

Relational Operators for the C Grammar

==

Equal:  If the value on the left is equal to the value on the right then the result is 1; otherwise the result is 0.

!=

Not equal:  If the value on the left is not equal to the value on the right then the result is 1; otherwise the result is 0.

<

Less than:  If the value on the left is less than the value on the right then the result is 1; otherwise the result is 0.

<=

Less than or equal:  If the value on the left is less than or equal to the value on the right then the result is 1; otherwise the result is 0.

>

Greater than:  If the value on the left is greater than the value on the right then the result is 1; otherwise the result is 0.

>=

Greater than or equal:  If the value on the left is greater than or equal to the value on the right then the result is 1; otherwise the result is 0.

Arithmetic/Logical Shift Operators for the C Grammar

<<

Left shift:  The bits of the value on the left are shifted to the left by the amount described by the value on the right.

>>

Right shift:  The bits of the value on the left are shifted to the right by the amount described by the value on the right.  If the object on the left is described as unsigned, the vacated high-order bits are zeroed.  If the object on the left is described as signed, the sign bit is propagated through the vacated high-order bits.  The debugger treats registers as unsigned items.

Binary Arithmetic Operators for the C Grammar

+

Addition:  The value on the right is added to the value on the left.

_

Subtraction:  The value on the right is subtracted from the value on the left.

*

Multiplication:  The value on the left is multiplied by the value on the right.

/

Division:  The value on the left is divided by the value on the right.

%

Modulus:  The modulus of the value on the left with respect to the value on the right is produced.  The result is the remainder when the value on the left is divided by the value on the right.

Unary Arithmetic Operators for the C Grammar

+

Plus:  The result is the value on the right.

_

Minus:  The result is the negation of the value on the right.

~

Bit-wise complement:  The result is the bit-wise complement of the value on the right.

!

Logical complement:  If the value on the right is equal to 0 then the result is 1; otherwise it is 0.

++

Increment:  Both prefix and postfix operators are supported.  If the object is on the right, it is pre-incremented by 1 (e.g., ++x).  If the object is on the left, it is post-incremented by 1 (e.g., x++).

_ _

Decrement:  Both prefix and postfix operators are supported.  If the object is on the right, it is pre-decremented by 1 (e.g., --x).  If the object is on the left, it is post-decremented by 1 (e.g., x--).

&

Address of:  The result is the address (segment:offset) of the object on the right (e.g., &main).

*

Points:  The result is the value stored at the location addressed by the value on the right (e.g., *(ds:100), *string.loc).   In the absence of typing information, a near pointer is produced.  If the operand does not have a segment specified, the default data segment (DGROUP) is assumed.
     
           (SS:00FE) = FFFF
     var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

%

Value at address:  The result is the value stored at the location addressed by the value on the right (e.g., %(ds:100), %string.loc).  In the absence of typing information, a far pointer is produced.  If the operand does not have a segment specified, the default data segment (DGROUP) is assumed.
     
           (SS:00FE) = FFFF
     var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

Note that this operator is not found in the C or C++ programming languages.

Special Unary Operators for the C Grammar

sizeof unary_expression

Example:

     sizeof tyme
     sizeof (*tyme)

sizeof(type_name)

Example:

     sizeof( struct tm )

(type_name) unary_expression

The type conversion operator (type_name) is used to convert an item from one type to another.  The following describes the syntax of "type_name".
     
     type_name ::= type_spec { [ "near" | "far" | "huge" ] "*" }
     type_spec ::= typedef_name
                      |   "struct" structure_tag
                      |   "union"  union_tag
                      |   "enum"   enum_tag
                      |   scalar_type { scalar_type }
     scalar_type ::= "char" | "int" | "float" | "double"
                      |   "short" | "long" | "signed" | "unsigned"

Example:

     (float) 4
     (int) 3.1415926

[type_name] unary_expression

You can force the debugger to treat a memory reference as a particular type of value by using a type coercion operator.  A type specification is placed inside brackets as shown above.  The basic types are char (character, 8 bits), short (short integer, 16 bits), long (long integer, 32 bits), float (single-precision floating-point, 32 bits), and double (double-precision floating-point, 64 bits).  Unless qualified by the short or long keyword, the int type will be 16 bits in 16-bit applications and 32 bits in 32-bit applications (386, 486 and Pentium systems).  The character, short integer and long integer types may be treated as signed or unsigned items.  The default for the character type is unsigned.  The default for the integer types is signed.
Example:

     [char]                   (default unsigned)
     [signed char]
     [unsigned char]
     [int]                    (default is signed)
     [short]                  (default is signed)
     [short int]             (default is signed)
     [signed short int]
     [long]                   (default is signed)
     [long int]               (default is signed)
     [signed long]
     [unsigned long int]
     [float]
     [double]

Note that it is unnecessary to specify the int keyword when short or long are specified.

?

Existence test:  The "?" unary operator may be used to test for the existence of a symbol.
Example:

     ?id

The result of this expression is 1 if "id" is a symbol known to the debugger and 0 otherwise.  If the symbol does not exist in the current scope then it must be qualified with its module name.  Automatic symbols exist only in the current function.

Binary Address Operator for the C Grammar

:

Memory locations can be referenced by using the binary ":" operator and a combination of constants, register names, and symbol names.  In the Intel 80x86 architecture, a memory reference requires a segment and offset specification.   A memory reference using the ":" operator takes the following form:
     
     segment:offset

The elements segment and offset can be expressions.

Example:

     (ES):(DI+100)
     (SS):(SP-20)

Primary Expression Operators for the C Grammar

[]

Elements of an array can be identified using subscript expressions.  Consider the following 3-dimensional array defined in the "C" language.
Example:

     char *ProcessorType[2][4][2] =
         { { { "Intel 8086",   "Intel 8088"   },
             { "Intel 80186",  "Intel 80188" },
             { "Intel 80286",  "unknown" },
             { "Intel 80386",  "unknown" } },

           { { "NEC V30",       "NEC V20" },
             { "unknown",       "unknown" },
             { "unknown",       "unknown" },
             { "unknown",       "unknown" } } };

This array can be viewed as two layers of rectangular matrices of 4 rows by 2 columns.  The array elements are all pointers to string values.

By using a subscript expression, specific slices of an array can be displayed.  To see only the values of the first layer, the following expression can be issued.

Example:

     processortype[0]

To see only the first row of the first layer, the following expression can be issued.

Example:

     processortype[0][0]

To see the second row of the first layer, the following command can be issued.

Example:

     processortype[0][1]

To see the value of a specific entry in a matrix, all the indices can be specified.

Example:

     processortype[0][0][0]
     processortype[0][0][1]
     processortype[0][1][0]

()

The function call operators appear to the right of a symbol name and identify a function call in an expression.  The parentheses can contain arguments.
Example:

     ClearScreen()
     PosCursor( 10, 20 )
     Line( 15, 1, 30, '-', '+', '-' )

.

The "." operator indicates field selection in a structure.  In the following example, tyme2 is a structure and tm_year is a field in the structure.
Example:

     tyme2.tm_year

->

The "->" operator indicates field selection when using a pointer to a structure.  In the following example, tyme is the pointer and tm_year is a field in the structure to which it points.
Example:

     tyme->tm_year

Operators for the C++ Grammar

Ambiguity Resolution in the C++ Grammar

The "this" Operator for the C++ Grammar

"operator" Functions in the C++ Grammar

Scope Operator "::" for the C++ Grammar

Constructor/Destructor Functions in the C++ Grammar

Operators for the FORTRAN Grammar

()

subscripting, substringing, or function call

.

field selection

->

field selection using a pointer

Assignment Operators for the FORTRAN Grammar

=

Assignment:  The value on the right is assigned to the object on the left.

+=

Additive assignment:  The object on the left is augmented by the value on the right.

-=

Subtractive assignment:  The object on the left is reduced by the value on the right.

*=

Multiplicative assignment:  The object on the left is multiplied by the value on the right.

/=

Division assignment:  The object on the left is divided by the value on the right.

%=

Modulus assignment:  The object on the left is updated with MOD(left,right).  The result is the remainder when the value of the object on the left is divided by the value on the right.

&=

Bit-wise AND:  The bits in the object on the left are ANDed with the bits of the value on the right.

|=

Bit-wise inclusive OR:  The bits in the object on the left are ORed with the bits of the value on the right.

^=

Bit-wise exclusive OR:  The bits in the object on the left are exclusively ORed with the bits of the value on the right.

<<=

Left shift:  The bits in the object on the left are shifted to the left by the amount of the value on the right.

>>=

Right shift:  The bits in the object on the left are shifted to the right by the amount of the value on the right.  If the object on the left is described as unsigned, the vacated high-order bits are zeroed.  If the object on the left is described as signed, the sign bit is propagated through the vacated high-order bits.  The debugger treats registers as unsigned items.

Logical Operators for the FORTRAN Grammar

.EQV.

Logical equivalence:  The logical equivalence of the value on the left and the value on the right is produced.

.NEQV.

Logical non-equivalence:  The logical non-equivalence of the value on the left and the value on the right is produced.

.OR.

Logical inclusive disjunction:  The logical OR of the value on the left and the value on the right is produced.

.AND.

Logical conjunction:  The logical AND of the value on the left and the value on the right is produced.

.NOT.

Logical negation:  The logical complement of the value on the right is produced.

Bit Operators for the FORTRAN Grammar

|

Bit-wise OR:  The bits of the value on the left and the value on the right are ORed.

^

Bit-wise exclusive OR:  The bits of the value on the left and the value on the right are exclusively ORed.

&

Bit-wise AND:  The bits of the value on the left and the value on the right are ANDed.

Relational Operators for the FORTRAN Grammar

.EQ.

Equal:  If the value on the left is equal to the value on the right then the result is 1; otherwise the result is 0.

.NE.

Not equal:  If the value on the left is not equal to the value on the right then the result is 1; otherwise the result is 0.

.LT.

Less than:  If the value on the left is less than the value on the right then the result is 1; otherwise the result is 0.

.LE.

Less than or equal:  If the value on the left is less than or equal to the value on the right then the result is 1; otherwise the result is 0.

.GT.

Greater than:  If the value on the left is greater than the value on the right then the result is 1; otherwise the result is 0.

.GE.

Greater than or equal:  If the value on the left is greater than or equal to the value on the right then the result is 1; otherwise the result is 0.

Arithmetic/Logical Shift Operators for the FORTRAN Grammar

<<

Left shift:  The bits of the value on the left are shifted to the left by the amount described by the value on the right.

>>

Right shift:  The bits of the value on the left are shifted to the right by the amount described by the value on the right.  If the object on the left is described as unsigned, the vacated high-order bits are zeroed.  If the object on the left is described as signed, the sign bit is propagated through the vacated high-order bits.  The debugger treats registers as unsigned items.

Concatenation Operator for the FORTRAN Grammar

//

String concatenation:  The concatenation of the character string value on the left and right is formed.

Binary Arithmetic Operators for the FORTRAN Grammar

+

Addition:  The value on the right is added to the value on the left.

_

Subtraction:  The value on the right is subtracted from the value on the left.

*

Multiplication:  The value on the left is multiplied by the value on the right.

/

Division:  The value on the left is divided by the value on the right.

%

Modulus:  The modulus of the value on the left with respect to the value on the right is produced.  The result is the remainder when the value on the left is divided by the value on the right.

**

Exponentiation:  This operation is not supported by the debugger.

Unary Arithmetic Operators for the FORTRAN Grammar

+

Plus:  The result is the value on the right.

_

Minus:  The result is the negation of the value on the right.

~

Bit-wise complement:  The result is the bit-wise complement of the value on the right.

++

Increment:  Both prefix and postfix operators are supported.  If the object is on the right, it is pre-incremented by 1 (e.g., ++x).  If the object is on the left, it is post-incremented by 1 (e.g., x++).

_ _

Decrement:  Both prefix and postfix operators are supported.  If the object is on the right, it is pre-decremented by 1 (e.g., --x).  If the object is on the left, it is post-decremented by 1 (e.g., x--).

&

Address of:  The result is the address (segment:offset) of the object on the right (e.g., &main).

*

Points:  The result is the value stored at the location addressed by the value on the right (e.g., *(ds:100), *string.loc).   In the absence of typing information, the value on the right is treated as a pointer into the default data segment (DGROUP) and a near pointer is produced.
     
           (SS:00FE) = FFFF
     var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

%

Value at address:  The result is the value stored at the location addressed by the value on the right (e.g., %(ds:100), %string.loc).  In the absence of typing information, the value on the right is treated as a pointer into the default data segment (DGROUP) and a far pointer is produced.
     
           (SS:00FE) = FFFF
     var:  (SS:0100) = 0152
           (SS:0102) = 1240
           (SS:0104) = EEEE

Note that this operator is not found in the FORTRAN 77 programming language.

Special Unary Operators for the FORTRAN Grammar

?

Existence test:  The "?" unary operator may be used to test for the existence of a symbol.
     
     ?id

The result of this expression is 1 if "id" is a symbol known to the debugger and 0 otherwise.  If the symbol does not exist in the current scope then it must be qualified with its module name.  Automatic symbols exist only in the current subprogram.

Binary Address Operator for the FORTRAN Grammar

:

Memory locations can be referenced by using the binary ":" operator and a combination of constants, register names, and symbol names.  In the Intel 80x86 architecture, a memory reference requires a segment and offset specification.   A memory reference using the ":" operator takes the following form:
     
     segment:offset

The elements segment and offset can be expressions.

Example:

     (ES):(DI+100)
     (SS):(SP-20)

Primary Expression Operators for the FORTRAN Grammar

()

Elements of an array can be identified using subscript expressions.

.

The "." operator indicates field selection in a structure.  This operator is useful in mixed language applications where part of the application is written in the C or C++ programming language.  In the following example, tyme2 is a structure and tm_year is a field in the structure.
     
     tyme2.tm_year

->

The "->" operator indicates field selection when using a pointer to a structure.  This operator is useful in mixed language applications where part of the application is written in the C or C++ programming language.  In the following example, tyme is the pointer and tm_year is a field in the structure to which it points.
     
     tyme->tm_year

Debugger Commands

Syntax Definitions

• A word in angle brackets, like <anything> is a defined term.  Its definition will appear after the syntax description of the command.
• [x] indicates that "x" is an optional item.  It may or may not be included in the command.
• [x|y|z] indicates that on of x, y or z should be included in the command.
• [x [x [...]]] indicates that x may be repeated zero or more times in the command.
• CApital indicates that ca,cap,capi,...  are accepted short forms for the command "capital".
• (GUI only) indicates that this command is only available in a GUI debugger.
• (character-based) indicates that this command is only available in a character mode debugger.
• <expr> indicates an expression.  These may include any of the variables, etc in the program being debugged, and are evaluated in the current program context.  See Open Watcom Debugger Expression Handling.
• <integer> is an integer constant
• <intexpr> is an an expression which evaluates to an integral value.  See Open Watcom Debugger Expression Handling.
• <command> is any debugger command or group of debugger commands.
  
  You can group debugger commands with braces and separate them with semi-colons.  The resulting compound command may be considered as an atomic command.
  
       
       {<command>;<command>;<command>}
• <address> is any expression which evaluates to an address.  See Open Watcom Debugger Expression Handling.
• <string> is a string of text, optionally enclosed in braces.  For example,
  
       
       this_is_a_string
       {so is this}
• <wndname> is the name of a window.  Valid window names (with acceptable short forms indicated in capitals) are:
  • ASsembly
  • ALl
  • BReak
  • Calls
  • Watch
  • FIle
  • FPu
  • FUnctions
  • FILEScope
  • LOCals
  • LOG
  • MEmory
  • MOdules
  • Register
  • SOurce
  • STack
  • Thread
  • IO
  • Globals
  • Variable
  • BInary
  • IMage
  • GLobalfunctions
  • Accelerators
  • TMPFile
  • REPlay
  • CUrrent
• <file> represents any valid operating system file name.  For example,
  
       
       c:\autoexec.bat
• <path> represents any valid operating system directory path.  For example,
  
       
       c:\dir1\dir2

Command Summary

Accelerate

<menu>

the string appearing on the main menu bar (File, Run, Break, Code, etc)

<menu_string>

is enough of the text appearing in a menu to uniquely identify it.

Break

/Set (default)

the breakpoint triggers when <address> is executed

/Byte

the breakpoint triggers when the byte at <address> is modified

/Word

the breakpoint triggers when the word at <address> is modified

/DWord

the breakpoint triggers when the double word at <address> is modified

/Modify

the breakpoint triggers when integer at <address> is modified

<condition>

an expression that must be true (non-zero value) before the breakpoint stops program execution

<countdown>

an integer.  The breakpoint will not stop program execution until <countdown> is decremented to zero.

Note:

If you specify both <condition> and <countdown>, <countdown> decrements only when <condition> evaluates to true.

<do_command>

a command that is executed each time the breakpoint stops program execution

<brkid>

option can be three possible values:

<address>

Perform the operation on breakpoint with the given address.

*

Perform the operation on all breakpoints.

#<integer>

Names a breakpoint by its index.  This index can be discovered on the title line of the Breakpoint dialog.

Call

/Far

Use a far call instruction.

/Near

Use a near call instruction.

/Interrupt

Call the routine as if it were an interrupt handler.

<parm>

is [/<location>] <expr>

<location>

is [/|<regset>]

/

means to put the parm on the stack.

/<regset>

means to put the parm into the named registers.

<regset> is a register aggregate.

See Open Watcom Debugger Expression Handling.

<printlist>

See the print command for details.

CAPture

COnfigfile

Display

<ord>

The height to be used for toolbar buttons.

<ord>,<ord>,<ord>,<ord>

These are the x and y coordinates of the top left corner, and the width and the height of the window respectively.  0,0,10000,10000 is a window covering the entire screen.

/Open

Open a new window or resize an existing one.

/New

Open a new window regardless of an existing one.

/Close

Close the window.

/MInimize

Iconize the window.

/MAximize

Make the window full screen size.

/REstore

Restore a window from a minimize or maximize.

DO (or /)

ERror

Examine

/<type>

where "<type>" is one of Byte, Word, Dword, Qword, Char, Short, Long, __int64, Unsigned_Char, Unsigned_Short, Unsigned_Long, Unsigned___int64, 0:16_Pointer, 16:16_Pointer, 0:32_Pointer, 16:32_Pointer, Float, Double, or Extended_Float.   Set the initial display type of the memory window.

/IOByte /IOWord /IODword

Set the initial display type of the line in the I/O window.

<address>

the address to examine.

<follow>

an expression which will be used if the memory window's Repeat function is chosen.

<len>

an integer expression indicating the length of memory to examine.

Flip

FOnt

<wndname>

the name of the affected window

<fontinfo>

operating system specific font data.

Go

/Until

skips breakpoints until the specified stop address is reached.

/Keep

allows you to keep a previous temporary breakpoint.  If you keep the previous breakpoint you cannot create a new one.

/Noflip

keeps the debugger from flipping to the application's screen.

<start>

the <address> at which to start execution (optional).

<stop>

the <address> at which to stop execution.

Help

HOok

PROGStart

a program is loaded

PROGEnd

a program terminates

DLLStart

a DLL is loaded

DLLEnd

a DLL is unloaded

EXECStart

program execution is beginning

EXECEnd

program execution is stopped

Sourceinfo

the current location being examined has debugging information

Assemblyinfo

the current location being examined has no debugging information

Modulechange

the current location being examined has changed modules

IF

INvoke (or <)

<file>

is the name of the command file to invoke.

<string>

will be passed as a parameter.  These parameters may be referenced in the command file as <1>, <2>, etc.

Log (or >)

MOdify

/Byte /Pointer /Word /Dword

Control the size of memory to be modified.

/IOByte /IOWord /IODword

Control the size of the I/O port to be modified.

<address>

The address to modify.

<expr>

The values to be placed in memory.

NEW

<symfile>

represents a file containing the symbolic information.

<progfile>

represents the executable file.

<args>

represent the arguments to be passed to the program.

/Restart

Reload the current application and place it into an initial state so that you may begin execution again.  The application may have already partially or completely executed.

/STDIn

associate the standard input file handle with a particular file or device.

/STDOut

associate the standard output file handle with a particular file or device.

/Symbol

load additional symbolic debugging information and specify the mapping between the linker addresses and the actual execution addresses.

PAint

<wndattr>

allows you to define the window attributes.  You can choose from the following items:

MEnu Plain

menu text (character-based)

MEnu STandout

menu accelerator key (character-based)

MEnu Disabled

grayed menu item (character-based)

MEnu Active

menu item under the cursor (character-based)

MEnu Active STandout

menu accelerator key under the cursor (character-based)

MEnu Frame

frame of the menu (character-based)

MEnu Disabled Active

grayed menu item under the cursor (character-based)

TItle Disabled

a non active window's title

Frame Active

the frame of the active window (character-based)

Frame Disabled

the frame an inactive window (character-based)

ICon

an icon

Plain

normal text within a window

Active

window text under the cursor

SElected

window text being selected

STandout

window text the debugger wishes to highlight

Active STandout

window text the debugger wishes to highlight under the cursor

BUtton

the gadgets on the left side of a window (character-based)

<dlgattr>

option allows you to define the dialog attributes.  The possible options are:

Plain

normal text

Frame

the dialog frame

SHadow

the shadow of a button

BUtton Plain

normal button text

BUtton STandout

button accelerator key character

BUtton Active

a button which has focus

BUtton Active STandout

button accelerator key character of a button with focus

<color>

You can choose from the following colours:

• BLAck
• BLUe
• GREEn
• Cyan
• Red
• MAgenta
• BROwn
• White
• GREY
• GRAy
• BRIght BLUe
• BRIght GREEn
• BRIght Cyan
• BRIght Red
• BRIght MAgenta
• Yellow
• BRIght BROwn
• BRIght White

Print (or ?)

/Window

opens up a watch window containing the listed expressions.

/Program

print the results to the application's screen.

<printlist>

is [<format>] [<exprlist>]

<exprlist>

is [<expr> [,<expr> [...]]]

<format>

is a printf like format string.  It consists of plain text intermixed with control sequences, which will be substituted with values from the expression list.  The control sequences are:

%i

The corresponding argument is printed out as a signed decimal integer value.

%d

The corresponding argument is printed out as a signed decimal integer value.

%u

The corresponding argument is printed out as an unsigned decimal integer value.

%x

The corresponding argument is printed out as an unsigned hexadecimal integer value.  Letter digits are printed in lower case (a-f).

%X

The corresponding argument is printed out as an unsigned hexadecimal integer value.  Letter digits are printed in upper case (A-F).

%o

The corresponding argument is printed out as an unsigned octal integer value.

%p

The corresponding argument is printed out as a pointer (segment:offset) value in hexadecimal notation.

%c

The corresponding argument is printed out as a single character value.

%s

The corresponding argument is printed out as a C/C++ string value.  The argument must point to a string of characters terminated by a byte whose value is zero.

%%

To print out a percentage symbol, the "%" must be doubled up (i.e., %%).

%f

The corresponding argument is printed out in floating-point representation.  If the floating-point value has a very large or small magnitude, you should use one of "g", "G", "e" or "E" formatting.

%g

The corresponding argument is printed out in floating-point representation.  Numbers of very large or small magnitude are printed out in scientific "E" notation (e.g., 1.54352e+16).  The exponent letter is printed in lower case.

%G

The corresponding argument is printed out in floating-point representation.  Numbers of very large or small magnitude are printed out in scientific "E" notation (e.g., 1.54352E+16).  The exponent letter is printed in upper case.

%e

The corresponding argument is printed out in scientific "E" notation (e.g., 1.23456e+02).  The exponent letter is printed in lower case.

%E

The corresponding argument is printed out in scientific "E" notation (e.g., 1.23456E+02).  The exponent letter is printed in upper case.

%r

The corresponding argument is printed out in the current default numeric radix.

%a

The corresponding argument is printed out as a symbol reference (symbol_name+offset) when possible; otherwise it is printed out as a pointer (segment:offset) value in hexadecimal notation.

%l

The corresponding argument is printed out as a line number reference (module_name@line_number+offset) when possible; otherwise it is printed out as a pointer (segment:offset) value in hexadecimal notation.

Quit

RECord

Register

REMark (or *)

Set

<location>

see call command.

<lookspec>

[/Ignore|/Respect] <string>

SHow

SKip

STackpos <intexpr>

SYstem (or !)

/Remote

the shell is started on the program side of a remote debug link.

/Local

the shell is started on the debugger side of a remote debug link.

THread (or ~)

/Show

display the status of the current thread.

/Freeze

freeze a thread and make it unrunnable.

/Thaw

make a frozen thread runnable.

/Change

to select a specific thread.

<threadid>

is the identification number of the thread.

Trace

/Assembly

trace through your assembly code on instruction at a time.

/Mixed

trace execution of the application one source statement at a time, or one instruction at a time when no source text is available.

/Source

trace execution of the application one source statement at a time.

/Into

continue execution to the next statement or assembly instruction.  If the current statement or instruction invokes a routine, then the next statement or instruction is the first one called in the routing.

/Next

continue execution to the next statement or assembly instruction that immediately follows the current statement or instruction in memory.  If the current statement or instruction is one that branches, be sure that the execution path eventually executed the statement or instruction that follows.  If the program does not executed this point, the program may execute to completion.

/Over

continue execution to the next statement or assembly instruction.  If the current statement or instruction invokes a routine, then the next statement or instruction is the one that follows the invocation of the routine.

Undo

View

/Binary

show the file contents in binary.

<file>

the file to be shown.

<module>

the module to be shown.  The default is the current module.

While

WIndow

WIndow CLose

close the window

WIndow CURSORStart

move the cursor to start of line

WIndow CURSOREnd

move the cursor to end of line

WIndow CURSORDown

move the cursor down one line

WIndow CURSORLeft

move the cursor left

WIndow CURSORRight

move the cursor right

WIndow CURSORUp

move up one line

WIndow Dump

dump the window to a file

WIndow Log

dump the window to a log window

WIndow FINDNext

find the next occurrence of the current search string

WIndow FINDPrev

find the previous occurrence of the current search string

WIndow Next

make another window the current window

WIndow PAGEDown

move the window down one page

WIndow PAGEUp

move the window up one page

WIndow POpup

show the window's floating pop-up menu

WIndow SEarch

search for a given string

WIndow SCROLLDown

scroll the window down one line

WIndow SCROLLUp

scroll the window up one line

WIndow SCROLLTop

scroll the window to the very top

WIndow SCROLLBottom

scroll the window to the very bottom

WIndow TABLeft

move to the previous tabstop

WIndow TABRight

move to the next tabstop

WIndow MAXimize

maximize the window

WIndow MINimize

minimize the window

WIndow REStore

restore the window

WIndow TIle

tile all windows

WIndow CAscade

cascade all windows

WIndow PRevious

move to the previous window

Predefined Symbols

eax

32-bit EAX register (32-bit mode only)

ax

16-bit AX register

al

8-bit AL register

ah

8-bit AH register

ebx

32-bit EBX register (32-bit mode only)

bx

16-bit BX register

bl

8-bit BL register

bh

8-bit BH register

ecx

32-bit ECX register (32-bit mode only)

cx

16-bit CX register

cl

8-bit CL register

ch

8-bit CH register

edx

32-bit EDX register (32-bit mode only)

dx

16-bit DX register

dl

8-bit DL register

dh

8-bit DH register

eip

Instruction pointer register (32-bit mode only)

ip

Instruction pointer register

esi

Source index register (32-bit mode only)

si

Source index register

edi

Destination index register (32-bit mode only)

di

Destination index register

esp

Stack pointer register (32-bit mode only)

sp

Stack pointer register

ebp

Base pointer register (32-bit mode only)

bp

Base pointer register

cs

Code segment register

ds

Data segment register

es

Extra segment register

fs

Segment register (32-bit mode only)

gs

Segment register (32-bit mode only)

ss

Stack segment register

fl

Flags register

efl

Flags register (32-bit mode only)

fl.flg_bit_name

Individual bits in Flags register
     
     flg_bit_name ::= "c" | "p" | "a" | "z" | "s" | "i" | "d" | "o"

efl.flg_bit_name

Individual bits in Flags register
     
     flg_bit_name ::= "c" | "p" | "a" | "z" | "s" | "i" | "d" | "o"

The following table lists the full name for each of the flags register bits:

fl.o, efl.o

overflow flag

fl.d, efl.d

direction flag

fl.i, efl.i

interrupt flag

fl.s, efl.s

sign flag

fl.z, efl.z

zero flag

fl.a, efl.a

auxiliary carry flag

fl.p, efl.p

parity flag

fl.c, efl.c

carry flag

st0 - st7

Numeric Data Processor registers (math coprocessor registers)

cw

8087 control word (math coprocessor control word)

cw.cw_bit_name

Individual bits in the control word
     
     cw_bit_name ::= "ic" | "rc" | "pc" | "iem" | "pm" |
                              "um" | "om" | "zm" | "dm" | "im"

The following table lists the full name for each of the control word bits:

cw.ic

infinity control
     0 = projective
     1 = affine

cw.rc

rounding control (2 bits)
     00 = round to nearest or even
     01 = round down (towards negative infinity)
     10 = round up (towards positive infinity)
     11 = chop (truncate toward zero)

cw.pc

precision control (2 bits)
     00 = 24 bits
     01 = reserved
     10 = 53 bits
     11 = 64 bits

cw.iem

interrupt enable mask (8087 only)
     0 = interrupts enabled
     1 = interrupts disabled (masked)

cw.pm

precision (inexact result) mask

cw.um

underflow mask

cw.om

overflow mask

cw.zm

zero-divide mask

cw.dm

denormalized operand mask

cw.im

invalid operand mask

sw

8087 status word (math coprocessor status word)

sw.sw_bit_name

Individual bits in the status word
     
     sw_bit_name ::=  "b" | "c3" | "st" | "c2" | "c1" |
                              "c0" | "es" | "sf" | "pe" | "ue" |
                              "oe" | "ze" | "de" | "ie"

The following table lists the full name for each of the status word bits:

sw.b

busy

sw.c3

condition code bit 3

sw.st

stack stop pointer (3 bits)
     000 = register 0 is stack top
     001 = register 1 is stack top
     010 = register 2 is stack top
         .
         .
         .
     111 = register 7 is stack top

sw.c2

condition code bit 2

sw.c1

condition code bit 1

sw.c0

condition code bit 0

sw.es

error summary (287, 387 only)

sw.sf

stack fault (387 only)

sw.pe

precision (inexact result) exception

sw.ue

underflow exception

sw.oe

overflow exception

sw.ze

zero-divide exception

sw.de

denormalized operand exception

sw.ie

invalid operation exception

mm0 - mm7

MMX registers

mm0.b0 - mm0.b7

MMX register component bytes

mm0.w0 - mm0.w3

MMX register component words

mm0.d0 - mm0.d1

MMX register component doublewords

xmm0 - xmm7

XMM registers (SSE registers)

xmm0.b0 - xmm0.b15

XMM register component bytes

xmm0.w0 - xmm0.w7

XMM register component words

xmm0.d0 - xmm0.d3

XMM register component doublewords

xmm0.q0 - xmm0.q1

XMM register component quadwords

dbg$32

This debugger symbol represents the mode in which the processor is running.

0

16-bit mode

1

32-bit mode

dbg$bp

This debugger symbol represents the register pair SS:BP (16-bit mode) or SS:EBP (32-bit mode).
Example:

     ? dbg$bp

dbg$code

This debugger symbol represents the current code location under examination.  The dot address "." is either set to dbg$code or dbg$data, depending on whether you were last looking at code or data. 

dbg$cpu

This debugger symbol represents the type of central processing unit which is in your personal computer system.

0

Intel 8088, 8086 or compatible processor

1

Intel 80188, 80186 or compatible processor

2

Intel 80286 or compatible processor

3

Intel 80386 or compatible processor

4

Intel 80486 or compatible processor

5

Intel Pentium processor

6

Intel Pentium Pro/II/III processor

15

Intel Pentium 4 processor

dbg$ctid

This debugger symbol represents the identification number of the current execution thread.  Under environments which do not support threading, the current thread ID is always 1.  The current execution thread can be selected using the Thread window or the Thread command. 

dbg$data

This debugger symbol represents the current data location under examination.  The dot address "." is either set to dbg$code or dbg$data, depending on whether you were last looking at code or data. 

dbg$etid

This debugger symbol represents the identification number of the thread that was executing when the debugger was entered.   Under environments which do not support threading, the executing thread ID is always 1. 

dbg$fpu

This debugger symbol represents the type of numeric data processor (math coprocessor) that is installed in your personal computer system.

0

No coprocessor is installed

1

An Intel 8087 is installed

2

An Intel 80287 is installed

3

An Intel 80387 is installed

4

An Intel 80486 processor, supporting coprocessor instructions, is installed

5

An Intel Pentium processor integrated FPU is installed

6

An Intel Pentium Pro/II/III processor integrated FPU is installed

15

An Intel Pentium 4 processor integrated FPU is installed

255

An 80x87 emulator is installed

dbg$ip

This debugger symbol represents the register pair CS:IP (16-bit mode) or CS:EIP (32-bit mode).
Example:

     ? dbg$ip

dbg$monitor

This debugger symbol represents the type of monitor adapter which is in use.

0

IBM Monochrome Adapter

1

IBM Colour Graphics Adapter (CGA)

2

IBM Enhanced Graphics Adapter (EGA)

3

IBM Video Graphics Array (VGA)

dbg$ntid

This debugger symbol represents the identification number of the next execution thread.  To iterate through all of the threads in a process, you can execute thread dbg$ntid repetitively until you are back to the original thread.  Under environments which do not support threading, the next thread ID is always 1.  To show the execution stack for all threads (in the Log window), you can execute the following commands:
Example:

     /orig_tid = dbg$ctid
     /curr_tid = dbg$ctid
     while curr_tid != 0 {
         print {----- Next Thread %x -----} curr_tid;
         show calls;
         /curr_tid = dbg$ntid;
         thread curr_tid;
         if( curr_tid == orig_tid ) {
             /curr_tid = 0;
         };
     }

dbg$os

This debugger symbol represents the operating system that is currently running the application.

0

Unknown Operating System

1

DOS

2

OS/2

3

386|DOS-Extender from Phar Lap Software, Inc.

5

NetWare 386 from Novell, Inc.

6

QNX from QNX Software Systems.

7

DOS/4GW from Tenberry Software, Inc., or CauseWay (both included in the Open Watcom C/C++(32) and Open Watcom FORTRAN 77/32 packages)

8

Windows 3.x from Microsoft Corporation

10

Windows NT/2000/XP or Windows 9x from Microsoft Corporation

12

QNX 6.x 'Neutrino'

13

GNU/Linux

14

FreeBSD

dbg$pid

(OS/2, NetWare 386, Linux, QNX, Windows NT, Windows 95 only) This debugger symbol contains the process identification value for the program being debugged. 

dbg$psp

(DOS only) This debugger symbol contains the segment value for the DOS "program segment prefix" of the program being debugged. 

dbg$radix

This debugger symbol represents the current default numeric radix. 

dbg$remote

This debugger symbol is 1 if the "REMotefiles" option was specified and 0 otherwise. 

dbg$sp

This debugger symbol represents the register pair SS:SP (16-bit mode) or SS:ESP (32-bit mode).
Example:

     ? dbg$sp

dbg$loaded

This debugger symbol is 1 if a program is loaded.  Otherwise, it is 0. 

dbg$nil

This debugger symbol is the null pointer value. 

dbg$src

This debugger symbol is 1 if you are currently debugging in an area that contains debugging information.

Wiring For Remote Debugging

Serial Port Wiring Considerations

Parallel Port Wiring Considerations

1. They are commercially available (you may already own one).
2. They may work with more PC "compatibles" than Watcom's cable.  Watcom's cabling requires 8 bi-directional data lines in the parallel port and some PC "compatibles" do not support this.

Remote File Operations (DOS, NT, OS/2 Only)

1. creating, listing and removing directories
2. setting the current drive and directory
3. display, renaming, erasing, and copying files (including PC to PC file transfers).