HP OpenVMS systems documentation

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.

#5
DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0)

This command causes the debugger to trace when X is not equal to 0. The condition is tested at each instruction encountered during execution. The syntax of the conditional expression in the WHEN clause is language-dependent.

DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K)
      

This command causes the debugger to trace the beginning of routine SUB2 during execution. At the tracepoint, the DO clause sets a watchpoint on variable K. The /SILENT qualifier suppresses the "trace ..." message and the display of source code at the tracepoint. This example shows a convenient way of setting a watchpoint on a nonstatic (stack or register) variable. A nonstatic variable is defined only when its defining routine (SUB2, in this case) is active (on the call stack).

DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X)
      

This command causes the debugger to trace the return instruction of routine ROUT4 (that is, just before execution returns to the calling routine). At the tracepoint, the DO clause issues the EXAMINE X command. This example shows a convenient way of obtaining the value of a nonstatic variable just before execution leaves that variable's defining routine.

DBG> SET TRACE/EVENT=TERMINATED
      

This command causes the debugger to trace the point at which any task makes a transition to the TERMINATED state.

Establishes the default type to be associated with program locations that do not have a symbolic name (and, therefore, do not have an associated compiler-generated type). When used with /OVERRIDE, it establishes the default type to be associated with all locations, overriding any compiler-generated types.

Format

SET TYPE type-keyword

Parameters

type-keyword

Specifies the default type to be established. Valid keywords are as follows:

ASCIC	Sets the default type to counted ASCII string with a 1-byte count field that precedes the string and gives its length. AC is also accepted as a keyword.
ASCID	Sets the default type to ASCII string descriptor. The CLASS and DTYPE fields of the descriptor are not checked, but the LENGTH and POINTER fields provide the character length and address of the ASCII string. The string is then displayed. AD is also accepted as a keyword.
ASCII: n	Sets the default type to ASCII character string (length n bytes). The length indicates both the number of bytes of memory to be examined and the number of ASCII characters to be displayed. If you do not specify a value for n, the debugger uses the default value of 4 bytes. The value n is interpreted in decimal radix.
ASCIW	Sets the default type to counted ASCII string with a 2-byte count field that precedes the string and gives its length. This data type occurs in Pascal and PL/I. AW is also accepted as a keyword.
ASCIZ	Sets the default type to zero-terminated ASCII string. The ending zero byte indicates the end of the string. AZ is also accepted as a keyword.
BYTE	Sets the default type to byte integer (length 1 byte).
D_FLOAT	Sets the default type to D_floating (length 8 bytes).
DATE_TIME	Sets the default type to date and time. This is a quadword integer (length 8 bytes) containing the internal representation of date and time. Values are displayed in the format dd-mmm-yyyy hh:mm:ss.cc. Specify an absolute date and time as follows: [dd-mmm-yyyy[:]] [hh:mm:ss.cc]
EXTENDED_FLOAT	(Alpha and I64 only) Sets the default type to IEEE X_floating (length 16 bytes).
FLOAT	On VAX systems, sets the default type to F_floating (length 4 bytes). On Alpha processors, sets the default type to IEEE T_floating (length 8 bytes).
G_FLOAT	Sets the default type to G_floating (length 8 bytes).
H_FLOAT	(VAX only) Sets the default type to H_floating (length 16 bytes).
INSTRUCTION	Sets the default type to instruction (variable length, depending on the number of instruction operands and the kind of addressing modes used).
LONG_FLOAT	(Alpha and I64 only) Sets the default type to IEEE S_Floating type (single precision, length 4 bytes).
LONG_LONG_FLOAT	(Alpha and I64 only) Sets the default type to IEEE T_Floating type (double precision, length 8 bytes).
LONGWORD	Sets the default type to longword integer (length 4 bytes). This is the default type for program locations that do not have a symbolic name (do not have a compiler-generated type).
OCTAWORD	Sets the default type to octaword integer (length 16 bytes).
PACKED: n	Sets the default type to packed decimal. The value of n is the number of decimal digits. Each digit occupies one nibble (4 bits).
QUADWORD	Sets the default type to quadword integer (length 8 bytes). This might be advisable for debugging 64-bit applications.
TYPE=( expression)	Sets the default type to the type denoted by expression (the name of a variable or data type declared in the program). This enables you to specify an application-declared type.
S_FLOAT	(Alpha and I64 only) Same as LONG_FLOAT.
T_FLOAT	(Alpha and I64 only) Same as LONG_LONG_FLOAT.
WORD	Sets the default type to word integer (length 2 bytes).
X_FLOAT	(Alpha and I64 only) Same as EXTENDED_FLOAT.

Qualifiers

/OVERRIDE

Associates the type specified with all program locations, whether or not they have a symbolic name (whether or not they have an associated compiler-generated type).

Description

When you use EXAMINE, DEPOSIT, or EVALUATE commands, the default types associated with address expressions affect how the debugger interprets and displays program entities.

The debugger recognizes the compiler-generated types associated with symbolic address expressions (symbolic names declared in your program), and it interprets and displays the contents of these locations accordingly. For program locations that do not have a symbolic name and, therefore, no associated compiler-generated type, the default type in all languages is longword integer, which is appropriate for debugging 32-bit applications.

On Alpha systems, when debugging applications that use the 64-bit address space, you should use the SET TYPE QUADWORD command.

