HP OpenVMS Systems Documentation

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

Examples

DBG> SET WATCH MAXCOUNT
      

This command establishes a watchpoint on the variable MAXCOUNT.

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.

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.

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.

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.

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.

Creates a screen window definition.

Note This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger.

Format

SET WINDOW window-name
AT (start-line,line-count
[,start-column,column-count])

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.

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

Examples

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.

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.

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).

Identifies the Ctrl-key sequence currently defined to abort the execution of a debugger command or to interrupt program execution.

Note This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger.

Format

SHOW ABORT_KEY

Description

By default, the Ctrl/C sequence, when entered within a debugging session, aborts the execution of a debugger command and interrupts program execution. The SET ABORT_KEY command enables you to assign the abort function to another Ctrl-key sequence. The SHOW ABORT_KEY command identifies the Ctrl-key sequence currently in effect for the abort function.

Related commands:

Ctrl/C
SET ABORT_KEY

Example

DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> SET ABORT_KEY = CTRL_P
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_P
DBG>
      

In this example, the first SHOW ABORT_KEY command identifies the default abort command key sequence, Ctrl/C. The SET ABORT_KEY = CTRL_P command assigns the abort-command function to Ctrl/P, as confirmed by the second SHOW ABORT_KEY command.

Indicates whether delivery of asynchronous system traps (ASTs) is enabled or disabled.

Format

SHOW AST

Description

The SHOW AST command indicates whether delivery of ASTs is enabled or disabled. The command does not identify an AST whose delivery is pending. The delivery of ASTs is enabled by default and with the ENABLE AST command. The delivery of ASTs is disabled with the DISABLE AST command.

Related commands:

(ENABLE,DISABLE) AST

Example

DBG> SHOW AST
ASTs are enabled
DBG> DISABLE AST
DBG> SHOW AST
ASTs are disabled
DBG>
      

The SHOW AST command indicates whether the delivery of ASTs is enabled.

Identifies the default file specification established with the last SET ATSIGN command. The debugger uses this file specification when processing the execute procedure (@) command.

Format

SHOW ATSIGN

Description

Related commands:

@ (Execute Procedure)
SET ATSIGN

Examples

DBG> SHOW ATSIGN
No indirect command file default in effect, using DEBUG.COM
DBG>
      

This example shows that if you did not use the SET ATSIGN command, the debugger assumes command procedures have the default file specification SYS$DISK:[]DEBUG.COM.

DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SHOW ATSIGN
Indirect command file default is USER:[JONES.DEBUG].DBG
DBG>
      

In this example, the SHOW ATSIGN command indicates the default file specification for command procedures, as previously established with the SET ATSIGN command.

Displays information about breakpoints.

Format

SHOW BREAK

Qualifiers

/PREDEFINED

Displays information about predefined breakpoints.

/USER

Displays information about user-defined breakpoints.

Description

The SHOW BREAK command displays information about breakpoints that are currently set, including any options such as WHEN or DO clauses, /AFTER counts, and so on, and whether the breakpoints are deactivated.

By default, SHOW BREAK displays information about both user-defined and predefined breakpoints (if any). This is equivalent to entering the SHOW BREAK/USER/PREDEFINED command. User-defined breakpoints are set with the SET BREAK command. Predefined breakpoints are set automatically when you start the debugger, and they depend on the type of program you are debugging.

If you established a breakpoint using SET BREAK/AFTER:n, the SHOW BREAK command displays the current value of the decimal integer n, that is, the originally specified integer value minus 1 for each time the breakpoint location was reached. (The debugger decrements n each time the breakpoint location is reached until the value of n is 0, at which time the debugger takes break action.)

On Alpha systems, the SHOW BREAK command does not display individual instructions when the break is on a particular class of instruction (as with SET BREAK/CALL or SET BREAK/RETURN).

Related commands:

(ACTIVATE,CANCEL,DEACTIVATE,SET) BREAK

Examples

DBG> SHOW BREAK
breakpoint at SUB1\LOOP
breakpoint at MAIN\MAIN+1F
   do (EX SUB1\D ; EX/SYMBOLIC PSL; GO)
breakpoint at routine SUB2\SUB2
   /after: 2
DBG>
      

The SHOW BREAK command identifies all breakpoints that are currently set. This example indicates user-defined breakpoints that are triggered whenever execution reaches SUB1\LOOP, MAIN\MAIN, and SUB2\SUB2, respectively.

