[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

OpenVMS Debugger Manual

Order Number: BA554-90016

June 2010

This manual explains the features of the OpenVMS Debugger for programmers in high-level languages and assembly language.

Revision/Update Information: This manual supersedes the OpenVMS Debugger Manual, Version 7.2.

Software Version: OpenVMS Version 8.4 for Integrity servers
OpenVMS Alpha Version 8.4

Hewlett-Packard Company
Palo Alto, California

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.

Printed in the U.S.A.

ZK4538

The HP OpenVMS documentation set is available on CD-ROM.

Contents

Index

Preface

Intended Audience

This manual is for programmers at all levels of experience. It covers all user interfaces of the OpenVMS Debugger:

The command interface for terminals and workstations
The HP DECwindows Motif for OpenVMS user interface for workstations
The Microsoft Windows PC client interface

The OpenVMS Debugger on OpenVMS Alpha systems can access all the extended memory made available by the 64-bit processing of the OpenVMS Alpha operating system. Hence, you can examine and manipulate data in the complete 64-bit address space.

The OpenVMS Debugger has been internationalized. For Asian users, the debugger's HP DECwindows Motif for OpenVMS, command line, and screen mode user interfaces can be used with multibyte characters.

You can use the debugger to debug code only in user mode. You cannot debug code in supervisor, executive, or kernel modes.

Document Structure

This manual is organized as follows:

Part 1 introduces the OpenVMS Debugger. Part 1 contains one chapter:
- Chapter 1 introduces the debugger.
Part 2 describes the debugger's command interface. Part 2 includes the following chapters:
- Chapter 2 gets you started using the debugger.
- Chapter 3 explains how to control and monitor program execution.
- Chapter 4 explains how to examine and manipulate program data.
- Chapter 5 explains how to control access to symbols in your program.
- Chapter 6 explains how to control the display of source code.
- Chapter 7 explains how to use screen mode.
Part 3 describes the debugger's HP DECwindows Motif for OpenVMS user interface. Part 3 includes the following chapters:
- Chapter 8 gives an overview of its HP DECwindows Motif for OpenVMS user interface features.
- Chapter 9 explains how to prepare your program for debugging and then start and end a debugging session using the HP DECwindows Motif for OpenVMS user interface.
- Chapter 10, which is organized by task, explains how to use the debugger via the HP DECwindows Motif for OpenVMS user interface.
Part 4 describes the debugger's PC interface. Part 4 contains one chapter:
- Chapter 11 gives an overview of the debugger's PC interface.
Part 5 describes advanced debugging topics. Part 5 includes the following chapters:
- Chapter 12, which is organized by task, explains how to use the debugger's Heap Analyzer.
- Chapter 13 explains additional convenience features, such as key definitions and other customizations.
- Chapter 14 explains some special cases, such as debugging optimized programs and multilanguage programs.
- Chapter 15 explains how to debug multiprocess programs.
- Chapter 16 explains how to debug tasking (multithread) programs.

Part 6 is the debugger command dictionary, followed by the appendixes:
- Appendix A lists the keypad-key definitions that are predefined by the debugger.
- Appendix B identifies all of the debugger built-in symbols and logical names.
- Appendix C identifies the debugger support for languages.
- Appendix D contains the source code of the programs shown in the figures in Chapters 8, 9, and 10.

Reader's Comments

HP welcomes your comments on this manual. Please send your comments or suggestions to the following address:

openvmsdoc@hp.com

How to Order Additional Documentation

For information about how to order additional documentation, see:

http://www.hp.com/go/openvms/doc/order

Conventions

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Clusters or clusters in this document are synonymous with VMSclusters.

In this manual, every use of DECwindows and DECwindows Motif refers to HP DECwindows Motif for OpenVMS software.

This manual contains many figures showing the DECwindows Motif user interface to the debugger. Because the display configuration of this interface is customizable, these figures may not exactly picture the appearance of debugger displays on your system.

The examples in this manual have not been updated to reflect the fact that the OpenVMS Debugger on OpenVMS Alpha systems can access all the extended memory made available by the 64-bit processing of the OpenVMS Alpha operating system. You should note that hexadecimal addresses are 16-digit numbers on Alpha. For example,

DBG> EVALUATE/ADDRESS/HEX %hex 000004A0
00000000000004A0 
DBG>

The following conventions are also used in this manual:

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), (-), or underscore (_) as a delimiter in EVE commands.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional choices. You can choose one or more items or no items. Do not type the brackets on the command line. However, you must include the brackets in the syntax for OpenVMS directory specifications and for a substring specification in an assignment statement.
\|	In command format descriptions, vertical bars separate choices within brackets or braces. Within brackets, the choices are optional; within braces, at least one choice is required. Do not type the vertical bars on the command line.
{ }	In command format descriptions, braces indicate required choices; you must choose at least one of the of the items listed. Do not type the braces on the command line.
bold text	This typeface represents the introduction of a new term. It also represents the name of an argument an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Part I
Introduction to the Debugger

