 |
OpenVMS Debugger Manual
SHOW TRACE
Displays information about tracepoints.
Format
SHOW TRACE
Qualifiers
/PREDEFINED
Displays information about predefined tracepoints.
/USER
Displays information about user-defined tracepoints.
Description
The SHOW TRACE command displays information about tracepoints that are
currently set, including any options such as WHEN or DO clauses, /AFTER
counts, and so on, and whether the tracepoints are deactivated.
By default, SHOW TRACE displays information about both user-defined and
predefined tracepoints (if any). This is equivalent to entering the
SHOW TRACE/USER/PREDEFINED command. User-defined tracepoints are set
with the SET TRACE command. Predefined tracepoints are set
automatically when you start the debugger, and they depend on the type
of program you are debugging.
If you established a tracepoint using SET TRACE/AFTER:n, the
SHOW TRACE command displays the current value of the decimal integer
n, that is, the originally specified integer value minus 1 for
each time the tracepoint location was reached. (The debugger decrements
n each time the tracepoint location is reached until the value
of n is 0, at which time the debugger takes trace action.)
On Alpha systems, the SHOW TRACE command does
not display individual instructions when the trace is on a particular
class of instruction (as with SET TRACE/CALL or SET TRACE/RETURN).
Related commands:
(ACTIVATE, DEACTIVATE, SET, CANCEL) TRACE
Examples
| #1 |
DBG> SHOW TRACE
tracepoint at routine CALC\MULT
tracepoint on calls:
RET RSB BSBB JSB BSBW CALLG CALLS
DBG>
|
In this VAX example, the SHOW TRACE command identifies all tracepoints
that are currently set. This example indicates user-defined tracepoints
that are triggered whenever execution reaches routine MULT in module
CALC or one of the instructions RET, RSB, BSBB, JSB, BSBW, CALLG, or
CALLS.
| #2 |
all> SHOW TRACE/PREDEFINED
predefined tracepoint on program activation
DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_ AT H1 SOURCE
(EXAM/SOURCE .%SOURCE_SCOPE\%PC);
SET DISP/DYN/REM/SIZE:64/PROC INST_ AT H1 INST
(EXAM/INSTRUCTION .0\%PC))
predefined tracepoint on program termination
all>
|
This command identifies the predefined tracepoints that are currently
set. The example shows the predefined tracepoints that are set
automatically by the debugger for a multiprocess program. The
tracepoint on program activation triggers whenever a new process comes
under debugger control. The DO clause creates a process-specific source
display named SRC_n and a process-specific instruction display
named INST_n whenever a process activation tracepoint is
triggered. The tracepoint on program termination triggers whenever a
process does an image exit.
SHOW TYPE
Identifies the current type for program locations that do not have a
compiler-generated type or, if you specify /OVERRIDE, the current
override type.
Format
SHOW TYPE
Qualifiers
/OVERRIDE
Identifies the current override type.
Description
The current type for program locations that do not have a
compiler-generated type is the type last established by the SET TYPE
command. If you did not enter a SET TYPE command, the type for those
locations is longword integer.
The current override type for all program locations is the override
type last established by the SET TYPE/OVERRIDE command. If you did not
enter a SET TYPE/OVERRIDE command, the override type is
"none".
Related commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
EXAMINE
(SET,SHOW,CANCEL) MODE
(SET,SHOW,CANCEL) RADIX
SET TYPE
Examples
| #1 |
DBG> SET TYPE QUADWORD
DBG> SHOW TYPE
type: quadword integer
DBG>
|
In this example, you set the type to quadword for locations that do not
have a compiler-generated type. The SHOW TYPE command displays the
current default type for those locations as quadword integer. This
means that the debugger interprets and displays entities at those
locations as quadword integers unless you specify otherwise (for
example with a type qualifier on the EXAMINE command).
| #2 |
DBG> SHOW TYPE/OVERRIDE
type/override: none
DBG>
|
This command indicates that no override type has been defined.
SHOW VECTOR_MODE (VAX Only)
Identifies the current vector mode (synchronized or nonsynchronized).
Applies to VAX vectorized programs.
Format
SHOW VECTOR_MODE
Description
The current vector mode is the mode established with the SET
VECTOR_MODE command. If you did not enter a SET VECTOR_MODE command,
the default vector mode is NONSYNCHRONIZED.
Related commands:
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
SYNCHRONIZE VECTOR_MODE (VAX only)
Example
|
DBG> SHOW VECTOR_MODE
Vector mode is nonsynchronized
DBG> SET VECTOR_MODE SYNCHRONIZED
DBG> SHOW VECTOR_MODE
Vector mode is synchronized
DBG>
|
The SHOW VECTOR_MODE command indicates the effect of the SET
VECTOR_MODE command.
SHOW WATCH
Displays information about watchpoints.
Format
SHOW WATCH
Description
The SHOW WATCH command displays information about watchpoints that are
currently set, including any options such as WHEN or DO clauses, /AFTER
counts, and so on, and whether the watchpoints are deactivated.
If you established a watchpoint using SET WATCH/AFTER:n, the
SHOW WATCH command displays the current value of the decimal integer
n, that is, the originally specified integer value minus 1 for
each time the watchpoint location was reached. (The debugger decrements
n each time the watchpoint location is reached until the value
of n is 0, at which time the debugger takes watch action.)
Related commands:
(ACTIVATE,CANCEL,DEACTIVATE,SET) WATCH
Example
|
DBG> SHOW WATCH
watchpoint of MAIN\X
watchpoint of SUB2\TABLE+20
DBG>
|
This command displays two watchpoints: one at the variable X (defined
in module MAIN), and the other at the location SUB2\TABLE+20 (20 bytes
beyond the address denoted by the address expression TABLE).
SHOW WINDOW
Identifies the name and screen position of predefined and user-defined
screen-mode windows.
Note
This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
SHOW WINDOW [window-name[,...]]
Parameters
windowname
Specifies the name of a screen window definition. If you do not specify
a name, or if you specify the asterisk (*) wildcard character by
itself, all window definitions are listed. You can use the wildcard
within a window name. Do not specify a window definition name with the
/ALL qualifier.
Qualifiers
/ALL
Lists all window definitions.
Description
Related commands:
(SHOW,CANCEL) DISPLAY
(SET,SHOW) TERMINAL
(SET,CANCEL) WINDOW
SHOW SELECT
Example
|
DBG> SHOW WINDOW LH*,RH*
window LH1 at (1,11,1,40)
window LH12 at (1,23,1,40)
window LH2 at (13,11,1,40)
window RH1 at (1,11,42,39)
window RH12 at (1,23,42,39)
window RH2 at (13,11,42,39)
DBG>
|
This command displays the name and screen position of all screen window
definitions whose names start with LH or RH.
SPAWN
Creates a subprocess, enabling you to execute DCL commands without
terminating a debugging session or losing your debugging context.
Note
This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
SPAWN [DCL-command]
Parameters
DCL-command
Specifies a DCL command which is then executed in a subprocess. Control
is returned to the debugging session when the DCL command terminates.
If you do not specify a DCL command, a subprocess is created and you
can then enter DCL commands. Either logging out of the spawned process
or attaching to the parent process (with the DCL command ATTACH)
returns you to your debugging session.
If the DCL command contains a semicolon, you must enclose the command
in quotation marks ("). Otherwise the semicolon is interpreted as
a debugger command separator. To include a quotation mark in the
string, enter two consecutive quotation marks ("").
Qualifiers
/INPUT=file-spec
Specifies an input DCL command procedure containing one or more DCL
commands to be executed by the spawned subprocess. The default file
type is .COM. If you specify a DCL command string with the SPAWN
command and an input file with /INPUT, the command string is processed
before the input file. After processing of the input file is complete,
the subprocess is terminated. Do not use the asterisk (*) wildcard
character in the file specification.
/OUTPUT=file-spec
Writes the output from the SPAWN operation to the specified file. The
default file type is .LOG. Do not use the asterisk (*) wildcard
character in the file specification.
/WAIT (default)
/NOWAIT
Controls whether the debugging session (the parent process) is
suspended while the subprocess is running. The /WAIT qualifier
(default) suspends the debugging session until the subprocess is
terminated. You cannot enter debugger commands until control returns to
the parent process.
The /NOWAIT qualifier executes the subprocess in parallel with the
debugging session. You can enter debugger commands while the subprocess
is running. If you use /NOWAIT, you should specify a DCL command with
the SPAWN command; the DCL command is then executed in the subprocess.
A message indicates when the spawned subprocess completes.
The kept debugger (that is, the debugger invoked with the DCL command
DEBUG/KEEP)
shares I/O channels with the parent process when it is run by a
SPAWN/NOWAIT command. Therefore, in the Compaq DECwindows Motif for OpenVMS user interface,
you must press the Return key twice on the DECterm from which the
debugger was run after the debugger version number has appeared in the
command view.
Optionally, you can execute the kept debugger in the following manner:
$ DEFINE DBG$INPUT NL:
$ SPAWN/NOWAIT RUN DEBUG/KEEP
|
Description
The SPAWN command acts exactly like the DCL command SPAWN. You can edit
files, compile programs, read mail, and so on without ending your
debugging session or losing your current debugging context.
In addition, you can spawn a DCL command SPAWN. DCL processes the
second SPAWN command, including any qualifier specified with that
command.
Related command:
ATTACH
Examples
This example shows that the SPAWN command, without a parameter, creates
a subprocess at DCL level. You can now enter DCL commands. Log out to
return to the debugger prompt.
| #2 |
DBG> SPAWN/NOWAIT/INPUT=READ_NOTES/OUTPUT=0428NOTES
|
This command creates a subprocess that is executed in parallel with the
debugging session. This subprocess executes the DCL command procedure
READ_NOTES.COM. The output from the spawned operation is written to the
file 0428NOTES.LOG.
| #3 |
DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM
|
This command creates a subprocess that is executed in parallel with the
debugging session. This subprocess creates another subprocess to
execute the DCL command procedure MYCOM.COM. The output from that
operation is written to the file MYCOM.LOG.
STEP
Executes the program up to the next line, instruction, or other
specified location.
Format
STEP [integer]
Parameters
integer
A decimal integer that specifies the number of step units (lines,
instructions, and so on) to be executed. If you omit the parameter, the
debugger executes one step unit.
Qualifiers
/BRANCH
Executes the program to the next branch instruction. STEP/BRANCH has
the same effect as SET BREAK/TEMPORARY/BRANCH;GO.
/CALL
Executes the program to the next call or return instruction. STEP/CALL
has the same effect as SET BREAK/TEMPORARY/CALL;GO.
/EXCEPTION
Executes the program to the next exception, if any. STEP/EXCEPTION has
the same effect as SET BREAK/TEMPORARY/EXCEPTION;GO. If no exception
occurs, STEP/EXCEPTION has the same effect as GO.
/INSTRUCTION
/INSTRUCTION=(opcode[,...])
When you do not specify an opcode, executes the program to the next
instruction. STEP/INSTRUCTION has the same effect as SET
BREAK/TEMPORARY/INSTRUCTION;GO.
On VAX processors, you can specify one or more opcodes; the debugger
executes the program to the next instruction whose opcode is in the
list. The following commands are equivalent:
DBG> STEP/INSTRUCTION=(opcode[,...])
DBG> SET BREAK/TEMPORARY/INSTRUCTION=(opcode[,...]);GO
|
On VAX processors, you can specify vector instructions; do not include
an instruction qualifier (/UNALIGNED_DATA, /VECTOR_INSTRUCTION,
/MODIFY, /0, or /1) with the instruction mnemonic.
/INTO
If execution is currently suspended at a routine call, STEP/INTO
executes the program up to the beginning of that routine (steps into
that routine). Otherwise, STEP/INTO has the same effect as STEP without
a qualifier. The /INTO qualifier is the opposite of /OVER (the default
behavior).
Note
On Alpha processors, when execution is stopped at an exception break,
STEP/INTO does not transfer control to a user exception handler. Stop
execution within the handler by setting a breakpoint in the handler.
|
The STEP/INTO behavior can be changed by also using the /[NO]JSB,
/[NO]SHARE, and /[NO]SYSTEM qualifiers.
/JSB
/NOJSB
(VAX only) Qualifies a previous SET STEP INTO command or a current
STEP/INTO command.
If execution is currently suspended at a routine call and the routine
is called by a JSB instruction, STEP/INTO/NOJSB has the same effect as
STEP/OVER. Otherwise, STEP/INTO/NOJSB has the same effect as STEP/INTO.
Use STEP/INTO/JSB to override a previous SET STEP NOJSB command.
STEP/INTO/JSB enables STEP/INTO to step into routines called by a JSB
instruction, as well as into routines called by a CALL instruction.
The /JSB qualifier is the default for all languages except DIBOL. The
/NOJSB qualifier is the default for DIBOL. In DIBOL,
application-declared routines are called by the CALL instruction and
DIBOL Run-Time Library routines are called by the JSB instruction.
/LINE
Executes the program to the next line of source code. However, the
debugger skips over any source lines that do not result in executable
code when compiled (for example, comment lines). STEP/LINE has the same
effect as SET BREAK/TEMPORARY/LINE;GO. This is the default behavior for
all languages.
/OVER
If execution is currently suspended at a routine call, STEP/OVER
executes the routine up to and including the routine's return
instruction (steps over that routine). The /OVER qualifier is the
default behavior and is the opposite of /INTO.
Note
On Alpha processors, when execution is suspended at a source line that
contains a loop with a routine call, STEP/OVER steps into the called
routine. To step to the next program statement, set a temporary
breakpoint at the statement and enter GO.
|
/RETURN
Executes the routine in which execution is currently suspended up to
its return instruction (that is, up to the point just prior to
transferring control back to the calling routine). This enables you to
inspect the local environment (for example, obtain the values of local
variables) before the return instruction deletes the routine's call
frame from the call stack. STEP/RETURN has the same effect as SET
BREAK/TEMPORARY/RETURN;GO.
STEP/RETURN n executes the program up n levels of the
call stack.
/SEMANTIC_EVENT
(Alpha only) Executes the program to the next semantic event.
STEP/SEMANTIC_EVENT simplifies debugging optimized code. (See the
Description section.)
/SHARE (default)
/NOSHARE
Qualifies a previous SET STEP INTO command or a current STEP/INTO
command.
If execution is currently suspended at a call to a shareable image
routine, STEP/INTO/NOSHARE has the same effect as STEP/OVER. Otherwise,
STEP/INTO/NOSHARE has the same effect as STEP/INTO.
Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE command.
STEP/INTO/SHARE enables STEP/INTO to step into shareable image
routines, as well as into other kinds of routines.
/SILENT
/NOSILENT (default)
Controls whether the "stepped to..." message and the source
line for the current location are displayed after the STEP has
completed. 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
after the STEP has completed. 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 a previous SET STEP INTO command or a current STEP/INTO
command.
If execution is currently suspended at a call to a system routine (in
P1 space), STEP/INTO/NOSYSTEM has the same effect as STEP/OVER.
Otherwise, STEP/INTO/NOSYSTEM has the same effect as STEP/INTO.
Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM command.
STEP/INTO/SYSTEM enables STEP/INTO to step into system routines, as
well as into other kinds of routines.
/VECTOR_INSTRUCTION
(VAX only) Executes the program to the next vector instruction.
STEP/VECTOR_INSTRUCTION has the same effect as SET
BREAK/TEMPORARY/VECTOR_INSTRUCTION;GO.
Description
The STEP command is one of the four debugger commands that can be used
to execute your program (the others are CALL, EXIT, and GO).
The behavior of the STEP command depends on the following factors:
- The default STEP mode previously established with a SET STEP
command, if any
- The qualifier specified with the STEP command, if any
- The number of step units specified as the parameter to the STEP
command, if any
If no SET STEP command was previously entered, the debugger takes the
following default actions when you enter a STEP command without
specifying a qualifier or parameter:
- Executes a line of source code (the default is STEP/LINE).
- Reports that execution has completed by issuing a "stepped to
..." message (the default is STEP/NOSILENT).
- Displays the line of source code at which execution is suspended
(the default is STEP/SOURCE).
- Issues the prompt.
The following qualifiers affect the location to which you step:
/BRANCH
/CALL
/EXCEPTION
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
/RETURN
/SEMANTIC_EVENT (Alpha only)
/VECTOR_INSTRUCTION (VAX only)
The following qualifiers affect what output is seen upon completion of
a step:
/[NO]SILENT
/[NO]SOURCE
The following qualifiers affect what happens at a routine call:
/INTO
/[NO]JSB (VAX only)
/OVER
/[NO]SHARE
/[NO]SYSTEM
If you plan to enter several STEP commands with the same qualifiers,
you can first use the SET STEP command to establish new default
qualifiers (for example, SET STEP INTO, NOSYSTEM makes the STEP command
behave like STEP/INTO/NOSYSTEM). Then you do not have to use those
qualifiers with the STEP command. You can override the current default
qualifiers for the duration of a single STEP command by specifying
other qualifiers. Use the SHOW STEP command to identify the current
STEP defaults.
If an exception breakpoint is triggered (resulting from a SET
BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is suspended
before any application-declared condition handler is started. If you
then resume execution with the STEP command, the debugger resignals the
exception and the program executes to the beginning of (steps into) the
condition handler, if any.
On Alpha systems, if your program has been compiled with the /OPTIMIZE
qualifier, semantic stepping mode is available, with the
STEP/SEMANTIC_EVENT and SET STEP SEMANTIC_EVENT commands. When you are
debugging optimized code, the apparent source program location tends to
bounce back and forth, with the same line appearing repeatedly. In
semantic stepping mode, the program executes to the next point in the
program where a significant effect (semantic event) occurs.
A semantic event is one of the following:
- Data event --- An assignment to a user variable
- Control event --- A control flow decision, with a conditional or
unconditional transfer of control, other than a call
- Call event --- A call (to a routine that is not stepped over) or a
return from a call
Not every assignment, transfer of control, or call is a semantic event.
The major exceptions are as follows:
- When two instructions are required to assign to a complex or
X_floating value, only the first instruction is treated as a semantic
event.
- When there are multiple branches that are part of a single
higher-level construct, such as a decision tree of branches that
implement a case or select construct, then only the first is treated as
a semantic event.
- When a call is made to a routine that is a compiler-specific helper
routine, such as a call to OTS$MOVE, which handles certain kinds of
string or storage copy operations, the call is not considered a
semantic event. Control will not stop at the call.
To step into
such a routine, you must do either of the following:
- Set a breakpoint at the routine entry point.
- Use a series of STEP/INSTRUCTION commands to reach the call of
interest and then use STEP/INSTRUCTION/INTO to enter the called routine.
- When there is more than one potential semantic event in a row with
the same line number, only the first is treated as a semantic event.
The STEP/SEMANTIC_EVENT command causes a breakpoint to be set at the
next semantic event. Execution proceeds to that next event. Parts of
any number of different lines and statements may be executed along the
way, without interfering with progress. When the semantic event is
reached (that is, when the instruction associated with that event is
reached but not yet executed), execution is suspended (similar to
reaching the next line when STEP/LINE is used).
For more information on debugging optimized programs, see
Chapter 14.
If you are debugging a multiprocess program, the STEP command is
executed in the context of the current process set. In addition, when
debugging a multiprocess program, the way in which execution continues
in your process depends on whether you entered a SET MODE [NO]INTERRUPT
command or a SET MODE [NO]WAIT command. By default (SET MODE
NOINTERRUPT), when one process stops, the debugger takes no action with
regard to the other processes. Also by default (SET MODE WAIT), the
debugger waits until all process in the current process set have
stopped before prompting for a new command. See Chapter 15 for more
information.
|
