This is the only level 1 module in this help library.
1 – src_workarea_hlp
Use the source view on the main window to do the following:
Location Function
------- ---------
Source display Display program source code, and, optionally,
compiler-generated line numbers to the left
of the code.
Breakpoint Set breakpoints on specific source lines or
toggles routines in your program, check breakpoint
status, and activate or deactivate breakpoints.
Current line Identify the line of source code that will be
indicator executed when program execution resumes.
Call stack Identify the sequence of routine calls on
the stack.
2 – popup_src
To use pop-up menus in the source view, select text or position your
mouse pointer in the source view, and press MB3. The debugger inserts
the selected text or line number in the menu items of the pop-up menu.
If you press MB3 while your mouse pointer rests on a source line in the
source view, a pop-up menu with the following items appears:
Examine [selection] Evaluates the selected expression and prints
its value in the command view.
Monitor [selection] Inserts the selected expression in the monitor
list of the monitor view.
Deposit [selection] Provides the Assign/Deposit dialog box.
Break on Routine Sets a breakpoint on a selected routine name.
[selection]
Toggle Breakpoint Activates/deactivates breakpoint at mouse pointer.
at Line
[line number]
Temporary Breakpoint Sets temporary breakpoint at mouse pointer.
at Line
[line number]
Go to Line Branches to [line number] without executing source
[line number] code betwen the line at which execution is suspended
and [line number].
Display Instruction Displays decoded instruction stream of your program.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
If you press MB3 while your mouse pointer rests in the annotation area
of the source view, a pop-up menu with the following items appears:
Toggle Breakpoint Activates/deactivates breakpoint at mouse pointer.
at Line
[line number]
Temporary Breakpoint Sets temporary breakpoint at mouse pointer.
at Line
[line number]
Go to Line Executes until [line number] is reached.
[line number]
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
3 – callstack_menu_hlp
Use the Call Stack menu on the main window to do the following:
Action Function
------- ---------
None Identifies the routine whose source code is
executing in the source view.
Pull-down Identifies the sequence of routines on the
menu call stack.
Click on Sets the context (scope) for source display,
routine instruction display, register display,
name and symbol searches to any routine on the
call stack.
4 – cnt_button_hlp
The push-button view on the main window contains push buttons that
correspond to debugger commands. You can modify, add, remove, and
resequence push buttons and the commands associated with them.
Use the default push buttons to complete the following functions.
Push
Button Function
------ --------
Stop Interrupts program execution or a debugger
operation without ending the debugging
session.
Go Starts or resumes execution from the current
program location.
Step Executes the program one step unit of
execution. By default, this is one executable
line of source code.
S-into (Step into) When execution is suspended at a
routine call statement, moves execution into
the called routine just past the start of the
routine. If not at a routine call statement,
this push button has the same behavior as the
Step push button.
S-ret (Step return) Executes the program directly to
the end of the routine.
S/call (Step call) Executes the program to the next
call or return instruction.
EX (Examine) Displays, in the command view,
the current value of a variable whose name
you have selected in a window.
E/az Displays, in the command view, the current
value of a variable whose name you have
selected in a window. The variable is interpreted
as a zero-terminated ASCII string.
E/ac Displays, in the command view, the current
value of a variable whose name you have
selected in a window. The variable is interpreted
as a counted ASCII string preceded by a one-byte
count field that contains the length of the string.
EVAL Displays, in the command view, the value
of a language expression in the current language
(by default, the language of the module containing
the main program.
MON (Monitor) Displays, in the monitor view, a
variable name that you have selected in a window
and the current value of that variable. Whenever the
debugger regains control from your program, it
automatically checks the value and updates the
displayed value accordingly.
5 – stop_btn_hlp
Use the Stop push button to interrupt program execution or a debugger operation without ending the debugging session.
6 – msg_region_hlp
The command view on the main window accepts command-line entry input, echoes GUI actions (in a command-line format), and displays debugger messages.
7 – popup_msgregion
To use the pop-up menu in the command view, position your mouse pointer
in the message region, and press MB3. The debugger automatically
inserts your last command in the [last command] menu item of this
pop-up menu.
Menu items are as follows:
Repeat Command Re-enters your last command.
[last command]
Clear Command Window Clears the command view and displays
the DBG> prompt.
Clear Command Line Clears command line.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
8 – src_window_menubar_hlp
Use the menus on the menu bar as explained in the Additional Topics.
9 – src_file_pd_menu_hlp
Use the File menu on the main window as follows:
Action Function
------ --------
Run Image... Brings a program under debugger
control by specifying an executable
image.
Run Foreign Brings a program under debugger
Command... control by specifying a foreign
command symbol.
Rerun Same... Reruns the same program under
debugger control.
Browse Sources Lists the modules in your program.
You can choose to list all modules,
or only those for which symbolic
information is available. You can
display the source code in any module
of your program for which symbolic
information is available.
Can also be used to set breakpoints on
routines.
Display Line Displays or hides line numbers in the
Numbers main window.
Server Connection... (Client-Server only) Invokes the
Server Connection dialog to allow you to
set up and control a connection between a
debug client and a debug server.
Exit Debug? Exits from the debugger. If running
in client-server mode, allows you
to exit either the client, server,
or both.
10 – src_edit_pd_menu_hlp
Use the Edit menu on the main window as follows:
Action Function
------ --------
Cut Cuts selected text from the current command
line and copies it to the clipboard.
If selected text is anywhere other than
the current command line, copies the
text to the clipboard.
Copy Copies selected text from the window to
the clipboard without removing it
from the window.
Paste Pastes text from the clipboard to the insert
point on the current command line in the
command view.
See the DECwindows Motif documentation for more information.
11 – src_break_pd_menu_hlp
Use the Break menu on the main window as follows:
Action Function
------ --------
On Exception Breaks on any exception signaled
during program execution.
Activate All Activates all breakpoints that have
not been canceled, causing the debugger
to suspend program execution when a
breakpoint is reached.
Deactivate All Deactivates all breakpoints, causing
the debugger to ignore them during
program execution.
Cancel All Removes all breakpoints from the
debugger's database. You cannot
reactivate these breakpoints without
explicitly setting them first.
Set... Displays the Set/Nodify Breakpoint
dialog box to set an individual breakpoint
(see Additional Topics).
12 – src_commands_pd_menu_hlp
Use the Commands menu on the main window as follows:
Action Function
------ --------
Examine... Examines the value of a variable or expression.
Deposit... Changes the value of a variable.
Edit File Opens the editable source window with the current
file displayed.
13 – cnt_options_pd_menu_hlp
Use the Options menu on the main or the optional view window as
follows:
Action Function
------ --------
Views... Displays one or more of the
debugger's optional views:
Breakpoint View
Monitor View
Instruction View
Threads View
Register View
.!Track Language Notify you when the debugger
.! Changes enters a module written in
.! a different source language
.! than the previous module.
Show Message Display a dotted line between
Separators debugger messages and commands.
Customize Adds, removes, or resequences
Buttons... a push button in the push-button view.
Also changes a button's label or
the debugger command associated with
a button.
Save Options Saves the current definitions of the
debugger user-interface options for use
in subsequent debugger sessions.
Restore Default Copies and saves the default definitions
Options of the the debugger user-interface options
for use in subsequent debugger sessions.
Edit Options File Loads and displays local debugger resource
file DECW$USER_DEFAULTS:VMSDEBUG.DAT in the
Debug Editor for review and modification.
14 – save_edit_options
The Save Options command in the Options menu of the source view saves the current definitions of the debugger user-interface options in the user-specific debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT. You can use the debugger editor or another editor to change the definitions in the debugger resource file.
15 – restore_default_options
The Restore Default Options in the Options menu of the source view copies the system default debugger resource file DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT to the user-specific debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT. It does not purge previous versions of the user-specific debugger resources file. You must exit and restart the debugger to invoke the default definitions in the restored debugger resource file.
16 – edit_options_file
The Edit Options File in the Options menu of the source view loads and displays the local debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT in the Debug Editor for review and modification. If there is no local debugger resource file, the Debug Editor buffer is empty. To create a local debugger resource file, exit the Debug Editor and select Save Options or Restore Default Options from the Options menu of the source view. You must exit and restart the debugger to invoke the default definitions in the edited debugger resource file.
17 – help_pd_menu_hlp
The Help menu contains the following items that let you display online
help about the debugger:
On Context
On Window
On Help
On Version
On Commands
For more information about using a Help menu item, double click on an
item from the list of Additional Topics below.
18 – run_new_hlp
After starting the debugger as explained in the topic Starting the
Debugger, bring a program under debugger control using one of the
following two techniques:
- Run a specified image. This is the most common technique and is
described below.
- Run an image by specifying a symbol for a foreign command or a DCL
command. This technique is described in the topic Running an Image
by Specifying a Symbol.
To run a specified image:
1. Choose Run Image... from the File menu on the main window. The
Run Image... dialog box appears, which lists:
- A Directories list that contains the parent directory and any
subdirectories contained in the current directory
- A Filter field; by default this specifies the .EXE files in
your current directory
- An Images list that contains the names of images in the current
directory that meet the filter specification
- An Arguments field to pass any required arguments to the image
to be run
- A Heap Analyzer button to run the Heap Analyzer
- An Image field to display and specify the full file
specification of the image to be run
- An OK button to run the image specified in the Image field and
dismiss the dialog box
- A Filter button to display a list of files that meet the
specification in the Filter field
- A Cancel button to dismiss the dialog box without taking and
further action
- A Help button to display this help information
2. In the Directories list, click on the name of the appropriate
subdirectory and click on Filter to list the (filtered) files in
the subdirectory. The debugger also displays, in the Directories
list, the parent directory and any subdirectories of the selected
directory.
3. In the Images list, click on the name of the image to be debugged.
The Image field now shows the image specification. You can edit
this specification as needed.
4. If applicable, enter arguments to be passed to the program in the
Arguments field. Quoted strings, may require additional quotation
marks because the debugger strips quotes when parsing the string.
5. To run the Heap Analyzer, click the Heap Analyzer button.
6. Click on OK to dismiss the dialog box and run the spcified image.
When the program is under debugger control, the debugger:
- Displays the program's source code in the main window.
- Suspends execution at the start of the main program. The
current-location pointer, to the left of the source code, shows the
line whose code will be executed next.
The message displayed in the command view indicates the name of the
main program unit and also indicates that the debugging session is
initialized for the source language of the program. The initialization
sets up language-dependent debugger parameters. These parameters
control the way the debugger parses names and expressions, formats
debugger output, and so on.
You can now debug your program.
With certain programs, the debugger suspends execution at the start of
some initialization code, before the main program, and displays the
following message:
Type GO to reach main program
With some of these programs (for example, Ada programs), the first
breakpoint lets you debug the initialization code using full symbolic
information.
Note the following restrictions about running a program under debugger
control:
- You cannot use the procedure just described to connect the debugger
to a running program.
- You cannot run a program under debugger control over a DECnet link.
Both the image to be debugged and the debugger must reside on the
same node.
19 – run_foreign_hlp
To run an image by specifying a symbol for a foreign (DCL) command:
1. Choose Run Foreign Command... from the File menu on the main
window. The Run Foreign Command dialog box appears.
2. Enter a symbol for a DCL command in the Foreign Command field. The
symbol might be defined as "RUN long_file_name.ext" or a similar
command.
3. Enter any arguments to be passed with the command in the Arguments
field. If you specify a quoted string, you might have to add
quotation marks because the debugger strips quotes when parsing the
string.
4. To run the Heap Analyzer, click the Heap Analyzer button.
5. Click on OK.
For information about startup conditions, see the Bringing a Program
Under Debugger Control topic.
20 – rerun_same_hlp
You can rerun the program currently under debugger control at any time
during a debugging session.
To rerun your program:
1. Choose Rerun Same... from the File menu on the main window. The
Rerun Same dialog box appears.
2. If applicable, enter any arguments to be passed to the program in
the Arguments field.
3. Choose whether to save or not save the current state of any
breakpoints or static watchpoints that you previously set,
activated, or deactivated. Nonstatic watchpoints might or might
not be saved, depending on the scope of the variable being watched
relative to the main program unit (where execution restarts).
4. To run the Heap Analyzer, click the Heap Analyzer button.
5. Click on OK.
When you rerun a program, it is in the same initial state as a program
that is initially brought under debugger control, except for any saved
breakpoints or static watchpoints. The source display and current
location pointer are updated accordingly.
When you rerun a program, the debugger uses the same version of the
image that is currently under debugger control. To debug a different
version of that program (or a different program) from the same
debugging session, choose Run Image... or Run Foreign Command... from
the File menu on the main window.
21 – browse_src_hlp
Use the Browse Source dialog box to: - Display the source code in any module of your program - Set breakpoints on routines
22 – popup_browser
To use pop-up menus in the Source Browser dialog box, position your
mouse pointer in the dialog box, and press MB3. A pop-up menu with the
following items appears:
Expand Expand the selected image or module to include its
component modules or functions in the Source
Browser display.
Collapse Collapse an expanded image, module, or function display.
Display Source Display (in the source display of the source view
on the main window) the source code associated
with the selected module.
Set Breakpoint Set a breakpoint on the selected function.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
23 – show_line_numb
To hide or display source line numbers in the main window, click on Show Line Numbers in the File menu of that window. Line numbers help you identify breakpoints that are listed in the breakpoint view. If you hide line numbers, more of the source code shows through a window of a given width.
24 – exit_db_hlp
To exit the kept debugger, which will terminate the current debugging session, click on Yes. Otherwise, click on No to return to the current session. In client-server mode, the default is to exit both the client and the server. Make sure that the correct buttons are selected, then click on OK to exit, or click on Cancel to return to the current session.
25 – cancel_all_break_hlp
To cancel all breakpoints, click on Yes. Otherwise, click on No to preserve all breakpoints.
26 – breakpoint_set_show_hlp
If you are displaying the Set/Modify Breakpoint dialog box from the
Set... menu item in the Break menu on the main or instruction window,
use the Set/Modify Breakpoint dialog box to SET a conditional
breakpoint or an action breakpoint.
If you are displaying the Set/Modify Breakpoint dialog box from the
Set/Modify... menu item in the Break menu on the optional view window
use the Set/Modify Breakpoint dialog box to SET OR MODIFY a conditional
breakpoint or an action breakpoint.
When the Set/Modify Breakpoint dialog box appears, complete the fields
as follows:
Field Action
----- ------
Location field If the dialog box does not display the
location of the breakpoint you are
setting or modifying, enter the location
using one of the following forms:
<routine-name>\%line <line-number>
routine <routine-name>
<numeric-address>
Condition field Optionally, enter a condition or edit
an existing condition. The relational
expression must be valid in the
source language of the program module.
Action field Optionally, enter an action or edit
an existing action by substituting
one or more new debugger commands
(separated by a semi-colon).
Activate/Deactivate Optionally, activate a deactivated
Breakpoint button breakpoint by accepting the default,
or deactivate an activated breakpoint
by toggling this button.
OK button Click on OK to set the breakpoint
and dismiss the dialog box.
Apply button Click on Apply to set the breakpoint
and clear the dialog box.
Cancel Breakpoint Click on Cancel Breakpoint to remove
button a breakpoint. Note that you can no longer
reactivate this breakpoint unless you
again explicitly set it.
Cancel button Click on Cancel to dismiss the dialog
box.
Help button Click on Help to display this help
information.
27 – examine_hlp
The Examine dialog box allows you to display the current value of a
variable or expression in the command view. If you choose, you can
change the type or output radix of the displayed value.
To use the Examine dialog box, perform the following steps:
1. Do one of the following:
- Find and select the variable name or expression symbols in a
window, and choose the Examine menu item from the Commands menu
on the main window. The Examine dialog box appears, with the
name you selected in the Variable/Expression field.
- Choose the Examine menu item from the Commands menu on the main
window. The Examine dialog box appears. Enter the name of the
variable or symbols of the expression you are examining in the
Variable/Expression field of the dialog box.
2. If you are changing the output type, pull down the menu in the
Typecast entry box and click on the desired data type.
3. If you are changing the output radix, pull down the menu in the
Output Radix entry box and click on the desired radix.
4. Click on Apply to give the command or click on OK to give the
command and dismiss the dialog box.
Your echoed command and the current value appear in the command view.
Click on Cancel to dismiss the dialog box.
Click on Help to display this Help information.
28 – deposit_hlp
The Deposit dialog box allows you to change the current value of a
variable. If you choose, you can change the input radix of the
deposited value.
To use the Deposit dialog box, perform the following steps:
1. Do one of the following:
- Find and select the variable name in a window, and choose the
Deposit menu item from the Commands menu on the main window.
The Deposit dialog box appears, with the name you selected in
the Variable field.
- Choose the Deposit menu item from the Commands menu on the main
window. The Deposit dialog box appears. Enter the name of the
variable to which you are depositing a value in the Variable
field of the dialog box.
2. Enter the value you are depositing in the Value field of the dialog
box.
3. If you are changing the input radix, pull down the menu in the
Input Radix entry box and click on the desired radix.
4. Click on Apply to give the command or click on OK to give the
command and dismiss the dialog box.
Your echoed command and the current value appear in the command view.
Click on Cancel to dismiss the dialog box.
Click on Help to display this Help information.
Your echoed command appears in the command view, indicating that the
value is changed.
29 – editor_hlp
Use the editable source window to edit the source code of the program
you are currently debugging, or any other source code file.
Location Function
--------- -----------
Buffer Displays an empty text buffer for text entry,
or a full text buffer containing the text you will
edit.
Search String Accepts a string for forward or backward search.
Entry Box
Directional Indicates the direction (forward, backward) of
Arrows a search.
Replace String Indicates whether search string is replaced when
Toggle found.
Replace String Accepts a string that replaces the specified
Entry Box search string.
Buffer Menu Provides a list of active buffers, any of which
you can choose to display.
30 – editor_find_hlp
Use the Find Text field to search for a specified string.
The direction of the search is controlled as follows:
- Press an arrow key to search text in the direction indicated by
that arrow. This also sets the default search direction.
- Press Ctrl/N to search forward (down) through the file, regardless
of the arrow indicator position.
- Press Ctrl/P to search backwards (up) through the file, regardless
of the arrow indicator position.
If you click the "Replace with" toggle button, the editor replaces each
instance of the search string with the text entered in the Replace with
field.
31 – editor_replace_hlp
Use the Replace with field to replace a specified string. After you enter the search string in the Find Text field and indicate a search direction, click the "Replace with" toggle button and enter the replacement string. The editor replaces each instance of the search string with the replacement string.
32 – editor_pd_menu_hlp
Use the menus on the menu bar as explained in the Additional Topics.
33 – fill_buffer
By default,the editor window displays an empty text buffer, called dbg_editor_main. If you are debugging a program at the time you invoke the editor, however, the editor window displays this program, names the filled text buffer with its specification, and places dbg_editor_main on the buffer menu as an alternative text buffer. The editor allows you to create any number of text buffers by choosing New (for empty text buffers) or Open (for existing files) from the File menu. The name of each buffer appears in the buffer menu. You can cut, copy, and paste text across buffers by choosing items from the Edit menu and selecting buffers from the buffer menu.
34 – search_text
Forward and backward search and replace operations can be performed by entering strings in the Find text and Replace with entry boxes and clicking on a directional arrow. If you continue to click on a directional arrow, or if you continue to press the Return key, a repeated search for the string occurs in the direction you indicate. You can also continue a search by choosing the Find/Replace Next or Find/Replace Previous items in the Edit menu.
35 – recompile_edits
When you complete your edits, and save these to your file by choosing the Save or Save As items from the editor's File menu, you need to recompile and relink your source file. You do not need to exit the debugger to do this. Enter the compile and link commands in another DECterm window, and when you return to the debugger, choose the Rerun Same item in the File menu on the main window. Your edited source code will appear in the debugger's source view.
36 – editor_file_pd_menu_hlp
Use the File menu on the editable source window as follows: Action Function ------ -------- New Opens a buffer for a new file. Open... Opens a buffer for an existing file. Save Saves the current buffer using same file name. Save As... Saves the current buffer using specified file name. Close Closes the editable source window. Editor
37 – editor_filesel_hlp
Use the Open/Save dialog box to specify the file you are opening
(before editing) or the file you are saving to (after editing), as
follows:
1. If the default value (for your current directory) is not
acceptable, click on the name of another directory from the
directory list.
2. In the list of files, click on the file name you are opening or
saving to.
3. Click on OK.
38 – editor_edit_pd_menu_hlp
Use the Edit menu on the editable source window as follows:
Action Function
------ --------
Cut Cuts selected text from the window and
copies it to the clipboard.
Copy Copies selected text from the window to
the clipboard without removing it
from the window.
Paste Pastes text from the clipboard to a
text-entry field or region.
Clear Clears the text selected (highlighted)
in the window.
Find/Replace Finds and replaces the next instance.
Next
(or Ctrl/N)
Find/Replace Finds and replace the previous instance.
Previous
(or Ctrl/P)
Refresh File Loads and displays the latest version
of the file in the selected editor
buffer. This is convenient for checking
.LOG and other results files during
debugging.
Close File Removes the currently selected edit
buffer from the display and menu,
closes the file, and frees associated
memory. Prompts the user to save or ignore
any modifications to the edit buffer.
39 – editor_text_buffer_menu
Use the Buffer menu on the editable source window as follows:
Action Function
------ --------
None Identifies the text buffer that is
currently active.
Pull-down menu Identifies all other text buffers that
are currently active, including the empty
text buffer, dbg_editor_main.
Clicking on Allows you to switch from one active
a buffer in buffer to another. You can cut, copy,
the pull-down and paste text across buffers by choosing
menu items from the Edit menu and selecting buffers
from the Buffer menu.
40 – options_viewsel_hlp
Use the Views dialog box as follows: Action Function ------ -------- File View Closes dialog box or exits debugger. Breakpoint View Displays the breakpoint view. Monitor View Displays the monitor view. Instruction View Displays the instruction view. Register View Displays the register view. Threads View Displays the threads view.
41 – optional_view_sel_hlp
Use the Views dialog box as follows: Action Function ------ -------- Breakpoint View Displays the breakpoint view. Monitor View Displays the monitor view. Instruction View Displays the instruction view. Register View Displays the register view. Threads View Displays the threads view.
42 – views
At startup, the debugger displays only one window, the main window.
To display additional information on your program in the optional view
window, perform the following steps:
1. Choose the Views... menu item from the Options menu on the main
window. The Views dialog box appears.
2. Click on one or more of the following views in the dialog box:
Breakpoint View Displays the breakpoint view.
Monitor View Displays the monitor view.
Instruction View Displays the instruction view.
Register View Displays the register view.
Threads View Displays the threads view.
These views appear within the optional view window on your screen.
To select different views, repeat this process, clicking on different
views within the View dialog box.
43 – close_views
To dismiss all views and close the optional view window, do one of the
following:
- Choose the Views... menu item from the Options menu on the main or
optional view window. When the Views dialog box appears, clear all
the toggle buttons within the dialog box, and click on OK.
- Choose the Close menu item from the File menu on the optional view
window to close the optional view window.
- Choose the Close menu item from the File menu on the instruction
window to close the instruction window.
44 – custm_db_hlp
Use the Customize Button Dialog box to modify, add, remove, or resequence push buttons and the associated debugger commands. NOTE: You cannot modify or remove the Stop push button.
45 – custm_add_hlp
Use the Add push button to add a new push button to the push-button view in the main window.
46 – custm_mod_hlp
Use the Modify push button to modify the label, icon, or debugger command associated with a push button in the push-button view.
47 – custm_remove_hlp
Use the Remove push button to remove a push button from the push-button view in the main window.
48 – custm_larrow_hlp
Use the Left Arrow button to move a push button one push button to the left in the push-button view.
49 – custm_rarrow_hlp
Use the Right Arrow push button to move a push button one push button to the right in the push-button view.
50 – on_context_hlp
Invisible: Brings up the ? pointer for context-sensitive help.
51 – on_mwindow_hlp
The OpenVMS Debugger helps you locate run-time programming or logic
errors, also known as bugs. You use the debugger with a program that
has been compiled and linked successfully but does not run correctly.
For example, the program might give incorrect output, go into an
infinite loop, or terminate prematurely. You locate errors with the
debugger by observing and manipulating your program interactively as it
executes. The debugger lets you:
- Display and edit the source code for your program, and browse
through other source code files.
- Monitor, examine, and change program variable and data structure
values and examine their type.
- Examine and manipulate the currently active functions on the call
stack.
- Set breakpoints that suspend program execution or issue debugger
command sequences.
- Step through execution one line of source code or machine
instruction at a time.
- Disassemble and examine machine code; examine and modify
machine-register values.
- Customize the debugging environment.
These are the basic debugging techniques. After you are satisfied that
you have found the error in the program, you can edit the source code
and compile, link, and execute the corrected version.
As you use the debugger and its documentation, you will discover
variations on the basic techniques. You can also customize the
debugger to meet your own needs.
The debugger is a symbolic debugger. You can specify variable names,
routine names, and so on, precisely as they appear in your source code.
You do not need to specify memory addresses or registers when referring
to program locations, but you can if you want.
You can also use the debugger with programs written in any of the
languages identified in the topic Debugger Support for Languages.
52 – on_owindow_hlp
The OpenVMS Debugger helps you locate run-time programming or logic
errors, also known as bugs. You use the debugger with a program that
has been compiled and linked successfully but does not run correctly.
For example, the program might give incorrect output, go into an
infinite loop, or terminate prematurely. You locate errors with the
debugger by observing and manipulating your program interactively as it
executes. The debugger lets you:
- Display and edit the source code for your program, and browse
through other source code files.
- Monitor, examine, and change program variable and data structure
values and examine their type.
- Examine and manipulate the currently active functions on the call
stack.
- Set breakpoints that suspend program execution or issue debugger
command sequences.
- Step through execution one line of source code or machine
instruction at a time.
- Disassemble and examine machine code; examine and modify
machine-register values.
- Customize the debugging environment.
These are the basic debugging techniques. After you are satisfied that
you have found the error in the program, you can edit the source code
and compile, link, and execute the corrected version.
As you use the debugger and its documentation, you will discover
variations on the basic techniques. You can also customize the
debugger to meet your own needs.
The debugger is a symbolic debugger. You can specify variable names,
routine names, and so on, precisely as they appear in your source code.
You do not need to specify memory addresses or registers when referring
to program locations, but you can if you want.
You can also use the debugger with programs written in any of the
languages identified in the topic Debugger Support for Languages.
53 – on_ewindow_hlp
Use the editable source window to edit the source code of the program you are currently debugging, or any other source code file. For information on tasks in the editable source window, see the Additional Topics below.
54 – on_iwindow_hlp
Use the instruction window to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions For information on tasks in the instruction window, see the Additional Topics below.
55 – on_help_hlp
Several kinds of online help about the debugger and debugging are
available during a debugging session:
- Context-sensitive help, which is information about an area or
object in a window or dialog box
- Task-oriented help, which consists of an introductory help topics
describing the tasks that can be accomplished in each window of the
debugger and several subtopics on specific debugging tasks
- Help on debugger commands and various topics, such as language
support
- Help on debugger diagnostic messages
Related context-sensitive and task-oriented topics are connected
through the list of Additional Topics in the Help windows.
56 – on_version_hlp
OpenVMS Debugger Software Version: OpenVMS Debugger Version 8.2 © 2005 Hewlett-Packard Development Company, L.P. All rights reserved. For more information about the OpenVMS Debugger, double click on Using the Main Window from the list of Additional Topics below.
57 – on_command_hlp
58 – debug_error_hlp
The error dialog box contains a brief description of an internal inconsistency detected by the debugger. If the cause of the error is not obvious, select the Help Menu on the Main Window, select On_Commands, select Messages, and scroll through the display until you can select the message code that is displayed in the error dialog box. You may find more information about the error in the OpenVMS System Messages and Recovery Procedures manual.
59 – breakpoint_disp_hlp
Use the breakpoint view to do the following: - Identify the breakpoints that are currently set in your program - Review or change breakpoint status - Display conditions or actions associated with breakpoints - Modify conditions or actions associated with breakpoints - Set new breakpoints Breakpoints are listed in the Identification column of the view, including the module name and line number for each breakpoint. All breakpoints listed in the breakpoint view have been previously set. A filled-in button in the State column indicates that the breakpoint is set and active. A cleared button indicates that the breakpoint has been deactivated. (If you delete a breakpoint, the breakpoint entry disappears from the breakpoint view.) If you have set a conditional breakpoint, the button shape changes from a square to a diamond. You can also double-click on a breakpoint entry to determine whether conditions or actions are associated with it.
60 – popup_break
To use the pop-up menu in the breakpoint view, position your mouse
pointer in the breakpoint list or annotation area of the breakpoint
view, and press MB3.
A pop-up menu with the following items appears:
Toggle Toggles a selected breakpoint.
Set/Modify... Provides the Set/Modify Breakpoint dialog box,
which contains information about a selected
breakpoint.
Cancel Removes a selected breakpoint.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
61 – monitor_disp_hlp
Use the monitor view to:
- Monitor the value of a variable or an expression during the
execution of your program
- Watch a variable during the execution of your program
- Change the value of a variable
To add an entry to the monitor list, select a variable name or
expression in the source view and click on the Monitor push button.
The debugger displays the current value in the monitor view and checks
and updates the displayed value whenever it regains control from your
program (for example, after a step or at a breakpoint).
Monitored variables and expressions are listed in the Monitor
Expression column. Their values are listed in the Value/Deposit
column.
The button in the Watched column indicates whether the variable is
being watched (button filled) or not (button empty).
62 – popup_monitor
To use the pop-up menu in the monitor view, position your mouse pointer
in the monitor view, and press MB3.
A pop-up menu with the following items appears:
Expand Expand a monitored aggregate to show its members.
Collapse Collapse an expanded aggregate.
Toggle Watchpoint Activates or deactivates a selected watchpoint.
Typecast -> Provides the list of type choices for modifying values.
Change Radix -> Provides the list of radix choices for modifying values.
Remove Remove the selected expression from the monitor
list of the monitor view.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
63 – register_view_hlp
Use the register view to: - Display the current values stored in the machine registers. - Modify the value stored in a register Any values that change as your program executes are highlighted whenever the debugger regains control from your program.
64 – popup_register
To use the pop-up menu in the register view, position your mouse pointer in the register view, and press MB3. A pop-up menu with the following menu items appears: Change Radix -> Provides the list of radix choices for modifying values. Step Step to next line, stepping over routine calls. Go Resume execution of program.
65 – inst_view_hlp
Use the instruction view to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions
66 – inst_workarea_hlp
Use the instruction view to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions
67 – popup_instruction
To use pop-up menus in the instruction view, select text or position
your mouse pointer in the instruction window, and press MB3. The
debugger inserts the selected text or line number in the menu items of
the pop-up menu.
If you press MB3 while your mouse pointer rests on an instruction
source line in the instruction window, a pop-up menu with the following
items appears:
Examine [selection] Evaluates the selected text and prints
its value in the command view.
Toggle Breakpoint Toggle breakpoint at your mouse pointer location.
[line number]
Display Source Display source associated with instruction.
Step-Instructions Step to next instruction, stepping over routine
calls.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
If you press MB3 while your mouse pointer rests in the annotation area
of the instruction window, a pop-up menu with the following items
appears:
Toggle Breakpoint Toggle breakpoint at your mouse pointer location.
Step Step to next line, stepping over routine calls.
Go Resume execution of program.
68 – task_view_hlp
Use the thread view to display information about the threads (tasks) of a multithreaded program.
69 – task_workarea_hlp
Use the threads view to display information about the threads (tasks) of a multithreaded program.
70 – cnt_window_hlp
Use the threads view to display information about the threads (tasks) of a multithreaded program.
71 – popup_task
To use pop-up menus in the threads view, select a thread from the list
or position your mouse pointer in the threads view, and press MB3.
A pop-up menu with the following menu items appears:
Abort Requests that the selected thread be terminated
at the next allowed opportunity. The exact effect
depends on the current event facility (which is
language dependent). For Ada tasks, this is
equivalent to executing an abort statement.
Activate Makes the selected thread the active thread.
Hold Places the selected thread on hold.
Nohold Releases the selected thread on hold.
Visible Makes the selected thread the visible thread.
72 – cnt_window_menubar_hlp
Use the menus on the menu bar as explained in the Additional Topics.
73 – cnt_file_pd_menu_hlp
Use the File menu on the optional view window as follows:
Action Function
------ --------
Close Closes the optional view window.
Exit Debug? In the kept debugger, ends the
debugging session, and exits the
debugger. In client-server mode,
allows you to exit the client,
server, or both.
74 – cnt_break_pd_menu_hlp
Use the Break menu on the optional view window as follows:
Action Function
------ --------
On Exception Breaks on any exception signaled
during program execution.
Activate All Activates any previously set
breakpoints.
Deactivate All Deactivates any previously set
breakpoints.
Cancel All... Removes all breakpoints from the
debugger's breakpoint list and
from the breakpoint view.
Toggle Toggles an individual breakpoint.
Set/Modify... Sets or modifies an individual breakpoint.
Cancel Removes an individual breakpoint.
75 – cnt_monitor_pd_menu_hlp
Use the Monitor menu on the optional view window as follows:
Action Function
------ --------
Expand Expands a selected nonscalar variable.
Collapse Collapses a selected nonscalar variable.
Deposit... Changes the value of variable.
Toggle
Watchpoint Activates or deactivates a watchpoint.
Typecast -> Typecasts a selected variable.
Change Radix -> Changes the radix for a selected variable.
Change All
Radix -> Changes the default radix for all subsequent
monitor entries.
Remove Removes the monitor entry from display.
76 – cnt_register_pd_menu_hlp
Use the Register menu on the optional view window as follows:
Action Function
------ --------
Assign... Modifies the selected register.
Change Radix -> Changes the radix for a selected register.
Change All
Radix -> Changes the radix for all registers.
77 – cnt_task_pd_menu_hlp
Use the Threads menu on the optional view window as follows:
Action Function
------ --------
Abort Requests that the selected thread be terminated
at the next allowed opportunity. The exact effect
depends on the current event facility (which is
language dependent). For Ada tasks, this is
equivalent to executing an abort statement.
Activate Makes the selected thread the active thread.
Hold Places the selected thread on hold.
Nohold Releases the selected thread on hold.
Make Makes the selected thread the visible thread.
Visible
All -> Uses the submenu to:
Abort all threads.
Hold all threads.
NoHold all threads.
78 – inst_window_menubar_hlp
Use the menus on the menu bar as explained in the Additional Topics.
79 – inst_file_pd_menu_hlp
Use the File menu on the Instruction View as follows:
Action Function
------ --------
Show Instruction Displays the address associated
Addresses with each instruction listed in
the instruction view.
Display Line Displays the line number of your
Numbers source-code program associated with
each instruction or set of instructions
listed in the instruction view.
Close Closes the instruction window.
80 – inst_edit_pd_menu_hlp
Use the Edit menu on the instruction view as follows:
Action Function
------ --------
Copy Copies text that you have selected in the
window to the clipboard without removing it
from the window.
(To paste your text from the clipboard to
a text-entry field or region, choose the
Paste item from the Edit menu on the
main window.)
81 – inst_break_pd_menu_hlp
Use the Break menu on the instruction window as follows:
Action Function
------ --------
Activate All Activates any previously set
breakpoints.
Deactivate All Deactivates any previously set
breakpoints.
Cancel All Removes all breakpoints from the
debugger's breakpoint list and
from the instruction view.
Set... Sets an individual breakpoint.
82 – server_connection_help
The Connection dialog is used to manage connections between a DECwindows Motif debug client and a debug server running on OpenVMS. You can use the Server Connection dialog to make new connections to servers, reconnect to servers that you have connected to before, monitor the status of existing active sessions, switch the display context among active sessions, test and shutdown servers, and limit the number of clients that a server will accept. See Additional Topics for specific information about the Server Connection dialog. To display the Server Options dialog of the Connection dialog box, click the Properties button, or open the Options menu, then click Connection dialog on the Properties submenu. Click sections of the Connection dialog box below to see a description of each control on the dialog box. Please refer to the OpenVMS Debugger manual for more information..
83 – conn_dialog_connect
Click Connect to initiate the connection request to the server identified in the Connection list. Status of the connection request is displayed in the message display of the Command view. Additional status is displayed at the bottom of the Server Connection dialog to indicate whether the requested connection has been established as a new active session. When a connection has been successfully made to a server the Server Connection dialog is dismissed and the Command view displays a client prompt to indicate that the server is ready to accept debugger commands. A new Source view is created, and all other active views display information in the context of the active session.
84 – conn_dialog_disconnect
Click Disconnect to disconnect the client from the currently active session as indicated in the Active Sessions list.
85 – conn_dialog_test
Click Test to test the connection between the debug client and the debug server. If the connection is operating correctly, the status "Server is Listening" appears in the lower portion of the Connection dialog box.
86 – conn_dialog_stop
Click Stop to cause the debug server associated with the currently active session to be shut down. Note: Once a server has been shut down, clients can no longer connect to it. To restart a server, type DEBUG/SERVER at the command prompt on the OpenVMS system.
87 – conn_dialog_options
Click Options in the Server Connection dialog to display the Server Options dialog for the currently selected session as indicated by the Active Sessions list in the Server Connection dialog. The Server Options dialog lets you select the connection protocol, and the maximum number of clients that are allowed to connect to a server. Once a session has been established, you cannot change the connection protocol. If you are the first client (the primary client) to connect to a server, you can control the maximum number of secondary clients that are allowed to connect to the server.
88 – c_s_primary_client
The primary client is the first client to connect to the server. The primary client uses the Server Options dialog to control whether or not any secondary clients can connect to the server.
89 – c_s_secondary_client
A secondary client is an additional client that has connected to the same server. Each clients that is connected to a session can enter debugger commands in the context of that session. The debugger display of each client connected to that session is updated reflect the current context of the session. Whether or not secondary clients are allowed is controlled by the primary client in the Server Options dialog.
90 – conn_dialog_connections
Use the Connection [local] list to specify the identification string of
the debug server with which you want to establish a session. Type or
select the identification string in the New Connection box. The New
Connection list contains the last 10 connections that you have made and
provides a convenient way to reconnect to a server from which you
previously disconnected and left running. Note that the presence of a
connection path in the list does not guarantee that the server is still
available
The most simple connection string contains the name of the OpenVMS node
followed by the port number within square brackets. For example:
NODNAM[4111]
Other examples of valid connection strings:
ncacn_ip_tcp:16.32.16.138[4111]
16.32.16.138
nodnam.bld.dec.com
nodnam.bld.dec.com[4112]
ncacn_dnet_nsp:19.10[RPC2BE08EF00001]
91 – conn_dialog_active_sessions
The Active Sessions list contains the sessions (connections to debug servers) that this client has already established. The session at the top of the list is the currently active session. All debugger views reflect the context of the program being debugged on the currently active session. You can switch between active sessions by selecting a session from the Active Sessions list. The Source view for that session is activated and all other debugger views are updated to reflect the program context of that session. All buttons on the Server Connection dialog, including Disconnect, Stop Server, Test and Properties as well as the status section of the Server Connection dialog are related to and act upon the currently active session.
92 – conn_dialog_cancel
Click Cancel to dismiss the Server Connection dialog.
93 – interfaces
The debugger has the following user-interface options to accommodate
different needs and debugging styles:
- The debugger has a DECwindows Motif interface for workstations.
The default DECwindows Motif interface provides the basic debugging
and convenience features that you will probably need most of the
time.
- The debugger has a command interface for character-cell terminals
and workstations. In addition to general-purpose debugging
features, the command interface provides special features not
available through the default DECwindows Motif interface.
- The DECwindows Motif interface is layered on the command interface
and has a command-entry prompt (in the command view of the main
window). From the DECwindows Motif interface, you can enter
debugger commands for the following purposes:
+ As an alternative to using the DECwindows Motif interface for
certain operations
+ To do tasks not available through the DECwindows Motif
interface
- You can customize the DECwindows Motif interface with many of the
special features of the command interface by modifying the push
buttons in the push-button view (and their associated debugger
commands) or by adding new push buttons.
94 – windows_menus
By default, the debugger starts up in the main window, which includes a source view, a push-button view, and a command view. When you start the debugger with the command DEBUG/KEEP from DCL level, the source view is initially empty. You can then bring a program under debugger control.
95 – cmd_entry
The debugger's DECwindows Motif interface is layered on the command
interface. The command-entry prompt (DBG>), located in the command
view, lets you enter debugger commands for the following purposes:
- As an alternative to using the DECwindows Motif interface for
certain operations
- To do debugging tasks not available through the DECwindows Motif
interface
When you use the DECwindows Motif interface, the debugger translates
your input into debugger commands. These commands are echoed in the
command view, at the prompt, so that you can correlate your input with
the corresponding command line that the debugger processes. Echoed
commands are visually indistinguishable from commands that you enter
explicitly.
In addition to entering debugger commands interactively at the prompt,
you can also enter them in debugger initialization files and command
files for execution under the DECwindows Motif environment.
96 – disabled_vms_cmds
The following table lists the debugger commands that are not available in the debugger's DECwindows Motif interface. Many of them are relevant only to the command interface's screen mode. ATTACH SELECT CANCEL MODE (SET,SHOW) ABORT_KEY CANCEL WINDOW (SET,SHOW) KEY DEFINE/KEY (SET,SHOW) MARGINS DELETE/KEY SET MODE [NO]KEYPAD DISPLAY SET MODE [NO]SCREEN EXAMINE/SOURCE SET MODE [NO]SCROLL EXPAND SET OUTPUT [NO]TERMINAL EXTRACT (SET,SHOW) TERMINAL HELP (SET,SHOW) WINDOW MOVE (SHOW,CANCEL) DISPLAY SAVE SHOW SELECT SCROLL SPAWN The debugger issues an error message if you try to enter any of these disabled commands at the command-entry prompt, or when the debugger executes a command procedure containing any of these commands.
97 – language_support
On VAX processors, you can use the debugger with programs written in
any of the following source languages:
Ada BASIC BLISS C
C++ COBOL DIBOL Fortran
MACRO-32 Pascal PL/I RPG II
SCAN
On Alpha processors, you can use the debugger with programs written in
any of the following source languages:
Ada BASIC BLISS C
C++ COBOL Fortran MACRO-32
MACRO-64 Pascal PL/I
On I64 processors, you can use the debugger with programs written in
any of the following source languages:
Assembler (IAS) BASIC BLISS C
C++ COBOL Fortran MACRO-32
IMACRO Pascal
The debugger recognizes the syntax, data types, operators, expressions,
scoping rules, and other constructs of a supported language.
For more information about debugger support for a particular language:
1. Choose On Commands from the Help menu in a debugger window.
2. Choose Language_Support from the list of Additional Topics.
3. Choose the language name from the list of Additional Topics.
98 – trademarks
Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. Intel® and Itanium® are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
99 – compile
To bring a program under debugger control and take full advantage of
symbolic debugging, you must first compile and link the program as
explained here.
You can use the debugger with programs written in any of the source
languages listed in the topic Debugger Support for Languages. The
following example shows how to compile and link a C program named
EIGHTQUEENS before using the debugger. The compiler and linker are
invoked from DCL level ($). The program's source code is in the file
EIGHTQUEENS.C.
On VAX systems, you explicitly identify linker options files in your
LINK command:
$ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS
$ LINK/DEBUG EIGHTQUEENS,OPTIONS_FILE/OPTIONS
On Alpha and I64 systems, you do not identify linker options files:
$ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS
$ LINK/DEBUG EIGHTQUEENS
The /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults for
some languages. These qualifiers are used in the example for emphasis.
(For more information about compiling and linking that is specific to a
particular language, see the documentation furnished with that
language.)
The /DEBUG qualifier on the compiler command (CC in this case) directs
the compiler to write the symbol information associated with
EIGHTQUEENS.C into the object module, EIGHTQUEENS.OBJ, in addition to
the code and data for the program. This symbol information lets you
use the names of variables, routines, and other symbols declared in
EIGHTQUEENS.C when using the debugger. If your program's source code
is in several files, you must compile each file whose symbols you want
to reference with the /DEBUG qualifier.
Some compilers optimize the object code to reduce the size of the
program or to make it run faster. In such cases you should compile
your program with the /NOOPTIMIZE command qualifier (or equivalent)
when preparing for debugging. Otherwise, the contents of some program
locations might be inconsistent with what you would expect from viewing
the source code. For example, some optimization techniques eliminate
certain variables so that you no longer have access to them while
debugging. (After the program has been debugged, you will probably
want to recompile it without the /NOOPTIMIZE qualifier to take
advantage of optimization.)
The /DEBUG qualifier on the LINK command directs the linker to include
all symbol information that is contained in EIGHTQUEENS.OBJ in the
executable image. The qualifier also causes the image activator to
start the debugger at run time if you start the debugger by running a
program, using the following DCL command syntax:
$ DEBUG/KEEP
If your program has several object modules, you need to specify those
modules in the LINK command (for most languages).
On VAX processors, the /OPTIONS qualifier indicates that OPTIONS_FILE
is a linker options file. In the OpenVMS VAX example, the file
specifies a run-time library to be linked with the program.
Even if you compile and link an image with the /DEBUG command
qualifier, you can execute that image normally without it being under
debugger control. To do so, use the /NODEBUG qualifier on the DCL RUN
command. For example:
$ RUN/NODEBUG EIGHTQUEENS
This is convenient for checking your program after you think it is
error free. Note that the data required by the debugger occupies space
within the executable image. So, when you think your program is
correct, you might want to link your program again without the /DEBUG
qualifier. This creates an image with only traceback data in the debug
symbol table, which uses less disk space.
On Alpha and I64 systems, you can debug programs that have been linked
with the /DSF qualifier (and therefore have a separate debug symbol
file). The /DSF qualifer to the LINK command directs the linker to
create a separate .DSF file to contain the symbol information. This
allows more flexible debugging options. Debugging such a program
requires the following:
1. The name of the .DSF file must match the name of the .EXE file
being debugged.
2. You must define DBG$IMAGE_DSF_PATH to point to the directory that
contains the .DSF file.
For example:
$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM
$ LINK/DSF=TESTDISK:[TESTDIR]TESTPROGRAM.DSF TESTPROGRAM
$ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR]
$ DEBUG/KEEP TESTPROGRAM
100 – stop
To interrupt program execution during a debugging session, click on the Stop push button on the push-button view in the main window. This is useful if, for example, the program is in an infinite loop. To abort a debugger operation in progress, click on Stop. This is useful if, for example, the debugger is displaying a long stream of data. Clicking on Stop does not end the debugging session. Clicking on Stop when the program is not running or when the debugger is not doing an operation has no effect.
101 – exit
To end a debugging session and exit the debugger, choose Exit Debug? from the File menu on the main window. This invokes a Confirm Exit dialog box to verify that you wish to exit the debugger. In the kept debugger, clicking on Yes returns control to system level. In client-server mode, allows you to exit the client, the server, or both. To rerun your program from the current debugging session, see the Rerunning the Same Program topic. To run another program from the current debugging session, see the Bringing a Program Under Debugger Control topic.
102 – src_display
The debugger displays the source code of your program in the source view of the main window. Whenever execution is suspended (for example, at a breakpoint), the debugger updates the source view, which displays the code surrounding the point at which execution is paused. The current-location pointer, to the left of the source code, marks the line whose code will execute next. (A source line corresponds to one or more programming language statements, depending on the language and coding style.) By default, the debugger displays compiler-generated line numbers to the left of the source code. These numbers help you identify breakpoints that are listed in the breakpoint view. You can choose not to display line numbers so that more of the source code can show in the window. To hide or display line numbers, choose Show Line Numbers from the File menu on the main window. The Call Stack menu, at the bottom right of the source window, shows the name of the routine whose source code is displayed. The current-location pointer is normally filled in. It is cleared if the displayed code is not that of the routine in which execution is paused (see the Making Source Code Available for Display and the Setting the Current Scope Relative to the Call Stack topics). You can use the scroll bars to show more of the source code. However, you can scroll vertically through only one module of your program at a time. (A module corresponds generally to a compilation unit. With many programming languages, a module corresponds to the contents of a source file. With some languages, such as Ada, a source file might contain one or more modules.) The Displaying Source Code in Another Module topic explains how to display source code for other parts of your program so that you can set breakpoints in various modules, and so on. The Making Source Code Available for Display topic explains what to do if the debugger cannot find source code for display. The Setting the Current Scope Relative to the Call Stack topic explains how to display source code for routines that are currently active on the call stack. After navigating through the source view, you can redisplay the location at which execution is paused by clicking on the Call Stack menu. If your program was optimized during compilation, the source code displayed might not reflect the actual contents of some program locations (see the Compiling and Linking Your Program for Debugging topic).
103 – src_display_module
To display source code in another module:
1. Choose Browse Source from the File menu on the main window. From
the submenu, select All to list all modules, select Symbolic to
list only those modules for which symbolic information is
available. The Browse Source dialog box appears, listing your
executable image, which is highlighted, and all the shareable
images linked with it (for example, DEBUG and LIBRTL). If the name
of an image is dimmed, no symbolic information is available for
that image.
2. Double click on the name of your executable image. The names of
the modules in that image are displayed (indented) under the image
name.
3. Click on the name of the module whose source code you want to
display. The Display Source button is now highlighted.
4. Click on Display Source. The source view now displays that
module's source code.
104 – src_display_nosrc
In certain cases, the debugger cannot display source code. Possible
causes are:
- Execution might be paused within a module of your program that was
compiled without the debug option.
- Execution might be paused within a system or library routine for
which no symbolic information is intended to be available. In such
cases you can quickly return execution to the calling routine by
clicking one or more times on the Step-Return push button on the
push-button view of the main window.
- The source file might have been moved to a different directory
after it was compiled. The Specifying the Location of Source Files
topic explains how to tell the debugger where to look for source
files.
If the debugger cannot find source code for display, it tries to
display the source code for the next routine down on the call stack for
which source code is available. If the debugger can display source
code for such a routine, the current-location pointer is cleared and
marks the source line to which execution returns in the calling
routine.
105 – src_display_srcfile
Information about the characteristics and the location of source files is embedded in the debug symbol table of your program. If a source file has been moved to a different directory since compile time, the debugger might not find the file. To direct the debugger to your source files, use the SET SOURCE command at the command-entry prompt.
106 – execute
The Additional Topics explain techniques for executing your program.
107 – exec_paused
To determine where execution is currently paused within your program:
1. If the current-location pointer is not visible in the source view,
click on the Call Stack menu of that window to display the pointer.
2. Look at the current-location pointer:
- If the pointer is filled in, it marks the source line whose
code will execute next. The Call Stack menu always shows the
routine at level 0 (where execution is paused) when the pointer
is filled in.
- If the pointer is cleared, the source code displayed is that of
a calling routine, and the pointer marks the source line to
which execution returns in that routine as follows:
+ If the Call Stack menu shows level 0, source code is not
available for display for the routine in which execution is
paused.
+ If the Call Stack menu shows a level other than 0, you are
displaying the source code for a calling routine.
To list the sequence of routine calls that are currently active on the
call stack, click on the Call Stack menu. Level 0 denotes the routine
in which execution is paused, level 1 denotes the calling routine, and
so on.
108 – start_exec
To start program execution or resume execution from the current
location, click on the Go push button on the push-button view of the
main window.
Letting your program run freely without debugger intervention is useful
in situations such as the following:
- To test for an infinite loop. In this case, you start execution;
then, if your program does not terminate and you suspect that it is
looping, click on the Stop push button. The source view will show
where you interrupted program execution, and the Call Stack menu
will identify the sequence of routine calls at that point.
- To execute your program directly to a particular location. In this
case, you first set a breakpoint at the location and then start
execution.
Once started, program execution continues until one of the following
events occurs:
- The program completes execution
- A breakpoint is reached (including a conditional breakpoint whose
condition is true)
- A watchpoint is triggered
- An exception is signaled
- You click on the Stop push button in the push-button view on the
main window.
Whenever the debugger suspends execution of the program, the source
view is updated and the current-location pointer marks the line whose
code will execute next.
109 – step_one_line
To execute one source line of your program, click on the Step push
button on the push-button view of the main window. This debugging
technique (called stepping) is one of the most commonly used.
After the line executes, the source view is updated and the
current-location pointer marks the line whose code will execute next.
Note the following points about source lines and the stepping behavior:
- A source line can consist of one or more programming language
elements, depending on the language and coding style used.
- When you click on the Step push button, the debugger executes one
executable line and suspends execution at the start of the next
executable line, by skipping over any intervening nonexecutable
lines.
- Executable lines are those for which instructions were generated by
the compiler (for example, lines with routine call or assignment
statements). Executable lines have a toggle button to their left
in the source view.
- Examples of nonexecutable lines are comment lines or lines with
variable declarations without value assignments. Nonexecutable
lines do not have a toggle button to their left in the source view.
Keep in mind that if you optimized your code at compilation time, the
source code displayed might not reflect the code that is actually
executing.
<here>
110 – step_in
When program execution is paused at a routine call statement, clicking
on the Step push button typically executes the called routine in one
step (depending on the coding style used), and the debugger suspends
execution at the next source line in the calling routine (assuming no
breakpoint was set within the called routine). This lets you step
through the code quickly without having to trace execution through any
called routines (some of which might be system or library routines).
This is called stepping over called routines.
To step into a called routine so that you can execute it one line at a
time:
1. Suspend execution at the routine call statement, for example, by
setting a breakpoint (see the Suspending Execution with Breakpoints
topic) and then clicking on the Go push button on the push-button
view of the main window.
2. When execution is paused at the call statement, click on the
Step-In push button on the push-button view of the main window.
This moves execution just past the start of the called routine.
Once execution is within the called routine, use the Step push button
to execute the routine line by line.
Clicking on the Step-In push button when execution is not paused at a
routine call statement is the same as clicking on the Step push button.
111 – step_return
When execution is suspended within a called routine, you can execute your program directly to the end of that routine by clicking on the Step-Return push button on the push-button view of the main window. The debugger suspends execution just before the routine's return instruction executes. At that point, the routine's call frame has not been deleted from the call stack, so you can still get the values of variables local to that routine, and so on. The Step-Return push button is particularly useful if you have inadvertently stepped into a system or library routine.
112 – break
A breakpoint is a location in your program at which you want execution
to stop so that you can check the current value of a variable, step
into a routine, and so on.
When using the debugger's DECwindows Motif interface, you can set
breakpoints on:
- Specific source lines
- Specific routines (functions, subprograms, and so on)
- Specific instructions (displayed in the instruction view)
- Exceptions signaled during the execution of your program
The debugger provides two ways to qualify breakpoints:
- You can set a conditional breakpoint. It triggers only when a
specified relational expression is evaluated as true.
- You can set an action breakpoint. It executes one or more
specified system-specific commands when the breakpoint triggers.
You can set a breakpoint that is both a conditional and action
breakpoint.
113 – break_srclin
You can set a breakpoint on any source line that has a toggle button to
its left in the source view. These are the lines for which the
compiler has generated executable code (routine declarations,
assignment statements, and so on).
To set a breakpoint on a source line:
1. Find the source line on which you want to set a breakpoint.
2. Click on the toggle button to the left of that line. (The
breakpoint is set when the toggle button is filled in.) The
breakpoint is set at the start of the source line--that is, on the
first machine-code instruction associated with that line.
114 – break_routine
Setting a breakpoint on a routine lets you move execution directly to
the routine and inspect the local environment.
To set a breakpoint on a routine:
1. Choose Browse Source from the File menu on the main window. From
the submenu, select All to list all modules, select Symbolic to
list only those modules for which symbolic information is
available. The Browse Source dialog box appears listing your
executable image, which is highlighted, and all the shareable
images linked with it (for example, DEBUG and LIBRTL). If the name
of an image is dimmed, no symbolic information is available for
that image.
2. Double click on the name of your executable image. The names of
the modules in that image are displayed (indented) under the image
name.
3. Double click on the name of the module whose source code you want
to display. The names of the routines in that module are displayed
in the Routine column.
4. Do one of the following:
- Double-click on the name of the routine on which you want to
set a breakpoint.
- Click on the name of the routine and then on the Set Breakpoint
button.
Either of these actions sets a breakpoint at the start of the
routine (directly after any prolog code). In the source view, the
toggle button to the left of the source line that contains the
start of the routine is now filled in, confirming that the
breakpoint is set. (If the breakpoint view is open, the breakpoint
will appear in the breakpoint list. If the instruction window is
open, the breakpoint will also display for the corresponding
instruction.)
115 – break_instruction
You can set a breakpoint on any instruction that has a toggle button to
its left in the annotation area. These are the lines for which the
compiler has generated executable code (routine declarations,
assignment statements, and so on).
To set a breakpoint on an instruction:
1. Find the instruction on which you want to set a breakpoint.
2. Click on the toggle button to the left of that line. (The
breakpoint is set when the toggle button is filled in.)
116 – break_exception
An exception breakpoint suspends execution when an exception is signaled and before any exception handler declared by your program executes. This allows you to step into the exception handler (if one is available) to check the flow of control. To set an exception breakpoint, choose On Exception from the Break menu. The exception breakpoint triggers whenever any exception is signaled.
117 – break_identify
There are two ways to determine which breakpoints are currently set:
- Scroll through your source or instruction code and note the lines
whose breakpoint button is filled in. This method can be time
consuming and also does not show which breakpoints were set and
then deactivated.
- Choose Views... from the Options menu on the main or optional view
window. When the Views dialog box appears, toggle breakpoint view.
Within the breakpoint view display, breakpoints are listed in the
Identification column of the view, including the module name and
line number for each breakpoint. A filled-in button in the State
column indicates that the breakpoint is set and active. A cleared
button indicates that the breakpoint is deactivated. (The
breakpoint view does not provide information on breakpoints that
have not been set or that have been deleted.)
118 – break_activ
After you set a breakpoint, you can deactivate it, activate it, or
cancel it.
Deactivating a breakpoint causes the debugger to ignore it during
program execution. However, the debugger keeps the breakpoint listed
in the breakpoint view so that you can activate it at a later time, for
example, when you rerun the program. Note the following points:
- To deactivate a specific breakpoint, clear the button for that
breakpoint in the source view, the instruction code display, or in
the breakpoint view.
In the breakpoint view, you can also choose Toggle from the Break
menu, if the breakpoint is currently activated.
- To deactivate all breakpoints, choose Deactivate All from the Break
menu on the main, instruction, or optional view window.
Activating a breakpoint causes it to take effect during program
execution:
- To activate a breakpoint, click on the button for that breakpoint
in the source view, instruction code display, or in the breakpoint
view.
In the breakpoint view, you can also choose Toggle from the Break
menu, if the breakpoint is currently deactivated.
- To activate all breakpoints, choose Activate All from the Break
menu on the main, instruction, or optional view window.
Canceling a breakpoint causes all information about the breakpoint to
be lost. Once you cancel a breakpoint, you cannot later reactivate it,
but must again explicitly set the breakpoint. Note the following
points:
- To cancel a specific breakpoint, choose Cancel from the Break menu
on the optional view window.
- To cancel all breakpoints, choose Cancel All from the Break menu on
the main, instruction, or optional view window.
119 – break_cond
A conditional breakpoint suspends execution only when a specified
expression is evaluated as true. For example, you can specify that a
breakpoint take effect when the value of a variable in your program is
4. The breakpoint is ignored if the value is other than 4.
The debugger evaluates the conditional expression when the breakpoint
triggers during execution of your program.
The following procedure sets a conditional breakpoint:
1. Display the source or instruction line on which you want to set the
conditional breakpoint.
2. Display the Set/Modify Breakpoint dialog box in one of the
following ways:
- Press Ctrl/MB1 on the button to the left of a source line, an
instruction line, or a breakpoint entry in the breakpoint view.
This causes the Set/Modify Breakpoint dialog box to display,
showing the line you selected in the Location: field.
- Choose the Set (main or instruction window) or Set/Modify
(optional view window) menu item from the Break menu. When the
Set/Modify dialog box appears, enter the line in the Location:
field.
3. Enter a relational expression in the Condition: field of the
dialog box. The expression must be valid in the source language.
For example, a[3] == 0 is a valid relational expression in the C
language.
4. Click on OK. The conditional breakpoint is now set. The debugger
indicates that a breakpoint is conditional by changing the shape of
the breakpoint's button from a square to a diamond.
The following procedure modifies a conditional breakpoint; that is, it
can be used to change the condition associated with an existing
conditional breakpoint, or to change an unqualified breakpoint into a
conditional breakpoint:
1. Do one of the following:
- Press Ctrl/MB1 on the button to the left of a source line, an
instruction code line, or a breakpoint entry in the breakpoint
view.
- Click on a breakpoint entry in the breakpoint view, and choose
the Set/Modify item from the Break Menu.
2. Follow steps 3 and 4 of the previous procedure, as appropriate.
120 – break_action
When an action breakpoint triggers, the debugger suspends execution and
then executes a specified list of commands.
The following procedure sets an action breakpoint:
1. Display the source or instruction line on which you want to set the
action breakpoint.
2. Display the Set/Modify Breakpoint dialog box in one of the
following ways:
- Press Ctrl/MB1 on the button to the left of a source line, an
instruction line, or a breakpoint entry in the breakpoint view.
This causes the Set/Modify Breakpoint dialog box to display,
showing the source line you selected in the Location: field.
- Choose the Set (main window) or Set/Modify (optional view
window) menu item from the Break menu. When the Set/Modify
dialog box appears, enter the source line in the Location:
field.
3. Enter one or more debugger commands in the Action: field of the
dialog box. For example:
DEPOSIT x[j] = 3; STEP; EXAMINE a
4. Click on OK. The action breakpoint is now set.
The following procedure modifies an action breakpoint; that is, it can
be used to change the command associated with an existing action
breakpoint, or to change an unqualified breakpoint into an action
breakpoint:
1. Do one of the following:
- Press Ctrl/MB1 on the button to the left of a source line, an
instruction code line, or a breakpoint entry in the breakpoint
view.
- Click on a breakpoint entry in the breakpoint view, and choose
the Set/Modify item from the Break Menu.
2. Follow steps 3 and 4 of the previous procedure, as appropriate.
121 – exam_deposit
The Additional Topics explain how to do various operations to display and modify the values of variables declared in your program.
122 – select
Use the following techniques to select variable names from windows for
the operations described in the Additional Topics.
When selecting names, follow the syntax of the source programming
language:
- To specify a scalar (nonaggregate) variable, such as an integer,
real, Boolean, or enumeration type, select the variable's name.
- To specify an entire aggregate, such as array or structure
(record), select the variable's name.
- To specify a single element of an aggregate variable, select the
entity using the language syntax. For example:
+ The string arr2[7] specifies element 7 of array arr2 in the C
language.
+ The string employee.address specifies the component address of
record (structure) employee in the Pascal language.
- To specify the object designated by a pointer variable, select the
entity following the language syntax. For example, the string
*int_point specifies the object designated by pointer int_point in
the C language.
Select character strings from windows as follows:
- In any window, to select a string delimited by blank spaces, use
the standard DECwindows Motif word-selection technique: position
the mouse pointer on that string and then double click MB1.
- In any window, to select an arbitrary character string, use the
standard DECwindows Motif text-selection technique: position the
mouse pointer on the first character, press and hold MB1 while
dragging the mouse pointer over the string, and then release MB1.
- In the debugger source view, you also have the option of using
language-sensitive text selection. To select a string delimited by
language-dependent identifier boundaries, position the mouse
pointer on that string and press Ctrl/MB1.
For example, suppose the source view contains the character string
arr2[m], then:
+ To select arr2, position the mouse pointer on arr2 and press
Ctrl/MB1.
+ To select m, position the mouse pointer on m and press
Ctrl/MB1.
You can change the key sequence for language-sensitive text
selection as explained in the Defining the Key Sequence for
Language-Sensitive Text Selection topic.
123 – examine
You can display the current value of a variable or expression in the
following ways:
- Using the Examine push button in the push-button view
- Using the Examine dialog box, accessed through the Command menu on
the main window
The Examine push button displays a current value most quickly, but the
Examine dialog box allows you to request typecasting or an altered
output radix in the displayed result.
To display the current value using the Examine push button:
1. Find and select the variable name or expression in a window.
2. Click on the Examine push button on the push-button view of the
main window. The debugger displays the variable or expression and
its current value in the command view. Note that this is the value
of the variable or expression in the current scope, which might not
be the same as the source location where you selected the variable
name or expression.
To display the current value using the Examine dialog box, perform the
following steps:
1. Do one of the following:
- Find and select the variable name or expression symbols in a
window, and choose the Examine menu item from the Commands menu
on the main window. The Examine dialog box appears, with the
name you selected in the Variable/Expression field.
- Choose the Examine menu item from the Commands menu on the main
window. The Examine dialog box appears. Enter the name of the
variable or symbols of the expression you are examining in the
Variable/Expression field of the dialog box.
2. If you are changing the output type, pull down the menu in the
Typecast entry box and click on the desired data type.
3. If you are changing the output radix, pull down the menu in the
Output Radix entry box and click on the desired radix.
4. Click on OK.
Your echoed command and the current value appear in the command view.
124 – monitor
When you monitor a variable or expression, the debugger displays the
value in the monitor view and checks and updates the displayed value
whenever the debugger regains control from your program (for example,
after a step or at a breakpoint).
To monitor a variable or expression:
1. Choose the Views... menu item in the Options menu on the main
window. The Views dialog box appears.
2. Click on monitor view within the dialog box. The monitor view
appears in the optional view window.
3. Find and select the variable name or expression in a window.
4. Click on the Monitor push button on the push-button view of the
main window. The debugger:
- Puts the selected variable name or expression, along with its
qualifying path name, in the Monitor Expression column
- Puts the current value of the variable in the Value/Deposit
column
- Puts a cleared button in the Watched column
125 – monitor_aggregate
If you select the name of an aggregate variable, such as an array or structure (record) and click on the Monitor push button, the debugger displays the word Aggregate in the Value/Deposit column of the monitor view. To display the values of all elements (components) of an aggregate variable, double click on the variable name in the Monitor Expression column. The displayed element names are indented relative to the parent name. If an element is also an aggregate, you can double click on its name to display its elements, and so on. To contract an expanded display so that only the aggregate parent name is shown in the monitor view, double click on the name in the Monitor Expression column. If you have selected a component of an aggregate variable, and the component expression is itself a variable, the debugger monitors the component that was active when you made the selection. For example, if you select the array component arr[i] and the current value of i is 9, the debugger monitors arr[9] even if the value of i subsequently changes to 10.
126 – monitor_pointer
If you select the name of a pointer (access) variable and click on the
Monitor push button, the debugger displays the address of the
referenced object in the Value/Deposit column of the monitor view.
To monitor the value of the referenced object (to dereference the
pointer variable), double click on the pointer name in the Monitor
Expression column. This adds an entry for the referenced object in the
monitor view, which is indented under the pointer entry. If a
referenced object is an aggregate, you can double click on its name to
display its elements, and so on.
If you are debugging programs written in C or C++, you may want to add
a new push button to the push button view, one that monitors a
dereferenced value. If so, you enter the following command in the
Command field of the Customize dialog box:
monitor *%s
For more information, see the Adding a New Push Button and Associated
Command help topic.
127 – watch
Whenever the program changes the value of a watched variable, the
debugger suspends execution and displays the old and new values in the
command view.
To watch a variable (also known as setting a watchpoint on a variable),
proceed as follows:
1. Monitor the variable as explained in the Monitoring a Variable
topic. The debugger puts a button in the Watched column of the
monitor view whenever you monitor a variable.
2. Click on the button in the Watched column. A filled-in button
indicates that the watchpoint is set.
To deactivate a watchpoint, clear its Watched button in the monitor
view (by clicking on the button). To activate a watchpoint, fill in
its Watched button.
The Accessing Static and Nonstatic (Automatic) Variables topic explains
static and nonstatic (automatic) variables and how to access them. The
debugger deactivates a nonstatic watchpoint when execution moves out of
(returns from) the variable's defining routine. When a nonstatic
variable is no longer active, its entry is dimmed in the monitor view
and its Watched button is cleared.
The debugger does not reactivate nonstatic watchpoints automatically if
execution later returns to the variable's defining routine. You must
reactivate nonstatic watchpoints yourself.
128 – deposit
You can change the value of a variable in the following ways:
- Using the Deposit dialog box, accessed from the Commands menu on
the main window
- Clicking on a monitored value within the monitor view
To change the value of a variable using the Deposit dialog box:
1. Do one of the following:
- Find and select the variable name in a window, and choose the
Deposit menu item from the Commands menu on the main window.
The Deposit dialog box appears, with the name you selected in
the Variable field.
- Choose the Deposit menu item from the Commands menu on the main
window. The Deposit dialog box appears. Enter the name of the
variable to which you are depositing a value in the Variable
field of the dialog box.
2. Enter the value you are depositing in the Value field of the dialog
box.
3. If you are changing the input radix, pull down the menu in the
Input Radix entry box and click on the desired radix.
4. Click on OK.
Your echoed command appears in the command view, indicating that the
value is changed.
To change the value of a monitored value within the monitor view:
1. Monitor the variable as explained in the Monitoring a Variable
topic.
2. Click on the variable's value in the Value/Deposit column of the
monitor view. A small dialog box appears over that value, which
you can now edit.
3. Enter the new value in the dialog box.
4. Click on the check mark (OK) in the dialog box. The dialog box is
removed and replaced by the new value, which indicates that the
variable now has that value. The debugger notifies you if you try
to enter a value that is incompatible with the variable's type,
range, and so on.
To cancel a text entry and dismiss the dialog box, click on X (Cancel).
You can change the value of only one component of an aggregate variable
(such as an array or structure) at a time. To change the value of an
aggregate-variable component:
1. Display the value of the component as explained in the Monitoring
an Aggregate (Array or Structure) Variable topic.
2. Follow the procedure for changing the value of a scalar variable.
129 – variable
In the Local Variable view, you can monitor the values of all local
variables and parameters passed to a routine.
The debugger displays these values, and checks and updates all
displayed values whenever the debugger regains control from your
program (for example, after a step or at a breakpoint).
You cannot add or remove an entry to the local variables and parameters
list. The debugger automatically removes previous entries and adds new
entries when a new routine appears at the top of the call stack.
To monitor a local variable or parameter:
1. Choose the Views... menu item in the Options menu on the main or
optional view window. The Views dialog box appears.
2. Click on the Local Variable View item in the Views dialog box. The
Local Variable view appears. The debugger automatically lists all
local variable and parameter names (in the Expression column) and
current values (in the Value/Deposit column).
To change the value of a monitored value within the local variable
view:
1. Monitor the local variable as explained above.
2. Click on the variable's value in the Value/Deposit column of the
local variable view. A small dialog box appears over that value,
which you can now edit.
3. Enter the new value in the dialog box.
4. Click on the check mark (OK) in the dialog box. The dialog box is
removed and replaced by the new value, which indicates that the
variable now has that value. The debugger notifies you if you try
to enter a value that is incompatible with the variable's type,
range, and so on.
To cancel a text entry and dismiss the dialog box, click on X (Cancel).
You can change the value of only one component of an aggregate variable
(such as an array or structure) at a time. To change the value of an
aggregate-variable component:
1. Display the value of the component as explained in the Monitoring
an Aggregate (Array or Structure) Variable topic.
2. Follow the procedure for changing the value of a scalar variable.
130 – access_var
The Additional Topics give some general considerations about accessing program variables while debugging. If your program was optimized during compilation, you might not have access to certain variables while debugging. When you compile a program for debugging, it is best to disable optimization, if possible. Before you check on the value of a variable, always execute the program beyond the point where the variable is declared and initialized. The value contained in any uninitialized variable should be considered invalid.
131 – static_nonstatic_var
NOTE: The generic term nonstatic variable is used here to denote what
is called an automatic variable in some languages.
The technique for accessing a variable varies according to whether it
is a static or nonstatic variable.
The system differentiates between static and nonstatic variables by
determining how they are stored.
A static variable is associated with the same memory address throughout
execution of the program. You can always access a static variable.
A nonstatic variable is allocated on the stack or in a register and has
a value only when its defining routine or block is active. Therefore,
you can access a nonstatic variable only when program execution is
paused within the scope of its defining routine or block (which
includes any routine called by the defining routine).
A common technique for accessing a nonstatic variable is first to set a
breakpoint on the defining routine and then to execute the program to
the breakpoint.
Whenever the execution of your program makes a nonstatic variable
inaccessible, the debugger notifies you as follows:
- If you try to display the value of the variable or monitor the
variable, the debugger issues a message that the variable is not
active or not in scope.
- If the variable is currently being monitored, its entry becomes
dimmed in the monitor view. When the entry is dimmed, the debugger
does not check or update the variable's displayed value; also, you
cannot change that value. The entry is fully displayed whenever
the variable becomes accessible again.
132 – instruction
The instruction view displays the decoded instruction stream of your program---the code that is actually executing. This is useful if the program you are debugging has been optimized by the compiler so that the information in the source view does not exactly reflect the code that is executing. To display the instruction view, choose Views... from the Options menu on the main or optional view window. When the View Selection dialog box appears, toggle Instruction View. By default, the instruction view automatically displays the decoded instruction stream of the routine in which execution is currently paused. The current-location pointer, to the left of the instructions, marks the instruction that will execute next. By default, the debugger displays line numbers and memory addresses to the left of the instructions You can choose not to display numbers or addresses so that more space is devoted to showing instructions. To hide or display line numbers, toggle the Display Line Numbers button from the File menu on the instruction view. To hide or display memory addresses, choose Show Instruction Addresses from the File menu on the instruction view. To copy memory addresses or instructions into a command you are entering at the command entry prompt, select text and choose Copy from the Edit menu in the instruction window. Then, position your mouse pointer at the command you have entered and choose Paste from the Edit menu on the main window. (You can also select instruction text to be used with a push button command you click in the push button view of the main window.) To set breakpoints from the instruction view, toggle the breakpoint button next to the instruction of interest. The breakpoint is set in the source display, instruction display (if the instruction view is open), and breakpoint view (if the breakpoint view is open). Information on the breakpoint is continuously updated in the source view, and in the instruction view and breakpoint view if they are open. You can also set breakpoints and change breakpoint status by pulling down the Break menu from the main or optional view window. After navigating through the instruction view, to redisplay the location at which execution is paused, click on the Call Stack menu. To display the instruction stream of any routine on the call stack, choose its name from the Call Stack menu on the main window.
133 – register
The register view displays the current contents of all machine
registers.
To display the register view, choose Views... from the Options menu,
then click on the button for Registers.
By default, the register view automatically displays the register
values associated with the routine in which execution is currently
paused. Any values that change as your program executes are
highlighted whenever the debugger regains control from your program.
To display the register values associated with any routine on the call
stack, choose its name from the Call Stack menu on the main window.
To change the value stored in a register:
1. Click on the register value in the register view. A small dialog
box appears over the current value, which you can now edit.
2. Enter the new value in the dialog box.
3. Click on the check mark (OK) in the dialog box. The dialog box is
removed and replaced by the new value, which indicates that the
register now contains that value.
To cancel a text entry and dismiss the dialog box, click on X (Cancel).
134 – task
Multithread programs have multiple threads of execution within a
process and include the following:
- Programs written in any language that use DECthreads or POSIX
1003.1b services.
- Programs that use language-specific threads services (services
provided directly by the language). Currently, Ada is the only
language with built-in threads services that the debugger supports.
Within the debugger, the term thread or task denotes such a flow of
control regardless of the language or implementation. The debugger's
threads support applies to all such programs.
The debugger lets you display thread information and modify task
characteristics to control thread execution, priority, state
transitions, and so on.
The following paragraphs summarize the multithread features of the
debugger's DECwindows Motif interface. For more information about the
debugger's threads support, see the manual provided with this debugger.
Displaying Information about Threads:
To display information about one or more threads of your program,
choose Views... from the Options menu on the main or optional view
window. When the Views dialog box appears, click the button for
Threads. The Threads View dialog box is displayed.
The thread view gives information about all currently existing
(nonterminated) tasks of your program. The information is updated
whenever the debugger regains control from the program.
The displayed information includes:
- The Thread ID. The arrow in the left column marks the active
thread, that is, the task that runs when you click on the Go or
Step push button.
- The current state of the thread. The running thread (thread in the
RUN state) is the active thread.
- Whether the thread has been put on hold.
- The thread priority.
- The current substate of the thread. The substate helps indicate
the possible cause of a thread's state.
- A debugger path name for the thread object or the address of the
thread object if the debugger cannot symbolize the thread object.
Changing Thread Characteristics:
To modify thread characteristics or the thread environment while
debugging, choose one of the following items from the Threads menu on
the optional view window:
Action Function
------ --------
Abort Requests that the selected thread be terminated at the
next allowed opportunity. The exact effect depends
on the current event facility (language dependent).
For Ada tasks, this is equivalent to executing an
abort statement.
Activate Makes the selected thread the active thread.
Hold Places the selected thread on hold.
Nohold Releases the selected thread from hold.
Make Makes the selected thread the visible task.
Visible
All -> Uses the submenu to:
Abort all threads
Hold all threads
NoHold all threads
To save these modifications for subsequent debugger sessions, choose
Save Options from the Options menu on the main or optional view window.
This creates a new version of the debugger resource file with the new
definitions.
135 – setscope
While debugging a routine in your program, you might want to set the
current scope to a calling routine (a routine down the stack from the
routine in which execution is currently paused). This enables you to:
- Determine where the current routine call originated
- Determine the value of a variable declared in a calling routine
- Determine the value of a variable during a particular invocation of
a routine that is called recursively
- Change the value of a variable in the context of a routine call
The Call Stack menu on the source view lists the names of the routines
of your program that are currently active on the stack, up to the
maximum number of lines that can be displayed on your screen.
The numbers on the left side of the menu indicate the level of each
routine on the stack relative to level 0, which denotes the routine in
which execution is paused.
To set the current scope to a particular routine on the stack, choose
its name from the Call Stack menu. This causes the following to occur:
- The Call Stack menu, when released, shows the name and relative
level of the routine that is now the current scope.
- The source view shows that routine's source code.
- The instruction view (if displayed) shows that routine's decoded
instructions.
- The register view (if displayed) shows the register values
associated with that routine call.
- If the scope is set to a calling routine (call-stack level other
than 0), the debugger clears the current-location pointer.
- The debugger sets the scope for symbol searches to the chosen
routine, so that you can examine variables, and so on, in the
context of that scope.
When you set the scope to a calling routine, the current-location
pointer (which is cleared) marks the source line to which execution
will return in that routine. Depending on the source language and
coding style used, this might be the line that contains the call
statement or some subsequent line.
136 – symbol_search
Symbol ambiguities can occur when a symbol (for example, a variable
name X) is defined in more than one routine or other program unit.
In most cases, the debugger resolves symbol ambiguities automatically.
First, it uses the scope and visibility rules of the currently set
language. In addition, because the debugger permits you to specify
symbols in arbitrary modules (to set breakpoints and so on), the
debugger uses the ordering of routine calls on the call stack to
resolve symbol ambiguities.
In some cases, however, the debugger might respond as follows when you
specify a symbol that is defined multiple times:
- It might issue a "symbol not unique" message because it is not able
to determine the particular declaration of the symbol that you
intended.
- It might reference the symbol declaration that is visible in the
current scope, which is not the one you want.
To resolve such problems, you must specify a scope where the debugger
should search for the particular declaration of the symbol:
- If the different declarations of the symbol are within routines
that are currently active on the call stack, use the Call Stack
menu on the source window to reset the current scope.
- Otherwise, enter the appropriate command at the command-entry
prompt (EXAMINE or MONITOR, for example), specifying a path-name
prefix with the symbol. For example, if the variable X is defined
in two modules named COUNTER and SWAP, the following command uses
the path name SWAP\X to specify the declaration of X that is in
module SWAP:
DBG> EXAMINE SWAP\X
137 – starting_debugger
To start the debugger, enter the following command from DCL level:
$ DEBUG/KEEP
This startup method enables you to rerun your program or run another
program from the same debugging session without exiting the debugger.
Additional options for starting the debugger are discussed in the
manual provided with this debugger. With some of these startup
methods, you cannot rerun your program or run another program from the
same debugging session.
138 – custom
You can customize the debugger's DECwindows Motif interface as follows:
- Define the startup configuration of the debugger windows and views
- Show or hide line numbers in the source view at debugger startup
- Modify, add, or remove push buttons and associated debugger
commands
- Define the key sequence to display the dialog box for conditional
and action breakpoints
- Define the key sequence to make text selection language-sensitive
in the source view
- Define the character font for text displayed in specific windows
and views
- Define or redefine the commands bound to individual keys on your
computer's keypad.
You can control the first three of these customizations interactively
from the DECwindows Motif interface, as explained in the Additional
Topics. In each of these three cases, you can save the current
settings by choosing Save Options from the Options menu on the main or
optional view window.
In addition, you can control all customizations by editing the debugger
resource file (DECW$USER_DEFAULTS:VMSDEBUG.DAT).
139 – custom_views
To define the startup configuration of the debugger windows and views:
1. While using the debugger, set up the desired configuration of the
windows and views.
2. Choose Save Options from the Options menu on the main or optional
view window. This creates a new version of the debugger resource
file with the new settings.
When you later start the debugger, the new configuration appears
automatically.
Note that adding views to the startup configuration increases the
startup time accordingly.
You can also define the startup window configuration by editing the
current definition of the following resources in the VMSDEBUG.DAT
resource file:
DebugSource.width
DebugSource.x
DebugSource.height
DebugSource.y
DebugControl.width
DebugControl.x
DebugControl.height
DebugControl.y
140 – custom_lineno
The source view displays source line numbers by default at debugger
startup. To hide (or display) line numbers at debugger startup:
1. While using the debugger, choose Show Line Numbers from the File
menu on the main window. Line numbers are displayed when a
filled-in button appears next to that menu item, and vice versa.
2. Choose Save Options from the Options menu on the main or optional
view window. This creates a new version of the debugger resource
file with the new settings.
When you later start the debugger, line numbers are either displayed or
hidden accordingly.
You can also set the startup default for line numbers by setting the
following resource to either True or False in the VMSDEBUG.DAT resource
file.
DebugSource.StartupShowSourceLineno
141 – custom_button
The push buttons on the push-button view are associated with debugger
commands. You can:
- Change a push button's label or the command associated with a push
button
- Add a new push button and assign a command to that button
- Remove a push button
- Resequence a push button
NOTE: You cannot modify or remove the Stop push button.
The Additional Topics explain how to customize push buttons
interactively through the DECwindows Motif interface.
To save these modifications for subsequent debugger sessions, choose
Save Options from the Options menu on the main window or an optional
view. This creates a new version of the debugger resource file with
the new definitions.
142 – custom_button_move
To resequence a push button:
1. Choose Customize Buttons... from the Options menu on the main
window or an optional view. The Customize dialog box appears.
2. Click on the push button in the control panel of the Customize
dialog box.
3. Click on Right Arrow or Left Arrow. The push button is resequenced
one place to the right or left in the dialog box control panel.
4. Click on OK. The push button is resequenced one place to the right
or left in the push-button view on the main window.
143 – custom_button_mod
To change a push button's label or the debugger command associated with
a push button:
1. Choose Customize Buttons... from the Options menu on the main
window or an optional view. The Customize dialog box appears.
2. Click on the push button in the control panel of the dialog box.
3. If changing the push button label, enter the new label in the Label
field or choose a predefined icon from the Icon menu. (If changing
the push button label, verify that the Icon menu is set to None.)
4. If changing the command associated with the push button, enter the
new command in the Command field.
If the command is to operate on a name or language expression
selected in a window, include %s in the command name. For example,
the following command displays the current value of the variable
whose name is currently selected:
EXAMINE %s
If the command is to operate on a name that has a a percent sign
(%) as the first character, specify two percent signs.
5. Click on Modify. The push button is modified in the dialog box
control panel.
6. Click on OK. The push button is modified in the push-button view
on the main window.
144 – custom_button_add
To add a new push button to the push-button view and assign a debugger
command to that push button:
1. Choose Customize Buttons... from the Options menu on the main
window. The Customize dialog box appears.
2. Enter the debugger command for that push button in the Command
field.
3. Enter a label for that push button in the Label field or choose a
predefined icon from the Icon menu.
4. Click on Add. The push button is added to the control panel within
the dialog box.
5. Click on OK. The push button is added to the push-button view in
the main window.
If you are debugging programs written in C or C++, you may want to add
a new push button to the push button view, one that monitors a
dereferenced value. If so, you enter the following command in the
Command field of the Customize dialog box:
monitor *%s
145 – custom_button_remove
To remove a push button:
1. Choose Customize Buttons... from the Options menu on the main
window. The Customize dialog box appears
2. Click on the push button in the control panel of the Customize
dialog box.
3. Click on Remove. The push button is removed from the control panel
within the dialog box.
4. Click on OK. The push button is removed from the push button view
in the main window.
146 – custom_resource
The debugger is installed on your system with a debugger resource file
DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT that defines the startup default
settings for the following debugger user-interface options:
- Configuration of windows and views
- Whether to show or hide line numbers in the source view
- Button names and associated debugger commands
- Key sequence to display the dialog box for conditional and action
breakpoints
- Key sequence for language-sensitive text selection in the source
view
- Character fonts for text in the windows and views
- Key bindings for commands associated with the computer keypad
- Colors for elements of the source and instruction views and Editor
- Command echo
- Title Bar label format
A listing of the system default debugger resource file with explanatory
comments is contained in the manual provided with this debugger.
You can customize the following features from the DECwindows Motif
interface:
- Configuration of windows and views
- Whether to show or hide line numbers in the source view
- Push button names and associated debugger commands
You can redefine the rest of the customizable parameters by editing
your local debugger resource file.
See Additional Topics for information about changing and saving the
debugger user-interface options, and restoring system default debugger
user-interface options.
147 – custom_key_breakdb
By default, the key sequence for displaying the dialog box for conditional and action breakpoints is Ctrl/MB1. To define another key sequence, edit the current definition of the following resource in the VMSDEBUG.DAT resource file: DebugSource.ModifyBreakpointToggleSequence
148 – custom_key_select
By default, the key sequence for language-sensitive text selection in the source view is Ctrl/MB1. To define another key sequence, edit the current definition of the following resource in the VMSDEBUG.DAT resource file: DebugSource.IdentifierSelectionSequence To avoid conflict with standard DECwindows Motif word selection, do not use a double-click combination, such as Ctrl<Btn1Down>(2).
149 – custom_font
To define another font for the text displayed in various debugger windows and views, edit the current definition of the following resources in the VMSDEBUG.DAT resource file: DebugDefault.Font DebugSource.Font DebugInstruction.Font DebugMessage.Font DebugOptions.Font
150 – custom_key_binding
The following commands have been mapped to individual keys on your
computer's keypad:
Command Keypad Label Key Designation
-------- ------------ ---------------
Step/Line KP0 <Key>0xFFB0
Examine KP1 <Key>0xFFB1
Go KPcomma <Key>0xFFAC
Step/Into GOLD-KP0 <Key>0xFF91,<Key>0xFFB0
Step/Over BLUE-KP0 <Key>0xFF94,<Key>0xFFB0
Examine^ GOLD-KP1 <Key>0xFF91,<Key>0xFFB1
Show Calls KP5 <Key>0xFFB5
Show Calls 3 GOLD-KP5 <Key>0xFF91,<Key>0xFFB5
Activate ENTER <Key>0xFF8D
To bind a different command to a key that is already associated with a
command, edit the current definition of the following resources in the
VMSDEBUG.DAT resource file:
DebugSource.*DXmCSText.translations:#override\n\
<Key>0xFFB0: EnterCmdOnCmdLine("step\line") \n\
<Key>0xFFB1: EnterCmdOnCmdLine("examine") \n\
<Key>0xFFAC: EnterCmdOnCmdLine("go") \n\
<Key>0xFF91,<Key>0xFFB0: EnterCmdOnCmdLine("step\into") \n\
<Key>0xFF94,<Key>0xFFB0: EnterCmdOnCmdLine("step\over") \n\
<Key>0xFF91,<Key>0xFFB1: EnterCmdOnCmdLine("examine^") \n\
<Key>0xFFB5: EnterCmdOnCmdLine("show calls") \n\
<Key>0xFF91,<Key>0xFFB5: EnterCmdOnCmdLine("show calls 3") \n\
<Key>0xFF8D: activate()\n\
To bind a command to a key that is not currently associated with a
command, refer to the Keysym Encoding chapter of the "X and Motif Quick
Reference Guide" for key designations.
151 – decwindows_basics
Information about using DECwindows Motif, such as how to use windows,
dialog boxes, and scroll bars, is available from Session Manager help.
To get Session Manager help:
1. Move the mouse pointer to the Session Manager icon (the icon that
contains a small key in it) in the Icon Box.
2. Press mouse button 1 (MB1) twice to display the Session Manager
window.
3. Move the mouse pointer to the Help menu; press and hold MB1 to pull
down this menu.
4. Move the mouse pointer to the On Basics menu item and release MB1.
The Session Manager displays a Help window, which includes a list
of Additional Topics about using DECwindows Motif.
152 – on_context
Context-sensitive help is information about an area or object in a
window or a dialog box.
To display context-sensitive help:
1. Choose On Context from the Help menu in a debugger window. The
pointer shape changes to a question mark (?).
2. Place the question mark on an object or area in a debugger window
or dialog box.
3. Click on MB1. Information about that area or object is displayed
in a Help window. Additional Topics provide task-oriented
discussions, where applicable.
To display context-sensitive help for a dialog box, you can also click
on the Help button in the dialog box.
153 – on_window
Choose On Window in the Help menu for an overview of the debugger along with information on how to do various tasks using the debugger.
154 – on_help
Choose On Help in the Help menu for instructions on how to use the help system.
155 – on_version
Choose On Version in the Help menu for version and copyright information about the OpenVMS Debugger.
156 – on_command
Choose On Commands in the Help menu for information about debugger commands. The debugger's DECwindows Motif interface is layered on the command interface. You can enter debugger commands at the DBG> command-entry prompt in the command view.
157 – context_sensitive_help
Context-sensitive help is information about an area or object in a
window or a dialog box.
To display context-sensitive help:
1. Choose On Context from the Help menu in a debugger window. The
pointer shape changes to a question mark (?).
2. Place the question mark on an object or area in a debugger window
or dialog box.
3. Click on MB1. Help for that area or object is displayed in a Help
window. Additional Topics provide task-oriented discussions, where
applicable.
To display context-sensitive help for a dialog box, you can also click
on the Help button in the dialog box.
158 – overview_help
The On Window help topic (Using the Main Window, Using the Optional View Window, Using the Editor Window, Using the Instruction Window) and their subtopics provide task-oriented information about the debugger and debugging. To display the On Window topics, use either of these techniques: - Choose On Window from the Help menu in a debugger window. - Choose Go To Overview from the View menu of a debugger help window. Then, to display information about a particular subject, choose a topic from the list of Additional Topics.
159 – command_help
You can enter debugger commands as follows:
- At the command-entry prompt in the command view.
- In certain debugger dialog boxes (for example, when assigning a new
command to a push button on the push-button view).
To display help on debugger commands and various topics:
- Choose On Commands from the Help menu of a debugger window.
- Choose the command name or other topic (for example,
Language_Support) from the list of Additional Topics.
160 – msg_help
Debugger diagnostic messages are displayed in the command view. To display help on a particular message: 1. Choose On Commands from the Help menu of a debugger window. 2. Choose Messages from the list of Additional Topics. 3. Choose the message identifier from the list of Additional Topics.
161 – ha_map_pane_hlp
The Memory Map, located at the upper left of the heap analyzer screen, displays a graphical representation of memory use in real time. Each memory allocation appears as a colored strip, or 'segment'. By searching for segments that seem too large, too numerous, or in other ways anomalous, you can identify areas in your application where one of the following memory events may be occurring: - Memory leaks - Fragmentation - Repetitive allocations - Insufficient allocation - Inefficient memory use For information on Memory Map context-sensitive pop-up menus and pull-down menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
162 – ha_hist_pane_hlp
The Type Histogram, located in the upper right of the heap analyzer
screen, allows you to see statistical summaries on segments of the same
segment type.
Use the Type Histogram to:
- Check the percentage of total segments represented by a segment
type. The left histogram shows this percentage graphically. Click
on an individual segment type to see a numerical percentage.
- Check the percentage of the total bytes allocated to a segment
type. The right histogram shows this percentage graphically.
Click on an individual segment type to see a numerical percentage.
The total number of segments and the total number of bytes (recognized
by the heap analyzer) appear at the top of the histogram window.
For information on Type Histogram context-sensitive pop-up menus, see
the additional topics below.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
163 – ha_type_cs
Most of the work you do in the heap analyzer is accomplished through
context-sensitive pop-up menus. The menu items available on the Type
Histogram are as follows:
Action Function
------ --------
Display Type Displays the segment's type definition
in the Information Window.
Go to Type Moves the cursor to the segment's type
in the Views-and-Types Display.
Do Not Use Type Adds the segment's type to the
Do-not-use Type List.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
164 – ha_msg_pane_hlp
The Message Window, located beneath the Memory Map, displays output
from the heap analyzer.
Use the Message Window on the heap analyzer window to do the following:
- Read informational and error messages generated by the heap
analyzer.
- Read one-line informational descriptions on individual segments.
(Click on MB1 while your mouse pointer rests on the segments of
interest.)
For information on Message Window context-sensitive pop-up menus, see
the additional topics below.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
165 – ha_map_cs
Most of the work you do in the heap analyzer is accomplished through
context-sensitive pop-up menus. The menu items available on the Memory
Map are as follows:
Action Function
------ --------
Traceback of Allocation
Displays a traceback, that is, the
sequence of routine calls on the
callstack, for the segment under
your mouse arrow.
Display Segment Displays the segment definition of
the segment under your mouse arrow
in the Information Window.
Display Contents Displays the contents of the segment
under your mouse arrow.
Display Address Displays the address under your mouse
arrow in the Information Window.
Display Type Displays the segment's type definition
in the Information Window.
Go to Type Moves the cursor to the segment's type
in the Views-and-Types Display.
Do Not Use Type Adds the segment's type to the
Do-not-use Type List.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
166 – ha_interpret_trace
The heap analyzer displays traceback information when you choose the Traceback of Allocation context-sensitive menu item from the Memory Map. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
167 – ha_interpret_gototype
The heap analyzer moves you to the Views-and-Types Display when you choose the Go to Type context-sensitive menu item from the Memory Map or the Type Histogram. Your mouse arrow rests on the segment type associated with the segment you selected in the Memory Map or Type Histogram. You can choose one of the following options for the display of this type in the Memory Map: - Change the color of the type - Show (or hide) the type - Expand (or collapse) the type - Save (or remove) the type For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
168 – ha_color_type
The heap analyzer allows you to change the color assigned to a segment type in the Memory Map by clicking MB3 on the color spectrum for a segment type or types. This feature can be useful if the colors of adjacent types are too similar to distinguish each type clearly. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
169 – ha_show_type
The heap analyzer allows you to hide (and then, show again) the display
of a segment type in the Memory Map by doing one of the following:
- Toggling the Show toggle button and clicking the Apply button in
the Views-and-Types Display.
- Selecting the Show or Hide menu item and clicking the Apply button
in the Views-and-Types Display.
This feature can be useful when you need to isolate a segment or
segments in the Memory Map in order to see them better.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
170 – ha_expand_type
The heap analyzer allows you to expand (or collapse) the display of a
segment type contained inside the display of other segment types in the
Memory Map by doing one of the following:
- Toggling the Expand toggle button and clicking the Apply button in
the Views-and-Types Display.
- Selecting the Expand or Collapse menu item and clicking the Apply
button in the Views-and-Types Display.
This feature can be useful when you need a more or less detailed
picture of an area in the Memory Map.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
171 – ha_save_type
The heap analyzer allows you to save (or remove) the display of a
segment type in the Memory Map by doing one of the following:
- Toggling the Save toggle button and clicking the Apply button in
the Views-and-Types Display.
- Selecting the Save or Remove menu item and clicking the Apply
button in the Views-and-Types display.
This feature can be useful when you need to improve heap analyzer
performance by discarding information on unimportant segments. It is
also useful when you need to discard all information before a point in
time, so you can perform a series of actions and see the display
resulting from them.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
172 – ha_interpret_donotuse
The heap analyzer adds a new segment type name to the Do-not-use Type
List when you perform one of the following actions:
- Choose the Do Not Use Type context-sensitive menu item from the
Memory Map or the Type Histogram.
The segment type added is the one associated with the segment your
mouse arrow is pointing to.
- Choose the Add to Do-not-use Type List pull-down menu item from the
Options menu on the Memory Map.
The segment type added is the one you type into the dialog box that
appears for your input.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
173 – ha_interpret_segdef
The heap analyzer displays segment type definitions when:
- You click MB1 on a segment displayed in the Memory Map.
- You choose the Display Segment context-sensitive menu item from the
Memory Map.
A segment definition has the following form:
0004ECA5 15: 00040000_0001CA00=0005CA00 LIBRTL (Image)
which includes:
- 0004ECA5: The address underneath your cursor when you pressed MB1
(This information does not appear when you choose from the
context-sensitive menu)
- 15: The segment number in the Memory Map display
- 00040000: The initial address of the segment
- 0001CA00: The length in bytes of the segment
- 005CA00: The final address of the segment
- LIBRTL: The segment name, or segment type
- Image: The segment classification (image, block, region, or zone)
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
174 – ha_interpret_typedef
The heap analyzer displays type definitions when you choose the Display
Type item in the context-sensitive menu for the Memory Map.
A type definition has the following form:
LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments
using 00002160 bytes
which includes:
- LIBRTL\LI$VM\LIB$GET_VM: The segment type name
- (Block): The type classification (image, block, region, or zone)
- 39 segments: Number of segments
- 00002160 bytes: Number of bytes
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
175 – ha_interpret_adddef
The heap analyzer displays segment address definitions when you choose the Display Address item in the context-sensitive menu for the Memory Map. An address definition has the following form: 001C710B is read and write accessible by the user which includes: - 001C710B: The address of the segment - read and write accessible: The access to the user For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
176 – ha_interpret_contdef
The heap analyzer displays segment contents definitions when you choose
the Display Contents item in the context-sensitive menu for the Memory
Map.
A contents definition has the following form:
contents of: 38: 001C7000+000000C0=001C70C0
LIBTRL\LIB$VM\LIB$GET_VM (Block)
00000000 00000000 00000000 001C7108
00345000 00000000 00000000 ~#@ 001C7118
00000B10 00000000 06503000 <> 001C7128
00C45000 00113000 00000000 * +*, 001C7138
00000000 000C4000 0000E000 .. ? 001C7148
which includes:
- 15: The segment number in the Memory Map display
- 001C7000: The initial address of the segment
- 000000C0: The length in bytes of the segment
- 001C70C0: The final address of the segment
- LIBRTL\LIB$VM\LIB$GET_VM: The segment name, or segment type
- Block: The segment classification (image, block, region, or zone)
- An ASCII representation of the contents of the segment
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
177 – ha_info_pane_hlp
The Information Window, located in the lower left of the heap analyzer screen, displays output from context-sensitive menu items in the Memory Map. These items request the following information: - Traceback entries for an allocation - Segment definitions - Contents definitions - Address definitions - Segment type definitions For information on Information Window context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
178 – ha_info_cs
Most of the work you do in the heap analyzer is accomplished through
context-sensitive pop-up menus. The menu item available on the
Information Window is as follows:
Action Function
------ --------
Go to Source Displays the source code associated with
the traceback entry under your mouse arrow.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
179 – ha_source_pane_hlp
The Source Window, located between the Information Window and the
Do-not-use Type List, displays the source code associated with a
traceback entry.
To display source code, perform the following steps:
1. Choose the Traceback of Allocation item in the context-sensitive
menu on the Memory Map.
2. When traceback information appears in the Information Window, click
on an individual traceback entry.
The routine call associated with the traceback is highlighted when
your source code appears.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
180 – ha_hidelist_view_hlp
The Do-not-use Type List, located between the Source Window and the Views-and-Types Display, lists the routines the heap analyzer does not use as "segment types," the names that characterize segments. For example, the display showing in the Memory Map may include many segments labeled with the names of low-level memory management routines. If you include these names in the Do-not-use Type List, the heap analyzer will search further for names to characterize segments, and each segment's purpose will become clearer. For information on Do-not-use Type List context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
181 – ha_hidelist_cs
Most of the work you do in the heap analyzer is accomplished through
context-sensitive pop-up menus. The menu item available on the
Do-not-use Type List is as follows:
Action Function
------ --------
Use Type Removes a segment type from the Do-not-use
Type List.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
182 – ha_typelist_pane_hlp
The Views-and-Types Display, located in the lower right of the heap analyzer screen, displays the segment types known to the heap analyzer and allows you to alter the display of these types. Since the type list is organized into images, blocks, regions, and zones, you can choose the scope of your change, as follows: - All views (all segments) - All blocks (or individual blocks) - All images (or individual images) - All regions (or individual regions) - All zones (or individual zones) Then, move to the right side of the display to choose your display change: - Change colors used in display - Suppress (or restore) types in display - Expand (or collapse) detail of types in display - Remove (or save) information on types displayed in session <here> For information on View-and-Types Display context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
183 – ha_typelist_cs
Most of the work you do in the heap analyzer is accomplished through
context-sensitive pop-up menus. The menu items available from the left
side of the Views-and-Types Display are as follows:
Action Function
------ --------
Display Type Displays the segment's type definition
in the Information Window.
Go to Type Moves the cursor to the segment's type
in the Views-and-Types Display.
Do Not Use Type Adds the segment's type to the
Do-not-use Type List.
The menu items available from the right side of the Views-and-Types
Display are as follows:
Action Function
------ --------
Color Spectrum Changes the color assigned to a segment type
or types in the Memory Map.
--------
Show Restores full Memory Map display.
Hide Suppresses the display of one or more segment
types.
Reset Cancels the options chosen.
---------
Expand Includes the display of segment types occurring
within other segment types in the Memory Map.
Collapse Suppresses the display of segment types occurring
within other segment types in the Memory Map.
Reset Cancels the options chosen.
---------
Save Saves all subsequent information about a
segment type or types.
Remove Deletes absolutely all information about a
segment type or types.
Reset Cancels the options chosen.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
184 – ha_source_db_hlp
Use the Set Source Dialog Box to specify a source directory search list.
185 – ha_add_hidetype_db_hlp
Use the Add to Do-not-use Type List Dialog Box to add additional routines to the Do-not-use Type List.
186 – ha_button_pane_hlp
The push buttons on the control panel allow you to control the speed
your application executes and the Memory Map displays. Use the push
buttons on the control panel to do the following:
Button Function
-------- ---------
Start/Step Initially, the Start push button starts your
application. Once your application is running,
this push button becomes the Step push button, which
you can use when your application is paused to
single-step through the Memory Map display.
Pause Stops the updating of the Memory Map.
Slow Slows the updating of the Memory Map.
Sync Off: A small histogram shows how far behind
your application's processing the Memory Map
displays events (a slight discrepancy improves
heap analyzer performance).
On: Directs the heap analyzer to update the Memory
Map at exactly the same time your application
executes the event.
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
187 – ha_file_menu_hlp
Use the File menu on the heap analyzer window as follows: Action Function ------ -------- Exit Exits the heap analyzer. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu.
188 – ha_display_menu_hlp
Use the Display menu on the heap analyzer window as follows:
Action Function
------ --------
Text Visible (Default.) Labels each segment in the Memory
Map with a segment name, provided that the
segment is large enough to carry a name label.
Auto Scroll (Default.) Automatically scrolls the Memory Map
to the highest memory addresses (lower right)
whenever memory is expanded.
Reduce Scroll When you request a limited or partial Memory
Region Map display, compresses the display so you can
see as many segments as possible without scrolling
to their location in the original display.
Display All Restores the complete Memory Map display after
Segments you have requested a limited or partial display.
Clear Clears text from the Information Window.
Information
Window
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
189 – ha_zoom_menu_hlp
Use the Zoom menu on the heap analyzer window to specify a closer or
more distant view of the Memory Map by choosing from the following
options:
Extraordinarily Close
Extremely Close
Very Close
Close
Medium (Default)
Far
Very Far
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
190 – ha_options_menu_hlp
Use the Options menu on the heap analyzer window as follows:
Action Function
------ --------
Set Source... Allows you to specify a search directory
when you display source code in the debugger
or in the source window.
Add to Allows you to specify additional segment types
Do-not-use to be included in the Do-not-use Type List.
Type List...
Save Allows you to save the segment types listed in
Do-not-use your Do-not-use Type List between heap analyzer
Type List sessions.
Restore Deletes additions to the Do-not-use Type List
Do-not-use since the last heap analyzer session.
Type List
For information on other heap analyzer screen locations and pop-up
menus, click the 'On Context' menu item in the heap analyzer Help menu,
then click the location of interest.
For information on using the heap analyzer, see the 'On Window' menu
item in the heap analyzer Help menu.
191 – ha_help_menu_hlp
Use the Help menu on the heap analyzer window as follows:
Action Function
------ --------
On Context Provides context-sensitive help for the heap analyzer.
On Window Provides task-oriented information on heap analyzer windows.
On Version Provides copyright and version information
on the heap analyzer.
On Help Provides task-oriented information on
DECwindows Motif online help.
Glossary Defines terms associated with the heap analyzer.
192 – on_context_ha
Context-sensitive help is information about an area or object in a
window or a dialog box.
To display context-sensitive help:
1. Choose On Context from the Help menu in a debugger window. The
pointer shape changes to a question mark (?).
2. Place the question mark on an object or area in a debugger window
or dialog box.
3. Click on MB1. Information about that area or object is displayed
in a Help window. Additional Topics provide task-oriented
discussions, where applicable.
To display context-sensitive help for a dialog box, you can also click
on the Help button in the dialog box.
193 – on_window_ha
Choose On Window in the Help menu for an overview of the heap analyzer along with information on how to do various tasks using the heap analyzer.
194 – On help ha
Choose On Help in the Help menu for instructions on how to use the help system.
195 – on_version_ha
Choose On Version in the Help menu for version and copyright information about the heap analyzer.
196 – glossary_ha
TBS: This information will appear in a later version release.
197 – ha_on_window_hlp
The heap analyzer is a feature of the debugger that provides a graphical representation of memory use in real time. By studying this representation, you can identify areas in your application where memory usage and performance can be improved. For example, you might notice allocations that are made too often, memory blocks that are too large, evidence of fragmentation, or memory leaks. After you locate an area of interest, you can request an enlarged, more detailed, or altered view. You can also request additional information on the size, contents, or address of the allocations shown. After you narrow your interest to an individual allocation, you can request traceback information. The analyzer allows you to correlate the traceback entry for an allocation with source code in your application program. By scrolling through the source-code display, you can then identify problematic code and decide how to correct it. The additional topics below, read in sequence, describe the steps involved in using the heap analyzer.
198 – ha_window_start
You can invoke the heap analyzer during a debugging session in one of
the following ways:
- In the debugger main window, choose the Run Image or Rerun Same
items from the File menu. When a dialog box appears, select the
program you wish to execute and click the heap analyzer toggle
button.
- At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER
or RERUN/HEAP_ANALYZER command.
- On VAX and Alpha systems, at the DCL prompt ($) in a DECterm window
outside the debugger, enter the following commands and then execute
your program:
$ DEFINE/USER LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
- To display the Heap Analyzer graphical display on I64 systems, at
the DCL prompt ($) enter the command
START HEAP_ANALYZER
You can also invoke the heap analyzer outside a debugging session by
entering the DEFINE/USER command detailed above, and then the DCL
command RUN/NODEBUG.
After you successfully invoke the heap analyzer, the heap analyzer
startup screen appears.
199 – ha_window_windows
The heap analyzer contains a main window, six subsidiary windows, and a control panel. The Memory Map, the most important window, displays a representation of your application's dynamic memory use. At startup, the Memory Map shows the images that comprise your application. As your application executes, you can see the relative location and size of individual memory blocks, images, program regions, memory zones, and dynamic strings as they are allocated and deallocated in memory space. The Message Window displays information on your heap analyzer session. At startup, the Message Window contains the message 'Heap Analyzer initialization complete. Press Start button to begin program.' As your application executes, informational and error messages appear in this window. The Push Button Control Panel contains buttons that allow you to control the speed of the Memory Map display. At startup, you click on the Start button to begin executing your application. As your application executes, you can click on other buttons in the panel to pause, slow, or otherwise affect the continuous display. The Information Window displays information on Memory Map segments. As your application executes, you can pause execution at any time to request specific information. The Source Window displays the application source code associated with a segment in the Memory Map. The Do-not-use Type List allows you to adjust the Memory Map display by redetermining a segment's type, or group name. The Views-and-Types Display allows you to adjust the Memory Map display by selectively viewing certain segment types. The Type Histogram displays summary and statistical information on segment types. As you use the heap analyzer, you may need to increase or decrease the size of the window in which you are working. To do this, pull the window pane sashes between windows or resize the screen as a whole.
200 – ha_window_sourcedir
If you are invoking the heap analyzer from a directory other than the
one that stores your application source code, you can set a source
directory for the heap analyzer as soon as the startup screen appears.
To set a source directory:
1. Choose the Set Source... menu item from the Options menu on the
heap analyzer screen.
The Set Source dialog box appears.
2. Enter the directory specification for your source directory as you
would for the OpenVMS Debugger SET SOURCE command.
For more information on this command, see the debugger SET SOURCE
command in online help.
3. Click on OK.
The heap analyzer can now access your application.
201 – ha_window_run
If you invoked the heap analyzer from within a debugging session, start
your application by performing the following steps:
1. Click on the Start button in the Push Button Control Panel.
The Message Window displays an "application starting" message, and
the Start button label changes to Step. The OpenVMS Debbugger main
window pops forward.
2. Click on the Go button in the OpenVMS Debugger's control panel, and
iconize the OpenVMS Debugger window.
Memory events associated with your application begin showing in the
Memory Map.
(If you invoked the heap analyzer outside a debugging session, start
your application by performing only step 1 above.)
After your application is running, the Memory Map (and other parts of
the heap analyzer display) are continuously updated to reflect the
state of your application.
Unless you intervene (by clicking one of the push buttons in the heap
analyzer control panel), this updating continues until an occurrence
causes memory events to stop. For example, your application might
prompt for input, the debugger might prompt for input, or your
application might finish execution.
202 – ha_window_contbutton
If you decide to examine events in the Memory Map as your application is executing, you can use the heap analyzer's push buttons to slow, pause, and otherwise affect the speed of the display. The Slow and Pause push buttons allow you to slow or pause the display. The Step push button allows you to single-step through memory events. The Sync histogram to the right of the Sync button indicates how far behind your application the heap analyzer is running. For performance reasons, the heap analyzer displays memory events a few seconds after their occurrence in your application. The Sync push button allows you to synchronize heap analyzer display and application execution, if this is important to you. Your application runs more slowly when you request synchronization.
203 – ha_window_defwork
The following sections describe how to use the heap analyzer when memory problems are clearly visible in the default Memory Map display. Visible problems include allocations that are larger than you expect, that repeat numerous times, that increment at each allocation, and that could occur in a more efficient way. In such cases, your heap analyzer session consists of the following steps: 1. Examine the Memory Map display. 2. Set display characteristics in the Memory Map (optional). 3. Request additional information on individual segments (optional). 4. Request traceback information on individual segments. 5. Correlate traceback entries with source code routines.
204 – ha_window_def_mmdisp
Depending on the size of your application, you may wish to examine the Memory Map display as your application is running (by using the push buttons to slow, pause, or step through events) or after your application completes running (by using the Memory Map's vertical scroll bar to scroll back through the display). You can identify segments whose size or location are not what you expect by remembering that a segment's location in the Memory Map corresponds to its location in dynamic memory. Lower addresses in dynamic memory are represented in the upper left of the Memory Map display. Addresses increase to the right and wrap at each line of the display.
205 – ha_window_def_optmmdisp
As you examine the Memory Map, you may wish to select display options that allow you to see more clearly those parts of the display you are most interested in. The Display Menu allows you to control whether you see segment type names within the Memory Map display, whether the display automatically scrolls to show the most recent activity, and whether you can compress the display. The Zoom Menu allows you to control the degree of magnification with which you see segments in the Memory Map. Choosing the Far menu item, for example, shows an overview of memory. Choosing Extremely Close shows a more detailed view of memory.
206 – ha_window_def_optinfo
As you examine the Memory Map display, you may find that you need more
information on those segments that interest you. The Memory Map pop-up
menu allows you to request segment, contents, address, and type
definitions for an individual segment.
A segment definition has the following form:
cursor-address n:init-address + length = end-address name ( view )
cursor-address The address beneath your cursor when you click MB3.
n The number of your segment within the sequence of
total segments.
init-address The initial address of your segment.
length The length (in bytes) of your segment.
end-address The last address of your segment.
name The segment type name of your segment.
view The view of your segment:
block, image, region, or zone.
(See the 'Altering the Views and Types Display' help
topic for more information on views.)
For example, the following segment definition describes the 15th
segment in your Memory Map display, which is a segment of type LIBRTL:
0004ECA5 15: 00040000+0001CA00=0005CA00 LIBRTL (Image)
A contents definition consists of a partial segment definition (a
segment definition without a cursor-address) and an ASCII
representation of the contents of segment addresses. For example:
contents of: 38: 001C7000+000000C0=001C70C0
LIBTRL\LIB$VM\LIB$GET_VM (Block)
[ASCII representation]
An address definition takes the form of a statement describing user
access to a stated address. For example:
001C710B is read and write accessible by the user
A type definition takes the form of a statement summarizing the total
number of segments and total number of bytes devoted to a segment type.
For example:
LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments
using 00002160 bytes
207 – ha_window_def_trace
After you identify an individual segment of interest, choose the
Traceback of Allocation menu item in the Memory Map pop-up menu.
Traceback information can help you understand why your segment was
created. Viewing traceback is also a preliminary step to displaying
application code.
Traceback information consists of a partial segment definition (a
segment definition without a cursor address) and the list of elements
on the callstack at the moment your segment was created. The element
naming convention is:
image name\module name\routine name\line number
For example:
traceback: 8:000BA800+00065C00=00120400 DECC$SHR (Image)
00066EDE DBG$HA_KERNEL
00005864 CRL$MAIN_DB\CRL_LIBRARY\crl__initialize_libraries\%LINE 5592
208 – ha_window_def_final
When the traceback display appears, you identify the traceback entry most closely associated with the segment you are investigating. Most often, you can do this by comparing segment type names and traceback routine names. When you double click MB1 on this traceback entry, the source code associated with the entry appears (highlighted) in the Source Window. You can then scroll through the source code display, identify problematic code, and decide how to correct it. If you cannot identify any problems in the displayed source code, return to the Information Window and double click MB1 on the routine immediately above or below your previous choice. If you double click MB1 on a traceback entry, and 'Source Not Available' messages appear in the Source Window, you may have forgotten to set a source directory at the beginning of your heap analyzer session. See the 'Setting a Source Directory' help topic for information on setting a search directory.
209 – ha_window_optwork
The following sections describe the steps to perform when the memory
events represented in the default Memory Map are not clear; that is,
you cannot tell whether a problem exists or not.
This circumstance can occur when the segment type names chosen by the
heap analyzer are too broad to be useful for your application, or when
the Memory Map is so full that you cannot easily see the segment of
interest.
In such cases, you can choose one or both of the following strategies:
- Review the type summary in the Type Histogram (to see a summary, in
total segments and total bytes, of each segment type's use) Buff
- Adjust the type determination in the Memory Map (directing the heap
analyzer to select type names that are more meaningful to you)
- Adjust the type display in the Memory Map (directing the heap
analyzer to suppress some types and highlight others)
If, by adjusting the type determination or display, you then identify
visible problems, you can resolve them in the same way you would if you
were working with the default Memory Map display. (For more
information, see the 'Working with the Default Display' help topic.)
210 – ha_window_opt_info
As you examine the Memory Map, you may wish to see a summary of Memory Map activity in the Type Histogram. The Type Histogram, which is two histograms back-to-back, shows the percentage of total segments and the percentage of total bytes devoted to each segment type in the Memory Map. To see these graphical representations in numeric form, click MB1 on the segment type of interest. To see the total number of segments or total number of bytes, check the top of each histogram.
211 – ha_window_opt_type
As you examine the Memory Map, you may find that some segment type
names are not meaningful to you. By adding these names to the
Do-not-use Type List, you direct the heap analyzer to rename segments
and, if necessary, regenerate the Memory Map display.
By default, the analyzer assigns segment type names at the creation of
a segment. In some cases, the analyzer assigns an element name (for
example, LIBRTL). In most cases, however, the analyzer searches down
the callstack to find a routine name that then serves as a segment type
name.
The analyzer chooses the first routine name on the callstack that is
not prohibited by the Do-not-use Type List. If the first routine is
prohibited, the analyzer examines the next routine down, and so on.
This default behavior can cause the following Memory Map problems:
- The same few type names appear repeatedly in the Memory Map
display.
This occurs when the first routines on the callstack are low-level
memory management or utility routines. Since most of the
allocation events in your application use these routines, you see
unrelated allocations grouped together with the same type name.
To prevent this problem, add any application-specific memory
management or utility routine names to the Do-not-use Type List
before you run your application.
- The type names assigned provide a higher level of abstraction than
you require.
This can occur when the first routine on the callstack is less
application-bound than your level of examination. If you need to
see type names that reflect application functions, it is not
helpful to see type names derived from intermediary memory
management routines instead.
This can also occur when the first routine on the callstack focuses
on a part of your application you are not interested in examining.
If you need to see type names that reflect subsystem functions (for
example, initialize_death_star), it is not helpful to see only one
type name for all subsystem functions (for example,
initialize_star).
To correct this problem, add the current type name to the
Do-not-use Type List until the Memory Map display reflects the
level of abstraction you desire.
To add a segment type name to the Do-not-use Type List, you can select
the Add to Do-not-use Type List pull-down menu item in the Options
menu, or you can choose the Do Not Use Type pop-up menu item in the
Memory Map, Type Histogram, or Views-and-Types Display. To delete a
segment type from this list, choose the Use Type pop-up menu item in
the Do-not-use Type List.
To save the contents of a Do-not-use Type List, you can choose the Save
Do-not-use Type List menu item in the Options menu. This saves the
list for future heap analyzer sessions. The Restore Do-not-use Type
List menu item removes recent additions to the list since the last time
the list was saved.
212 – ha_window_opt_disp
As you examine the Memory Map, you may find that you need to adjust the type display to focus more clearly on your area of interest. The Views-and-Types Display allows you to specify changes to multiple or individual segments of the same type. The Views-and-Types Display is actually two windows separated by a window sash. You can expand the left window to show all the known types in your application. The right window contains the display options (color, show status, expand status, and save status).
213 – ha_window_opt_scope
The heap analyzer receives information about segments from four OpenVMS
memory managers that perform allocations and deallocations in memory
space. Each memory manager has a slightly different view, or overall
picture, of dynamic memory.
Each memory manager recognizes a different set of segment types. This
means that, within the heap analyzer, where views from the memory
managers are layered on each other, a single memory location can be
associated with one or more segment types.
The left window of the Views-and-Types Display contains a hierarchy
that reflects this integration:
- Views (integrates all four views)
- Blocks (block view from LIB$VM memory manager)
- Images (image view from SYS$IMAGE memory manager)
- Regions (system services view from SYS$SERVICES memory manager)
- Zones (zone view from LIB$VM_ZONE memory manager)
To see the individual segment types recognized by each memory manager,
expand the default display by double clicking MB1 on Blocks, Images,
Regions, or Zones keywords. To collapse an individual listing, click
MB3 on the keyword you previously selected.
This hierarchy offers you the following choices in scope:
- To affect all segment types in all views:
Click MB1 on the Views keyword
- To affect all segment types in one view:
Click MB1 on the Blocks, Images, or Zones keywords.
- To affect individual segment types:
Double click MB1 on the view of your choice, and click MB1 on one
or more single segment types.
214 – ha_window_opt_dispopt
The right window of the Views-and-Types Display shows the display
options available, as follows:
- Color
To change the color of all segment types, all segment types in a
particular view, or individual segment types, click MB3 on the
color button in the display. When the vertical color strip
appears, click MB1 on the color of your choice. Then, click the
Apply button to apply your change.
- Show (or hide) status
To suppress (or restore) the display of all segment types, all
segment types in particular view, or individual segment types,
toggle the Show button to the Hide (or Show) setting and click MB1.
(Alternatively, you can choose the appropriate menu item from the
Show pop-up menu.) Then, click the Apply button to apply your
change.
Use this option to clear the Memory Map of segments you are not
examining. You can also use this option to find all segments of a
particular type (by hiding every other segment).
- Expand (or collapse) status
To collapse (or expand) the display of segment types contained
within all segment types, all segment types in a particular view,
or individual segment types, toggle the Expand button to the
Collapse (or Expand) setting and click MB1. (Alternatively, you
can choose the appropriate menu item from the Expand pop-up menu.)
Then, click the Apply button to apply your change.
Use this option to clear the Memory Map of nested segments you are
not examining. Depending on your application, heap analyzer
performance may also improve.
- Save (or remove) status
To destroy (or save) information on all segment types, all segment
types in a particular view, or individual segment types, toggle the
Save button to the Remove (or Save) setting and click MB1.
(Alternatively, you can choose the appropriate menu item from the
Save pop-up menu.) Then, click the Apply button to apply your
change.
Use this option to clear the Memory Map completely, and then resume
Memory Map display.
To cancel a choice, click the Reset button, or choose the Reset menu
item from the Show, Expand, or Save pop-up menus.
215 – ha_window_exit
To exit the heap analyzer, choose the Exit item from the File menu on the heap analyzer screen.
216 – ha_on_version_hlp
The heap analyzer is a feature of the OpenVMS Debugger Software Version: OpenVMS Debugger Version 8.2 © 2005 Hewlett-Packard Development Company, L.P. All rights reserved. For more information about the heap analyzer, double click on 'Using the Heap Analyzer' from the list of Additional Topics below.
217 – ha_on_help_hlp
Two kinds of online help about the debugger and debugging are available
during a debugging session:
Context-sensitive help, which is information about an area or
object in a window or dialog box
- Task-oriented help, which consists of an introductory help topic
named 'Using the Heap Analyzer' and several subtopics on specific
debugging tasks
Related context-sensitive and task-oriented topics are connected
through the list of Additional Topics in the Help windows.
218 – ha_context_sensitive_help
Context-sensitive help is information about an area or object in a
window or a dialog box.
To display context-sensitive help:
1. Choose On Context from the Help menu in the heap analyzer screen.
The pointer shape changes to a question mark (?).
2. Place the question mark on an object or area in a heap analyzer
window or dialog box.
3. Click on MB1. Help for that area or object is displayed in a Help
window. Additional Topics provide task-oriented discussions, where
applicable.
To display context-sensitive help for a dialog box, you can also click
on the Help button in the dialog box.