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:

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

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

DBG> SET TRACE SUB3
      

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

DBG> SET TRACE/BRANCH/CALL
      

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

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

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.

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

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.