This part introduces the Debugger.

Chapter 1
Introduction to the Debugger

This chapter briefly describes the command interface of the OpenVMS Debugger, and provides the following information:

An overview of debugger features
Instructions to compile and link your program for debugging
Instructions to start and end a debugging session
A list of the debugger commands grouped by function

For a tutorial introduction to basic debugging tasks, see Chapter 2.

1.1 Overview of the Debugger

The OpenVMS Debugger is a tool to locate run-time programming or logic errors, also known as bugs, in 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.

By using the OpenVMS Debugger, you can locate program bugs by observing and manipulating the program interactively as it executes. Debugger commands enable you to:

Control and observe execution of the program
Display and browse through the source code of the program to identify instructions and variables worth scrutiny
Suspend program execution at specified points in order to monitor changes in variables and other program entities
Change the value of a variable and, in some cases, test the modification without having to edit the source code, recompile, and relink
Trace the execution path of the program
Monitor exception conditions and language-specific events

These are basic debugging techniques. After locating program errors, you can edit the source code and compile, link, execute, and test the corrected version.

As you use the debugger and its documentation, you will discover and develop variations on the basic techniques. You can also customize the debugger for your own needs. Section 1.1.1 summarizes the features of the OpenVMS Debugger.

1.1.1 Functional Features

Programming Language Support

On Alpha processors, you can use the debugger with programs written in the following Compaq languages:

Ada	BASIC	BLISS	C
C++	COBOL	Fortran	MACRO-32 ¹
MACRO-64	Pascal	PL/I

¹Note that MACRO-32 must be compiled with the AMACRO compiler.

On Integrity server, you can use the debugger with programs written in the following Compaq languages:

Assembler (IAS)	BASIC	BLISS	C
C++	COBOL	Fortran	MACRO-32 ¹
IMACRO	PASCAL
Assembler (IAS)	BASIC	BLISS	C
C++	COBOL	Fortran	MACRO-32 ¹
IMACRO	PASCAL

¹Note that MACRO-32 must be compiled with the AMACRO compiler.
¹Note that MACRO-32 must be compiled with the AMACRO compiler.

The debugger recognizes the syntax, data types, operators, expressions, scoping rules, and other constructs of a supported language. You can change the debugging context from one language to another (with the SET LANGUAGE command) during a debugging session.

Symbolic Debugging

The debugger is a symbolic debugger. You can refer to program locations by the symbols used in your program---the names of variables, routines, labels, and so on. You can also specify explicit memory addresses or machine registers if you choose.

Support for All Data Types

The debugger recognizes the data types generated by the compilers of all supported languages, such as integer, floating-point, enumeration, record, array, and so on, and displays the values of each program variable according to its declared type.

Flexible Data Format

With the debugger, you can enter and display a variety of data forms and data types. The source language of the program determines the default format for the entry and display of data. However, you can select other formats as needed.

Starting or Resuming Program Execution

Once the program is under control of the debugger, you can start or resume program execution with the GO or STEP command. The GO command causes the program to execute until specified events occur (the PC points to a designated line of code, a variable is modified, an exception is signaled, or the program terminates). You can use the STEP command to execute a specified number instructions or lines of source code, or until the program reaches the next instruction of a specified class.

Breakpoints

You can set a breakpoint with the SET BREAK command, to suspend program execution at a specified location in order to check the current status of the program. You can also direct the debugger to suspend execution when the program is about to execute an instruction of a specific class. You can also suspend execution when certain events occur, such as exceptions and tasking (multithread) events.

Tracepoints

You can set a tracepoint with the SET TRACE command, to cause the debugger to report each time that program execution reaches a specified location (that is, each time the program counter (PC) references that location). As with the SET BREAK command, you can also trace the occurrence of classes of instructions and monitor the occurrence of certain events, such as exceptions and tasking (multithread) events.

Watchpoints

