 |
OpenVMS Debugger Manual
SET TRACE
Establishes a tracepoint at the location denoted by an address
expression, at instructions of a particular class, or at the occurrence
of specified events.
Format
SET TRACE [address-expression[,...]]
[WHEN(conditional-expression)]
[DO(command[;...])]
Parameters
address-expression
Specifies an address expression (a program location) at which a
tracepoint is to be set. With high-level languages, this is typically a
line number, a routine name, or a label, and can include a path name to
specify the entity uniquely. 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. Do not specify an
address expression with the following qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INTO
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/TERMINATING
The /MODIFY and /RETURN qualifiers are used with specific kinds of
address expressions.
If you specify a memory address or an address expression whose value is
not a symbolic location, check (with the EXAMINE command) that an
instruction actually begins at the byte of memory so indicated. If an
instruction does not begin at this byte, a run-time error can occur
when an instruction including that byte is executed. When you set a
tracepoint by specifying an address expression whose value is not a
symbolic location, the debugger does not verify that the location
specified marks the beginning of an instruction.
conditional-expression
Specifies a conditional expression in the currently set language that
is to be evaluated whenever execution reaches the tracepoint. (The
debugger checks the syntax of the expressions in the WHEN clause when
execution reaches the tracepoint, not when the tracepoint is set.) If
the expression is true, the debugger reports that a tracepoint has been
triggered. If an action (DO clause) is associated with the tracepoint,
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 trace action is taken. The debugger checks the syntax of the
commands in a DO clause when it executes the DO clause, not when the
tracepoint is set.
Qualifiers
/ACTIVATING
Causes the debugger to trace when a new process comes under debugger
control. See also the /TERMINATING qualifier.
/AFTER:n
Specifies that trace action not be taken until the nth time
the designated tracepoint is encountered (n is a decimal
integer). Thereafter, the tracepoint occurs every time it is
encountered provided that conditions in the WHEN clause (if specified)
are true. The SET TRACE/AFTER:1 command has the same effect as SET
TRACE.
/BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution. See also the /INTO and /OVER qualifiers.
/CALL
Causes the debugger to trace every call instruction encountered during
program execution, including the return instruction. See also the /INTO
and /OVER qualifiers.
/EVENT=event-name
Causes the debugger to trace the specified event (if that event is
defined and detected by the current event facility). If you specify an
address expression with /EVENT, causes the debugger to trace whenever
the specified event occurs for that address expression. You cannot
specify an address expression with certain event names.
Event facilities are available for programs that call Ada or SCAN
routines or that use POSIX Threads services. To identify the current
event facility and the associated event names, use the SHOW
EVENT_FACILITY command.
/EXCEPTION
Causes the debugger to trace every exception that is signaled. The
trace action occurs before any application-declared exception handlers
are invoked.
As a result of a SET TRACE/EXCEPTION command, whenever your program
generates an exception, the debugger reports the exception and
resignals the exception, thus allowing any application-declared
exception handler to execute.
/INSTRUCTION
When you do not specify an opcode, causes the debugger to trace every
instruction encountered during program execution.
See also the /INTO and /OVER qualifiers.
/INTO
(Default) Applies only to tracepoints set with the following qualifiers
(that is, when an address expression is not explicitly specified):
/BRANCH
/CALL
/INSTRUCTION
/LINE
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.
/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
/LINE
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 Alpha, 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
/LINE
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
/LINE
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.
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
/RETURN
/SYSEMULATE (Alpha 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
/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
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
|
(Integrity servers and Alpha only) Sets the default type to IEEE
X_floating (length 16 bytes).
|
|
G_FLOAT
|
Sets the default type to G_floating (length 8 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
|
(Integrity servers and Alpha only) Sets the default type to IEEE
S_Floating type (single precision, length 4 bytes).
|
|
LONG_LONG_FLOAT
|
(Integrity servers and 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
|
(Integrity servers and Alpha only) Same as LONG_FLOAT.
|
|
T_FLOAT
|
(Integrity servers and Alpha only) Same as LONG_LONG_FLOAT.
|
|
WORD
|
Sets the default type to word integer (length 2 bytes).
|
|
X_FLOAT
|
(Integrity servers and 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.
The default data type for untyped storage locations is changed from
longword (32-bits) to quadword (64-bits).
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
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.
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.
|
