 |
HP OpenVMS Debugger Manual
SDA
Invokes the System Dump Analyzer (SDA) from within the OpenVMS debugger
without terminating a debugger session.
Format
SDA [sda-command]
Parameters
sda-command
One SDA command to be executed before returning control to the OpenVMS
debugger.
Description
The SDA command allows you to use the System Dump Analyzer (SDA) within
the debugger for the following tasks:
- System code debugging with the System Code Debugger (SCD) (Alpha
and I64 only)
- System dump analysis with the System Dump Debugger (SDD) (Alpha and
I64 only)
- Process dump analysis with the System Dump Analyzer (SDA) (Alpha
and I64 only)
This gives you access to all SDA commands within the debugging session.
When you exit SDA, you return to the same debugging session. Note that
you do not have access to debugger commands within the SDA session.
Note
The SDA command is not available when debugging user-mode programs.
|
Related commands
ANALYZE/CRASH_DUMP
ANALYZE/PROCESS_DUMP
CONNECT %NODE
Example
|
DBG> SDA
OpenVMS (TM) Alpha process dump analyzer
SDA> ..
.
.
SDA> EXIT
DBG>
|
This example opens an SDA session within the OpenVMS debugger, performs
some analysis, closes the SDA session and returns control to the
debugger.
|
DBG> SDA SHOW PROCESS
.
.
DBG>
|
This example show the execution of a single SDA command from within the
debugger, followed by a return of control to the debugger.
SELECT
Selects a screen display as the current error, input, instruction,
output, program, prompt, scrolling, or source display.
Note
This command is not available in the HP DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
SELECT [display-name]
Parameters
display-name
Specifies the display to be selected. You can specify any one of the
following, with the restrictions noted in the qualifier descriptions:
- A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Alpha and I64 only)
IREG
- A display previously created with the DISPLAY command
- A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you omit this parameter and do not specify a qualifier, you
"unselect" the current scrolling display (no display then has
the scrolling attribute). If you omit this parameter but specify a
qualifier (/INPUT, /SOURCE, and so on), you unselect the current
display with that attribute (see the qualifier descriptions).
Qualifiers
/ERROR
Selects the specified display as the current error display. This causes
all debugger diagnostic messages to go to that display. The display
specified must be either an output display or the PROMPT display. If
you do not specify a display, this qualifier selects the PROMPT display
current error display. By default, the PROMPT display has the error
attribute.
/INPUT
Selects the specified display as the current input display. This causes
that display to echo debugger input (which appears in the PROMPT
display). The display specified must be an output display.
If you do not specify a display, the current input display is
unselected and debugger input is not echoed to any display (debugger
input appears only in the PROMPT display). By default, no display has
the input attribute.
/INSTRUCTION
Selects the specified display as the current instruction display. This
causes the output of all EXAMINE/INSTRUCTION commands to go to that
display. The display specified must be an instruction display.
If you do not specify a display, the current instruction display is
unselected and no display has the instruction attribute.
By default, for all languages except MACRO--32, no display has the
instruction attribute. If the language is set to MACRO--32, the INST
display has the instruction attribute by default.
/OUTPUT
Selects the specified display as the current output display. This
causes debugger output that is not already directed to another display
to go to that display. The display specified must be either an output
display or the PROMPT display.
If you do not specify a display, the PROMPT display is selected as the
current output display. By default, the OUT display has the output
attribute.
/PROGRAM
Selects the specified display as the current program
display. This causes the debugger to try to force program
input and output to that display. Currently, only the PROMPT display
can be specified.
If you do not specify a display, the current program display is
unselected and program input and output are no longer forced to the
specified display.
By default, the PROMPT display has the program attribute, except on
workstations, where the program attribute is unselected.
/PROMPT
Selects the specified display as the current prompt
display. This is where the debugger prompts for input.
Currently, only the PROMPT display can be specified. Moreover, you
cannot unselect the PROMPT display (the PROMPT display always has the
prompt attribute).
/SCROLL
(Default) Selects the specified display as the current scrolling
display. This is the default display for the SCROLL, MOVE, and EXPAND
commands. Although any display can have the scroll attribute, you can
use only the MOVE and EXPAND commands (not the SCROLL command) with the
PROMPT display.
If you do not specify a display, the current scrolling display is
unselected and no display has the scroll attribute.
By default, for all languages except MACRO-32, the SRC display has the
scroll attribute. If the language is set to MACRO-32, the INST display
has the scroll attribute by default.
/SOURCE
Selects the specified display as the current source display. This
causes the output of all TYPE and EXAMINE/SOURCE commands to go to that
display. The display specified must be a source display.
If you do not specify a display, the current source display is
unselected and no display has the source attribute.
By default, for all languages except MACRO--32, the SRC display has the
source attribute. If the language is set to MACRO--32, no display has
the source attribute by default.
Description
Attributes are used to select the current scrolling display and to
direct various types of debugger output to particular displays. This
gives you the option of mixing or isolating different types of
information, such as debugger input, output, diagnostic messages, and
so on in scrollable displays.
Use the SELECT command with one or more qualifiers (/ERROR, /SOURCE,
and so on) to assign one or more corresponding attributes to a display.
By default, if you do not specify a qualifier, /SCROLL is assumed.
If you use the SELECT command without specifying a display name, the
attribute assignment indicated by the qualifier is canceled
(unselected). To reassign display attributes, you must use another
SELECT command. For more information, see the individual qualifier.
For a list of the key definitions associated with the SELECT command,
type Help Keypad_Definitions_CI. Also, use the SHOW KEY command to
determine the current key definitions.
Related commands:
DISPLAY
EXPAND
MOVE
SCROLL
SHOW SELECT
Examples
| #1 |
DBG> SELECT/SOURCE/SCROLL SRC2
|
This command selects display SRC2 as the current source and scrolling
display.
| #2 |
DBG> SELECT/INPUT/ERROR OUT
|
This command selects display OUT as the current input and error
display. This causes debugger input, debugger output (assuming OUT is
the current output display), and debugger diagnostic messages to be
logged in the OUT display in the correct sequence.
This command unselects (deletes the source attribute from) the
currently selected source display. The output of a TYPE or
EXAMINE/SOURCE command then goes to the currently selected output
display.
SET ABORT_KEY
Assigns the debugger's abort function to another Ctrl-key sequence. By
default, Ctrl/C does the abort function.
Note
This command is not available in the HP DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
SET ABORT_KEY = CTRL_character
Parameters
character
Specifies the key you press while holding down the Ctrl key. You can
specify any alphabetic character.
Description
By default, the Ctrl/C sequence, when entered within a debugging
session, aborts the execution of a debugger command and interrupts
program execution. The SET ABORT_KEY command enables you to assign the
abort function to another Ctrl-key sequence. This might be necessary if
your program has a Ctrl/C AST service routine enabled.
Many Ctrl-key sequences have predefined functions, and the SET
ABORT_KEY command enables you to override such definitions (see the
OpenVMS User's Manual). Some of the Ctrl-key characters not
used by the operating system are G, K, N, and P.
The SHOW ABORT_KEY command identifies the Ctrl-key sequence currently
in effect for the abort function.
Do not use Ctrl/Y from within a debugging session. Instead, use either
Ctrl/C or an equivalent Ctrl-key sequence established with the SET
ABORT_KEY command.
Related commands:
Ctrl/C
Ctrl/Y
SHOW ABORT_KEY
Example
|
DBG> SHOW ABORT_KEY
Abort Command Key is CTRL_C
DBG> GO
...
[Ctrl/C]
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
[Ctrl/C]
%DEBUG-W-ABORTED, command aborted by user request
DBG> SET ABORT_KEY = CTRL_P
DBG> GO
...
[Ctrl/P]
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
[Ctrl/P]
%DEBUG-W-ABORTED, command aborted by user request
DBG>
|
This example shows the following:
- Use of Ctrl/C for the abort function (default).
- Use of the SET ABORT_KEY command to reassign the abort function to
Ctrl/P.
SET ATSIGN
Establishes the default file specification that the debugger uses when
searching for command procedures.
Format
SET ATSIGN file-spec
Parameters
file-spec
Specifies any part of a file specification (for example, a directory
name or a file type) that the debugger is to use by default when
searching for a command procedure. If you do not supply a full file
specification, the debugger assumes SYS$DISK:[]DEBUG.COM as the default
file specification for any missing field.
You can specify a logical name that translates to a search list. In
this case, the debugger processes the file specifications in the order
they appear in the search list until the command procedure is found.
Description
When you invoke a debugger command procedure with the execute procedure
(@) command, the debugger assumes, by default, that the command
procedure file specification is SYS$DISK:[]DEBUG.COM. The SET ATSIGN
command enables you to override this default.
Related commands:
@ (Execute Procedure)
SHOW ATSIGN
Example
|
DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> @TEST
|
In this example, when you use the @TEST command, the debugger looks for
the file TEST.DBG in USER:[JONES.DEBUG].
SET BREAK
Establishes a breakpoint at the location denoted by an address
expression, at instructions of a particular class, or at the occurrence
of specified events.
Format
SET BREAK [address-expression[,...]]
[WHEN(conditional-expression)]
[DO(command[;...])]
Parameters
address-expression
Specifies an address expression (a program location) at which a
breakpoint 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, see the Address_Expressions help topic.
Do not specify the asterisk (*) wildcard character. Do not specify an
address expression with any of the following qualifiers:
/ACTIVATING
/BRANCH
/CALL
/EXCEPTION
/HANDLER
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/INTO
/[NO]JSB (VAX only)
/LINE
/OVER
/[NO]SHARE
/[NO]SYSTEM
/SYSEMULATE (Alpha only)
/TERMINATING
/UNALIGNED_DATA (Alpha and I64 only)
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
breakpoint 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.
On VAX systems, CALLS and CALLG routines start with an entry mask.
conditional-expression
Specifies a conditional expression in the currently set language that
is to be evaluated whenever execution reaches the breakpoint. (The
debugger checks the syntax of the expressions in the WHEN clause when
execution reaches the breakpoint, not when the breakpoint is set.) If
the expression is true, the debugger reports that a breakpoint has been
triggered. If an action (DO clause) is associated with the breakpoint,
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 break action is taken. The debugger checks the syntax of the
commands in a DO clause when it executes the DO clause, not when the
breakpoint is set.
Qualifiers
/ACTIVATING
Causes the debugger to break when a new process comes under debugger
control. The debugger prompt is displayed when the first process comes
under debugger control. This enables you to enter debugger commands
before the program has started execution. See also the /TERMINATING
qualifier.
/AFTER:n
Specifies that break action not be taken until the nth time
the designated breakpoint is encountered (n is a decimal
integer). Thereafter, the breakpoint occurs every time it is
encountered provided that conditions in the WHEN clause (if specified)
are true. The SET BREAK/AFTER:1 command has the same effect as SET
BREAK.
/BRANCH
Causes the debugger to break on every branch instruction encountered
during program execution. See also the /INTO and /OVER qualifiers.
/CALL
Causes the debugger to break on every call instruction encountered
during program execution, including the RET instruction. See also the
/INTO and /OVER qualifiers.
/EVENT=event-name
Causes the debugger to break on 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 break 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. Use the SHOW
EVENT_FACILITY command to identify the current event facility and the
associated event names.
/EXCEPTION
Causes the debugger to break whenever an exception is signaled. The
break action occurs before any application-declared exception handlers
are invoked.
As a result of a SET BREAK/EXCEPTION command, whenever your program
generates an exception, the debugger suspends program execution,
reports the exception, and displays its prompt. When you resume
execution from an exception breakpoint, the behavior is as follows:
- If you enter a GO command without an
address-expression parameter, the exception is
resignaled, thus allowing any application-declared exception handler to
execute.
- If you enter a GO command with an
address-expression parameter, program execution
continues at the specified location, thus inhibiting the execution of
any application-declared exception handler.
- On VAX, if you enter a STEP command, the debugger steps into any
application-declared exception handler. If there is no
application-declared handler for that exception, the debugger resignals
the exception.
On Alpha, you must explicitly set a breakpoint in
the exception handler before entering a STEP or a GO command to get the
debugger to suspend execution within the handler.
- If you enter a CALL command, the routine specified is executed.
On Alpha processors, an exception might not be delivered (to the program
or debugger) immediately after the execution of the instruction that
caused the exception. Therefore, the debugger might suspend execution
on an instruction beyond the one that actually caused the exception.
/HANDLER
Causes the debugger to scan the call stack and attempt to set a
breakpoint on every established frame-based handler whenever the
program being debugged has an exception. The debugger does not
discriminate between standard RTL handlers and user-established
handlers.
On Alpha and I64 systems, most RTLs establish a jacket RTL handler on a
frame where the user program has defined a handler. The RTL jacket
performs setup, argument manipulation, and dispatch to the user written
handlers. When processing the exception, the debugger can only set the
breakpoint on the RTL jacket handler, because that is the address on
the call stack. If the debugger suspends program execution in a jacket
RTL handler, you can usually reach the user-defined handler by finding
the dispatch point(s) via some number of STEP/CALLs followed by a
STEP/INTO.
See the OpenVMS Calling Standard for more information on frame-based
handlers.
If the jacket RTL handler is part of an installed shared image such as
ALPHA LIBOTS, the debugger cannot set a breakpoint on it (no private
user mode write access). In this case, activate ALL RTLs as private
images via logical names. For example:
$DEFINE LIBOTS SYS$SHARE:LIBOTS.EXE;
|
Note that the trailing semicolon (;) is required. Note also that all
(or none) of your shared installed RTLs should be activated privately.
Use SHOW IMAGE/FULL data to realize the list of images with system
space code sections and then define logicals for all of them and rerun
your debug session.
/INSTRUCTION
/INSTRUCTION[=(opcode[,...])]
When you do not specify an opcode, causes the debugger to break on
every instruction encountered during program execution.
On VAX processors only, you can optionally specify one or more opcodes.
This causes the debugger to break on every instruction with an opcode
that is on the list.
See also the /INTO and /OVER qualifiers.
/INTO
(Default) Applies only to breakpoints set with the following qualifiers
(that is, when an address expression is not explicitly specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
When used with those qualifiers, /INTO causes the debugger to break at
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 break action with
/[NO]JSB, /[NO]SHARE, and /[NO]SYSTEM.
/JSB
/NOJSB
(VAX only) Qualifies /INTO. Use with /INTO and one of the following
qualifiers:
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...])
/LINE
The /JSB qualifier is the default for all languages except DIBOL. It
lets the debugger break within routines that are called by the JSB or
CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies
that breakpoints 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 break on the beginning of each source line
encountered during program execution. See also the /INTO and /OVER
qualifiers.
/MODIFY
Causes the debugger to break on every instruction that writes to and
modifies the value of the location indicated by the address expression.
The address expression is typically a variable name.
The SET BREAK/MODIFY command acts exactly like a SET WATCH command and
operates under the same restrictions.
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). SET TYPE LONGWORD restores the default length of 4 bytes.
/OVER
Applies only to breakpoints set with the following qualifiers (that is,
when an address expression is not explicitly specified):
/BRANCH
/CALL
/INSTRUCTION
/INSTRUCTION=(opcode[,...]) (VAX only)
/LINE
When used with those qualifiers, /OVER causes the debugger to break at
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 BREAK/RETURN command cancels a previous SET BREAK 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
The /SHARE qualifier permits the debugger to break within shareable
image routines as well as other routines. The /NOSHARE qualifier
specifies that breakpoints not be set within shareable images.
/SILENT
/NOSILENT (default)
Controls whether the "break..." message and the source line
for the current location are displayed at the breakpoint. The /NOSILENT
qualifier specifies that the message is displayed. The /SILENT
qualifier specifies that the message and the source line are not
displayed. The /SILENT qualifier overrides /SOURCE. See also the SET
STEP [NO]SOURCE command.
/SOURCE (default)
/NOSOURCE
Controls whether the source line for the current location is displayed
at the breakpoint. The /SOURCE qualifier specifies that the source line
is displayed. The /NOSOURCE qualifier specifies that no source line is
displayed. The /SILENT qualifier overrides /SOURCE. See also the SET
STEP [NO]SOURCE command.
/SYSEMULATE[=mask]
(Alpha only) Stops program execution and returns control to the
debugger after the operating system emulates an instruction. The
optional argument mask is an unsigned quadword with bits set to specify
which emulated instruction groups shall cause breakpoints. The only
emulated instruction group currently defined consists of the BYTE and
WORD instructions. Select this instruction group by setting bit 0 of
mask to 1.
|
