This command causes the debugger to trace line 14 of module TEST5 when
X is not equal to 2. At the tracepoint, the EXAMINE Y command is
issued. The /NOSOURCE qualifier suppresses the display of source code
at the tracepoint. The syntax of the conditional expression in the WHEN
clause is language-dependent.
When an instruction causes the modification of a watchpoint location,
the debugger takes the following actions:
- Suspends program execution after that instruction has completed
execution.
- If you specified /AFTER when you set the watchpoint, checks the
AFTER count. If the specified number of counts has not been reached,
execution continues and the debugger does not perform the remaining
steps.
- Evaluates the expression in a WHEN clause, if you specified one
when you set the watchpoint. If the value of the expression is false,
execution continues and the debugger does not perform the remaining
steps.
- Reports that execution has reached the watchpoint location
("watch of...") unless you specified /SILENT.
- Reports the old (unmodified) value at the watchpoint location.
- Reports the new (modified) value at the watchpoint location.
- Displays the line of source code at which execution is suspended,
unless you specified /NOSOURCE or /SILENT when you set the watchpoint
or entered a previous SET STEP NOSOURCE command.
- Executes the commands in a DO clause, if you specified one when you
set the watchpoint. If the DO clause contains a GO command, execution
continues and the debugger does not perform the next step.
- Issues the prompt.
For high-level language programs, the address expressions you specify
with the SET WATCH command are typically variable names. If you specify
an absolute memory address that is associated with a compiler-generated
type, the debugger symbolizes the address and uses the length in bytes
associated with that type to determine the length in bytes of the
watchpoint location. If you specify an absolute memory address that the
debugger cannot associate with a compiler-generated type, the debugger
watches 4 bytes of memory (by default), beginning at the byte
identified by the address expression. You can change this length,
however, by setting the type to either WORD (SET TYPE WORD, which
changes the default length to 2 bytes) or BYTE (SET TYPE BYTE, which
changes the default length to 1 byte). SET TYPE LONGWORD restores the
default length of 4 bytes.
You can set a watchpoint on a range, for example,
The debugger establishes a series of longword watches that cover the
range.
You can set watchpoints on aggregates (that is, entire arrays or
records). A watchpoint set on an array or record triggers if any
element of the array or record changes. Thus, you do not need to set
watchpoints on individual array elements or record components. Note,
however, that you cannot set an aggregate watchpoint on a variant
record.
You can also set a watchpoint on a record component, on an individual
array element, or on an array slice (a range of array elements). A
watchpoint set on an array slice triggers if any element within that
slice changes. When setting the watchpoint, follow the syntax of the
current language.
The following qualifiers affect what output is seen when a watchpoint
is reached:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect the timing and duration of watchpoints:
/AFTER:n
/TEMPORARY
The following qualifiers apply only to nonstatic variables:
/INTO
/OVER
The following qualifier overrides the debugger's determination of
whether a variable is static or nonstatic:
/[NO]STATIC
Note
On VAX systems, watchpoints set on variables
whose addresses are in global sections do not work. Attempting to set a
watchpoint on a location in a global section results in a
%DEBUG-E-BADWATCH message.
|
Static and Nonstatic Watchpoints
The technique for setting a watchpoint depends on whether the variable
is static or nonstatic.
A static variable is associated with the same memory address throughout
execution of the program. You can always set a watchpoint on a static
variable throughout execution.
A nonstatic variable is allocated on the call stack or in a register
and has a value only when its defining routine is active (on the call
stack). Therefore, you can set a watchpoint on a nonstatic variable
only when execution is currently suspended within the scope of the
defining routine (including any routine called by the defining
routine). The watchpoint is canceled when execution returns from the
defining routine. With a nonstatic variable, the debugger traces every
instruction to detect any changes in the value of a watched variable or
location.
Another distinction between static and nonstatic watchpoints is speed
of execution. To watch a static variable, the debugger write-protects
the page containing the variable. If your program attempts to write to
that page, an access violation occurs and the debugger handles the
exception, determining whether the watched variable was modified.
Except when writing to that page, the program executes at normal speed.
To watch a nonstatic variable, the debugger traces every instruction in
the variable's defining routine and checks the value of the variable
after each instruction has been executed. Since this significantly
slows execution, the debugger issues a message when you set a nonstatic
watchpoint.
As explained in the next paragraphs, /[NO]STATIC, /INTO, and /OVER
enable you to exercise some control over speed of execution and other
factors when watching variables.
The debugger determines whether a variable is static or nonstatic by
checking how it is allocated. Typically, a static variable is in P0
space (0 to 3FFFFFFF, hexadecimal); a nonstatic variable is in P1 space
(40000000 to 7FFFFFFF) or in a register. The debugger issues a warning
if you try to set a watchpoint on a variable that is allocated in P1
space or in a register when execution is not currently suspended within
the scope of the defining routine.
The /[NO]STATIC qualifiers enable you to override this default
behavior. For example, if you have allocated nonstack storage in P1
space, use /STATIC when setting a watchpoint on a variable that is
allocated in that storage area. This enables the debugger to use the
faster write-protection method of watching the location instead of
tracing every instruction. Conversely, if, for example, you have
allocated your own call stack in P0 space, use /NOSTATIC when setting a
watchpoint on a variable that is allocated on that call stack. This
enables the debugger to treat the watchpoint as a nonstatic watchpoint.
You can also control the execution speed for nonstatic watchpoints in
called routines by using /INTO and /OVER.
On both Alpha and VAX processors, both static and nonstatic watchpoints
are available. With static watchpoints, the debugger write-protects the
page of memory in which the watched variable is stored. Static
watchpoints, therefore, would interfere with the system service itself
if not for the debugger's use of system service interception (SSI).
If a static watchpoint is in effect then, through system service
interception, the debugger deactivates the static watchpoint,
asynchronous traps (ASTs), and thread switching, just before the system
service call. The debugger reactivates them just after the system
service call completes, putting the watchpoint, AST enabling, and
thread switching back to their original state and, finally, checking
for any watchpoint hits. This behavior is designed to allow the system
service to run as it normally would (that is, without write-protected
pages) and to prevent the AST code or a different thread from
potentially changing the watchpointed location while the watchpoint is
deactivated. Be aware of this behavior if, for example, your
application tests to see if ASTs are enabled.
An active static watchpoint can cause a system service to fail, likely
with an ACCVIO status, if the system service is not supported by the
system service interception (SSI) vehicle (DBGSSISHR on OpenVMS VAX
systems and SYS$SSISHR on OpenVMS Alpha systems). Any system service
that is not in SYS$PUBLIC_VECTORS is unsupported by SSI, including User
Written System Services (UWSS) and any loadable system services, such
as $MOUNT.
When a static watchpoint is active, the debugger write-protects the
page containing the variable to be watched. A system service call not
supported by SSI can fail if it tries to write to that page of user
memory.
To avoid this failure, do either of the following:
- Deactivate the static watchpoint before the service call. When the
call completes, check the watchpoint manually and reactivate it.
- Use nonstatic watchpoints. Note that nonstatic watchpoints can
slow execution.
If a watched location changes during a system service routine, you will
be notified, as usual, that the watchpoint occurred. Note that, on rare
occasions, stack may show one or more debugger frames on top of the
frame or frames for your program. To work around this problem, enter
one or more STEP/RETURN commands to get back to your program.
System service interception is on by default, but on Alpha
processors only, you can disable interception prior to a debugging
session by issuing the following command:
$ DEFINE SSI$AUTO_ACTIVATE OFF
|
To reenable system service interception, issue one of the following
commands:
$ DEFINE SSI$AUTO_ACTIVATE ON
$ DEASSIGN SSI$AUTO_ACTIVATE
|
Global Section Watchpoints (Alpha and I64 Only)
On Alpha processors, you can set watchpoints on variables or arbitrary
program locations in global sections. A global section is a region of
memory that is shared among all processes of a multiprocess program. A
watchpoint that is set on a location in a global section (a global
section watchpoint) triggers when any process modifies the contents of
that location.
You set a global section watchpoint just as you would set a watchpoint
on a static variable. However, because of the way the debugger monitors
global section watchpoints, note the following point. When setting
watchpoints on arrays or records, performance is improved if you
specify individual elements rather than the entire structure with the
SET WATCH command.
If you set a watchpoint on a location that is not yet mapped to a
global section, the watchpoint is treated as a conventional static
watchpoint. When the location is subsequently mapped to a global
section, the watchpoint is automatically treated as a global section
watchpoint and an informational message is issued. The watchpoint is
then visible from each process of the multiprocess program.
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH
MONITOR
SET BREAK
SET STEP [NO]SOURCE
SET TRACE
