wdbgbrkp.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap *refid=vidbrk Breakpoints
.*
.np
.ix 'breakpoint' 'defined'
.ix 'watchpoint' 'defined'
.ix 'tracepoint' 'defined'
The &dbgname. uses the single term breakpoint to refer to the group of
functions that other debuggers often call breakpoints, watchpoints,
and tracepoints.
.np
A breakpoint is traditionally defined as a place in your program where
you want execution to stop so that you can examine program variables
and data structures. A watchpoint causes your program to be executed
one instruction or source line at a time, watching for the value of an
expression to become true. Do not confuse a watchpoint with the watch
window. A tracepoint causes your program to be executed one
instruction or source line at a time, watching for the value of
certain program variables or memory-referencing expressions to change.
.np
In the &dbgname.:
.ix 'breakpoint' 'on execute'
.ix 'breakpoint' 'on write'
.ix 'Variables' 'stopping on write'
.begbull $compact
.bull
Break-on-execute refers to the traditional breakpoint
.bull
Break-on-write refers to the traditional tracepoint
.bull
A traditional watchpoint is a break-on-execute or break-on-write that
is coupled with a condition
.ix 'watchpoint'
.endbull
.np
The &dbgname unifies these three concepts by defining three parts to a
breakpoint:
.begbull $compact
.bull
the location in the program where the breakpoint occurs
.bull
the condition under which the breakpoint is triggered
.bull
the action that takes place when the breakpoint triggers
.endbull
.np
You can specify a countdown, which means that a condition must be true
a designated number of times before the breakpoint is triggered.
.ix 'breakpoint' 'countdown'
.ix 'breakpoint' 'condition'
.np
When a breakpoint is triggered, several things can happen:
.begbull $compact
.bull
program execution is stopped (a breakpoint)
.bull
an expression is executed (code splice)
.bull
a group of breakpoints is enabled or disabled
.endbull
.np
In this chapter, you will learn about the breakpoint including how to
set simple breakpoints, conditional breakpoints, and how to set
breakpoints that watch for the exact moment when a program variable,
expression, or data object changes value.
.*
.section How to Use Breakpoints during a Debugging Session
.*
.np
The following topics are discussed:
.begbull
.bull
:HDREF refid='dbgbrks'.
.bull
:HDREF refid='dbgbrkc'.
.endbull
.*
.beglevel
.*
.section *refid=dbgbrks Setting Simple Breakpoints
.*
.np
.ix 'breakpoint' 'setting simple'
When debugging, you will often want to set a few simple breakpoints to
make your program pause execution when it executes certain code. You
can set or clear a breakpoint at any location in your program by
placing the cursor on the source code line and selecting
.menuref 'Toggle' 'Break'
or by clicking on the button to the left of the source line. You can
set breakpoints in the assembly window in a similar fashion. Setting a
break-on-write breakpoint is equally simple. Select the variable with
the right mouse button and choose
.popup Break
.dot
.np
.ix 'breakpoint' 'state'
Break points have three states.  They are:
.begbull $compact
.bull
enabled
.bull
disabled
.bull
cleared (non-existent)
.endbull
.np
The button for an enabled break point is a stop sign or [!].
The button for a disabled break point is a grey stop sign or [.].
A green diamond or [ ] appears when no breakpoint exists at the given
line. The same buttons also appear in the Assembly window and the
Break window to indicate the status of a break point.
.begnote
.note 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.
.endnote
.*
.section *refid=dbgbrkc Clearing, Disabling, and Enabling Breakpoints
.*
.np
.ix 'breakpoint' 'clearing'
.ix 'breakpoint' 'disabling'
.ix 'breakpoint' 'enabling'
Choosing
.menuref 'Toggle' 'Break'
(F9) toggles between the three different breakpoint states:
.begbull $compact
.bull
enabled
.bull
disabled
.bull
cleared (non-existent)
.endbull
.*
.endlevel
.*
.section *refid=menubrk The Break Menu
.*
.np
You can use the
.mi Break
menu to control your breakpoints. Operations including creating new
breakpoints, changing a breakpoint's status, and viewing a list of all
break points.
.*
.begmenu Break
.*
.menuitem Toggle
.*
.ix 'breakpoint' 'toggling'
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.
.begnote
.note 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.
.endnote
.*
.menuitem At Cursor
.*
.ix 'breakpoint' 'at cursor position'
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
.mi At Cursor
.ct ,
the Breakpoint dialog appears.
.*
.menuitem New
.*
.ix 'breakpoint' 'setting'
This allows you to create any type of breakpoint using a dialog. You
must specify the address in the dialog.
.*
.menuitem On Image Load...
.*
.ix 'breakpoint' '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.
.*
.menuitem On Debug Message
.*
.ix 'breakpoint' '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
.kw OutputDebugString
function.
This option is toggled each time it is selected from the
.mi Break
menu.
.*
.menuitem View All
.*
.ix 'breakpoint' 'displaying'
Open the breakpoint window. This window will show a list of all
breakpoints. You can use the window to create, delete and modify
breakpoints.
.*
.menuitem Clear All
.*
.ix 'breakpoint' 'clearing all'
Clear all breakpoints.
.*
.menuitem Disable All
.*
.ix 'breakpoint' 'disabling all'
Disable all breakpoints, but do not delete them.
.*
.menuitem Enable All
.*
.ix 'breakpoint' 'enabling all'
Enable all breakpoints that are disabled.