27.4 – Description, Continued...
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
Related commands:
(ACTIVATE,DEACTIVATE,SHOW,CANCEL) WATCH
MONITOR
SET BREAK
SET STEP [NO]SOURCE
SET TRACE
27.5 – Static and Nonstatic Watchpoints
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 Alpha 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 (
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:
o Deactivate the static watchpoint before the service call.
When the call completes, check the watchpoint manually and
reactivate it.
o 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
27.6 – Global Section Watchpoints
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.
Examples
1.DBG> SET WATCH MAXCOUNT
This command establishes a watchpoint on the variable MAXCOUNT.
2.DBG> SET WATCH ARR
DBG> GO
. . .
watch of SUBR\ARR at SUBR\%LINE 12+8
old value:
(1): 7
(2): 12
(3): 3
new value:
(1): 7
(2): 12
(3): 28
break at SUBR\%LINE 14
DBG>
In this example, the SET WATCH command sets a watchpoint on
the three-element integer array, ARR. Execution is then resumed
with the GO command. The watchpoint triggers whenever any array
element changes. In this case, the third element changed.
3.DBG> SET WATCH ARR(3)
This command sets a watchpoint on element 3 of array ARR (Fortran
array syntax). The watchpoint triggers whenever element 3
changes.
4.DBG> SET WATCH P_ARR[3:5]
This command sets a watchpoint on the array slice consisting
of elements 3 to 5 of array P_ARR (Pascal array syntax). The
watchpoint triggers whenever any of these elements change.
5.DBG> SET WATCH P_ARR[3]:P_ARR[5]
This command sets a separate watchpoint on each of elements 3 to
5 of array P_ARR (Pascal array syntax). Each watchpoint triggers
whenever its target element changes.
6.DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
In this example, variable K is a nonstatic variable and is
defined only when its defining routine, SUB2, is active (on
the call stack). The SET TRACE command sets a tracepoint on
SUB2. When the tracepoint is triggered during execution, the
DO clause sets a watchpoint on K. The watchpoint is then canceled
when execution returns from routine SUB2. The /SILENT qualifier
suppresses the "trace . . . " message and the display of source
code at the tracepoint.
7.DBG> g
%DEBUG-I-ASYNCSSWAT, possible asynchronous system service and static
watchpoint collision break at LARGE_UNION\main\%LINE 24192+60
DBG> sho call
module name routine name line rel PC abs PC
*LARGE_UNION main 24192 00000000000003A0 00000000000303A0
*LARGE_UNION __main 24155 0000000000000110 0000000000030110
FFFFFFFF80B90630 FFFFFFFF80B90630
DBG> ex/sour %line 24192
module LARGE_UNION
24192: sstatus = sys$getsyi (EFN$C_ENF, &sysid, 0, &syi_ile, &myiosb, 0, 0);
In this example, an asynchronous write by SYS$QIO to its IOSB
output parameter fails if that IOSB is being watched directly
or even if it simply lives on the same page as an active static
watchpoint.
Debugger notices this problem and warns the user about potential
collisions between static watchpoints and asynchronous system
services.
28 – WINDOW
Creates a screen window definition. This command is not available
in the VSI DECwindows Motif for OpenVMS user interface to the
debugger.
Format
SET WINDOW window-name
AT (start-line,line-count
[,start-column,column-count])
28.1 – Parameters
window-name
Specifies the name of the window you are defining. If a window
definition with that name already exists, it is canceled in favor
of the new definition.
start-line
Specifies the starting line number of the window. This line
displays the window title, or header line. The top line of the
screen is line 1.
line-count
Specifies the number of text lines in the window, not counting
the header line. The value must be at least 1. The sum of start-
line and line-count must not exceed the current screen height.
start-column
Specifies the starting column number of the window. This is the
column at which the first character of the window is displayed.
The leftmost column of the screen is column 1.
column-count
Specifies the number of characters per line in the window. The
value must be at least 1. The sum of start-column and column-
count must not exceed the current screen width.
28.2 – Description
A screen window is a rectangular region on the terminal screen
through which you can view a display. The SET WINDOW command
establishes a window definition by associating a window name
with a screen region. You specify the screen region in terms of a
starting line and height (line count) and, optionally, a starting
column and width (column count). If you do not specify the
starting column and column count, the starting column defaults
to column 1 and the column count defaults to the current screen
width.
You can specify a window region in terms of expressions that use
the built-in symbols %PAGE and %WIDTH.
You can use the names of any windows you have defined with the
SET WINDOW command in a DISPLAY command to position displays on
the screen.
Window definitions are dynamic-that is, window dimensions expand
and contract proportionally when a SET TERMINAL command changes
the screen width or height.
Related commands:
DISPLAY
(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SHOW,CANCEL) WINDOW
28.3 – Examples
1.DBG> SET WINDOW ONELINE AT (1,1)
This command defines a window named ONELINE at the top of the
screen. The window is one line deep and, by default, spans the
width of the screen.
2.DBG> SET WINDOW MIDDLE AT (9,4,30,20)
This command defines a window named MIDDLE at the middle of the
screen. The window is 4 lines deep starting at line 9, and 20
columns wide starting at column 30.
3.DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
This command defines a window named FLEX that occupies a region
around the middle of the screen and is defined in terms of the
current screen height (%PAGE) and width (%WIDTH).