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[; . . . ])]
1 – 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.
2 – Qualifiers
2.1 /ACTIVATING
Causes the debugger to trace when a new process comes under
debugger control. See also the /TERMINATING qualifier.
2.2 /AFTER
/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.
2.3 /BRANCH
Causes the debugger to trace every branch instruction encountered
during program execution. See also the /INTO and /OVER
qualifiers.
2.4 /CALL
Causes the debugger to trace every call instruction encountered
during program execution, including the return instruction. See
also the /INTO and /OVER qualifiers.
2.5 /EVENT
/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.
2.6 /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.
2.7 /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.
2.8 /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.
2.9 /LINE
Causes the debugger to trace the beginning of each source line
encountered during program execution. See also the /INTO and
/OVER qualifiers.
2.10 /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.
2.11 /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).
2.12 /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
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.
2.13 /SHARE
/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.
2.14 /SILENT
/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.
2.15 /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.
2.16 /SYSTEM
/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.
2.17 /TEMPORARY
Causes the tracepoint to disappear after it is triggered (the
tracepoint does not remain permanently set).
2.18 /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.
3 – Description
When a tracepoint is triggered, the debugger takes the following
actions:
1. Suspends program execution at the tracepoint location.
2. 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.
3. 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.
4. Reports that execution has reached the tracepoint location by
issuing a "trace . . . " message, unless you specified /SILENT.
5. 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.
6. Executes the commands in a DO clause, if you specified one
when you set the tracepoint.
7. 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
4 – Description (Continued...)
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
5 – 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.