DBG> SHOW BREAK/PREDEFINED
predefined breakpoint on Ada event "DEPENDENTS_EXCEPTION"
   for any value
predefined breakpoint on Ada event "EXCEPTION_TERMINATED"
   for any value
DBG>
      

This command identifies the predefined breakpoints that are currently set. The example shows two predefined breakpoints, which are associated with Ada tasking exception events. These breakpoints are set automatically by the debugger for all Ada programs and for any mixed language program that is linked with an Ada module.

Identifies the currently active routine calls.

Format

SHOW CALLS [integer]

Parameters

integer

A decimal integer that specifies the number of routine calls to be identified. If you omit the parameter, the debugger identifies all routine calls for which it has information.

Qualifiers

/IMAGE

Displays the image name for each active call on the call stack.

Description

The SHOW CALLS command shows a traceback that lists the sequence of active routine calls that lead to the routine in which execution is currently suspended. Any recursive routine calls are shown in the display, so you can use the SHOW CALLS command to examine the chain of recursion.

SHOW CALLS displays one line of information for each call frame on the call stack, starting with the most recent call. The top line identifies the currently executing routine, the next line identifies its caller, the following line identifies the caller of the caller, and so on.

Even if your program contains no routine calls, the SHOW CALLS command displays an active call. The reason for this is that your program has a stack frame built for it when it is first activated. Thus, if the SHOW CALLS display shows no active calls, either your program has terminated or the call stack has been corrupted.

On VAX processors, the sequence of routine calls corresponds to the sequence of call frames on the call stack. Whenever a call is made to a routine as your program executes, the operating system creates a separate call frame on the call stack. Each call frame stores information about the calling routine, for example, the PC value that enables the SHOW CALLS command to symbolize module and routine information.

On Alpha processors, a routine invocation can result in a stack frame procedure (with a call frame on the stack), a register frame procedure (with a call frame stored in the register set), or a null frame procedure (without a call frame). SHOW CALLS provides one line of information on all three: stack frame procedures, register frame procedures, and null frame procedures. (See the Alpha example below.)

The following information is provided for each line of the SHOW CALLS display:

• The name of the enclosing module. An asterisk (*) to the left of a module name indicates that the module is set.
• The name of the calling routine, provided the module is set (the first line shows the currently executing routine).
• The line number where the call was made in that routine, provided the module is set (the first line shows the line number at which execution is suspended).
• The value of the PC in the calling routine at the time that control was transferred to the called routine. On VAX processors, the PC value is shown as a memory address relative to the nearest preceding symbol value (for example, a routine) and also as an absolute address. On Alpha processors, the PC is shown as a memory address relative to the first code address in the module and also as an absolute address.
  When you specify the /IMAGE qualifier, the debugger first does a SET IMAGE command for each image that has debug information (that is, it was linked using the /DEBUG or /TRACEBACK qualifier). The debugger then displays the image name for each active call on the calls stack. The output display has been expanded and displays the image name in the first column.
  The debugger suppresses the share$image_name module name, because that information is provided by the /IMAGE qualifier.
  The SET IMAGE command lasts only for the duration of the SHOW CALLS/IMAGE command. The debugger restores the set image state when the SHOW CALLS/IMAGE command is complete.

On Alpha processors, the output of a SHOW CALLS command may include system call frames in addition to the user call frames associated with your program. System call frames appear in the following circumstances:

• When an exception occurs
• When an asynchronous system trap occurs
• When a watchpoint occurs in system space

The display of system call frames does not indicate a problem.

Related commands:

SHOW SCOPE
SHOW STACK

Examples

DBG> SHOW CALLS
module name   routine name   line      rel PC      abs PC
 SUB2         SUB2                    00000002    0000085A
*SUB1         SUB1              5     00000014    00000854
*MAIN         MAIN             10     0000002C    0000082C
DBG>

      

This command displays information about the sequence of currently active procedure calls on a VAX system.

DBG> SHOW CALLS
 module name   routine name     line          rel PC           abs PC
*MAIN           FFFF             31      00000000000002B8 00000000000203C4
-the above appears to be a null frame in the same scope as the frame below
*MAIN           MAIN             13      00000000000000A8 00000000000200A8
                                         0000000000000000 FFFFFFFF8255A1F8



      

This example is on an Alpha system. Note that sections of routine prologues and epilogues appear to the debugger to be null frames. The portion of the prologue before the change in the frame pointer (FP) and the portion of the epilogue after restoration of the FP each look like a null frame, and are reported accordingly.