[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Debugger Manual

OpenVMS Debugger Manual

Order Number: AA-QSBJC-TE


January 1999

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.1.

Software Version: OpenVMS Alpha Version 7.2 OpenVMS VAX Version 7.2




Compaq Computer Corporation
Houston, Texas


January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

© Compaq Computer Corporation 1999. All rights reserved.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DEC Ada, DEC BASIC, DEC Fortran, DECdirect, DECnet, DECthreads, DECterm, DIGITAL, eXcursion, LAT, MicroVAX, OpenVMS, PATHWORKS, VAX, VAX Ada, VMS, VT, and the Compaq logo.

The following are third-party trademarks:

BASIC is a registered trademark of the Trustees of Dartmouth College, (Dartmouth Structured Basic) D.B.A. Dartmouth College.

INSTALLSHIELD is a registered trademark of Stirling Technologies, Inc.

Intel is a registered trademark of Intel Corporation.

IEEE and POSIX are registered trademarks of The Institute of Electrical and Electronics Engineers, Inc.

Microsoft Windows NT and Windows NT are registered trademarks and Windows 95 is a trademark of Microsoft Corporation.

Motif, OSF, OSF/1, and OSF/Motif are registered trademarks and Open Software Foundation is a trademark of the Open Software Foundation, Inc.

OSI is a registered trademark of CA Management, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK4538

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index


Preface

Intended Audience

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

On VAX processors, you can use the debugger with programs written in the following VAX 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 the following DEC languages:
Ada BASIC BLISS C
C++ COBOL Fortran MACRO-32 1
MACRO-64 Pascal PL/I  


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

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 DECwindows Motif, command line, and screen mode 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:

Related Documents

The following documents may also be helpful when using the debugger.

Programming Languages

This manual emphasizes debugger usage that is common to all or most supported languages. For more information specific to a particular language, see:

Linker Utility

For information about the linking of programs or shareable images, see the OpenVMS Linker Utility Manual.

Delta/XDelta Debugger

For information about debugging code in supervisor, executive, or kernel modes (that is, in other than user mode), see the OpenVMS Delta/XDelta Debugger Manual in the OpenVMS documentation set. This manual contains information about debugging programs that run in privileged processor mode or at an elevated interrupt priority level.

OpenVMS Alpha System-Code Debugger (Alpha Only)

On Alpha processors, see the OpenVMS Alpha Device Support: Developer's Guide for information on debugging Alpha operating system code. This manual describes how to create an Alpha device driver, activate the OpenVMS Alpha System-Code Debugger through the OpenVMS Debugger, and debug within the OpenVMS Alpha System-Code Debugger environment.

For information on the OpenVMS Alpha System-Code Debugger-specific commands, see the CONNECT and REBOOT commands in Part 6.

DECwindows Motif

For general information about the DECwindows Motif interface, see the VMS DECwindows User's Guide.

For additional information on the Open Systems Software Group (OSSG) products and services, access the following OpenVMS World Wide Web address:


http://www.openvms.digital.com 

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:
Internet openvmsdoc@zko.mts.dec.com
Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:


 http://www.openvms.digital.com:81/ 

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

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 DECwindows Motif for OpenVMS software.

This manual contains many figures showing the DECwindows Motif 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 and 8-digit numbers on VAX. 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 elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.
bold text This text style represents the introduction of a new term or 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 1
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:

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:

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.

Note

The kernel and main debugger communicate through global sections. The main debugger communicates with up to eight kernel debuggers through a 65-page (VAX) or 65-pagelet (Alpha) global section (65*512 bytes on either platform). Therefore, you might need to increase the system parameters GBLPAGES and GBLSECTIONS. For example, if 10 users use the debugger simultaneously, the debugger requires 10 global sections using a total of 650 global pages or pagelets.

Note

Each user needs a PRCLM quota sufficient to create an additional subprocess for the debugger, beyond the number of processes needed by the program.

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. You may need to increase these quotas to account for the debugger subprocess as follows:

  • You should increase each user's ENQLM quota by at least the number of processes being debugged.
  • You might need to increase each user's PGFLQUOTA. If a user has an insufficient PGFLQUOTA, the debugger may fail to activate or may cause "virtual memory exceeded" errors during execution.
  • You might need to increase each user's BYTLM and FILLM quotas. The debugger requires sufficient BYTLM and FILLM quotas to open each image file being debugged, the corresponding source files, and the debugger input, output, and log files. To increase these quotas, you can run SYS$SYSTEM:AUTHORIZE.EXE to adjust parameters in SYSUAF.DAT.

1.1.1 Functional Features

Programming Language Support

On VAX processors, you can use the debugger with programs written in the following VAX 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 the following DEC languages:
Ada BASIC BLISS C
C++ COBOL Fortran MACRO-32 1
MACRO-64 Pascal PL/I  


1Note 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 commands. 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 DECthreads 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.

Vector Debugging (VAX Only)

On VAX processors, you can debug vectorized programs, that is, programs that use VAX vector instructions. You can control and monitor execution at the vector instruction level, examine and deposit vector instructions, manipulate the contents of vector registers, use a mask to display specific vector elements, and control synchronization between the scalar and vector processors.

Terminal and Workstation Support

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


Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4538PRO.HTML