OpenVMS Debugger Manual

Document revision date: 19 July 1999

OpenVMS Debugger Manual

Contents

Index

When used with those qualifiers, /INTO causes the debugger to trace the specified points within called routines (as well as within the routine in which execution is currently suspended). The /INTO qualifier is the default and is the opposite of /OVER.

When using /INTO, you can further qualify the trace action with the /[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM qualifiers.

/JSB

/NOJSB

(VAX only) Qualifies /INTO. Use with /INTO and one of the following qualifiers:

/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...])
/LINE
/VECTOR_INSTRUCTION

The /JSB qualifier is the default for all languages except DIBOL. It lets the debugger set tracepoints within routines that are called by the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies that tracepoints not be set within routines called by JSB instructions. In DIBOL, application-declared routines are called by the CALL instruction and DIBOL Run-Time Library routines are called by the JSB instruction.

/LINE

Causes the debugger to trace the beginning of each source line encountered during program execution. See also the /INTO and /OVER qualifiers.

/MODIFY

Causes the debugger to trace when an instruction writes to and changes the value of a location indicated by a specified address expression. The address expression is typically a variable name.

The SET TRACE/MODIFY X command is equivalent to SET WATCH X DO(GO). The SET TRACE/MODIFY command operates under the same restrictions as SET WATCH.

If you specify an absolute address for the address expression, the debugger might not be able to associate the address with a particular data object. In this case, the debugger uses a default length of 4 bytes. 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). The SET TYPE LONGWORD command restores the default length of 4 bytes.

/OVER

Applies only to tracepoints set with the following qualifiers (that is, when an address expression is not explicitly specified):

/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)

When used with those qualifiers, /OVER causes the debugger to trace the specified points only within the routine in which execution is currently suspended (not within called routines). The /OVER qualifier is the opposite of /INTO (which is the default).

/RETURN

Causes the debugger to break on the return instruction of the routine associated with the specified address expression (which can be a routine name, line number, and so on). Breaking on the return instruction enables you to inspect the local environment (for example, obtain the values of local variables) while the routine is still active. Note that the view of a local environment may differ depending on your architecture. On VAX processors, this qualifier can only be applied to routines called with a CALLS or CALLG instruction; it cannot be used with JSB routines. On Alpha processors, this qualifier can be applied to any routine.

The address-expression parameter is an instruction address within a routine. It can simply be a routine name, in which case it specifies the routine start address. However, you can also specify another location in a routine, so you can see only those returns that are taken after a certain code path is followed.

A SET TRACE/RETURN command cancels a previous SET TRACE if you specify the same address expression.

/SHARE (default)

/NOSHARE

Qualifies /INTO. Use with /INTO and one of the following qualifiers:

/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)

The /SHARE qualifier permits the debugger to set tracepoints within shareable image routines as well as other routines. The /NOSHARE qualifier specifies that tracepoints not be set within shareable images.

/SILENT

/NOSILENT (default)

Controls whether the "trace..." message and the source line for the current location are displayed at the tracepoint. 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

/NOSOURCE (default)

Controls whether the source line for the current location is displayed at the tracepoint. 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.

/SYSTEM (default)

/NOSYSTEM

Qualifies /INTO. Use with /INTO and one of the following qualifiers:

/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/VECTOR_INSTRUCTION (VAX only)

The /SYSTEM qualifier permits the debugger to set tracepoints within system routines (P1 space) as well as other routines. The /NOSYSTEM qualifier specifies that tracepoints not be set within system routines.

/TEMPORARY

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

/TERMINATING

(Default) Causes the debugger to trace when a process does an image exit. The debugger gains control and displays its prompt when the last image of a one-process or multiprocess program exits. See also the /ACTIVATING qualifier.

/VECTOR_INSTRUCTION

(VAX only) Causes the debugger to trace every vector instruction encountered during execution. See also the /INTO and /OVER qualifiers.

Description

When a tracepoint is triggered, the debugger takes the following actions:

Suspends program execution at the tracepoint location.
If you specified /AFTER when you set the tracepoint, checks the AFTER count. If the specified number of counts has not been reached, execution is resumed and the debugger does not perform the remaining steps.
Evaluates the expression in a WHEN clause, if you specified one when you set the tracepoint. If the value of the expression is false, execution is resumed and the debugger does not perform the remaining steps.
Reports that execution has reached the tracepoint location by issuing a "trace..." message, unless you specified /SILENT.
Displays the line of source code corresponding to the tracepoint, unless you specified /NOSOURCE or /SILENT when you set the tracepoint or entered a previous SET STEP NOSOURCE command.
Executes the commands in a DO clause, if you specified one when you set the tracepoint.
Resumes execution.

You set a tracepoint at a particular location in your program by specifying an address expression with the SET TRACE command. You set a tracepoint on consecutive source lines, classes of instructions, or events by specifying a qualifier with the SET TRACE command. Generally, you must specify either an address expression or a qualifier, but not both. Exceptions are /EVENT and /RETURN.
The /LINE qualifier sets a tracepoint on each line of source code.
The following qualifiers set tracepoints on classes of instructions. Using these qualifiers and /LINE causes the debugger to trace every instruction of your program as it executes and thus significantly slows down execution.

/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/RETURN
/SYSEMULATE (Alpha only)
/VECTOR_INSTRUCTION (VAX only)

The following qualifiers set tracepoints on classes of events:

/ACTIVATING
/EVENT=event-name
/EXCEPTION
/TERMINATING

The following qualifiers affect what happens at a routine call:

/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM

The following qualifiers affect what output is displayed when a tracepoint is reached:

/[NO]SILENT
/[NO]SOURCE

The following qualifiers affect the timing and duration of tracepoints:

/AFTER:n
/TEMPORARY

Use the /MODIFY qualifier to monitor changes at program locations (typically changes in the values of variables).
If you set a tracepoint at a location currently used as a breakpoint, the breakpoint is canceled in favor of the tracepoint, and conversely.
Tracepoints can be user defined or predefined. User-defined tracepoints are set explicitly with the SET TRACE command. Predefined tracepoints, which depend on the type of program you are debugging (for example, Ada or multiprocess), are established automatically when you start the debugger. Use the SHOW TRACE command to identify all tracepoints that are currently set. Any predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled independently. For example, a location or event can have both a user-defined and a predefined tracepoint. Canceling the user-defined tracepoint does not affect the predefined tracepoint, and conversely.
Related commands:

(ACTIVATE,DEACTIVATE,SHOW,CANCEL) TRACE
CANCEL ALL
GO
SET BREAK
(SET,SHOW) EVENT_FACILITY
SET STEP [NO]SOURCE
SET WATCH

Examples

#1
DBG> SET TRACE SUB3

This command causes the debugger to trace the beginning of routine SUB3 when that routine is executed.

#2
DBG> SET TRACE/BRANCH/CALL

This command causes the debugger to trace every BRANCH instruction and every CALL instruction encountered during program execution.

#3
DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM

This command causes the debugger to trace the beginning of every source line, including lines in called routines (/INTO) but not in shareable image routines (/NOSHARE) or system routines (/NOSYSTEM).

#4
DBG> SET TRACE/NOSOURCE TEST5\%LINE 14 WHEN (X .NE. 2) DO (EXAMINE Y)

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.

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

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

#8
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.

SET TYPE

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 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 only) Sets the default type to IEEE S_Floating type (single precision, length 4 bytes).

LONG_LONG_FLOAT (Alpha 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 only) Same as LONG_FLOAT.

T_FLOAT (Alpha only) Same as LONG_LONG_FLOAT.

WORD Sets the default type to word integer (length 2 bytes).

X_FLOAT (Alpha 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 utilize the 64-bit address space, it might be advisable to 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

#1
DBG> SET TYPE ASCII:8

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

#2
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.

#3
DBG> SET TYPE D_FLOAT

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

#4
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.

SET VECTOR_MODE (VAX only)

Enables or disables a debugger vector mode option.
Applies only to VAX vectorized programs.

Format

SET VECTOR_MODE vector-mode-option

Parameters

vector-mode-option
Specifies the vector mode option. Valid keywords are as follows:

SYNCHRONIZED Specifies that the debugger force automatic synchronization between the scalar and vector processors whenever a vector instruction is executed. Specifically, the debugger issues a SYNC instruction after every vector instruction and, in addition, an MSYNC instruction after any vector instruction that accesses memory. This forces the completion of all activities associated with the vector instruction that is being synchronized:

Any exception that was caused by a vector instruction is delivered before the next scalar instruction is executed. Forcing the delivery of a pending exception triggers an exception breakpoint or tracepoint (if one was set) or invokes an exception handler (if one is available at that location in the program).
Any read or write operation between vector registers and either the general registers or memory is completed before the next scalar instruction is executed.

The SET VECTOR_MODE SYNCHRONIZED command does not issue an immediate SYNC or MSYNC instruction at the time it is issued. To force immediate synchronization, use the SYNCHRONIZE VECTOR_MODE command.

NOSYNCHRONIZED (Default) Specifies that the debugger not force synchronization between the scalar and vector processors except for internal debugger purposes. As a result, any synchronization is controlled entirely by the program, and the program runs as if it were not under debugger control.

Description

Vector mode options control the way in which the debugger interacts with the vector processor. For details about the SET VECTOR_MODE command, see the parameter descriptions.
Related commands:

(SHOW,SYNCHRONIZE) VECTOR_MODE

Examples

#1
DBG> SET VECTOR_MODE SYNCHRONIZED

This command causes the debugger to force synchronization between the scalar and vector processors after each vector instruction is executed.

#2
DBG> SHOW VECTOR_MODE Vector mode is nonsynchronized DBG> SET VECTOR_MODE SYNCHRONIZED (1) DBG> SHOW VECTOR_MODE Vector mode is synchronized DBG> STEP (2) stepped to .MAIN.\SUB\%LINE 99 99: VVDIVD V1,V0,V2 DBG> STEP (3) %SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, mask=00000004, PC=000002E1, PSL=03C00010 break on unhandled exception preceding .MAIN.\SUB\%LINE 100 100: CLRL R0 DBG>

DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED   (1)
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
DBG> STEP   (2)
stepped to .MAIN.\SUB\%LINE 99 
    99:         VVDIVD  V1,V0,V2
DBG> STEP   (3)
%SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
                  mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%LINE 100 
   100:         CLRL    R0
DBG>

The comments that follow refer to the callouts in the previous example:

Previous Next Contents Index

privacy and legal statement

4538PRO_057.HTML

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 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 only) Sets the default type to IEEE S_Floating type (single precision, length 4 bytes).
LONG_LONG_FLOAT	(Alpha 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 only) Same as LONG_FLOAT.
T_FLOAT	(Alpha only) Same as LONG_LONG_FLOAT.
WORD	Sets the default type to word integer (length 2 bytes).
X_FLOAT	(Alpha only) Same as EXTENDED_FLOAT.