The SET TYPE command enables you to change the default type associated with locations that do not have a symbolic name. The SET TYPE/OVERRIDE command enables you to set a default type for all program locations, both those that do and do not have a symbolic name.

The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII, /BYTE, /G_FLOAT, and so on) which enable you to override, for the duration of a single command, the type previously associated with any program location.

Related commands:

CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW,CANCEL) MODE
SHOW TYPE

Examples

DBG> SET TYPE ASCII:8
      

This command establishes an 8-byte ASCII character string as the default type associated with untyped program locations.

DBG> SET TYPE/OVERRIDE LONGWORD
      

This command establishes longword integer as the default type associated with both untyped program locations and program locations that have compiler-generated types.

DBG> SET TYPE D_FLOAT
      

This command establishes D_Floating as the default type associated with untyped program locations.

DBG> SET TYPE TYPE=(S_ARRAY)
      

This command establishes the type of the variable S_ARRAY as the default type associated with untyped program locations.

Establishes a watchpoint at the location denoted by an address expression.

Format

SET WATCH address-expression[,...]
[WHEN(conditional-expression)]
[DO(command[;...])]

Parameters

address-expression

Specifies an address expression (a program location) at which a watchpoint is to be set. With high-level languages, this is typically the name of a program variable and can include a path name to uniquely specify the variable. More generally, an address expression can also be a memory address or a register and can be composed of numbers (offsets) and symbols, as well as one or more operators, operands, or delimiters. For information about the operators that you can use in address expressions, type Help Address_Expressions.

Do not specify the asterisk (*) wildcard character.

conditional-expression

Specifies a conditional expression in the currently set language; the expression is to be evaluated whenever execution reaches the watchpoint. (The debugger checks the syntax of the expressions in the WHEN clause when execution reaches the watchpoint, not when the watchpoint is set.) If the expression is true, the debugger reports that a watchpoint has been triggered. If an action (DO clause) is associated with the watchpoint, it will occur at this time. If the expression is false, a report is not issued, the commands specified by the DO clause (if one was specified) are not executed, and program execution is continued.

command

Specifies a debugger command to be executed as part of the DO clause when watch action is taken. The debugger checks the syntax of the commands in a DO clause when it executes the DO clause, not when the watchpoint is set.

Qualifiers

/AFTER:n

Specifies that watch action not be taken until the nth time the designated watchpoint is encountered (n is a decimal integer). Thereafter, the watchpoint occurs every time it is encountered provided that conditions in the WHEN clause are true. The SET WATCH/AFTER:1 command has the same effect as SET WATCH.

/INTO

Specifies that the debugger is to monitor a nonstatic variable by tracing instructions not only within the defining routine, but also within a routine that is called from the defining routine (and any other such nested calls). The SET WATCH/INTO command enables you to monitor nonstatic variables within called routines more precisely than SET WATCH/OVER; but the speed of execution within called routines is faster with SET WATCH/OVER.

/OVER

Specifies that the debugger is to monitor a nonstatic variable by tracing instructions only within the defining routine, not within a routine that is called by the defining routine. As a result, the debugger executes a called routine at normal speed and resumes tracing instructions only when execution returns to the defining routine. The SET WATCH/OVER command provides faster execution than SET WATCH/INTO; but if a called routine modifies the watched variable, execution is interrupted only upon returning to the defining routine. When you set watchpoints on nonstatic variables, SET WATCH/OVER is the default.

/SILENT

/NOSILENT (default)

Controls whether the "watch..." message and the source line for the current location are displayed at the watchpoint. The /NOSILENT qualifier specifies that the message is displayed. The /SILENT qualifier specifies that the message and source line are not displayed. The /SILENT qualifier overrides /SOURCE.

/SOURCE (default)

/NOSOURCE

Controls whether the source line for the current location is displayed at the watchpoint. The /SOURCE qualifier specifies that the source line is displayed. The /NOSOURCE qualifier specifies that the source line is not displayed. The /SILENT qualifier overrides /SOURCE. See also the SET STEP [NO]SOURCE command.

/STATIC

/NOSTATIC

Enables you to override the debugger's default determination of whether a specified variable (watchpoint location) is static or nonstatic. The /STATIC qualifier specifies that the debugger should treat the variable as a static variable, even though it might be allocated in P1 space. This causes the debugger to monitor the location by using the faster write-protection method rather than by tracing every instruction. The /NOSTATIC qualifier specifies that the debugger should treat the variable as a nonstatic variable, even though it might be allocated in P0 space, and causes the debugger to monitor the location by tracing every instruction. Be careful when using these qualifiers.

/TEMPORARY

Causes the watchpoint to disappear after it is triggered (the watchpoint does not remain permanently set).

Description

When an instruction causes the modification of a watchpoint location, the debugger takes the following actions:

1. Suspends program execution after that instruction has completed execution.
2. 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.
3. 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.
4. Reports that execution has reached the watchpoint location ("watch of...") unless you specified /SILENT.
5. Reports the old (unmodified) value at the watchpoint location.
6. Reports the new (modified) value at the watchpoint location.
7. 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.
8. 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.
9. 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,

SET WATCH 30000:300018

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

Examples

DBG> SET WATCH MAXCOUNT
      

---

Previous

Next

Contents

Index