 |
OpenVMS Debugger Manual
START HEAP_ANALYZER (Integrity servers only)
Starts the Heap Analyzer to diagnose heap memory problems.
Note
The Heap Analyzer requires a DECwindows display.
|
Format
START HEAP_ANALYZER [integer]
Description
Invokes the Heap Analyzer for a graphical display of the ongoing memory
usage by the image being debugged. Once the Heap Analyzer main window
is displayed, the Heap Analyzer is populated with the currently loaded
images. Press the Heap Analyzer START button to return to the Debugger
command prompt (DBG>).
Note
Heap memory operations that occur before you enter the START
HEAP_ANALYZER command are not recorded by the Heap Analyzer. To ensure
all heap memory operations are recorded, HP recommends that you start
the Heap Analyzer early in the life of the image being monitored.
|
See Chapter 12 for full information about using the Heap Analyzer.
Related commands:
RUN
RERUN
Example
Invokes the Heap Analyzer for a graphical display of the ongoing memory
usage by the program being debugged.
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
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.
/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, 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.
/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, 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.
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
/LINE
/RETURN
/SEMANTIC_EVENT (Alpha 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
/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.
Related commands:
CALL
EXIT
GO
SET BREAK/EXCEPTION
SET MODE [NO]INTERRUPT
SET PROCESS
(SET,SHOW) STEP
Examples
| #1 |
DBG> SHOW STEP
step type: source, nosilent, by line,
over routine calls
DBG> STEP
stepped to SQUARES$MAIN\%LINE 4
4: OPEN(UNIT=8, FILE='DATAFILE.DAT', STATUS='OLD')
DBG>
|
In this example, the SHOW STEP command identifies the default
qualifiers currently in effect for the STEP command. In this case, the
STEP command, without any parameters or qualifiers, executes the next
line of source code. After the STEP command has completed, execution is
suspended at the beginning of line 4.
| #2 |
DBG> STEP 5
stepped to MAIN\%LINE 47
47: SWAP(X,Y);
DBG>
|
This command executes the next 5 lines of source code. After the STEP
command has completed, execution is suspended at the beginning of line
47.
| #3 |
DBG> STEP/INTO
stepped to routine SWAP
23: procedure SWAP (A,B: in out integer) is
DBG> STEP
stepped to MAIN\SWAP\%LINE 24
24: TEMP: integer := 0;
DBG> STEP/RETURN
stepped on return from MAIN\SWAP\%LINE 24 to MAIN\SWAP\%LINE 29
29: end SWAP;
DBG>
|
In this example, execution is paused at a call to routine SWAP, and the
STEP/INTO command executes the program up to the beginning of the
called routine. The STEP command executes the next line of source code.
The STEP/RETURN command executes the rest of routine SWAP up to its RET
instruction (that is, up to the point just prior to transferring
control back to the calling routine).
| #4 |
DBG> SET STEP INSTRUCTION
DBG> SHOW STEP
step type: source, nosilent, by instruction,
over routine calls
DBG> STEP
stepped to SUB1\%LINE 26: MOVL S^#4,B^-20(FP)
26: Z:integer:=4;
DBG>
|
In this example, the SET STEP INSTRUCTION command establishes
/INSTRUCTION as the default STEP command qualifier. This is verified by
the SHOW STEP command. The STEP command executes the next instruction.
After the STEP command has completed, execution is suspended at the
first instruction (MOVL) of line 26 in module SUB1.
STOP
Interrupts all specified processes that are running.
Format
STOP [process-spec[,...]
Parameters
process-spec
This parameter specifies the process set to be stopped. The default is
the current process set. Use any of the following forms:
|
[%PROCESS_NAME]
process-name
|
The process name, if that name does not contain spaces or lowercase
characters. The process name can include the asterisk (*) wildcard
character.
|
|
[%PROCESS_NAME] "
process-name "
|
The process name, if that name contains spaces or lowercase characters.
You can also use apostrophes (') instead of quotation marks (").
|
|
%PROCESS_PID
process_id
|
The process identifier (PID, a hexadecimal number).
|
[%PROCESS_NUMBER]
process-number
(or %PROC
process-number)
|
The number assigned to a process when it comes under debugger control.
A new number is assigned sequentially, starting with 1, to each
process. If a process is terminated with the EXIT or QUIT command, the
number can be assigned again during the debugging session. Process
numbers appear in a SHOW PROCESS display. Processes are ordered in a
circular list so they can be indexed with the built-in symbols
%PREVIOUS_PROCESS and %NEXT_PROCESS.
|
|
process-set-name
|
A symbol defined with the DEFINE/PROCESS_SET command to represent a
group of processes.
|
|
%NEXT_PROCESS
|
The next process after the visible process in the debugger's circular
process list.
|
|
%PREVIOUS_PROCESS
|
The process previous to the visible process in the debugger's circular
process list.
|
|
%VISIBLE_PROCESS
|
The process whose stack, register set, and images are the current
context for looking up symbols, register values, routine calls,
breakpoints, and so on.
|
You can also use the asterisk (*) wildcard character to specify all
processes.
Description
The STOP command interrupts the specified processes. You can use the
STOP command in nowait mode to stop processes that are still running.
Examples
| #1 |
all> SHOW PROCESS
Number Name State Current PC
1 DBGK$$2727282C break SERVER\
main\%LINE 18834
2 USER1_2 running not available
* 3 USER1_3 running not available
all> CLIENTS> STOP
all> show process
Number Name State Current PC
1 DBGK$$2727282C break SERVER
main<literal>\main\%LINE 18834
2 USER1_2 interrupted 0FFFFFFFF800F7A20
* 3 USER1_3 interrupted 0FFFFFFFF800F7A20
all>
|
This command sequence first shows all processes, then stops the
processes in process set clients. The last SHOW PROCESS command shows
the new process states.
SYMBOLIZE
Converts a memory address to a symbolic representation, if possible.
Format
SYMBOLIZE address-expression[,...]
Parameters
address-expression
Specifies an address expression to be symbolized. Do not use the
asterisk (*) wildcard character.
Description
If the address is a static address, it is symbolized as the nearest
preceding symbol name, plus an offset. If the address is also a code
address and a line number can be found that covers the address, the
line number is included in the symbolization.
If the address is a register address, the debugger displays all symbols
in all set modules that are bound to that register. The full path name
of each such symbol is displayed. The register name itself
("%R5", for example) is also displayed.
If the address is a call stack location in the call frame of a routine
in a set module, the debugger searches for all symbols in that routine
whose addresses are relative to the frame pointer (FP) or the stack
pointer (SP). The closest preceding symbol name plus an offset is
displayed as the symbolization of the address. A symbol whose address
specification is too complex is ignored.
On Alpha, the commands SYMBOLIZE procedure-code-address and
SYMBOLIZE procedure-descriptor-address both display the path
name of the routine, entry point, or Ada package specified by these
addresses.
If the debugger cannot symbolize the address, a message is displayed.
Related commands:
EVALUATE/ADDRESS
SET MODE [NO]LINE
SET MODE [NO]SYMBOLIC
(SET,SHOW) MODULE
SHOW SYMBOL
Examples
| #1 |
DBG> SYMBOLIZE %R5
address PROG\%R5:
PROG\X
DBG>
|
This example shows that the local variable X in routine PROG is located
in register R5.
| #2 |
DBG> SYMBOLIZE %HEX 27C9E3
address 0027C9E3:
MOD5\X
DBG>
|
This command directs the debugger to treat the integer literal 27C9E3
as a hexadecimal value and convert that address to a symbolic
representation, if possible. The address converts to the symbol X in
module MOD5.
TYPE
Displays lines of source code.
Format
TYPE [[module-name\]line-number[:line-number]
[,[module-name\]line-number[:line-number][,...]]]
Parameters
module-name
Specifies the module that contains the source lines to be displayed. If
you specify a module name along with the line numbers, use standard
pathname notation: insert a backslash (\) between the module name and
the line numbers.
If you do not specify a module name, the debugger uses the current
scope (as established by a previous SET SCOPE command, or the PC scope
if you did not enter a SET SCOPE command) to find source lines for
display. If you specify a scope search list with the SET SCOPE command,
the debugger searches for source lines only in the module associated
with the first named scope.
line-number
Specifies a compiler-generated line number (a number used to label a
source language statement or statements).
If you specify a single line number, the debugger displays the source
code corresponding to that line number.
If you specify a list of line numbers, separating each with a comma,
the debugger displays the source code corresponding to each of the line
numbers.
If you specify a range of line numbers, separating the beginning and
ending line numbers in the range with a colon (:), the debugger
displays the source code corresponding to that range of line numbers.
You can display all the source lines of a module by specifying a range
of line numbers starting from 1 and ending at a number equal to or
greater than the largest line number in the module.
After displaying a single line of source code, you can display the next
line of that module by entering a TYPE command without a line number
(that is, by entering TYPE and then pressing the Return key). You can
then display the next line and successive lines by repeating this
sequence, in effect, reading through your source program one line at a
time.
Description
The TYPE command displays the lines of source code that correspond to
the specified line numbers. The line numbers used by the debugger to
identify lines of source code are generated by the compiler. They
appear in a compiler-generated listing and in a screen-mode source
display.
If you specify a module name with the TYPE command, the module must be
set. Use the SHOW MODULE command to determine whether a particular
module is set. Then use the SET MODULE command, if necessary.
In screen mode, the output of a TYPE command is directed at the current
source display, not at an output or DO display. The source display
shows the lines specified and any surrounding lines that fit in the
display window.
Related commands:
EXAMINE/SOURCE
SET (BREAK,TRACE,WATCH)/[NO]SOURCE
SET MODE [NO]SCREEN
(SET,SHOW,CANCEL) SCOPE
SET STEP [NO]SOURCE
STEP/[NO]SOURCE
Examples
| #1 |
DBG> TYPE 160
module COBOLTEST
160: START-IT-PARA.
DBG> TYPE
module COBOLTEST
161: MOVE SC1 TO ES0.
DBG>
|
In this example, the first TYPE command displays line 160, using the
current scope to locate the module containing that line number. The
second TYPE command, entered without specifying a line number, displays
the next line in that module.
| #2 |
DBG> TYPE 160:163
module COBOLTEST
160: START-IT-PARA.
161: MOVE SC1 TO ES0.
162: DISPLAY ES0.
163: MOVE SC1 TO ES1.
DBG>
|
This command displays lines 160 to 163, using the current scope to
locate the module.
| #3 |
DBG> TYPE SCREEN_IO\7,22:24
|
This command displays line 7 and lines 22 to 24 in module SCREEN_IO.
|