You can set a watchpoint with the SET WATCH command to cause the debugger to suspend program execution whenever a particular variable (or other specified memory location) has been modified, at which point the debugger reports the old and new values of the variable.

Manipulation of Variables and Program Locations

You can use the EXAMINE command to determine the value of a variable or memory location. You can use the DEPOSIT command to change that value. You can then continue execution of the program to determine the effect of the change without having to recompile, relink, and rerun the program.

Evaluation of Expressions

You can use the EVALUATE command to compute the value of a source-language expression or an address expression in the syntax of the language to which the debugger is currently set.

Control Structures

You can use logical control structures (FOR, IF, REPEAT, WHILE) in commands to control the execution of other commands.

Shareable Image Debugging

You can debug shareable images (images that are not directly executable). The SET IMAGE command enables you to access the symbols declared in a shareable image (that was compiled and linked with the /DEBUG qualifiers).

Multiprocess Debugging

You can debug multiprocess programs (programs that run in more than one process). The SHOW PROCESS and SET PROCESS commands enable you to display process information and to control the execution of images in individual processes.

Task Debugging

You can debug tasking programs (also known as multithread programs). These programs use Compaq POSIX Threads Library or POSIX 1003.1b services, or use language-specific tasking services (for example, Ada tasking programs). The SHOW TASK and SET TASK commands enable you to display task information and to control the execution of individual tasks.

Terminal and Workstation Support

The debugger supports all VT-series terminals and VAX workstations.

1.1.2 Convenience Features

Online Help

Online help is always available during a debugging session. Online help contains information about all debugger commands and additional selected topics.

Source Code Display

During a debugging session, you can display the source code for program modules written in any of the languages supported by the OpenVMS Debugger.

Screen Mode

In screen mode, you can capture and display various kinds of information in scrollable display units. You can move these display units around the screen and resize them as needed. Automatically updated source, instruction, and register displays units are available. You can selectively direct debugger input, output, and diagnostic messages to specific display units. You can also create display units to capture the output of specific command sequences.

Kept Debugger

The kept debugger enables you to run different program images or rerun the same image from the current debugging session without having to first exit and restart the debugger. When you rerun a program, you can choose to retain or cancel any previously set breakpoints, as well as most tracepoints and watchpoints.

DECwindows Motif User Interface

The OpenVMS Debugger has an optional HP DECwindows Motif for OpenVMS graphical user interface (GUI) that provides access to common debugger commands by means of pushbuttons, pulldown menus, and popup menus. The GUI is an optional enhancement to the debugger command line interface that is available on workstations running DECwindows Motif. When using the GUI, you have full command-line access to all debugger commands that are relevant within a DECwindows Motif environment.

Microsoft Windows Interface

The OpenVMS Debugger has an optional client/server configuration that allows you to access the debugger and its functions from a PC running on your supplied Microsoft operating system. This debugger implementation has a debug server that runs on OpenVMS on an Alpha or Integrity server CPU, and a debug client interface that runs on Microsoft operating systems on an Intel or Alpha CPU.

Client/Server Configuration

The client/server configuration allows you to debug programs that run on an OpenVMS node remotely from another OpenVMS node using the DECwindows Motif user interface, or from a PC using the Microsoft Windows interface. Up to 31 debug clients can simultaneously access the same debug server, which allows many debugging options.

Keypad Mode

When you start the debugger, several predefined debugger command sequences are assigned to the keys of the numeric keypad of the VT52, VT100, and LK201 keyboards. You can also create your own key definitions.

Source Editing

As you find errors during a debugging session, you can use the EDIT command to use any editor available on your system. You can specify the editor with the SET EDITOR command. If you use the Language-Sensitive Editor (LSE), the editing cursor is automatically positioned within the source file corresponding to the source code that appears in the screen-mode source display.

Command Procedures

You can direct the debugger to execute a command procedure (a file of debugger commands) to re-create a debugging session, to continue a previous session, or to avoid typing the same debugger commands many times during a debugging session. In addition, you can pass parameters to command procedures.

Initialization Files

You can create an initialization file that contains debugger commands to set default debugging modes, screen display definitions, keypad key definitions, symbol definitions, and so on. Upon startup, the OpenVMS Debugger automatically executes the initialization file to create the predefined debugging environment.

Log Files

You can create a log file to contain a record of command input and debugger output. You can then use the log file to analyze the debugging session, or edit the file for use as a command procedure in subsequent debugging sessions.

Symbol Definitions

You can define your own symbols to represent lengthy commands, address expressions, or values in abbreviated form.