 |
HP OpenVMS Debugger Manual
1.13.4 Controlling Type Selection and Radix
The following commands control type selection and radix:
(SET,SHOW,CANCEL) RADIX
|
(Establishes, displays, restores) the radix for data entry and display
|
(SET,SHOW,CANCEL) TYPE
|
(Establishes, displays, restores) the type for program locations that
are not associated with a compiler-generated type
|
SET MODE [NO]G_FLOAT
|
Controls whether double-precision floating-point constants are
interpreted as G_FLOAT or D_FLOAT
|
1.13.5 Controlling Symbol Searches and Symbolization
The following commands control symbol searches and symbolization:
SHOW SYMBOL
|
Displays symbols in your program
|
(SET,SHOW,CANCEL) MODULE
|
Sets a module by loading its symbol information into the debugger's
symbol table, identifies, cancels a set module
|
(SET,SHOW,CANCEL) IMAGE
|
Sets a shareable image by loading data structures into the debugger's
symbol table, identifies, cancels a set image
|
SET MODE [NO]DYNAMIC
|
Controls whether or not modules and shareable images are set
automatically when the debugger interrupts execution
|
(SET,SHOW,CANCEL) SCOPE
|
(Establishes, displays, restores) the scope for symbol searches
|
SYMBOLIZE
|
Converts a memory address to a symbolic address expression
|
SET MODE [NO]LINE
|
Controls whether or not program locations are displayed in terms of
line numbers or
routine-name +
byte offset
|
SET MODE [NO]SYMBOLIC
|
Controls whether or not program locations are displayed symbolically or
in terms of numeric addresses
|
1.13.6 Displaying Source Code
The following commands control the display of source code:
TYPE
|
Displays lines of source code
|
EXAMINE/SOURCE
|
Displays the source code at the location specified by the address
expression
|
SEARCH
|
Searches the source code for the specified string
|
(SET,SHOW) SEARCH
|
(Establishes, displays) the default qualifiers for the SEARCH command
|
SET STEP [NO]SOURCE
|
Enables/disables the display of source code after a STEP command has
been executed or at a breakpoint, tracepoint, or watchpoint
|
(SET,SHOW) MARGINS
|
(Establishes, displays) the left and right margin settings for
displaying source code
|
(SET,SHOW,CANCEL) SOURCE
|
(Creates, displays, cancels) a source directory search list
|
1.13.7 Using Screen Mode
The following commands control screen mode and screen displays:
SET MODE [NO]SCREEN
|
Enables/disables screen mode
|
DISPLAY
|
Creates or modifies a display
|
SCROLL
|
Scrolls a display
|
EXPAND
|
Expands or contracts a display
|
MOVE
|
Moves a display across the screen
|
(SHOW,CANCEL) DISPLAY
|
(Identifies, deletes) a display
|
(SET,SHOW,CANCEL) WINDOW
|
(Creates, identifies, deletes) a window definition
|
SELECT
|
Selects a display for a display attribute
|
SHOW SELECT
|
Identifies the displays selected for each of the display attributes
|
SAVE
|
Saves the current contents of a display into another display
|
EXTRACT
|
Saves a display or the current screen state into a file
|
(SET,SHOW) TERMINAL
|
(Establishes, displays) the terminal screen height and width that the
debugger uses when it formats displays and other output
|
SET MODE [NO]SCROLL
|
Controls whether an output display is updated line by line or once per
command
|
Ctrl/W
DISPLAY/REFRESH
|
Refreshes the screen
|
1.13.8 Editing Source Code
The following commands control source editing from a debugging session:
EDIT
|
Starts an editor during a debugging session
|
(SET,SHOW) EDITOR
|
(Establishes, identifies) the editor started by the EDIT command
|
1.13.9 Defining Symbols
The following commands define and delete symbols for addresses,
commands, or values:
DEFINE
|
Defines a symbol as an address, command, or value
|
DELETE
|
Deletes symbol definitions
|
(SET,SHOW) DEFINE
|
(Establishes, displays) the default qualifier for the DEFINE command
|
SHOW SYMBOL/DEFINED
|
Identifies symbols that have been defined with the DEFINE command
|
1.13.10 Using Keypad Mode
The following commands control keypad mode and key definitions:
SET MODE [NO]KEYPAD
|
Enables/disables keypad mode
|
DEFINE/KEY
|
Creates key definitions
|
DELETE/KEY
|
Deletes key definitions
|
SET KEY
|
Establishes the key definition state
|
SHOW KEY
|
Displays key definitions
|
1.13.11 Using Command Procedures, Log Files, and Initialization Files
The following commands are used with command procedures and log files:
@ (execute procedure)
|
Executes a command procedure
|
(SET,SHOW) ATSIGN
|
(Establishes, displays) the default file specification that the
debugger uses to search for command procedures
|
DECLARE
|
Defines parameters to be passed to command procedures
|
(SET,SHOW) LOG
|
(Specifies, identifies) the debugger log file
|
SET OUTPUT [NO]LOG
|
Controls whether or not a debugging session is logged
|
SET OUTPUT [NO]SCREEN_LOG
|
Controls whether or not, in screen mode, the screen contents are logged
as the screen is updated
|
SET OUTPUT [NO]VERIFY
|
Controls whether or not debugger commands are displayed as a command
procedure is executed
|
SHOW OUTPUT
|
Identifies the current output options established by the SET OUTPUT
command
|
1.13.12 Using Control Structures
The following commands establish conditional and looping structures for
debugger commands:
FOR
|
Executes a list of commands while incrementing a variable
|
IF
|
Executes a list of commands conditionally
|
REPEAT
|
Executes a list of commands a specified number of times
|
WHILE
|
Executes a list of commands while a condition is true
|
EXITLOOP
|
Exits an enclosing WHILE, REPEAT, or FOR loop
|
1.13.13 Debugging Multiprocess Programs
The following commands debug multiprocess programs. Note that these
commands are specific to multiprocess programs. Many of the commands
listed under other categories have qualifiers or parameters that are
specific to multiprocess programs (for example, SET BREAK/ACTIVATING,
EXIT process-spec, DISPLAY/PROCESS=).
CONNECT
|
Brings a process under debugger control
|
DEFINE/PROCESS_SET
|
Assigns a symbolic name to a list of process specifications
|
SET MODE [NO]INTERRUPT
|
Controls whether execution is interrupted in other processes when it is
paused in some process
|
(SET,SHOW) PROCESS
|
Modifies the multiprocess debugging environment, displays process
information
|
WAIT
|
When debugging a multiprocess program, controls whether the debugger
waits until all processes have stopped before prompting for another
command
|
1.13.14 Additional Commands
The following commands are used for miscellaneous purposes:
HELP
|
Displays online help on debugger commands and selected topics
|
ANALYZE/CRASH_DUMP
|
Opens a process dump for analysis with the System Dump Debugger (SDD)
|
ANALYZE/PROCESS_DUMP
|
Opens a process dump for analysis with the System Code Debugger (SCD)
|
(DISABLE,ENABLE,SHOW) AST
|
(Disables, enables) the delivery of ASTs in the program, identifies
whether delivery is enabled or disabled
|
PTHREAD
|
Passes a command to the POSIX Threads Debugger
|
(SET,SHOW) EVENT_FACILITY
|
(Establishes, identifies) the current run-time facility for Ada,
POSIX Threads, and SCAN events
|
(SET,SHOW) LANGUAGE
|
(Establishes, identifies) the current language
|
SET OUTPUT [NO]TERMINAL
|
Controls whether debugger output, except for diagnostic messages, is
displayed or suppressed
|
SET PROMPT
|
Specifies the debugger prompt
|
(SET,SHOW) TASK|THREAD
|
Modifies the tasking environment, displays task information
|
SHOW EXIT_HANDLERS
|
Identifies the exit handlers declared in the program
|
SHOW MODE
|
Identifies the current debugger modes established by the SET MODE
command (for example, screen mode, step mode)
|
SHOW OUTPUT
|
Identifies the current output options established by the SET OUTPUT
command
|
Part II Command Interface
This part describes the debugger's command interface.
For information about the debugger's DECwindows Motif user interface,
see Part 3.
Chapter 2 Getting Started with the Debugger
This chapter gives a tutorial introduction to the debugger's command
interface.
The way you use the debugger depends on several factors: the kind of
program you are working on, the kinds of errors you are looking for,
and your own personal style and experience with the debugger. This
chapter explains the following basic tasks that apply to most
situations:
- Entering debugger commands and getting online help
- Viewing your source code with the TYPE command and in screen mode
- Controlling program execution with the GO, STEP, and SET BREAK
commands, and monitoring execution with the SHOW CALLS, SET TRACE, and
SET WATCH commands
- Examining and manipulating data with the EXAMINE, DEPOSIT, and
EVALUATE commands
- Controlling symbol references with path names and the SET MODULE
and SET SCOPE commands
Several examples are language specific. However, the general concepts
are readily adaptable to all supported languages.
The sample debugging session in Section 2.6 shows how to use some of
this information to locate an error and correct it.
For information about starting and ending a debugging session, see
Section 1.3.
2.1 Entering Debugger Commands and Accessing Online Help
After you start the debugger as explained in Section 1.3, you can
enter debugger commands whenever the debugger prompt (DBG>) is
displayed. To enter a command, type it at the keyboard and press
Return. For example, the following command sets a watchpoint on the
variable COUNT:
Detailed reference information about debugger commands is available in
Part 6 and through the debugger's online help:
- To list the help topics, type HELP at the prompt.
- For an explanation of the help system, type HELP HELP.
- For complete rules on entering commands, type HELP Command_Format.
- To display help on a particular command, type HELP
command. For example, to display HELP on the SET WATCH
command, type HELP SET WATCH.
- To list commands grouped by function, type HELP Command_Summary.
Online help is also available on the following topics:
New_Features
Release_Notes
Address_Expressions
Built_in_Symbols
DECwindows_Interface
Keypad_Definitions
Language_Support
Logical_Names
Messages (diagnostic messages)
Path_Names (to qualify symbolic names)
Screen_Mode
SS$_DEBUG condition (to start debugger from program)
System_Management
To display help about any of these topics, type HELP topic.
For example, to display information about diagnostic messages, type
HELP Messages.
When you start the debugger, a few commonly used command sequences are
automatically assigned to the keys on the numeric keypad (to the right
of the main keyboard). Thus, you can perform certain functions either
by entering a command or by pressing a keypad key.
The predefined key functions are identified in Figure 2-1.
Figure 2-1 Keypad Key Functions Predefined by the
Debugger---Command Interface
Most keypad keys have three predefined functions---DEFAULT, GOLD, and
BLUE.
- To enter a key's DEFAULT function, press the key.
- To enter its GOLD function, first press and release the PF1 (GOLD)
key, and then press the key.
- To enter its BLUE function, first press and release the PF4 (BLUE)
key, and then press the key.
In Figure 2-1, the DEFAULT, GOLD, and BLUE functions are listed
within each key's outline, from top to bottom, respectively. For
example:
- Pressing KP0 (keypad key 0) enters the STEP command.
- Pressing PF1 KP0 enters the STEP/INTO command.
- Pressing PF4 KP0 enters the STEP/OVER command.
Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down,
left, right, or up, respectively. By putting the keypad in the MOVE,
EXPAND, or CONTRACT state, indicated in Figure 2-1, you can also use
these keys to move, expand, or contract displays in four directions.
Enter the command HELP Keypad_Definitions to display the keypad key
definitions.
You can redefine keypad key functions with the DEFINE/KEY command.
2.2 Displaying Source Code
The debugger provides two modes for displaying information: noscreen
mode and screen mode. By default, when you start the debugger, you are
in noscreen mode, but you might find that it is easier to view source
code in screen mode. The following sections briefly describe both modes.
2.2.1 Noscreen Mode
Noscreen mode is the default, line-oriented mode of displaying input
and output. The interactive examples throughout this chapter, excluding
Section 2.2.2, show noscreen mode.
In noscreen mode, use the TYPE command to display one or more source
lines. For example, the following command displays line 7 of the module
in which execution is currently paused:
DBG> TYPE 7
module SWAP_ROUTINES
7: TEMP := A;
DBG>
|
The display of source lines is independent of program execution. To
display source code from a module (compilation unit) other than the one
in which execution is currently paused, use the TYPE command with a
path name to specify the module. For example, the following command
displays lines 16 to 21 of module TEST:
Path names are discussed in more detail in Section 2.3.2, with the STEP
command.
You can also use the EXAMINE/SOURCE command to display the source line
for a routine or any other program location that is associated with an
instruction.
The debugger also displays source lines automatically when it suspends
execution at a breakpoint or watchpoint, after a STEP command, or when
a tracepoint is triggered (see Section 2.3).
After displaying source lines at various locations in your program, you
can redisplay the location at which execution is currently paused by
pressing KP5.
If the debugger cannot locate source lines for display, it issues a
diagnostic message. Source lines might not be available for a variety
of reasons. For example:
- Execution is paused within a module that was compiled or linked
without the /DEBUG qualifier.
- Execution is paused within a system or shareable image routine for
which no source code is available.
- The source file was moved to a different directory after it was
compiled (the location of source files is embedded in the object
modules). In this case, use the SET SOURCE command to specify the new
location.
- The module might need to be set with the SET MODULE command. Module
setting is explained in Section 2.5.1.
To switch to noscreen mode from screen mode, press PF1 PF3 (or type SET
MODE NOSCREEN). You can use the TYPE and EXAMINE/SOURCE commands in
screen mode as well as noscreen mode.
2.2.2 Screen Mode
Screen mode provides the easiest way to view your source code. To
switch to screen mode, press PF3 (or type SET MODE SCREEN). In screen
mode, by default the debugger splits the screen into three displays
named SRC, OUT, and PROMPT, as shown in Figure 2-2.
Figure 2-2 Default Screen Mode Display Configuration
The SRC display shows the source code of the module in which execution
is currently paused. An arrow in the left column points to the source
line corresponding to the current value of the program counter (PC).
The PC is a register that contains the memory address of the
instruction to be executed next. The line numbers, which are assigned
by the compiler, match those in a listing file. As you execute the
program, the arrow moves down and the source code is scrolled
vertically to center the arrow in the display.
The OUT display captures the debugger's output in response to the
commands that you enter. The PROMPT display shows the debugger prompt,
your input (the commands that you enter), debugger diagnostic messages,
and program output.
You can scroll both SRC and OUT to see whatever information might
scroll beyond the display window's edge. Press KP3 repeatedly as needed
to select the display to be scrolled (by default, SRC is scrolled).
Press KP8 to scroll up and KP2 to scroll down. Scrolling a display does
not affect program execution.
In screen mode, if the debugger cannot locate source lines for the
routine in which execution is currently paused, it tries to display
source lines in the next routine down on the call stack for which
source lines are available. If the debugger can display source lines
for such a routine, it issues the following message:
%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC.
Displaying source in a caller of the current routine.
DBG>
|
In such cases, the arrow in the SRC display identifies the line that
contains code following the call statement in the calling routine.
2.3 Controlling and Monitoring Program Execution
This section explains how to perform the following tasks:
- Start and resume program execution
- Execute the program to the next source line, instruction, or other
step unit
- Determine where execution is currently paused
- Use breakpoints to suspend program execution at points of interest
- Use tracepoints to trace the execution path of your program through
specified locations
- Use watchpoints to monitor changes in the values of variables
With this information you can pick program locations where you can then
test and manipulate the contents of variables as described in
Section 2.4.
|