OpenVMS Debugger Manual - Software Products Library

OpenVMS Debugger Manual - Software Products Library
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
© Copyright 2010 Hewlett-Packard Development Company, L.P.
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.
This document was prepared using DECdocument, Version 3.3-1b.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xxiii
Part I Introduction to the Debugger
1 Introduction to the Debugger
Overview of the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Functional Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Convenience Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preparing an Executable Image for Debugging . . . . . . . . . . . . . . . . . . . . .
Compiling a Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking a Program for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling Debugger Activation with the LINK and RUN Commands
.......................................................
1.3
Debugging a Program with the Kept Debugger . . . . . . . . . . . . . . . . . . . . .
1.3.1
Starting the Kept Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.3.2
When Your Program Completes Execution . . . . . . . . . . . . . . . . . . . . . .
1.3.3
Rerunning the Same Program from the Kept Debugger . . . . . . . . . . .
1.3.4
Running Another Program from the Kept Debugger . . . . . . . . . . . . . .
1.4
Interrupting Program Execution and Aborting Debugger Commands . . . .
1.5
Pausing and Resuming a Debugging Session . . . . . . . . . . . . . . . . . . . . . . .
1.6
Starting the Debugger by Running a Program . . . . . . . . . . . . . . . . . . . . .
1.7
Starting the Debugger After Interrupting a Running Program . . . . . . . . .
1.8
Ending a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.9
Debugging a Program on a Workstation Running DECwindows Motif . . . .
1.10
Debugging a Program from a PC Running the Debug Client . . . . . . . . . .
1.11
Debugging Detached Processes That Run with No CLI . . . . . . . . . . . . . . .
1.12
Configuring Process Quotas for the Debugger . . . . . . . . . . . . . . . . . . . . . .
1.13
Debugger Command Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.1
Starting and Ending a Debugging Session . . . . . . . . . . . . . . . . . . . . . .
1.13.2
Controlling and Monitoring Program Execution . . . . . . . . . . . . . . . . .
1.13.3
Examining and Manipulating Data . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.4
Controlling Type Selection and Radix . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.5
Controlling Symbol Searches and Symbolization . . . . . . . . . . . . . . . .
1.13.6
Displaying Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.7
Using Screen Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.8
Editing Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.9
Defining Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.10
Using Keypad Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.11
Using Command Procedures, Log Files, and Initialization Files . . . . .
1.13.12
Using Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.13
Debugging Multiprocess Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.13.14
Additional Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1
1.1.1
1.1.2
1.2
1.2.1
1.2.2
1.2.3
1–1
1–2
1–3
1–5
1–5
1–6
1–6
1–7
1–8
1–11
1–11
1–12
1–12
1–12
1–13
1–14
1–15
1–15
1–16
1–17
1–17
1–17
1–18
1–18
1–19
1–19
1–19
1–20
1–20
1–21
1–21
1–21
1–21
1–22
1–22
1–22
iii
Part II Command Interface
2 Getting Started with the Debugger
2.1
2.2
2.2.1
2.2.2
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.3.5
2.3.6
2.4
2.4.1
2.4.2
2.4.3
2.5
2.5.1
2.5.2
2.6
Entering Debugger Commands and Accessing Online Help
Displaying Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . .
Noscreen Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Screen Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling and Monitoring Program Execution . . . . . . . . .
Starting or Resuming Program Execution . . . . . . . . . .
Executing the Program by Step Unit . . . . . . . . . . . . . .
Determining Where Execution Is Paused . . . . . . . . . . .
Suspending Program Execution with Breakpoints . . . .
Tracing Program Execution with Tracepoints . . . . . . .
Monitoring Changes in Variables with Watchpoints . . .
Examining and Manipulating Program Data . . . . . . . . . . .
Displaying the Value of a Variable . . . . . . . . . . . . . . . .
Assigning a Value to a Variable . . . . . . . . . . . . . . . . . .
Evaluating Language Expressions . . . . . . . . . . . . . . . .
Controlling Access to Symbols in Your Program . . . . . . . . .
Setting and Canceling Modules . . . . . . . . . . . . . . . . . .
Resolving Symbol Ambiguities . . . . . . . . . . . . . . . . . . .
Sample Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2–1
2–4
2–4
2–5
2–6
2–6
2–7
2–7
2–8
2–9
2–10
2–11
2–12
2–13
2–13
2–14
2–14
2–15
2–15
Commands Used to Execute the Program . . . . . . . . . . . . . . . . . . . . . . . . .
Executing the Program by Step Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the STEP Command Behavior . . . . . . . . . . . . . . . . . . . . . . .
Stepping Into and Over Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Suspending and Tracing Execution with Breakpoints and Tracepoints . . .
Setting Breakpoints or Tracepoints on Individual Program
Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Symbolic Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Locations in Memory . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining and Symbolizing Memory Addresses . . . . . . . . . . . . . . .
Setting Breakpoints or Tracepoints on Lines or Instructions . . . . . . . .
Setting Breakpoints on Emulated Instructions (Alpha Only) . . . . . . . .
Controlling Debugger Action at Breakpoints or Tracepoints . . . . . . . .
Setting Breakpoints or Tracepoints on Exceptions . . . . . . . . . . . . . . . .
Setting Breakpoints or Tracepoints on Events . . . . . . . . . . . . . . . . . .
Deactivating, Activating, and Canceling Breakpoints or Tracepoints
.......................................................
Monitoring Changes in Variables and Other Program Locations . . . . . . . .
Deactivating, Activating, and Canceling Watchpoints . . . . . . . . . . . . .
Watchpoint Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Watching Nonstatic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Execution Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting a Watchpoint on a Nonstatic Variable . . . . . . . . . . . . . . . .
Options for Watching Nonstatic Variables . . . . . . . . . . . . . . . . . . .
Setting Watchpoints in Installed Writable Shareable Images . . . .
3–1
3–2
3–2
3–3
3–4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3 Controlling and Monitoring Program Execution
3.1
3.2
3.2.1
3.2.2
3.3
3.3.1
3.3.1.1
3.3.1.2
3.3.1.3
3.3.2
3.3.3
3.3.4
3.3.5
3.3.6
3.3.7
3.4
3.4.1
3.4.2
3.4.3
3.4.3.1
3.4.3.2
3.4.3.3
3.4.3.4
iv
3–5
3–6
3–7
3–8
3–8
3–9
3–9
3–10
3–10
3–11
3–11
3–13
3–14
3–14
3–15
3–15
3–16
3–16
4 Examining and Manipulating Program Data
4.1
4.1.1
4.1.2
4.1.3
4.1.4
4.1.5
4.1.6
4.1.6.1
4.1.6.2
4.1.7
4.1.8
4.1.9
4.1.10
4.1.11
4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.3
4.3.1
4.4
4.4.1
4.4.2
4.5
4.5.1
4.5.2
4.5.2.1
4.5.2.2
4.5.2.3
General Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Variables While Debugging . . . . . . . . . . . . . . . . .
Using the EXAMINE Command . . . . . . . . . . . . . . . . . . . . .
Using the DUMP Command . . . . . . . . . . . . . . . . . . . . . . . . .
Using the DEPOSIT Command . . . . . . . . . . . . . . . . . . . . . .
Address Expressions and Their Associated Types . . . . . . . .
Evaluating Language Expressions . . . . . . . . . . . . . . . . . . . .
Using Variables in Language Expressions . . . . . . . . . . .
Numeric Type Conversion by the Debugger . . . . . . . . . .
Address Expressions Compared to Language Expressions . .
Specifying the Current, Previous, and Next Entity . . . . . . .
Language Dependencies and the Current Language . . . . . .
Specifying a Radix for Entering or Displaying Integer Data
Obtaining and Symbolizing Memory Addresses . . . . . . . . . .
Examining and Depositing into Variables . . . . . . . . . . . . . . . . .
Scalar Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ASCII String Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Array Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Record Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pointer (Access) Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examining and Depositing Instructions . . . . . . . . . . . . . . . . . . .
Examining Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examining and Depositing into Registers . . . . . . . . . . . . . . . . .
Examing and Depositing into Alpha Registers . . . . . . . . . . .
Examing and Depositing into Integrity server Registers . . .
Specifying a Type When Examining and Depositing . . . . . . . . .
Defining a Type for Locations Without a Symbolic Name . . .
Overriding the Current Type . . . . . . . . . . . . . . . . . . . . . . . .
Integer Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ASCII String Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-Declared Types . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4–1
4–1
4–2
4–3
4–4
4–5
4–6
4–7
4–8
4–8
4–9
4–11
4–12
4–13
4–15
4–16
4–17
4–17
4–19
4–20
4–20
4–21
4–22
4–22
4–24
4–29
4–29
4–30
4–31
4–31
4–32
Controlling Symbol Information When Compiling and Linking .
Compiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local and Global Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling Symbol Information in Debugged Images . . . . . .
Creating Separate Symbol Files (Alpha Only) . . . . . . . . . . . .
Setting and Canceling Modules . . . . . . . . . . . . . . . . . . . . . . . . . .
Resolving Symbol Ambiguities . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbol Lookup Conventions . . . . . . . . . . . . . . . . . . . . . . . . .
Using SHOW SYMBOL and Path Names to Specify Symbols
Uniquely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Simplifying Path Names . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Symbols in Routines on the Call Stack . . . . . .
Specifying Global Symbols . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Routine Invocations . . . . . . . . . . . . . . . . . . . .
Using SET SCOPE to Specify a Symbol Search Scope . . . . . .
Debugging Shareable Images . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiling and Linking Shareable Images for Debugging . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5–2
5–2
5–3
5–4
5–5
5–6
5–6
5–8
5–8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5–9
5–10
5–10
5–11
5–11
5–11
5–12
5–12
5 Controlling Access to Symbols in Your Program
5.1
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.2
5.3
5.3.1
5.3.2
5.3.2.1
5.3.2.2
5.3.2.3
5.3.2.4
5.3.3
5.4
5.4.1
v
5.4.2
5.4.2.1
5.4.2.2
5.4.2.3
5.4.3
Accessing Symbols in Shareable Images . . . . . . . . . . . . . . . . . . . . . .
Accessing Symbols in the PC Scope (Dynamic Mode) . . . . . . . . . .
Accessing Symbols in Arbitrary Images . . . . . . . . . . . . . . . . . . . .
Accessing Universal Symbols in Run-Time Libraries and System
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging Resident Images (Alpha Only) . . . . . . . . . . . . . . . . . . . . .
.
.
.
5–14
5–14
5–14
.
.
5–16
5–17
.
.
.
.
.
.
.
6–1
6–2
6–3
6–4
6–5
6–7
6–8
Concepts and Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Display Kinds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DO (Command[; . . . ]) Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . .
INSTRUCTION Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INSTRUCTION (Command) Display Kind . . . . . . . . . . . . . . . . . . . . . .
OUTPUT Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REGISTER Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOURCE Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SOURCE (Command) Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . .
PROGRAM Display Kind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Display Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Source Display (SRC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Source Code in Arbitrary Program Locations . . . . . . . .
Displaying Source Code for a Routine on the Call Stack . . . . . . . .
Predefined Output Display (OUT) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Prompt Display (PROMPT) . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Instruction Display (INST) . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying the Instruction Display . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Instructions in Arbitrary Program Locations . . . . . . . .
Displaying Instructions for a Routine on the Call Stack . . . . . . . .
Displaying Register Values for a Routine on the Call Stack . . . . . .
Manipulating Existing Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scrolling a Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Showing, Hiding, Removing, and Canceling a Display . . . . . . . . . . . . .
Moving a Display Across the Screen . . . . . . . . . . . . . . . . . . . . . . . . . .
Expanding or Contracting a Display . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying a Display Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying a Window in Terms of Lines and Columns . . . . . . . . . . . . .
Using a Predefined Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Window Definition . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Display Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving Displays and the Screen State . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Screen Height and Width . . . . . . . . . . . . . . . . . . . . . . . . . . .
7–2
7–4
7–4
7–5
7–5
7–6
7–7
7–8
7–8
7–9
7–9
7–12
7–13
7–14
7–15
7–15
7–15
7–16
7–17
7–18
7–18
7–18
7–19
7–19
7–20
7–20
7–21
7–21
7–21
7–22
7–22
7–22
7–23
7–23
7–24
6 Controlling the Display of Source Code
6.1
6.2
6.3
6.4
6.5
6.6
6.7
How the Debugger Obtains Source Code Information . . . . . . . . .
Specifying the Location of Source Files . . . . . . . . . . . . . . . . . . . .
Displaying Source Code by Specifying Line Numbers . . . . . . . . .
Displaying Source Code by Specifying Code Address Expressions
Displaying Source Code by Searching for Strings . . . . . . . . . . . .
Controlling Source Display After Stepping and at Eventpoints .
Setting Margins for Source Display . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7 Screen Mode
7.1
7.2
7.2.1
7.2.2
7.2.3
7.2.4
7.2.5
7.2.6
7.2.7
7.2.8
7.3
7.4
7.4.1
7.4.1.1
7.4.1.2
7.4.2
7.4.3
7.4.4
7.4.4.1
7.4.4.2
7.4.4.3
7.4.4.4
7.5
7.5.1
7.5.2
7.5.3
7.5.4
7.6
7.7
7.7.1
7.7.2
7.7.3
7.8
7.9
7.10
vi
7.11
Screen-Related Built-In Symbols . . . . . . . . .
7.11.1
Screen Height and Width . . . . . . . . . . . .
7.11.2
Display Built-In Symbols . . . . . . . . . . . .
7.12
Screen Dimensions and Predefined Windows
7.13
Internationalization of Screen Mode . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7–25
7–25
7–25
7–26
7–27
8.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.1.1
Convenience Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2
Debugger Windows and Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.1
Default Window Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2
Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.1
Title Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.2
Source View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.3
Menus on Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.4
Call Stack Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.5
Push Button View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.2.6
Command View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.3
Optional Views Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.2.3.1
Menus on Optional Views Window . . . . . . . . . . . . . . . . . . . . . . . . .
8.3
Entering Commands at the Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.3.1
Debugger Commands That Are Not Available in the HP DECwindows
Motif for OpenVMS Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4
Displaying Online Help About the Debugger . . . . . . . . . . . . . . . . . . . . . . .
8.4.1
Displaying Context-Sensitive Help . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8.4.2
Displaying the Overview Help Topic and Subtopic . . . . . . . . . . . . . . . .
8.4.3
Displaying Help on Debugger Commands . . . . . . . . . . . . . . . . . . . . . .
8.4.4
Displaying Help on Debugger Diagnostic Messages . . . . . . . . . . . . . . .
8–1
8–2
8–5
8–5
8–5
8–6
8–6
8–6
8–8
8–9
8–9
8–10
8–13
8–15
Part III DECwindows Motif Interface
8 Introduction
8–17
8–17
8–18
8–18
8–18
8–18
9 Starting and Ending a Debugging Session
Starting the Kept Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When Your Program Completes Execution . . . . . . . . . . . . . . . . . . . . . . . . .
Rerunning the Same Program from the Current Debugging Session . . . .
Running Another Program from the Current Debugging Session . . . . . . .
Debugging an Already Running Program . . . . . . . . . . . . . . . . . . . . . . . . . .
Interrupting Program Execution and Aborting Debugger Operations . . . .
Ending a Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional Options for Starting the Debugger . . . . . . . . . . . . . . . . . . . . .
Starting the Debugger by Running a Program . . . . . . . . . . . . . . . . . .
Starting the Debugger After Interrupting a Running Program . . . . . .
Overriding the Debugger’s Default Interface . . . . . . . . . . . . . . . . . . . .
Displaying the Debugger’s HP DECwindows Motif for OpenVMS
User Interface on Another Workstation . . . . . . . . . . . . . . . . . . . . .
9.8.3.2
Displaying the Debugger’s Command User Interface in a
DECterm Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.8.3.3
Displaying the Command Interface and Program Input/Output in
Separate DECterm Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.8.3.4
Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY . . .
9.9
Starting the Motif Debug Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.9.1
Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.1
9.2
9.3
9.4
9.5
9.6
9.7
9.8
9.8.1
9.8.2
9.8.3
9.8.3.1
9–1
9–5
9–5
9–6
9–6
9–7
9–7
9–7
9–8
9–9
9–9
9–10
9–10
9–11
9–12
9–13
9–13
vii
.
.
.
.
.
9–13
9–14
9–14
9–16
9–17
10.1
Displaying the Source Code of Your Program . . . . . . . . . . . . . . . . . . . . . . .
10.1.1
Displaying the Source Code of Another Routine . . . . . . . . . . . . . . . . . .
10.1.2
Displaying the Source Code of Another Module . . . . . . . . . . . . . . . . .
10.1.3
Making Source Code Available for Display . . . . . . . . . . . . . . . . . . . . . .
10.1.4
Specifying the Location of Source Files . . . . . . . . . . . . . . . . . . . . . . . .
10.2
Editing Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.3
Executing Your Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.3.1
Determining Where Execution Is Currently Paused . . . . . . . . . . . . . .
10.3.2
Starting or Resuming Program Execution . . . . . . . . . . . . . . . . . . . . . .
10.3.3
Executing Your Program One Source Line at a Time . . . . . . . . . . . . . .
10.3.4
Stepping into a Called Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.3.5
Returning from a Called Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4
Suspending Execution by Setting Breakpoints . . . . . . . . . . . . . . . . . . . . .
10.4.1
Setting Breakpoints on Source Lines . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4.2
Setting Breakpoints on Routines with Source Browser . . . . . . . . . . . .
10.4.3
Setting an Exception Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4.4
Identifying the Currently Set Breakpoints . . . . . . . . . . . . . . . . . . . . . .
10.4.5
Deactivating, Activating, and Canceling Breakpoints . . . . . . . . . . . . .
10.4.6
Setting a Conditional Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.4.7
Setting an Action Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5
Examining and Manipulating Variables . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.1
Selecting Variable Names from Windows . . . . . . . . . . . . . . . . . . . . . .
10.5.2
Displaying the Current Value of a Variable . . . . . . . . . . . . . . . . . . . . .
10.5.3
Changing the Current Value of a Variable . . . . . . . . . . . . . . . . . . . . . .
10.5.4
Monitoring a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.4.1
Monitoring an Aggregate (Array or Structure) Variable . . . . . . . .
10.5.4.2
Monitoring a Pointer (Access) Variable . . . . . . . . . . . . . . . . . . . . .
10.5.5
Watching a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.5.6
Changing the Value of a Monitored Scalar Variable . . . . . . . . . . . . . . .
10.6
Accessing Program Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.6.1
Accessing Static and Nonstatic (Automatic) Variables . . . . . . . . . . . . .
10.6.2
Setting the Current Scope Relative to the Call Stack . . . . . . . . . . . . .
10.6.3
How the Debugger Searches for Variables and Other Symbols . . . . . .
10.7
Displaying and Modifying Values Stored in Registers . . . . . . . . . . . . . . . .
10.8
Displaying the Decoded Instruction Stream of Your Program . . . . . . . . . .
10.9
Debugging Tasking (Multithread) Programs . . . . . . . . . . . . . . . . . . . . . . .
10.9.1
Displaying Information About Tasks (Threads) . . . . . . . . . . . . . . . . . .
10.9.2
Changing Task (Threads) Characteristics . . . . . . . . . . . . . . . . . . . . . .
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.10.1
Defining the Startup Configuration of Debugger Views . . . . . . . . . . .
10.10.2
Displaying or Hiding Line Numbers in Source View and Instruction
View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10–1
10–2
10–5
10–5
10–5
10–6
10–7
10–7
10–8
10–8
10–9
10–9
10–10
10–10
10–11
10–12
10–12
10–13
10–13
10–15
10–16
10–16
10–17
10–19
10–20
10–20
10–22
10–22
10–23
10–24
10–24
10–25
10–26
10–27
10–28
10–28
10–29
10–30
9.9.2
9.9.3
9.9.4
9.9.5
9.9.6
Starting the Server . . . . . . . . . . . . . . .
Primary Clients and Secondary Clients
Starting the Motif Client . . . . . . . . . . .
Switching Between Sessions . . . . . . . .
Closing a Client/Server Session . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10 Using the Debugger
viii
10–30
10–31
10–31
Modifying, Adding, Removing, and Resequencing Push Buttons . . . . .
Changing a Button’s Label or Associated Command . . . . . . . . . . .
Adding a New Button and Associated Command . . . . . . . . . . . . .
Removing a Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Resequencing a Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing the Debugger Resource File . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining the Key Sequence to Display the Breakpoint Dialog Box
....................................................
10.10.4.2
Defining the Key Sequence for Language-Sensitive Text Selection
....................................................
10.10.4.3
Defining the Font for Displayed Text . . . . . . . . . . . . . . . . . . . . . .
10.10.4.4
Defining the Key Bindings on the Keypad . . . . . . . . . . . . . . . . . .
10.11 Debugging Detached Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10.10.3
10.10.3.1
10.10.3.2
10.10.3.3
10.10.3.4
10.10.4
10.10.4.1
10–32
10–32
10–33
10–34
10–34
10–35
10–41
10–41
10–41
10–41
10–42
Part IV PC Client Interface
11 Using the Debugger PC Client/Server Interface
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11–1
11–1
11–2
11–2
11–2
11–3
11–3
11–4
11–4
11–4
11–4
11–5
12.1
Starting a Heap Analyzer Session . . . . . . . . . . . . . . . . . .
12.1.1
Invoking the Heap Analyzer . . . . . . . . . . . . . . . . . . .
12.1.2
Viewing Heap Analyzer Windows . . . . . . . . . . . . . . . .
12.1.3
Viewing Heap Analyzer Pull-Down Menus . . . . . . . . .
12.1.4
Viewing Heap Analyzer Context-Sensitive Menus . . .
12.1.5
Setting a Source Directory . . . . . . . . . . . . . . . . . . . . .
12.1.6
Starting Your Application . . . . . . . . . . . . . . . . . . . . .
12.1.7
Controlling the Speed of Display . . . . . . . . . . . . . . . .
12.2
Working with the Default Display . . . . . . . . . . . . . . . . . .
12.2.1
Memory Map Display . . . . . . . . . . . . . . . . . . . . . . . . .
12.2.2
Options for Memory Map Display . . . . . . . . . . . . . . .
12.2.3
Options for Further Information . . . . . . . . . . . . . . . .
12.2.4
Requesting Traceback Information . . . . . . . . . . . . . . .
12.2.5
Correlating Traceback Information with Source Code
12.3
Adjusting Type Determination and Display . . . . . . . . . . .
12.3.1
Options for Further Information . . . . . . . . . . . . . . . .
12.3.2
Altering Type Determination . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
12–1
12–1
12–2
12–5
12–6
12–7
12–7
12–7
12–9
12–9
12–9
12–11
12–13
12–13
12–15
12–15
12–17
11.1
11.2
11.3
11.4
11.5
11.5.1
11.5.2
11.6
11.6.1
11.6.2
11.6.3
11.7
Introduction . . . . . . . . . . . . . . . . . . . . .
Installation of PC Client . . . . . . . . . . .
Primary Clients and Secondary Clients
The PC Client Workspace . . . . . . . . . .
Establishing a Server Connection . . . .
Choosing a Transport . . . . . . . . . . .
Secondary Connections . . . . . . . . . .
Terminating a Server Connection . . . . .
Exiting Both Client and Server . . .
Exiting the Client Only . . . . . . . . .
Stopping Only the Server . . . . . . . .
Documentation . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Part V Advanced Topics
12 Using the Heap Analyzer
ix
12.3.3
Altering the Views-and-Types Display . . . . . . . . . . . . . . . . . . . . . . . . .
12.3.3.1
Selecting the Scope of Your Change . . . . . . . . . . . . . . . . . . . . . . . .
12.3.3.2
Choosing a Display Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.4
Exiting the Heap Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.5
Sample Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.5.1
Isolating Display of Interactive Command . . . . . . . . . . . . . . . . . . . . . .
12.5.2
Adjusting Type Determination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.5.3
Requesting Traceback Information . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12.5.4
Correlating Traceback with Source Code . . . . . . . . . . . . . . . . . . . . . . .
12.5.5
Locating an Allocation Error in Source Code . . . . . . . . . . . . . . . . . . . .
12–19
12–19
12–21
12–23
12–23
12–23
12–24
12–25
12–26
12–27
13 Additional Convenience Features
13.1
13.1.1
13.1.2
13.2
13.3
13.4
13.4.1
13.4.2
13.4.3
13.5
13.5.1
13.5.2
13.6
13.6.1
13.6.2
13.6.3
13.6.4
13.6.5
13.7
Using Debugger Command Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passing Parameters to Command Procedures . . . . . . . . . . . . . . . . . . .
Using a Debugger Initialization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging a Debugging Session into a File . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Symbols for Commands, Address Expressions, and Values . . . . .
Defining Symbols for Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining Symbols for Address Expressions . . . . . . . . . . . . . . . . . . . . . .
Defining Symbols for Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Commands to Function Keys . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced Techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Control Structures to Enter Commands . . . . . . . . . . . . . . . . . . . . . .
FOR Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IF Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REPEAT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WHILE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXITLOOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Routines Independently of Program Execution . . . . . . . . . . . . . . .
13–1
13–1
13–2
13–4
13–5
13–6
13–6
13–7
13–7
13–8
13–8
13–9
13–9
13–10
13–10
13–10
13–10
13–10
13–11
14 Debugging Special Cases
14.1
Debugging Optimized Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.1.1
Eliminated Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.1.2
Changes in Coding Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.1.3
Semantic Stepping (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.1.4
Use of Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.1.5
Split-Lifetime Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.2
Debugging Screen-Oriented Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.2.1
Setting the Protection to Allocate a Terminal . . . . . . . . . . . . . . . . . . .
14.3
Debugging Multilanguage Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.1
Controlling the Current Debugger Language . . . . . . . . . . . . . . . . . . . .
14.3.2
Specific Differences Among Languages . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.1
Default Radix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.2
Evaluating Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.3
Arrays and Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.4
Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.5
Initialization Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.3.2.6
Predefined Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.4
Recovering from Stack Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.5
Debugging Exceptions and Condition Handlers . . . . . . . . . . . . . . . . . . . . .
x
14–1
14–2
14–4
14–4
14–8
14–8
14–12
14–13
14–14
14–14
14–15
14–15
14–15
14–16
14–16
14–17
14–17
14–17
14–18
14.5.1
Setting Breakpoints or Tracepoints on Exceptions . . . . . . . . . . . . . . . .
14.5.2
Resuming Execution at an Exception Breakpoint . . . . . . . . . . . . . . . .
14.5.3
Effect of the Debugger on Condition Handling . . . . . . . . . . . . . . . . . . .
14.5.3.1
Primary Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.5.3.2
Secondary Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.5.3.3
Call-Frame Handlers (Application-Declared) . . . . . . . . . . . . . . . . .
14.5.3.4
Final and Last-Chance Handlers . . . . . . . . . . . . . . . . . . . . . . . . . .
14.5.4
Exception-Related Built-In Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.6
Debugging Exit Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.7
Debugging AST-Driven Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.7.1
Disabling and Enabling the Delivery of ASTs . . . . . . . . . . . . . . . . . . .
14.8
Debugging Translated Images (Alpha and Integrity servers Only) . . . . . . .
14.9
Debugging Programs That Perform Synchronization or Communication
Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14.10 Debugging Inlined Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14–18
14–19
14–21
14–21
14–21
14–21
14–22
14–23
14–23
14–24
14–24
14–24
14–25
14–25
15 Debugging Multiprocess Programs
15.1
Basic Multiprocess Debugging Techniques . . . . . . . . . . . . . . . . . . . . . . . . .
15.1.1
Starting a Multiprocess Debugging Session . . . . . . . . . . . . . . . . . . . . .
15.2
Obtaining Information About Processes . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.3
Process Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.4
Process Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.5
Debugger Prompts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.6
Process-Sensitive Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.7
Visible Process and Process-Sensitive Commands . . . . . . . . . . . . . . . . . . .
15.8
Controlling Process Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.8.1
WAIT Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.8.2
Interrupt Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.8.3
STOP Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.9
Connecting to Another Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.10 Connecting to a Spawned Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.11 Monitoring the Termination of Images . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.12 Releasing a Process From Debugger Control . . . . . . . . . . . . . . . . . . . . . . .
15.13 Terminating Specified Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.14 Interrupting Program Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.15 Ending the Debugging Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16 Supplemental Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16.0.1
Process Relationships When Debugging . . . . . . . . . . . . . . . . . . . . .
15.16.1
Specifying Processes in Debugger Commands . . . . . . . . . . . . . . . . . . .
15.16.2
Monitoring Process Activation and Termination . . . . . . . . . . . . . . . . .
15.16.3
Interrupting the Execution of an Image to Connect It to the
Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16.4
Screen Mode Features for Multiprocess Debugging . . . . . . . . . . . . . . .
15.16.5
Setting Watchpoints in Global Sections (Alpha and Integrity servers
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16.6
System Requirements for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16.6.1
User Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.16.6.2
System Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15.17 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15–1
15–1
15–2
15–4
15–5
15–6
15–6
15–7
15–7
15–7
15–8
15–8
15–9
15–9
15–10
15–10
15–11
15–11
15–11
15–12
15–12
15–13
15–14
15–14
15–15
15–15
15–16
15–16
15–17
15–17
xi
16 Debugging Tasking Programs
16.1
Comparison of POSIX Threads and Ada Terminology . . . . . . . . . . . . . . . .
16.2
Sample Tasking Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.2.1
Sample C Multithread Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.2.2
Sample Ada Tasking Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3
Specifying Tasks in Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . .
16.3.1
Definition of Active Task and Visible Task . . . . . . . . . . . . . . . . . . . . . .
16.3.2
Ada Tasking Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3.3
Task ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3.4
Task Built-In Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.3.4.1
Caller Task Symbol (Ada Only) . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.4
Displaying Information About Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.4.1
Displaying Information About POSIX Threads Tasks . . . . . . . . . . . . .
16.4.2
Displaying Task Information About Ada Tasks . . . . . . . . . . . . . . . . . .
16.5
Changing Task Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.5.1
Putting Tasks on Hold to Control Task Switching . . . . . . . . . . . . . . . .
16.6
Controlling and Monitoring Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.6.1
Setting Task-Specific and Task-Independent Debugger
Eventpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.6.2
Setting Breakpoints on POSIX Threads Tasking Constructs . . . . . . . .
16.6.3
Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept
Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.6.4
Monitoring Task Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.7
Additional Task-Debugging Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16.7.1
Debugging Programs with Deadlock Conditions . . . . . . . . . . . . . . . . . .
16.7.2
Automatic Stack Checking in the Debugger . . . . . . . . . . . . . . . . . . . . .
16.7.3
Using Ctrl/Y When Debugging Ada Tasks . . . . . . . . . . . . . . . . . . . . . .
16–2
16–2
16–3
16–7
16–10
16–11
16–11
16–13
16–14
16–15
16–15
16–15
16–19
16–24
16–24
16–25
16–25
16–26
16–26
16–28
16–31
16–31
16–33
16–33
VI Debugger Command Dictionary
1
2
2.1
2.2
2.3
3
4
5
xii
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Command Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entering Commands at the Keyboard . . . . . . . . . . . . . . . . . . . .
Entering Commands in Command Procedures . . . . . . . . . . . . . .
Commands Disabled in the Debugger’s HP DECwindows Motif for
OpenVMS User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Diagnostic Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Command Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . .
@ (Execute Procedure) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACTIVATE BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACTIVATE TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ACTIVATE WATCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ANALYZE/CRASH_DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ANALYZE/PROCESS_DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL ALL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CANCEL RADIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. DEBUG–3
. DEBUG–3
. DEBUG–3
. DEBUG–4
. DEBUG–4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. DEBUG–5
. DEBUG–5
. DEBUG–6
. DEBUG–7
. DEBUG–9
. DEBUG–12
. DEBUG–14
. DEBUG–15
. DEBUG–17
. DEBUG–19
. DEBUG–20
. DEBUG–25
. DEBUG–27
. DEBUG–30
. DEBUG–31
. DEBUG–32
CANCEL SCOPE . . . . . . . . . . . . . . . . . . . . . .
CANCEL SOURCE . . . . . . . . . . . . . . . . . . . .
CANCEL TRACE . . . . . . . . . . . . . . . . . . . . . .
CANCEL TYPE/OVERRIDE . . . . . . . . . . . . .
CANCEL WATCH . . . . . . . . . . . . . . . . . . . . .
CANCEL WINDOW . . . . . . . . . . . . . . . . . . . .
CONNECT . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ctrl/C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ctrl/W . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ctrl/Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ctrl/Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEACTIVATE BREAK . . . . . . . . . . . . . . . . . .
DEACTIVATE TRACE . . . . . . . . . . . . . . . . . .
DEACTIVATE WATCH . . . . . . . . . . . . . . . . . .
DECLARE . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE/KEY . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE/PROCESS_SET . . . . . . . . . . . . . . . .
DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE/KEY . . . . . . . . . . . . . . . . . . . . . . . .
DEPOSIT . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE AST . . . . . . . . . . . . . . . . . . . . . . . .
DISCONNECT . . . . . . . . . . . . . . . . . . . . . . . .
DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DUMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EDIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE AST . . . . . . . . . . . . . . . . . . . . . . . .
EVALUATE . . . . . . . . . . . . . . . . . . . . . . . . . .
EVALUATE/ADDRESS . . . . . . . . . . . . . . . . .
EXAMINE . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXITLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXPAND . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXTRACT . . . . . . . . . . . . . . . . . . . . . . . . . . .
FOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MONITOR . . . . . . . . . . . . . . . . . . . . . . . . . . .
MOVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PTHREAD . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REBOOT (Integrity servers and Alpha Only) .
REPEAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RERUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. DEBUG–33
. DEBUG–34
. DEBUG–38
. DEBUG–41
. DEBUG–42
. DEBUG–43
. DEBUG–44
. DEBUG–47
. DEBUG–49
. DEBUG–50
. DEBUG–52
. DEBUG–53
. DEBUG–55
. DEBUG–57
. DEBUG–58
. DEBUG–61
. DEBUG–63
. DEBUG–67
. DEBUG–70
. DEBUG–72
. DEBUG–74
. DEBUG–80
. DEBUG–81
. DEBUG–83
. DEBUG–89
. DEBUG–92
. DEBUG–94
. DEBUG–95
. DEBUG–98
. DEBUG–101
. DEBUG–112
. DEBUG–115
. DEBUG–116
. DEBUG–119
. DEBUG–121
. DEBUG–123
. DEBUG–125
. DEBUG–126
. DEBUG–127
. DEBUG–131
. DEBUG–133
. DEBUG–135
. DEBUG–138
. DEBUG–139
. DEBUG–140
. DEBUG–142
. DEBUG–144
xiii
SCROLL . . . . . . . . . . . . . . . . .
SEARCH . . . . . . . . . . . . . . . .
SDA . . . . . . . . . . . . . . . . . . . .
SELECT . . . . . . . . . . . . . . . . .
SET ABORT_KEY . . . . . . . . .
SET ATSIGN . . . . . . . . . . . . .
SET BREAK . . . . . . . . . . . . .
SET DEFINE . . . . . . . . . . . . .
SET EDITOR . . . . . . . . . . . . .
SET EVENT_FACILITY . . . . .
SET IMAGE . . . . . . . . . . . . . .
SET KEY . . . . . . . . . . . . . . . .
SET LANGUAGE . . . . . . . . . .
SET LANGUAGE/DYNAMIC .
SET LOG . . . . . . . . . . . . . . . .
SET MARGINS . . . . . . . . . . .
SET MODE . . . . . . . . . . . . . .
SET MODULE . . . . . . . . . . . .
SET OUTPUT . . . . . . . . . . . .
SET PROCESS . . . . . . . . . . .
SET PROMPT . . . . . . . . . . . .
SET RADIX . . . . . . . . . . . . . .
SET SCOPE . . . . . . . . . . . . . .
SET SEARCH . . . . . . . . . . . .
SET SOURCE . . . . . . . . . . . .
SET STEP . . . . . . . . . . . . . . .
SET TASK | THREAD . . . . . .
SET TERMINAL . . . . . . . . . .
SET TRACE . . . . . . . . . . . . . .
SET TYPE . . . . . . . . . . . . . . .
SET WATCH . . . . . . . . . . . . .
SET WINDOW . . . . . . . . . . . .
SHOW ABORT_KEY . . . . . . .
SHOW AST . . . . . . . . . . . . . .
SHOW ATSIGN . . . . . . . . . . .
SHOW BREAK . . . . . . . . . . .
SHOW CALLS . . . . . . . . . . . .
SHOW DEFINE . . . . . . . . . . .
SHOW DISPLAY . . . . . . . . . .
SHOW EDITOR . . . . . . . . . . .
SHOW EVENT_FACILITY . . .
SHOW EXIT_HANDLERS . . .
SHOW IMAGE . . . . . . . . . . . .
SHOW KEY . . . . . . . . . . . . . .
SHOW LANGUAGE . . . . . . . .
SHOW LOG . . . . . . . . . . . . . .
SHOW MARGINS . . . . . . . . .
xiv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. DEBUG–146
. DEBUG–149
. DEBUG–152
. DEBUG–154
. DEBUG–157
. DEBUG–159
. DEBUG–160
. DEBUG–169
. DEBUG–170
. DEBUG–172
. DEBUG–174
. DEBUG–176
. DEBUG–177
. DEBUG–179
. DEBUG–180
. DEBUG–181
. DEBUG–184
. DEBUG–188
. DEBUG–191
. DEBUG–193
. DEBUG–196
. DEBUG–197
. DEBUG–199
. DEBUG–203
. DEBUG–205
. DEBUG–209
. DEBUG–213
. DEBUG–217
. DEBUG–219
. DEBUG–226
. DEBUG–229
. DEBUG–236
. DEBUG–238
. DEBUG–239
. DEBUG–240
. DEBUG–241
. DEBUG–243
. DEBUG–246
. DEBUG–247
. DEBUG–249
. DEBUG–250
. DEBUG–251
. DEBUG–252
. DEBUG–254
. DEBUG–257
. DEBUG–258
. DEBUG–259
SHOW MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW MODULE . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW OUTPUT . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW PROCESS . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW RADIX . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SCOPE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SOURCE . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW STACK . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW SYMBOL . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW TASK | THREAD . . . . . . . . . . . . . . . . . . . .
SHOW TERMINAL . . . . . . . . . . . . . . . . . . . . . . . .
SHOW TRACE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW WATCH . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW WINDOW . . . . . . . . . . . . . . . . . . . . . . . . . .
SPAWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
START HEAP_ANALYZER (Integrity servers only)
STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SYMBOLIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WAIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WHILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. DEBUG–260
. DEBUG–261
. DEBUG–264
. DEBUG–265
. DEBUG–269
. DEBUG–270
. DEBUG–272
. DEBUG–273
. DEBUG–275
. DEBUG–277
. DEBUG–280
. DEBUG–281
. DEBUG–284
. DEBUG–288
. DEBUG–289
. DEBUG–291
. DEBUG–292
. DEBUG–293
. DEBUG–294
. DEBUG–296
. DEBUG–297
. DEBUG–303
. DEBUG–305
. DEBUG–307
. DEBUG–309
. DEBUG–310
DEFAULT, GOLD, BLUE Functions . . . . . . . . . . . .
Key Definitions Specific to LK201 Keyboards . . . . .
Keys That Scroll, Move, Expand, Contract Displays
Online Keypad Key Diagrams . . . . . . . . . . . . . . . . .
Debugger Key Definitions . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
A–1
A–3
A–3
A–4
A–5
SS$_DEBUG Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Built-In Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constructing Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Counting Parameters Passed to Command Procedures . . . . . . . . . . .
Determining the Debugger Interface (Command or HP DECwindows
Motif for OpenVMS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling the Input Radix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying Program Locations and the Current Value of an Entity . .
Using Symbols and Operators in Address Expressions . . . . . . . . . . .
Obtaining Information About Exceptions . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
B–1
B–1
B–3
B–4
B–8
B–8
.
.
.
.
.
B–8
B–9
B–9
B–10
B–13
A Predefined Key Functions
A.1
A.2
A.3
A.4
A.5
B Built-In Symbols and Logical Names
B.1
B.2
B.3
B.3.1
B.3.2
B.3.3
B.3.4
B.3.5
B.3.6
B.3.7
B.3.8
xv
B.3.9
Specifying the Current, Next, and Previous Scope on the Call
Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B–14
C Summary of Debugger Support for Languages
C.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.2
GNAT Ada (Integrity servers only) . . . . . . . . . . . . . . . . . . . . . . .
C.3
HP Ada (Alpha) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.1
Ada Names and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.1.1
Ada Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.1.2
Predefined Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.1.2.1
Specifying Attributes with Enumeration Types . . . . .
C.3.1.2.2
Resolving Overloaded Enumeration Literals . . . . . . .
C.3.2
Operators and Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.2.1
Operators in Language Expressions . . . . . . . . . . . . . . . . .
C.3.2.2
Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.4
Compiling and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.5
Source Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.6
EDIT Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.7
GO and STEP Commands . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.8
Debugging Ada Library Packages . . . . . . . . . . . . . . . . . . . . .
C.3.9
Predefined Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.10
Monitoring Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.10.1
Monitoring Any Exception . . . . . . . . . . . . . . . . . . . . . . . .
C.3.10.2
Monitoring Specific Exceptions . . . . . . . . . . . . . . . . . . . .
C.3.10.3
Monitoring Handled Exceptions and Exception Handlers
C.3.11
Examining and Manipulating Data . . . . . . . . . . . . . . . . . . . .
C.3.11.1
Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.11.2
Access Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.12
Module Names and Path Names . . . . . . . . . . . . . . . . . . . . . .
C.3.13
Symbol Lookup Conventions . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.14
Setting Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.3.14.1
Setting Modules for Package Bodies . . . . . . . . . . . . . . . .
C.3.15
Resolving Overloaded Names and Symbols . . . . . . . . . . . . . .
C.3.16
CALL Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4
BASIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . .
C.4.2
Constructs in Language and Address Expressions . . . . . . . . .
C.4.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.4
Compiling for Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.5
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.6
Evaluating Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.7
Line Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.8
Stepping into Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.4.9
Symbolic References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.5
BLISS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.5.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . .
C.5.2
Constructs in Language and Address Expressions . . . . . . . . .
C.5.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.6
C .................................................
C.6.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . .
C.6.2
Constructs in Language and Address Expressions . . . . . . . . .
C.6.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
xvi
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
C–1
C–2
C–2
C–2
C–3
C–3
C–4
C–5
C–5
C–5
C–6
C–7
C–7
C–8
C–9
C–9
C–10
C–10
C–11
C–11
C–12
C–12
C–13
C–13
C–14
C–15
C–15
C–16
C–17
C–17
C–17
C–18
C–18
C–18
C–19
C–19
C–19
C–19
C–19
C–19
C–20
C–20
C–20
C–21
C–22
C–22
C–22
C–23
C–24
Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Static and Nonstatic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scalar Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structures and Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C++ Version 5.5 and Later (Alpha and Integrity servers Only) . . . . . . . .
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Case Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Information About a Class . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Information About an Object . . . . . . . . . . . . . . . . . . . . . .
Setting Watchpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Limitations on Debugger Support for C++ . . . . . . . . . . . . . . . . . . . . .
COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COBOL INITIALIZE Statement and Large Tables (Arrays) (Alpha
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.9
Fortran . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.9.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
C.9.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
C.9.3
Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.9.4
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.9.5
Initialization Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10 MACRO–32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
C.10.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.4
MACRO–32 Compiler (AMACRO - Alpha Only; IMACRO - Integrity
servers Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.4.1
Code Relocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.4.2
Symbolic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.10.4.3
Locating Arguments Without $ARGn Symbols . . . . . . . . . . . . . .
C.10.4.4
Arguments That Are Easy to Locate . . . . . . . . . . . . . . . . . . . . . .
C.10.4.5
Arguments That Are Not Easy to Locate . . . . . . . . . . . . . . . . . . .
C.10.4.6
Debugging Code with Floating-Point Data . . . . . . . . . . . . . . . . . .
C.10.4.7
Debugging Code with Packed Decimal Data . . . . . . . . . . . . . . . .
C.11
MACRO–64 (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.11.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
C.11.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
C.11.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12 Pascal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . .
C.12.3
Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.4
Built-In Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.5
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.6
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.12.7
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.6.4
C.6.5
C.6.6
C.6.7
C.6.8
C.6.9
C.7
C.7.1
C.7.2
C.7.3
C.7.4
C.7.5
C.7.6
C.7.7
C.7.8
C.7.9
C.8
C.8.1
C.8.2
C.8.3
C.8.4
C.8.5
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
C–24
C–25
C–25
C–25
C–25
C–26
C–27
C–27
C–28
C–29
C–29
C–30
C–31
C–33
C–33
C–36
C–43
C–43
C–44
C–44
C–44
.
.
.
.
.
.
.
.
.
.
.
C–45
C–45
C–45
C–46
C–46
C–46
C–47
C–48
C–48
C–49
C–49
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
C–50
C–50
C–50
C–50
C–51
C–51
C–52
C–52
C–53
C–53
C–54
C–54
C–55
C–55
C–56
C–56
C–56
C–56
C–57
C–58
xvii
C.13 PL/I (Alpha Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . . .
C.13.3
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.4
Static and Nonstatic Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.5
Examining and Manipulating Data . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.5.1
EXAMINE Command Examples . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.13.5.2
Notes on Debugger Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.14 Language UNKNOWN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.14.1
Operators in Language Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.14.2
Constructs in Language and Address Expressions . . . . . . . . . . . . . . . .
C.14.3
Predefined Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C.14.4
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C–58
C–58
C–59
C–59
C–59
C–60
C–60
C–60
C–61
C–61
C–63
C–63
C–63
D EIGHTQUEENS.C
D.1
D.2
EIGHTQUEENS.C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8QUEENS.C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
D–1
D–3
Index
Examples
1–1
1–2
2–1
2–2
9–1
10–1
15–1
15–2
15–3
15–4
15–5
16–1
16–2
16–3
16–4
16–5
16–6
16–7
16–8
C–1
C–2
D–1
D–2
D–3
xviii
Compiling a Program with the /DEBUG Qualifier . . . . . . . . . . .
Linking a Program with the /DEBUG Qualifier . . . . . . . . . . . . .
Sample Program SQUARES . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Debugging Session Using Program SQUARES . . . . . . . .
Command Procedure SEPARATE_WINDOW.COM . . . . . . . . . . . .
System Default Debugger Resource File
(DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT)
...................................................
RUN/NEW Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW PROCESS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Process Specification Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . .
server.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
client.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample C Multithread Program . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Ada Tasking Program . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample SHOW TASK/ALL Display for POSIX Threads Tasks . . .
Sample SHOW TASK/FULL Display for a POSIX Threads Task .
Sample SHOW TASK/STAT/FULL Display for POSIX Threads
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample SHOW TASK/ALL Display for Ada Tasks . . . . . . . . . . . .
Sample SHOW TASK/FULL Display for an Ada Task . . . . . . . . .
Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks
C++ Example Program CXXDOCEXAMPLE.C . . . . . . . . . . . . . .
C++ Debugging Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Single-Module Program EIGHTQUEENS.C . . . . . . . . . . . . . . . . .
Main Module 8QUEENS.C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Submodule 8QUEENS_SUB.C . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1–5
1–6
2–16
2–16
9–11
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10–36
15–1
15–3
15–4
15–17
15–18
16–3
16–7
16–15
16–17
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
16–19
16–20
16–21
16–22
C–37
C–38
D–1
D–3
D–3
Figures
2–1
2–2
7–1
7–2
7–3
8–1
8–2
8–3
8–4
8–5
8–6
8–7
8–8
8–9
9–1
9–2
9–3
9–4
9–5
9–6
9–7
9–8
9–9
10–1
10–2
10–3
10–4
10–5
10–6
10–7
10–8
10–9
10–10
10–11
10–12
10–13
10–14
10–15
10–16
10–17
10–18
10–19
10–20
10–21
Keypad Key Functions Predefined by the Debugger—Command
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Screen Mode Display Configuration . . . . . . . . . . . . . . . .
Default Screen Mode Display Configuration . . . . . . . . . . . . . . . .
Screen Mode Source Display When Source Code Is Not Available
Screen Mode Instruction Display (VAX Example) . . . . . . . . . . . .
Debugger Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menus on Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Buttons in the Push Button View . . . . . . . . . . . . . . . . . .
Debugger Main Window and the Optional Views Window . . . . .
Monitor, Breakpoint, and Register Views . . . . . . . . . . . . . . . . . .
Instruction View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Thread View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menus on Optional Views Window . . . . . . . . . . . . . . . . . . . . . . .
Entering Commands at the Prompt . . . . . . . . . . . . . . . . . . . . . . .
Debugger at Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running a Program by Specifying an Image . . . . . . . . . . . . . . . .
Running a Program by Specifying a Command Symbol . . . . . . .
Source Display at Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rerunning the Same Program . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Server Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . .
Server Options Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Active Sessions List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Confirm Exit Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Source Code of Another Routine . . . . . . . . . . . . . . . .
Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting a Breakpoint on a Source Line . . . . . . . . . . . . . . . . . . . .
Setting a Breakpoint on a Routine . . . . . . . . . . . . . . . . . . . . . . . .
Setting a Conditional Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . .
Setting an Action Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying the Value of an Integer Variable . . . . . . . . . . . . . . . .
Displaying the Value of an Array Aggregate . . . . . . . . . . . . . . . .
Displaying the Value of an Array Element . . . . . . . . . . . . . . . . .
Typecasting the Value of a Variable . . . . . . . . . . . . . . . . . . . . . . .
Changing the Value of a Variable . . . . . . . . . . . . . . . . . . . . . . . . .
Monitoring a Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Expanded Aggregate Variable (Array) in Monitor View . . . . . . .
Pointer Variable and Referenced Object in Monitor View . . . . . .
Watched Variable in Monitor View . . . . . . . . . . . . . . . . . . . . . . . .
Changing the Value of a Monitored Scalar Variable . . . . . . . . . . .
Changing the Value of a Component of an Aggregate Variable . .
Current Scope Set to a Calling Routine . . . . . . . . . . . . . . . . . . . .
Register View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Instruction View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2–3
2–5
7–2
7–14
7–17
8–5
8–6
8–9
8–11
8–12
8–12
8–13
8–13
8–16
9–2
9–3
9–3
9–4
9–6
9–15
9–15
9–17
9–17
10–2
10–4
10–6
10–11
10–12
10–14
10–15
10–17
10–18
10–18
10–19
10–19
10–21
10–21
10–22
10–22
10–23
10–24
10–26
10–27
10–28
xix
10–22
10–23
10–24
12–1
12–2
12–3
12–4
12–5
12–6
12–7
12–8
12–9
12–10
12–11
12–12
12–13
12–14
12–15
16–1
A–1
Thread View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the STEP Button Label to an Icon . . . . . . . . . . . . . . .
Adding a Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Pull-Down Menus . . . . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Context-Sensitive Pop-Up Menus . . . . . . . . . . . .
Heap Analyzer Control Panel . . . . . . . . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Display Menu and Zoom Menu . . . . . . . . . . . . .
Heap Analyzer Memory Map Context-Sensitive Pop-Up Menu .
Heap Analyzer Information and Source Windows . . . . . . . . . . .
Heap Analyzer Type Histogram . . . . . . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Do-Not-Use Type List . . . . . . . . . . . . . . . . . . . .
Heap Analyzer Views-and-Types Hierarchy . . . . . . . . . . . . . . . .
Heap Analyzer Views-and-Types Display Options . . . . . . . . . . .
Incrementing Memory Allocation Indicates a Memory Leak . . .
The Do-Not-Use Type Menu Item Redefines Segment Type . . . .
The Click on Traceback Entry Shows Associated Source Code . .
Review of Source Code Shows Double Allocation . . . . . . . . . . . .
Diagram of a Task Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keypad Key Functions Predefined by the Debugger—Command
Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
10–29
10–33
10–34
12–4
12–5
12–6
12–8
12–10
12–12
12–14
12–16
12–18
12–20
12–22
12–24
12–25
12–26
12–27
16–18
.....
A–2
Tables
1–1
4–1
4–2
4–3
5–1
5–2
7–1
7–2
7–3
8–1
8–2
8–3
8–4
8–5
8–6
8–7
15–1
15–2
16–1
16–2
xx
Controlling Debugger Activation with the LINK and RUN
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Symbols for Alpha Registers . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Symbols for Integrity server Registers . . . . . . . . . . . . . . . . .
SET TYPE Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compiler Options for DST Symbol Information . . . . . . . . . . . . . . . . . .
Effect of Compiler and Linker on DST and GST Symbol
Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Register Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menus on Main Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displays in Register View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default Buttons in the Push Button View . . . . . . . . . . . . . . . . . . . . . .
Optional Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menus on Optional Views Window . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keypad Definitions in the HP DECwindows Motif for OpenVMS
Debugger Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugger Commands Not Available in the HP DECwindows Motif for
OpenVMS User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Process Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comparison of POSIX Threads and Ada Terminology . . . . . . . . . . . . .
Task Built-In Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1–7
4–23
4–24
4–29
5–3
5–4
7–7
7–12
7–27
8–7
8–8
8–9
8–10
8–14
8–16
8–17
15–3
15–13
16–2
16–14
Generic Task States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
POSIX Threads Task Substates . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ada Task Substates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generic Low-Level Task Scheduling Events . . . . . . . . . . . . . . . . . . .
POSIX Threads-Specific Events . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ada-Specific Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ada Tasking Deadlock Conditions and Debugger Commands for
Diagnosing Them . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG–1 Debugging States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A–1
Key Definitions Specific to LK201 Keyboards . . . . . . . . . . . . . . . . .
A–2
Keys That Change the Key State . . . . . . . . . . . . . . . . . . . . . . . . . . .
A–3
Keys That Invoke Online Help to Display Keypad Diagrams . . . . . .
A–4
Debugger Key Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B–1
Debugger Symbols for Alpha Registers (Alpha Only) . . . . . . . . . . . .
B–2
Debugger Symbols for Integrity server Registers (Integrity servers
Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
16–3
16–4
16–5
16–6
16–7
16–8
16–9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
16–32
. DEBUG–267
.
A–3
.
A–4
.
A–5
.
A–5
.
B–4
..
16–16
16–17
16–20
16–28
16–29
16–29
B–5
xxi
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 I introduces the OpenVMS Debugger. Part I contains one chapter:
–
•
•
Chapter 1 introduces the debugger.
Part II describes the debugger’s command interface. Part II 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 III describes the debugger’s HP DECwindows Motif for OpenVMS user
interface. Part III includes the following chapters:
–
Chapter 8 gives an overview of its HP DECwindows Motif for OpenVMS
user interface features.
xxiii
•
–
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 IV describes the debugger’s PC interface. Part IV contains one chapter:
–
•
•
Chapter 11 gives an overview of the debugger’s PC interface.
Part V describes advanced debugging topics. Part V 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 VI 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.
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:
•
The debugger’s online help system (see Section 2.1)
•
The documentation supplied with that language, particularly regarding
compiling and linking the program for debugging
•
The VAX MACRO and Instruction Set Reference Manual or the MACRO–64
Assembler for OpenVMS AXP Systems Reference Manual for information
about assembly-language instructions and the MACRO assembler
Linker Utility
For information about the linking of programs or shareable images, see the
OpenVMS Linker Utility Manual.
xxiv
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
See the OVMS_ALPHA_SYS_ANALYS_TLS_MAN for information on debugging
operating system code. This manual describes how to activate the OpenVMS
System-Code Debugger through the OpenVMS Debugger, and debug within the
OpenVMS System-Code Debugger environment.
For information on the OpenVMS System-Code Debugger-specific commands, see
the CONNECT and REBOOT commands in Part VI.
HP DECwindows Motif for OpenVMS
For general information about the HP DECwindows Motif for OpenVMS user
interface, see the Using DECwindows Motif for OpenVMS.
For additional information about HP OpenVMS products and services, visit the
following World Wide Web address:
http://www.hp.com/go/openvms
Reader’s Comments
HP welcomes your comments on this manual. Please send comments to:
[email protected]
How to Order Additional Documentation
For information about how to order additional documentation, visit the following
World Wide Web address:
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,
xxv
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.
...
xxvi
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.
xxvii
Part I
Introduction to the Debugger
This part introduces the Debugger.
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
Introduction to the Debugger
1.1 Overview of the 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-321
MACRO–64
Pascal
PL/I
1 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-321
IMACRO
PASCAL
1 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.
1–2
Introduction to the Debugger
1.1 Overview of the Debugger
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.
1–3
Introduction to the Debugger
1.1 Overview of the Debugger
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.
1–4
Introduction to the Debugger
1.1 Overview of the Debugger
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.
1.2 Preparing an Executable Image for Debugging
To take full advantage of symbolic debugging, you must first compile and link the
program’s modules (compilation units) using the compiler and linker /DEBUG
qualifiers as explained in Section 1.2.1 and Section 1.2.2.
1.2.1 Compiling a Program for Debugging
Example 1–1 shows how to compile (for debugging) a C program, FORMS.EXE,
that consists of two source modules: FORMS.C and INVENTORY.C. FORMS.C is
the main program module.
Example 1–1 Compiling a Program with the /DEBUG Qualifier
$ CC/DEBUG/NOOPTIMIZE INVENTORY,FORMS
Note that the /DEBUG and /NOOPTIMIZE qualifiers are compiler command
defaults for some languages. These qualifiers are used in the example for
emphasis. (For information about compiling programs in a specific language, see
the documentation for that language.)
The /DEBUG qualifier in the compiler command in Example 1–1 directs
the compiler to include the symbol information associated with FORMS.C
and INVENTORY.C in object modules FORMS.OBJ and INVENTORY.OBJ,
respectively. This enables you to refer to the symbolic names of variables,
routines, and other declared symbols while debugging the program. Only object
files created with the /DEBUG qualifier contain symbol information. You can
control whether to include all symbol information or only that required to trace
program flow (see Section 5.1.1).
1–5
Introduction to the Debugger
1.2 Preparing an Executable Image for Debugging
Some compilers optimize the object code to reduce the size of the program or
to make it run faster. In such cases the object code does not always match the
source code, which can make debugging more difficult. To avoid this, compile
the program with the /NOOPTIMIZE command qualifier (or equivalent). After
the nonoptimized program has been debugged, you can recompile and test it
again without the /NOOPTIMIZE qualifier to take advantage of optimization.
Section 14.1 describes some of the effects of optimization.
1.2.2 Linking a Program for Debugging
Example 1–2 shows how to link a C program, FORMS.EXE that consists of two
source modules: FORMS.C and INVENTORY.C. FORMS.C is the main program
module. Both source modules were compiled with the /DEBUG qualifier (see
Example 1–1).
Example 1–2 Linking a Program with the /DEBUG Qualifier
$ LINK/DEBUG FORMS,INVENTORY
In Example 1–2, the /DEBUG qualifier in the LINK command directs the linker
to include in the executable image all symbol information that is contained in the
object modules being linked. Most languages require that you specify all included
object modules in the LINK command. See Section 5.1.3 for more details on how
to control symbol information with the LINK command.
On Alpha and Integrity server systems, you can now debug programs that have
been linked with the /DSF qualifier (and therefore have a separate debug symbol
file). The /DSF qualifier 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:
•
The name of the .DSF file must match the name of the .EXE file being
debugged.
•
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
See Section 5.1.5 for more information about debugging programs that have
separate symbol files. See the OpenVMS Linker Utility Manual for more
information about using the /DSF qualifier.
1.2.3 Controlling Debugger Activation with the LINK and RUN Commands
In addition to passing symbol information to the executable image, the
LINK/DEBUG command causes the image activator to start the debugger if you
execute the resulting image with the DCL command RUN. (See Section 1.6.)
You can also run an image compiled and linked with the /DEBUG command
qualifiers without invoking the debugger. To do so, use the /NODEBUG qualifier
in the DCL command RUN. For example:
$ RUN/NODEBUG FORMS
1–6
Introduction to the Debugger
1.2 Preparing an Executable Image for Debugging
This is convenient for checking your program once you think it is error free. Note
that the data required by the debugger occupies space within the executable
image. When your program is correct, you can link your program again without
the /DEBUG qualifier. This creates an image with only traceback data in the
debug symbol table, which creates a smaller executable file.
Table 1–1 summarizes how to control debugger activation with the LINK and
RUN command qualifiers. Note that the LINK command qualifiers /[NO]DEBUG
and /[NO]TRACEBACK affect not only debugger activation but also the maximum
level of symbol information provided when debugging.
Table 1–1 Controlling Debugger Activation with the LINK and RUN Commands
LINK Command
Qualifier
To Run Program without
Debugger
To Run Program with
Debugger
Maximum Symbol
Information Available1
/DEBUG1
RUN/NODEBUG
RUN
Full
None or
/TRACEBACK or
/NODEBUG3
RUN
RUN/DEBUG
Only traceback4
/NOTRACEBACK
RUN
RUN/DEBUG5
None
/DSF6
RUN
DEBUG/KEEP7
6
RUN
/DSF
DEBUG/SERVER
Full
7
Full
1
On OpenVMS Alpha systems, anything that uses system service interception (SSI), such as the debugger or the Heap
Analyzer, is unable to intercept system service call images activated by shared linkage. The image activator, therefore,
avoids shared linkage for images linked or run with /DEBUG, and instead activates private image copies. This affects
performance of user applications under debugger or Heap Analyzer control, as images activated by shared linkage run
faster.
3 LINK/TRACEBACK (or LINK/NODEBUG) is a LINK command default.
4
Traceback information includes compiler-generated line numbers and the names of routines and modules (compilation
units). This symbol information is used by the traceback condition handler to identify the PC value (where execution is
paused) and the active calls when a run-time error has occurred. The information is also used by the debugger SHOW
CALLS command (see Section 2.3.3).
5
The RUN/DEBUG command allows you to run the debugger, but if you entered the LINK/NOTRACEBACK command,
you will be unable to do symbolic debugging.
6 Alpha
and Integrity server only.
7 Logical
name DBG$DSF_IMAGE_NAME must point to the directory that contains the .DSF file (see Section 1.2.2).
1.3 Debugging a Program with the Kept Debugger
You can run the OpenVMS Debugger as the kept debugger, which allows you
to rerun the same program again and again, or to run different programs, all
without terminating the debugging session. This section explains how to:
•
Start the kept debugger and then bring a program under debugger control
•
Rerun the same program from the current debugging session
•
Run another program from the current debugging session
•
Interrupt program execution and abort debugger commands
•
Interrupt a debugging session and then return to the debugging session
1–7
Introduction to the Debugger
1.3 Debugging a Program with the Kept Debugger
1.3.1 Starting the Kept Debugger
This section explains how to start the kept debugger from DCL level ( $ ) and
bring your program under debugger control. Section 1.6 and Section 1.7 describe
other ways to invoke the debugger.
Using the kept debugger enables you to use the debugger’s RERUN and RUN
features explained in Section 1.3.3 and Section 1.3.4, respectively.
Notes
The following problems or restrictions are specific to the kept debugger:
•
If a previous debugger process has not completely stopped, you may
see the following error at debugger startup:
%DEBUG-E-INTERR, internal debugger error in
DBGMRPC\DBG$WAIT_FOR_EVENT got an ACK
To fix this problem, exit the debugger. Then use the DCL command
SHOW PROCESS/SUBPROCESS to check whether any debugger
subprocesses exist. If so, stop them by using the DCL command STOP
and then restart the debugger.
•
Running a sequence of many large programs can cause the debugger
to fail because it has run out of memory, global sections, or some other
resource.
To fix this problem, exit the debugger and restart the debugging
session.
To start the kept debugger and bring your program under debugger control:
1. Verify that you have compiled and linked the program as explained in
Section 1.2.
2. Enter the following command line:
$ DEBUG/KEEP
Upon startup, the debugger displays its banner, executes any user-defined
initialization file (see Section 13.2), and displays its DBG> prompt to indicate
that you can now enter debugger commands, as explained in Section 2.1.
3. Bring your program under debugger control with the debugger RUN
command, specifying the executable image of your program as the parameter.
For example:
DBG> RUN FORMS
%DEBUG-I-INITIAL,Language: C, Module: FORMS
DBG>
The message displayed indicates that this debugging session is initialized for a C
program and that the name of the main program unit (the module containing the
image transfer address) is FORMS. 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. See Section 4.1.9 for
more information about language-dependent parameters.
1–8
Introduction to the Debugger
1.3 Debugging a Program with the Kept Debugger
The debugger suspends program execution (by setting a temporary breakpoint) at
the start of the main program unit or, with certain programs, at the start of some
initialization code, at which point the debugger displays the following message:
%DEBUG-I-NOTATMAIN, Type GO to reach main program
With some of these programs (for example, Ada programs), the temporary
breakpoint enables you to debug the initialization code using full symbolic
information. See Section 14.3 for more information.
At this point, you can debug your program as explained in Chapter 2.
RUN and RERUN Command Options for Programs That Require Arguments
Some programs require arguments. This section explains how to use the RUN
and RERUN commands with the /ARGUMENTS and /COMMAND qualifiers
when debugging a program with the kept debugger.
After starting the kept debugger, you can specify the image to be debugged
by entering the RUN command with an image name, or the RUN/COMMAND
command with a DCL foreign command. Note that you can specify a DCL foreign
command only with the /COMMAND qualifier to the RUN command.
You can specify a list of arguments with the /ARGUMENTS qualifier to the RUN
and RERUN commands.
The different methods are shown in the following example of a debugger session.
The program to be debugged is echoargs.c, a program that echoes the input
arguments to the terminal:
#include <stdio.h>
main(int argc, char *argv[])
{
int i;
for (i = 0; i < argc; i++)
printf("%s\n", argv[i]);
}
Compile and link the program as follows:
$ cc/debug/noopt echoargs.c
$ link/debug echoargs
Define a DCL foreign command as follows:
$ ECHO == "$ sys$disk:[]echoargs.exe"
Invoke the kept debugger. The debugger session in the example that follows
shows three ways of passing arguments:
•
RUN with /COMMAND and /ARGUMENTS
•
RERUN with /ARGUMENTS
•
RUN with /ARGUMENTS and image name
RUN with /COMMAND and /ARGUMENTS This section of the debugger session
shows the use of the debugger RUN command with the /COMMAND and
/ARGUMENTS qualifiers. The /COMMAND qualifier specifies DCL foreign
command echo. The /ARGUMENTS qualifier specifies arguments fa sol la mi.
The first GO command executes the initialization code of echoargs.exe after which
the debugger suspends program execution at the temporary breakpoint at the
start of the program. The second GO command executes echoargs.exe, which
correctly echoes the arguments to the screen.
1–9
Introduction to the Debugger
1.3 Debugging a Program with the Kept Debugger
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG> RUN/COMMAND="echo"/ARGUMENTS="fa sol la mi"
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
fa
sol
la
mi
%DEBUG-I-EXITSTATUS,is ’%SYSTEM-S-NORMAL, Normal successful completion’
RERUN with /ARGUMENTS This section of the debugger session shows the
use of the RERUN command with the /ARGUMENTS qualifier to run the same
image again, with new arguments fee fii foo fum. (If you omit the /ARGUMENTS
qualifier, the debugger reruns the program with the arguments used previously.)
The first GO command executes the initialization code of echoargs.exe after which
the debugger suspends program execution at the temporary breakpoint at the
start of the program. The second GO command executes echoargs.exe, which
correctly echoes the arguments to the screen.
DBG> RERUN/ARGUMENTS="fee fii foo fum"
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
fee
fii
foo
fum
%DEBUG-I-EXITSTATUS,is ’%SYSTEM-S-NORMAL, Normal successful completion’
RUN with /ARGUMENTS and Image Name This section of the debugging
session uses the RUN command to invoke a fresh image of echoargs, with the
/ARGUMENTS qualifier to specify a new set of arguments a b c.
The first GO command executes the initialization code of echoargs.exe after which
the debugger suspends program execution at the temporary breakpoint at the
start of the program. The second GO command executes echoargs.exe, which
correctly echoes the arguments to the screen.
DBG> RUN/ARGUMENTS="a b c" echoargs
%DEBUG-I-NOTATMAIN,Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN,Type GO to reach main program
DBG> GO
break at routine ECHOARGS\main
1602: for (i = 0; i < argc; i++)
DBG> GO
_dsa1:[jones.test]echoargs.exe;2
a
b
c
%DEBUG-I-EXITSTATUS,is ’%SYSTEM-S-NORMAL, Normal successful completion’
DBG> quit
1–10
Introduction to the Debugger
1.3 Debugging a Program with the Kept Debugger
RUN Command Restrictions
Note the following restrictions about the debugger RUN command:
•
You can use the RUN command only if you started the debugger with the
DCL command DEBUG/KEEP.
•
You cannot use the RUN command to connect the debugger to a running
program (see Section 1.7).
•
Unless you are using the debugger client/server interface, you cannot run a
program under debugger control over a network link. See Section 9.9 and
Chapter 11 for more information about using the debugger client/server
interface.
1.3.2 When Your Program Completes Execution
When your program completes execution normally during a debugging session,
the debugger issues the following message:
%DEBUG-I-EXITSTATUS,is ’%SYSTEM-S-NORMAL, Normal successful completion’)
You then have the following options:
•
You can rerun your program from the same debugging session (see
Section 1.3.3).
•
You can run another program from the same debugging session (see
Section 1.3.4).
•
You can end the debugging session (see Section 1.8).
1.3.3 Rerunning the Same Program from the Kept Debugger
You can rerun the program currently under debugger control at any time during
a debugging session, provided you invoked the kept debugger as explained in
Section 1.3.1. Use the RERUN command. For example:
DBG> RERUN
%DEBUG-I-NOTATMAIN, Language: C, Module: ECHOARGS
%DEBUG-I-NOTATMAIN, Type GO to reach main program
DBG>
The RERUN command terminates the image you were debugging and brings a
fresh copy of that image under debugger control, pausing at the start of the main
source module as if you had used the RUN command (see Section 1.3.1).
When you use the RERUN command you can save the current state (activated or
deactivated) of any breakpoints, tracepoints, and static watchpoints. Note that
the state of a particular nonstatic watchpoint might not be saved, depending
on the scope of the variable being watched relative to the main program unit
(where execution restarts). RERUN/SAVE is the default. To clear all breakpoints
tracepoints, and watchpoints, enter RERUN/NOSAVE.
The RERUN command invokes 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, use the RUN command. To
rerun a program with new arguments, use the /ARGUMENTS qualifier (see RUN
and RERUN Command Options for Programs That Require Arguments).
1–11
Introduction to the Debugger
1.3 Debugging a Program with the Kept Debugger
1.3.4 Running Another Program from the Kept Debugger
You can bring another program under debugger control at any time during a
debugging session, provided you invoked the kept debugger as explained in
Section 1.3.1. Use the debugger RUN command. For example:
DBG> RUN TOTALS
%DEBUG-I-NOTATMAIN, Language: FORTRAN, Module: TOTALS
DBG>
The debugger loads the program and pauses execution at the start of the main
source module.
For more information about startup conditions and restrictions, see Section 1.3.1.
For information about all RUN command options, see the debugger RUN
command description.
1.4 Interrupting Program Execution and Aborting Debugger
Commands
If your program goes into an infinite loop during a debugging session so that
the debugger prompt does not reappear, press Ctrl/C. This interrupts program
execution and returns you to the debugger prompt (pressing Ctrl/C does not end
the debugging session). For example:
DBG> GO
.
.
.
Ctrl/C
DBG>
You can also press Ctrl/C to abort the execution of a debugger command. This is
useful if, for example, the debugger is displaying a long stream of data.
Pressing Ctrl/C when the program is not running or when the debugger is not
performing an operation has no effect.
If your program has a Ctrl/C AST (asynchronous system trap) service routine
enabled, use the SET ABORT_KEY command to assign the debugger’s abort
function to another Ctrl/key sequence. To identify the abort key that is currently
defined, enter the SHOW ABORT_KEY command.
Pressing Ctrl/Y from within a debugging session has the same effect as pressing
Ctrl/Y during the execution of a program. Control is returned to the DCL
command interpreter ($ prompt).
1.5 Pausing and Resuming a Debugging Session
The debugger SPAWN and ATTACH commands enable you to interrupt a
debugging session from the debugger prompt, enter DCL commands, and return
to the debugger prompt. These commands function essentially like the DCL
commands SPAWN and ATTACH:
1–12
•
Use the debugger SPAWN command to create a subprocess.
•
Use the debugger ATTACH command to attach to an existing process or
subprocess.
Introduction to the Debugger
1.5 Pausing and Resuming a Debugging Session
You can enter the SPAWN command with or without specifying a DCL command
as a parameter. If you specify a DCL command, it is executed in a subprocess
(if the DCL command invokes a utility, that utility is invoked in a subprocess).
Control returns to the debugging session when the DCL command terminates
(or when you exit the utility). The following example shows spawning the DCL
command DIRECTORY:
DBG> SPAWN DIR [JONES.PROJECT2]*.FOR
.
.
.
Control returned to process JONES_1
DBG>
The next example shows spawning the DCL command MAIL, which invokes the
Mail utility:
DBG> SPAWN MAIL
MAIL> READ/NEW
.
.
.
MAIL> EXIT
Control returned to process JONES_1
DBG>
If you enter the SPAWN command without specifying a parameter, a subprocess
is created, and you can then enter DCL commands. Either logging out of the
subprocess or attaching to the parent process (with the DCL command ATTACH)
returns you to the debugging session. For example:
DBG> SPAWN
$ RUN PROG2
.
.
.
$ ATTACH JONES_1
Control returned to process JONES_1
DBG>
If you plan to go back and forth several times between your debugging session
and a spawned subprocess (which might be another debugging session), use
the debugger ATTACH command to attach to that subprocess. Use the DCL
command ATTACH to return to the parent process. Because you do not create
a new subprocess every time you leave the debugger, you use system resources
more efficiently.
If you are running two debugging sessions simultaneously, you can define a new
debugger prompt for one of the sessions with the SET PROMPT command. This
helps you differentiate the sessions.
1.6 Starting the Debugger by Running a Program
You can bring your program under control of the non-kept debugger in one step
by entering the DCL command RUN filespec.
Note that when running the non-kept debugger, you cannot use the debugger
RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4,
respectively. To rerun the same program or run another program under debugger
control, you must first exit the debugger and start it again.
1–13
Introduction to the Debugger
1.6 Starting the Debugger by Running a Program
To start the non-kept debugger by running a program:
1. Verify that you have compiled and linked the program as explained in Section
1.2.1 and Section 1.2.2.
2. Enter the DCL command RUN filespec to start the debugger.
For example:
$ RUN FORMS
Debugger Banner and Version Number
%DEBUG-I-NOTATMAIN, Language: C, Module: FORMS
DBG>
Upon startup, the debugger displays its banner, executes any user-defined
initialization file, sets the language-dependent parameters to the source language
of the main program, suspends execution at the start of the main program, and
prompts for commands.
For more information about startup conditions, see Section 1.2.3 and
Section 1.3.1.
1.7 Starting the Debugger After Interrupting a Running Program
You can bring a program that is executing freely under debugger control. This is
useful either if you suspect that the program might be in an infinite loop or if you
see erroneous output.
To bring your program under debugger control:
1. Verify that you have compiled and linked the program as explained in
Section 1.2.
2. Enter the DCL command RUN/NODEBUG filespec to execute the program
without invoking the debugger.
3. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL
command interpreter.
4. Enter the DCL command DEBUG. This invokes the non-kept debugger.
For example:
$ RUN/NODEBUG FORMS
.
.
.
Ctrl/Y
Interrupt
$ DEBUG
Debugger Banner and Version Number
%DEBUG-I-NOTATMAIN, Language: C, Module: FORMS
DBG>
Upon startup, the debugger displays its banner, executes any user-defined
initialization file, sets the language-dependent parameters to the source language
of the module where execution is interrupted, and prompts for commands.
To know where the execution is interrupted, enter the SHOW CALLS command
to determine where execution is paused and to display the sequence of routine
calls on the call stack (the SHOW CALLS command is described in Section 2.3.3).
1–14
Introduction to the Debugger
1.7 Starting the Debugger After Interrupting a Running Program
Note that when running the non-kept debugger, you cannot use the debugger
RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4,
respectively. To rerun the same program or run another program under debugger
control, you must first exit the debugger and start it again.
For more information about startup conditions, see Section 1.2.3 and
Section 1.3.1.
1.8 Ending a Debugging Session
To end a debugging session in an orderly manner and return to DCL level, enter
EXIT or QUIT or press Ctrl/Z. For example:
DBG> EXIT
$
The QUIT command starts the debugger exit handlers to close log files, restores
the screen and keypad states, and so on.
The EXIT command and Ctrl/Z function identically. They perform the same
functions as the QUIT command, and additionally execute any exit handlers that
are declared in your program.
1.9 Debugging a Program on a Workstation Running DECwindows
Motif
If you are at a workstation running HP DECwindows Motif for OpenVMS, by
default the debugger starts up in the HP DECwindows Motif for OpenVMS user
interface, which is displayed on the workstation specified by the HP DECwindows
Motif for OpenVMS applicationwide logical name DECW$DISPLAY.
The logical name DBG$DECW$DISPLAY enables you to override the default to
display the debugger’s command interface in a DECterm window, along with any
program input/output (I/O).
To display the debugger’s command interface in a DECterm window:
1. Enter the following definition in the DECterm window from which you plan
to start the debugger:
$ DEFINE/JOB DBG$DECW$DISPLAY " "
You can specify one or more space characters between the quotation marks.
You should use a job definition for the logical name. If you use a process
definition, it must not have the CONFINE attribute.
2. Start the debugger in the usual way from that DECterm window (see
Section 1.3.1). The debugger’s command interface is displayed in the same
window.
For example:
$ DEFINE/JOB DBG$DECW$DISPLAY " "
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG>
You can now bring your program under debugger control as explained
in Section 1.3.1. For more information about the logical names
DBG$DECW$DISPLAY and DECW$DISPLAY, see Section 9.8.3.
1–15
Introduction to the Debugger
1.9 Debugging a Program on a Workstation Running DECwindows Motif
On a workstation running HP DECwindows Motif for OpenVMS, you can also
run the client/server configuration of the OpenVMS debugger. See Section 9.9 for
details.
1.10 Debugging a Program from a PC Running the Debug Client
The OpenVMS Debugger Version 7.2 and later features a client/server interface
that allows you to debug programs running on OpenVMS on Alpha from a PC
debug client interface running:
•
Microsoft Windows (Intel)
•
Microsoft Windows NT Version 3.51 or greater (Intel or Alpha)
Note
The client/server interface for OpenVMS Integrity server systems is
planned for a future release.
The OpenVMS client/server configuration allows the following:
•
Remote access to OpenVMS Debug servers from other OpenVMS systems or
from PCs running Windows 95 or Windows NT Version 3.51 or later
•
Client access to multiple servers, each running on the same or different
OpenVMS nodes
•
Multiple clients on different nodes to simultaneously connect to the same
server for teaching or team debugging
•
Debugging of multitier client/server applications that are distributed among
several mixed-platform systems
The client and server communicate using Distributed Computing
Environment/Remote Procedure Calls (DCE/RPC) over one of the following
transports:
•
TCP/IP
•
UDP
•
DECnet
To invoke the server on an OpenVMS node, enter the following command:
$ DEBUG/SERVER
The server displays its network binding strings. You must specify one of these
strings when you connect a HP DECwindows Motif for OpenVMS or Microsoft
Windows client to this server. For example:
$ DEBUG/SERVER
%DEBUG-I-SPEAK:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-AWAIT:
TCP/IP: YES, DECnet: YES, UDP: YES
Network Binding: ncacn_ip_tcp:16.32.16.138[1034]
Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001]
Network Binding: ncadg_ip_udp:16.32.16.138[1045]
Ready for client connection...
In the client’s Server Connection dialog box, enter the type of network protocol
(TCP/IP, DECnet, or UDP) and the corresponding network binding string (see
Section 9.9.4).
1–16
Introduction to the Debugger
1.10 Debugging a Program from a PC Running the Debug Client
Note
Messages and program output appear by default in the window in which
you start the server. You can redirect program output to another window
as required.
For more information about using the debug client interface, see Chapter 11.
1.11 Debugging Detached Processes That Run with No CLI
The design and implementation of the debugger’s HP DECwindows Motif for
OpenVMS user interface requires that the process being debugged have a
command line interpreter (CLI). To debug a detached process (such as a print
symbiont) that does not have a CLI, you must use the character-cell (screen
mode) interface to the debugger.
To do so, direct DBG$INPUT, DBG$OUTPUT and DBG$ERROR to a terminal
port that is not logged in. This allows the image to be debugged with the
standard character-cell interface on that terminal.
For example:
$
$
$
$
DEFINE/TABLE=GROUP DBG$INPUT TTA3:
DEFINE/TABLE=GROUP DBG$OUTPUT TTA3:
DEFINE/TABLE=GROUP DBG$ERROR TTA3:
START/QUEUE SYS$PRINT /PROCESSOR=dev:[dir]test_program
[Debugger starts up on logged-out terminal TTA3:]
1.12 Configuring Process Quotas for the Debugger
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.13 Debugger Command Summary
The following sections list all the debugger commands and any related DCL
commands in functional groupings, along with brief descriptions. During a
debugging session, you can get online help on all debugger commands and their
qualifiers by typing HELP at the debugger prompt (see Section 2.1).
1–17
Introduction to the Debugger
1.13 Debugger Command Summary
1.13.1 Starting and Ending a Debugging Session
The following commands start the debugger, bring a program under debugger
control, and interrupt and end a debugging session. Except where the DCL
commands RUN and DEBUG are indicated specifically, all commands are
debugger commands.
$DEBUG/KEEP
(DCL) Starts the kept debugger.
$RUN SYS$SHARE:DEBUGSHR.EXE
(DCL) Starts the kept debugger.
$DEBUG/SERVER
(DCL) Starts the debug server.
$DEBUG/CLIENT
(DCL) Starts the debug client.
$RUN SYS$SHARE:DEBUGUISHR.EXE
(DCL) Starts the debug client.
RUN filespec
Brings a program under debugger control.
RERUN
Reruns the program currently under debugger
control.
$RUN program-image
(DCL) If the specified image was linked
using LINK/DEBUG, starts the debugger
and also brings the image under debugger
control. When you start the debugger in this
manner, you cannot then use the debugger
RUN or RERUN commands. You can use
the /[NO]DEBUG qualifiers with the RUN
command to control whether the debugger is
started when the program is executed.
EXIT, Ctrl/Z
Ends a debugging session, executing all exit
handlers.
QUIT
Ends a debugging session without executing
any exit handlers declared in the program.
Ctrl/C
Aborts program execution or a debugger
command without interrupting the debugging
session.
(SET,SHOW) ABORT_KEY
(Assigns, identifies) the default Ctrl/C abort
function to another Ctrl/key sequence,
identifies the Ctrl/key sequence currently
defined for the abort function.
Ctrl/Y
$DEBUG
(DCL) Interrupts a program that is running
without debugger control and starts the
debugger.
ATTACH
Passes control of your terminal from the
current process to another process.
SPAWN
Creates a subprocess, which enables you to
execute DCL commands without ending a
debugging session or losing your debugging
context.
1.13.2 Controlling and Monitoring Program Execution
The following commands control and monitor program execution:
1–18
GO
Starts or resumes program execution
STEP
Executes the program up to the next line,
instruction, or specified instruction
(SET,SHOW) STEP
(Establishes, displays) the default qualifiers
for the STEP command
Introduction to the Debugger
1.13 Debugger Command Summary
(SET,SHOW,CANCEL) BREAK
(Sets, displays, cancels) breakpoints
(ACTIVATE,DEACTIVATE) BREAK
(Activates, deactivates) previously set
breakpoints
(SET,SHOW,CANCEL) TRACE
(Sets, displays, cancels) tracepoints
(ACTIVATE,DEACTIVATE) TRACE
(Activates, deactivates) previously set
tracepoints
(SET,SHOW,CANCEL) WATCH
(Sets, displays, cancels) watchpoints
(ACTIVATE,DEACTIVATE) WATCH
(Activates, deactivates) previously set
watchpoints
SHOW CALLS
Identifies the currently active routine calls
SHOW STACK
Gives additional information about the
currently active routine calls
CALL
Calls a routine
1.13.3 Examining and Manipulating Data
The following commands examine and manipulate data:
EXAMINE
Displays the value of a variable or the
contents of a program location
SET MODE [NO]OPERANDS
Controls whether the address and contents of
the instruction operands are displayed when
you examine an instruction
DEPOSIT
Changes the value of a variable or the
contents of a program location
DUMP
Displays the contents of memory in a manner
similar to the DCL command DUMP
EVALUATE
Evaluates a language or address expression
MONITOR
(Applies only to the debugger’s HP
DECwindows Motif for OpenVMS user
interface) Displays the current value of
a variable or language expression in the
monitor view of the HP DECwindows Motif for
OpenVMS user interface
1.13.4 Controlling Type Selection and Radix
The following commands control type selection and radix:
(SET,SHOW,CANCEL) RADIX
(Establishes, displays, restores) the radix for
data entry and display
(SET,SHOW,CANCEL) TYPE
(Establishes, displays, restores) the type for
program locations that are not associated with
a compiler-generated type
SET MODE [NO]G_FLOAT
Controls whether double-precision floatingpoint constants are interpreted as G_FLOAT
or D_FLOAT
1.13.5 Controlling Symbol Searches and Symbolization
The following commands control symbol searches and symbolization:
SHOW SYMBOL
Displays symbols in your program
(SET,SHOW,CANCEL) MODULE
Sets a module by loading its symbol
information into the debugger’s symbol table,
identifies, cancels a set module
1–19
Introduction to the Debugger
1.13 Debugger Command Summary
(SET,SHOW,CANCEL) IMAGE
Sets a shareable image by loading data
structures into the debugger’s symbol table,
identifies, cancels a set image
SET MODE [NO]DYNAMIC
Controls whether or not modules and
shareable images are set automatically when
the debugger interrupts execution
(SET,SHOW,CANCEL) SCOPE
(Establishes, displays, restores) the scope for
symbol searches
SYMBOLIZE
Converts a memory address to a symbolic
address expression
SET MODE [NO]LINE
Controls whether or not program locations
are displayed in terms of line numbers or
routine-name + byte offset
SET MODE [NO]SYMBOLIC
Controls whether or not program locations are
displayed symbolically or in terms of numeric
addresses
1.13.6 Displaying Source Code
The following commands control the display of source code:
TYPE
Displays lines of source code
EXAMINE/SOURCE
Displays the source code at the location
specified by the address expression
SEARCH
Searches the source code for the specified
string
(SET,SHOW) SEARCH
(Establishes, displays) the default qualifiers
for the SEARCH command
SET STEP [NO]SOURCE
Enables/disables the display of source code
after a STEP command has been executed or
at a breakpoint, tracepoint, or watchpoint
(SET,SHOW) MARGINS
(Establishes, displays) the left and right
margin settings for displaying source code
(SET,SHOW,CANCEL) SOURCE
(Creates, displays, cancels) a source directory
search list
1.13.7 Using Screen Mode
The following commands control screen mode and screen displays:
1–20
SET MODE [NO]SCREEN
Enables/disables screen mode
DISPLAY
Creates or modifies a display
SCROLL
Scrolls a display
EXPAND
Expands or contracts a display
MOVE
Moves a display across the screen
(SHOW,CANCEL) DISPLAY
(Identifies, deletes) a display
(SET,SHOW,CANCEL) WINDOW
(Creates, identifies, deletes) a window
definition
SELECT
Selects a display for a display attribute
SHOW SELECT
Identifies the displays selected for each of the
display attributes
SAVE
Saves the current contents of a display into
another display
Introduction to the Debugger
1.13 Debugger Command Summary
EXTRACT
Saves a display or the current screen state
into a file
(SET,SHOW) TERMINAL
(Establishes, displays) the terminal screen
height and width that the debugger uses when
it formats displays and other output
SET MODE [NO]SCROLL
Controls whether an output display is updated
line by line or once per command
Ctrl/W
DISPLAY/REFRESH
Refreshes the screen
1.13.8 Editing Source Code
The following commands control source editing from a debugging session:
EDIT
Starts an editor during a debugging session
(SET,SHOW) EDITOR
(Establishes, identifies) the editor started by
the EDIT command
1.13.9 Defining Symbols
The following commands define and delete symbols for addresses, commands, or
values:
DEFINE
Defines a symbol as an address, command, or
value
DELETE
Deletes symbol definitions
(SET,SHOW) DEFINE
(Establishes, displays) the default qualifier for
the DEFINE command
SHOW SYMBOL/DEFINED
Identifies symbols that have been defined with
the DEFINE command
1.13.10 Using Keypad Mode
The following commands control keypad mode and key definitions:
SET MODE [NO]KEYPAD
Enables/disables keypad mode
DEFINE/KEY
Creates key definitions
DELETE/KEY
Deletes key definitions
SET KEY
Establishes the key definition state
SHOW KEY
Displays key definitions
1.13.11 Using Command Procedures, Log Files, and Initialization Files
The following commands are used with command procedures and log files:
@ (execute procedure)
Executes a command procedure
(SET,SHOW) ATSIGN
(Establishes, displays) the default file
specification that the debugger uses to search
for command procedures
DECLARE
Defines parameters to be passed to command
procedures
(SET,SHOW) LOG
(Specifies, identifies) the debugger log file
SET OUTPUT [NO]LOG
Controls whether or not a debugging session
is logged
1–21
Introduction to the Debugger
1.13 Debugger Command Summary
SET OUTPUT [NO]SCREEN_LOG
Controls whether or not, in screen mode, the
screen contents are logged as the screen is
updated
SET OUTPUT [NO]VERIFY
Controls whether or not debugger commands
are displayed as a command procedure is
executed
SHOW OUTPUT
Identifies the current output options
established by the SET OUTPUT command
1.13.12 Using Control Structures
The following commands establish conditional and looping structures for debugger
commands:
FOR
Executes a list of commands while
incrementing a variable
IF
Executes a list of commands conditionally
REPEAT
Executes a list of commands a specified
number of times
WHILE
Executes a list of commands while a condition
is true
EXITLOOP
Exits an enclosing WHILE, REPEAT, or FOR
loop
1.13.13 Debugging Multiprocess Programs
The following commands debug multiprocess programs. Note that these
commands are specific to multiprocess programs. Many of the commands
listed under other categories have qualifiers or parameters that are specific
to multiprocess programs (for example, SET BREAK/ACTIVATING, EXIT
process-spec, DISPLAY/PROCESS=).
CONNECT
Brings a process under debugger control
DEFINE/PROCESS_SET
Assigns a symbolic name to a list of process
specifications
SET MODE [NO]INTERRUPT
Controls whether execution is interrupted in
other processes when it is paused in some
process
(SET,SHOW) PROCESS
Modifies the multiprocess debugging
environment, displays process information
WAIT
When debugging a multiprocess program,
controls whether the debugger waits until all
processes have stopped before prompting for
another command
1.13.14 Additional Commands
The following commands are used for miscellaneous purposes:
1–22
Introduction to the Debugger
1.13 Debugger Command Summary
HELP
Displays online help on debugger commands
and selected topics
ANALYZE/CRASH_DUMP
Opens a process dump for analysis with the
System Dump Debugger (SDD)
ANALYZE/PROCESS_DUMP
Opens a process dump for analysis with the
System Code Debugger (SCD)
(DISABLE,ENABLE,SHOW) AST
(Disables, enables) the delivery of ASTs in
the program, identifies whether delivery is
enabled or disabled
PTHREAD
Passes a command to the POSIX Threads
Debugger
(SET,SHOW) EVENT_FACILITY
(Establishes, identifies) the current run-time
facility for Ada, POSIX Threads, and SCAN
events
(SET,SHOW) LANGUAGE
(Establishes, identifies) the current language
SET OUTPUT [NO]TERMINAL
Controls whether debugger output, except
for diagnostic messages, is displayed or
suppressed
SET PROMPT
Specifies the debugger prompt
(SET,SHOW) TASK | THREAD
Modifies the tasking environment, displays
task information
SHOW EXIT_HANDLERS
Identifies the exit handlers declared in the
program
SHOW MODE
Identifies the current debugger modes
established by the SET MODE command
(for example, screen mode, step mode)
SHOW OUTPUT
Identifies the current output options
established by the SET OUTPUT command
1–23
Part II
Command Interface
This part describes the debugger’s command interface.
For information about the debugger’s DECwindows Motif user interface, see
Part III.
2
Getting Started with the Debugger
This chapter gives a tutorial introduction to the debugger’s command interface.
The way you use the debugger depends on several factors: the kind of program
you are working on, the kinds of errors you are looking for, and your own
personal style and experience with the debugger. This chapter explains the
following basic tasks that apply to most situations:
•
Entering debugger commands and getting online help
•
Viewing your source code with the TYPE command and in screen mode
•
Controlling program execution with the GO, STEP, and SET BREAK
commands, and monitoring execution with the SHOW CALLS, SET TRACE,
and SET WATCH commands
•
Examining and manipulating data with the EXAMINE, DEPOSIT, and
EVALUATE commands
•
Controlling symbol references with path names and the SET MODULE and
SET SCOPE commands
Several examples are language specific. However, the general concepts are
readily adaptable to all supported languages.
The sample debugging session in Section 2.6 shows how to use some of this
information to locate an error and correct it.
For information about starting and ending a debugging session, see Section 1.3.
2.1 Entering Debugger Commands and Accessing Online Help
After you start the debugger as explained in Section 1.3, you can enter debugger
commands whenever the debugger prompt (DBG>) is displayed. To enter a
command, type it at the keyboard and press Return. For example, the following
command sets a watchpoint on the variable COUNT:
DBG> SET WATCH COUNT
Detailed reference information about debugger commands is available in Part VI
and through the debugger’s online help:
•
To list the help topics, type HELP at the prompt.
•
For an explanation of the help system, type HELP HELP.
•
For complete rules on entering commands, type HELP Command_Format.
•
To display help on a particular command, type HELP command. For example,
to display HELP on the SET WATCH command, type HELP SET WATCH.
•
To list commands grouped by function, type HELP Command_Summary.
2–1
Getting Started with the Debugger
2.1 Entering Debugger Commands and Accessing Online Help
Online help is also available on the following topics:
New_Features
Release_Notes
Address_Expressions
Built_in_Symbols
DECwindows_Interface
Keypad_Definitions
Language_Support
Logical_Names
Messages (diagnostic messages)
Path_Names (to qualify symbolic names)
Screen_Mode
SS$_DEBUG condition (to start debugger from program)
System_Management
To display help about any of these topics, type HELP topic. For example, to
display information about diagnostic messages, type HELP Messages.
When you start the debugger, a few commonly used command sequences are
automatically assigned to the keys on the numeric keypad (to the right of the
main keyboard). Thus, you can perform certain functions either by entering a
command or by pressing a keypad key.
The predefined key functions are identified in Figure 2–1.
Most keypad keys have three predefined functions—DEFAULT, GOLD, and
BLUE.
•
To enter a key’s DEFAULT function, press the key.
•
To enter its GOLD function, first press and release the PF1 (GOLD) key, and
then press the key.
•
To enter its BLUE function, first press and release the PF4 (BLUE) key, and
then press the key.
In Figure 2–1, the DEFAULT, GOLD, and BLUE functions are listed within each
key’s outline, from top to bottom, respectively. For example:
•
Pressing KP0 (keypad key 0) enters the STEP command.
•
Pressing PF1 KP0 enters the STEP/INTO command.
•
Pressing PF4 KP0 enters the STEP/OVER command.
Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down, left,
right, or up, respectively. By putting the keypad in the MOVE, EXPAND, or
CONTRACT state, indicated in Figure 2–1, you can also use these keys to
move, expand, or contract displays in four directions. Enter the command
HELP Keypad_Definitions to display the keypad key definitions.
You can redefine keypad key functions with the DEFINE/KEY command.
2–2
Getting Started with the Debugger
2.1 Entering Debugger Commands and Accessing Online Help
Figure 2–1 Keypad Key Functions Predefined by the Debugger—Command Interface
F19
F18
F17
DEFAULT
(SCROLL)
MOVE
8
F20
EXPAND
(EXPAND +)
CONTRACT
(EXPAND −)
MOVE/UP
MOVE/UP:999
MOVE/UP:5
"MOVE"
4
PF1
PF2
GOLD
GOLD
GOLD
HELP DEFAULT
HELP GOLD
HELP BLUE
7
4
5
SCROLL/LEFT
SCROLL/LEFT:255
SCROLL/LEFT...
SET MODE SCREEN
SET MODE NOSCR
DISP/GENERATE
SCROLL/UP
SCROLL/TOP
SCROLL/UP...
EX/SOU .0\%PC
SHOW CALLS
SHOW CALLS 3
6
PF4
MOVE/LEFT
MOVE/LEFT:999
MOVE/LEFT:10
BLUE
BLUE
BLUE
DISPLAY next
SET PROC next
DISP 2 SRC
MOVE/DOWN
MOVE/DOWN:999
MOVE/DOWN:5
DISP next at FS
DISP SRC, OUT
,
6
SCROLL/RIGHT
SCROLL/RIGHT:255
SCROLL/RIGHT...
MOVE/RIGHT
MOVE/RIGHT:999
MOVE/RIGHT:10
2
−
9
8
DISP SRC,INST,OUT
DISP INST,REG,OUT
DISP 2 SRC, 2 INST
PF3
8
"EXPAND"
GO
SEL/SOURCE next
SEL/INST next
EXPAND/UP
EXPAND/UP:999
EXPAND/UP:5
4
1
2
3
EXAMINE
EXAM^(prev)
DISP 3 SRC, 3 INST
SCROLL/DOWN
SCROLL/BOTTOM
SCROLL/DOWN...
SEL SCROLL next
SEL OUTPUT next
DISP 3 SRC
.
0
STEP
STEP/INTO
STEP/OVER
6
ENTER
EXPAND/RIGHT
EXPAND/RIGHT:999
EXPAND/RIGHT:10
EXPAND/LEFT
EXPAND/LEFT:999
EXPAND/LEFT:10
2
ENTER
EXPAND/DOWN
EXPAND/DOWN:999
EXPAND/DOWN:5
RESET
RESET
RESET
8
"CONTRACT"
LK201 Keyboard:
Press
F17
F18
F19
F20
VT−100 Keyboard:
Type
SET KEY/STATE=DEFAULT
SET KEY/STATE=MOVE
SET KEY/STATE=EXPAND
SET KEY/STATE=CONTRACT
Keys 2,4,6,8
SCROLL
MOVE
EXPAND
CONTRACT
Keys 2,4,6,8
SCROLL
MOVE
EXPAND
CONTRACT
EXPAND/UP:−1
EXPAND/UP:−999
EXPAND/UP:−5
4
6
EXPAND/LEFT:−1
EXPAND/LEFT:−999
EXPAND/LEFT:−10
EXPAND/RIGHT:−1
EXPAND/RIGHT:−999
EXPAND/RIGHT:−10
2
EXPAND/DOWN:−1
EXPAND/DOWN:−999
EXPAND/DOWN:−5
ZK−0956A−GE
2–3
Getting Started with the Debugger
2.2 Displaying Source Code
2.2 Displaying Source Code
The debugger provides two modes for displaying information: noscreen mode
and screen mode. By default, when you start the debugger, you are in noscreen
mode, but you might find that it is easier to view source code in screen mode.
The following sections briefly describe both modes.
2.2.1 Noscreen Mode
Noscreen mode is the default, line-oriented mode of displaying input and output.
The interactive examples throughout this chapter, excluding Section 2.2.2, show
noscreen mode.
In noscreen mode, use the TYPE command to display one or more source lines.
For example, the following command displays line 7 of the module in which
execution is currently paused:
DBG> TYPE 7
module SWAP_ROUTINES
7:
TEMP := A;
DBG>
The display of source lines is independent of program execution. To display source
code from a module (compilation unit) other than the one in which execution is
currently paused, use the TYPE command with a path name to specify the
module. For example, the following command displays lines 16 to 21 of module
TEST:
DBG> TYPE TEST\16:21
Path names are discussed in more detail in Section 2.3.2, with the STEP
command.
You can also use the EXAMINE/SOURCE command to display the source line for
a routine or any other program location that is associated with an instruction.
The debugger also displays source lines automatically when it suspends execution
at a breakpoint or watchpoint, after a STEP command, or when a tracepoint is
triggered (see Section 2.3).
After displaying source lines at various locations in your program, you can
redisplay the location at which execution is currently paused by pressing KP5.
If the debugger cannot locate source lines for display, it issues a diagnostic
message. Source lines might not be available for a variety of reasons. For
example:
•
Execution is paused within a module that was compiled or linked without the
/DEBUG qualifier.
•
Execution is paused within a system or shareable image routine for which no
source code is available.
•
The source file was moved to a different directory after it was compiled (the
location of source files is embedded in the object modules). In this case, use
the SET SOURCE command to specify the new location.
•
The module might need to be set with the SET MODULE command. Module
setting is explained in Section 2.5.1.
To switch to noscreen mode from screen mode, press PF1 PF3 (or type SET
MODE NOSCREEN). You can use the TYPE and EXAMINE/SOURCE commands
in screen mode as well as noscreen mode.
2–4
Getting Started with the Debugger
2.2 Displaying Source Code
2.2.2 Screen Mode
Screen mode provides the easiest way to view your source code. To switch to
screen mode, press PF3 (or type SET MODE SCREEN). In screen mode, by
default the debugger splits the screen into three displays named SRC, OUT, and
PROMPT, as shown in Figure 2–2.
Figure 2–2 Default Screen Mode Display Configuration
SRC:
module SWAP_ROUTINES scroll−source
2: with Text_IO; use TEXT_IO;
3: package body SWAP_ROUTINES is
4:
procedure SWAP1 (A,B: in out INTEGER) is
5:
TEMP: INTEGER;
6:
begin
TEMP := A;
7:
> 8:
A := B;
B := TEMP;
9:
end;
10:
11:
procedure SWAP2 (A,B: in out COLOR) is
12:
OUT−output
stepped to SWAP_ROUTINES\SWAP1\%LINE 8
SWAP_ROUTINES\SWAP1\A: 35
PROMPT error−program−prompt
DBG> STEP
DBG> EXAMINE A
DBG>
ZK−6502−GE
The SRC display shows the source code of the module in which execution
is currently paused. An arrow in the left column points to the source line
corresponding to the current value of the program counter (PC). The PC is a
register that contains the memory address of the instruction to be executed next.
The line numbers, which are assigned by the compiler, match those in a listing
file. As you execute the program, the arrow moves down and the source code is
scrolled vertically to center the arrow in the display.
The OUT display captures the debugger’s output in response to the commands
that you enter. The PROMPT display shows the debugger prompt, your input (the
commands that you enter), debugger diagnostic messages, and program output.
You can scroll both SRC and OUT to see whatever information might scroll
beyond the display window’s edge. Press KP3 repeatedly as needed to select the
display to be scrolled (by default, SRC is scrolled). Press KP8 to scroll up and
KP2 to scroll down. Scrolling a display does not affect program execution.
In screen mode, if the debugger cannot locate source lines for the routine in which
execution is currently paused, it tries to display source lines in the next routine
down on the call stack for which source lines are available. If the debugger can
display source lines for such a routine, it issues the following message:
%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC.
Displaying source in a caller of the current routine.
DBG>
2–5
Getting Started with the Debugger
2.2 Displaying Source Code
In such cases, the arrow in the SRC display identifies the line that contains code
following the call statement in the calling routine.
2.3 Controlling and Monitoring Program Execution
This section explains how to perform the following tasks:
•
Start and resume program execution
•
Execute the program to the next source line, instruction, or other step unit
•
Determine where execution is currently paused
•
Use breakpoints to suspend program execution at points of interest
•
Use tracepoints to trace the execution path of your program through specified
locations
•
Use watchpoints to monitor changes in the values of variables
With this information you can pick program locations where you can then test
and manipulate the contents of variables as described in Section 2.4.
2.3.1 Starting or Resuming Program Execution
Use the GO command to start or resume program execution.
After it is started with the GO command, program execution continues until one
of the following events occurs:
•
The program completes execution
•
A breakpoint is reached
•
A watchpoint is triggered
•
An exception is signaled
•
You press Ctrl/C
With most programming languages, when you bring a program under debugger
control, execution is initially paused directly at the beginning of the main
program. Entering a GO command at this point quickly enables you to test for an
infinite loop or an exception.
If an infinite loop occurs during execution, the program does not terminate, so the
debugger prompt does not reappear. To obtain the prompt, interrupt execution by
pressing Ctrl/C (see Section 1.4). If you are using screen mode, the pointer in the
source display indicates where execution stopped. You can also use the SHOW
CALLS command to identify the currently active routine calls on the call stack
(see Section 2.3.3).
If an exception that is not handled by your program is signaled, the debugger
interrupts execution at that point so that you can enter commands. You can then
look at the source display and a SHOW CALLS display to find where execution is
paused.
The most common use of the GO command is in conjunction with breakpoints,
tracepoints, and watchpoints, as described in Section 2.3.4, Section 2.3.5, and
Section 2.3.6, respectively. If you set a breakpoint in the path of execution and
then enter the GO command, execution is paused at that breakpoint. Similarly, if
you set a tracepoint, execution is monitored through that tracepoint. If you set a
watchpoint, execution is paused when the value of the watched variable changes.
2–6
Getting Started with the Debugger
2.3 Controlling and Monitoring Program Execution
2.3.2 Executing the Program by Step Unit
Use the STEP command to execute the program one or more step units at a time.
By default, a step unit is one line of source code. In the following example, the
STEP command executes one line, reports the action ("stepped to . . . "), and
displays the line number (27) and source code of the line to be executed next:
DBG> STEP
stepped to TEST\COUNT\%LINE 27
27: X := X + 1;
DBG>
Execution is now paused at the first machine-code instruction for line 27 within
routine COUNT of module TEST.
When displaying a program symbol (for example, a line number, routine name, or
variable name), the debugger always uses a path name. A path name consists
of the symbol plus a prefix that identifies the symbol’s location. In the previous
example, the path name is TEST\COUNT\%LINE 27. The leftmost element of
a path name is the module name. Moving toward the right, the path name lists
any successively nested routines and blocks that enclose the symbol. A backslash
character ( \ ) is used to separate elements (except when the language is Ada,
where a period is used to parallel Ada syntax).
A path name uniquely identifies a symbol of your program to the debugger. In
general, you need to use path names in commands only if the debugger cannot
resolve a symbol ambiguity in your program (see Section 2.5). Usually the
debugger can determine the symbol you mean from its context.
When using the STEP command, note that only those source lines for which code
instructions were generated by the compiler are recognized as executable lines by
the debugger. The debugger skips over any other lines—for example, comment
lines.
You can specify different stepping modes, such as stepping by instruction rather
than by line (SET STEP INSTRUCTION). Also, by default, the debugger steps
over called routines—execution is not paused within a called routine, although
the routine is executed. By entering the SET STEP INTO command, you direct
the debugger to suspend execution within called routines as well as within the
routine in which execution is currently paused (SET STEP OVER is the default
mode).
2.3.3 Determining Where Execution Is Paused
Use the SHOW CALLS command when you are unsure where execution is paused
during a debugging session (for example, after a Ctrl/C interruption).
The command displays a traceback that lists the sequence of calls leading to the
routine in which execution is paused. For each routine (beginning with the one in
which execution is paused), the debugger displays the following information:
•
The name of the module that contains the routine
•
The name of the routine
•
The line number at which the call was made (or at which execution is paused,
in the case of the current routine)
•
The corresponding PC value
2–7
Getting Started with the Debugger
2.3 Controlling and Monitoring Program Execution
On Alpha and Integrity server processors, the PC is shown as a memory
address relative to the first code address in the module and also as an
absolute address.
Note that on Integrity server processors, there is no hardware PC register.
The PC is a software constructed value, built by adding the hardware
Instruction Pointer (IP) register and the slot offset of the instruction within
the bundle (0, 1, or 2).
For example:
DBG> SHOW CALLS
module name routine name
*TEST
*TEST
*MY_PROG
DBG>
PRODUCT
COUNT
MY_PROG
line
18
47
21
rel PC
abs PC
00000009 0000063C
00000009 00000647
0000000D 00000653
This example indicates that execution is paused at line 18 of routine PRODUCT
(in module TEST), which was called from line 47 of routine COUNT (in module
TEST), which was called from line 21 of routine MY_PROG (in module MY_
PROG).
2.3.4 Suspending Program Execution with Breakpoints
The SET BREAK command enables you to select locations at which to suspend
program execution (breakpoints). You can then enter commands to check the call
stack, examine the current values of variables, and so on. You resume execution
from a breakpoint with the GO or STEP commands.
The following example shows a typical use of the SET BREAK command:
DBG> SET BREAK COUNT
DBG> GO
.
.
.
break at routine PROG2\COUNT
54: procedure COUNT(X,Y:INTEGER);
DBG>
In the example, the SET BREAK command sets a breakpoint on routine COUNT
(at the beginning of the routine’s code); the GO command starts execution. When
routine COUNT is encountered, the following occurs:
•
Execution is paused.
•
The debugger announces that the breakpoint at COUNT has been reached
("break at . . . ").
•
The debugger displays the source line (54) at which execution is paused.
•
The debugger prompts for another command.
At this breakpoint, you can use the STEP command to step through routine
COUNT and then use the EXAMINE command (discussed in Section 2.4.1) to
check on the values of X and Y.
When using the SET BREAK command, you can specify program locations using
various kinds of address expressions (for example, line numbers, routine
names, memory addresses, byte offsets). With high-level languages, you typically
use routine names, labels, or line numbers, possibly with path names to ensure
uniqueness.
2–8
Getting Started with the Debugger
2.3 Controlling and Monitoring Program Execution
Specify routine names and labels as they appear in the source code. Line
numbers can be derived from either a source code display or a listing file.
When specifying a line number, use the prefix %LINE; otherwise, the debugger
interprets the line number as a memory location. For example, the following
command sets a breakpoint at line 41 of the module in which execution is paused.
The breakpoint causes the debugger to suspend execution at the beginning of
line 41.
DBG> SET BREAK %LINE 41
Note that you can set breakpoints only on lines that resulted in machine-code
instructions. The debugger warns you if you try to do otherwise (for example, on
a comment line). To pick a line number in a module other than the one in which
execution is paused, you must specify the module’s name in a path name. For
example:
DBG> SET BREAK SCREEN_IO\%LINE 58
You can also use the SET BREAK command with a qualifier, but no parameter, to
break on every line, or on every CALL instruction, and so on. For example:
DBG> SET BREAK/LINE
DBG> SET BREAK/CALL
You can set breakpoints on events, such as exceptions, or state transitions in
tasking programs.
You can conditionalize a breakpoint (with a WHEN clause) or specify that a list of
commands be executed at the breakpoint (with a DO clause).
To display the current breakpoints, enter the SHOW BREAK command.
To deactivate a breakpoint, enter the DEACTIVATE BREAK command, and
specify the program location exactly as you did when setting the breakpoint.
This causes the debugger to ignore the breakpoint during program execution.
However, you can activate it at a later time, for example, when you rerun the
program (see Section 1.3.3). A deactivated breakpoint is listed as such in a
SHOW BREAK display.
To activate a breakpoint, use the ACTIVATE BREAK command. Activating a
breakpoint causes it to take effect during program execution.
The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL operate
on all breakpoints and are particularly useful when rerunning a program.
To cancel a breakpoint, use the CANCEL BREAK command. A canceled
breakpoint is no longer listed in a SHOW BREAK display.
2.3.5 Tracing Program Execution with Tracepoints
The SET TRACE command enables you to select locations for tracing the
execution of your program (tracepoints), without stopping its execution. After
setting a tracepoint, you can start execution with the GO command and then
monitor the path of execution, checking for unexpected behavior. By setting a
tracepoint on a routine, you can also monitor the number of times it is called.
As with breakpoints, every time a tracepoint is reached, the debugger issues a
message and displays the source line. But the program continues executing, and
the debugger prompt is not displayed. For example:
2–9
Getting Started with the Debugger
2.3 Controlling and Monitoring Program Execution
DBG> SET TRACE COUNT
DBG> GO
trace at routine PROG2\COUNT
54: procedure COUNT(X,Y:INTEGER);
.
.
.
This is the only difference between a breakpoint and a tracepoint. When
using the SET TRACE command, you specify address expressions, qualifiers,
and optional clauses exactly as with the SET BREAK command. The
commands SHOW TRACE, ACTIVATE TRACE, DEACTIVATE TRACE, and
CANCEL TRACE operate on tracepoints in a manner similar to the corresponding
commands for breakpoints (see Section 2.3.4).
2.3.6 Monitoring Changes in Variables with Watchpoints
The SET WATCH command enables you to specify program variables that the
debugger monitors as your program executes. This process is called setting
watchpoints. If the program modifies the value of a watched variable, the
debugger suspends execution and displays information. The debugger monitors
watchpoints continuously during program execution. (Note that you can also
use the SET WATCH command to monitor arbitrary program locations, not just
variables.)
You can set a watchpoint on a variable by specifying the variable’s name with the
SET WATCH command. For example, the following command sets a watchpoint
on the variable TOTAL:
DBG> SET WATCH TOTAL
Subsequently, every time the program modifies the value of TOTAL, the
watchpoint is triggered.
Note
The technique you use to set watchpoints depends on your system (Alpha
or Integrity servers) and the type of variable, static or nonstatic. On
Alpha systems, for example, a static variable is associated with the
same memory address throughout program execution.
The following example shows what happens when your program modifies the
contents of this watched variable:
DBG> SET WATCH TOTAL
DBG> GO
.
.
.
watch of SCREEN_IO\TOTAL at SCREEN_IO\%LINE 13
13: TOTAL = TOTAL + 1;
old value: 16
new value: 17
break at SCREEN_IO\%LINE 14
14: POP(TOTAL);
DBG>
2–10
Getting Started with the Debugger
2.3 Controlling and Monitoring Program Execution
In this example, a watchpoint is set on the variable TOTAL and execution is
started. When the value of TOTAL changes, execution is paused. The debugger
announces the event ("watch of . . . "), identifying where TOTAL changed (the
beginning of line 13) and the associated source line. The debugger then displays
the old and new values and announces that execution has been paused at the
beginning of the next line (14). Finally, the debugger prompts for another
command. When a change in a variable occurs at a point other than the
beginning of a source line, the debugger gives the line number plus the byte
offset from the beginning of the line.
On Alpha processors, you can set a watchpoint on a nonstatic variable by
setting a tracepoint on the defining routine and specifying a DO clause to set
the watchpoint whenever execution reaches the tracepoint. Since a nonstatic
variable is allocated on the stack or in a register and exists only when its
defining routine is active (on the call stack), the variable name is not always
meaningful in the way that a static variable name is.
In the following example, a watchpoint is set on the nonstatic variable Y in
routine ROUT3. After the tracepoint is triggered, the WPTTRACE message
indicates that the nonstatic watchpoint is set, and the watchpoint is triggered
when the value of Y changes. For example:
DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y)
DBG> GO
.
.
.
trace at routine MOD4\ROUT3
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every
instruction
.
.
.
watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16
16:
Y := 4
old value:
3
new value:
4
break at MOD4\ROUT3\%LINE 17
17:
SWAP(X,Y);
DBG>
When execution returns to the calling routine, the nonstatic variable is no
longer active, so the debugger automatically cancels the watchpoint and issues a
message to that effect.
On Alpha processors and Integrity server, the debugger treats all watchpoints as
nonstatic
watchpoints.
The commands SHOW WATCH, ACTIVATE WATCH, DEACTIVATE WATCH,
and CANCEL WATCH operate on watchpoints in a manner similar to the
corresponding commands for breakpoints (see Section 2.3.4). However, a nonstatic
watchpoint exists only as long as execution remains within the scope of the
variable being watched.
2.4 Examining and Manipulating Program Data
This section explains how to use the EXAMINE, DEPOSIT, and EVALUATE
commands to display and modify the contents of variables and evaluate
expressions. Before you can examine or deposit into a nonstatic variable, as
defined in Section 2.3.6, its defining routine must be active.
2–11
Getting Started with the Debugger
2.4 Examining and Manipulating Program Data
2.4.1 Displaying the Value of a Variable
To display the current value of a variable, use the EXAMINE command. It has
the following syntax:
EXAMINE address-expression
The debugger recognizes the compiler-generated data type of the variable you
specify and retrieves and formats the data accordingly. The following examples
show some uses of the EXAMINE command.
Examine a string variable:
DBG> EXAMINE EMPLOYEE_NAME
PAYROLL\EMPLOYEE_NAME:
"Peter C. Lombardi"
DBG>
Examine three integer variables:
DBG> EXAMINE
SIZE\WIDTH:
SIZE\LENGTH:
SIZE\AREA:
DBG>
WIDTH, LENGTH, AREA
4
7
28
Examine a two-dimensional array of real numbers (three per dimension):
DBG> EXAMINE REAL_ARRAY
PROG2\REAL_ARRAY
(1,1):
27.01000
(1,2):
31.00000
(1,3):
12.48000
(2,1):
15.08000
(2,2):
22.30000
(2,3):
18.73000
DBG>
Examine element 4 of a one-dimensional array of characters:
DBG> EXAMINE CHAR_ARRAY(4)
PROG2\CHAR_ARRAY(4): ’m’
DBG>
Examine a record variable (COBOL example):
DBG> EXAMINE PART
INVENTORY\PART:
ITEM:
"WF-1247"
PRICE:
49.95
IN_STOCK: 24
DBG>
Examine a record component (COBOL example):
DBG> EXAMINE IN_STOCK OF PART
INVENTORY\IN-STOCK of PART:
IN_STOCK: 24
DBG>
You can use the EXAMINE command with any kind of address expression (not
just a variable name) to display the contents of a program location. The debugger
associates certain default data types with untyped locations. If you want the
data interpreted and displayed in some other data format you can override the
defaults for typed and untyped locations.
2–12
Getting Started with the Debugger
2.4 Examining and Manipulating Program Data
2.4.2 Assigning a Value to a Variable
To assign a new value to a variable, use the DEPOSIT command. It has the
following syntax:
DEPOSIT address-expression = language-expression
The DEPOSIT command is like an assignment statement in most programming
languages.
In the following examples, the DEPOSIT command assigns new values to
different variables. The debugger checks that the value assigned, which can be a
language expression, is consistent with the data type and dimensional constraints
of the variable.
Deposit a string value (it must be enclosed in quotation marks (") or apostrophes
(’):
DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84"
Deposit an integer expression:
DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10
Deposit element 12 of an array of characters (you cannot deposit an entire array
aggregate with a single DEPOSIT command, only an element):
DBG> DEPOSIT C_ARRAY(12) := ’K’
Deposit a record component (you cannot deposit an entire record aggregate with a
single DEPOSIT command, only a component):
DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172
Deposit an out-of-bounds value (X was declared as a positive integer):
DBG> DEPOSIT X = -14
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds
at or near DEPOSIT
As with the EXAMINE command, you can specify any kind of address expression
(not just a variable name) with the DEPOSIT command. You can override the
defaults for typed and untyped locations if you want the data interpreted in some
other data format.
2.4.3 Evaluating Language Expressions
To evaluate a language expression, use the EVALUATE command. It has the
following syntax:
EVALUATE language-expression
The debugger recognizes the operators and expression syntax of the currently
set language. In the following example, the value 45 is assigned to the integer
variable WIDTH; the EVALUATE command then obtains the sum of the current
value of WIDTH and 7:
DBG> DEPOSIT WIDTH := 45
DBG> EVALUATE WIDTH + 7
52
DBG>
2–13
Getting Started with the Debugger
2.4 Examining and Manipulating Program Data
In the next example, the values TRUE and FALSE are assigned to the Boolean
variables WILLING and ABLE, respectively; the EVALUATE command then
obtains the logical conjunction of these values:
DBG> DEPOSIT WILLING := TRUE
DBG> DEPOSIT ABLE := FALSE
DBG> EVALUATE WILLING AND ABLE
False
DBG>
2.5 Controlling Access to Symbols in Your Program
To have full access to the symbols that are associated with your program (variable
names, routine names, source code, line numbers, and so on), you must compile
and link the program using the /DEBUG qualifier, as explained in Section 1.2.
Under these conditions, the way in which the debugger handles these symbols is
transparent to you in most cases. However, the following two areas might require
action:
•
Setting and canceling modules
•
Resolving symbol ambiguities
2.5.1 Setting and Canceling Modules
To facilitate symbol searches, the debugger loads symbol information from the
executable image into a run-time symbol table (RST), where that information can
be accessed efficiently. Unless symbol information is in the RST, the debugger
does not recognize or properly interpret the associated symbols.
Because the RST takes up memory, the debugger loads it dynamically,
anticipating what symbols you might want to reference in the course of program
execution. The loading process is called module setting, because all symbol
information for a given module is loaded into the RST at one time.
Initially, only the module containing the image transfer address is set.
Subsequently, whenever execution of the program is interrupted, the debugger
sets the module that contains the routine in which execution is paused. This
enables you to reference the symbols that should be visible at that location.
If you try to reference a symbol in a module that has not been set, the debugger
warns you that the symbol is not in the RST. For example:
DBG> EXAMINE K
%DEBUG-W-NOSYMBOL, symbol ’K’ is not in symbol table
DBG>
You must use the SET MODULE command to set the module containing that
symbol explicitly. For example:
DBG> SET MODULE MOD3
DBG> EXAMINE K
MOD3\ROUT2\K: 26
DBG>
The SHOW MODULE command lists the modules of your program and identifies
which modules are set.
2–14
Getting Started with the Debugger
2.5 Controlling Access to Symbols in Your Program
Dynamic module setting can slow the debugger down as more and more modules
are set. If performance becomes a problem, you can use the CANCEL MODULE
command to reduce the number of set modules, or you can disable dynamic
module setting by entering the SET MODE NODYNAMIC command (SET MODE
DYNAMIC enables dynamic module setting).
2.5.2 Resolving Symbol Ambiguities
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.
If the debugger cannot resolve a symbol ambiguity, it issues a message. For
example:
DBG> EXAMINE Y
%DEBUG-W-NOUNIQUE, symbol ’Y’ is not unique
DBG>
You can then use a path-name prefix to uniquely specify a declaration of the
given symbol. First, use the SHOW SYMBOL command to identify all path
names associated with the given symbol (corresponding to all declarations of that
symbol) that are currently loaded in the RST. Then use the desired path-name
prefix when referencing the symbol. For example:
DBG> SHOW SYMBOL Y
data MOD7\ROUT3\BLOCK1\Y
data MOD4\ROUT2\Y
DBG> EXAMINE MOD4\ROUT2\Y
MOD4\ROUT2\Y: 12
DBG>
If you need to refer to a particular declaration of Y repeatedly, use the SET
SCOPE command to establish a new default scope for symbol lookup. Then,
references to Y without a path-name prefix specify the declaration of Y that is
visible in the new scope. For example:
DBG> SET SCOPE MOD4\ROUT2
DBG> EXAMINE Y
MOD4\ROUT2\Y: 12
DBG>
To display the current scope for symbol lookup, use the SHOW SCOPE command.
To restore the default scope, use the CANCEL SCOPE command.
2.6 Sample Debugging Session
This section walks you through a debugging session with a simple Fortran
program that contains a logic error (see Example 2–1). Compiler-assigned line
numbers have been added in the example so that you can identify the source lines
referenced in the discussion.
The program, called SQUARES, performs the following functions:
1. Reads a sequence of integer numbers from a data file and saves these
numbers in the array INARR (lines 4 and 5).
2–15
Getting Started with the Debugger
2.6 Sample Debugging Session
2. Enters a loop in which it copies the square of each nonzero integer into
another array OUTARR (lines 8 through 13).
3. Prints the number of nonzero elements in the original sequence and the
square of each such element (lines 16 through 21).
Example 2–1 Sample Program SQUARES
1:
2:
3:
4:
5:
6:
7:
8:
9:
10:
11:
12:
13:
14:
15:
16:
17:
18:
19:
20:
21:
22:
INTEGER INARR(20), OUTARR(20)
C
C
C
C
C
C
---Read the input array from the data file.
OPEN(UNIT=8, FILE=’DATAFILE.DAT’, STATUS=’OLD’)
READ(8,*) N, (INARR(I), I=1,N)
---Square all nonzero elements and store in OUTARR.
K = 0
DO 10 I = 1, N
IF(INARR(I) .NE. 0) THEN
OUTARR(K) = INARR(I)**2
ENDIF
10 CONTINUE
---Print the squared output values. Then stop.
PRINT 20, K
20 FORMAT(’ Number of nonzero elements is’,I4)
DO 40 I = 1, K
PRINT 30, I, OUTARR(I)
30 FORMAT(’ Element’,I4,’ has value’,I6)
40 CONTINUE
END
When you run SQUARES, it produces the following output, regardless of the
number of nonzero elements in the data file:
$ RUN SQUARES
Number of nonzero elements is
0
The error in the program is that variable K, which keeps track of the current
index into OUTARR, is not incremented in the loop on lines 9 through 13. The
statement K = K + 1 should be inserted just before line 11.
Example 2–2 shows how to start the debugging session and then how to use
the debugger to find the error. Comments, keyed to the callouts, follow the
example.
Example 2–2 Sample Debugging Session Using Program SQUARES
$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES
$ LINK/DEBUG SQUARES "
$ DEBUG/KEEP
!
#
Debugger Banner and Version Number
DBG> RUN SQUARES $
Language: FORTRAN, Module: SQUARES$MAIN
DBG> STEP 4 %
stepped to SQUARES$MAIN\%LINE 9
9:
DO 10 I = 1, N
(continued on next page)
2–16
Getting Started with the Debugger
2.6 Sample Debugging Session
Example 2–2 (Cont.) Sample Debugging Session Using Program SQUARES
DBG> EXAMINE N,K &
SQUARES$MAIN\N:
9
SQUARES$MAIN\K:
0
DBG> STEP 2 ’
stepped to SQUARES$MAIN\%LINE 11
11:
OUTARR(K) = INARR(I)**2
DBG> EXAMINE I,K (
SQUARES$MAIN\I:
1
SQUARES$MAIN\K:
0
DBG> DEPOSIT K = 1 )
DBG> SET TRACE/SILENT %LINE 11 DO (DEPOSIT K = K + 1) +>
DBG> GO +?
Number of nonzero elements is 4
Element 1 has value
16
Element 2 has value
36
Element 3 has value
9
Element 4 has value
49
’Normal successful completion’
DBG> SPAWN [email protected]
$ EDIT SQUARES.FOR +A
.
.
.
10:
IF(INARR(I) .NE. 0) THEN
11:
K = K + 1
12:
OUTARR(K) = INARR(I)**2
13:
ENDIF
.
.
.
$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES +B
$ LINK/DEBUG SQUARES
$ LOGOUT +C
DBG> RUN SQUARES +D
Language: FORTRAN, Module: SQUARES$MAIN
DBG> SET BREAK %LINE 12 DO (EXAMINE I,K) +E
DBG> GO +F
SQUARES$MAIN\I:
1
SQUARES$MAIN\K:
1
DBG> GO
SQUARES$MAIN\I:
2
SQUARES$MAIN\K:
2
DBG> GO
SQUARES$MAIN\I:
4
SQUARES$MAIN\K:
3
DBG> EXIT +G
$
The following comments apply to the callouts in Example 2–2. Example 2–1
shows the program that is being debugged.
! The /DEBUG qualifier on the DCL FORTRAN command directs the compiler
to write the symbol information associated with SQUARES into the object
module, SQUARES.OBJ, in addition to the code and data for the program.
The /NOOPTIMIZE qualifier disables optimization by the Fortran compiler,
which ensures that the executable code matches the source code of the
program. Debugging optimized code can be confusing because the contents
of some program locations might be inconsistent with what you would expect
from viewing the source code.
2–17
Getting Started with the Debugger
2.6 Sample Debugging Session
" The /DEBUG qualifier on the DCL command LINK causes the linker to
include all symbol information that is contained in SQUARES.OBJ in the
executable image.
# The DCL command DEBUG/KEEP starts the debugger, which displays
its banner and the debugger prompt, DBG>. You can now enter debugger
commands.
$ The debugger command RUN SQUARES brings the program SQUARES
under debugger control. The informational message identifies the source
language of the program and the name of the main program unit (FORTRAN
and SQUARES, respectively, in this example).
Execution is initially paused at the start of the main program unit (line 1 of
SQUARES, in this example).
% You decide to test the values of variables N and K after the READ statement
has been executed and the value 0 has been assigned to K.
The command STEP 4 executes 4 source lines of the program. Execution is
now paused at line 9. Note that the STEP command ignores source lines that
do not result in executable code; also, by default, the debugger identifies the
source line at which execution is paused.
& The command EXAMINE N, K displays the current values of N and K. Their
values are correct at this point in the execution of the program.
’ The command STEP 2 executes the program into the loop that copies and
squares all nonzero elements of INARR into OUTARR.
( The command EXAMINE I,K displays the current values of I and K.
I has the expected value 1, but K has the value 0 instead of 1, which is the
expected value. Now you can see the error in the program: K should be
incremented in the loop just before it is used in line 11.
) The DEPOSIT command assigns K the value it should have now: 1.
+> The SET TRACE command is now used to patch the program so that the
value of K is incremented automatically in the loop. The command sets a
tracepoint that triggers every time execution reaches line 11:
•
The /SILENT qualifier suppresses the "trace at" message that would
otherwise appear each time line 11 is executed.
•
The DO clause issues the DEPOSIT K = K + 1 command every time the
tracepoint is triggered.
+? To test the patch, the GO command starts execution from the current location.
The program output shows that the patched program works properly. The
EXITSTATUS message shows that the program executed to completion.
[email protected] The SPAWN command spawns a subprocess to return control temporarily to
DCL level (without ending the debugging session) so that you can correct the
source file and recompile and relink the program.
+A The EDIT command invokes an editor and the source file is edited to add
K = K + 1 after line 10, as shown. (Compiler-assigned line numbers have
been added to clarify the example.)
+B The revised program is compiled and linked.
2–18
Getting Started with the Debugger
2.6 Sample Debugging Session
+C The LOGOUT command terminates the spawned subprocess and returns
control to the debugger.
+D The (debugger) command RUN SQUARES brings the revised program under
debugger control so that its correct execution can be verified.
+E The SET BREAK command sets a breakpoint that triggers every time line
12 is executed. The DO clause displays the values of I and K automatically
when the breakpoint triggers.
+F The GO command starts execution.
At the first breakpoint, the value of K is 1, indicating that the program is
running correctly so far. Each additional GO command shows the current
values of I and K. After two more GO commands, K is now 3, as expected,
but note that I is 4. The reason is that one of the INARR elements was 0 so
that lines 11 and 12 were not executed (and K was not incremented) for that
iteration of the DO loop. This confirms that the program is running correctly.
+G The EXIT command ends the debugging session and returns control to DCL
level.
2–19
3
Controlling and Monitoring Program Execution
This chapter describes how to control and monitor program execution while
debugging by using the following techniques:
•
Executing the program by step unit
•
Suspending and tracing execution with breakpoints and tracepoints
•
Monitoring changes in variables and other program locations with
watchpoints
The following related functions are discussed in Chapter 2:
•
Starting or resuming program execution with the GO command (Section 2.3.1)
•
Monitoring where execution is currently paused with the SHOW CALLS
command (Section 2.3.3)
This chapter includes information that is common to all programs. For more
information:
•
See Chapter 15 for additional information specific to multiprocess programs.
•
See Chapter 16 for additional information specific to tasking (multithread)
programs.
For information about rerunning your program or running another program from
the current debugging session, see Section 1.3.3 and Section 1.3.4.
3.1 Commands Used to Execute the Program
Only four debugger commands are directly associated with program execution:
GO
STEP
CALL
EXIT (if your program has exit handlers)
As explained in Section 2.3.1 and Section 2.3.2, GO and STEP are the basic
commands for starting and resuming program execution. The STEP command is
discussed further in Section 3.2.
During a debugging session, routines are executed as they are called during the
execution of a program. The CALL command enables you to arbitrarily call and
execute a routine that was linked with your program. This command is discussed
in Section 13.7.
The EXIT command was discussed in Section 1.8, in conjunction with ending a
debugging session. Because it executes any exit handlers in your program, it is
also useful for debugging exit handlers (see Section 14.6).
3–1
Controlling and Monitoring Program Execution
3.1 Commands Used to Execute the Program
When using any of these four commands, note that program execution can be
interrupted or stopped by any of the following events:
•
The program terminates
•
A breakpoint is reached
•
A watchpoint is triggered
•
An exception is signaled
•
You press Ctrl/C
3.2 Executing the Program by Step Unit
The STEP command (probably the most frequently used debugger command)
enables you to execute your program in small increments called step units.
By default, a step unit is an executable line of source code. In the following
example, the STEP command executes one line, reports the action ("stepped
to . . . "), and displays the line number (27) and source code of the next line to be
executed:
DBG> STEP
stepped to TEST\COUNT\%LINE 27
27: X := X + 1;
DBG>
Execution is now paused at the first machine-code instruction for line 27 of
module TEST. Line 27 is in COUNT, a routine within module TEST.
The STEP command can also execute several source lines at a time. If you specify
a positive integer as a parameter, the STEP command executes that number of
lines. In the following example, the STEP command executes the next three lines:
DBG> STEP 3
stepped to TEST\COUNT\%LINE 34
34: SWAP(X,Y);
DBG>
Note that only those source lines for which code instructions were generated by
the compiler are recognized as executable lines by the debugger. The debugger
skips over any other lines—for example, comment lines. Also, if a line has more
than one statement on it, the debugger executes all the statements on that line
as part of the single step.
Source lines are displayed by default after stepping if they are available for the
module being debugged. Source lines are not available if you are stepping in code
that has not been compiled or linked with the /DEBUG qualifier (for example,
a shareable image routine). If source lines are available, you can control their
display with the SET STEP [NO]SOURCE command and the /[NO]SOURCE
qualifier of the STEP command. For information about how to control the display
of source code in general and in particular after stepping, see Chapter 6.
3.2.1 Changing the STEP Command Behavior
You can change the default behavior of the STEP command in two ways:
3–2
•
By specifying a STEP command qualifier—for example, STEP/INTO
•
By establishing a new default qualifier with the SET STEP command—for
example, SET STEP INTO
Controlling and Monitoring Program Execution
3.2 Executing the Program by Step Unit
In the following example, the STEP/INTO command steps into a called routine
when the program counter (PC) is at a call statement. The debugger displays
the source line identifying the routine PRODUCT, which is called from routine
COUNT of module TEST:
DBG> STEP/INTO
stepped to routine TEST\PRODUCT
6:
function PRODUCT(X,Y : INTEGER) return INTEGER is
DBG>
After the STEP/INTO command executes, subsequent STEP commands revert to
the default behavior.
In contrast, the SET STEP command enables you to establish new defaults
for the STEP command. These defaults remain in effect until another SET
STEP command is entered. For example, the SET STEP INTO command causes
subsequent STEP commands to behave like STEP/INTO (SET STEP LINE causes
subsequent STEP commands to behave like STEP/LINE).
There is a SET STEP command parameter for each STEP command qualifier.
You can override the current STEP command defaults for the duration of a single
STEP command by specifying other qualifiers. Use the SHOW STEP command to
identify the current STEP command defaults.
3.2.2 Stepping Into and Over Routines
By default, when the PC is at a call statement and you enter the STEP command,
the debugger steps over the called routine. Although the routine is executed,
execution is not paused within the routine but, rather, on the beginning of the
line that follows the call statement. When stepping by instruction, execution is
paused on the instruction that follows a called routine’s return instruction.
To step into a called routine when the PC is at a call statement, enter the
STEP/INTO command. The following example shows how to step into the routine
PRODUCT, which is called from routine COUNT of module TEST:
DBG> STEP
stepped to TEST\COUNT\%LINE 18
18:
AREA := PRODUCT(LENGTH, WIDTH);
DBG> STEP/INTO
stepped to routine TEST\PRODUCT
6:
function PRODUCT(X,Y : INTEGER) return INTEGER is
DBG>
To return to the calling routine from any point within the called routine, use
the STEP/RETURN command. It causes the debugger to step to the return
instruction of the routine being executed. A subsequent STEP command brings
you back to the statement that follows the routine call. For example:
DBG> STEP/RETURN
stepped on return from TEST\PRODUCT\%LINE 11 to TEST\PRODUCT\%LINE 15+4
15:
end PRODUCT;
DBG> STEP
stepped to TEST\COUNT\%LINE 19
19:
LENGTH := LENGTH + 1;
DBG>
To step into several routines, enter the SET STEP INTO command to change the
default behavior of the STEP command from STEP/OVER to STEP/INTO:
DBG> SET STEP INTO
3–3
Controlling and Monitoring Program Execution
3.2 Executing the Program by Step Unit
As a result of this command, when the PC is at a call statement, a STEP
command suspends execution within the called routine. If you later want to step
over routine calls, enter the SET STEP OVER command.
When SET STEP INTO is in effect, you can qualify the kinds of called routines
that the debugger is stepping into by specifying any of the following parameters
with the SET STEP command:
•
[NO]SHARE—Controls whether to step into called routines in shareable
images.
•
[NO]SYSTEM—Controls whether to step into called system routines.
These parameters make it possible to step into application-defined routines and
automatically step over system routines, and so on. For example, the following
command directs the debugger to step into called routines in user space only. The
debugger steps over routines in system space and in shareable images.
DBG> SET STEP INTO,NOSYSTEM,NOSHARE
3.3 Suspending and Tracing Execution with Breakpoints and
Tracepoints
This section discusses using the SET BREAK and SET TRACE commands to,
respectively, suspend and trace program execution. The commands are discussed
together because of their similarities.
SET BREAK Command Overview
The SET BREAK command lets you specify program locations or events at which
to suspend program execution (breakpoints). After setting a breakpoint, you can
start or resume program execution with the GO command, letting the program
run until the specified location or condition is reached. When the breakpoint
is triggered, the debugger suspends execution, identifies the breakpoint, and
displays the DBG> prompt. You can then enter debugger commands—for
example, to determine where you are (with the SHOW CALLS command), step
into a routine, examine or modify variables, and so on.
The syntax of the SET BREAK command is as follows:
SET BREAK[/qualifier[ . . . ]] [address-expression[, . . . ]]
[WHEN (conditional-expression)]
[DO (command[; . . . ])]
The following example shows a typical use of the SET BREAK command and
shows the general default behavior of the debugger at a breakpoint.
In this example, the SET BREAK command sets a breakpoint on routine COUNT
(at the beginning of the routine’s code). The GO command starts execution. When
routine COUNT is encountered, execution is paused, the debugger announces that
the breakpoint at COUNT has been reached ("break at . . . "), displays the source
line (54) where execution is paused, and prompts for another command:
DBG> SET BREAK COUNT
DBG> GO
.
.
.
break at routine PROG2\COUNT
54: procedure COUNT(X,Y:INTEGER);
DBG>
3–4
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
SET TRACE Command Overview
The SET TRACE command lets you select program locations or events for tracing
the execution of your program without stopping its execution (tracepoints). After
setting a tracepoint, you can start execution with the GO command and then
monitor that location, checking for unexpected behavior. By setting a tracepoint
on a routine, you can also monitor the number of times it is called.
The debugger’s default behavior at a tracepoint is identical to that at a
breakpoint, except that program execution continues past a tracepoint. Thus,
the DBG> prompt is not displayed when a tracepoint is reached and announced
by the debugger.
Except for the command name, the syntax of the SET TRACE command is
identical to that of the SET BREAK command:
SET TRACE[/qualifier[ . . . ]] [address-expression[, . . . ]]
[WHEN (conditional-expression)]
[DO (command[; . . . ])]
The SET TRACE and SET BREAK commands have similar syntax. When using
the SET TRACE command, specify address expressions, qualifiers, and the
optional WHEN and DO clauses exactly as with the SET BREAK command.
Unless you use the /TEMPORARY qualifier on the SET BREAK or SET TRACE
command, breakpoints and tracepoints remain in effect until you:
•
Deactivate or cancel them (see Section 3.3.7)
•
Rerun the program with the RERUN/NOSAVE command (see Section 1.3.3)
•
Run a new program (see Section 1.3.4) or end the debugging session
(Section 1.8)
To identify all of the breakpoints or tracepoints that are currently set, use the
SHOW BREAK or SHOW TRACE command.
To deactivate, activate, or cancel breakpoints or tracepoints, use the following
commands (see Section 3.3.7):
DEACTIVATE BREAK, DEACTIVATE TRACE
ACTIVATE BREAK, ACTIVATE TRACE
CANCEL BREAK, CANCEL TRACE
The following sections describe how to specify program locations and events with
the SET BREAK and SET TRACE commands.
3.3.1 Setting Breakpoints or Tracepoints on Individual Program Locations
To set a breakpoint or a tracepoint on a particular program location, specify an
address expression with the SET BREAK or SET TRACE command.
Fundamentally, an address expression specifies a memory address or a register.
Because the debugger understands the symbols associated with your program,
the address expressions you typically use with the SET BREAK or SET TRACE
command are routine names, labels, or source line numbers rather than memory
addresses—the debugger converts these symbols to addresses.
3–5
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
3.3.1.1 Specifying Symbolic Addresses
Note
In some cases, when using the SET BREAK or SET TRACE command
with a symbolic address expression, you might need to set a module or
specify a scope or a path name. Those concepts are described in detail in
Chapter 5. The examples in this section assume that all modules are set
and that all symbols referenced are uniquely defined, unless otherwise
indicated.
The following examples show how to set a breakpoint on a routine (SWAP) and a
tracepoint on a label (LOOP1):
DBG> SET BREAK SWAP
DBG> SET TRACE LOOP1
The next command sets a breakpoint on the return instruction of routine
SWAP. Breaking on the return instruction of a routine lets you inspect the
local environment (for example, to obtain the values of local variables) while the
routine is still active.
DBG> SET BREAK/RETURN SWAP
Some languages, for example Fortran, use numeric labels. To set a breakpoint or
a tracepoint on a numeric label, you must precede the number with the built-in
symbol %LABEL. Otherwise, the debugger interprets the number as a memory
address. For example, the following command sets a tracepoint on label 20:
DBG> SET TRACE %LABEL 20
You can set a breakpoint or a tracepoint on a line of source code by specifying the
line number preceded by the built-in symbol %LINE. The following command sets
a breakpoint on line 14:
DBG> SET BREAK %LINE 14
The previous breakpoint causes execution to pause on the first instruction of line
14. You can set a breakpoint or a tracepoint only on lines for which the compiler
generated instructions (lines that resulted in executable code). If you specify a
line number that is not associated with an instruction, such as a comment line or
a statement that declares but does not initialize a variable, the debugger issues a
diagnostic message. For example:
DBG> SET BREAK %LINE 6
%DEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8
%DEBUG-E-NOSYMBOL, symbol ’%LINE 6’ is not in the symbol table
DBG>
The previous messages indicate that the compiler did not generate instructions
for lines 6 or 7 in this case.
Some languages allow more than one statement on a line. In such cases, you
can use statement numbers to differentiate among statements on the same line.
A statement number consists of a line number, followed by a period ( . ), and a
number indicating the statement. The syntax is as follows:
%LINE line-number.statement-number
3–6
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
For example, the following command sets a tracepoint on the second statement of
line 38:
DBG> SET TRACE %LINE 38.2
When searching for symbols that you reference in commands, the debugger
uses the conventions described in Section 5.3.1. That is, it first looks within the
module where execution is currently paused, then in other scopes associated
with routines on the call stack, and so on. Therefore, to specify a symbol that is
defined in more than one module, such as a line number, you might need to use
a path name. For example, the following command sets a tracepoint on line 27 of
module MOD4:
DBG> SET TRACE MOD4\%LINE 27
Remember the symbol lookup conventions when specifying a line number in
debugger commands. If that line number is not defined in the module where
execution is paused (because it is not associated with an instruction), the
debugger uses the symbol lookup conventions to locate another module where
the line number is defined.
When specifying address expressions, you can combine symbolic addresses with
byte offsets. Thus, you can set a breakpoint or a tracepoint on a particular
instruction by specifying its line number and the byte offset from the beginning of
that line to the first byte of the instruction. For example, the next command sets
a breakpoint on the address that is five bytes beyond the beginning of line 23:
DBG> SET BREAK %LINE 23+5
3.3.1.2 Specifying Locations in Memory
To set a breakpoint or a tracepoint on a location in memory, specify its numerical
address in the currently set radix. The default radix for both data entry and
display is decimal for most languages.
On Alpha processors, the exceptions are BLISS, MACRO–32, and MACRO–64,
which have a default radix of hexadecimal.
On Integrity server, the exceptions are BLISS, MACRO–32, and Intel Assembler.
For example, the following command sets a breakpoint at address 2753, decimal,
or at address 2753, hexadecimal:
DBG> SET BREAK 2753
You can specify a radix when you enter an individual integer literal (such as
2753) by using one of the built-in symbols %BIN, %OCT, %DEC, or %HEX. For
example, in the following command line the symbol %HEX specifies that 2753
should be treated as a hexadecimal integer:
DBG> SET BREAK %HEX 2753
Note that when specifying a hexadecimal number that starts with a letter rather
than a number, you must add a leading 0. Otherwise, the debugger tries to
interpret the entity specified as a symbol declared in your program.
For additional information about specifying radixes and about the built-in
symbols %BIN, %DEC, %HEX, and %OCT, see Section 4.1.10 and Appendix B.
If a breakpoint or a tracepoint was set on a numerical address that corresponds
to a symbol in your program, the SHOW BREAK or SHOW TRACE command
identifies the breakpoint symbolically.
3–7
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
3.3.1.3 Obtaining and Symbolizing Memory Addresses
Use the EVALUATE/ADDRESS command to determine the memory address
associated with a symbolic address expression, such as a line number, routine
name, or label. For example:
DBG> EVALUATE/ADDRESS SWAP
1536
DBG> EVALUATE/ADDRESS %LINE 26
1629
DBG>
The address is displayed in the current radix. You can specify a radix qualifier to
display the address in another radix. For example:
DBG> EVALUATE/ADDRESS/HEX %LINE 26
0000065D
DBG>
The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS. It
converts a memory address into its symbolic representation (including its path
name) if such a representation is possible. Chapter 5 explains how to control
symbolization. See Section 4.1.11 for more information about obtaining and
symbolizing addresses.
3.3.2 Setting Breakpoints or Tracepoints on Lines or Instructions
The following SET BREAK and SET TRACE command qualifiers cause the
debugger to break on or trace every source line or every instruction of a particular
class:
/LINE
/BRANCH
/CALL
/INSTRUCTION
When using these qualifiers, do not specify an address expression.
For example, the following command causes the debugger to break on the
beginning of every source line encountered during execution:
DBG> SET BREAK/LINE
The instruction-related qualifiers are especially useful for opcode tracing, which
is the tracing of all instructions or the tracing of a class of instructions. The next
command causes the debugger to trace every branch instruction encountered (for
example BEQL, BGTR, and so on):
DBG> SET TRACE/BRANCH
Note that opcode tracing slows program execution.
By default, when you use the qualifiers discussed in this section, the debugger
breaks or traces within all called routines as well as within the currently
executing routine (this is equivalent to specifying SET BREAK/INTO or SET
TRACE/INTO). By specifying SET BREAK/OVER or SET TRACE/OVER, you
can suppress break or trace action within all called routines. Or, you can use
the /[NO]JSB, /[NO]SHARE, or /[NO]SYSTEM qualifiers to specify the kinds of
called routines where break or trace action is to be suppressed. For example, the
next command causes the debugger to break on every line except within called
routines that are in shareable images or system space:
DBG> SET BREAK/LINE/NOSHARE/NOSYSTEM
3–8
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
3.3.3 Setting Breakpoints on Emulated Instructions (Alpha Only)
On Alpha systems, to cause the debugger to suspend program execution when
an instruction is emulated, use the command SET BREAK/SYSEMULATE. The
syntax of the SET BREAK command when using the /SYSEMULATE qualifier is:
SET BREAK/SYSEMULATE[=mask]
The optional argument mask is a quadword with bits set to specify which
instruction groups shall trigger breakpoints. The only emulated instruction group
currently defined consists of the BYTE and WORD instructions. Specify this
instruction group by setting bit 0 of mask to 1.
If you do not specify mask, or if mask = FFFFFFFFFFFFFFFF, the debugger
stops program execution whenever the operating system emulates any
instruction.
3.3.4 Controlling Debugger Action at Breakpoints or Tracepoints
The SET BREAK and SET TRACE commands provide several options for
controlling the behavior of the debugger at breakpoints and tracepoints—the
/AFTER, /[NO]SILENT, /[NO]SOURCE, and /TEMPORARY command qualifiers,
and the optional WHEN and DO clauses. The following examples show several of
these options.
The following command sets a breakpoint on line 14 and specifies that the
breakpoint take effect after the fifth time that line 14 is executed:
DBG> SET BREAK/AFTER:5 %LINE 14
The following command sets a tracepoint that is triggered at every line of
execution. The DO clause obtains the value of the variable X when each line is
executed:
DBG> SET TRACE/LINE DO (EXAMINE X)
The following example shows how you capture the WHEN and DO clauses
together. The command sets a breakpoint at line 27. The breakpoint is triggered
(execution is paused) only when the value of SUM is greater than 100 (not each
time line 27 is executed). The DO clause causes the value of TEST_RESULT to
be examined whenever the breakpoint is triggered—that is, whenever the value
of SUM is greater than 100. If the value of SUM is not greater than 100 when
execution reaches line 27, the breakpoint is not triggered and the DO clause is
not executed.
DBG> SET BREAK %LINE 27 WHEN (SUM > 100) DO (EXAMINE TEST_RESULT)
See Section 4.1.6 and Section 14.3.2.2 for information about evaluating language
expressions like SUM > 100.
The /SILENT qualifier suppresses the break or trace message and source code
display. This is useful when, for example, you want to use the SET TRACE
command only to execute a debugger command at the tracepoint. In the following
example, the SET TRACE command is used to examine the value of the Boolean
variable STATUS at the tracepoint:
3–9
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
DBG> SET TRACE/SILENT %LINE 83 DO (EXAMINE STATUS)
DBG> GO
.
.
.
SCREEN_IO\CLEAR\STATUS: OFF
.
.
.
In the next example, the SET TRACE command is used to count the number
of times line 12 is executed. The first DEFINE/VALUE command defines a
symbol COUNT and initializes its value to 0. The DO clause of the SET TRACE
command causes the value of COUNT to be incremented and evaluated whenever
the tracepoint is triggered (whenever execution reaches line 12).
DBG> DEFINE/VALUE COUNT=0
DBG> SET TRACE/SILENT %LINE 12 DO (DEF/VAL COUNT=COUNT+1;EVAL COUNT)
Source lines are displayed by default at breakpoints, tracepoints, and watchpoints
if they are available for the module being debugged. You can also control their
display with the SET STEP [NO]SOURCE command and the /[NO]SOURCE
qualifier of the SET BREAK, SET TRACE, and SET WATCH commands. See
Chapter 6 for information about how to control the display of source code in
general and in particular at breakpoints, tracepoints, and watchpoints.
3.3.5 Setting Breakpoints or Tracepoints on Exceptions
The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands direct
the debugger to treat any exception generated by your program as a breakpoint
or tracepoint, respectively. The breakpoint or tracepoint occurs before any
application-declared exception handler is invoked. See Section 14.5 for debugging
techniques associated with exceptions and condition handlers.
3.3.6 Setting Breakpoints or Tracepoints on Events
The SET BREAK and SET TRACE commands each have an /EVENT=event-name
qualifier. You can use this qualifier to set breakpoints or tracepoints that are
triggered by various events (denoted by event-name keywords). Events and their
keywords are currently defined for the following event facilities:
•
ADA event facility, which defines Compaq Ada tasking events. Ada events are
defined in Section 16.6.4.
•
THREADS event facility, which defines tasking (multithread) events for
programs written in any language that uses POSIX Threads services.
Threads events are defined in Section 16.6.4.
The appropriate facility and event-name keywords are defined when the program
is brought under debugger control. Use the SHOW EVENT_FACILITY command
to identify the current event facility and the associated event-name keywords.
The SET EVENT_FACILITY command enables you to change the event facility
and change your debugging context. This is useful if you have a multilanguage
program and want to debug a routine that is associated with an event facility but
that facility is not currently set.
The following example shows how to set a SCAN event breakpoint. It causes the
debugger to break whenever a SCAN token is built, for any value:
DBG> SET BREAK/EVENT=TOKEN
3–10
Controlling and Monitoring Program Execution
3.3 Suspending and Tracing Execution with Breakpoints and Tracepoints
When a breakpoint or tracepoint is triggered, the debugger identifies the event
that caused it to be triggered and gives additional information.
3.3.7 Deactivating, Activating, and Canceling Breakpoints or Tracepoints
After a breakpoint or tracepoint is set, you can deactivate it, activate it, or cancel
it.
To deactivate a breakpoint or tracepoint, enter the DEACTIVATE BREAK
or DEACTIVATE TRACE command. This causes the debugger to ignore the
breakpoint or tracepoint during program execution. However, you can activate it
at a later time, for example, when you rerun the program (see Section 1.3.3). A
deactivated breakpoint or tracepoint is listed as such in a SHOW BREAK display.
To activate a breakpoint or tracepoint, use the ACTIVATE BREAK or
ACTIVATE TRACE command. Activating a breakpoint or tracepoint causes
it to take effect during program execution.
The commands DEACTIVATE BREAK/ALL and ACTIVATE BREAK/ALL
(or DEACTIVATE TRACE/ALL and ACTIVATE TRACE/ALL) operate on all
breakpoints or tracepoints and are particularly useful when rerunning a program
with the RERUN command.
To cancel a breakpoint or tracepoint, use the CANCEL BREAK or
CANCEL TRACE command. A canceled breakpoint or tracepoint is no longer
listed in a SHOW BREAK or SHOW TRACE display.
When using any of these commands, specify the address expression and qualifiers
(if any) exactly as you did when setting the breakpoint or tracepoint. For
example:
DBG> DEACTIVATE TRACE/LINE
DBG> CANCEL BREAK SWAP,MOD2\LOOP4,2753
3.4 Monitoring Changes in Variables and Other Program Locations
The SET WATCH command enables you to specify program variables (or arbitrary
memory locations) that the debugger monitors as your program executes. This
process is called setting watchpoints. If, during execution, the program modifies
the value of a watched variable (or memory location), the watchpoint is triggered.
The debugger then suspends execution, displays information, and prompts
for more commands. The debugger monitors watchpoints continuously during
program execution.
This section describes the general use of the SET WATCH command. Section 3.4.3
gives additional information about setting watchpoints on nonstatic variables—
variables that are allocated on the call stack or in registers.
Note
In some cases, when using the SET WATCH command with a variable
name (or any other symbolic address expression), you might need to set a
module or specify a scope or a path name. Those concepts are described
in Chapter 5. The examples in this section assume that all modules are
set and that all variable names are uniquely defined.
If your program was optimized during compilation, certain variables in
the program might be removed by the compiler. If you then try to set
3–11
Controlling and Monitoring Program Execution
3.4 Monitoring Changes in Variables and Other Program Locations
a watchpoint on such a variable, the debugger issues a warning (see
Section 1.2 and Section 14.1).
The syntax of the SET WATCH command is as follows:
SET WATCH[/qualifier[ . . . ]] address-expression[, . . . ]
[WHEN (conditional-expression)]
[DO (command[; . . . ])]
You can specify any valid address expression, but usually you specify the
name of a variable. The following example shows a typical use of the SET
WATCH command and shows the general default behavior of the debugger at a
watchpoint:
DBG> SET WATCH COUNT
DBG> GO
.
.
.
watch of MOD2\COUNT at MOD2\%LINE 24
24: COUNT := COUNT + 1;
old value: 27
new value: 28
break at MOD2\%LINE 25
25: END;
DBG>
In this example, the SET WATCH command sets a watchpoint on the variable
COUNT, and the GO command starts execution. When the program changes the
value of COUNT, execution is paused. The debugger then does the following:
•
Announces the event ("watch of MOD2\COUNT . . . "), identifying the
location of the instruction that changed the value of the watched variable
(" . . . at MOD2\%LINE 24")
•
Displays the associated source line (24)
•
Displays the old and new values of the variable (27 and 28)
•
Announces that execution is paused at the beginning of the next line ("break
at MOD2\%LINE 25") and displays that source line
•
Prompts for another command
When the address of the instruction that modified a watched variable is not at
the beginning of a source line, the debugger denotes the instruction’s location by
displaying the line number plus the byte offset from the beginning of the line.
For example:
DBG> SET WATCH K
DBG> GO
.
.
.
watch of TEST\K at TEST\%LINE 19+5
19: DO 40 K = 1, J
old value: 4
new value: 5
break at TEST\%LINE 19+9
19: DO 40 K = 1, J
DBG>
3–12
Controlling and Monitoring Program Execution
3.4 Monitoring Changes in Variables and Other Program Locations
In this example, the address of the instruction that modified variable K is 5 bytes
beyond the beginning of line 19. The breakpoint is on the instruction that follows
the instruction that modified the variable (not on the beginning of the next source
line as in the preceding example).
You can set watchpoints on aggregates (that is, entire arrays or records). A
watchpoint set on an array or record triggers if any element of the array or record
changes. Thus, you do not need to set watchpoints on individual array elements
or record components. However, you cannot set an aggregate watchpoint on a
variant record. In the following example, the watchpoint is triggered because
element 3 of array ARR was modified:
DBG> SET WATCH ARR
DBG> GO
.
.
.
watch of SUBR\ARR at SUBR\%LINE 12
12:
ARR(3) := 28
old value:
(1):
7
(2):
12
(3):
3
(4):
0
new value:
(1):
(2):
(3):
(4):
7
12
28
0
break at SUBR\%LINE 13
DBG>
You can also set a watchpoint on a record component, on an individual array
element, or on an array slice (a range of array elements). A watchpoint set on an
array slice triggers if any element within that slice changes. When setting the
watchpoint, use the syntax of the current language. For example, the following
command sets a watchpoint on element 7 of array CHECK using Pascal syntax:
DBG> SET WATCH CHECK[7]
To identify all of the watchpoints that are currently set, use the SHOW WATCH
command.
3.4.1 Deactivating, Activating, and Canceling Watchpoints
After a watchpoint is set, you can deactivate it, activate it, or cancel it.
To deactivate a watchpoint, use the DEACTIVATE WATCH command. This
causes the debugger to ignore the watchpoint during program execution.
However, you can activate it at a later time, for example, when you rerun
the program (see Section 1.3.3). A deactivated watchpoint is listed as such in a
SHOW WATCH display.
To activate a watchpoint, use the ACTIVATE WATCH command. Activating a
watchpoint causes it to take effect during program execution. You can always
activate a static watchpoint, but the debugger cancels a nonstatic watchpoint
if execution moves out of the scope in which the variable is defined (see
Section 3.4.3).
3–13
Controlling and Monitoring Program Execution
3.4 Monitoring Changes in Variables and Other Program Locations
The commands DEACTIVATE WATCH/ALL and ACTIVATE WATCH/ALL operate
on all watchpoints and are particularly useful when rerunning a program with
the RERUN command.
To cancel a watchpoint, use the CANCEL WATCH command. A canceled
watchpoint is no longer listed in a SHOW WATCH display.
3.4.2 Watchpoint Options
The SET WATCH command provides the same options for controlling the behavior
of the debugger at watchpoints that the SET BREAK and SET TRACE commands
provide for breakpoints and tracepoints—namely the /AFTER, /[NO]SILENT,
/[NO]SOURCE, and /TEMPORARY qualifiers, and the optional WHEN and DO
clauses. See Section 3.3.4 for examples.
3.4.3 Watching Nonstatic Variables
Note
The generic term nonstatic variable is used here to denote what is called
an automatic variable in some languages.
Storage for a variable in your program is allocated either statically or
nonstatically. A static variable is associated with the same memory address
throughout execution of the program. A nonstatic variable is allocated on the
call stack or in a register and has a value only when its defining routine is
active on the call stack. As explained in this section, the technique for setting a
watchpoint, the watchpoint’s behavior, and the speed of program execution are
different for the two kinds of variables.
To determine how a variable is allocated, use the EVALUATE/ADDRESS
command. A static variable generally has its address in P0 space (0 to
3FFFFFFF, hexadecimal). A nonstatic variable generally has its address in
P1 space (40000000 to 7FFFFFFF, hexadecimal) or is in a register. In the
following Pascal code example, X is declared as a static variable, but Y is a
nonstatic variable (by default). The EVALUATE/ADDRESS command, entered
while debugging, shows that X is allocated at memory location 512, but Y is
allocated in register R0.
.
.
.
VAR
X: [STATIC] INTEGER;
Y: INTEGER;
.
.
.
DBG> EVALUATE/ADDRESS X
512
DBG> EVALUATE/ADDRESS Y
%R0
DBG>
When using the SET WATCH command, note the following distinction. You can
set a watchpoint on a static variable throughout execution of your program, but
you can set a watchpoint on a nonstatic variable only when execution is paused
within the scope of the variable’s defining routine. Otherwise, the debugger
issues a warning. For example:
3–14
Controlling and Monitoring Program Execution
3.4 Monitoring Changes in Variables and Other Program Locations
DBG> SET WATCH Y
%DEBUG-W-SYMNOTACT, nonstatic variable ’MOD4\ROUT3\Y’
is not active
DBG>
Section 3.4.3.2 describes how to set a watchpoint on a nonstatic variable.
3.4.3.1 Execution Speed
When a watchpoint is set, the speed of program execution depends on whether
the variable is static or nonstatic. To watch a static variable, the debugger writeprotects the page containing the variable. If your program attempts to write to
that page (modify the value of that variable), an access violation occurs and the
debugger handles the exception. The debugger temporarily unprotects the page
to allow the instruction to complete and then determines whether the watched
variable was modified. Except when writing to that page, the program executes
at full speed.
Because problems arise if the call stack or registers are write-protected, the
debugger must use another technique to watch a nonstatic variable. It traces
every instruction in the variable’s defining routine and checks the value of the
variable after each instruction has been executed. Because this significantly slows
down the execution of the program, the debugger issues the following message
when you set a nonstatic watchpoint:
DBG> SET WATCH Y
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction
DBG>
3.4.3.2 Setting a Watchpoint on a Nonstatic Variable
To set a watchpoint on a nonstatic variable, make sure that execution is paused
within the defining routine. A convenient technique is to set a tracepoint on the
routine that includes a DO clause to set the watchpoint. Thus, whenever the
routine is called, the tracepoint is triggered and the watchpoint is automatically
set on the local variable. In the following example, the WPTTRACE message
indicates that a watchpoint has been set on Y, a nonstatic variable that is local to
routine ROUT3:
DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y)
DBG> GO
.
.
.
trace at routine MOD4\ROUT3
%DEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction
.
.
.
watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16
16:
Y := 4
old value:
3
new value:
4
break at MOD4\ROUT3\%LINE 17
17:
SWAP(X,Y);
DBG>
When execution returns to the caller of routine ROUT3, variable Y is no longer
active. Therefore, the debugger automatically cancels the watchpoint and issues
the following messages:
%DEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has gone out of scope
%DEBUG-I-WATCHCAN, watchpoint now canceled
3–15
Controlling and Monitoring Program Execution
3.4 Monitoring Changes in Variables and Other Program Locations
3.4.3.3 Options for Watching Nonstatic Variables
The SET WATCH command qualifiers /OVER, /INTO, and /[NO]STATIC provide
options for watching nonstatic variables.
When you set a watchpoint on a nonstatic variable, you can direct the debugger
to do one of two things at a routine call:
•
Step over the called routine—executing it at full speed—and resume
instruction tracing after returning. This is the default (SET WATCH/OVER).
•
Trace instructions within the called routine, which monitors the variable
instruction-by-instruction within the routine (SET WATCH/INTO).
Using the SET WATCH/OVER command results in better performance. However,
if the called routine modifies the watched variable, the watchpoint is triggered
only after execution returns from that routine. The SET WATCH/INTO command
slows down program execution but enables you to monitor watchpoints more
precisely within called routines.
The debugger determines whether a variable is static or nonstatic by looking
at its address (P0 space, P1 space, or register). When entering a SET WATCH
command, you can override this decision with the /[NO]STATIC qualifier. For
example, if you have allocated nonstack storage in P1 space, use the SET
WATCH/STATIC command to specify that a particular variable is static even
though it is in P1 space. Conversely, if you have allocated your own call stack in
P0 space, use the SET WATCH/NOSTATIC command to specify that a particular
variable is nonstatic even though it is in P0 space.
3.4.3.4 Setting Watchpoints in Installed Writable Shareable Images
When setting a watchpoint in an installed writable shareable image, use the SET
WATCH/NOSTATIC command (see Section 3.4.3.3).
The reason you must set a nonstatic watchpoint is as follows. Variables declared
in such shareable images are typically static variables. By default, the debugger
watches a static variable by write-protecting the page containing that variable.
However, the debugger cannot write-protect a page in an installed writable
shareable image. Therefore, the debugger must use the slower method of
detecting changes, as for nonstatic variables—that is, by checking the value at the
watched location after each instruction has been executed (see Section 3.4.3.1).
If any other process modifies the watched location’s value, the debugger may
report that your program modified the watched location.
3–16
4
Examining and Manipulating Program Data
This chapter explains how to use the EXAMINE and DEPOSIT commands to
display and modify the values of symbols declared in your program as well as the
contents of arbitrary program locations. The chapter also explains how to use the
EVALUATE and other commands that evaluate language expressions.
The topics covered in this chapter are organized as follows:
•
General concepts related to using the EXAMINE, DEPOSIT, and EVALUATE
commands.
•
Use of the commands with symbolic names—for example, the names of
variables and routines declared in your program. Such symbolic address
expressions are associated with compiler generated types.
•
Use of the commands with program locations (memory addresses or registers)
that do not have symbolic names. Such address expressions are not
associated with compiler generated types.
•
Specifying a type to override the type associated with an address expression.
The examples in this chapter do not cover all language-dependent behavior.
When debugging in any language, be sure also to consult the following
documentation:
•
Section 14.3, which highlights some important language differences that you
should be aware of when debugging multilanguage programs.
•
The debugger’s online help (type HELP Language).
•
The documentation supplied with that language.
4.1 General Concepts
This section introduces the EXAMINE, DEPOSIT, and EVALUATE commands
and discusses concepts that are common to those commands.
4.1.1 Accessing Variables While Debugging
Note
The generic term nonstatic variable is used here to denote what is called
an automatic variable in some languages.
Before you try to examine or deposit into a nonstatic (stack-local or register)
variable, its defining routine must be active on the call stack. That is,
program execution must be paused somewhere within the defining routine.
See Section 3.4.3 for more information about nonstatic variables.
4–1
Examining and Manipulating Program Data
4.1 General Concepts
You can examine a static variable at any time during program execution, and
you can examine a nonstatic variable as soon as execution reaches its defining
routine. However, before you examine any variable, you should execute the
program beyond the point where the variable is declared and initialized. The
value contained in any uninitialized variable should be considered invalid.
Many compilers optimize code to make the program run faster. If the code that
you are debugging has been optimized, some program locations might not match
what you would expect from looking at the source code. In particular, some
optimization techniques eliminate certain variables so that you no longer have
access to them while debugging.
Section 14.1 explains the effect of several optimization techniques on the
executable code. When first debugging a program, it is best to disable
optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler
command qualifier.
In some cases, when using the EXAMINE or DEPOSIT command with a variable
name (or any other symbolic address expression) you might need to set a module
or specify a scope or a path name. Those concepts are described in Chapter 5.
The examples in this chapter assume that all modules are set and that all
variable names are uniquely defined.
4.1.2 Using the EXAMINE Command
For high-level language programs, the EXAMINE command is used mostly to
display the current value of variables, and it has the following syntax:
EXAMINE address-expression[, . . . ]
For example, the following command displays the current value of the integer
variable X:
DBG> EXAMINE X
MOD3\X: 17
DBG>
When displaying the value, the debugger prefixes the variable name with its path
name—in this case, the name of the module where variable X is declared (see
Section 5.3.2).
The EXAMINE command usually displays the current value of the entity, denoted
by an address expression, in the type associated with that location (for example,
integer, real, array, record, and so on).
When you enter an EXAMINE command, the debugger evaluates the address
expression to yield a program location (a memory address or a register). The
debugger then displays the value stored at that location as follows:
•
If the location has a symbolic name, the debugger formats the value according
to the compiler-generated type associated with that symbol.
•
If the location does not have a symbolic name, the debugger formats the value
in the type longword integer by default.
See Section 4.1.5 for more information about the types associated with symbolic
and nonsymbolic address expressions.
By default, when displaying the value, the debugger identifies the address
expression and its path name symbolically if symbol information is available. See
Section 4.1.11 for more information about symbolizing addresses.
4–2
Examining and Manipulating Program Data
4.1 General Concepts
The debugger can directly examine a wchar_t variable:
DBG> EXAMINE wide_buffer
TST\main\wide_buffer[0:31]: ’test data line 1................’
OpenVMS Debugger on Integrity servers displays general, floatingpoint and
predicate registers as if the register rename base (CFM.rrb) and rotating size
(CFM.sor) are both zero. In other words, when rotating registers are in use, the
effects of the rotation are ignored.
Note
This is a rare condition that occurs only in unusual circumstances in C++
and asssembly language programs; most programs are not affected by this
problem.
In this condition, you must examine the CFM register and manually adjust the
EXAMINE command to account for the non-zero CFM.rrb and CFM.sor fields.
4.1.3 Using the DUMP Command
Use the debugger command DUMP to display the contents of memory, in a
manner similar to that of the DCL command DUMP, in one of the following
formats:
Binary
Byte
Decimal
Hexadecimal
Longword (default)
Octal
Quadword
Word
The DUMP command has the following syntax:
DUMP address-expression1[:address-expression2]
The default for address-expression2 is address-expression1. For example, the
following command displays the current value of registers R16 through R25 in
quadword format.
DBG> DUMP/QUADWORD R16:R25
0000000000000078 0000000000030038
000000202020786B 0000000000030041
0000000000030140 0000000000007800
0000000000010038 0000000000000007
0000000000000006 0000000000000000
8.......x.......
A.......kx ...
[email protected]
........8.......
................
%R16
%R18
%R20
%R22
%R24
DBG>
You can use the command DUMP to display registers, variables, and arrays. The
debugger makes no attempt to interpret the structure of arrays. The following
qualifiers determine how the debugger displays output from the DUMP command:
4–3
Examining and Manipulating Program Data
4.1 General Concepts
Qualifier
Formats Output As
/BINARY
Binary integers
/BYTE
One-byte integers
/DECIMAL
Decimal integers
/HEXADECIMAL Hexadecimal integers
/LONGWORD
Longword integers (length 4 bytes)
/OCTAL
Octal integers
/QUADWORD
Quadword integers (length 8 bytes)
/WORD
Word integers (length 2 bytes)
By default, the debugger displays examined entities that do not have a compilergenerated type as longwords.
4.1.4 Using the DEPOSIT Command
For high-level languages, the DEPOSIT command is used mostly to assign a new
value to a variable. The command is similar to an assignment statement in most
programming languages, and has the following syntax:
DEPOSIT address-expression = language-expression
For example, the following DEPOSIT command assigns the value 23 to the
integer variable X:
DBG> EXAMINE X
MOD3\X: 17
DBG> DEPOSIT X = 23
DBG> EXAMINE X
MOD3\X: 23
DBG>
The DEPOSIT command usually evaluates a language expression and deposits
the resulting value into a program location denoted by an address expression.
When you enter a DEPOSIT command, the debugger does the following:
•
It evaluates the address expression to yield a program location.
•
If the program location has a symbolic name, the debugger associates the
location with the symbol’s compiler generated type. If the location does not
have a symbolic name, the debugger associates the location with the type
longword integer by default (see Section 4.1.5).
•
It evaluates the language expression in the syntax of the current language
and in the current radix to yield a value. This behavior is identical to that of
the EVALUATE command (see Section 4.1.6).
•
It checks that the value and type of the language expression is consistent
with the type of the address expression. If you try to deposit a value that
is incompatible with the type of the address expression, the debugger issues
a diagnostic message. If the value is compatible, the debugger deposits the
value into the location denoted by the address expression.
Note that the debugger might do type conversion during a deposit operation if
the language rules allow it. For example, assume X is an integer variable. In the
following example, the real value 2.0 is converted to the integer value 2, which is
then assigned to X:
4–4
Examining and Manipulating Program Data
4.1 General Concepts
DBG> DEPOSIT X = 2.0
DBG> EXAMINE X
MOD3\X: 2
DBG>
In general, the debugger tries to follow the assignment rules for the current
language.
4.1.5 Address Expressions and Their Associated Types
The symbols that are declared in your program (variable names, routine names,
and so on) are symbolic address expressions. They denote memory addresses
or registers. Symbolic address expressions (also called symbolic names in this
chapter) have compiler-generated types, and the debugger knows the type and
location that are associated with symbolic names. Section 4.1.11 explains how to
obtain memory addresses and register names from symbolic names and how to
symbolize program locations.
Symbolic names include the following categories:
•
Variables
The associated program locations contain the current values of variables.
Techniques for examining and depositing into variables are described in
Section 4.2.
•
Routines, labels, and line numbers
The associated program locations contain instructions. Techniques for
examining and depositing instructions are described in Section 4.3.
Program locations that do not have a symbolic name are not associated with
a compiler-generated type. To enable you to examine and deposit into such
locations, the debugger associates them with the default type longword integer.
If you specify a location that does not have a symbolic name, the EXAMINE
command displays the contents of four bytes starting at the address specified and
formats the displayed information as an integer value. In the following example,
the memory address 926 is not associated with a symbolic name (note that the
address is not symbolized when the EXAMINE command is executed). Therefore,
the EXAMINE command displays the value at that address as a longword integer.
DBG> EXAMINE 926
926: 749404624
DBG>
By default you can deposit up to four bytes of integer data into a program location
that does not have a symbolic name. This data is formatted as a longword integer.
For example:
DBG> DEPOSIT 926 = 84
DBG> EXAMINE 926
926: 84
DBG>
Techniques for examining and depositing into locations that do not have a
symbolic name are described in Section 4.5.
The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII:n, /BYTE,
and so on) that enable you to override the type associated with a program
location. This is useful either if you want the contents of the location to be
interpreted and displayed in another type, or if you want to deposit some value of
a particular type into a location that is associated with another type. Techniques
for overriding a type are described in Section 4.5.
4–5
Examining and Manipulating Program Data
4.1 General Concepts
4.1.6 Evaluating Language Expressions
A language expression consists of any combination of one or more symbols,
literals, and operators that is evaluated to a single value in the syntax of the
current language and in the current radix. (The current language and current
radix are defined in Section 4.1.9 and Section 4.1.10, respectively.) Several
debugger commands and constructs evaluate language expressions:
•
The EVALUATE and DEPOSIT commands, which are described in this
section and in Section 4.1.4, respectively
•
The IF, FOR, REPEAT, and WHILE commands (see Section 13.6)
•
WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET
WATCH commands (see Section 3.3.4)
This discussion applies to all commands and constructs that evaluate language
expressions, but it focuses on using the EVALUATE command.
The EVALUATE command evaluates one or more language expressions in the
syntax of the current language and in the current radix and displays the resulting
values. The command has the following syntax:
EVALUATE language-expression[, . . . ]
One use of the EVALUATE command is to perform arithmetic calculations that
might be unrelated to your program. For example:
DBG> EVALUATE (8+12)*6/4
30
DBG>
The debugger uses the rules of operator precedence of the current language when
evaluating language expressions.
You can also evaluate language expressions that include variables and other
constructs. For example, the following EVALUATE command subtracts 3 from
the current value of the integer variable X, multiplies the result by 4, and
displays the resulting value:
DBG> DEPOSIT X = 23
DBG> EVALUATE (X - 3) * 4
80
DBG>
However, you cannot evaluate a language expression that includes a function call.
For example, if PRODUCT is a function that multiplies two integers, you cannot
enter the EVALUATE PRODUCT(3,5) command. If your program assigns the
returned value of a function to a variable, you can examine the resulting value of
that variable.
If an expression contains symbols with different compiler generated types, the
debugger uses the type-conversion rules of the current language to evaluate
the expression. If the types are incompatible, a diagnostic message is issued.
Debugger support for operators and other constructs in language expressions is
listed in the debugger’s online help for each language (type HELP Language).
The built-in symbol %CURVAL denotes the current value—the value last
displayed by an EVALUATE or EXAMINE command or deposited by a DEPOSIT
command. The backslash ( \ ) also denotes the current value when used in that
context. For example:
4–6
Examining and Manipulating Program Data
4.1 General Concepts
DBG> EXAMINE X
MOD3\X: 23
DBG> EVALUATE %CURVAL
23
DBG> DEPOSIT Y = 47
DBG> EVALUATE \
47
DBG>
4.1.6.1 Using Variables in Language Expressions
You can use variables in language expressions in much the same way that you
use them in the source code of your program.
Thus, the debugger generally interprets a variable used in a language expression
as the current value of that variable, not the address of the variable. For example
(X is an integer variable):
DBG> DEPOSIT X = 12
DBG> EXAMINE X
MOD4\X: 12
DBG> EVALUATE X
12
DBG> EVALUATE X + 4
16
DBG> DEPOSIT X = X/2
DBG> EXAMINE X
MOD4\X: 6
DBG>
! Assign the value 12 to X.
! Display the value of X.
! Evaluate and display the value of X.
! Add the value of X to 4.
! Divide the value of X by 2 and assign
! the resulting value to X.
! Display the new value of X.
Using a variable in a language expression as shown in the previous examples
is generally limited to single-valued, noncomposite variables. Typically, you can
specify a multivalued, composite variable (like an array or record) in a language
expression only if the syntax indicates that you are referencing only a single
value (a single element of the aggregate). For example, if ARR is the name of an
array of integers, the following command is invalid:
DBG> EVALUATE ARR
%DEBUG-W-NOVALUE, reference does not have a value
DBG>
However, the following commands are valid because only a single element of the
array is referenced:
DBG> EVALUATE ARR(2)
! Evaluate element 2 of array ARR.
37
DBG> DEPOSIT K = 5 + ARR(2) ! Deposit the sum of two integer
DBG>
! values into an integer variable.
If the current language is BLISS, the debugger interprets a variable in a language
expression as the address of that variable. To denote the value stored in a
variable, you must use the contents-of operator (period ( . )). For example, when
the language is set to BLISS:
4–7
Examining and Manipulating Program Data
4.1 General Concepts
DBG> EXAMINE Y
MOD4\Y: 3
DBG> EVALUATE Y
02475B
DBG> EVALUATE .Y
3
DBG> EVALUATE Y + 4
02475F
DBG> EVALUATE .Y + 4
7
DBG>
! Display the value of Y.
! Display the address of Y.
! Display the value of Y.
!
!
!
!
Add 4 to the address of Y and
display the resulting value.
Add 4 to the value of Y and display
the resulting value.
For all languages, to obtain the address of a variable, use the
EVALUATE/ADDRESS command as described in Section 4.1.11. The EVALUATE
and EVALUATE/ADDRESS commands both display the address of an address
expression when the language is set to BLISS.
4.1.6.2 Numeric Type Conversion by the Debugger
When evaluating language expressions involving numeric types of different
precision, the debugger first converts lower-precision types to higher-precision
types before performing the evaluation. In the following example, the debugger
converts the integer 1 to the real 1.0 before doing the addition:
DBG> EVALUATE 1.5 + 1
2.5
DBG>
The basic rules are as follows:
•
If integer and real types are mixed, the integer type is converted to the real
type.
•
If integer types of different sizes are mixed (for example, byte-integer and
word-integer), the one with the smaller size is converted to the larger size.
•
If real types of different sizes are mixed (for example, S_float and T_float), the
one with the smaller size is converted to the larger size.
In general, the debugger allows more numeric type conversion than the
programming language. In addition, the hardware type used for a debugger
calculation (word, longword, S_float, and so on) might differ from that chosen by
the compiler. Because the debugger is not as strongly typed or as precise as some
languages, the evaluation of an expression by the EVALUATE command might
differ from the result that would be calculated by compiler-generated code and
obtained with the EXAMINE command.
4.1.7 Address Expressions Compared to Language Expressions
Do not confuse address expressions with language expressions. An address
expression specifies a program location; a language expression specifies a value.
In particular, the EXAMINE command expects an address expression as its
parameter, and the EVALUATE command expects a language expression as its
parameter. These points are shown in the next examples.
In the following example, the value 12 is deposited into the variable X. This is
confirmed by the EXAMINE command. The EVALUATE command computes and
displays the sum of the current value of X and the integer literal 6,
4–8
Examining and Manipulating Program Data
4.1 General Concepts
DBG> DEPOSIT X = 12
DBG> EXAMINE X
MOD3\X: 12
DBG> EVALUATE X + 6
18
DBG>
In the next example, the EXAMINE command displays the value currently stored
at the memory location that is 6 bytes beyond the address of X:
DBG> EXAMINE X + 6
MOD3\X+6: 274903
DBG>
In this case the location is not associated with a compiler-generated type.
Therefore, the debugger interprets and displays the value stored at that location
in the type longword integer (see Section 4.1.5).
In the next example, the value of X + 6 (that is, 18) is deposited into the location
that is 6 bytes beyond the address of X. This is confirmed by the last EXAMINE
command.
DBG> EXAMINE
MOD3\X: 12
DBG> DEPOSIT
DBG> EXAMINE
MOD3\X: 12
DBG> EXAMINE
MOD3\X+6: 18
DBG>
X
X + 6 = X + 6
X
X + 6
4.1.8 Specifying the Current, Previous, and Next Entity
When using the EXAMINE and DEPOSIT commands, you can use three special
built-in symbols (address expressions) to refer quickly to the current, previous,
and next data locations (logical entities). These are the period ( . ), the circumflex
( ^ ), and the Return key.
The period ( . ), when used by itself with an EXAMINE or DEPOSIT command,
denotes the current entity—that is, the program location most recently referenced
by an EXAMINE or DEPOSIT command. For example:
DBG> EXAMINE X
SIZE\X: 7
DBG> DEPOSIT . = 12
DBG> EXAMINE .
SIZE\X: 12
DBG>
The circumflex ( ^ ) and Return key denote, respectively, the previous and next
logical data locations relative to the last EXAMINE or DEPOSIT command (the
logical predecessor and successor, respectively). The circumflex and Return key
are useful for referring to consecutive indexed components of an array. The
following example shows the use of these operators with an array of integers,
ARR:
4–9
Examining and Manipulating Program Data
4.1 General Concepts
DBG> EXAMINE
MAIN\ARR(5):
DBG> EXAMINE
MAIN\ARR(4):
DBG> EXAMINE
MAIN\ARR(5):
DBG> EXAMINE
MAIN\ARR(6):
DBG>
ARR(5)
448670
^
792802
Return
! Examine element 5 of array ARR.
! Examine the previous element (4).
! Examine the next element (5).
448670
Return
! Examine the next element (6).
891236
The debugger uses the type associated with the current entity to determine
logical successors and predecessors.
You can also use the built-in symbols %CURLOC, %PREVLOC, and %NEXTLOC
to achieve the same purpose as the period, circumflex, and Return key,
respectively. These symbols are useful in command procedures and also if
your program uses the circumflex for other purposes. Moreover, using the Return
key to signify the logical successor does not apply to all contexts. For example,
you cannot press the Return key after entering the DEPOSIT command to
indicate the next location, but you can always use the symbol %NEXTLOC for
that purpose.
Note that, like EXAMINE and DEPOSIT, the EVALUATE/ADDRESS command
also resets the values of the current, previous, and next logical-entity built-in
symbols (see Section 4.1.11). However, you cannot press the Return key after
entering the EVALUATE/ADDRESS command to indicate the next location. For
more information about debugger built-in symbols, see Appendix B.
The previous examples show the use of the built-in symbols after referencing a
symbolic name with the EXAMINE or DEPOSIT command. If you examine or
deposit into a memory address, that location might or might not be associated
with a compiler-generated type. When you reference a memory address, the
debugger uses the following conventions to determine logical predecessors and
successors:
•
If the address has a symbolic name (the name of a variable, component of
a composite variable, routine, and so on), the debugger uses the associated
compiler-generated type.
•
If the address does not have a symbolic name, the debugger uses the type
longword integer by default.
As the current entity is reset with new examine or deposit operations, the
debugger associates each new location with a type in the manner indicated to
determine logical successors and predecessors. This is shown in the following
examples.
Assume that a Fortran program has declared three variables, ARY, FLT, and
BTE, as follows:
•
ARY is an array of three word integers (2 bytes each)
•
FLT is an F_floating type (4 bytes)
•
BTE is a byte integer (1 byte)
Assume that storage for these variables has been allocated at consecutive
addresses in memory, starting with 1000. For example:
4–10
Examining and Manipulating Program Data
4.1 General Concepts
1000:
1002:
1004:
1006:
1010:
1011:
.
.
.
ARY(1)
ARY(2)
ARY(3)
FLT
BTE
undefined
Examining successive logical data locations will give the following results:
DBG> EXAMINE 1000
! Examine ARY(1), associated with 1000.
MOD3\ARY(1): 13
! Current entity is now ARY(1).
DBG> EXAMINE
! Examine next location, ARY(2),
MOD3\ARY(2): 7
! using type of ARY(1) as reference.
DBG> EXAMINE
! Examine next location, ARY(3).
MOD3\ARY(3): 19
! Current entity is now ARY(3).
DBG> EXAMINE
! Examine entity at 1006 (FLT).
MOD3\FLT: 1.9117807E+07 ! Current entity is now FLT.
DBG> EXAMINE
! Examine entity at 1010 (BTE).
MOD3\BTE: 43
! Current entity is now BTE.
DBG> EXAMINE
! Examine entity at 1011 (undefined).
1011: 17694732
! Interpret data as longword integer.
DBG>
! Location is not symbolized.
The same principles apply when you use type qualifiers with the EXAMINE
and DEPOSIT commands (see Section 4.5.2). The type specified by the qualifier
determines the data boundary of an entity and, therefore, any logical successors
and predecessors.
4.1.9 Language Dependencies and the Current Language
The debugger enables you to set your debugging context to any of several
supported languages. The setting of the current language determines how the
debugger parses and interprets the names, numbers, operators, and expressions
you specify in debugger commands, and how it displays data.
By default, the current language is the language of the module containing the
main program, and it is identified when you bring the program under debugger
control. For example:
$ PASCAL/NOOPTIMIZE/DEBUG TEST1
$ LINK/DEBUG TEST1
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG> RUN TEST1
Language: PASCAL, Module: TEST1
DBG>
When debugging modules whose code is written in other languages, you can use
the SET LANGUAGE command to establish a new language-dependent context.
Section 14.3 highlights some important language differences. Debugger support
for operators and other constructs in language expressions is listed for each
language in the debugger’s online help (type HELP Language).
4–11
Examining and Manipulating Program Data
4.1 General Concepts
4.1.10 Specifying a Radix for Entering or Displaying Integer Data
The debugger can interpret and display integer data in any one of four radixes:
decimal, hexadecimal, octal, and binary. The default radix is decimal for most
languages.
On Alpha processors, the exceptions are BLISS, MACRO–32 and MACRO–64,
which have a default radix of hexadecimal.
You can control the radix for the following kinds of integer data:
•
Data that you specify in address expressions or language expressions
•
Data that is displayed by the EVALUATE and EXAMINE commands
You cannot control the radix for other kinds of integer data. For example,
addresses are always displayed in hexadecimal radix in a SHOW CALLS display.
Or, when specifying an integer n with various command qualifiers (/AFTER:n,
/UP:n, and so on), you must use decimal radix.
The technique you use to control radix depends on your objective. To establish
a new radix for all subsequent commands, use the SET RADIX command. For
example:
DBG> SET RADIX HEXADECIMAL
After this command is executed, all integer data that you enter in address or
language expressions is interpreted as being hexadecimal. Also, all integer data
displayed by the EVALUATE and EXAMINE commands is given in hexadecimal
radix.
The SHOW RADIX command identifies the current radix (which is either the
default radix, or the radix last established by a SET RADIX command). For
example:
DBG> SHOW RADIX
input radix: hexadecimal
output radix: hexadecimal
DBG>
The SHOW RADIX command identifies both the input radix (for data entry)
and the output radix (for data display). The SET RADIX command qualifiers
/INPUT and /OUTPUT enable you to specify different radixes for data entry and
display. For more information, see the SET RADIX command.
Use the CANCEL RADIX command to restore the default radix.
The examples that follow show several techniques for displaying or entering
integer data in another radix without changing the current radix.
To convert some integer data to another radix without changing the current
radix, use the EVALUATE command with a radix qualifier (/BINARY, /DECIMAL,
/HEXADECIMAL, /OCTAL). For example:
DBG> SHOW RADIX
input radix: decimal
output radix: decimal
DBG> EVALUATE 18 + 5
23
DBG> EVALUATE/HEX 18 + 5
00000017
DBG>
4–12
! 23 is decimal integer.
! 17 is hexadecimal integer.
Examining and Manipulating Program Data
4.1 General Concepts
The radix qualifiers do not affect the radix for data entry.
To display the current value of an integer variable (or the contents of a program
location that has an integer type) in another radix, use the EXAMINE command
with a radix qualifier. For example:
DBG> EXAMINE X
MOD4\X: 4398
DBG> EXAMINE/OCTAL .
MOD4\X: 00000010456
DBG>
! 4398 is a decimal integer.
! X is the current entity.
! 10456 is an octal integer.
To enter one or more integer literals in another radix without changing the
current radix, use one of the radix built-in symbols %BIN, %DEC, %HEX, or
%OCT. A radix built-in symbol directs the debugger to treat an integer literal
that follows (or all numeric literals in a parenthesized expression that follows) as
a binary, decimal, hexadecimal, or octal number, respectively. These symbols do
not affect the radix for data display. For example:
DBG> SHOW RADIX
input radix: decimal
output radix: decimal
DBG> EVAL %BIN 10
2
DBG> EVAL %HEX (10 + 10)
32
DBG> EVAL %HEX 20 + 33
65
DBG> EVAL/HEX %OCT 4672
000009BA
DBG> EXAMINE X + %DEC 12
MOD3\X+12: 493847
DBG> DEPOS J = %OCT 7777777
DBG> EXAMINE .
MOD3\J: 2097151
DBG> EXAMINE/OCTAL .
MOD3\J: 00007777777
DBG> EXAMINE %HEX 0A34D
SHARE$LIBRTL+4941: 344938193
DBG>
!
!
!
!
!
!
!
!
!
!
!
!
Evaluate the binary integer 10.
2 is a decimal integer.
Evaluate the hexadecimal integer 20.
32 is a decimal integer.
Treat 20 as hexadecimal, 33 as decimal.
65 is a decimal integer.
Treat 4672 as octal and display in hex.
9BA is a hexadecimal number.
Examine the location 12 decimal bytes
beyond the address of X.
Deposit an octal value.
Display that value in decimal radix.
! Display that value in octal radix.
! Examine location A34D, hexadecimal.
! 344938193 is a decimal integer.
Note
When specifying a hexadecimal integer that starts with a letter rather
than a number (for example, A34D in the last example), add a leading
0. Otherwise, the debugger tries to interpret the integer as a symbol
declared in your program.
For more examples showing the use of the radix built-in symbols, see
Appendix B.
4.1.11 Obtaining and Symbolizing Memory Addresses
Use the EVALUATE/ADDRESS command to determine the memory address
or the register name associated with a symbolic address expression, such as a
variable name, line number, routine name, or label. For example:
4–13
Examining and Manipulating Program Data
4.1 General Concepts
DBG> EVALUATE/ADDRESS X
! A variable name
2476
DBG> EVALUATE/ADDRESS SWAP
! A routine name
1536
DBG> EVALUATE/ADDRESS %LINE 26
1629
DBG>
The address is displayed in the current radix (as defined in Section 4.1.10). You
can specify a radix qualifier to display the address in another radix. For example:
DBG> EVALUATE/ADDRESS/HEX X
000009AC
DBG>
If a variable is associated with a register instead of a memory address, the
EVALUATE/ADDRESS command displays the name of the register, regardless of
whether a radix qualifier is used. The following command indicates that variable
K (a nonstatic variable) is associated with register R2:
DBG> EVALUATE/ADDRESS K
%R2
DBG>
Like the EXAMINE and DEPOSIT commands, EVALUATE/ADDRESS resets
the values of the current, previous, and next logical-entity built-in symbols (see
Section 4.1.8). Unlike the EVALUATE command, EVALUATE/ADDRESS does not
affect the current-value built-in symbols %CURVAL and backslash ( \ ).
The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS, but
without affecting the current, previous, or next logical-entity built-in symbols. It
converts a memory address or a register name into its symbolic representation
(including its path name) if such a representation is possible (Chapter 5 explains
how to control symbolization). For example, the following command shows that
variable K is associated with register R2:
DBG> SYMBOLIZE %R2
address MOD3\%R2:
MOD3\K
DBG>
By default, symbolic mode is in effect (SET MODE SYMBOLIC). Therefore, the
debugger displays all addresses symbolically if symbols are available for the
addresses. For example, if you specify a numeric address with the EXAMINE
command, the address is displayed in symbolic form if symbolic information is
available:
DBG> EVALUATE/ADDRESS X
2476
DBG> EXAMINE 2476
MOD3\X: 16
DBG>
However, if you specify a register that is associated with a variable, the
EXAMINE command does not convert the register name to the variable name.
For example:
4–14
Examining and Manipulating Program Data
4.1 General Concepts
DBG> EVALUATE/ADDRESS K
%R2
DBG> EXAMINE %R2
MOD3\%R2: 78
DBG>
By entering the SET MODE NOSYMBOLIC command, you disable symbolic mode
and cause the debugger to display numeric addresses rather than their symbolic
names. When symbolization is disabled, the debugger might process commands
somewhat faster because it does not need to convert numbers to names. The
EXAMINE command has a /[NO]SYMBOLIC qualifier that enables you to control
symbolization for a single EXAMINE command. For example:
DBG> EVALUATE/ADDRESS Y
512
DBG> EXAMINE 512
MOD3\Y: 28
DBG> EXAMINE/NOSYMBOLIC 512
512: 28
DBG>
Symbolic mode also affects the display of instructions.
For example, on Integrity servers:
DBG> EXAMINE/INSTRUCTION .%PC
HELLO\main\%LINE 8: add
r34=200028, r1
DBG> EXAMINE/NOSYMBOL/INSTRUCTION .%PC
65969:
add
r34 = 200028, r1
DBG>
4.2 Examining and Depositing into Variables
The examples in this section show how to use the EXAMINE and DEPOSIT
commands with variables.
Languages differ in the types of variables they use, the names for these types,
and the degree to which different types can be intermixed in expressions. The
following generic types are discussed in this section:
•
Scalars (such as integer, real, character, or Boolean)
•
Strings
•
Arrays
•
Records
•
Pointers (access types)
The most important consideration when examining and manipulating variables in
high-level language programs is that the debugger recognizes the names, syntax,
type constraints, and scoping rules of the variables in your program. Therefore,
when specifying a variable with the EXAMINE or DEPOSIT command, you use
the same syntax that is used in the source code. The debugger processes and
displays the data accordingly. Similarly, when assigning a value to a variable, the
debugger follows the typing rules of the language. It issues a diagnostic message
if you try to deposit an incompatible value. The examples in this section show
some of these invalid operations and the resulting diagnostics.
4–15
Examining and Manipulating Program Data
4.2 Examining and Depositing into Variables
When using the DEPOSIT command (or any other command), note the following
behavior. If the debugger issues a diagnostic message with a severity level of I
(informational), the command is still executed (the deposit is made in this case).
The debugger aborts an illegal command line only when the severity level of the
message is W (warning) or greater.
For additional language-specific information, see the debugger’s online help (type
HELP Language).
4.2.1 Scalar Types
The following examples show use of the EXAMINE, DEPOSIT, and EVALUATE
commands with some integer, real, and Boolean types.
Examine a list of three integer variables:
DBG> EXAMINE
SIZE\WIDTH:
SIZE\LENGTH:
SIZE\AREA:
DBG>
WIDTH, LENGTH, AREA
4
7
28
Deposit an integer expression:
DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10
DBG>
The debugger checks that a value to be assigned is compatible with the data type
and dimensional constraints of the variable. The following example shows an
attempt to deposit an out-of-bounds value (X was declared as a positive integer):
DBG> DEPOSIT X = -14
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT
DBG>
If you try to mix numeric types (integer and real of varying precision) in a
language expression, the debugger generally follows the rules of the language.
Strongly typed languages do not allow much, if any, mixing. With some
languages, you can deposit a real value into an integer variable. However,
the real value is converted into an integer. For example:
DBG> DEPOSIT I = 12345
DBG> EXAMINE I
MOD3\I: 12345
DBG> DEPOSIT I = 123.45
DBG> EXAMINE I
MOD3\I: 123
DBG>
If numeric types are mixed in an expression, the debugger performs type
conversion as discussed in Section 4.1.6.2. For example:
4–16
Examining and Manipulating Program Data
4.2 Examining and Depositing into Variables
DBG> DEPOSIT Y = 2.356
DBG> EXAMINE Y
MOD3\Y: 2.35600000000000
DBG> EVALUATE Y + 3
5.35600000000000
DBG> DEPOSIT R = 5.35E3
DBG> EXAMINE R
MOD3\R: 5350.000
DBG> EVALUATE R*50
267500.0
DBG> DEPOSIT I = 22222
DBG> EVALUATE R/I
0.2407524
DBG>
! Y is of type G_floating point.
! R is of type F_floating point.
The next example shows some operations with Boolean variables. The values
TRUE and FALSE are assigned to the variables WILLING and ABLE,
respectively. The EVALUATE command then obtains the logical conjunction
of these values.
DBG> DEPOSIT WILLING = TRUE
DBG> DEPOSIT ABLE = FALSE
DBG> EVALUATE WILLING AND ABLE
False
DBG>
4.2.2 ASCII String Types
When displaying an ASCII string value, the debugger encloses it within quotation
marks ( " ) or apostrophes (’), depending on the language syntax. For example:
DBG> EXAMINE EMPLOYEE_NAME
PAYROLL\EMPLOYEE_NAME:
"Peter C. Lombardi"
DBG>
To deposit a string value (including a single character) into a string variable, you
must enclose the value in quotation marks ( " ) or apostrophes (’). For example:
DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84"
DBG>
If the string has more ASCII characters (1 byte each) than can fit into the location
denoted by the address expression, the debugger truncates the extra characters
from the right and issues the following message:
%DEBUG-I-ISTRTRU, string truncated at or near DEPOSIT
If the string has fewer characters, the debugger pads the remaining characters to
the right of the string by inserting ASCII space characters.
4.2.3 Array Types
You can examine an entire array aggregate, a single indexed element, or a slice
(a range of elements). However, you can deposit into only one element at a time.
The following examples show typical operations with arrays.
The following command displays the values of all the elements of the array
variable ARRX, a one-dimensional array of integers:
4–17
Examining and Manipulating Program Data
4.2 Examining and Depositing into Variables
DBG> EXAMINE ARRX
MOD3\ARRX
(1):
42
(2):
17
(3):
278
(4):
56
(5):
113
(6):
149
DBG>
The following command displays the value of element 4 of array ARRX (depending
on the language, parentheses or brackets are used to denote indexed elements):
DBG> EXAMINE ARRX(4)
MOD3\ARRX(4): 56
DBG>
The following command displays the values of all the elements in a slice of ARRX.
This slice consists of the range of elements from element 2 to element 5:
DBG> EXAMINE ARRX(2:5)
MOD3\ARRX
(2):
17
(3):
278
(4):
56
(5):
113
DBG>
In general, a range of values to be examined is denoted by two values separated
by a colon (value1:value2). Depending on the language, two periods ( .. ) can be
used instead of a colon.
You can deposit a value to only a single array element at a time (you cannot
deposit to an array slice or an entire array aggregate with a single DEPOSIT
command). For example, the following command deposits the value 53 into
element 2 of ARRX:
DBG> DEPOSIT ARRX(2) = 53
DBG>
The following command displays the values of all the elements of array REAL_
ARRAY, a two-dimensional array of real numbers (three per dimension):
DBG> EXAMINE REAL_ARRAY
PROG2\REAL_ARRAY
(1,1):
27.01000
(1,2):
31.00000
(1,3):
12.48000
(2,1):
15.08000
(2,2):
22.30000
(2,3):
18.73000
DBG>
The debugger issues a diagnostic message if you try to deposit to an index value
that is out of bounds. For example:
DBG> DEPOSIT REAL_ARRAY(1,4) = 26.13
%DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4,
bounds are 1..3
DBG>
4–18
Examining and Manipulating Program Data
4.2 Examining and Depositing into Variables
In the previous example, the deposit operation was executed because the
diagnostic message is of I level. This means that the value of some array element
adjacent to (1,3), possibly (2,1) might have been affected by the out-of-bounds
deposit operation.
To deposit the same value to several components of an array, you can use a
looping command such as FOR or REPEAT. For example, assign the value RED
to elements 1 to 4 of the array COLOR_ARRAY:
DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR_ARRAY(I) = RED)
DBG>
You can also use the built-in symbols ( . ) and ( ^ ) to step through array elements,
as explained in Section 4.1.8.
4.2.4 Record Types
Note
The generic term record is used here to denote a data structure whose
elements have heterogeneous data types—what is called a struct type in
the C language.
You can examine an entire record aggregate, a single record component, or several
components. However, you can deposit into only one component at a time. The
following examples show typical operations with records.
The following command displays the values of all the components of the record
variable PART:
DBG> EXAMINE PART
INVENTORY\PART:
ITEM:
"WF-1247"
PRICE:
49.95
IN_STOCK: 24
DBG>
The following command displays the value of component IN_STOCK of record
PART (general syntax):
DBG> EXAMINE PART.IN_STOCK
INVENTORY\PART.IN_STOCK: 24
DBG>
The following command displays the value of the same record component using
COBOL syntax (the language must be set to COBOL):
DBG> EXAMINE IN_STOCK OF PART
INVENTORY\IN_STOCK of PART:
IN_STOCK: 24
DBG>
The following command displays the values of two components of record PART:
DBG> EXAMINE PART.ITEM, PART.IN_STOCK
INVENTORY\PART.ITEM:
"WF-1247"
INVENTORY\PART.IN_STOCK: 24
DBG>
4–19
Examining and Manipulating Program Data
4.2 Examining and Depositing into Variables
The following command deposits a value into record component IN_STOCK:
DBG> DEPOSIT PART.IN_STOCK = 17
DBG>
4.2.5 Pointer (Access) Types
You can examine the entity designated (pointed to) by a pointer variable and
deposit a value into that entity. You can also examine a pointer variable.
For example, the following Pascal code declares a pointer variable A that
designates a value of type real:
.
.
.
TYPE
T = ^REAL;
VAR
A : T;
.
.
.
The following command displays the value of the entity designated by the pointer
variable A:
DBG> EXAMINE A^
MOD3\A^: 1.7
DBG>
In the following example, the value 3.9 is deposited into the entity designated by
A:
DBG> DEPOSIT A^ = 3.9
DBG> EXAMINE A^
MOD3\A^: 3.9
DBG>
When you specify the name of a pointer variable with the EXAMINE command,
the debugger displays the memory address of the object it designates. For
example:
DBG> EXAMINE/HEXADECIMAL A
SAMPLE\A: 0000B2A4
DBG>
4.3 Examining and Depositing Instructions
The debugger recognizes address expressions that are associated with
instructions. This enables you to examine and deposit instructions using the
same basic techniques as with variables.
When debugging at the instruction level, you might find it convenient to first
enter the following command. It sets the default step mode to stepping by
instruction:
DBG> SET STEP INSTRUCTION
DBG>
4–20
Examining and Manipulating Program Data
4.3 Examining and Depositing Instructions
There are other step modes that enable you to execute the program to specific
kinds of instructions. You can also set breakpoints to interrupt execution at these
instructions.
In addition, you can use a screen-mode instruction display (see Section 7.4.4) to
display the actual decoded instruction stream of your program.
4.3.1 Examining Instructions
If you specify an address expression that is associated with an instruction in an
EXAMINE command (for example, a line number), the debugger displays the
first instruction at that location. You can then use the period ( . ), Return key,
and circumflex ( ^ ) to display the current, next, and previous instruction (logical
entity), as described in Section 4.1.8.
For example, on Alpha processors:
DBG> EXAMINE %LINE
MOD3\%LINE 12:
DBG> EXAMINE
MOD3\%LINE 12+4:
DBG> EXAMINE
MOD3\%LINE 12+8:
DBG> EXAMINE ^
MOD3\%LINE 12+4:
DBG>
12
BIS
R31,R31,R2
BIS
R31,R2,R0 ! Next instruction
ADDL
R31,R0,R0 ! Next instruction
BIS
R31,R2,R0 ! Previous instruction
Line numbers, routine names, and labels are symbolic address expressions that
are associated with instructions. In addition, instructions might be stored in
various other memory addresses and in certain registers during the execution of
your program.
The program counter (PC) is the register that contains the address of the next
instruction to be executed by your program. The command EXAMINE .%PC
displays that instruction. The period ( . ), when used directly in front of an
address expression, denotes the contents of operator—that is, the contents of the
location designated by the address expression. Note the following distinction:
•
EXAMINE %PC displays the current PC value, namely the address of the
next instruction to be executed.
•
EXAMINE .%PC displays the contents of that address, namely the next
instruction to be executed by the program.
As shown in the previous examples, the debugger knows whether an address
expression is associated with an instruction. If it is, the EXAMINE command
displays that instruction (you do not need to use the /INSTRUCTION
qualifier). You use the /INSTRUCTION qualifier to display the contents
of an arbitrary program location as an instruction—that is, the command
EXAMINE/INSTRUCTION causes the debugger to interpret and format the
contents of any program location as an instruction (see Section 4.5.2).
When you examine consecutive instructions in a MACRO-32 program, the
debugger might misinterpret data as instructions if storage for the data is
allocated in the middle of a stream of instructions. The following example shows
this problem. It shows some MACRO-32 code with two longwords of data storage
allocated directly after the BRB instruction at line 7 (line numbers have been
added to the example for clarity).
4–21
Examining and Manipulating Program Data
4.3 Examining and Depositing Instructions
module TEST
1:
.TITLE
2:
3: TEST$START::
4:
.WORD
5:
6:
MOVL
7:
BRB
8:
9:
.LONG
10:
.LONG
11:
12: LABEL_2:
13:
MOVL
14:
15:
.END
TEST
0
#2,R2
LABEL_2
^X12345
^X14465
#5,R5
TEST$START
The following EXAMINE command displays the instruction at the start of line 6:
DBG> EXAMINE %LINE 6
TEST\TEST$START\%LINE 6: MOVL
DBG>
S^#02,R2
The following EXAMINE command correctly interprets and displays the logical
successor entity as an instruction at line 7:
DBG> EXAMINE
TEST\TEST$START\%LINE 7: BRB
DBG>
TEST\TEST$START\LABEL_2
However, the following three EXAMINE commands incorrectly interpret the three
logical successors as instructions:
DBG> EXAMINE
TEST\TEST$START\%LINE 7+2: MULF3 S^#11.00000,S^#0.5625000,S^#0.5000000
DBG> EXAMINE
%DEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes
TEST\TEST$START\%LINE 7+6: MULD3 S^#0.5625000[R4],S^#0.5000000,@W^5505(R0)
DBG> EXAMINE
TEST$START+12: HALT
DBG>
4.4 Examining and Depositing into Registers
The EXAMINE command displays contents of any register that is accessible
in your program. You can use the DEPOSIT command to change the contents
of these registers. The number and type of registers vary for each OpenVMS
platform, as described in the following sections.
4.4.1 Examing and Depositing into Alpha Registers
On Alpha processors, the Alpha architecture provides 32 general (integer)
registers and 32 floating-point registers, some of which are used for temporary
address and data storage. Table 4–1 identifies the debugger built-in symbols that
refer to Alpha registers.
4–22
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
Table 4–1 Debugger Symbols for Alpha Registers
Symbol
Description
Alpha Integer Registers
%R0 . . . %R28
Registers R0 . . . R28
%FP (%R29)
Stack frame base register (FP)
%SP (%R30)
Stack pointer (SP)
%R31
ReadAsZero/Sink (RZ)
%PC
Program counter (PC)
%PS
Processor status register (PS). The built-in symbols %PSL and
%PSW are disabled for Alpha processors.
Alpha Floating-Point Registers
%F0 . . . %F30
Registers F0 . . . F30
%F31
ReadAsZero/Sink
On Alpha processors:
•
You can omit the percent sign ( % ) prefix if your program has not declared a
symbol with the same name.
•
You cannot deposit a value into register R30.
•
You cannot deposit a value into registers R31 or F31. They are permanently
assigned the value 0.
•
There are no vector registers.
The following examples show how to examine and deposit into registers:
DBG> SHOW TYPE
type: long integer
DBG> SHOW RADIX
input radix: decimal
output radix: decimal
DBG> EXAMINE %R11
MOD3\%R11: 1024
DBG> DEPOSIT %R11 = 444
DBG> EXAMINE %R11
R11: 444
DBG> EXAMINE %PC
MOD\%PC: 1553
DBG> EXAMINE %SP
0\%SP: 2147278720
DBG>
! Show type for locations without
! a compiler-generated type.
! Identify current radix.
! Display value in R11.
! Deposit new value into R11.
! Check new value.
! Display value in program counter.
! Display value in stack pointer.
See Section 4.3.1 for specific information about the PC.
Processor Status (Alpha Only)
On Alpha processors, the processor status (PS) is a register whose value
represents a number of processor state variables. The first three bits of the
PS are reserved for the use of the software. The values of these bits can be
controlled by a user program. The remainder of the bits, bits 4 to 64, contain
privileged information and cannot be altered by a user-mode program.
4–23
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
The following example shows how to examine the contents of the PS:
DBG> EXAMINE %PS
MOD1\%PS:
SP_ALIGN IPL VMM CM
48
0 0 USER
DBG>
IP SW
0 3
See the Alpha Architecture Reference Manual for complete information about the
PS, including the values of the various bits.
You can also display the information in the PS in other formats. For example:
DBG> EXAMINE/LONG/HEX %PS
MOD1\%PS:
0000001B
DBG> EXAMINE/LONG/BIN %PS
MOD1\%PS:
00000000 00000000 00000000 00011011
DBG>
The command EXAMINE/PS displays the value at any location in PS format.
This is useful for examining the combined current and saved PS values.
4.4.2 Examing and Depositing into Integrity server Registers
On Integrity server processors, the Integrity server architecture provides:
•
Up to 128 64-bit general registers
•
Up to 128 82-bit floating-point registers (the debugger allows you to treat
these as full octawords),
•
Up to 64 1-bit predicate, 8 64-bit branch, and 128 (only 20 are accessible/used)
application registers
•
Special registers (for example, %PC) and viritual registers (for example,
%RETURN_PC)
Most of these registers are read/writable from user mode debug. Some, however,
are not writable and others are only accessible from the higher privileges related
with the System Code Debugger (SCD) configuration (see OpenVMS Alpha System
Analysis Tools Manual).
Table 4–2 Debugger Symbols for Integrity server Registers
Symbol
Description
Integrity server Application Registers
%KR0 . . . %KR7
Kernel registers 0 . . . 7
%RSC (%AR16)
Register Stack Configuration
%BSP (%AR17)
Backing Store Pointer
%BSPSTORE
(%AR18)
Backing Store Pointer for Memory Stores
%RNAT (%AR19)
RSE NaT Collection
%CCV ($AR32)
Compare and Exchange Compare Value
%UNAT (%AR36)
User NaT Collection
(continued on next page)
4–24
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
Table 4–2 (Cont.) Debugger Symbols for Integrity server Registers
Symbol
Description
Integrity server Application Registers
%FPSR (%AR40)
Floating-point Status
%PFS (%AR64)
Previous Function State
%LC (%AR65)
Loop Count
%EC (%AR66)
Epilog Count
%CSD
Code Segment
%SSD
Stack Segment
Control Registers
%DCR (%CR0)
Default Control
%ITM (%CR1)
Interval Timer Match (only visible for SCD)
%IVA (%CR2)
Interruption Vector Address (only visible for SCD)
%PTA (%CR8)
Page Table Address (only visible for SCD)
%PSR (%CR9,
%ISPR)
Interruption Processor Status
%ISR (%CR17)
Interruption Status
%IIP (%CR19)
Interruption Instruction Pointer
%IFA (%CR20)
Interruption Faulting Address
%ITIR (%CR21)
Interruption TLB Insertion
%IIPA (%CR22)
Interruption Instruction Previous
%IFS (%CR23)
Interruption Function State
%IIM (%CR24)
Interruption Immediate
%IHA (%CR25)
Interruption Hash Address
%LID (%CR64)
Local Interrupt ID (only visible for SCD)
%TPR (%CR66)
Task Priority (only visible for SCD)
%IRR0 . . . %IRR3
(%CR68 . . .
%CR71)
External Interrupt Request 0 . . . 3 (only visible for SCD)
%ITV (%CR72)
Interval Timer (only visible for SCD)
%PMV (%CR73)
Performance Monitoring (only visible for SCD)
%CMCV (%CR74)
Corrected Machine Check Vector (only visible for SCD)
%IRR0 and %IRR1
(%CR80 and
%CR81)
Local Redirection 0:1 (only visible for SCD)
(continued on next page)
4–25
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
Table 4–2 (Cont.) Debugger Symbols for Integrity server Registers
Symbol
Description
Special Registers
%IH (%SR0)
Invocation Handle
%PREV_BSP
Previous Backing Store Pointer
%PC (%IP)
Program Counter (Instruction Pointer | slot number)
%RETURN_PC
Return Program Counter
%CFM
Current Frame Marker
%NEXT_PFS
Next Previous Frame State
%PSP
Previous Stack Pointer
%CHFCTX_ADDR
Condition Handling Facility Context Address
%OSSD
Operating System Specific Data
%HANDLER_FV
Handler Function Value
%LSDA
Language Specific Data Area
%UM
User Mask
Predicate Registers
%PR (%PRED)
Predicate Collection Register—Collection of %P0 . . . %P63
%P0 . . . %P63
Predicate (single-bit)Registers 0 . . . 63
Branch Registers
%RP (%B0)
Return Pointer
%B1 . . . %B7
Branch Registers 1 . . . 7
General Integer Registers
%R0
General Integer Register 0
%GP (%R1)
Global Data Pointer
%R2 . . . %R11
General Integer Registers 2 . . . 11
%SP (%R12)
Stack Pointer
%TP (%R13)
Thread Pointer
%R14 . . . %R24
General Integer Registers 14 . . . 24
%AP (%R25)
Argument Information
%R26 . . . %R127
General Integer Registers 26 . . . 127
Output Registers
%OUT0 . . .
%OUT7
Output Registers, runtime aliases (i.e., If the frame has allocated
output registers, then %OUT0 maps to the first allocated output
registers, for example, %R38, etc.)
(continued on next page)
4–26
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
Table 4–2 (Cont.) Debugger Symbols for Integrity server Registers
Symbol
Description
General Registers
%GRNAT0 and
%GRNAT1
General Register Not A Thing (NAT) collection registers 64 bits
each, for example, %GRNAT0<3,1,0> is the NAT bit for %R3.
Floating Point Registers
%F0 . . . %F127
Floating Point Registers 0 . . . 127
On Integrity server processors:
•
You can omit the percent sign (%) prefix if your program has not declared a
symbol with the same name.
•
You cannot deposit values into the following kinds of registers: unallocated,
disabled, or unreadable registers. For example:
%R38 to %R127, if only %R32 to %R37 were allocated
%F0 (always 0.0)
%F1 (always 1.0)
%R0 (always 0)
%SP
%P0 (always 1)
%GRNAT0 and %GRNAT1
All of the special registers, except %PC
Most of the control and application registers (see below)
•
For regular user mode debug and SCD, you can also deposit into registers, as
follows:
Control registers %IPSR, %ISR, %IIP, %IFA, %ITIR, %IIPA, %IFS, %IIM,
and %IHA for exception frames
Application registers %RSC and %CCV
•
For SCD ONLY, you can also deposit into registers, as follows:
Application registers %KR0 to %KR7
Control registers %DCR, %ITM, %IVA, %PTA, %LID, %TPR, %IRR0 to
%IRR3, %ITV, %PMV, %CMCV, %LRR0, and %LRR1
•
There are no vector registers.
•
Some register reads are automatically formatted. You can override this
formatting, as shown in Section 4.4.1 (for example, EXAMINE/QUAD/HEX
%FPSR).
•
For information on the Floating Point Status Register (%FPSR), see the Intel
IA-64 Architecture Software Developer’s Manual Volume 1. Example:
4–27
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
DBG> ex %fpsr
LOOPER\main\%FPSR:
I U O Z D V TD RC PC WRE FTZ
SF3 0 0 0 0 0 0 1 0 3 0 0
SF2 0 0 0 0 0 0 1 0 3 0 0
SF1 0 0 0 0 0 0 1 0 3 1 0
SF0 0 0 0 0 0 0 0 0 3 0 0
TRAPS ID UD OD ZD DD VD
1 1 1 1 1 1
DBG>
You can also force this formatting on any location (see EXAMINE/FPSR).
•
For information about Previous Function State (%PFS), Current Frame
Maker (%CFM), Interrupt Function State (%IFS), and Next Previous
Function State (%NEXT_PFS) registers, see Intel IA-64 Architecture Software
Developer’s Manual, Volume 1. Example:
DBG> ex %pfs
LOOPER\main\%PFS:
PPL PEC SOF SOL SOR RRB_GR RRB_FR RRB_PR
3 0 29 21 0
0
0
0
DBG> ex %cfm
LOOPER\main\%CFM:
SOF SOL SOR RRB_GR RRB_FR RRB_PR
6 5 0
0
0
0
DBG> ex %ifs
LOOPER\main\%IFS:
SOF SOL SOR RRB_GR RRB_FR RRB_PR
6 5 0
0
0
0
DBG> ex %next_pfs
LOOPER\main\%NEXT_PFS:
PPL PEC SOF SOL SOR RRB_GR RRB_FR RRB_PR
3 0 6 5 0
0
0
0
DBG>
Also see EXAMINE/PFS and EXAMINE/CFM.
•
For information about the Process Status Register (%PSR), see the Intel IA-64
Architecture Software Developer’s Manual, Volume 2. Example:
DBG> ex %psr
LOOPER\main\%PSR:
IA BN ED RI SS DD DA ID IT MC IS CPL RT TB LP DB SI DI PP SP DFH DFL
0 1 0 0 0 0 0 0 1 0 0 3 1 0 0 0 0 1 0 0 0 0
DT PK I IC MFH MFL AC UP BE
1 0 1 1 1 1 0 0 0
DBG>
Also see EXAMINE/PSR.
•
The debugger defaults to a bit vector format for the %GRNAT0, %GRANT1,
and %PR registers. For example:
DBG> ex %grnat0,%pr
LOOPER\main\%GRNAT0:
11111111 11111111 11111111 11000000 00000000 00000000 00000000 00000000
LOOPER\main\%PR:
00000000 00000000 00000000 00000000 11111111 01010110 10010110 10100011
DBG>
4–28
Examining and Manipulating Program Data
4.4 Examining and Depositing into Registers
•
The debugger defaults to single bits for registers %p0 . . . %p63. For example:
DBG> ex %p6,%p7
LOOPER\main\%P6:
LOOPER\main\%P7:
DBG>
0
1
4.5 Specifying a Type When Examining and Depositing
The preceding sections explain how to use the EXAMINE and DEPOSIT
commands with program locations that have a symbolic name and, therefore, are
associated with a compiler-generated type.
Section 4.5.1 describes how the debugger formats (types) data for program
locations that do not have a symbolic name and explains how you can control the
type for those locations.
Section 4.5.2 explains how to override the type associated with any program
location, including a location that has a symbolic name.
4.5.1 Defining a Type for Locations Without a Symbolic Name
Program locations that do not have a symbolic name and, therefore, are not
associated with a compiler-generated type have the type longword integer by
default. Section 4.1.5 explains how to examine and deposit into such locations
using the default type.
The SET TYPE command enables you to change the default type in order to
examine and display the contents of a location in another type, or to deposit a
value of one type into a location associated with another type. Table 4–3 lists the
type keywords for the SET TYPE command.
Table 4–3 SET TYPE Keywords
ASCIC
ASCID
ASCII:n
ASCIW
ASCIZ
BYTE
D_FLOAT
DATE_TIME
EXTENDED_FLOAT1
F_LOAT
FLOAT
G_FLOAT
1 Integrity
server and Alpha specific
INSTRUCTION
LONG_FLOAT1
LONG_LONG_FLOAT1
LONGWORD
OCTAWORD
PACKED
QUADWORD
S_FLOAT1
T_FLOAT1
TYPE=(type-expression)
WORD
X_FLOAT1
For example, the following commands set the type for locations without a
symbolic name to, respectively, byte integer, G_floating, and ASCII with 6 bytes
of ASCII data. Each successive SET TYPE command resets the type.
DBG> SET TYPE BYTE
DBG> SET TYPE G_FLOAT
DBG> SET TYPE ASCII:6
Note that the SET TYPE command, when used without the /OVERRIDE
qualifier, does not affect the type for program locations that have a symbolic
name (locations associated with a compiler-generated type).
The SHOW TYPE command identifies the current type for locations without a
symbolic name. To restore the default type for such locations, enter the SET
TYPE LONGWORD command.
4–29
Examining and Manipulating Program Data
4.5 Specifying a Type When Examining and Depositing
4.5.2 Overriding the Current Type
The SET TYPE/OVERRIDE command enables you to change the type associated
with any program location, including locations with compiler-generated types.
For example, after the following command is executed, an unqualified EXAMINE
command displays the contents of only the first byte of the location specified
and interprets the contents as byte integer data. An unqualified DEPOSIT
command modifies only the first byte of the location specified and formats the
data deposited as byte integer data.
DBG> SET TYPE/OVERRIDE BYTE
See Table 4–3 for the valid type keywords for the SET TYPE/OVERRIDE
command.
To identify the current override type, enter the SHOW TYPE/OVERRIDE
command. To cancel the current override type and restore the normal
interpretation of locations that have a symbolic name, enter the CANCEL
TYPE/OVERRIDE command.
The EXAMINE and DEPOSIT commands have qualifiers that enable you to
override the type currently associated with a program location for the duration
of the EXAMINE or DEPOSIT command. These qualifiers override any previous
SET TYPE or SET TYPE/OVERRIDE command as well as any compilergenerated type. See the DEPOSIT and EXAMINE commands for the type
qualifiers available to each command.
When used with a type qualifier, the EXAMINE command displays the entity
specified by the address expression in that type. For example:
DBG> EXAMINE/BYTE .
! Type is
MOD3\%LINE 15 : -48
DBG> EXAMINE/WORD .
! Type is
MOD3\%LINE 15 : 464
DBG> EXAMINE/LONG .
! Type is
MOD3\%LINE 15 : 749404624
DBG> EXAMINE/QUAD .
! Type is
MOD3%LINE 15 : +0130653502894178768
DBG> EXAMINE/FLOAT .
! Type is
MOD3%LINE 15 : 1.9117807E-38
DBG> EXAMINE/G_FLOAT .
! Type is
MOD3%LINE 15 : 1.509506018605227E-300
DBG> EXAMINE/ASCII .
! Type is
MOD3\%LINE 15 : ".."
DBG>
byte integer.
word integer.
longword integer.
quadword integer.
F_floating.
G_floating.
ASCII string.
When used with a type qualifier, the DEPOSIT command deposits a value of that
type into the location specified by the address expression, which overrides the
type associated with the address expression.
The remaining sections provide examples of specifying integer, string, and
user-declared types with type qualifiers and the SET TYPE command.
4–30
Examining and Manipulating Program Data
4.5 Specifying a Type When Examining and Depositing
4.5.2.1 Integer Types
The following examples show the use of the EXAMINE and DEPOSIT commands
with integer-type qualifiers (/BYTE, /WORD, /LONGWORD). These qualifiers
enable you to deposit a value of a particular integer type into an arbitrary
program location.
DBG> SHOW TYPE
type: long integer
DBG> EVALU/ADDR .
724
DBG> DEPO/BYTE . = 1
DBG>
724:
DBG>
724:
DBG>
EXAM .
1280461057
EXAM/BYTE .
1
DEPO/WORD . = 2
! Show type for locations without
! a compiler-generated type.
! Current location is 724.
! Deposit the value 1 into one byte
! of memory at address 724.
! By default, 4 bytes are examined.
! Examine one byte only.
! Deposit the value 2 into first two
! bytes (word) of current entity.
! Examine a word of the current entity.
DBG> EXAM/WORD .
724: 2
DBG> DEPO/LONG 724 = 999 ! Deposit the value 999 into 4 bytes
!(a longword) beginning at address 724.
DBG> EXAM/LONG 724
! Examine 4 bytes (longword)
724: 999
! beginning at address 724.
DBG>
4.5.2.2 ASCII String Type
The following examples show the use of the EXAMINE and DEPOSIT commands
with the /ASCII:n type qualifier.
When used with the DEPOSIT command, this qualifier enables you to deposit
an ASCII string of length n into an arbitrary program location. In the example,
the location has a symbolic name (I) and, therefore, is associated with a compilergenerated integer type. The command syntax is as follows:
DEPOSIT/ASCII:n address-expression = "ASCII string of length n"
The default value of n is 4 bytes.
DBG> DEPOSIT I = "abcde"
! I has compiler-generated integer type.
%DEBUG-W-INVNUMBER, invalid numeric string ’abcde’
! So, it cannot deposit string into I.
DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer
! type to deposit 5 bytes of
! ASCII data.
DBG> EXAMINE .
! Display value of I in compilerMOD3\I: 1146048327
! generated integer type.
DBG> EXAM/ASCII:5 .
! Display value of I as 5-byte
MOD3\I: "abcde"
! ASCII string.
DBG>
To enter several DEPOSIT/ASCII commands, you can establish an override ASCII
type with the SET TYPE/OVERRIDE command. Subsequent EXAMINE and
DEPOSIT commands then have the effect of specifying the /ASCII qualifier with
these commands. For example:
4–31
Examining and Manipulating Program Data
4.5 Specifying a Type When Examining and Depositing
DBG> SET TYPE/OVER ASCII:5!
DBG> DEPOSIT I = "abcde" !
DBG> EXAMINE I
!
MOD3\I: "abcde"
!
DBG> CANCEL TYPE/OVERRIDE !
DBG> EXAMINE I
!
MOD3\I: 1146048327
DBG>
Establish ASCII:5 as override type.
Can now deposit 5-byte string into I.
Display value of I as 5-byte
ASCII string.
Cancel ASCII override type.
Display I in compiler-generated type.
4.5.2.3 User-Declared Types
The following examples show the use of the EXAMINE and DEPOSIT commands
with the /TYPE=(name) qualifier. The qualifier enables you to specify a userdeclared override type when examining or depositing.
For example, assume that a Pascal program contains the following code, which
declares the enumeration type COLOR with the three values RED, GREEN, and
BLUE:
.
.
.
TYPE
COLOR = (RED,GREEN,BLUE);
.
.
.
During the debugging session, the SHOW SYMBOL/TYPE command identifies
the type COLOR as it is known to the debugger:
DBG> SHOW SYMBOL/TYPE COLOR
data MOD3\COLOR
enumeration type (COLOR, 3 elements), size: 1 byte
DBG>
The next example displays the value at address 1000, which is not associated
with a symbolic name. Therefore, the value 0 is displayed in the type longword
integer, by default.
DBG> EXAMINE 1000
1000: 0
DBG>
The next example displays the value at address 1000 in the type COLOR. The
preceding SHOW SYMBOL/TYPE command indicates that each enumeration
element is stored in 1 byte. Therefore, the debugger converts the first byte of the
longword integer value 0 at address 1000 to the equivalent enumeration value,
RED (the first of the three enumeration values):
DBG> EXAMINE/TYPE=(COLOR) 1000
1000: RED
DBG>
The following DEPOSIT command deposits the value GREEN into address 1000
with the override type COLOR. The EXAMINE command displays the value at
address 1000 in the default type, longword integer:
DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN
DBG> EXAMINE 1000
1000: 1
DBG>
4–32
Examining and Manipulating Program Data
4.5 Specifying a Type When Examining and Depositing
The following SET TYPE command establishes the type COLOR for locations,
such as address 1000, that do not have a symbolic name. The EXAMINE
command now displays the value at 1000 in the type COLOR:
DBG> SET TYPE TYPE=(COLOR)
DBG> EXAMINE 1000
1000: GREEN
DBG>
4–33
5
Controlling Access to Symbols in Your
Program
Symbolic debugging enables you to specify variable names, routine names, and so
on, precisely as they appear in your source code. You do not need to use numeric
memory addresses or registers when referring to program locations.
In addition, you can use symbols in the context that is appropriate for the
program and its source language. The debugger supports the language
conventions regarding data types, expressions, scope and visibility of entities, and
so on.
To have full access to the symbols that are associated with your program, you
must compile and link the program using the /DEBUG command qualifier.
Under these conditions, the way in which symbol information is passed from your
source program to the debugger and is processed by the debugger is transparent
to you in most cases. However, certain situations might require some action.
For example, when you try to set a breakpoint on a routine named COUNTER,
the debugger might display the following diagnostic message:
DBG> SET BREAK COUNTER
%DEBUG-E-NOSYMBOL, symbol ’COUNTER’ is not in the symbol table
DBG>
You must then set the module where COUNTER is defined, as explained in
Section 5.2.
The debugger might display the following message if the same symbol X is
defined (declared) in more than one module, routine, or other program unit:
DBG> EXAMINE X
%DEBUG-E-NOUNIQUE, symbol ’X’ is not unique
DBG>
You must then resolve the symbol ambiguity, perhaps by specifying a path name
for the symbol, as explained in Section 5.3.
This chapter explains how to handle these and other situations related to
accessing symbols in your program.
The chapter discusses only the symbols (typically address expressions) that are
derived from your source program:
•
The names of entities that you have declared in your source code, such as
variables, routines, labels, array elements, or record components
•
The names of modules (compilation units) and shareable images that are
linked with your program
5–1
Controlling Access to Symbols in Your Program
•
Elements that the debugger uses to identify source code—for example, the
specifications of source files, and source line numbers as they appear in a
listing file or when the debugger displays source code
The following types of symbols are discussed in other chapters:
•
The symbols you create during a debugging session with the DEFINE
command are covered in Section 13.4.
•
The debugger’s built-in symbols, such as the period ( . ) and %PC, are
discussed throughout this manual in the appropriate context and are defined
in Appendix B.
Also, see Section 4.1.11 for information about how to obtain the memory
addresses and register names associated with symbolic address expressions and
how to symbolize program locations.
Note
If your program was optimized during compilation, certain variables
in the program might be removed by the compiler. If you then try to
reference such a variable, the debugger issues a warning (see Section 1.2
and Section 14.1).
Before you try to reference a nonstatic (stack-local or register) variable,
its defining routine must be active on the call stack. That is, program
execution must be paused somewhere within the defining routine (see
Section 3.4.3).
5.1 Controlling Symbol Information When Compiling and Linking
To take full advantage of symbolic debugging, you must compile and link your
program with the /DEBUG qualifier as explained in Section 1.2.
The following sections describe how symbol information is created and passed to
the debugger when compiling and linking.
5.1.1 Compiling
When you compile a source file using the /DEBUG qualifier, the compiler creates
symbol records for the debug symbol table (DST records) and includes them in
the object module being created.
DST records provide not only the names of symbols but also all relevant
information about their use. For example:
•
Data types, ranges, constraints, and scopes associated with variables
•
Parameter names and parameter types associated with functions and
procedures
•
Source-line correlation records, which associate source lines with line
numbers and source files
Most compilers allow you to vary the amount of DST information put in an object
module by specifying different options with the /DEBUG qualifier. Table 5–1
identifies the options for most compilers (see the documentation supplied with
your compiler for complete information).
5–2
Controlling Access to Symbols in Your Program
5.1 Controlling Symbol Information When Compiling and Linking
Table 5–1 Compiler Options for DST Symbol Information
Compiler Command Qualifier
1
/DEBUG
DST Information in Object Module
Full
2
/DEBUG=TRACEBACK
Traceback only (module names, routine names, and
line numbers)
/NODEBUG3
None
1
/DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS,TRACEBACK) are equivalent.
2
/DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS,TRACEBACK) are equivalent.
3
/NODEBUG, /DEBUG=NONE, and /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent.
The TRACEBACK option is a default for most compilers. That is, if you omit
the /DEBUG qualifier, most compilers assume /DEBUG=TRACEBACK. The
TRACEBACK option enables the traceback condition handler to translate
memory addresses into routine names and line numbers so that it can give a
symbolic traceback if a run-time error has occurred. For example:
$ RUN FORMS
.
.
.
%PAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT
%PAS-F-ERROPECRE, error opening/creating file
%RMS-F-FNM, error in file name
%TRACE-F-TRACEBACK, symbolic stack dump follows
module name
routine name
PAS$IO_BASIC
PAS$IO_BASIC
PAS$IO_BASIC
FORMS
$
_PAS$CODE
_PAS$CODE
_PAS$CODE
FORMS
line
rel PC
abs PC
59
00000192
0000054D
0000028B
00000020
00001CED
000020A8
00001DE6
000005A1
Traceback information is also used by the debugger’s SHOW CALLS command.
5.1.2 Local and Global Symbols
DST records contain information about all of the symbols that are defined in your
program. These are either local or global symbols.
Typically, a local symbol is a symbol that is referenced only within the module
where it is defined; a global symbol is a symbol such as a routine name,
procedure entry point, or a global data name, that is defined in one module but
referenced in other modules.
A global symbol that is defined in a shareable image and is referenced in
another image (for example the main, executable image of a program) is called a
universal symbol. When creating a shareable image, you must explicitly define
any universal symbols as such at link time. See Section 5.4 for information about
universal symbols and shareable images.
Generally, the compiler resolves references to local symbols, and the linker
resolves references to global symbols.
The distinction between local and global symbols is discussed in various parts of
this chapter in connection with symbol lookup and with shareable images and
universal symbols.
5–3
Controlling Access to Symbols in Your Program
5.1 Controlling Symbol Information When Compiling and Linking
5.1.3 Linking
When you enter the LINK/DEBUG command to link object modules and produce
an executable image, the linker performs several functions that affect debugging:
•
It builds a debug symbol table (DST) from the DST records contained in
the object modules being linked. The DST is the primary source of symbol
information during a debugging session.
•
It resolves references to global symbols and builds a global symbol table
(GST). The GST duplicates some of the global symbol information already
contained in the DST, but the GST is used by the debugger for symbol lookup
under certain circumstances.
•
It puts the DST and GST in the executable image.
•
It sets flags in the executable image that cause the image activator to
pass control to the debugger when you enter the DCL command RUN (see
Section 1.2).
Section 5.4 explains how to link shareable images for debugging, including how
to define universal symbols (global symbols that are defined within a shareable
image and referenced from another image).
Table 5–2 summarizes the level of DST and GST information passed to the
debugger depending on the compiler or LINK command option. The compiler
command qualifier controls the level of DST information passed to the linker. The
LINK command qualifier controls not only how much DST and GST information
is passed to the debugger but also whether the program can be brought under
debugger control (see Section 1.2).
Table 5–2 Effect of Compiler and Linker on DST and GST Symbol Information
Compiler
Command
Qualifier1
DST Data in
Object Module
LINK Command
Qualifier2
DST Data
Passed
to Debugger
GST Data
Passed
to Debugger3
/DEBUG
Full
/DEBUG
Full
Full
/DEBUG=TRACE
Traceback only
/DEBUG
Traceback only
Full
/NODEBUG
None
/DEBUG
None
Full
/DEBUG
Full
/DSF4
Full
Full5
/DEBUG=TRACE
Traceback only
/DSF4
Traceback only
Full5
/NODEBUG
None
/DSF4
None
Full5
1
2
See Table 5–1 for additional information.
You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 5.4).
3
GST data includes global symbol information that is resolved at link time. GST data for an executable image includes
the names and values of global routines and global constants. GST data for a shareable image includes universal symbols
(see Section 5.1.2 and Section 5.4).
4 Alpha only.
5 DBG$IMAGE_DSF_PATH
must point to the directory in which the .DSF file resides.
(continued on next page)
5–4
Controlling Access to Symbols in Your Program
5.1 Controlling Symbol Information When Compiling and Linking
Table 5–2 (Cont.) Effect of Compiler and Linker on DST and GST Symbol Information
Compiler
Command
Qualifier1
DST Data in
Object Module
LINK Command
Qualifier2
DST Data
Passed
to Debugger
GST Data
Passed
to Debugger3
/DEBUG
Full
/TRACE6
Traceback only
Full
/DEBUG=TRACE
Traceback only
/TRACE
Traceback only
Full
/NODEBUG
None
/TRACE
None
Full
/DEBUG
Full
/NOTRACE7
1
2
See Table 5–1 for additional information.
You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 5.4).
3
GST data includes global symbol information that is resolved at link time. GST data for an executable image includes
the names and values of global routines and global constants. GST data for a shareable image includes universal symbols
(see Section 5.1.2 and Section 5.4).
6
LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command.
7
The RUN/DEBUG command allows you to run the debugger, but if you entered the LINK/NOTRACEBACK command
you will be unable to do symbolic debugging.
If you specify /NODEBUG with the compiler command and subsequently link and
execute the image, the debugger issues the following message when the program
is brought under debugger control:
%DEBUG-I-NOLOCALS, image does not contain local symbols
The previous message, which occurs whether you linked with the /TRACEBACK
or /DEBUG qualifier, indicates that no DST has been created for that image.
Therefore, you have access only to global symbols contained in the GST.
If you do not specify /DEBUG with the LINK command, the debugger issues the
following message when the program is brought under debugger control:
%DEBUG-I-NOGLOBALS, some or all global symbols not accessible
The previous message indicates that the only global symbol information available
during the debugging session is stored in the DST.
These concepts are discussed in later sections. In particular, see Section 5.4 for
additional information related to debugging shareable images.
5.1.4 Controlling Symbol Information in Debugged Images
Symbol records occupy space within the executable image. After you debug your
program, you might want to link it again without using the /DEBUG qualifier to
make the executable image smaller. This creates an image with only traceback
data in the DST and with a GST.
The LINK/NOTRACEBACK command enables you to secure the contents of an
image from users after it has been debugged. Use this command for images that
are to be installed with privileges (see the OpenVMS System Manager’s Manual
and the OpenVMS System Management Utilities Reference Manual). When
you use the /NOTRACEBACK qualifier with the LINK command, no symbolic
information (including traceback data) is passed to the image.
5–5
Controlling Access to Symbols in Your Program
5.1 Controlling Symbol Information When Compiling and Linking
5.1.5 Creating Separate Symbol Files (Alpha Only)
On Alpha systems, you can LINK your program with the /DSF qualifier to create
a separate file that contains symbol information. By default, the symbol file has
the same file name as the executable file created by the LINK utility, and has file
type .DSF. For example:
$
$
$
$
CC/DEBUG/NOOPTIMIZE TESTPROGRAM.C
LINK/DSF TESTPROGRAM
DEFINE DBG$IMAGE_DSF_PATH SYS$DISK:[]
DEBUG/KEEP TESTPROGRAM
This example does the following:
1. Compiles TESTPROGRAM.C
2. Creates TESTPROGRAM.EXE and TESTPROGRAM.DSF
3. Defines logical name DBG$IMAGE_DSF_PATH as the current directory
4. Invokes the kept debugger
This procedure allows you to create smaller executable files and still have
global symbol information available for debugging. Certain applications, such as
installed resident files, require that the executable not contain symbol tables. In
addition, .DSF files allow you to deliver executable files without symbol tables to
customers, but retain separate .DSF files for future debugging needs.
Note
For ease of debugging, use the /NOOPTIMIZE qualifer (if possible) when
compiling the program. See Section 14.1 for information about debugging
optimized code.
Debugging an executable file that has a separate symbol (.DSF) file requires the
following:
•
The name of the .DSF file must match the name of the .EXE file being
debugged.
•
You must define DBG$IMAGE_DSF_PATH to point to the directory that
contains the .DSF file.
See the OpenVMS Linker Utility Manual for more information about using the
/DSF qualifier.
5.2 Setting and Canceling Modules
You need to set a module if the debugger is unable to locate a symbol that you
have specified (for example, a variable name X) and issues a message as in the
following example:
DBG> EXAMINE X
%DEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table
DBG>
This section explains module setting, and the conditions under which you might
need to set or cancel a module, using the SET MODULE and CANCEL MODULE
commands.
5–6
Controlling Access to Symbols in Your Program
5.2 Setting and Canceling Modules
When you compile and link your program using the /DEBUG command qualifier,
as explained in Section 5.1, complete symbol information is passed from the
program’s source code to its executable image.
Symbol information is contained in the debug symbol table (DST) and global
symbol table (GST) within the executable image. The DST contains detailed
information about local and global symbols. The GST duplicates some of the
global symbol information contained in the DST.
To facilitate symbol searches, the debugger loads symbol information from the
DST and GST into a run-time symbol table (RST), which is structured for efficient
symbol lookup. Unless symbol information is in the RST, the debugger does not
recognize or properly interpret the associated symbol.
Because the RST takes up memory, the debugger loads it dynamically,
anticipating what symbols you might want to reference in the course of program
execution. The loading process is called module setting, because all symbol
information for a given module is loaded into the RST at one time.
When your program is brought under debugger control, all GST records are
loaded into the RST, because global symbols must be accessible throughout the
debugging session. Also, the debugger sets the module that contains the main
program (the routine specified by the image transfer address, where execution is
paused at the start of a debugging session). You then have access to all global
symbols and to any local symbols that should be visible within the main program.
Subsequently, whenever execution of the program is interrupted, the debugger
sets the module that contains the routine in which execution is paused. (For
Ada programs, the debugger also sets any module that is related by a withclause or subunit relationship, as explained in the debugger’s online help. Type
Help Language_Support_Ada.) This enables you to reference the symbols that
should be visible at that program location (in addition to the global symbols).
This default mode of operation is called dynamic mode. When setting a module
dynamically, the debugger issues a message such as the following:
%DEBUG-I-DYNMODSET, setting module MOD4
If you try to reference a symbol that is defined in a module that has not been set,
the debugger warns you that the symbol is not in the RST. You must then use the
SET MODULE command to set the module containing that symbol explicitly. For
example:
DBG> EXAMINE X
%DEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table
DBG> SET MODULE MOD3
DBG> EXAMINE X
MOD3\ROUT2\X: 26
DBG>
The SHOW MODULE command lists the modules of your program and identifies
which modules are set.
When a module is set, the debugger automatically allocates memory as needed by
the RST. This can eventually slow down the debugger as more modules are set. If
performance becomes a problem, you can use the CANCEL MODULE command
to reduce the number of set modules, which automatically releases memory.
Or you can disable dynamic mode by entering the SET MODE NODYNAMIC
command. When dynamic mode is disabled, the debugger does not set modules
automatically. Use the SHOW MODE command to determine whether dynamic
mode is enabled or disabled.
5–7
Controlling Access to Symbols in Your Program
5.2 Setting and Canceling Modules
For additional information about module setting specific to Ada programs, see the
debugger’s online help (type Help Language_Support_Ada).
Section 5.4 explains how to set images and modules when debugging shareable
images.
5.3 Resolving Symbol Ambiguities
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, by using
the scope and visibility rules of the currently set language and the ordering of
routine calls on the call stack, as explained in Section 5.3.1.
However, in some cases the debugger might respond as follows when you specify
a symbol that is defined multiple times:
•
It might not be able to determine the particular declaration of the symbol
that you intended. For example:
DBG> EXAMINE X
%DEBUG-W-NOUNIQUE, symbol ’X’ is not unique
DBG>
•
It might reference the declaration that is visible in the current scope, which
may not be the one you want.
To resolve such problems, you must specify a scope where the debugger should
search for a particular declaration of the symbol. In the following example, the
pathname COUNTER\X uniquely specifies a particular declaration of X:
DBG> EXAMINE COUNTER\X
COUNTER\X: 14
DBG>
The following sections discuss scope concepts and explain how to resolve symbol
ambiguities.
5.3.1 Symbol Lookup Conventions
This section explains how the debugger searches for symbols, resolving
most potential symbol ambiguities using the scope and visibility rules of the
programming language and also its own rules. Section 5.3.2 and Section 5.3.3
describe supplementary techniques that you can use when necessary.
You can specify symbols in debugger commands by using either a path name or
the exact symbol.
If you use a path name, the debugger looks for the symbol in the scope denoted
by the pathname prefix (see Section 5.3.2).
If you do not specify a pathname prefix, by default, the debugger searches the
run-time symbol table (RST) as explained in the following paragraphs (you can
modify this default behavior with the SET SCOPE command as explained in
Section 5.3.3).
First, the debugger looks for symbols in the PC scope (also known as scope
0), according to the scope and visibility rules of the currently set language.
This means that, typically, the debugger first looks within the block or routine
surrounding the current PC value (where execution is currently paused). If the
symbol is not found, the debugger searches the nesting program unit, then its
nesting unit, and so on. The precise manner, which depends on the language,
5–8
Controlling Access to Symbols in Your Program
5.3 Resolving Symbol Ambiguities
ensures that the correct declaration of a symbol that is defined multiple times is
chosen.
However, you can reference symbols throughout your program, not just those that
are visible in the PC scope as defined by the language. This is necessary so you
can set breakpoints in arbitrary areas, examine arbitrary variables, and so on.
Therefore, if the symbol is not visible in the PC scope, the debugger continues
searching as follows.
After the PC scope, the debugger searches the scope of the calling routine (if
any), then its caller, and so on. Symbolically, the complete scope search list is
denoted (0,1,2, . . . ,n), where 0 denotes the PC scope and n is the number of calls
on the call stack. Within each scope (call frame), the debugger uses the visibility
rules of the language to locate a symbol.
This search list, based on the call stack, enables the debugger to differentiate
symbols that are defined multiple times in a convenient, predictable way.
If the symbol is still not found, the debugger searches the rest of the RST—that
is, the other set modules and the global symbol table (GST). At this point the
debugger does not attempt to resolve any symbol ambiguities. Instead, if more
than one occurrence of the symbol is found, the debugger issues a message such
as the following:
%DEBUG-W-NOUNIQUE, symbol ’Y’ is not unique
If you have used a SET SCOPE command to modify the default symbol search
behavior, you can restore the default behavior with the CANCEL SCOPE
command.
5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely
If the debugger indicates that a symbol reference is not unique, use the SHOW
SYMBOL command to obtain all possible path names for that symbol, then
specify a path name to reference the symbol uniquely. For example:
DBG> EXAMINE COUNT
%DEBUG-W-NOUNIQUE, symbol ’COUNT’ is not unique
DBG> SHOW SYMBOL COUNT
data MOD7\ROUT3\BLOCK1\COUNT
data MOD4\ROUT2\COUNT
routine MOD2\ROUT1\ROUT3\COUNT
DBG> EXAMINE MOD4\ROUT2\COUNT
MOD4\ROUT2\COUNT: 12
DBG>
The command SHOW SYMBOL COUNT lists all declarations of the symbol
COUNT that exist in the RST. The first two declarations of COUNT are
variables (data). The last declaration listed is a routine. Each declaration
is shown with its pathname prefix, which indicates the path (search scope)
the debugger must follow to reach that particular declaration. For example,
MOD4\ROUT2\COUNT denotes the declaration of the symbol COUNT in
routine ROUT2 of module MOD4.
The pathname format is as follows. The leftmost element of a path name
identifies the module containing the symbol. Moving toward the right, the path
name lists the successively nested routines and blocks that lead to the particular
declaration of the symbol (which is the rightmost element).
The debugger always displays symbols with their path names, but you need to
use path names in debugger commands only to resolve an ambiguity.
5–9
Controlling Access to Symbols in Your Program
5.3 Resolving Symbol Ambiguities
The debugger looks up line numbers like any other symbols you specify (by
default, it first looks in the module where execution is paused). A common use of
path names is for specifying a line number in an arbitrary module. For example:
DBG> SET BREAK QUEUE_MANAGER\%LINE 26
The SHOW SYMBOL command identifies global symbols twice, because global
symbols are included both in the DST and in the GST. For example:
DBG>
data
data
data
DBG>
SHOW SYMBOL X
ALPHA\X
ALPHA\BETA\X
X (global)
! global X
! local X
! same as ALPHA\X
In the case of a shareable image, its global symbols are universal symbols and the
SHOW SYMBOL command identifies universal symbols twice (see Section 5.1.2
and Section 5.4).
5.3.2.1 Simplifying Path Names
Path names are often long. You can simplify the process of specifying path names
in three ways:
•
Abbreviate a path name
•
Define a brief symbol for a path name
•
Set a new search scope so you do not have to use a path name
To abbreviate a path name, delete the names of nesting program units starting
from the left, but leave enough of the path name to specify it uniquely. For
example, ROUT3\COUNT is a valid abbreviated path name for the routine in the
first example of Section 5.3.2.
To define a symbol for a path name, use the DEFINE command. For example:
DBG> DEFINE INTX = INT_STACK\CHECK\X
DBG> EXAMINE INTX
To set a new search scope, use the SET SCOPE command, which is described in
Section 5.3.3.
5.3.2.2 Specifying Symbols in Routines on the Call Stack
You can use a numeric path name to specify the scope associated with a routine
on the call stack (as identified in a SHOW CALLS display). The pathname prefix
"0\ " denotes the PC scope, the pathname prefix "1\ " denotes scope 1 (the scope
of the caller routine), and so on.
For example, the following commands display the current values of two distinct
declarations of Y, which are visible in scope 0 and scope 2, respectively:
DBG> EXAMINE 0\Y
DBG> EXAMINE 2\Y
By default, the EXAMINE Y command signifies EXAMINE 0\Y.
See the SET SCOPE/CURRENT command description in Section 5.3.3. That
command enables you to reset the reference for the default scope search list
relative to the call stack.
5–10
Controlling Access to Symbols in Your Program
5.3 Resolving Symbol Ambiguities
5.3.2.3 Specifying Global Symbols
To specify a global symbol uniquely, use a backslash ( \ ) as a prefix to the symbol.
For example, the following command displays the value of the global symbol X:
DBG> EXAMINE \X
5.3.2.4 Specifying Routine Invocations
When a routine is called recursively, you might need to distinguish among several
calls to the same routine, all of which generate new symbols with identical names.
You can include an invocation number in a path name to indicate a particular
call to a routine. The number must be a nonnegative integer and must follow the
name of the rightmost routine in the path name. A 0 denotes the most recent
invocation; 1 denotes the previous invocation, and so on. For example, if PROG
calls COMPUTE and COMPUTE calls itself recursively, and each call creates a
new variable SUM, the following command displays the value of SUM for the
most recent call to COMPUTE:
DBG> EXAMINE PROG\COMPUTE 0\SUM
To refer to the variable SUM that was generated in the previous call to
COMPUTE, express the path name with a 1 in place of the 0.
When you do not include an invocation number, the debugger assumes that the
reference is to the most recent call to the routine (the default invocation number
is 0).
See the SET SCOPE/CURRENT command description in Section 5.3.3. That
command enables you to reset the reference for the default scope search list
relative to the call stack.
5.3.3 Using SET SCOPE to Specify a Symbol Search Scope
By default, the debugger looks up symbols that you specify without a pathname
prefix by using the scope search list described in Section 5.3.1.
The SET SCOPE command enables you to establish a new scope for symbol
lookup so that you do not have to use a path name when referencing symbols in
that scope.
In the following example, the SET SCOPE command establishes the path name
MOD4\ROUT2 as the new scope for symbol lookup. Then, references to Y
without a pathname prefix specify the declaration of Y that is visible in the new
scope.
DBG> EXAMINE Y
%DEBUG-E-NOUNIQUE, symbol ’Y’ is not unique
DBG> SHOW SYMBOL Y
data MOD7\ROUT3\BLOCK1\Y
data MOD4\ROUT2\Y
DBG> SET SCOPE MOD4\ROUT2
DBG> EXAMINE Y
MOD4\ROUT2\Y: 12
DBG>
After you enter a SET SCOPE command, the debugger applies the path name you
specified in the command to all references that are not individually qualified with
path names.
5–11
Controlling Access to Symbols in Your Program
5.3 Resolving Symbol Ambiguities
You can specify numeric path names with SET SCOPE. For example, the
following command sets the current scope to be three calls down from the PC
scope:
DBG> SET SCOPE 3
You can also define a scope search list to specify the order in which the debugger
should search for symbols. For example, the following command causes the
debugger to look for symbols first in the PC scope (scope 0) and then in the scope
denoted by routine ROUT2 of module MOD4:
DBG> SET SCOPE 0, MOD4\ROUT2
The debugger’s default scope search list is equivalent to entering the following
command (if it existed):
DBG> SET SCOPE 0,1,2,3, . . . ,n
Here the debugger searches successively down the call stack to find a symbol.
You can use the SET SCOPE/CURRENT command to reset the reference for the
default scope search list to another routine down the call stack. For example, the
following command sets the scope search list to be 2,3,4, . . . ,n:
DBG> SET SCOPE/CURRENT 2
To display the current scope search list for symbol lookup, use the SHOW SCOPE
command. To restore the default scope search list (see Section 5.3.1), use the
CANCEL SCOPE command.
5.4 Debugging Shareable Images
By default, your program might be linked with several Compaq-supplied
shareable images (for example, the run-time library image LIBRTL.EXE). This
section explains how to extend the concepts described in the previous sections
when debugging user-defined shareable images.
A shareable image is not intended to be directly executed. A shareable image
must first be included as input in the linking of an executable image, and then
the shareable image is loaded at run time when the executable image is run. You
do not have to install a shareable image to debug it. Instead, you can debug your
own private copy by assigning a logical name to it.
See the OpenVMS Linker Utility Manual for detailed information about linking
shareable images.
5.4.1 Compiling and Linking Shareable Images for Debugging
The basic steps in compiling and linking a shareable image for debugging are as
follows:
1. Compile the source files for the main image and for the shareable image, by
using the /DEBUG qualifier.
2. Link the shareable image with the /SHAREABLE and /DEBUG command
qualifiers and declare any universal symbols for that image. (A universal
symbol is a global symbol that is defined in a shareable image and referenced
in another image.)
3. Link the shareable image against the main image by specifying the shareable
image with the /SHAREABLE file qualifier as a linker option. Also specify
the /DEBUG command qualifier.
5–12
Controlling Access to Symbols in Your Program
5.4 Debugging Shareable Images
4. Define a logical name to point to the local copy of the shareable image. You
must specify the device and directory as well as the image name. Otherwise
the image activator looks for an image of that name in the system default
shareable image library directory, SYS$SHARE.
5. Bring the main image under debugger control. The shareable image is loaded
at run time.
These steps are shown next with a simple example. In the example, MAIN.FOR
and SUB1.FOR are the source files for the main (executable) image; SHR1.FOR
and SHR2.FOR are the source files for the shareable image to be debugged.
You compile the source files for each image as described in Section 5.1.
$ FORTRAN/NOOPT/DEBUG MAIN,SUB1
$ FORTRAN/NOOPT/DEBUG SHR1,SHR2
On Alpha processors, use the LINK command with the SYMBOL_VECTOR option
to create the shareable image and specify any universal symbols. For example:
$ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYS$INPUT:/OPTIONS
SYMBOL_VECTOR=(SHR_ROUT=PROCEDURE) Ctrl/Z
In the previous examples:
•
The /SHAREABLE command qualifier creates the shareable image SHR1.EXE
from the object files SHR1.OBJ and SHR2.OBJ.
•
The /OPTIONS qualifier appended to SYS$INPUT: enables you to specify the
universal symbol SHR_ROUT.
•
The /DEBUG qualifier builds a debug symbol table (DST) and a global symbol
table (GST) for SHR1.EXE and puts them in that image. The GST contains
the universal symbol SHR_ROUT.
You have now built the shareable image SHR1.EXE in your current default
directory. Because SHR1.EXE is a shareable image, you do not execute it
explicitly. Instead you link SHR1.EXE against the main (executable) image:
$ LINK/DEBUG MAIN,SUB1,SYS$INPUT:/OPTIONS
SHR1.EXE/SHAREABLE Ctrl/Z
$
In the previous example:
•
The LINK command creates the executable image MAIN.EXE from
MAIN.OBJ and SUB1.OBJ.
•
The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and puts them
in that image.
•
The /SHAREABLE qualifier appended to SHR1.EXE specifies that SHR1.EXE
is to be linked against MAIN.EXE as a shareable image.
When you execute the resulting main image, MAIN.EXE, any shareable images
linked against it are loaded at run time. However, by default, the image activator
looks for shareable images in the system default shareable image library
directory, SYS$SHARE. Therefore, you must define the logical name SHR1 to
point to SHR1.EXE in your current default directory. Be sure to specify the
device and directory:
$ DEFINE SHR1 SYS$DISK:[]SHR1.EXE
5–13
Controlling Access to Symbols in Your Program
5.4 Debugging Shareable Images
You can now bring both MAIN and SHR1 under debugger control by specifying
MAIN with the debugger RUN command (after starting the debugger):
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG> RUN MAIN
5.4.2 Accessing Symbols in Shareable Images
All the concepts covered in Section 5.1, Section 5.2, and Section 5.3 apply to the
modules of a single image, namely the main (executable) image. This section
provides additional information that is specific to debugging shareable images.
When you link shareable images for debugging as explained in Section 5.4.1,
the linker builds a DST and a GST for each image. The GST for a shareable
image contains only universal symbols. To conserve memory, the debugger builds
an RST for an image only when that image is set, either dynamically by the
debugger or when you use a SET IMAGE command.
The SHOW IMAGE command identifies all shareable images that are linked with
your program, shows which images are set, and identifies the current image (see
Section 5.4.2.2 for a definition of the current image). Only the main image is set
initially when you bring the program under debugger control.
The following sections explain how the debugger sets images dynamically
during program execution and how you can access symbols in arbitrary images
independently of execution.
See Section 3.4.3.4 for information about setting watchpoints in installed writable
shareable images.
5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode)
By default, dynamic mode is enabled. Therefore, whenever the debugger
interrupts execution, the debugger sets the image and module where execution is
paused, if they are not already set.
Dynamic mode gives you the following access to symbols automatically:
•
You can reference symbols defined in all set modules in the image where
execution is paused.
•
You can reference any universal symbols in the GST for that image.
By setting other modules in that image with the SET MODULE command, you
can reference any symbol defined in the image.
After an image is set, it remains set until you cancel it with the CANCEL
IMAGE command. If the debugger slows down as more images and modules
are set, use the CANCEL IMAGE command. You can also enter the SET MODE
NODYNAMIC command to disable dynamic mode.
5.4.2.2 Accessing Symbols in Arbitrary Images
The last image that you or the debugger sets is the current image. The current
image is the debugging context for symbol lookup. Therefore, when using the
following commands, you can reference only the symbols that are defined in the
current image:
DEFINE/ADDRESS
DEFINE/VALUE
DEPOSIT
5–14
Controlling Access to Symbols in Your Program
5.4 Debugging Shareable Images
EVALUATE
EXAMINE
TYPE
(SET,CANCEL) BREAK
(SET,SHOW,CANCEL) MODULE
(SET,CANCEL) TRACE
(SET,CANCEL) WATCH
SHOW SYMBOL
Note that the SHOW BREAK, SHOW TRACE, and SHOW WATCH commands
identify any breakpoints, tracepoints, or watchpoints that have been set in all
images.
To reference a symbol in another image, use the SET IMAGE command to make
the specified image the current image, then use the SET MODULE command to
set the module where that symbol is defined (the SET IMAGE command does not
set any modules). The following sample program shows these concepts.
The sample program consists of a main image PROG1 and a shareable image
SHR1. Assume that you have just brought the program under debugger control
and that execution is paused within the main program unit in image PROG1.
Assume that you want to set a breakpoint on routine ROUT2, which is defined in
some module in image SHR1.
If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in the
current image, PROG1:
DBG> SET BREAK ROUT2
%DEBUG-E-NOSYMBOL, symbol ’ROUT2’ is not in symbol table
DBG>
The SHOW IMAGE command shows that image SHR1 needs to be set:
DBG> SHOW IMAGE
image name
set
base address
end address
*PROG1
SHR1
yes
no
00000200
00001000
000009FF
00001FFF
total images: 2
DBG> SET IMAGE SHR1
bytes allocated: 32856
DBG> SHOW IMAGE
image name
set
base address
end address
PROG1
*SHR1
yes
yes
00000200
00001000
000009FF
00001FFF
total images: 2
DBG>
bytes allocated: 41948
SHR1 is now set and is the current image. However, because the SET IMAGE
command does not set any modules, you must set the module where ROUT2 is
defined before you can set the breakpoint:
DBG> SET BREAK ROUT2
%DEBUG-E-NOSYMBOL, symbol ’ROUT2’ is not in symbol table
DBG> SET MODULE/ALL
DBG> SET BREAK ROUT2
DBG> GO
break at routine ROUT2
10:
SUBROUTINE ROUT2(A,B)
DBG>
5–15
Controlling Access to Symbols in Your Program
5.4 Debugging Shareable Images
Now that you have set image SHR1 and all its modules and have reached the
breakpoint at ROUT2, you can debug using the normal method (for example, step
through the routine, examine variables, and so on).
After you have set an image and set modules within that image, the image and
modules remain set even if you establish a new current image. However, you
have access to symbols only in the current image at any one time.
5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images
The following paragraphs describe how to access a universal symbol (such as
a routine name) in a run-time library or other shareable image for which no
symbol-table information was generated. With this information you can, for
example, use the CALL command to execute a run-time library or system service
routine as explained in Section 13.7.
Enter the SET MODULE command with the following command syntax:
SET MODULE SHARE$image-name
For example:
DBG> SET MODULE SHARE$LIBRTL
The debugger creates dummy modules for each shareable image in your program.
The names of these shareable image modules have the prefix SHARE$. The
command SHOW MODULE/SHARE identifies these shareable image modules as
well as the modules in the current image.
Once a shareable image module has been set with the SET MODULE command,
you can access all of the image’s universal symbols. For example, the following
command lists all of the universal symbols in LIBRTL:
DBG> SHOW SYMBOL * IN SHARE$LIBRTL
.
.
.
routine SHARE$LIBRTL\STR$APPEND
routine SHARE$LIBRTL\STR$DIVIDE
routine SHARE$LIBRTL\STR$ROUND
.
.
.
routine SHARE$LIBRTL\LIB$WAIT
routine SHARE$LIBRTL\LIB$GETDVI
.
.
.
You can then specify these universal symbols with, for example, the CALL or SET
BREAK command.
Setting a shareable image module with the SET MODULE command loads the
universal symbols for that image into the run-time symbol table so that you can
reference these symbols from the current image. However, you cannot reference
other (local or global) symbols in that image from the current image. That is,
your debugging context remains set to the current image.
5–16
Controlling Access to Symbols in Your Program
5.4 Debugging Shareable Images
5.4.3 Debugging Resident Images (Alpha Only)
A resident image is a shareable module that is created and installed in a
particular way to enhance its efficiency. The requirements of creating such an
image include linking the image without a symbol table, and running the image
in system space. These requirements make such an image difficult to debug. The
following procedure creates a resident image that can be more easily debugged.
1. Compile the shareable image. For example:
$ CC/DEBUG/NOOPTIMIZE RESIDENTMODULE.C
2. Link the shareable image using the /DSF qualifier. For example:
$ LINK/NOTRACEBACK/SHAREABLE/SECTION_BINDING/DSF RESIDENTMODULE
See the OpenVMS Linker Utility Manual for information about linking the
image.
3. Create the installed resident image. See OpenVMS System Management
Utilities Reference Manual: A–L for information about using the Install utility.
See OpenVMS System Manager’s Manual, Volume 2: Tuning, Monitoring, and
Complex Systems for information about resident images.
4. Compile the program that calls the resident image. For example:
$ CC/DEBUG/NOOPTIMIZE TESTPROGRAM
5. Create the executable image that calls the resident image. For example:
$ LINK/DSF TESTPROGRAM
6. Create a private copy of the resident image. For example:
$ COPY SYS$LIBRARY:RESIDENTMODULE.EXE []RESIDENTMODULE.EXE
7. Define a logical name that points to the private copy of the resident image.
For example:
$ DEFINE RESIDENTMODULE []RESIDENTMODULE
8. Make sure that the .DSF file for the test program and the .DSF file for the
resident module both reside in the same directory.
9. Define DBG$IMAGE_DSF_PATH to point to the directory that contains the
.DSF files.
10. Invoke the debugger. For example:
$ DEBUG/KEEP TESTPROGRAM
You should now have access to all debugging options for the executable and
resident images.
5–17
6
Controlling the Display of Source Code
The term source code refers to statements in a programming language as they
appear in a source file. Each line of source code is also called a source line.
This chapter covers the following topics:
•
Obtaining information about source files and source lines
•
Specifying the location of a source file that has been moved to another
directory after it was compiled
•
Displaying source lines by specifying line numbers, code address expressions,
or search strings
•
Controlling the display of source code at breakpoints, tracepoints, and
watchpoints and after a STEP command has been executed
•
Using the SET MARGINS command to improve the display of source lines
under certain circumstances
The techniques described in this chapter apply to screen mode as well as line
(noscreen) mode. Any difference in behavior between line mode and screen mode
is identified in this chapter and in the descriptions of the commands discussed.
(Screen mode is described in Chapter 7.)
If your program has been optimized by the compiler, the code that is executing as
you debug might not always match your source code. See Section 14.1 for more
information.
6.1 How the Debugger Obtains Source Code Information
When a compiler processes source files to generate object modules, it assigns
a line number to each source line sequentially. For most languages, each
compilation unit (module) starts with line 1. For other languages like Ada, each
source file, which might represent several compilation units, starts with line 1.
Line numbers appear in a source listing obtained with the /LIST compilecommand qualifier. They also appear whenever the debugger displays source
code, either in line mode or screen mode. Moreover, you can specify line numbers
with several debugger commands (for example, TYPE and SET BREAK).
The debugger displays source lines only if you have specified the /DEBUG
command with both the compile command and the LINK command. Under these
conditions, the symbol information created by the compiler and passed to the
debug symbol table (DST) includes source-line correlation records. For a given
module, source-line correlation records contain the full file specification of each
source file that contributes to that module. In addition, they associate source
records (symbols, types, and so on) with source files and line numbers in the
module.
6–1
Controlling the Display of Source Code
6.2 Specifying the Location of Source Files
6.2 Specifying the Location of Source Files
The debug symbol table (DST) contains the full file specification of each source
file when it was compiled. By default, the debugger expects a source file to be
in the same directory it was in at compile time. If a source file is moved to a
different directory after it is compiled, the debugger does not find it and issues a
warning such as the following when attempting to display source code from that
file:
%DEBUG-W-UNAOPNSRC, unable to open source file DISK:[JONES.WORK]PRG.FOR;2
In such cases, use the SET SOURCE command to direct the debugger to the new
directory. The command can be applied to all source files for your program or to
only the source files for specific modules.
For example, after you enter the following command line, the debugger looks for
all source files in WORK$:[JONES.PROG3]:
DBG> SET SOURCE WORK$:[JONES.PROG3]
You can specify a directory search list with the SET SOURCE command.
For example, after the following command line is entered, the debugger
looks for source files first in the current default directory ([ ]) and then in
WORK$:[JONES.PROG3]:
DBG> SET SOURCE [], WORK$:[JONES.PROG3]
If you want to apply the SET SOURCE command only to the source files for a
given module, use the /MODULE=module-name qualifier and specify that module.
For example, the following command line specifies that the source files for module
SCREEN_IO are in the directory DISK2:[SMITH.SHARE] (the search of source
files for other modules is not affected by this command):
DBG> SET SOURCE/MODULE=SCREEN_IO DISK2:[SMITH.SHARE]
To summarize, the SET SOURCE/MODULE command specifies the location of
source files for a particular module, but the SET SOURCE command specifies
the location of source files for modules that were not mentioned explicitly in SET
SOURCE/MODULE commands.
When you enter a SET SOURCE command, be aware that one of the two
qualifiers, /LATEST or /EXACT, will always be active. The /LATEST qualifier
directs the debugger to search for the latest version of your source files (the
highest-numbered version in your directory). The /EXACT qualifier, the default,
directs the debugger to search for the version last compiled (the version recorded
in the debugger symbol table created at compile time). For example, A SET
SOURCE/LATEST command might search for SORT.FOR;3 while a SET
SOURCE/EXACT command might search for SORT.FOR;1.
Use the SHOW SOURCE command to display all source directory search lists
currently in effect. The command displays the search lists for specific modules (as
previously established by one or more SET SOURCE/MODULE commands) and
the search list for all other modules (as previously established by a SET SOURCE
command). For example:
6–2
Controlling the Display of Source Code
6.2 Specifying the Location of Source Files
DBG> SET SOURCE [PROJA],[PROJB],USER$:[PETER.PROJC]
DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2:[PROJD]
DBG> SHOW SOURCE
source directory search list for COBOLTEST:
[]
DISK$2:[PROJD]
source directory search list for all other modules:
[PROJA]
[PROJB]
USER$:[PETER.PROJC]
DBG>
If no SET SOURCE or SET SOURCE/MODULE command has been entered, the
SHOW SOURCE command indicates that no search list is currently in effect.
Use the CANCEL SOURCE command to cancel the effect of a previous SET
SOURCE command. Use the CANCEL SOURCE/MODULE command to cancel
the effect of a previous SET SOURCE/MODULE command (specifying the same
module name).
When a source directory search list has been canceled, the debugger again
expects the source files corresponding to the designated modules to be in the
same directories they were in at compile time.
For more information about how the debugger locates source files that have been
moved to another directory after compile time, see the SET SOURCE command.
6.3 Displaying Source Code by Specifying Line Numbers
The TYPE command enables you to display source lines by specifying compilerassigned line numbers, where each line number designates a line of source
code.
For example, the following command displays line 160 and lines 22 to 24 of the
module being debugged:
DBG> TYPE 160, 22:24
module COBOLTEST
160: START-IT-PARA.
module COBOLTEST
22: 02
SC2V2 PIC S99V99
23: 02
SC2V2N PIC S99V99
24: 02
CPP2
PIC PP99
DBG>
COMP VALUE 22.33.
COMP VALUE -22.33.
COMP VALUE 0.0012.
You can display all the source lines of a module by specifying a range of line
numbers starting from 1 and ending at a number equal to or greater than the
largest line number in the module.
After displaying a source line, you can display the next line in that module by
entering a TYPE command without a line number—that is, by entering a TYPE
command and then pressing the Return key. For example:
DBG> TYPE 160
module COBOLTEST
160: START-IT-PARA.
DBG> TYPE
module COBOLTEST
161:
MOVE SC1 TO ES0.
DBG>
You can then display the next line and successive lines by entering the TYPE
command repeatedly, which lets you read through your code one line at a time.
6–3
Controlling the Display of Source Code
6.3 Displaying Source Code by Specifying Line Numbers
To display source lines in an arbitrary module of your program, specify the
module name with the line numbers. Use standard pathname notation—that is,
first specify the module name, then a backslash ( \ ), and finally the line numbers
(or the range of line numbers) without intervening spaces. For example, the
following command displays line 16 of module TEST:
DBG> TYPE TEST\16
If you specify a module name with the TYPE command, the module must be set.
Use the SHOW MODULE command to determine whether a particular module is
set. Then use the SET MODULE command, if necessary (see Section 5.2).
If you do not specify a module name with the TYPE command, the debugger
displays source lines for the module in which execution is currently paused by
default—that is, the module associated with the PC scope. If you have specified
another scope with the SET SCOPE command, the debugger displays source lines
in the module associated with the specified scope.
In screen mode, the output of a TYPE command updates the current source
display (see Section 7.2.6).
After displaying source lines at various locations in your program, you can
redisplay the line at which execution is currently paused by pressing KP5.
6.4 Displaying Source Code by Specifying Code Address
Expressions
The EXAMINE/SOURCE command enables you to display the source line
corresponding to a code address expression. A code address expression denotes
the address of a machine-code instruction and, therefore, must be one of the
following:
•
A line number associated with one or more instructions
•
A label
•
A routine name
•
The memory address of an instruction
You cannot specify a variable name with the EXAMINE/SOURCE command,
because a variable name is associated with data, not with instructions.
When you use the EXAMINE/SOURCE command, the debugger evaluates the
address expression to obtain a memory address, determines which compilerassigned line number corresponds to that address, and then displays the source
line designated by the line number.
For example, the following command line displays the source line associated with
the address (declaration) of routine SWAP:
DBG> EXAMINE/SOURCE SWAP
module MAIN
47: procedure SWAP(X,Y: in out INTEGER) is
DBG>
If you specify a line number that is not associated with an instruction, the
debugger issues a diagnostic message. For example:
6–4
Controlling the Display of Source Code
6.4 Displaying Source Code by Specifying Code Address Expressions
DBG> EXAMINE/SOURCE %LINE 6
%DEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8
%DEBUG-E-NOSYMBOL, symbol ’%LINE 6’ is not in the symbol table
DBG>
When using the EXAMINE/SOURCE command with a symbolic address
expression (a line number, label, or routine), you might need to set the module
in which the entity is defined, unless that module is already set. Use the SHOW
MODULE command to determine whether a particular module is set. Then, if
necessary, use the SET MODULE command (see Section 5.2).
The command EXAMINE/SOURCE .%PC displays the source line corresponding
to the current PC value (the line that is about to be executed). For example:
DBG> EXAMINE/SOURCE .%PC
module COBOLTEST
162:
DISPLAY ES0.
DBG>
Note the use of the contents-of operator ( . ), which specifies the contents of
the entity that follows the period. If you do not use the contents-of operator,
the debugger tries to find a source line for the PC rather than for the address
currently stored in the PC:
DBG> EXAMINE/SOURCE %PC
%DEBUG-W-NOSRCLIN, no source line for address 7FFF005C
DBG>
The following example shows the use of a numeric path name (1\) to display
the source line at the PC value one level down the call stack (at the call to the
routine in which execution is paused):
DBG> EXAMINE/SOURCE .1\%PC
In screen mode, the output of an EXAMINE/SOURCE command updates the
current source display (see Section 7.2.6).
The debugger uses the EXAMINE/SOURCE command in the following contexts to
display source code at the current PC value.
Keypad key 5 (KP5) is bound to the following debugger command sequence:
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC; EXAMINE/INST .%INST_SCOPE\%PC
This command sequence displays the source line and the instruction at which
execution is currently paused in the current scope. Pressing KP5 enables you to
quickly determine your debugging context.
The predefined source display SRC is an automatically updated display that
executes the following built-in command every time the debugger interrupts
execution and prompts for commands (see Section 7.4.1):
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC
6.5 Displaying Source Code by Searching for Strings
The SEARCH command enables you to display any source lines that contain an
occurrence of a specified string.
The syntax of the SEARCH command is as follows:
SEARCH[/qualifier[, . . . ]] [range] [string]
6–5
Controlling the Display of Source Code
6.5 Displaying Source Code by Searching for Strings
The range parameter can be a module name, a range of line numbers, or a
combination of both. If you do not specify a module name, the debugger uses the
current scope to find source lines, as with the TYPE command (see Section 6.3).
By default, the SEARCH command displays the source line that contains the first
(next) occurrence of a string in a specified range (SEARCH/NEXT). The command
SEARCH/ALL displays all source lines that contain an occurrence of a string in a
specified range. For example, the following command line displays the source line
that contains the first occurrence of the string pro in module SCREEN_IO:
DBG> SEARCH SCREEN_IO pro
The remaining examples use source lines from one COBOL module, in the current
scope, to show various aspects of the SEARCH command.
The following command line displays all source lines within lines 40 to 50 that
contain an occurrence of the string D:
DBG> SEARCH/ALL 40:50 D
module COBOLTEST
40: 02
D2N
COMP-2 VALUE -234560000000.
41: 02
D
COMP-2 VALUE 222222.33.
42: 02
DN
COMP-2 VALUE -222222.333333.
47: 02
DR0
COMP-2 VALUE 0.1.
48: 02
DR5
COMP-2 VALUE 0.000001.
49: 02
DR10
COMP-2 VALUE 0.00000000001.
50: 02
DR15
COMP-2 VALUE 0.0000000000000001.
DBG>
After you have found an occurrence of a string in a particular module, you can
enter the SEARCH command with no parameters to display the source line
containing the next occurrence of the same string in the same module. This is
similar to using the TYPE command without a parameter to display the next
source line. For example:
DBG> SEARCH 42:50 D
module COBOLTEST
42: 02
DN
DBG> SEARCH
module COBOLTEST
47: 02
DR0
DBG>
COMP-2 VALUE -222222.333333.
COMP-2 VALUE 0.1.
By default, the debugger searches for a string as specified and does not interpret
the context surrounding an occurrence of the string (this is the behavior of
SEARCH/STRING). If you want to locate an occurrence of a string that is
an identifier in your program (for example, a variable name) and exclude
other occurrences of the string, use the /IDENTIFIER qualifier. The command
SEARCH/IDENTIFIER displays only those occurrences of the string that are
bounded on either side by a character that cannot be part of an identifier in the
current language.
The default qualifiers for the SEARCH command are /NEXT and /STRING. If you
want to establish different default qualifiers, use the SET SEARCH command.
For example, after the following command is executed, the SEARCH command
behaves like SEARCH/IDENTIFIER:
DBG> SET SEARCH IDENTIFIER
6–6
Controlling the Display of Source Code
6.5 Displaying Source Code by Searching for Strings
Use the SHOW SEARCH command to display the default qualifiers currently in
effect for the SEARCH command. For example:
DBG> SHOW SEARCH
search settings: search for next occurrence, as an identifier
DBG>
6.6 Controlling Source Display After Stepping and at Eventpoints
By default, the debugger displays the associated source line when a breakpoint,
tracepoint, or watchpoint is triggered and upon the completion of a STEP
command.
When you enter a STEP command, the debugger displays the source line at which
execution is paused after the step. For example:
DBG> STEP
stepped to MAIN\%LINE 16
16:
RANGE := 500;
DBG>
When a breakpoint or tracepoint is triggered, the debugger displays the source
line at the breakpoint or tracepoint, respectively. For example:
DBG> SET BREAK SWAP
DBG> GO
.
.
.
break at MAIN\SWAP
47: procedure SWAP(X,Y: in out INTEGER) is
DBG>
When a watchpoint is triggered, the debugger displays the source line
corresponding to the instruction that caused the watchpoint to be triggered.
The SET STEP [NO]SOURCE command enables you to control the display of
source code after a step and at breakpoints, tracepoints, and watchpoints. SET
STEP SOURCE, the default, enables source display. SET STEP NOSOURCE
suppresses source display. For example:
DBG> SET STEP NOSOURCE
DBG> STEP
stepped to MAIN\%LINE 16
DBG> SET BREAK SWAP
DBG> GO
.
.
.
break at MAIN\SWAP
DBG>
You can selectively override the effect of a SET STEP SOURCE command or
a SET STEP NOSOURCE command by using the qualifiers /SOURCE and
/NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET WATCH
commands.
6–7
Controlling the Display of Source Code
6.6 Controlling Source Display After Stepping and at Eventpoints
The STEP/SOURCE command overrides the effect of the SET STEP NOSOURCE
command, but only for the duration of that STEP command (similarly,
STEP/NOSOURCE overrides the effect of SET STEP SOURCE for the duration of
that STEP command). For example:
DBG> SET STEP NOSOURCE
DBG> STEP/SOURCE
stepped to MAIN\%LINE 16
16:
RANGE := 500;
DBG>
The SET BREAK/SOURCE command overrides the effect of the SET STEP
NOSOURCE command, but only for the breakpoint set with that SET BREAK
command (similarly, SET BREAK/NOSOURCE overrides the effect of SET STEP
SOURCE for the breakpoint set with that SET BREAK command). The same
conventions apply to the SET TRACE and SET WATCH commands. For example:
DBG> SET STEP SOURCE
DBG> SET BREAK/NOSOURCE SWAP
DBG> GO
.
.
.
break at MAIN\SWAP
DBG>
6.7 Setting Margins for Source Display
The SET MARGINS command enables you to specify the leftmost and rightmost
source-line character positions at which to begin and end the display of a source
line (respectively, the left and right margins). This is useful for controlling the
display of source code when, for example, the code is deeply indented or long lines
wrap at the right margin. In such cases, you can set the left margin to eliminate
indented space in the source display, and you can decrease the right margin
setting to truncate lines and prevent them from wrapping.
For example, the following command line sets the left margin to column 20 and
the right margin to column 35.
DBG> SET MARGINS 20:35
Subsequently, only that portion of the source code that is between columns 20 and
35 is displayed when you enter commands that display source lines (for example,
TYPE, SEARCH, STEP). Use the SHOW MARGINS command to identify the
current margin settings for the display of source lines.
Note that the SET MARGINS command affects only the display of source lines.
It does not affect the display of other debugger output (for example, output from
an EXAMINE command).
The SET MARGINS command is useful mostly in line (noscreen) mode. In screen
mode, the SET MARGINS command has no effect on the display of source lines
in a source display, such as the predefined display SRC.
6–8
7
Screen Mode
Screen mode is an enhancement to the command line interface of the OpenVMS
debugger that enables you to simultaneously display separate groups of data
about the debugging session, in a manner similar to that available with the HP
DECwindows Motif for OpenVMS user interface (see Part III). For example,
you can display source code in one portion of the screen, register contents in a
different portion, debugger output in another portion, and so on.
To invoke screen mode, press PF3 on the keypad (or enter the SET MODE
SCREEN command). To return to line-oriented debugging, press PF1 PF3 (or
enter the SET MODE NOSCREEN command).
Note
Note that you cannot enter screen mode from within the DECWindows
Motif interface to the debugger.
Screen mode output is best displayed on VT-series terminals with higher numbers
than VT52, and on workstations running VWS. The larger screen of workstations
is particularly suitable to using a number of displays for different purposes.
This chapter covers the following topics:
•
Screen mode concepts and terminology used throughout the chapter
•
Using different kinds of displays
•
Directing debugger output to different displays by assigning display attributes
•
Using predefined displays SRC, OUT, PROMPT, INST, REG, IREG, and
FREG (Alpha only), which are automatically available when you enter screen
mode
•
Scrolling, hiding, deleting, moving, and resizing a display
•
Creating a new display
•
Specifying a display window
•
Creating a display configuration
•
Saving the current state of screen displays
•
Changing your terminal screen’s height and width during a debugging session
and the effect on display windows
•
Using screen-related debugger built-in symbols
•
Using predefined windows
•
Enabling country-specific features for screen mode
7–1
Screen Mode
Many screen mode commands are bound to keypad keys. For key definitions, see
Appendix A.
Note
This chapter provides information common to programs that run in one or
several processes. See Chapter 15 for additional information specific to
multiprocess programs.
7.1 Concepts and Terminology
A display is a group of text lines. The text can be lines from a source file,
assembly-language instructions, the values contained in registers, your input to
the debugger, debugger output, or program input and output.
You view a display through its display window, which can occupy any
rectangular area of the screen. Because a display window is typically smaller
than the associated display, you can scroll the display window up, down, right,
and left across the display text to view any part of the display.
Figure 7–1 is an example of screen mode that shows three display windows. The
name of each display (SRC, OUT, and PROMPT) appears at the top left corner of
its display window. The display name serves both as a tag on the display itself
and as a name for future reference in commands.
Figure 7–1 Default Screen Mode Display Configuration
SRC: module SQUARES$MAIN
scroll−source
7: C
−− Square all
non−zero elements and store in output array
8:
K = 0
9:
DO 10 I = 1, N
10:
IF(INARR(I) .NE. 0) THEN
OUTARR(K) = INARR(I)**2
−> 11:
12:
ENDIF
13:
10 CONTINUE
14: C
15: C
−− Print the squared output values. Then stop.
16:
PRINT 20, K
17: 20
FORMAT(’ Number of non−zero elements is’,I4)
OUT−output
stepped to SQUARES$MAIN\%LINE 9
9:
DO 10 I = 1, N
SQUARES$MAIN\N:
9
SQUARES$MAIN\K:
0
stepped to SQUARES$MAIN\%LINE 11
PROMPT error−program−prompt
DBG> EXAM N, K
DBG> STEP 2
DGB>
ZK−6503−GE
Figure 7–1 is the default display configuration established when you first invoke
screen mode. SRC, OUT, and PROMPT are three of the predefined displays
that the debugger provides when you enter screen mode (see Section 7.4). You can
modify the configuration of these displays as well as create additional displays.
7–2
Screen Mode
7.1 Concepts and Terminology
Displays SRC, OUT, and PROMPT have the following basic characteristics:
•
SRC is a source-code display that occupies the upper half of the screen
(it displays Fortran code in Figure 7–1). The name of the source module
displayed, SQUARES$MAIN, is to the right of the display name.
•
OUT, located in a window directly below SRC, shows the output of debugger
commands.
•
PROMPT, at the bottom of the screen, shows the debugger prompt and
debugger input.
Conceptually, displays are placed on the screen as on a pasteboard. The display
most recently referenced by a command is put on top of the pasteboard by default.
Therefore, depending on their screen locations, display windows that you have
referenced recently might overlay or hide other display windows.
The debugger maintains a display list, which is the pasting order of displays.
Several keypad key definitions use the display list to cycle through the displays
currently on the pasteboard.
Every display belongs to a display kind (see Section 7.2). The display kind
determines what type of information the display can capture and display, such as
source code, or debugger output. The display kind defines whether displayed data
is paged into the memory buffer or discarded when the memory buffer overflows.
The display kind also determines how the contents of the display are generated.
The contents of a display are generated in two ways:
•
Some displays are automatically updated. Their definition includes a
command list that is executed whenever the debugger gains control from
the program. The output of the command list forms the contents of those
displays. Display SRC belongs to that category: it is automatically updated
so that an arrow points to the source line at which execution is currently
paused.
•
Other displays, for example, display OUT, are updated in response to
commands you enter interactively. For a display of this type to be updated, it
must first be assigned an appropriate display attribute (with the SELECT
command). The display attribute identifies the display as the target display
for one or more types of output (see Section 7.3).
The names of any attributes assigned to a display appear to the right of the
display name, in lowercase letters. In Figure 7–1, SRC has the source and scroll
attributes (SRC is the current source display and the current scrolling
display), OUT has the output attribute (it is the current output display),
and so on. Note that, although SRC is automatically updated by its own built-in
command, it can also receive the output of certain interactive commands (such as
EXAMINE/SOURCE) because it has the source attribute.
The concepts introduced in this section are developed in more detail in the rest of
this chapter.
7–3
Screen Mode
7.2 Display Kinds
7.2 Display Kinds
Every display has a display kind. The display kind determines the type of
information a display contains, how that information is generated, and whether
the memory buffer associated with the display is paged.
Typically, you specify a display kind when you use the DISPLAY command to
create a new display (if you do not specify a display kind, an output display is
created). You can also use the DISPLAY command to change the display kind of
an existing display with the following keywords:
DO (command[,...])
INSTRUCTION
INSTRUCTION (command)
OUTPUT
REGISTER
SOURCE
SOURCE (command)
The contents of a register display are generated and updated automatically
by the debugger. The contents of other kinds of displays are generated by
commands, and these display kinds fall into two general groups.
A display that belongs to one of the following display kinds has its contents
updated automatically according to the command or command list you supply
when defining that display:
DO (command[,...])
INSTRUCTION (command)
REGISTER
SOURCE (command)
The command list specified is executed each time the debugger gains control
from your program, if the display is not marked as removed. The output of the
commands forms the new contents of the display. If the display is marked as
removed, the debugger does not execute the command list until you view that
display (marking that display as unremoved).
A display that belongs to one of the following display kinds derives its contents
from commands that you enter interactively:
INSTRUCTION
OUTPUT
SOURCE
To direct debugger output to a specific display in this group, you must first select
it with the SELECT command. The technique is explained in the following
sections and in Section 7.3. After a display is selected for a certain type of output,
the output from your commands forms the contents of the display.
7.2.1 DO (Command[; . . . ]) Display Kind
A DO display is an automatically-updated display. The commands in the
command list are executed in the order listed each time the debugger gains
control from your program. Their output forms the contents of the display and
erases any previous contents.
7–4
Screen Mode
7.2 Display Kinds
For example, the following command creates the DO display CALLS at window
Q3. (Window Q3 refers to screen dimensions of the window. For information
about screen dimensions and predefined windows, see Section 7.12.) Each time
the debugger gains control from the program, the SHOW CALLS command is
executed and the output is displayed in CALLS, replacing any previous contents.
DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)
The following command creates a DO display named V2_DISP that shows the
contents of elements 4 to 7 of the vector register V2 (using Fortran array syntax).
The display is automatically updated whenever the debugger gains control from
the program:
DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7))
The default size of the memory buffer associated with any DO display is 64 lines.
When the memory buffer is full, the oldest lines are discarded to make room for
new text. You can use the DISPLAY/SIZE command to change the buffer size.
7.2.2 INSTRUCTION Display Kind
An instruction display shows the output of an EXAMINE/INSTRUCTION
command within the instruction stream of a routine. Because the instructions
displayed are decoded from the image being debugged and show the exact code
that is executing, this kind of display is particularly useful in helping you debug
optimized code (see Section 14.1).
In the display, one line is devoted to each instruction. Source-line numbers
corresponding to the instructions are displayed in the left column. The instruction
at the location being examined is centered in the display and is marked by an
arrow in the left column.
Before anything can be written to an instruction display, you must select it as the
current instruction display with the SELECT/INSTRUCTION command.
In the following example, the DISPLAY command creates the instruction display
INST2 at RH1. The SELECT/INSTRUCTION command then selects INST2 as
the current instruction display. When the EXAMINE/INSTRUCTION X command
is executed, window RH1 fills with the instruction stream surrounding the
location denoted by X. The arrow points to the instruction at location X, which is
centered in the display.
DBG> DISPLAY INST2 AT RH1 INSTRUCTION
DBG> SELECT/INSTRUCTION INST2
DBG> EXAMINE/INSTRUCTION X
Each subsequent EXAMINE/INSTRUCTION command updates the display.
The default size of the memory buffer associated with any instruction display is
64 lines; however, you can scroll back and forth to view all the instructions within
the routine. You can use the DISPLAY/SIZE command to change the buffer size
and improve performance.
7.2.3 INSTRUCTION (Command) Display Kind
This is an instruction display that is automatically updated with the output of
the command specified. That command, which must be an
EXAMINE/INSTRUCTION command, is executed each time the debugger gains
control from your program.
7–5
Screen Mode
7.2 Display Kinds
For example, the following command creates the instruction display INST3 at
window RS45. Each time the debugger gains control, the built-in command
EXAMINE/INSTRUCTION .%INST_SCOPE\%PC is executed, updating the
display.
DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC)
This command creates a display that functions like the predefined display INST.
The built-in EXAMINE/INSTRUCTION command displays the instruction at the
current PC value in the current scope (see Section 7.4.4).
If an automatically updated instruction display is selected as the current
instruction display, it is updated like a simple instruction display by an
interactive EXAMINE/INSTRUCTION command (in addition to being updated by
its built-in command).
The default size of the memory buffer associated with any instruction display is
64 lines; however, you can scroll back and forth to view all the instructions within
the routine. You can use the DISPLAY/SIZE command to change the buffer size
and improve performance.
7.2.4 OUTPUT Display Kind
An output display shows any debugger output that is not directed to another
display. New output is appended to the previous contents of the display.
Before anything can be written to an output display, it must be selected as
the current output display with the SELECT/OUTPUT command, or as the
current error display with the SELECT/ERROR command, or as the current
input display with the SELECT/INPUT command. See Section 7.3 for more
information about using the SELECT command with output displays.
In the following example, the DISPLAY command creates the output display
OUT2 at window T2 (the display kind OUTPUT can be omitted from this
example, because it is the default kind). The SELECT/OUTPUT command then
selects OUT2 as the current output display. These two commands create a display
that functions like the predefined display OUT:
DBG> DISPLAY OUT2 AT T2 OUTPUT
DBG> SELECT/OUTPUT OUT2
OUT2 now collects any debugger output that is not directed to another display.
For example:
•
The output of a SHOW CALLS command goes to OUT2.
•
If no instruction display has been selected as the current instruction display,
the output of an EXAMINE/INSTRUCTION command goes to OUT2.
•
By default, debugger diagnostic messages are directed to the PROMPT
display. They can be directed to OUT2 with the SELECT/ERROR command.
The default size of the memory buffer associated with any output display is 64
lines. When the memory buffer is full, the oldest lines are discarded to make
room for new text. You can use the DISPLAY/SIZE command to change the buffer
size.
7–6
Screen Mode
7.2 Display Kinds
7.2.5 REGISTER Display Kind
A register display is an automatically updated display that shows the current
values, in hexadecimal format, of the processor registers and as many of the top
call-stack values as will fit in the display.
The register values displayed are for the routine in which execution is currently
paused. The values are updated whenever the debugger takes control. Any
changed values are highlighted.
There are up to three predefined register displays. The REG, IREG, and FREG
displays are predefined on Alpha and Integrity server processors. The contents of
the predefined displays are shown in Table 7–1.
Table 7–1 Predefined Register Displays
Display
Alpha
Intel Itanium
REG
-
R0 to R31
PC
PS
F0 to F31
FPCR
SFPCR
top of call-stack values
- PC
- CFM
- R1 to R31
- R32 to R127 ( as
many as are used)
- F2 to F127
- top-of-stack
values
IREG
- R0 to R31
- PC
- PS
- top of call-stack values
The data is shown in
hexadecimal format.
- PC
- CFM
- R1 to R31
- top of call-stack
values
The data is shown
in hexadecimal
format.
FREG
- F0 to F31
- FPCR
- SFPCR
- top of call-stack values
The data is shown in floatingpoint format.
- F2 to F127
- top-of-stack
values
The register data
is shown in the
format consistent
with the data
value (integer or
floating-point);
the stack values
are shown in
floating-point
format.
On Alpha processors, the predefined display REG contains, in hexadecimal
format, general-purpose registers R0 to R28, FP (R29), SP (R30), R31, PC,
PS floating-point registers F0 to F31, FPCR, SFPCR, and as many of the top
call-stack values as will fit in the display.
On Alpha processors, the predefined display IREG contains, in hexadecimal
format, general-purpose registers R0 to R28, FP, and as many of the top call-stack
values as can be displayed in the window.
On Alpha processors, the predefined display FREG contains floating-point
registers F0 to F31, FPCR, SFPCR, displayed in floating-point format and as
many of the top call-stack values (in hexadecimal format) as can be displayed in
the window.
7–7
Screen Mode
7.2 Display Kinds
The default size of the memory buffer associated with any register display is 64
lines. When the memory buffer is full, the oldest lines are discarded to make
room for new text. You can use the DISPLAY/SIZE command to change the buffer
size.
7.2.6 SOURCE Display Kind
A source display shows the output of a TYPE or EXAMINE/SOURCE command
within the source code of a module, if that source code is available. Source line
numbers are displayed in the left column. The source line that is the output of
the command is centered in the display and is marked by an arrow in the left
column. If a range of lines is specified with the TYPE command, the lines are
centered in the display, but no arrow is shown.
Before anything can be written to a source display, you must select it as the
current source display with the SELECT/SOURCE command.
In the following example, the DISPLAY command creates source display SRC2 at
Q2. The SELECT/SOURCE command then selects SRC2 as the current source
display. When the TYPE 34 command is executed, window RH1 fills with the
source code surrounding line 34 of the module being debugged. The arrow points
to line 34, centered in the display.
DBG> DISPLAY SRC2 AT Q2 SOURCE
DBG> SELECT/SOURCE SRC2
DBG> TYPE 34
Each subsequent TYPE or EXAMINE/SOURCE command updates the display.
The default size of the memory buffer of a source display is 64 lines. The memory
buffer of a source display is paged, enabling you to scroll back and forth through
the entire source module or routine. You can use the DISPLAY/SIZE command to
change the buffer size to improve performance.
7.2.7 SOURCE (Command) Display Kind
This is a source display that is automatically updated with the output of the
command specified. That command, which must be an EXAMINE/SOURCE or
TYPE command, is executed each time the debugger gains control from your
program.
For example, the following command creates source display SRC3 at window
RS45. Each time the debugger gains control, it executes the built-in command
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC and updates the display.
DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .%SOURCE_SCOPE\%PC)
This command creates a display that functions like the predefined display SRC.
The built-in EXAMINE/SOURCE command displays the source line for the
current PC value in the current scope (see Section 7.4.1).
If you select an automatically updated source display as the current source
display, it displays the output generated by an interactive
EXAMINE/SOURCE or TYPE command in addition to the output generated by
its built-in command.
The default size of the memory buffer of a source display is 64 lines. The memory
buffer of an automatically updated source display is paged, enabling you to scroll
back and forth through the entire source module or routine. You can use the
DISPLAY/SIZE command to change the buffer size to improve performance.
7–8
Screen Mode
7.2 Display Kinds
7.2.8 PROGRAM Display Kind
A program display can receive the output of the program being debugged. The
predefined PROMPT display belongs to the program display kind, and is the only
display permitted of that kind. You cannot create a new display of the program
display kind.
To avoid possible confusion, the PROMPT display has several restrictions (see
Section 7.4.3).
7.3 Display Attributes
In screen mode, the output from commands you enter interactively is directed
to various displays according to the type of output and the display attributes
assigned to these displays. For example, debugger diagnostic messages go to
the display that has the error attribute (the current error display). By assigning
one or more attributes to a display, you can mix or isolate different kinds of
information.
7–9
Screen Mode
7.3 Display Attributes
The attributes have the following names:
error
input
instruction
output
program
prompt
scroll
source
When a display is assigned an attribute, the name of that attribute appears
in lowercase letters on the top border of its window to the right of the display
name. Note that the scroll attribute does not affect debugger output but is used
to control the default display for the SCROLL, MOVE, and EXPAND commands.
By default, attributes are assigned to the predefined displays as follows:
•
SRC has the source and scroll attributes
•
OUT has the output attribute
•
PROMPT has the prompt, program, and error attributes
To assign an attribute to a display, use the SELECT command with the qualifier
of the same name as the attribute. In the following example, the DISPLAY
command creates the output display ZIP. The SELECT/OUTPUT command
then selects ZIP as the current output display—the display that has the output
attribute. After this command is executed, the word "output" disappears from
the top border of the predefined output display OUT and appears instead on
display ZIP, and all the debugger output formerly directed to OUT is now directed
to ZIP.
DBG> DISPLAY ZIP OUTPUT
DBG> SELECT/OUTPUT ZIP
You can assign specific attributes only to certain display kinds. The following
list identifies each of the SELECT command qualifiers, its effect, and the display
kinds to which you can assign that attribute:
SELECT Qualifier
7–10
Apply to
Display Kind
Description
/ERROR
Output
Prompt
Selects the specified display as the current error
display. Directs any subsequent debugger diagnostic
message to that display. If no display is specified,
selects the PROMPT display as the current error
display.
/INPUT
Output
Selects the specified display as the current input
display. Echoes any subsequent debugger input in
that display. If no display is specified, unselects the
current input display: debugger input is not echoed
to any display.
Screen Mode
7.3 Display Attributes
SELECT Qualifier
Apply to
Display Kind
/INSTRUCTION
Instruction
Selects the specified display as the current
instruction display. Directs the output of any
subsequent EXAMINE/INSTRUCTION command
to that display. Keypad key sequence PF4 COMMA
selects the next instruction display in the display list
as the current instruction display. If no display is
specified, unselects the current instruction display:
no display has the instruction attribute.
/OUTPUT
Output
Prompt
Selects the specified display as the current output
display. Directs any subsequent debugger output
to that display, except where a particular type of
output is being directed to another display (such
as diagnostic messages going to the current error
display). Keypad key sequence PF1 KP3 selects the
next output display in the display list as the current
output display. If no display is specified, selects the
PROMPT display as the current output display.
/PROGRAM
Prompt
Selects the specified display as the current program
display. Tries to force any subsequent program
input or output to that display. If no display is
specified, unselects the current program display:
program input and output are no longer forced to the
PROMPT display.
/PROMPT
Prompt
Selects the specified display as the current prompt
display where the debugger prompts for input. You
cannot unselect the PROMPT display.
/SCROLL
All
Selects the specified display as the current scrolling
display. Makes that display the default display
for any subsequent SCROLL, MOVE, or EXPAND
command. You can specify any display (however,
note that the PROMPT display cannot be scrolled).
The /SCROLL qualifier is the default if you do not
specify a qualifier with the SELECT command. Key
KP3 selects as the current scrolling display the next
display in the display list after the current scrolling
display. If no display is specified, unselects the
current scrolling display: no display has the scroll
attribute.
/SOURCE
Source
Selects the specified display as the current source
display. Directs the output of any subsequent TYPE
or EXAMINE/SOURCE command to that display.
Keypad key sequence PF4 KP3 selects the next
source display in the display list as the current
source display. If no display is specified, unselects
the current source display: no display has the source
attribute.
Description
Subject to the restrictions listed, a display can have several attributes. In the
preceding example, ZIP was selected as the current output display. In the next
example, ZIP is further selected as the current input, error, and scrolling display.
After these commands are executed, debugger input, output, and diagnostics
are logged in ZIP in the proper sequence as they occur, and ZIP is the current
scrolling display.
DBG> SELECT/INPUT/ERROR/SCROLL ZIP
To identify the displays currently selected for each of the display attributes, use
the SHOW SELECT command.
7–11
Screen Mode
7.3 Display Attributes
If you use the SELECT command with a particular qualifier but without
specifying a display name, the effect is typically to deassign that attribute (to
unselect the display that had the attribute). The exact effect depends on the
attribute, as described in the preceding table.
7.4 Predefined Displays
The debugger provides the following predefined displays that you can use to
capture and display different kinds of data:
SRC, the predefined source display
OUT, the predefined output display
PROMPT, the predefined prompt display
INST, the predefined instruction display
REG, the predefined register display
FREG, the predefined floating-point register display (Alpha only)
IREG, the predefined integer register display
When you enter screen mode, the debugger puts SRC in the top half of the screen,
PROMPT in the bottom sixth, and OUT between SRC and PROMPT, as shown
in Figure 7–1. Displays INST, REG, FREG (Alpha only), and IREG are initially
removed from the screen by default.
To re-create this default configuration, press BLUE MINUS on the keypad (PF4
followed by the MINUS ( – ) key).
The basic features of the predefined displays are described in the next sections.
As explained in other parts of this chapter, you can change certain characteristics
of these displays, such as the buffer size or display attributes. You can also create
additional displays similar to the predefined displays.
To display summary information about the characteristics of any display, use the
SHOW DISPLAY command.
Table 7–2 summarizes key information about the predefined displays.
Table 7–2 Predefined Displays
Display Name
Display Kind
Valid Display Attributes
SRC
Source
Scroll
Source (By Default)
X
OUT
Output
Error
Input
Output (By Default)
Scroll
X
PROMPT
Output
Error (By Default)
Output
Program (By Default)
Prompt (By Default)
Scroll 1
X
INST
Instruction
Instruction
Scroll
REG
Register
Scroll
1 The
Visible on Startup
predefined PROMPT display cannot be scrolled.
(continued on next page)
7–12
Screen Mode
7.4 Predefined Displays
Table 7–2 (Cont.) Predefined Displays
Display Name
Display Kind
Valid Display Attributes
FREG (Alpha only)
Register
Scroll
IREG
Register
Scroll
Visible on Startup
7.4.1 Predefined Source Display (SRC)
Note
See Chapter 6 for information about how to make source code available
for display during a debugging session.
The predefined display SRC (see Figure 7–1) is an automatically updated source
display.
You can use SRC to display source code in two basic ways:
•
By default, SRC automatically displays the source code for the module in
which execution is currently paused. This enables you to quickly determine
your current debugging context.
•
In addition, because SRC has the source attribute by default, you can use
it to display the source code for any part of your program as explained in
Section 7.4.1.1.
The name of the module whose source code is displayed is shown at the right
of the display name, SRC. The numbers displayed at the left of the source code
are the compiler-generated line numbers, as they might appear in a compilergenerated listing file.
As you execute the program under debugger control, SRC is automatically
updated whenever execution is paused. The arrow in the leftmost column
indicates the source line to be executed next. Specifically, execution is paused at
the first instruction associated with that source line. Thus, the line indicated by
the arrow corresponds to the current program counter (PC) value. The PC is a
register that contains the memory address of the next instruction to be executed.
If the debugger cannot locate source code for the routine in which execution is
paused (because, for example, the routine is a run-time library routine), it tries
to display source code in the next routine down on the call stack for which source
code is available. When displaying source code for such a routine, the debugger
issues the following message:
%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC.
Displaying source in a caller of the current routine.
Figure 7–2 shows this feature. The source display shows that a call to routine
TYPE is currently active. TYPE corresponds to a Fortran run-time library
procedure. No source code is available for that routine, so the debugger displays
the source code of the calling routine. The output of a SHOW CALLS command,
shown in the output display, identifies the routine where execution is paused and
the call sequence leading to that routine.
In such cases, the arrow in the source window identifies the line to which
execution returns after the routine call. Depending on the source language and
coding style, this might be the line that contains the call statement or the next
line.
7–13
Screen Mode
7.4 Predefined Displays
Figure 7–2 Screen Mode Source Display When Source Code Is Not Available
SRC: module TEST scroll−source
%DEBUG−I−SOURCESCOPE, Source lines not available for .0\%PC
Displaying source in a caller of the current routine
CHARACTER*(*) ARRAYX
3:
TYPE *, ARRAYX
−>
4:
RETURN
5:
END
6:
OUT−output
stepped to SHARE$FORRTL+810
module name
routine name
SHARE$FORRTL
SHARE$FORRTL
*TEST
TEST
*A
A
line
4
3
rel PC
0000032A
0000001E
00000011
abs PC
00000B2A
00000436
00000411
PROMPT−error−program−prompt
DBG> STEP
DBG> SHOW CALLS
DBG>
ZK−6504−GE
If your program was optimized during compilation, the source code displayed
in SRC might not always represent the code that is actually executing. The
predefined instruction display INST is useful in such cases, because it shows the
exact instructions that are executing (see Section 7.4.4).
The built-in command that automatically updates display SRC is
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC. For information about the
EXAMINE/SOURCE command, see Section 6.4. The built-in debugger symbol
%SOURCE_SCOPE denotes a scope and has the following properties:
•
By default %SOURCE_SCOPE denotes scope 0, which is the scope of the
routine where execution is currently paused.
•
If you have reset the scope search list relative to the call stack by means
of the SET SCOPE/CURRENT command (see Section 7.4.1.2), %SOURCE_
SCOPE denotes the current scope specified (the scope of the routine at the
start of the search list).
•
If source code is not available for the routine in the current scope,
%SOURCE_SCOPE denotes scope n, where n is the first level down the
call stack for which source code is available.
7.4.1.1 Displaying Source Code in Arbitrary Program Locations
You can use display SRC to display source code throughout your program, if
source code is available for display:
7–14
•
You can scroll through the entire source display by pressing KP2 (scroll down)
or KP8 (scroll up) as explained in Section 7.5.1. This enables you to view any
of the source code within the module in which execution is paused.
•
You can display the source code for any routine that is currently on the call
stack by using the SET SCOPE/CURRENT command (see Section 7.4.1.2).
Screen Mode
7.4 Predefined Displays
•
Because SRC has the source attribute, you can display source code throughout
your program by using the TYPE and EXAMINE/SOURCE commands:
To display arbitrary source lines, use the TYPE command (see
Section 6.3).
To display the source line associated with a code location (for example,
a routine declaration), use the EXAMINE/SOURCE command (see
Section 6.4).
When using the TYPE or EXAMINE/SOURCE command, make sure that the
module in which you want to view source code is set first. Use the SHOW
MODULE command to determine whether a particular module is set. Then
use the SET MODULE command, if necessary (see Section 5.2).
After manipulating the contents of display SRC, you can redisplay the location
at which execution is currently paused (the default behavior of SRC) by pressing
KP5.
7.4.1.2 Displaying Source Code for a Routine on the Call Stack
The command SET SCOPE/CURRENT lets you display the source code for any
routine that is currently on the call stack. For example, the following command
updates display SRC so that it shows the source code for the caller of the routine
in which execution is currently paused:
DBG> SET SCOPE/CURRENT 1
To reset the default scope for displaying source code, enter the command CANCEL
SCOPE. The command causes display SRC to show the source code for the routine
at the top of the call stack where execution is paused.
7.4.2 Predefined Output Display (OUT)
Figure 7–1 and Figure 7–2 show some typical debugger output in the predefined
display OUT.
Display OUT is a general-purpose output display. By default, OUT has the output
attribute so it displays any debugger output that is not directed to the source
display SRC or the instruction display INST. For example, if display INST is
not displayed or does not have the instruction attribute, any output that would
otherwise update display INST is shown in display OUT.
By default, OUT does not display debugger diagnostic messages (these appear
in the PROMPT display). You can assign display attributes to OUT so that
it captures debugger input and diagnostics as well as normal output (see
Section 7.3).
By default, the memory buffer associated with predefined display OUT contains
100 lines.
7.4.3 Predefined Prompt Display (PROMPT)
The predefined display PROMPT is the display in which the debugger prompts
for input. Figure 7–1 and Figure 7–2 show PROMPT in its default location, the
bottom sixth of the screen.
By default, PROMPT has the prompt attribute. In addition, PROMPT also has
(by default) the program and error attributes, which force program output and
diagnostic messages to that display.
7–15
Screen Mode
7.4 Predefined Displays
PROMPT has different properties and restrictions than other displays. This is to
eliminate possible confusion when manipulating that display:
•
The PROMPT display window is always fully visible. You cannot hide
PROMPT (with the DISPLAY/HIDE command), remove PROMPT from the
pasteboard (with the DISPLAY/REMOVE command), or delete PROMPT (with
the CANCEL DISPLAY command).
•
You can assign PROMPT the scroll attribute so that it receives the output of
the MOVE and EXPAND commands. However, you cannot scroll through the
PROMPT display.
•
The PROMPT display window always occupies the full width of the screen,
beginning in the first column.
•
You can move PROMPT vertically anywhere on the screen, expand it to fill
the full screen height, or contract it down to two lines.
The debugger alerts you if you try to move or expand a display such that it is
hidden by PROMPT.
7.4.4 Predefined Instruction Display (INST)
Note
By default, the predefined instruction display INST is not shown on the
screen and does not have the instruction attribute (see Section 7.4.4.1 and
Section 7.4.4.2).
Display INST is an automatically updated instruction display. It shows the
decoded instruction stream of your program. This is the exact code that is
executing, including the effects of any compiler optimization.
A VAX example is shown in Figure 7–3.
This type of display is useful when debugging code that has been optimized. In
such cases some of the code being executed might not match the source code that
is shown in a source display. See Section 14.1 for information about the effects of
optimization.
You can use INST in two basic ways:
•
By default, INST automatically displays the decoded instructions for the
routine in which execution is currently paused. This enables you to quickly
determine your current debugging context.
•
In addition, if INST has the instruction attribute, you can use it to display
the decoded instructions for any part of your program as explained in
Section 7.4.4.2.
The name of the routine whose instructions are displayed is shown at the right of
the display name, INST. The numbers displayed at the left of the instructions are
the compiler-generated source line numbers.
As you execute the program under debugger control, INST is updated
automatically whenever execution is paused. The arrow in the leftmost column
points to the instruction at which execution is paused. This is the instruction
that will be executed next and whose address is the current PC value.
7–16
Screen Mode
7.4 Predefined Displays
Figure 7–3 Screen Mode Instruction Display (VAX Example)
INST:routine SQUARES$MAIN
: TSTL
B^16(R11)
: BLEQ
SQUARES$MAIN\%LINE 16
Line
10: MOVL
B^4(R11),R0
: TSTL
W^−164(R11)[R0]
: BEQL
SQUARES$MAIN\%LINE 13
B^12(R11),R1
−> ne 11: MOVL
: MOVL
B^4(R11),R0
: MULL3
W^−164(R11)[R0],W^−164(R11)[R0],B^−84(R11)[R1]
Line
13: AOBLEQ B^16(R11),B^4(R11),SQUARES$MAIN\%LINE 10
Line
16: PUSHAL L^525
: MNEGL
S^#1,−(SP)
OUT−output
stepped to SQUARES$MAIN\%LINE 9
9:
DO 10 I = 1, N
3
SQUARES$MAIN\N:
0
SQUARES$MAIN\K:
stepped to SQUARES$MAIN\%LINE 11
1
SQUARES$MAIN\I:
0
SQUARES$MAIN\K:
PROMPT−error−program−prompt
DBG> STEP
DBG> EXAMINE I,K
DBG>
ZK−6505−GE
The built-in command that automatically updates display INST is
EXAMINE/INSTRUCTION .%INST_SCOPE\%PC. For information about the
EXAMINE/INSTRUCTION command, see Section 4.3.1. The built-in debugger
symbol %INST_SCOPE denotes a scope and has the following properties:
•
By default %INST_SCOPE denotes scope 0, which is the scope of the routine
where execution is currently paused.
•
If you have reset the scope search list relative to the call stack by means of
the SET SCOPE/CURRENT command (see Section 7.4.4.3), %INST_SCOPE
denotes the current scope specified (the scope of the routine at the start of the
search list).
7.4.4.1 Displaying the Instruction Display
By default, display INST is marked as removed (see Section 7.5.2) from the
display pasteboard and is not visible. To show display INST, use one of the
following methods:
•
Press KP7 to place displays SRC and INST side by side. This enables you to
compare the source code and the decoded instruction stream.
•
Press PF1 KP7 to place displays INST and REG side by side.
•
Enter the DISPLAY INST command to place INST in its default or most
recently defined location (see Section 7.5.2).
7–17
Screen Mode
7.4 Predefined Displays
7.4.4.2 Displaying Instructions in Arbitrary Program Locations
You can use display INST to display decoded instructions throughout your
program as follows:
•
You can scroll through the entire instruction display by pressing KP2 (scroll
down) or KP8 (scroll up) as explained in Section 7.5.1. This enables you to
view any instruction within the routine in which execution is paused.
•
You can display the instruction stream for any routine that is currently on the
call stack by using the SET SCOPE/CURRENT command (see Section 7.4.4.3).
•
If INST has the instruction attribute, you can display the instructions
for any code location throughout your program by using the
EXAMINE/INSTRUCTION command as follows:
To assign INST the instruction attribute, use the
SELECT/INSTRUCTION INST command (see Section 7.2.2 and
Section 7.3). Note that the instruction attribute is automatically assigned
to INST when you display it by pressing either KP7 or PF1 KP7.
To display the instructions associated with a code location (for example,
a routine declaration), use the EXAMINE/INSTRUCTION command (see
Section 4.3.1).
If no display has the instruction attribute, the output of an
EXAMINE/INSTRUCTION command is directed at display OUT.
After manipulating the contents of display INST, you can redisplay the location
at which execution is currently paused (the default behavior of INST) by pressing
KP5.
7.4.4.3 Displaying Instructions for a Routine on the Call Stack
The SET SCOPE/CURRENT command lets you display the instructions for any
routine that is currently on the call stack. For example, the following command
updates display INST so that it shows the instructions for the caller of the routine
in which execution is currently paused:
DBG> SET SCOPE/CURRENT 1
To reset the default scope for displaying instructions, enter the CANCEL SCOPE
command. The command causes display INST to show the instructions for the
routine at the top of the call stack where execution is paused.
7.4.4.4 Displaying Register Values for a Routine on the Call Stack
The SET SCOPE/CURRENT command lets you display the register values
associated with any routine that is currently on the call stack. For example, the
following command updates display REG so that it shows the register values for
the caller of the routine in which execution is currently paused:
DBG> SET SCOPE/CURRENT 1
To reset the default scope for displaying register values, enter the CANCEL
SCOPE command. This command causes display REG to show the register values
for the routine at the top of the call stack, where execution is paused.
7–18
Screen Mode
7.5 Manipulating Existing Displays
7.5 Manipulating Existing Displays
This section explains how to perform the following functions:
•
Use the SELECT and SCROLL commands to scroll a display.
•
Use the DISPLAY command to show, hide, or remove a display; the CANCEL
DISPLAY command to permanently delete a display; and the SHOW
DISPLAY command to identify the displays that currently exist and their
order in the display list.
•
Use the MOVE command to move a display across the screen.
•
Use the EXPAND command to expand or contract a display.
Section 7.7 and Section 7.2 discuss more advanced techniques for modifying
existing displays with the DISPLAY command—how to change the display
window and the type of information displayed.
7.5.1 Scrolling a Display
A display usually has more lines of text (and possibly longer lines) than can
be seen through its window. The SCROLL command lets you view text that is
hidden beyond a window’s border. You can scroll through all displays except for
the PROMPT display.
The easiest way to scroll displays is with the keypad keys, described later in this
section. Using the relevant commands is explained first.
You can specify a display explicitly with the SCROLL command. Typically,
however, you first use the SELECT/SCROLL command to select the current
scrolling display. This display then has the scroll attribute and is the default
display for the SCROLL command. You then use the SCROLL command with
no parameter to scroll that display up or down by a specified number of lines, or
to the right or left by a specified number of columns. The direction and distance
scrolled are specified with the command qualifiers (/UP:n, /RIGHT:n, and so on).
In the following example, the SELECT command selects display OUT as the
current scrolling display (/SCROLL can be omitted because it is the default
qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines down:
DBG> SELECT OUT
DBG> SCROLL/DOWN:18
Several useful SELECT and SCROLL command lines are assigned to keypad keys
(See Appendix A for a keypad diagram):
•
Pressing KP3 assigns the scroll attribute to the next display in the display
list after the current scrolling display. To select a display as the current
scrolling display, press KP3 repeatedly until the word "scroll" appears on the
top line of that display.
•
Press KP8, KP2, KP6, or KP4 to scroll up, down, right, or left, respectively.
The amount of scroll depends on which key state you use (DEFAULT, GOLD,
or BLUE).
7–19
Screen Mode
7.5 Manipulating Existing Displays
7.5.2 Showing, Hiding, Removing, and Canceling a Display
The DISPLAY command is the most versatile command for creating and
manipulating displays. In its simplest form, the command puts an existing
display on top of the pasteboard where it appears through its current window.
For example, the following command shows the display INST through its current
window:
DBG> DISPLAY INST
Pressing KP9, which is bound to the DISPLAY %NEXTDISP command, enables
you to achieve this effect conveniently. The built-in function %NEXTDISP
signifies the next display in the display list. (Appendix B identifies all screenrelated built-in functions.) Each time you press KP9, the next display in the list
is put on top of the pasteboard in its current window.
By default, the top line of display OUT (which identifies the display) coincides
with the bottom line of display SRC. If SRC is on top of the pasteboard, its bottom
line hides the top line of OUT (keep this in mind when using the DISPLAY
command and associated keypad keys to put various displays on top of the
pasteboard).
To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE
command. This command changes the order of that display in the display list.
To remove a display from the pasteboard so that it is no longer seen (yet is not
permanently deleted), use the DISPLAY/REMOVE command. To put a removed
display back on the pasteboard, use the DISPLAY command.
To delete a display permanently, use the CANCEL DISPLAY command. To
re-create the display, use the DISPLAY command as described in Section 7.6.
Note that you cannot hide, remove, or delete the PROMPT display.
To identify the displays that currently exist, use the SHOW DISPLAY command.
They are listed according to their order on the display list. The display that is on
top of the pasteboard is listed last.
For more information about the DISPLAY options, see the DISPLAY command.
Note that the DISPLAY command accepts optional parameters that let you
modify other characteristics of existing displays, namely the display window and
the type of information displayed. The techniques are discussed in Section 7.7
and Section 7.2.
7.5.3 Moving a Display Across the Screen
Use the MOVE command to move a display across the screen. The qualifiers
/UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of
lines or columns by which to move the display. If you do not specify a display, the
current scrolling display is moved.
The easiest way to move a display is by using keypad keys:
7–20
•
Press KP3 repeatedly as needed to select the current scrolling display.
•
Put the keypad in the MOVE state, then press KP8, KP2, KP4, or KP6 to
move the display up, down, left, or right, respectively. See Appendix A.
Screen Mode
7.5 Manipulating Existing Displays
7.5.4 Expanding or Contracting a Display
Use the EXPAND command to expand or contract a display. The qualifiers /UP:n,
/DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of lines
or columns by which to expand or contract the display (to contract a display,
specify negative integer values with these qualifiers). If you do not specify a
display, the current scrolling display is expanded or contracted.
The easiest way to expand or contract a display is to use the keypad keys:
•
Press KP3 repeatedly as needed to select the current scrolling display.
•
Put the keypad in the EXPAND or CONTRACT state, then press KP8, KP2,
KP4, or KP6 to expand or contract the display vertically or horizontally. See
Appendix A.
The PROMPT display cannot be contracted (or expanded) horizontally. Also, it
cannot be contracted vertically to less than two lines.
7.6 Creating a New Display
To create a new screen display, use the DISPLAY command. The basic syntax is
as follows:
DISPLAY display-name [AT window-spec] [display-kind]
The display name can be any name that is not already used to name a display
(use the SHOW DISPLAY command to identify all existing displays). A newly
created display is placed on top of the pasteboard, on top of any existing displays
(except for the predefined PROMPT display, which cannot be hidden). The display
name appears at the top left corner of the display window.
Section 7.7 explains the options for specifying windows. If you do not provide a
window specification, the display is positioned in the upper or lower half of the
screen, alternating between these locations as you create new displays.
Section 7.2 explains the options for specifying display kinds. If you do not specify
a display kind, an output display is created.
For example, the following command creates a new output display named OUT2.
The window associated with OUT2 is either the top or bottom half of the screen.
DBG> DISPLAY OUT2
The following command creates a new DO display named EXAM_XY that is
located in the right third quarter (RQ3) of the screen. This display shows the
current value of variables X and Y and is updated whenever the debugger gains
control from the program.
DBG> DISPLAY EXAM_XY AT RQ3 DO (EXAMINE X,Y)
For more information, see the DISPLAY command.
7.7 Specifying a Display Window
Display windows can occupy any rectangular portion of the screen.
You can specify a display window when you create a display with the DISPLAY
command. You can also change the window currently associated with a display
by specifying a new window with the DISPLAY command. When specifying a
window, you have the following options:
•
Specify a window in terms of lines and columns.
7–21
Screen Mode
7.7 Specifying a Display Window
•
Use the name of a predefined window, such as H1.
•
Use the name of a window definition previously established with the SET
WINDOW command.
Each of these techniques is described in the following sections. When specifying
windows, keep in mind that the PROMPT display always remains on top of the
display pasteboard and, therefore, occludes any part of another display that
shares the same region of the screen.
Display windows, regardless of how specified, are dynamic. This means that, if
you use a SET TERMINAL command to change the screen height or width, the
window associated with a display expands or contracts in proportion to the new
screen height or width.
7.7.1 Specifying a Window in Terms of Lines and Columns
The general form of a window specification is (start-line,line-count[,startcolumn,column-count]). For example, the following command creates the output
display CALLS and specifies that its window be 7 lines deep starting at line 10,
and 30 columns wide starting at column 50:
DBG> DISPLAY CALLS AT (10,7,50,30)
If you do not specify start-column or column-count, the window occupies the full
width of the screen.
7.7.2 Using a Predefined Window
The debugger provides many predefined windows. These have short, symbolic
names that you can use in the DISPLAY command instead of having to specify
lines and columns. For example, the following command creates the output
display ZIP and specifies that its window be RH1 (the top right half of the
screen):
DBG> DISPLAY ZIP AT RH1
The SHOW WINDOW command identifies all predefined window definitions as
well as those you create with the SET WINDOW command.
7.7.3 Creating a New Window Definition
The predefined windows should be adequate for most situations, but you can
also create a new window definition with the SET WINDOW command. This
command, which has the following syntax, associates a window name with a
window specification:
SET WINDOW window-name AT (start-line,line-count[,
start-column,column-count])
After creating a window definition, you can use its name (like that of a predefined
window) in a DISPLAY command. In the following example, the window
definition MIDDLE is established. That definition is then used to display
OUT through the window MIDDLE.
DBG> SET WINDOW MIDDLE AT (9,4,30,20)
DBG> DISPLAY OUT AT MIDDLE
To identify all current window definitions, use the SHOW WINDOW command.
To delete a window definition, use the CANCEL WINDOW command.
7–22
Screen Mode
7.8 Sample Display Configuration
7.8 Sample Display Configuration
How to best use screen mode depends on your personal style and on what type of
error you are looking for. You might be satisfied to use the predefined displays. If
you have access to a larger screen, you might want to create additional displays
for various purposes. The following example gives some ideas.
Assume you are debugging in a high-level language and are interested in tracing
the execution of your program through several routine calls.
First set up the default screen configuration—that is, SRC in H1, OUT in
S45, and PROMPT in S6 (the keypad key sequence PF4 MINUS gives this
configuration). SRC shows the source code of the module in which execution is
paused.
The following command creates a source display named SRC2 in RH1 that shows
the PC value at scope 1 (one level down the call stack, at the call to the routine
in which execution is paused):
DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC)
Thus the left half of your screen shows the currently executing routine and the
right half shows the caller of that routine.
The following command creates a DO display named CALLS at S4 that executes
the SHOW CALLS command each time the debugger gains control from the
program:
DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS)
Because the top half of OUT is now hidden by CALLS, make OUT’s window
smaller as follows:
DBG> DISPLAY OUT AT S5
You can create a similar display configuration with instruction displays instead of
source displays.
7.9 Saving Displays and the Screen State
The SAVE command enables you to make a snapshot of an existing display and
save that copy as a new display. This is useful if, for example, you later want to
refer to the current contents of an automatically updated display (such as a DO
display).
In the following example, the SAVE command saves the current contents of
display CALLS into display CALLS4, which is created by the command:
DBG> SAVE CALLS AS CALLS4
The new display is removed from the pasteboard. To view its contents, use the
DISPLAY command:
DBG> DISPLAY CALLS4
The EXTRACT command has two uses. First, it enables you to save the contents
of a display in a text file. For example, the following command extracts the
contents of display CALLS, appending the resulting text to the file COB34.TXT:
DBG> EXTRACT/APPEND CALLS COB34
7–23
Screen Mode
7.9 Saving Displays and the Screen State
Second, the EXTRACT/SCREEN_LAYOUT command enables you to create a
command procedure that can later be executed during a debugging session
to re-create the previous state of the screen. In the following example, the
EXTRACT/SCREEN_LAYOUT command creates a command procedure with the
default specification SYS$DISK:[ ]DBGSCREEN.COM. The file contains all the
commands needed to re-create the current state of the screen.
DBG> EXTRACT/SCREEN_LAYOUT
.
.
.
DBG> @DBGSCREEN
Note that you cannot save the PROMPT display as another display, or extract it
into a file.
7.10 Changing the Screen Height and Width
During a debugging session, you can change the height or width of your terminal
screen. One reason might be to accommodate long lines that would wrap if
displayed across 80 columns. Or, if you are at a workstation, you might want to
reformat your debugger window relative to other windows.
To change the screen height or width, use the SET TERMINAL command.
The general effect of the command is the same whether you are at a VT-series
terminal or at a workstation.
In this example, assume you are using a workstation window in its default
emulated VT100-screen mode, with a screen size of 24 lines by 80 columns.
You have started the debugger and are using it in screen mode. You now want
to take advantage of the larger screen. The following command increases the
screen height and width of the debugger window to 35 lines and 110 columns
respectively:
DBG> SET TERMINAL/PAGE:35/WIDTH:110
By default, all displays are dynamic. A dynamic display automatically adjusts
its window dimensions in proportion when a SET TERMINAL command
changes the screen height or width. This means that, when using the SET
TERMINAL command, you preserve the relative positions of your displays. The
/[NO]DYNAMIC qualifier on the DISPLAY command lets you control whether
or not a display is dynamic. If a display is not dynamic, it does not change
its window coordinates after you enter a SET TERMINAL command (you can
then use the DISPLAY, MOVE, or EXPAND commands, or various keypad key
combinations, to move or resize a display).
To see the current terminal width and height being used by the debugger, use the
SHOW TERMINAL command.
Note that the debugger’s SET TERMINAL command does not affect the terminal
screen size at DCL level. When you exit the debugger, the original screen size is
maintained.
7–24
Screen Mode
7.11 Screen-Related Built-In Symbols
7.11 Screen-Related Built-In Symbols
The following built-in symbols are available for specifying displays and screen
parameters in language expressions:
•
%SOURCE_SCOPE—To display source code. %SOURCE_SCOPE is described
in Section 7.4.1.
•
%INST_SCOPE—To display instructions. %INST_SCOPE is described in
Section 7.4.4.
•
%PAGE, %WIDTH—To specify the current screen height and width.
•
%CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT,
%NEXTSCROLL, %NEXTSOURCE—To specify displays in the display list.
7.11.1 Screen Height and Width
The built-in symbols %PAGE and %WIDTH return, respectively, the current
height and width of the terminal screen. These symbols can be used in various
expressions, such as for window specifications. For example, the following
command defines a window named MIDDLE that occupies a region around the
middle of the screen:
DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
7.11.2 Display Built-In Symbols
Each time you refer to a specific display with a DISPLAY command, the display
list is updated and reordered, if necessary. The most recently referenced display
is put at the tail of the display list, because that display is pasted last on the
pasteboard (you can identify the display list by entering a SHOW DISPLAY
command).
You can use display built-in symbols to specify displays relative to their positions
in the display list. These symbols, listed as follows, enable you to refer to
displays by their relative positions in the list instead of by their explicit names.
The symbols are used mainly in keypad key definitions or command procedures.
Display symbols treat the display list as a circular list. Therefore, you can enter
commands that use display symbols to cycle through the display list until you
reach the display you want.
%CURDISP
The current display. This is the display most recently referenced
with a DISPLAY command—the least occluded display.
%CURSCROLL
The current scrolling display. This is the default display for the
SCROLL, MOVE, and EXPAND commands, as well as for the
associated keypad keys (KP2, KP4, KP6, and KP8).
%NEXTDISP
The next display in the list after the current display. The next
display is the display that follows the topmost display. Because
the display list is circular, this is the display at the bottom of the
pasteboard—the most occluded display.
%NEXTINST
The next instruction display in the display list after the current
instruction display. The current instruction display is the display
that receives the output from the EXAMINE/INSTRUCTION
commands.
7–25
Screen Mode
7.11 Screen-Related Built-In Symbols
%NEXTOUTPUT
The next output display in the display list after the current output
display. An output display receives debugger output that is not
already directed to another display.
%NEXTSCROLL
The next display in the display list after the current scrolling
display.
%NEXTSOURCE
The next source display in the display list after the current source
display. The current source display is the display that receives the
output from the TYPE and EXAMINE/SOURCE commands.
7.12 Screen Dimensions and Predefined Windows
On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. On
a workstation, the screen is larger in both height and width. The debugger can
accommodate screen sizes up to 100 lines by 255 columns.
The debugger has many predefined windows that you can use to position
displays on the screen. In addition to the full height and width of the screen, the
predefined windows include all possible regions that result from:
•
Dividing the screen vertically into equal fractions: halves, thirds, quarters,
sixths, or eighths
•
Combining vertically contiguous equal fractions: halves, thirds, quarters,
sixths, or eighths
•
Dividing the vertical fractions into left and right halves
The SHOW WINDOW command identifies all predefined display windows.
The following conventions apply to the names of predefined windows. The
prefixes L and R denote left and right windows, respectively. Other letters denote
the full screen (FS) or fractions of the screen height (H: half, T: third, Q: quarter,
S: sixth, E: eighth). The trailing numbers denote specific segments of the screen
height, starting from the top. For example:
•
Windows T1, T2, and T3 occupy the top, middle, and bottom thirds of the
screen, respectively.
•
Window RH2 occupies the right bottom half of the screen.
•
Window LQ23 occupies the left middle two quarters of the screen.
•
Window S45 occupies the fourth and fifth sixths of the screen.
The following four commands create displays that have windows identical in size
and location (the top half of the screen):
DBG>
DBG>
DBG>
DBG>
DISPLAY
DISPLAY
DISPLAY
DISPLAY
XYZ
XYZ
XYZ
XYZ
AT
AT
AT
AT
H1 SOURCE
Q12 SOURCE
S123 SOURCE
E1234 SOURCE
The horizontal boundaries (start-column, column-count) of the predefined
windows for the default terminal screen width of 80 columns are as follows:
7–26
•
Left-hand windows: (1,40)
•
Right-hand windows: (42,39)
Screen Mode
7.12 Screen Dimensions and Predefined Windows
Table 7–3 lists the vertical boundaries (start-line, line-count) of single-segment
display windows predefined for the default terminal screen height of 24 lines.
Table 7–3 does not list windows that consist of multiple segments such as E23 (a
display window created from the combination of display windows E2 and E3).
Table 7–3 Predefined Windows
Window Name
Start-line,Line-count
Window Location
FS
(1,23)
Full screen
H1
(1,11)
Top half
H2
(13,11)
Bottom half
T1
(1,7)
Top third
T2
(9,7)
Middle third
T3
(17,7)
Bottom third
Q1
(1,5)
Top quarter
Q2
(7,5)
Second quarter
Q3
(13,5)
Third quarter
Q4
(19,5)
Bottom quarter
S1
(1,3)
Top sixth
S2
(5,3)
Second sixth
S3
(9,3)
Third sixth
S4
(13,3)
Fourth sixth
S5
(17,3)
Fifth sixth
S6
(21,3)
Bottom sixth
E1
(1,2)
Top eighth
E2
(4,2)
Second eighth
E3
(7,2)
Third eighth
E4
(10,2)
Fourth eighth
E5
(13,2)
Fifth eighth
E6
(16,2)
Sixth eighth
E7
(19,2)
Seventh eighth
E8
(22,2)
Bottom eighth
7.13 Internationalization of Screen Mode
You can enable country-specific features for screen mode by defining logical
names, as follows:
•
DBG$SMGSHR — For specifying the Screen Management (SMG) shareable
image. The debugger uses the SMG shareable image in its implementation of
screen mode. Asian variants of the SMG shareable image handle multibyte
characters. Hence, if an Asian variant of SMG is used by the debugger, the
screen mode interface to the debugger will be able to display and manipulate
multibyte characters.
Define the DBG$SMGSHR logical name as follows:
$ DEFINE/JOB DBG$SMGSHR <name_of_Asian_SMG>
7–27
Screen Mode
7.13 Internationalization of Screen Mode
where <name_of_Asian_SMG> varies according to the variants of Asian
OpenVMS. For example, the name of the Asian SMG in Japanese OpenVMS
is JSY$SMGSHR.EXE.
•
7–28
SMG$DEFAULT_CHARACTER_SET — For the Asian SMG and multibyte
characters. This logical need only be defined if DBG$SMGSHR has been
defined. See the documentation on Asian or Japanese screen management
routines for details on how to define this logical name.
Part III
DECwindows Motif Interface
This part describes the HP DECwindows Motif for OpenVMS user interface of the
debugger.
For information about the debugger’s command interface, see Part II.
8
Introduction
This chapter introduces the HP DECwindows Motif for OpenVMS user interface
of the debugger. For information about the command interface, see Part II.
Note
The HP DECwindows Motif for OpenVMS user interface to the OpenVMS
Debugger Version 7.1 or later requires Version 1.2 or later of HP
DECwindows Motif for OpenVMS.
This chapter provides the following information:
•
A functional overview of the OpenVMS Debugger, including its user interface
options—HP DECwindows Motif for OpenVMS and command (Section 8.1)
•
An orientation to the debugger’s HP DECwindows Motif for OpenVMS screen
features, such as windows, menus, and so on (Section 8.2)
•
Instructions for entering debugger commands at the command-entry prompt
(Section 8.3)
•
Instructions for accessing online help (Section 8.4)
For information about starting a debugging session, see Chapter 9. For detailed
information about using the Motif interface for debugging, see Chapter 10. For
the source code of program EIGHTQUEENS.EXE, shown in the figures of this
chapter, see Appendix D.
8.1 Introduction
The OpenVMS Debugger has a HP DECwindows Motif for OpenVMS graphical
user interface (GUI) for workstations. This enhancement to the screen-mode
command interface accepts mouse input to choose items from menus and to
activate or deactivate push buttons, to drag the pointer to select text in windows,
and so on. The debugger’s HP DECwindows Motif for OpenVMS GUI menus and
push buttons provide the functions for most basic debugging tasks.
The HP DECwindows Motif for OpenVMS GUI is layered on the character-cell
command interface and has a command-entry prompt on the command line
(in the command view). From the HP DECwindows Motif for OpenVMS GUI
command line, you can enter debugger commands for the following purposes:
•
To perform certain operations by using the HP DECwindows Motif for
OpenVMS user interface menus and push buttons for certain operations
•
To do debugging tasks not available through the HP DECwindows Motif for
OpenVMS GUI menus and push buttons
8–1
Introduction
8.1 Introduction
You can customize the HP DECwindows Motif for OpenVMS GUI to associate
other debugger commands with new or existing push buttons.
You can run the HP DECwindows Motif for OpenVMS GUI in local mode or in
client/server mode. Client/server mode allows you to debug programs remotely
from another OpenVMS node. The user interface in both Motif modes is virtually
identical. Chapter 9 describes how to start interfaces.
Notes
The HP DECwindows Motif for OpenVMS GUI does not recognize the
HELP command at its command-entry prompt. Choose the On Commands
item in the Help menu for online help on debugger commands.
You cannot use the HP DECwindows Motif for OpenVMS GUI to debug
detached processes such as print symbionts that run without a command
line interpreter (CLI). See Section 1.11 for details about debugging
detached processes that do not have a CLI.
8.1.1 Convenience Features
The following paragraphs highlight some of the convenience features of the
debugger’s default HP DECwindows Motif for OpenVMS interface. Section 8.2
gives visual details. (Convenience features of the debugger’s command interface
are described in detail in Section 1.1.2.)
Source-Code Display
The OpenVMS Debugger is a source-level debugger. The debugger displays in
the source view the source code that surrounds the instruction where program
execution is paused currently. You can enable and disable the display of compilergenerated line numbers.
A source browser lets you:
•
List the images, modules, and routines of your program
•
Display source code from selected modules or routines
•
Display the underlying hierarchy of modules and routines
•
Set breakpoints by double-clicking on selected routines
Call-Stack Navigation
The call-stack menu on the main window lists the sequence of routine calls
currently on the call stack. Click on a routine name in the call-stack menu to set
(to that routine) the context (scope) for
8–2
•
Source code display (in the source view)
•
Register display (in the register view)
•
Instruction display (in the instruction view)
•
Symbol searches
Introduction
8.1 Introduction
Breakpoints
You set, activate, and deactivate breakpoints by clicking on buttons next to the
source lines in the source view or the instruction view. Optionally, you can set,
deactivate, or activate breakpoints by selecting items in window pull-down menus,
pop-up menus, context-sensitive menus, or dialog boxes. You can set conditional
breakpoints, which suspend program execution if the specified condition is true.
You can set action breakpoints, which execute one or more debugger commands
when the breakpoint suspends program execution. The main window push
buttons, the instruction view push buttons, and the breakpoint view give a
visual indication of activated, deactivated, and conditional breakpoints.
Push Buttons
Push buttons in the push button view control common operations: by clicking
on a push button, you can start execution, step to the next source line, display
the value of a variable selected in a window, interrupt execution, and so on.
You can modify, add, remove, and resequence push buttons and the associated
debugger commands.
Context-Sensitive Pop-Up Menus
Context-sensitive pop-up menus list common operations associated with your
view (source view, command view, and so on.) When you click MB3, the pop-up
menu lists actions for the text you have selected, the source line at which you are
pointing, or the view in which you are working.
Displaying and Manipulating Data
To display the value of a variable or expression, select the variable or expression
in the source view and click on a push button, such as Examine (examine
variable). You can also display selected values by choosing items from window
pull-down menus (such as Examine, in the Commands pull-down menu), contextsensitive menus, or dialog boxes. You can display values in different type or radix
formats.
To change the value of a variable, edit the currently displayed value in the
monitor view. You can also change values by selecting items in window pulldown menus (such as Deposit, in the Commands pull-down menu), contextsensitive pop-up menus, or dialog boxes.
The monitor view displays the updated values of specified variables whenever the
debugger regains control from your program.
Kept Debugger RERUN Command
You can run the debugger in a state known as the kept debugger from which
you can rerun the same program or run another program without exiting the
debugger. When rerunning a program, you can choose to save the current state
of breakpoints, tracepoints, and static watchpoints. The kept debugger is also
available in the screen mode debugger. See Section 9.1 for information on starting
the kept debugger.
Client/Server Configuration
You can run the debugger in a client/server configuration, which allows you to
debug programs that run on an OpenVMS node remotely from another OpenVMS
node using the HP DECwindows Motif for OpenVMS 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.
8–3
Introduction
8.1 Introduction
Instruction and Register Views
The instruction view shows the decoded instruction stream (the code that
is actually executing) of your program. This view is useful if the program you
are debugging has been optimized by the compiler, in which case the source
code in the source view may not reflect the code that is executing. You can set
breakpoints on instructions and display the memory addresses and source-code
line numbers associated with each instruction.
The register view displays the current contents of all machine registers. You
can edit the displayed values to deposit other values into the registers.
Debugger Status Indicator
The debugger has a status indicator to identify the state of the debugger, which
can be one of the following:
•
D—the program being debugged is running
•
U—the Debugger is executing a user command
Threads Program Support
The threads view displays information about the current state of all tasks of a
multithread program. You can modify threads characteristics to control thread
execution, priority, state transitions, and so on.
Integration with Command Interface
The debugger’s HP DECwindows Motif for OpenVMS GUI is an enhancement
to the character-cell debugger. It is layered on, and closely integrated with, the
command-driven character-cell debugger:
•
When you use the HP DECwindows Motif for OpenVMS GUI menus and push
buttons, the debugger echoes your commands in the command view to provide
a record of your actions.
•
When you enter commands at the prompt, the debugger updates the HP
DECwindows Motif for OpenVMS views accordingly.
Integration with Source-Level Editor
You can edit program source code without exiting from the debugger. In the editor
view, you can display the source code, search and replace text, or add additional
text. Editor view text buffers allow you to move quickly back and forth between
new or existing files, and copy, cut, and paste text from buffer to buffer.
The text editor available through the debugger’s HP DECwindows Motif for
OpenVMS menu interface is a simple convenience feature, not intended to replace
sophisticated text editors such as the Language-Sensitive Editor (LSE). To use a
different editor, enter the Edit command at the DBG> prompt in the command
view (see the EDIT command).
Customization
You can modify the following and other aspects of the debugger’s HP DECwindows
Motif for OpenVMS interface and save the current settings in a resource file to
customize your debugger startup environment:
8–4
•
Configuration of windows and views (for example, size, screen location, order)
•
Push button order, labels, and associated debugger commands (this includes
adding and removing push buttons)
•
Character fonts for displayed text
Introduction
8.1 Introduction
Online Help
Online help is available for the debugger’s HP DECwindows Motif for OpenVMS
interface (context-sensitive help) and for its command interface.
8.2 Debugger Windows and Menus
The following sections describe the debugger windows, menus, views, and other
features of the OpenVMS Debugger HP DECwindows Motif for OpenVMS
interface.
8.2.1 Default Window Configuration
By default, the debugger starts up in the main window, as shown in Figure 8–1.
When you start the debugger as explained in Section 9.1, the source view is
initially empty. Figure 8–1 shows the source view after a program has been
brought under debugger control (by directing the debugger to run a specific
image, in this example, EIGHTQUEENS).
You can customize the startup configuration to your preference as described in
Section 10.10.1.
Figure 8–1 Debugger Main Window
8.2.2 Main Window
The main window (see Figure 8–1) includes:
•
Title bar (see Section 8.2.2.1)
•
Source view (see Section 8.2.2.2)
•
Call Stack view (see Section 8.2.2.4)
8–5
Introduction
8.2 Debugger Windows and Menus
•
Push button view (see Section 8.2.2.5)
•
Command view (see Section 8.2.2.6)
If the debugger is running on an Alpha or Integrity server processor, the name of
the debugger is "OpenVMS Debug64."
8.2.2.1 Title Bar
The title bar, at the top of the main window, displays (by default) the name of the
debugger, the name of the program being debugged, and the name of the source
code module that is currently displayed in the source view.
8.2.2.2 Source View
The source view shows the following:
•
Source code of the program you are debugging and, by default, the compilergenerated line numbers (to the left of the source code). To choose not to
display line numbers, see Section 10.1.
•
Breakpoint toggle push buttons.
•
Current-location pointer (a triangle to the left of breakpoint push buttons),
which points to the line of source code that will be executed when program
execution resumes.
For more information about displaying source code, see Section 8.2.2.3 and
Section 10.1.
8.2.2.3 Menus on Main Window
Figure 8–2 and Table 8–1 describe the menus on the main window.
Figure 8–2 Menus on Main Window
8–6
Introduction
8.2 Debugger Windows and Menus
Table 8–1 Menus on Main Window
Menu
Item
Description
File
Run Image...
Bring a program under debugger control by specifying
an executable image.
Run Foreign
Command...
Bring a program under debugger control by specifying
a symbol for a foreign command.
Rerun Same...
Rerun the same program under debugger control.
Browse Sources
Display the source code in any module of your program.
Set breakpoints on routines.
Edit
Break
Symbolic—List only those modules for which the
debugger has symbolic information.
•
All—List all modules.
Display Line
Numbers
Display or hide line numbers in the source view.
Server
Connection...
(Client/Server mode) Specify the network binding
string of the server for connection.
Exit Debug?
End the debugging session, terminating the debugger.
Cut
Cut selected text and copy it to the clipboard. You can
cut text only from fields or regions that accept input
(although, in most cases, Cut copies the selected text to
the clipboard).
Copy
Copy selected text from the window to the clipboard
without deleting the text.
Paste
Paste text from the clipboard to a text-entry field or
region.
On Exception
Break on any exception signaled during program
execution.
Activate All
Activate any previously set breakpoints.
Deactivate All
Deactivate any previously set breakpoints.
Cancel All
Remove all breakpoints from the debugger’s breakpoint
list and from the breakpoint view.
Set...
Set a new breakpoint, optionally associated with a
particular condition or action, at a specified location.
Commands Examine...
Options
•
Examine the current value of a variable or expression.
The output value may be typecast or changed in radix.
Deposit...
Deposit a value to a variable. The input value may be
changed in radix.
Edit File
Edit the source code of your file in the debugger’s
editor.
Views...
Display one or more of the following:
Breakpoint view
Monitor view
Instruction view
Tasking view
Register view (see Table 8–2)
(continued on next page)
8–7
Introduction
8.2 Debugger Windows and Menus
Table 8–1 (Cont.) Menus on Main Window
Menu
Help
Item
Description
Track Language
Changes
Notify you if the debugger enters a module that is
written in a language different from the previously
executed module.
Show Message
Separators
Display a dotted line between each command and
message displayed by the debugger.
Customize
Buttons...
Modify, add, remove, or resequence a push button in
the push button view and the associated debugger
command.
Save Options
Save the current settings of all HP DECwindows Motif
for OpenVMS features of the debugger that you can
customize interactively, such as the configuration of
windows and views, and push button definitions. This
preserves the current debugger configuration for the
next time you run the debugger.
Restore Default
Options
Copy the system default debugger resource file
DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT
to the user-specific resource file DECW$USER_
DEFAULTS:VMSDEBUG.DAT. The default options
take effect when you next start the debugger.
Edit Options File
Load and display the user-specific resource file
DECW$USER_DEFAULTS:VMSDEBUG.DAT in the
debug editor for review and modification.
On Context
Enable the display of context-sensitive online help.
On Window
Display information about the debugger.
On Help
Display information about the online help system.
On Version
Display information about this version of the debugger.
On Commands
Display information about debugger commands.
Table 8–2 Displays in Register View
Register Type
Alpha Displays
Integrity Server Displays
Call Frame
R0, R25, R26,
R27, FP, SP,
F0, F1, PC, PS,
FPCR, SFPCR
PC, CFM, BSP, BSPSTORE, PFS, RP,
UNAT, GP, SP, TP, AI
General Purpose
R0-R28, FP, SP,
R31
PC, GP, R2-R11, SP, TP, R14-R24, AI,
R26-R127
Floating Point
F0-F31
F2 - F127
8.2.2.4 Call Stack Menu
The Call Stack menu, between the source view and the push button view, shows
the name of the routine whose source code is displayed in the source view. This
menu lists the sequence of routine calls currently on the stack and lets you set
the scope of source code display and symbol searches to any routine on the stack
(see Section 10.6.2).
8–8
Introduction
8.2 Debugger Windows and Menus
8.2.2.5 Push Button View
Figure 8–3 and Table 8–3 describe the default push buttons in the main window.
You can modify, add, remove, and resequence buttons and their associated
commands as explained in Section 10.10.3.
Figure 8–3 Default Buttons in the Push Button View
Table 8–3 Default Buttons in the Push Button View
Button
Description
Stop
Interrupt program execution or a debugger operation without ending the
debugging session.
Go
Start or resume execution from the current program location.
STEP
Execute the program one step unit of execution. By default, this is one
executable line of source code.
S/in
When execution is suspended at a routine call statement, move execution
into the called routine just past the start of the routine. This is the same
behavior as STEP if not at a routine call statement.
S/ret
Execute the program directly to the end of the current routine.
S/call
Execute the program directly to the next Call or Return instruction.
EX
Display, in the command view, the current value of a variable whose name
you have selected in a window.
E/az
Display, 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
Display, 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
Display, 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
Display, 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.
8.2.2.6 Command View
The command view, located directly under the push button view in the main
window, accepts typed command input on the command line (see Section 8.3),
and displays debugger output other than that displayed in the optional views.
Examples of such output are:
•
The result of an Examine operation.
•
Diagnostic messages. For online help on debugger diagnostic messages, see
Section 8.4.4.
8–9
Introduction
8.2 Debugger Windows and Menus
•
Command echo. The debugger translates your HP DECwindows Motif for
OpenVMS menu and push button input into debugger commands and displays
those commands on the command line in the command view, providing a
record of your most recent commands. This enables you to correlate your
input with debugger actions.
You can clear the entire command view, leaving only the current command-line
prompt, by choosing Clear Command Window from the pop-up menu.
You can clear the current command line by choosing Clear Command Line from
the pop-up menu.
8.2.3 Optional Views Window
Table 8–4 lists the optional views. They are accessible by choosing Views... from
the Options menu on the main window.
Table 8–4 Optional Views
View
Description
Breakpoint view
List all breakpoints that are currently set and identify those which
are activated, deactivated, or qualified as conditional breakpoints. The
breakpoint view also allows you to modify the state of each breakpoint.
Monitor view
List variables whose values you want to monitor as your program
executes. The debugger updates the values whenever it regains control
from your program (for example, after a step or at a breakpoint).
Alternatively, you can set a watchpoint, causing execution to stop
whenever a particular variable has been modified. You can also change
the values of variables.
Instruction view
Display the decoded instruction stream of your program and allow you
to set breakpoints on instructions. By default, the debugger displays
the corresponding memory addresses and source-code line numbers to
the left of the instructions. You can choose to suppress these.
Register view
Display the current contents of all machine registers. The debugger
updates the values whenever it regains control from your program. The
register view also lets you change the values in registers.
Tasking view
List all the existing (nonterminated) tasks of a tasking program.
Provides information about each task and allows you to modify the
state of each task.
Figure 8–5 shows a possible configuration of the breakpoint view, monitor view,
and register view, as a result of the selections in the View menu in Figure 8–4.
Figure 8–6 shows the instruction view, which is a separate window so that you
can position it where most convenient. Figure 8–7 shows the tasking view.
Note that the registers and instructions displayed are system-specific. Figure 8–5
and Figure 8–6 show Integrity server-specific registers and instructions.
You can move and resize all windows. You can also save a particular configuration
of the windows and views so that it is set up automatically when you restart the
debugger (see Section 10.10.1).
8–10
Introduction
8.2 Debugger Windows and Menus
Note
If you are debugging a UI application and you have many debugger
windows overlapping the user program’s windows, the X server will
occasionally abruptly terminate the user program.
To avoid this problem, refrain from overlapping or covering windows
belonging to the user program.
Figure 8–4 Debugger Main Window and the Optional Views Window
8–11
Introduction
8.2 Debugger Windows and Menus
Figure 8–5 Monitor, Breakpoint, and Register Views
Figure 8–6 Instruction View
8–12
Introduction
8.2 Debugger Windows and Menus
Figure 8–7 Thread View
Figure 8–8 Menus on Optional Views Window
8.2.3.1 Menus on Optional Views Window
Figure 8–8 and Table 8–5 describe the menus on the optional views window.
8–13
Introduction
8.2 Debugger Windows and Menus
Table 8–5 Menus on Optional Views Window
Menu
Item
Description
File
Close
Close the optional views window.
Exit Debug?
End the debugging session, terminating the debugger.
On Exception
Break on any exception signaled during program
execution.
Activate All
Activate any previously set breakpoints.
Break
Monitor
Register
Tasks
Deactivate All
Deactivate any previously set breakpoints.
Cancel All
Remove all breakpoints from the debugger’s breakpoint
list and from the breakpoint view.
Toggle
Toggle a breakpoint.
Set/Modify...
Set a new breakpoint, optionally associated with a
particular condition or action, at a specified location.
Cancel
Cancel (delete) an individual breakpoint.
Expand
Expand monitor view output to include the values
of component parts of a selected item as well as the
aggregate value.
Collapse
Collapse the monitor view output to show only the
aggregate value of a selected item, instead of the values of
each component part.
Deposit...
Change the value of a monitored element.
Toggle
Watchpoint
Toggle a selected watchpoint.
Typecast
Use the submenu to typecast output for a selected variable
to int, long, quad, short, or char*.
Change Radix
Use the submenu to change the output radix for a selected
variable to hex, octal, binary, or decimal.
Change All Radix
Use the submenu to change the output radix for all
subsequent monitored elements to hex, octal, binary, or
decimal.
Remove
Remove an element from the monitor view.
Change Radix
Use the submenu to change radix for selected register to
hex, octal, binary, or decimal.
Change All Radix
Use the submenu to change radix for all registers to hex,
octal, binary, or decimal.
Abort
Request that the selected task be terminated at the next
allowed opportunity.
Activate
Make the selected task the active task.
Hold
Place the selected task on hold.
Nohold
Release the selected task from hold.
Make Visible
Make the selected task the visible task.
All
Use the submenu to abort all tasks or release all tasks
from hold.
(continued on next page)
8–14
Introduction
8.2 Debugger Windows and Menus
Table 8–5 (Cont.) Menus on Optional Views Window
Menu
Item
Description
Options
Views...
Display one or more of the following:
Breakpoint view
Monitor view
Instruction view
Tasking view
Register view
Help
Customize
Buttons...
Modify, add, remove, or resequence a push button in the
push button view and the associated debugger command.
Save Options
Save the current settings of all HP DECwindows Motif for
OpenVMS features of the debugger that you can customize
interactively, such as the configuration of windows and
views, and push button definitions. This preserves your
current debugger configuration for the next time you run
the debugger.
Restore Default
Options
Copy the system default debugger resource file
DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT
to the user-specific resource file DECW$USER_
DEFAULTS:VMSDEBUG.DAT. The default options take
effect when you next start the debugger.
Edit Options File
Load and display the user-specific resource file
DECW$USER_DEFAULTS:VMSDEBUG.DAT in the
debug editor for review and modification.
On Context
Enable the display of context-sensitive online help.
On Window
Display information about the debugger.
On Help
Display information about the online help system.
On Version
Display information about this version of the debugger.
On Commands
Display information about debugger commands.
8.3 Entering Commands at the Prompt
The debugger’s HP DECwindows Motif for OpenVMS GUI is layered on the
command interface. The command line, the last line in the command view
and identified by the command-entry prompt (DBG>), lets you enter debugger
commands for the following purposes:
•
As an alternative to using the HP DECwindows Motif for OpenVMS GUI
menus and push buttons for certain operations
•
To do debugging tasks not available through the HP DECwindows Motif for
OpenVMS GUI pull-down menus and push buttons
Figure 8–9 shows the RUN command in the command view.
8–15
Introduction
8.3 Entering Commands at the Prompt
Figure 8–9 Entering Commands at the Prompt
When you use the HP DECwindows Motif for OpenVMS interface pull-down
menus and push buttons, the debugger translates your input into debugger
commands and echoes these commands on the command line so that you have a
record of your commands. Echoed commands are visually indistinguishable from
commands that you enter explicitly on the command line.
For information about the debugger’s command interface, see Part II. For online
help about the commands, see Section 8.4.3.
In addition to entering debugger commands interactively at the prompt, you can
also place them in debugger initialization files and command files for execution
within the HP DECwindows Motif for OpenVMS environment.
You can also take advantage of the keypad support available at the commandentry prompt. (This support is a subset of the more extensive keypad support
provided for the command interface, which is described in Appendix A.) The
commands in Table 8–6 are mapped to individual keys on your computer
keypad.
Table 8–6 Keypad Definitions in the HP DECwindows Motif for OpenVMS
Debugger Interface
Command
Corresponding Key
Step/Line
KP0
Step/Into
GOLD-KP0
Step/Over
BLUE-KP0
Examine
KP1
Examine^
GOLD-KP1
Go
KP,
Show Calls
KP5
Show Calls 3
GOLD-KP5
To enter one of these commands, press the key or keys indicated, followed by the
Enter key on the keypad. (The GOLD key is PF1; the BLUE key is PF4.)
For information on changing these key bindings, or binding commands to
unassigned keys on the keypad, see Section 10.10.4.4.
8–16
Introduction
8.3 Entering Commands at the Prompt
8.3.1 Debugger Commands That Are Not Available in the HP DECwindows
Motif for OpenVMS Interface
Table 8–7 lists the debugger commands that are disabled in the debugger’s HP
DECwindows Motif for OpenVMS interface. Many of them are relevant only to
the debugger’s screen mode.
Table 8–7 Debugger Commands Not Available in the HP DECwindows Motif for
OpenVMS User Interface
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
1
(SET,SHOW) WINDOW
MOVE
(SET,CANCEL) DISPLAY
SAVE
SHOW SELECT
SCROLL
SPAWN
1 Help
on commands is available from the Help menu in a debugger window.
The debugger issues an error message if you enter any of these commands on
the command line, or if the debugger encounters one of these commands while
executing a command procedure.
8.4 Displaying Online Help About the Debugger
The following types of online help about the debugger and debugging are
available during a debugging session:
•
Context-sensitive help—information about an area or object in a window or
dialog box
•
Task-oriented help—consists of an introductory help topic named Overview 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
Task-oriented topics related to context-sensitive topics are connected through the
list of additional topics in the help windows.
8–17
Introduction
8.4 Displaying Online Help About the Debugger
8.4.1 Displaying 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 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.
Notes
Chapter 12, which is organized by task, explains how to use the
debugger’s Heap Analyzer.
You cannot obtain true context-sensitive help about any push button other
than Stop. This is because all other buttons can be modified or removed.
8.4.2 Displaying the Overview Help Topic and Subtopic
The Overview help topic (Overview of the Debugger) and its subtopics provide
task-oriented information about the debugger and debugging.
To display the Overview topic, 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.
To display information about a particular topic, choose it from the list of
additional topics.
8.4.3 Displaying Help on Debugger Commands
To display help on debugger commands:
1. Choose On Commands from the Help menu of a debugger window.
2. Choose the command name or other topic (for example, Language_Support)
from the list of additional topics.
Note that the Help command is not available through the command line interface
in the command view.
8.4.4 Displaying Help on Debugger Diagnostic Messages
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.
8–18
9
Starting and Ending a Debugging Session
This chapter explains how to:
•
Start the debugger (Section 9.1)
•
Continue when your program completes execution (Section 9.2)
•
Rerun the same program from the current debugging session (Section 9.3)
•
Run another program from the current debugging session (Section 9.4)
•
Interrupt program execution and debugger operations (Section 9.6)
•
End a debugging session (Section 9.7)
•
Start the debugger in additional ways for specific purposes (Section 9.8)
•
Debug a program already running in a subprocess or detached process
(Section 9.5)
9.1 Starting the Kept Debugger
This section explains the most common way to start the debugger from DCL level
( $ ) and bring your program under debugger control. Section 9.8 explains optional
ways to start the debugger.
Starting the kept debugger as explained here enables you to use the Connect (see
Section 9.5), Rerun (see Section 9.3), and Run (see Section 9.4) features.
To start the debugger and bring your program under debugger control:
1. Verify that you have compiled and linked the program as explained in
Section 1.2.
2. Enter the following command line:
$ DEBUG/KEEP
By default, the debugger starts up as shown in Figure 9–1. The main window
remains empty until you bring a program under debugger control (Step 4).
Upon startup, the debugger executes any user-defined initialization file (see
Section 13.2).
3. Bring your program under debugger control using one of the following three
techniques:
•
If the program is already running in a subprocess or detached process, use
the CONNECT command to bring the program under debugger control.
See Section 9.5.
9–1
Starting and Ending a Debugging Session
9.1 Starting the Kept Debugger
Figure 9–1 Debugger at Startup
•
Run a specified image (this is the most common technique):
1. Choose Run Image... from the File menu on the main window. The
Run Image dialog lists the executable images in your current directory
(see Figure 9–2).
2. Click on the name of the image to be debugged. The Image: field
displays the image name.
3. If applicable, enter arguments to be passed to the program in the
Arguments: field. If you specify a quoted string, you might have to
add quotation marks because the debugger strips quotation marks
when parsing the string.
4. Click on OK.
•
Run an image by specifying a DCL command or a symbol for a foreign
command:
1. Choose Run Foreign Command... from the File menu on the main
window. The Run Foreign Command dialog is displayed (see
Figure 9–3).
2. Enter the symbol in the Foreign Command: field (such a symbol can
provide a shortcut around the directory and file selection process).
The foreign command X1, shown in Figure 9–3, has been previously
defined:
$X1 :== RUN MYDISK:[MYDIR.MYSUBDIR]EIGHTQUEENS.EXE
3. Enter any arguments to be passed with the command in the
Arguments: field.
9–2
Starting and Ending a Debugging Session
9.1 Starting the Kept Debugger
Figure 9–2 Running a Program by Specifying an Image
Figure 9–3 Running a Program by Specifying a Command Symbol
4. Click on OK.
9–3
Starting and Ending a Debugging Session
9.1 Starting the Kept Debugger
Once the debugger has control of the program, the debugger:
•
Displays the program’s source code in the main window, as shown in
Figure 9–4.
•
Suspends execution at the start of the main program. The current-location
pointer to the left of the source code shows which line of code will be executed
next.
Figure 9–4 Source Display at Startup
The message displayed in the command view indicates that this debugging
session is initialized for a C program and that the name of the source module is
EIGHTQUEENS.
With certain programs, the debugger sets a temporary breakpoint to suspend
program execution at the start of some initialization code, before the main
program, and displays the following message:
Type GO to reach MAIN program
No source line for address: nnnnnnnn
With some of these programs (for example, Ada programs), the breakpoint
enables you to debug the initialization code using full symbolic information.
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 as explained in Chapter 10.
9–4
Starting and Ending a Debugging Session
9.1 Starting the Kept Debugger
Note the following restrictions about running a program under debugger control:
•
You cannot use the procedure in this section to connect the debugger to a
running program (see Section 9.8.2).
•
To run a program under debugger control over a network link, you must use
the debugger client/server interface. See Section 9.9 for more information.
If you try to run a program that does not exist, or misspell the name of a program
that does exist, the following error messages are displayed in the DECterm
window, rather than in the command view:
%DCL-W-ACTIMAGE, error activating image
-CLI-E-IMAGEFNF, image file not found
9.2 When Your Program Completes Execution
When your program completes execution normally during a debugging session,
the debugger issues the following message:
’Normal successful completion’
You then have the following options:
•
You can rerun your program from the same debugging session (see
Section 9.3).
•
You can run another program from the same debugging session (see
Section 9.4).
•
You can end the debugging session (see Section 9.7).
9.3 Rerunning the Same Program from the Current Debugging
Session
When running the kept debugger (see Section 9.1), you can rerun the program
currently under debugger control at any time during a debugging session.
To rerun the program:
1. Choose Rerun Same... from the File menu on the main window. The Rerun
dialog is displayed (see Figure 9–5).
2. Enter any arguments to be passed to the program, if required, in the
Arguments: field. If you specify a quoted string, you might have to add
quotation marks because the debugger strips quotation marks when parsing
the string.
3. Choose whether or not to keep the current state of any breakpoints,
tracepoints, or static watchpoints that you previously set, activated, or
deactivated (see Section 10.4 and Section 10.5.5). 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. Click on OK.
9–5
Starting and Ending a Debugging Session
9.3 Rerunning the Same Program from the Current Debugging Session
Figure 9–5 Rerunning the Same Program
When you rerun a program, it is in the same initial state as a program that is
brought under debugger control as explained in Section 9.1, except for any saved
breakpoints, tracepoints, 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
(see Section 9.1).
9.4 Running Another Program from the Current Debugging Session
You can bring another program under debugger control at any time during a
debugging session, if you started the debugger as explained in Section 9.1. Follow
the procedure in that section for bringing a program under debugger control (also
note the restrictions about using that procedure).
9.5 Debugging an Already Running Program
This section describes how to debug a program that is already running in a
subprocess or in a detached process. Perform the following steps:
1. Start the Kept debugger configuration using the DCL command:
$ DEBUG/KEEP
2. At the DBG> prompt, use the CONNECT command to interrupt the program
and bring it under debug control. CONNECT can be used to attach to
a program running in a subprocess or attach to a program running in a
detached process. Detached processes must meet both of the following
requirements:
•
The detached process UIC must be in the same group as your process
•
The detached process must have a CLI mapped
The second requirement effectively means that the program must have been
started with a command similar to this:
$ RUN/DETACH/INPUT=xxx.com SYS$SYSTEM:LOGINOUT
where xxx.com is a command procedure that starts the program with
/NODEBUG.
9–6
Starting and Ending a Debugging Session
9.5 Debugging an Already Running Program
Once you have connected to the program, the rest of the debugging session is
the same as a normal debugger session.
3. When you have finished debugging the program, do either of the following:
•
Use the DISCONNECT command to release debugger control of the
program. The program continues execution.
•
Exit the debugger. The program will terminate.
9.6 Interrupting Program Execution and Aborting Debugger
Operations
To interrupt program execution during a debugging session, click on the Stop
button on the push button view (see Figure 8–3). 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 has no
effect when the program is not running or when the debugger is not executing a
command.
9.7 Ending a Debugging Session
To end a debugging session and terminate the debugger, choose Exit Debugger
from the File menu on the main window, or enter EXIT at the prompt (to avoid
confirmation dialogue). This returns control to system level.
To rerun your program from the current debugging session, see Section 9.3.
To run another program from the current debugging session, see Section 9.4.
9.8 Additional Options for Starting the Debugger
In addition to the startup procedure described in Section 9.1, the following
options are available for starting the debugger from DCL level ($):
•
Start the debugger by running the program to be debugged with the DCL
command RUN (see Section 9.8.1).
•
Interrupt a running program by pressing Ctrl/Y and then start the debugger
using the DCL command DEBUG (see Section 9.8.2).
•
Override the debugger’s default (HP DECwindows Motif for OpenVMS user
interface (see Section 9.8.3) to achieve the following:
–
Display the HP DECwindows Motif for OpenVMS user interface on
another workstation
–
Display the command interface in a DECterm window along with any
program input/output (I/O)
–
Display the command interface and program I/O in separate DECterm
windows
In all cases, before starting the debugger, verify that you have compiled and
linked the modules of your program (as explained in Section 1.2).
9–7
Starting and Ending a Debugging Session
9.8 Additional Options for Starting the Debugger
9.8.1 Starting the Debugger by Running a Program
You can start the debugger and also bring your program under debugger control
in one step by entering the DCL command RUN filespec (assuming the program
was compiled and linked with the /DEBUG qualifier).
However, you cannot then use the Rerun or Run features explained in Section 9.3
and Section 9.4, respectively. To rerun the same program or run a new program
under debugger control, you must first exit the debugger and start it again.
To start the debugger by running a program, enter the DCL command
RUN filespec to start the debugger. For example:
$ RUN EIGHTQUEENS
By default, the debugger starts up as shown in Figure 9–4, executing any userdefined initialization file and displaying the program’s source code in the main
window. The current-location pointer shows that execution is paused at the start
of the main program. The debugger sets the language-dependent parameters to
the source language of the main program unit.
For more information about debugger startup, see Section 9.1.
9–8
Starting and Ending a Debugging Session
9.8 Additional Options for Starting the Debugger
9.8.2 Starting the Debugger After Interrupting a Running Program
You can bring a program that is executing freely under debugger control. This is
useful if you suspect that the program might be in an infinite loop or if you see
erroneous output.
To bring your program under debugger control:
1. Enter the DCL command RUN/NODEBUG filespec to execute the program
without debugger control.
2. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL
command interpreter.
3. Enter the DCL command DEBUG to start the debugger.
For example:
$ RUN/NODEBUG EIGHTQUEENS
.
.
.
Ctrl/Y
Interrupt
$ DEBUG
[starts debugger]
At startup, the debugger displays the main window and executes any user-defined
initialization file, and sets the language-dependent parameters to the source
language of the module in which execution was interrupted.
To help you determine where execution was interrupted:
1. Look at the main window.
2. Enter the SET MODULES/CALLS command at the command-entry prompt.
3. Display the Call Stack menu on that window to identify the sequence of
routine calls on the call stack. The routine at level 0 is the routine in which
execution is currently paused (see Section 10.3.1).
When you start the debugger in this manner, you cannot then use the Rerun or
Run features explained in Section 9.3 and Section 9.4, respectively. To rerun the
same program or run a new program under debugger control, you must first exit
the debugger and start it again.
For more information about debugger startup, see Section 9.1.
9.8.3 Overriding the Debugger’s Default Interface
By default, if your workstation is running HP DECwindows Motif for OpenVMS,
the debugger starts up in the HP DECwindows Motif for OpenVMS user interface,
which is displayed on the workstation specified by the HP DECwindows Motif for
OpenVMS applicationwide logical name DECW$DISPLAY.
This section explains how to override the debugger’s default DECwindows Motif
user interface to achieve the following:
•
Display the debugger’s HP DECwindows Motif for OpenVMS user interface
on another workstation
•
Display the debugger’s command interface in a DECterm window along with
any program I/O
9–9
Starting and Ending a Debugging Session
9.8 Additional Options for Starting the Debugger
•
Display the debugger’s command interface and program I/O in separate
DECterm windows
The logical name DBG$DECW$DISPLAY enables you to override the
default interface of the debugger. In most cases, there is no need to define
DBG$DECW$DISPLAY because the default is appropriate.
Section 9.8.3.4 provides more information about the logical names
DBG$DECW$DISPLAY and DECW$DISPLAY.
9.8.3.1 Displaying the Debugger’s HP DECwindows Motif for OpenVMS User Interface on
Another Workstation
If you are debugging a HP DECwindows Motif for OpenVMS application that
uses most of the screen (or if you are debugging pop-ups in a Motif application),
you might find it useful to run the program on one workstation and display the
debugger’s HP DECwindows Motif for OpenVMS user interface on another. To do
so:
1. Enter a logical definition with the following syntax in the DECterm window
from which you plan to run the program:
DEFINE/JOB DBG$DECW$DISPLAY workstation_pathname
The path name for the workstation where the debugger’s HP DECwindows
Motif for OpenVMS user interface is to be displayed is workstation_pathname.
See the description of the SET DISPLAY command in the OpenVMS DCL
Dictionary for the syntax of this path name.
It is recommended that you use a job definition. If you use a process
definition, it must not have the CONFINE attribute.
2. Run the program from that DECterm window. The debugger’s HP
DECwindows Motif for OpenVMS user interface is now displayed on the
workstation specified by DBG$DECW$DISPLAY. The application’s windowing
interface is displayed on the workstation where it is normally displayed.
3. Use client/server mode (see Section 9.9.2).
9.8.3.2 Displaying the Debugger’s Command User Interface in a DECterm Window
To display the debugger’s command interface in a DECterm window, along with
any program I/O:
1. Enter the following definition in the DECterm window from which you plan
to start the debugger:
$ DEFINE/JOB DBG$DECW$DISPLAY " "
You can specify one or more spaces between the quotation marks. You should
use a job definition for the logical name. If you use a process definition, it
must not have the CONFINE attribute.
2. Start the debugger from that DECterm window (see Section 9.1). The
debugger’s command interface is displayed in the same window.
For example:
$ DEFINE/JOB DBG$DECW$DISPLAY " "
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG>
9–10
Starting and Ending a Debugging Session
9.8 Additional Options for Starting the Debugger
You can now bring your program under debugger control as explained in
Section 9.1.
9.8.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm
Windows
This section describes how to display the debugger’s command interface in a
DECterm window other than the DECterm window in which you start the
debugger. This separate window is useful when using the command interface to
debug a screen-oriented program as follows:
•
The program’s input/output (I/O) is displayed in the window from which you
start the debugger.
•
The debugger’s I/O, including any screen-mode display, is displayed in the
separate window.
The effect is the same as entering the SET MODE SEPARATE command at the
DBG> prompt on a workstation running VWS rather than HP DECwindows Motif
for OpenVMS. (The SET MODE SEPARATE command is not valid when used in
a DECterm window.)
The following example shows how to display the debugger’s command interface in
a separate debugger window titled Debugger.
1. Create the command procedure SEPARATE_WINDOW.COM shown in
Example 9–1.
Example 9–1 Command Procedure SEPARATE_WINDOW.COM
$ ! Simulates effect of SET MODE SEPARATE from a DECterm window
$ !
$ CREATE/TERMINAL/NOPROCESS /WINDOW_ATTRIBUTES=(TITLE="Debugger",ICON_NAME="Debugger",ROWS=40)/DEFINE_LOGICAL=(TABLE=LNM$JOB,DBG$INPUT,DBG$OUTPUT)
$ ALLOCATE DBG$OUTPUT
$ EXIT
$ !
$ ! The command CREATE/TERMINAL/NOPROCESS creates a DECterm
$ ! window without a process.
$ !
$ ! The /WINDOW_ATTRIBUTES qualifier specifies the window’s
$ ! title (Debugger), icon name (Debugger), and the number
$ ! of rows in the window (40).
$ !
$ ! The /DEFINE_LOGICAL qualifier assigns the logical names
$ ! DBG$INPUT and DBG$OUTPUT to the window, so that it becomes
$ ! the debugger input and output device.
$ !
$ ! The command ALLOCATE DBG$OUTPUT causes the separate window
$ ! to remain open when you end the debugging session.
2. Execute the command procedure as follows:
$ @SEPARATE_WINDOW
%DCL-I-ALLOC, _MYNODE$TWA8: allocated
A new DECterm window is created with the attributes specified in
SEPARATE_WINDOW.COM.
3. Follow the steps in Section 9.8.3.2 to display the debugger’s command
interface. The interface is displayed in the new window.
9–11
Starting and Ending a Debugging Session
9.8 Additional Options for Starting the Debugger
4. You can now enter debugger commands in the debugger window. Program I/O
is displayed in the DECterm window from which you started the debugger.
5. When you end the debugging session with the EXIT command, control returns
to the DCL prompt in the program I/O window but the debugger window
remains open.
6. To display the debugger’s command interface in the same window as the
program’s I/O (as in Section 9.8.3.2), enter the following commands:
$ DEASSIGN/JOB DBG$INPUT
$ DEASSIGN/JOB DBG$OUTPUT
The debugger window remains open until you close it explicitly.
9.8.3.4 Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY
By default, if your workstation is running HP DECwindows Motif for OpenVMS,
the debugger starts up in the HP DECwindows Motif for OpenVMS user interface,
which is displayed on the workstation specified by the HP DECwindows Motif for
OpenVMS applicationwide logical name DECW$DISPLAY. DECW$DISPLAY is
defined in the job table by FileView or DECterm and points to the display device
for the workstation.
For information about DECW$DISPLAY, see the description of the DCL
commands SET DISPLAY and SHOW DISPLAY in the OpenVMS DCL Dictionary.
The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent
of DECW$DISPLAY. DBG$DECW$DISPLAY is similar to the debugger-specific
logical names DBG$INPUT and DBG$OUTPUT. These logical names enable you
to reassign SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on
which debugger input and output are to appear.
The default user interface of the debugger results when DBG$DECW$DISPLAY
is undefined or has the same translation as DECW$DISPLAY. By default,
DBG$DECW$DISPLAY is undefined.
The algorithm that the debugger follows when using the logical definitions of
DECW$DISPLAY and DBG$DECW$DISPLAY is as follows:
1. If the logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise,
use the logical name DECW$DISPLAY.
2. Translate the logical name. If its value is not null (if the string contains
characters other than spaces), the HP DECwindows Motif for OpenVMS user
interface is displayed on the specified workstation. If the value is null (if
the string consists only of spaces), the command interface is displayed in the
DECterm window.
To enable the OpenVMS Debugger to start up in the HP DECwindows Motif for
OpenVMS user interface, first enter one of the following DCL commands:
$DEFINE DBG$DECW$DISPLAY "WSNAME::0"
$SET DISPLAY/CREATE/NODE=WSNAME
where WSNAME is the nodename of your workstation.
9–12
Starting and Ending a Debugging Session
9.9 Starting the Motif Debug Client
9.9 Starting the Motif Debug Client
The OpenVMS Debugger Version 7.2 features a client/server interface that allows
you to debug programs running on OpenVMS on a VAX or Alpha CPU from a
client interface running on the same or separate system.
The debugger client/server retains the functionality of the kept debugger, but
splits the debugger into two components: the debug server and the debug client.
The debug server runs on an OpenVMS system, and is just like the kept debugger
without the user interface. The debug client contains the user interface, and runs
on an OpenVMS system using HP DECwindows Motif for OpenVMS, or on a PC
running Microsoft Windows 95 or Microsoft Windows NT.
9.9.1 Software Requirements
The debug server requires OpenVMS Version 7.2 or later.
The debug client can run on any of the following:
•
OpenVMS Version 7.2 or later, along with HP DECwindows Motif for
OpenVMS Version 1.2-4
•
Microsoft Windows 95
•
Microsoft Windows NT Version 3.51 or later (Intel or Alpha)
The OpenVMS Debugger client/server configuration also requires that the
following be installed on the OpenVMS node running the server:
•
A TCP/IP stack
•
DCE RPC
Notes
If you are running TCP/IP Services for OpenVMS (UCX) Version 4.1, you
must have ECO2 installed. You can also run a later version of UCX.
The OpenVMS Version 7.2 installation procedures automatically install
DCE RPC.
9.9.2 Starting the Server
You can start the debug server after logging in directly to the OpenVMS system,
or you may find it more convenient to log in remotely with a product such as
eXcursion, or an emulator such as Telnet.
To start the debug server, enter the following command:
$ DEBUG/SERVER
The server displays its network binding strings. The server port number is
enclosed in square brackets ([ ]). For example:
$ DEBUG/SERVER
%DEBUG-I-SPEAK:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-AWAIT:
TCP/IP: YES, DECnet: YES, UDP: YES
Network Binding: ncacn_ip_tcp:16.32.16.138[1034]
Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001]
Network Binding: ncadg_ip_udp:16.32.16.138[1045]
Ready for client connection...
9–13
Starting and Ending a Debugging Session
9.9 Starting the Motif Debug Client
Use one of the network binding strings to identify this server when you connect
from the client (see Section 9.9.4). The following table matches the network
binding string prefix with its associated network transport:
Network Transport
Network Binding String Prefix
TCP/IP
ncacn_ip_tcp
DECnet
ncacn_dnet_nsp
UDP
ncadg_ip_udp
Notes
You can usually identify the server using only the node name and the port
number. For example, nodnam[1034].
Messages and program output appear by default in the window in which
you start the server. You can redirect program output to another window
as required.
The following example contains an error message that indicates that DCE is not
installed:
$ debug/server
%LIB-E-ACTIMAGE, error activating image disk:[SYSn.SYSCOMMON.][SYSLIB]DTSS$SHR.EXE;
-RMS-E-FNF, file not found
This indicates that DCE is installed but not configured.
9.9.3 Primary Clients and Secondary Clients
The debugger client/server interface allows more than one client to be connected
to the same server. This allows team debugging, classroom sessions, and other
applications.
The primary client is the first client to connect to the server. A secondary client
is an additional client that has connected to the same server. The primary client
controls whether or not any secondary clients can connect to the server.
Section 9.9.4 describes how to specify the number of secondary clients allowed in
a session.
9.9.4 Starting the Motif Client
A session is the connection between a particular client and a particular server.
Each session is identified within the client by the network binding string the
client used to connect to the server. Once the debug server is running, start the
Motif debug client. To do so, enter the following command:
$ DEBUG/CLIENT
To establish a session from the Motif debug client, click on Server Connection
from the File menu. The Server Connection dialog displays, in the Connection
list, the default network binding string. This string is based on the last string
you entered, or the node on which the client is running. There is not necessarily
a server associated with the default binding string. Figure 9–6 shows the Server
Connection dialog.
9–14
Starting and Ending a Debugging Session
9.9 Starting the Motif Debug Client
Figure 9–6 Debug Server Connection Dialog
From the buttons at the bottom of the Server Connection dialog, you can
•
Connect to the selected server to begin and activate a new session
•
Disconnect from a session
•
Test whether the session is still available
•
Stop the server
•
Cancel the connection operation and dismiss the dialog
In addition, the Options button invokes the Server Options dialog, which allows
you to select the network transport to be used (see Section 11.5.1).
The Server Options dialog also allows you to select the number of secondary
clients (0-31) allowed for a new session.
Figure 9–7 shows the Server Options dialog.
Figure 9–7 Server Options Dialog
To connect the client to a server, perform the following steps:
1. Open the File menu.
2. Click Server Connection.
9–15
Starting and Ending a Debugging Session
9.9 Starting the Motif Debug Client
3. Enter the server network binding string in the Connection field, or select the
default string.
4. Click Options.
5. In the Server Options dialog, click on the network transport: TCP/IP, DECnet,
or UDP.
6. In the Server Options dialog. select the number of secondary clients (0-31) to
be allowed.
7. Click OK to dismiss the Server Options dialog.
8. In the Server Connection dialog, click Connect.
You can establish connections to an unlimited number of servers by repeating the
sequence above and specifying the new network binding string each time.
9.9.5 Switching Between Sessions
Each time you connect to a server and initiate a session, the session is listed in
the Active Sessions list in the Server Connection dialog (see Figure 9–8). You can
switch back and forth between sessions. Each time you switch to a new session,
the debugger updates the contents of any open debugger displays with the new
context.
To switch to a different session, perform the following steps:
1. Open the File menu.
2. Click Server Connection.
3. Click the Active Sessions list to display the list of active sessions.
4. Double click the required session in the Active Sessions list. This selects the
session as the current session, dismisses the Server Connection dialog, and
updates the debugger displays with the current context.
Note that you cannot change the number of secondary clients allowed on a session
while that session is active. To change the number of clients allowed on a session,
you must be the primary client, and perform the following steps:
1. Open the File menu.
2. Specify the network binding string of the session.
3. Click Disconnect.
4. Click Options.
5. In the Server Options dialog, click on the network transport: TCP/IP, DECnet,
or UDP.
6. In the Server Options dialog, select the number of secondary clients (0-31) to
be allowed.
7. Click OK to dismiss the Server Options dialog.
8. In the Server Connection dialog, click Connect.
9–16
Starting and Ending a Debugging Session
9.9 Starting the Motif Debug Client
Figure 9–8 Active Sessions List
9.9.6 Closing a Client/Server Session
Click on Exit Debug? on the File menu to invoke the Confirm Exit dialog.
Figure 9–9 shows the Confirm Exit dialog.
Figure 9–9 Confirm Exit Dialog
Once you have invoked the Confirm Exit dialog, perform one of the following:
•
To terminate both the client and the server (default) click OK.
•
To dismiss the Confirm Exit dialog without taking any action, click Cancel.
•
To terminate only the debug client, perform the following steps:
1. Click Exit Server.
2. Click OK.
•
To terminate only the debug server, perform the following steps:
1. Click Exit Client.
2. Click OK.
If you do not terminate the debug server, you can connect to the server from
another debug client. If you do not terminate the client, you can connect to
another server for which you know the network binding string.
9–17
10
Using the Debugger
This chapter explains how to:
•
Display the source code of your program (Section 10.1)
•
Edit your program under debugger control (Section 10.2)
•
Execute your program under debugger control (Section 10.3)
•
Suspend execution with breakpoints (Section 10.4)
•
Examine and manipulate program variables (Section 10.5)
•
Access program variables (Section 10.6)
•
Display and modify values stored in registers (Section 10.7)
•
Display the decoded instruction stream of your program (Section 10.8)
•
Debug tasking programs (Section 10.9)
•
Customize the debugger’s HP DECwindows Motif for OpenVMS user interface
(Section 10.10)
The chapter describes window actions and window menu choices, but you can
perform most common debugger operations by choosing items from contextsensitive pop-up menus. To access these menus, click MB3 while the mouse
pointer is in the window area.
You can also enter commands at the HP DECwindows Motif for OpenVMS
command prompt. For information about entering debugger commands, see
Section 8.3.
For the source code of programs EIGHTQUEENS.EXE and 8QUEENS.EXE,
shown in the figures of this chapter, see Appendix D.
10.1 Displaying the Source Code of Your Program
The debugger displays the source code of your program in the main window (see
Figure 10–1).
Whenever execution is suspended (for example, at a breakpoint), the debugger
updates the source display by displaying the code surrounding the point at which
execution is paused. The current-location pointer, to the left of the source code,
marks which line of code will execute next. (A source line corresponds to one or
more programming-language statements, depending on the language and coding
style.)
10–1
Using the Debugger
10.1 Displaying the Source Code of Your Program
Figure 10–1 Source Display
By default, the debugger displays compiler-generated line numbers to the left of
the source code. These numbers help identify breakpoints, which are listed in the
breakpoint view (see Section 10.4.4). 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, toggle Display Line Numbers from the File menu on the main window.
The Call Stack menu, between the source view and the push button view, shows
the name of the routine whose source code is displayed.
The current-location pointer is normally filled in as shown in Figure 10–1. It
is cleared if the displayed code is not that of the routine in which execution is
paused (see Section 10.1.3 and Section 10.6.2).
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 following sections explain how to display source code for other parts of
your program so that you can set breakpoints in various modules, and so on.
Section 10.1.3 explains what to do if the debugger cannot find source code for
display. Section 10.6.2 explains how to display the source code associated with
routines that are currently active on the call stack.
After navigating the main window, 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 Section 1.2).
10.1.1 Displaying the Source Code of Another Routine
To display source code of another routine:
1. Choose Browse Sources from the File menu on the main window (see
Figure 10–2).
Select SYMBOLIC display the names of all modules linked in the image.
Select ALL to display the names of only those modules for which the debugger
has symbolic information.
10–2
Using the Debugger
10.1 Displaying the Source Code of Your Program
The Source Browser dialog box displays the name of your executable image,
which is highlighted, and the class of shareable images linked with it
(SYMBOLIC or ALL). The name of a linked image is dimmed if 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 containing the routine of interest.
The names of the routines in that module are displayed (indented) under the
module name, and the Display Source button is now highlighted.
4. Click on the name of the routine whose source code you want to display.
5. Click on the Display Source push button. The debugger displays in the source
view the source code of the target routine, along with an empty breakpoint
button to the left of the source code. If the instruction view is open, this
display is updated to show the machine code of the target routine.
Section 10.6.2 describes an alternative way to display routine source code for
routines currently active on the call stack.
10–3
Using the Debugger
10.1 Displaying the Source Code of Your Program
Figure 10–2 Displaying Source Code of Another Routine
10–4
Using the Debugger
10.1 Displaying the Source Code of Your Program
10.1.2 Displaying the Source Code of Another Module
To display source code of another module:
1. Choose Browse Sources from the File menu on the main window.
Select SYMBOLIC display the names of all modules linked in the image.
Select ALL to display the names of only those modules for which the debugger
has symbolic information.
The Source Browser dialog box displays the name of your executable image,
which is highlighted, and the class of shareable images linked with it
(SYMBOLIC or ALL). The names of the shareable images are dimmed if no
symbolic information is available for them.
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 display in the main window now shows
the routine’s source code. (If the instruction display in the instruction view is
open, this display is updated to show the routine’s instruction code.)
10.1.3 Making Source Code Available for Display
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 or linked without the debug option (see Section 1.2).
•
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 S/ret button in the push button view (see Section 10.3.5).
•
The source file might have been moved to a different directory after it was
compiled. Section 10.1.4 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 moved to point to the source line to which execution returns in the
calling routine.
10.1.4 Specifying the Location of Source Files
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
DBG> prompt (see Section 6.2).
10–5
Using the Debugger
10.2 Editing Your Program
10.2 Editing Your Program
The debugger provides a simple text editor you can use to edit your source files
while debugging your program (see Figure 10–3).
The text editor available through the debugger’s HP DECwindows Motif for
OpenVMS menu interface is a simple convenience feature, not intended to replace
sophisticated text editors such as the Language-Sensitive Editor (LSE). You
cannot substitute a more sophisticated editor for the text editor invoked with the
Edit File item in the Commands menu. To use a different editor, enter the EDIT
command at the DBG> prompt in the command view (see EDIT in the Command
Reference Dictionary of this manual).
Note
When you enter an EDIT command at the command prompt, the debugger
uses the DECterm window that invoked the debugging session as the
user-defined-editor window (as opposed to the debugger’s built-in editor,
which is hardwired to the COMMANDS EDIT FILE pull-down menu).
This behavior constitutes a tradeoff that allows a more flexible choice of
editors. If you inadvertently exit this DECterm window using FILE EXIT
or MWM Close, the debugging session terminates abruptly, having lost its
parent window.
Figure 10–3 Editor Window
To invoke the editor, choose the Edit File item in the Commands menu on the
main window. By default, the editor opens a buffer and displays the module
currently displayed in the source view. The buffer is named with the file
specification of the file in the buffer. If no file is displayed in the source view, the
editor displays an empty text buffer, called main_buffer. The buffer name appears
in the buffer menu, which is just under the menu bar of the editor view.
10–6
Using the Debugger
10.2 Editing Your Program
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 text buffer appears in the buffer menu. You can cut, copy, and paste text
from buffer to buffer by choosing items from the Edit menu and selecting buffers
from the buffer menu.
You can perform forward and backward search and replace operations by entering
strings in the Find and Replace with fields and clicking on a directional arrow.
You can perform a repeated search for the string by continuing to press the
Return key. You can also continue a search by choosing the Find/Replace Next or
Find/Replace Previous items in the Edit menu.
To save the file, choose the Save or Save As... items from the File menu. If you do
not save your corrections before closing a modified buffer or exiting the debugger,
the debugger displays a warning message.
To test any changes to the source code:
1. Select a DECterm window separate from that in which the debugger is
running.
2. Recompile the program.
3. Relink the program.
4. Return to the debugging session.
5. Choose the Run Image... item in the File menu on the main window.
10.3 Executing Your Program
This section explains how to:
•
Determine where execution is currently paused within your program
•
Start or resume program execution
•
Execute the program one source line at a time, step by step
For information about rerunning your program or running another program from
the current debugging session, see Section 9.3 and Section 9.4.
10.3.1 Determining Where Execution Is Currently Paused
To determine where execution is currently paused within your program:
1. If the current-location pointer is not visible in the main window, click on the
Call Stack menu of that window to display the pointer (see Figure 10–1).
2. Look at the current-location pointer:
•
If the pointer is filled in, it marks the source line whose code will execute
next (see Section 10.1). The Call Stack menu always shows the routine at
scope 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:
If the Call Stack menu shows level 0, source code is not available
for display for the routine in which execution is paused (see
Section 10.1.3).
10–7
Using the Debugger
10.3 Executing Your Program
If the Call Stack menu shows a level other than 0, you are displaying
the source code for a calling routine (see Section 10.6.2).
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.
10.3.2 Starting or Resuming Program Execution
To start program execution or resume execution from the current location, click
on the Go button in the push button view (see Figure 8–3).
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 button. The main window will show where you interrupted program
execution, and the Call Stack menu will identify the sequence of routine calls
at that point (see Section 10.3.1).
•
To execute your program directly to a particular location. In this case,
you first set a breakpoint at the location (see Section 10.4) 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 button on the push button view.
Whenever the debugger suspends execution of the program, the main window
display is updated and the current-location pointer marks which line of code will
execute next.
10.3.3 Executing Your Program One Source Line at a Time
To execute one source line of your program, click on the STEP button in the push
button view or enter the STEP command in the command view. 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 which line of code will execute next.
Note the following points about source lines and the stepping behavior:
10–8
•
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 button, the debugger executes one executable
line and suspends execution at the start of the next executable line, skipping
over any intervening nonexecutable lines.
Using the Debugger
10.3 Executing Your Program
•
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 button to their left in the main window.
•
Examples of nonexecutable lines are comment lines or lines with variable
declarations without value assignments. Nonexecutable lines do not have a
button to their left in the main window.
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 (see Section 1.2).
10.3.4 Stepping into a Called Routine
When program execution is paused at a routine call statement, clicking on the
STEP 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 enables you to 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 Section 10.4) and then clicking on the Go button in the push
button view.
2. When execution is paused at the call statement, click on the S/in button
in the push button view, or enter the STEP/INTO command at the DBG>
prompt. This moves execution just past the start of the called routine.
Once execution is within the called routine, click on the STEP button to execute
the routine line by line.
Clicking on the S/in button when execution is not paused at a routine call
statement is the same as clicking on the STEP button.
10.3.5 Returning from a Called Routine
When execution is suspended within a called routine, you can execute your
program directly to the end of that routine by clicking on the S/ret button in the
push button view, or enter the STEP/RETURN command at the DBG> prompt.
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.
You can also use the S/call button in the push button view (or enter the
STEP/CALL command at the DBG> prompt) to execute the program directly
to the next Return or Call instruction.
The S/ret button is particularly useful if you have inadvertently stepped into a
system or library routine (see Section 10.1.3).
10–9
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
10.4 Suspending Execution by Setting Breakpoints
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 HP DECwindows Motif for OpenVMS user interface,
you can set breakpoints on:
•
Specific source lines
•
Specific routines (functions, subprograms, and so on)
•
Exceptions signaled during the execution of your program
Note
If you are stopped at a breakpoint in a routine that has control of the
mouse pointer by a PointerGrab or a KeyboardGrab, your workstation
will hang.
To work around this problem, debug your program using two
workstations. For more information, see Section 9.8.3.1.
The debugger provides two ways to qualify breakpoints:
•
You can set a conditional breakpoint. The debugger suspends execution
at a conditional breakpoint only when a specified relational expression is
evaluated as true.
•
You can set an action breakpoint. The debugger executes one or more
specified system-specific commands when it reaches the breakpoint.
You can set a breakpoint that is both a conditional and action breakpoint.
The following sections explain these breakpoint options.
10.4.1 Setting Breakpoints on Source Lines
You can set a breakpoint on any source line that has a button to its left in
the source display. 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 (see Section 10.1).
2. Click on the button to the left of that line. (The breakpoint is set when the
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.
Figure 10–4 shows that a breakpoint has been set on the start of line 37.
10–10
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
Figure 10–4 Setting a Breakpoint on a Source Line
10.4.2 Setting Breakpoints on Routines with Source Browser
Setting a breakpoint on a routine enables you to move execution directly to the
routine and inspect the local environment.
To set a breakpoint on a routine:
1. Choose Browse Sources from the File menu on the main window (see
Figure 10–2).
Select SYMBOLIC to display the names of all modules linked in the image.
Select ALL to display the names of only those modules for which the debugger
has symbolic information.
The Source Browser dialog box displays the name of your executable image,
which is highlighted, and the class of shareable images linked with it
(SYMBOLIC or ALL). The name of a linked image is dimmed if no symbolic
information is available for that image.
2. Double click on the name of the 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 target module. The names of the routines
in that module are displayed (indented) under the module name (see
Figure 10–5).
4. Double click on the name of the routine on which to set a breakpoint. The
debugger echoes the results of your SET BREAKPOINT command on the
command line in the command view.
Alternatively, click once on the name of the routine, then click the Set
Breakpoint button in the Source Browser view. The debugger echoes the
results of your SET BREAKPOINT command on the command line in the
command view.
10–11
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
Figure 10–5 Setting a Breakpoint on a Routine
10.4.3 Setting an Exception Breakpoint
An exception breakpoint suspends execution when an exception is signaled and
before any exception handler declared by your program executes. This enables
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 on the
main window or the optional views window.
10.4.4 Identifying the Currently Set Breakpoints
There are three ways to determine which breakpoints are currently set:
•
10–12
Scroll through your source 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 (see Section 10.4.5).
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
•
Choose Views... from the Options menu on the main window or the optional
views window. When the Views dialog box appears, click on Breakpoint View
to display the breakpoint view (see Figure 8–4).
The breakpoint view lists a module name and line number for each breakpoint
(see Section 10.1). A filled-in button next to the breakpoint identification
indicates that the breakpoint is activated. A cleared button indicates that the
breakpoint is deactivated.
•
Enter the SHOW BREAK command at the DBG> prompt in the command
view. The debugger lists all the breakpoints that are currently set, including
specifications for conditional breakpoints, and commands to be executed at
action breakpoints.
10.4.5 Deactivating, Activating, and Canceling Breakpoints
After a breakpoint is set, you can deactivate, activate, or delete it.
Deactivating a breakpoint causes the debugger to ignore the breakpoint 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 (see Section 9.3). Note the following points:
•
To deactivate a specific breakpoint, clear the button for that breakpoint in the
main window 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.
Activating a breakpoint causes it to take effect during program execution:
•
To activate a breakpoint, fill in the button for that breakpoint in the main
window 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.
When you cancel a breakpoint, it is no longer listed in the breakpoint view so
that later you cannot activate it from that list. You have to reset the breakpoint
as explained in Section 10.4.1 and Section 10.4.2. Note the following points:
•
To cancel a specific breakpoint, choose Cancel from the Break menu on the
optional views window.
•
To cancel all breakpoints, choose Cancel All from the Break menu.
10.4.6 Setting a Conditional Breakpoint
The debugger suspends execution of the program at a conditional breakpoint
only when a specified expression is evaluated as true. The debugger evaluates
the conditional expression when program execution reaches the breakpoint and
ignores the breakpoint if the expression is not true.
The following procedure sets a conditional breakpoint, whether or not a
breakpoint was previously set at that location:
1. Display the source line on which you want to set the conditional breakpoint
(see Section 10.1).
10–13
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
2. Do one of the following:
•
Press Ctrl/MB1 on the button to the left of the source line. This displays
the Set/Modify Breakpoint dialog box, showing the source line you selected
in the Location: field (see Figure 10–6).
•
Choose the Set or Set/Modify item from the Break menu. When the
Set/Modify Breakpoint dialog box displays, enter the source 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.
Figure 10–6 Setting a Conditional Breakpoint
The following procedure modifies a conditional breakpoint; that is, it can be used
either to change the location or condition associated with an existing conditional
breakpoint, or to change an unqualified breakpoint into a conditional breakpoint:
1. Choose Views... from the Options menu on the main window or optional
views window. When the Views dialog box appears, click on Breakpoint View
to display the breakpoint view.
2. From the breakpoint view, do one of the following:
•
Press Ctrl/MB1 on the button to the left of the listed breakpoint.
•
Click on a breakpoint listed in the view, and choose the Set/Modify item
from the Break menu.
3. Follow steps 3 and 4 of the previous procedure, as appropriate.
10–14
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
10.4.7 Setting an Action Breakpoint
When a program reaches an action breakpoint, the debugger suspends execution
of the program and executes a specified list of commands.
To set an action breakpoint, whether or not a breakpoint was previously set at
that location:
1. Display the source line on which you want to set the action breakpoint (see
Section 10.1).
2. Do one of the following:
•
Press Ctrl/MB1 on the button to the left of the source line. This displays
the Set/Modify Breakpoint dialog box, showing the source line you selected
in the Location: field (see Figure 10–6).
•
Choose the Set or Set/Modify item from the Break menu. When the
Set/Modify Breakpoint dialog box displays, 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 (see Figure 10–7.)
Figure 10–7 Setting an Action Breakpoint
The following procedure modifies an action breakpoint; that is, it can be used
either to change the location or command associated with an existing action
breakpoint, or to change an unqualified breakpoint into an action breakpoint:
1. Choose Views... from the Options menu on the main window or optional views
window, then click on Breakpoint View when the Views dialog box appears.
2. From the breakpoint view, do one of the following:
•
Press Ctrl/MB1 on the button to the left of the listed breakpoint.
10–15
Using the Debugger
10.4 Suspending Execution by Setting Breakpoints
•
Click on a breakpoint listed in the view, and choose the Set/Modify item
in the Break menu.
3. Follow steps 3 and 4 of the previous procedure, as appropriate.
10.5 Examining and Manipulating Variables
This section explains how to:
•
Select variable names from windows
•
Display the value of a variable
•
Monitor a variable
•
Watch a variable
•
Change the value of a variable
See Section 10.6, which also applies to all operations on variables.
10.5.1 Selecting Variable Names from Windows
Use the following techniques to select variable names from windows for the
operations described in the sections that follow (see Section 10.5.2 for examples).
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 an 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 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, in the C language, the string
*int_point specifies the object designated by pointer int_point.
Select character strings from windows as follows:
10–16
•
In any window, to select a string delimited by blank spaces, use the standard
HP DECwindows Motif for OpenVMS word selection technique: position the
pointer on that string and then double click MB1.
•
In any window, to select an arbitrary character string, use the standard
HP DECwindows Motif for OpenVMS text-selection technique: position the
pointer on the first character, press and hold MB1 while dragging the pointer
over the string and then release MB1.
•
In the debugger source display, you also have the option of using languagesensitive text selection. To select a string delimited by language-dependent
identifier boundaries, position the pointer on that string and press
Ctrl/MB1.
Using the Debugger
10.5 Examining and Manipulating Variables
For example, suppose the source display contains the character string
arr2[m], then:
To select arr2, position the pointer on arr2 and press Ctrl/MB1.
To select m, position the pointer on m and press Ctrl/MB1.
You can change the key sequence for language-sensitive text selection as
explained in Section 10.10.4.2.
10.5.2 Displaying the Current Value of a Variable
To display the current value of a variable:
1. Find and select the variable name in a window as explained in Section 10.5.1.
2. Click on the EX button in the push button view. The debugger displays the
variable and its current value in the command view. The debugger displays
the value of a variable in the current scope, which might not be the same as
the source location you were intending.
Figure 10–8, Figure 10–9, and Figure 10–10 show how to display the value of an
integer variable, array aggregate, and array element, respectively.
Figure 10–8 Displaying the Value of an Integer Variable
To display the current value in a different type or radix, use the following
alternative method:
1. Find and select the variable name in a window as explained in Section 10.5.1.
2. Choose Examine... in the Commands menu in the main window.
The Examine dialog box appears with the name selected in the
Variable/Expression field.
3. Choose the default, int, long, quad, short, or char* item from the Typecast
menu within the dialog box.
10–17
Using the Debugger
10.5 Examining and Manipulating Variables
Figure 10–9 Displaying the Value of an Array Aggregate
Figure 10–10 Displaying the Value of an Array Element
4. Choose the default, hex, octal, decimal, or binary item from the Output Radix
menu within the dialog box.
5. Click on OK.
The value, altered to your specification, appears in the command view.
Figure 10–11 shows that the variable j has been typecast as long.
10–18
Using the Debugger
10.5 Examining and Manipulating Variables
Figure 10–11 Typecasting the Value of a Variable
Figure 10–12 Changing the Value of a Variable
10.5.3 Changing the Current Value of a Variable
To change the current value of a variable:
•
Find and select the variable name in a window as explained in Section 10.5.1.
•
Choose Deposit... from the Commands menu in the main window. The
Deposit dialog box appears with the name selected in the Variable field.
•
Enter the new value in the Value field.
•
Choose the default, hex, octal, decimal, or binary item from the Input Radix
menu within the dialog box.
•
Click on OK.
The new value, altered to your specification, appears in the command view and is
assigned to the variable.
Figure 10–12 shows a new value for the variable safe.
10–19
Using the Debugger
10.5 Examining and Manipulating Variables
10.5.4 Monitoring a Variable
When you monitor a variable, 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).
Note
You can monitor only a variable, including an aggregate such as an array
or structure (record). You cannot monitor a composite expression or
memory address.
To monitor a variable (see Figure 10–13):
1. Find and select the variable name in a window as explained in Section 10.5.1.
2. Click on the MON button in the push button view. The debugger:
•
Displays the monitor view (if it is not displayed)
•
Puts the selected variable’s name, along with its qualifying path name, in
the Monitor Expression column
•
Puts the value of the variable in the Value/Deposit column
•
Puts a cleared button in the Watched column (see Section 10.5.5).
You can typecast the output value when monitoring variables by choosing the
Typecast item in the Monitor menu.
You can change the output radix when monitoring variables as follows:
•
Choose Change Radix in the Monitor menu to change the output radix for a
selected monitored element.
•
Choose the Change All Radix in the Monitor menu to change the output radix
for all subsequently monitored elements.
To remove a monitored element from the monitor view, choose Remove from the
Monitor menu.
10.5.4.1 Monitoring an Aggregate (Array or Structure) Variable
If you select the name of an aggregate variable, such as an array or structure
(record) and click on the MON 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 (or choose Expand in the Monitor menu).
The displayed element names are indented relative to the parent name (see
Figure 10–14). If an element is also an aggregate, you can double click on its
name to display its elements, and so on.
10–20
Using the Debugger
10.5 Examining and Manipulating Variables
Figure 10–13 Monitoring a Variable
Figure 10–14 Expanded Aggregate Variable (Array) in Monitor View
To collapse 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
(or choose Collapse from the Monitor menu).
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.
10–21
Using the Debugger
10.5 Examining and Manipulating Variables
10.5.4.2 Monitoring a Pointer (Access) Variable
If you select the name of a pointer (access) variable and click on the MON button,
the debugger displays the address of the referenced object in the
Value/Deposit column of the monitor view (see the top entry in Figure 10–15).
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, indented under the
pointer entry (see the bottom entry in Figure 10–15). If a referenced object is
an aggregate, you can double click on its name to display its elements, and so
on.
Figure 10–15 Pointer Variable and Referenced Object in Monitor View
10.5.5 Watching a Variable
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):
•
Monitor the variable as explained in Section 10.5.4. The debugger puts a
button in the Watched column of the monitor view whenever you monitor a
variable. See Figure 10–16.
•
Click on the button in the Watched column. A filled-in button indicates that
the watchpoint is set.
Figure 10–16 Watched Variable in Monitor View
To deactivate a watchpoint, clear its Watched button in the monitor view (by
clicking on the button) or choose Toggle Watchpoint in the Monitor menu. To
activate a watchpoint, fill in its Watched button or choose Toggle Watchpoint in
the Monitor menu.
10–22
Using the Debugger
10.5 Examining and Manipulating Variables
Section 10.6.1 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 automatically reactivate nonstatic watchpoints if execution
later returns to the variable’s defining routine. You must reactivate nonstatic
watchpoints explicitly.
10.5.6 Changing the Value of a Monitored Scalar Variable
To change the value of a scalar (nonaggregate) variable, such as an integer or
Boolean type (see Figure 10–17):
1. Monitor the variable as explained in Section 10.5.4.
2. Click on the variable’s value in the Value/Deposit column of the monitor view.
A small dialog box is displayed 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, indicating 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.
Figure 10–17 Changing the Value of a Monitored Scalar Variable
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 (see Figure 10–18):
1. Display the value of the component as explained in Section 10.5.4.1.
2. Click on the variable’s value in the Value/Deposit column of the monitor view.
A small dialog box is displayed 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, indicating 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.
10–23
Using the Debugger
10.5 Examining and Manipulating Variables
Figure 10–18 Changing the Value of a Component of an Aggregate Variable
10.6 Accessing Program Variables
This section provides some general information 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 (see Section 1.2.1).
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.
10.6.1 Accessing Static and Nonstatic (Automatic) Variables
Note
The generic term nonstatic variable is used here to denote what is called
an automatic variable in some languages.
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 (on the call stack). 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:
•
10–24
If you try to display the value of the variable or monitor the variable (as
explained in Section 10.5.2 and Section 10.5.4, respectively), the debugger
issues a message that the variable is not active or not in scope.
Using the Debugger
10.6 Accessing Program Variables
•
If the variable (or an expression that includes 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 as explained in Section 10.5.3. The
entry is fully displayed whenever the variable becomes accessible again.
•
If the variable is currently being watched (as explained in Section 10.5.5),
the watchpoint is deactivated (its Watched button is cleared) and its entry
is dimmed in the monitor view. However, note that the watchpoint is not
reactivated automatically when the variable becomes accessible again.
10.6.2 Setting the Current Scope Relative to the Call Stack
While debugging a routine in your program, you can 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 main window lists the names of the routines (and,
under certain conditions, the images and modules) of your program that are
currently active on the stack, up to the maximum number of lines that can be
displayed on your screen (see Figure 10–19). 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 the routine’s
name from the Call Stack menu (see Figure 10–19). 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 main window 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 (a call-stack level other than 0), the
debugger clears the current-location pointer, as shown in Figure 10–19.
•
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.
10–25
Using the Debugger
10.6 Accessing Program Variables
Figure 10–19 Current Scope Set to a Calling Routine
10.6.3 How the Debugger Searches for Variables and Other Symbols
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 automatically resolves symbol ambiguities. 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,
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:
10–26
•
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 main
window to reset the current scope (see Section 10.6.2).
•
Otherwise, enter the appropriate command at the command 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:
Using the Debugger
10.6 Accessing Program Variables
DBG> EXAMINE SWAP\X
10.7 Displaying and Modifying Values Stored in Registers
The register view displays the current contents of all machine registers (see
Figure 10–20).
To display the register view, choose Views... from the Options menu on the main
window or the optional views window, then click on Registers when the Views
dialog box appears.
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 (see Section 10.6.2).
To change the value stored in a register:
1. Click on the register value in the register view. A small dialog box is
displayed 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 debugger removes
the dialog box and displays the new value, indicating that the register now
contains that value. To dismiss the dialog box without changing the value in
the register, click on X (Cancel).
To change the radix used to display register values:
•
Choose Change Radix in the Register menu to change the radix in current
and subsequent output for a selected register.
•
Choose Change All Radix in the Register menu to change the radix in current
and subsequent output for all registers.
Figure 10–20 Register View
10–27
Using the Debugger
10.8 Displaying the Decoded Instruction Stream of Your Program
10.8 Displaying the Decoded Instruction Stream of Your Program
The instruction view displays the decoded instruction stream of your program:
the code that is actually executing (see Figure 10–21). This is useful if the
program you are debugging has been optimized by the compiler so that the
information in the main window does not exactly reflect the code that is executing
(see Section 1.2).
Figure 10–21 Instruction View
To display the instruction view, choose Views... from the Options menu on the
main window or the optional views window, then click on Instructions when the
Views dialog box appears.
By default, the instruction view automatically displays the decoded instruction
stream of the routine in which execution is currently paused. The currentlocation pointer, to the left of the instructions, marks the instruction that will
execute next.
By default, the debugger displays source code line numbers to the left of the
instructions with which they are associated. To hide or display line numbers,
toggle Display Line Numbers from the File menu in the instruction view.
By default, the debugger displays memory addresses to the left of the
instructions. To hide or display addresses, toggle Show Instruction Addresses
from the File menu in the instruction view.
After navigating the instruction view, click on the Call Stack menu to redisplay
the location at which execution is paused.
To display the instruction stream of any routine on the call stack, choose
the routine’s name from the Call Stack menu on the main window (see
Section 10.6.2).
10.9 Debugging Tasking (Multithread) Programs
Tasking programs, also called multithreaded programs, have multiple threads of
execution within a process and include the following:
10–28
•
Programs in any language that use HP POSIX Threads Library or POSIX
1003.1b services.
•
Programs that use language-specific tasking services (services provided
directly by the language). Currently, Ada is the only language with built-in
tasking services that the debugger supports.
Using the Debugger
10.9 Debugging Tasking (Multithread) Programs
Within the debugger, the term task or thread denotes such a flow of control,
regardless of the language or implementation. The debugger’s tasking support
applies to all such programs.
The debugger enables you to display task information and modify task
characteristics to control task execution, priority, state transitions, and so
on.
The following sections summarize the tasking features of the debugger’s HP
DECwindows Motif for OpenVMS user interface. For more information about the
debugger’s tasking support, see Chapter 16.
10.9.1 Displaying Information About Tasks (Threads)
To display information about one or more tasks (threads) of your program, choose
Views... from the Options menu on the main window or the optional views
window, then click on Threads when the Views dialog box appears.
The Threads view gives information about all currently existing (nonterminated)
tasks of your program. The information is updated whenever the debugger
regains control from the program, as shown in Figure 10–22.
Figure 10–22 Thread View
The displayed information includes:
•
The thread ID. The arrow in the left column marks the active task; i.e., the
thread that runs when you click on the Go or STEP button.
•
The thread priority.
•
Whether the task (thread) has been put on hold as explained in Section 10.9.2.
•
The current state of the task (thread). The task in the RUN (running) state
is the active task.
•
The current substate of the task (thread). The substate helps indicate the
possible cause of a task’s state.
•
A debugger path name for the task (thread) object or the address of the task
object if the debugger cannot symbolize the task object.
10–29
Using the Debugger
10.9 Debugging Tasking (Multithread) Programs
10.9.2 Changing Task (Threads) Characteristics
To modify a task’s (thread’s) characteristics or the tasking environment while
debugging, choose one of the following items from the Threads menu:
Threads Menu Item
Description
Abort
Request that the selected task (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
Make the selected task (thread) the active task.
Hold
Place the selected task (thread) on hold.
Nohold
Release the selected task (thread) from hold.
Make Visible
Make the selected task the visible task (thread).
All
Use the submenu to abort all tasks (threads) or release all
tasks (threads) from hold.
10.10 Customizing the Debugger’s HP DECwindows Motif for
OpenVMS Interface
The debugger is installed on your system with a default debugger resource
file (DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT) that defines the startup
defaults for the following customizable parameters:
•
Configuration of windows and views
•
Whether to show or hide line numbers in the main window
•
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 and
instruction view
•
Character fonts for text in the views
•
Character font for text displayed in specific windows and views
•
Color of the text foreground and background colors in the source view,
instruction view, and editor view
•
Display of program, module, and routine names in the main window title bar
•
Whether or not the debugger requires confirmation before exiting
A copy of the system default debugger resource file with explanatory comments is
included in Example 10–1 in Section 10.10.4.
You can modify the first three of these display attributes interactively from
the HP DECwindows Motif for OpenVMS user interface, as explained in
Section 10.10.1, Section 10.10.2, and Section 10.10.3. In each case, you can save
the modified display configuration for future debugging sessions by choosing Save
Options from the Options menu.
In addition, you can modify all the listed attributes of the debugger display
configuration by editing and saving the debugger resource file, as explained in
Section 10.10.4.
10–30
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
When you choose Save Options from the Options menu or you edit and save
the local debugger resource file, the debugger creates a new version of the
local debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT that
contains the definitions of the display configuration attributes. When you next
start the debugger, it uses the attributes defined in the most recent local resource
file to configure the output display. You can fall back to previous debugger display
configurations with appropriate use of the DCL commands DELETE, RENAME,
and COPY.
To fall back to the system default display configuration, select Restore Default
Options from the OpenVMS Debugger Options menu.
10.10.1 Defining the Startup Configuration of Debugger Views
To define the startup configuration of the debugger views:
1. While using the debugger, set up your preferred configuration of views.
2. Choose Save Options from the Options menu to create a new version of the
debugger resource file.
When you next start the debugger, the debugger uses the most recent resource
file to create the new display configuration.
You can also define the startup display configuration by editing the definition of
these views in the resource file (see Section 10.10.4).
10.10.2 Displaying or Hiding Line Numbers in Source View and Instruction
View
The source view and instruction view display source line numbers by default at
debugger startup. To hide (or display) line numbers at debugger startup:
1. While using the debugger, choose Display Line Numbers from the File menu
on the main window (or the instruction view). Line numbers are displayed
when a filled-in button appears next to that menu item.
2. Choose Save Options from the Options menu to create a new version of the
debugger’s local resource file.
When you next start the debugger, the debugger uses the most recent resource
file to create the new display configuration.
You can also set the startup default for line numbers by setting the following
resources to either True or False in the resource file (see Section 10.10.4).
DebugSource.StartupShowSourceLineno: True
DebugInstruction.StartupShowInstLineno: True
10–31
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
10.10.3 Modifying, Adding, Removing, and Resequencing Push Buttons
The buttons on the push button view are associated with debugger commands.
You can:
•
Change a button’s label or associated command
•
Add a new button
•
Remove a button
•
Resequence a button
Note
You cannot modify or remove the Stop button.
To save these modifications for future debugger sessions, choose Save Options
from the Options menu.
Section 10.10.3.1, Section 10.10.3.2, and Section 10.10.3.3 explain how to
customize push buttons interactively through the HP DECwindows Motif for
OpenVMS user interface. You can also customize push buttons by editing the
resource file. Button definitions in the resource file begin with:
DebugControl.Button
(See Example 10–1.)
10.10.3.1 Changing a Button’s Label or Associated Command
To change a button’s label or associated command:
1. Choose Customize Buttons... from the Options menu on the main window or
the optional views window. The Customize Buttons dialog box is displayed
(see Figure 10–23).
2. Within the dialog box, click on the button you are modifying. This fills the
Command and Label fields with the parameters for that button. The example
in Figure 10–23 shows that the STEP button was selected.
3. To change the button icon, pull down the Icon menu within the dialog box
and select one of the predefined icons. As Figure 10–23 shows, the Label field
dims and is filled with the debugger’s internal name for the predefined icon.
The icon itself appears in the dialog box’s push button display.
To change the button label, select None on the Icon menu and enter a new
label in the Label field.
4. To change the command associated with the button, enter the new command
in the Command field. For online help about the commands, see Section 8.4.3.
If the command is to operate on a name or language expression selected in
a window, specify %S as the command parameter. For example, the following
command displays the current value of the language expression that is
currently selected:
EVALUATE %s
10–32
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
If the command is to operate on a debugger built-in symbol or any other name
that has a percent sign ( % ) as the first character, specify two percent signs.
For example:
EXAMINE %%NEXTLOC
5. Click on Modify. The button’s label or associated command is changed within
the dialog box push button display.
6. Click on Apply. The button’s label or associated command is changed within
the debugger’s push button view.
To save these modifications for future debugger sessions, choose Save Options
from the Options menu.
Figure 10–23 Changing the STEP Button Label to an Icon
10.10.3.2 Adding a New Button and Associated Command
To add a new button to the push button view and assign a debugger command to
that button:
1. Choose Customize Buttons... from the Options menu. The Customize Buttons
dialog box is displayed (see Figure 10–24).
2. Enter the debugger command for the new button in the Command field
(see Section 10.10.3.1). Figure 10–24 shows the debugger command
run mydisk:[mydirectory]x.exe was entered.
3. Enter a label for that button in the Label field or choose a predefined icon
from the Icon menu. Figure 10–24 shows that the Run-X label was chosen.
4. Click on Add. The button is added to the dialog box push button display.
5. Click on Apply. The button is added to the debugger’s push button view.
To save these modifications for future debugger sessions, choose Save Options
from the Options menu.
10–33
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Figure 10–24 Adding a Button
10.10.3.3 Removing a Button
To remove a button:
1. Choose Customize Buttons... from the Options menu on the main or optional
views window. The Customize Buttons dialog box is displayed.
2. Within the dialog box, click on the button you are removing. This fills the
Command and Label fields with the parameters for that button.
3. Click on Remove. The button is removed from the dialog box push button
display.
4. Click on Apply. The button is removed from the debugger’s push button view.
To save these modifications for future debugger sessions, choose Save Options
from the Options menu.
10.10.3.4 Resequencing a Button
To resequence a button:
1. Choose Customize Buttons... from the Options menu on the main or optional
views window. The Customize Buttons dialog box is displayed.
2. Within the dialog box, click on the button you are resequencing. This fills the
Command and Label fields with the parameters for that button.
3. Click on the left or right arrow to move the button one position to the left or
right. Continue to click until the button has moved, one position at a time, to
its final position.
4. Click on Apply to transfer this position to the debugger’s push button view.
To save these modifications for future debugger sessions, choose Save Options
from the Options menu.
10–34
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
10.10.4 Editing the Debugger Resource File
The debugger is installed on your system with a default debugger resource
file (DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT) that defines the default
display configuration for the debugger. When you modify the display attributes as
described in Section 10.10 and then save the modifications with the Save Options
command in the Options menu, the debugger creates a local debugger resource
file, DECW$USER_DEFAULTS:VMSDEBUG.DAT. You can edit this file to further
modify the debugger display configuration.
If you do not have a local debugger resource file, you can create one with
the Restore Default Options item in the Options menu. Whenever you start
the debugger, it creates the debugger display configuration as defined in
the most recent version of the local debugger resource file if there is one;
otherwise, the debugger uses the definitions in the system debugger resource
file, DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT.
You cannot edit the system resource file. You can modify the debugger
display configuration either by following the procedures in Section 10.10.1,
Section 10.10.2, and Section 10.10.3, or by editing and saving your local debugger
resource file.
Example 10–1 contains a copy of the system default debugger resource file. Most
entries are annotated within the file or are self-explanatory. Section 10.10.4.1,
Section 10.10.4.2, Section 10.10.4.3, and Section 10.10.4.4 contain additional
information about modifying certain key sequences. For complete information
about specifying key sequences, see the translation table syntax in the X Toolkit
Intrinsics documentation.
Note
The line in Example 10–1 that begins with DebugControl.ButtonList
does not completely fit in this example. This line identifies the button
definitions contained in the file. The full line in the file also contains
the following button names: StepReturnButton, StepCallButton,
ExamineButton, ExamineASCIZButton, ExamineASCICButton,
EvalButton, MonitorButton.
10–35
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! OpenVMS Debug32/64 Debugger Resource File
!
DebugVersion: 71
!
! GEOMETRY RESOURCES:
!
! Written when you execute "SAVE OPTIONS" from the Options Menu.
!
DebugSource.x: 11
DebugSource.y: 30
DebugSource.width: 620
DebugSource.height: 700
!
DebugControl.x: 650
DebugControl.y: 30
DebugControl.width: 600
DebugControl.height: 700
!
DebugEditor.x: 650
DebugEditor.y: 30
DebugEditor.width: 600
DebugEditor.height: 700
!
DebugInstruction.x: 11
DebugInstruction.y: 769
DebugInstruction.width: 620
DebugInstruction.height: 243
!
*DebugBrowser.x: 650
*DebugBrowser.y: 30
*DebugBrowser.width: 335
*DebugBrowser.height: 300
!
! LINE NUMBER DISPLAY RESOURCES:
!
! Create the line or address number display in views at startup?
!
DebugSource.StartupShowSourceLineno: True
DebugInstruction.StartupShowInstLineno: True
DebugInstruction.StartupShowInstAddrno: False
!
! WINDOW PANE RESOURCES:
!
! Relative size of panes in main window.
! Main window height is derived from sum of panes.
!
DebugSource*SrcView.height: 460
DebugSource*PushbuttonPanel.height: 36
DebugSource*MessageOutputPanel.height: 145
!
DebugControl.BreakpointView.height: 175
DebugControl.MonitorView.height: 150
DebugControl.TaskView.height: 130
DebugControl.RegisterView.height: 250
(continued on next page)
10–36
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! CUSTOM BUTTON RESOURCES:
!
! The following resources determine which buttons to put in the button panel.
! Buttons will show in the order they are listed here.
! For each button there MUST be a set of associated resources.
! EXAMPLE:
! ButtonCommand
- Associates a command with the button.
! ButtonLegend
- Button Label or pixmap name if pixmap flag is True.
! ButtonPixmapFlag - If True uses ButtonLegend as predefined pixmap name.
!
DebugControl.ButtonList: \ GoButton, StepButton, StepInButton, ...
!
DebugControl.ButtonCommand.GoButton: go
DebugControl.ButtonLegend.GoButton: go_pixmap
DebugControl.ButtonPixmapFlag.GoButton: True
!
DebugControl.ButtonCommand.StepButton: step
DebugControl.ButtonLegend.StepButton: STEP
DebugControl.ButtonPixmapFlag.StepButton: False
!
DebugControl.ButtonCommand.StepInButton: step/in
DebugControl.ButtonLegend.StepInButton: S/in
DebugControl.ButtonPixmapFlag.StepInButton: False
!
DebugControl.ButtonCommand.StepReturnButton: step/return
DebugControl.ButtonLegend.StepReturnButton: S/ret
DebugControl.ButtonPixmapFlag.StepReturnButton: False
!
DebugControl.ButtonCommand.StepCallButton: step/call
DebugControl.ButtonLegend.StepCallButton: S/call
DebugControl.ButtonPixmapFlag.StepCallButton: False
!
DebugControl.ButtonCommand.ExamineButton: examine %s
DebugControl.ButtonLegend.ExamineButton: EX
DebugControl.ButtonPixmapFlag.ExamineButton: False
!
DebugControl.ButtonCommand.ExamineASCIZButton: examine/asciz %s
DebugControl.ButtonLegend.ExamineASCIZButton: E/az
DebugControl.ButtonPixmapFlag.ExamineASCIZButton: False
!
DebugControl.ButtonCommand.ExamineASCICButton: examine/ascic %s
DebugControl.ButtonLegend.ExamineASCICButton: E/ac
DebugControl.ButtonPixmapFlag.ExamineASCICButton: False
!
DebugControl.ButtonCommand.EvalButton: evaluate %s
DebugControl.ButtonLegend.EvalButton: EVAL
DebugControl.ButtonPixmapFlag.EvalButton: False
!
DebugControl.ButtonCommand.MonitorButton: monitor %s
DebugControl.ButtonLegend.MonitorButton: MON
DebugControl.ButtonPixmapFlag.MonitorButton: False
(continued on next page)
10–37
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! THE FOLLOWING RESOURCES CAN ONLY BE CHANGED BY EDITING THIS FILE.
! ----------------------------------------------------------------! Be sure to trim off any trailing white-spaces.
!
! FONT RESOURCES:
!
! If a font is specified for a view, and the font is available on the
! system, it will be used for that view.
!
! For any views which do not explicitly specify a font, the font specified
! by the resource "DebugDefault.Font" will be used if it is available on the
! system.
!
! If no font resources are specified at all, the debugger will use the
! systems own default font specification.
!
! The "DebugOptions.Font" applies to all optional views. We suggest that
! you select a font with a point size no larger than 14 in the option views
! in order to preserve label alignment.
!
! Using 132 column sources? Try this narrow font:
!
-dec-terminal-medium-r-narrow--14-100-100-100-c-60-iso8859-1
!
!
FORMAT: -*-FONTNAM-FACE-T-*--*-PTS-*-*-*-*-CHARSET
!
DebugDefault.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1
DebugSource.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1
DebugInstruction.Font: -*-COURIER-BOLD-R-*--*-140-*-*-*-*-ISO8859-1
DebugMessage.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1
DebugOptions.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1
!
! STARTUP RESOURCES: 3=Iconified, 0=Visible
!
DebugSource.initialState: 0
DebugControl.initialState: 0
DebugEditor.initialState: 0
DebugInstruction.initialState: 0
(continued on next page)
10–38
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! COLOR RESOURCES:
!
! Use any of the OSF Motif Named Colors.
!
! Foreground = Text Color, Background = Window Color
!
! Try: Gainsboro, MintCream, Linen, SeaShell, MistyRose, Honeydew
!
Cornsilk, Lavender
!
! To use your system default color scheme, comment out all lines
! pertaining to color.
!
! Common color scheme (unless overridden for a specific view)
!
*background:
Gainsboro
*borderColor:
Red
!
! Source View Colors
!
!DebugSource*background: Gainsboro
DebugSource*topShadowColor:
WindowTopshadow
DebugSource*bottomShadowColor:
WindowBottomshadow
DebugSource*src_txt.foreground: blue
DebugSource*src_txt.background: white
DebugSource*src_lineno_txtw.foreground: red
DebugSource*cnt_msg_txt.foreground: black
DebugSource*cnt_msg_txt.background: white
!
! Control View Colors
!
!DebugControl*background: Gainsboro
DebugControl*topShadowColor:
WindowTopshadow
DebugControl*bottomShadowColor:
WindowBottomshadow
!
! Instruction View Colors
!
!DebugInstruction*background: Gainsboro
DebugInstruction*topShadowColor:
WindowTopshadow
DebugInstruction*bottomShadowColor:
WindowBottomshadow
DebugInstruction*inst_txt.foreground: blue
DebugInstruction*inst_txt.background: white
DebugInstruction*inst_addrno_txtw.foreground: red
!
! Editor Colors
!
!DebugEditor*background: Gainsboro
DebugEditor*topShadowColor:
WindowTopshadow
DebugEditor*bottomShadowColor:
WindowBottomshadow
DebugEditor*edit_textw.foreground: black
DebugEditor*edit_textw.background: white
(continued on next page)
10–39
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! REGISTER VIEW RESOURCES:
!
! Which Registers to display by default in the Register View?
! CF = Call Frame, GP = General Purpose, FP = Floating Point (Integrity server and Alpha Only)
!
*Show_CF_Registers.set: True
*Show_GP_Registers.set: False
*Show_FP_Registers.set: False
!
! SHOW MESSAGE/COMMAND SEPARATOR LINES?
!
*Show_Message_Separators.set: True
!
! TRACK LANGUAGE CHANGES? (parser follows module language)
!
*Track_Language_Changes.set: False
!
! KEY SEQUENCE RESOURCES:
!
! Key sequence used to activate the dialog box for conditional and action
! breakpoints.
!
DebugSource.ModifyBreakpointToggleSequence: Ctrl <Btn1Down>, Ctrl <Btn1Up>
!
! GENERAL KEYPAD FUNCTIONS:
!
!<Key>0xFFB0=KP0, <Key>0xFF91,<Key>0xFFB0=GOLD-KP0,
!<Key>0xFF94,<Key>0xFFB0=BLUE-KP0, <Key>0xFFB1=KP1,
!<Key>0xFF91,<Key>0xFFB1=GOLD-KP1, <Key>0xFFAC=KP,
DebugSource.*XmText.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
!
! IDENTIFIER WORD SELECTION: (language-based delimiters)
! NOTE: DO NOT use any double click combination for the following resource
!
otherwise normal text selection in the source window will not work.
!
DebugSource.IdentifierSelectionSequence: Ctrl<Btn1Down>
!
! EXIT CONFIRMATION:
!
DebugDisplayExitConfirmDB: True
(continued on next page)
10–40
Using the Debugger
10.10 Customizing the Debugger’s HP DECwindows Motif for OpenVMS Interface
Example 10–1 (Cont.) System Default Debugger Resource File (DECW$SYSTEM_
DEFAULTS:VMSDEBUG.DAT)
!
! COMMAND ECHO:
!
DebugEchoCommands: True
!
! TITLE FORMAT: Main window and optional view window.
!
! The following title format directives are supported:
!
! %t - The title of the debugger application.
! %p - The name of the user program being debugged.
! %f - The name of the current file displayed in the source window.
!
DebugControl.TitleFormat: %t - %p: %f
!
! DRAG AND DROP MESSAGE SUPRESSION: (Dont mess with these)
!
*.dragInitiatorProtocolStyle: DRAG_NONE
*.dragReceiverProtocolStyle: DRAG_NONE
10.10.4.1 Defining the Key Sequence to Display the Breakpoint Dialog Box
By default, the key sequence for displaying the dialog box for conditional and
action breakpoints is Ctrl/MB1 (see Section 10.4.6 and Section 10.4.7). To define
another key sequence, edit the current definition of the following resource in the
resource file. For example:
DebugSource.ModifyBreakpointToggleSequence:
Ctrl<Btn1Down>(2)
10.10.4.2 Defining the Key Sequence for Language-Sensitive Text Selection
By default, the key sequence for language-sensitive text selection in the main
window and instruction view is Ctrl/MB1 (see Section 10.5.1). To define another
key sequence, edit the current definition of the following resource in the resource
file. For example:
DebugSource.IdentifierSelectionSequence: Ctrl<Btn1Down>
To avoid conflict with standard HP DECwindows Motif for OpenVMS word
selection, do not use a double-click combination, such as Ctrl<Btn1Down>(2).
10.10.4.3 Defining the Font for Displayed Text
To define another font for the text displayed in various debugger windows and
views, edit the current definition of the following resources in the resource file.
For example:
DebugDefault.Font: -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1
10.10.4.4 Defining the Key Bindings on the Keypad
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 resource file. For
example:
<literal>(<Key>)0xFFB0: EnterCmdOnCmdLine("step/line 3") \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.
10–41
Using the Debugger
10.11 Debugging Detached Processes
10.11 Debugging Detached Processes
You cannot use the HP DECwindows Motif for OpenVMS user interface to the
debugger to debug detached processes, such as print symbionts, which run
without a command line interpreter (CLI).
To debug a detached process that runs without a CLI, use the character-cell
(screen mode) interface to the debugger (see Section 1.11).
10–42
Part IV
PC Client Interface
This part introduces the debugger’s PC client interface.
For information about the debugger’s command interface, see Part II.
For information about the debugger’s Decwindows Motif interface, see Part III.
11
Using the Debugger PC Client/Server Interface
This chapter describes the PC client/server interface to the debugger.
Note
The OpenVMS Version 7.3 debugger does not support previous versions of
the PC client. You must install the Version 1.1 PC client that is found in
the kit on the OpenVMS Version 7.3 distribution media, as identified in
Section 11.2.
Version 1.1 PC client is compatible with OpenVMS Version 7.3 and prior
debugger servers.
11.1 Introduction
The debug server runs on OpenVMS systems. The client is the user interface
to the debugger, from which you enter debugger commands that are sent to the
server. The server executes the commands and sends the results to the client
for display. The client runs on Microsoft Windows 95, Windows 98, Windows NT,
Windows 2000, and Windows XP.
[DEBUG_CLIENTS011.KIT]DEBUGX86011.EXE
11.2 Installation of PC Client
There is no special installation procedure for the components that run on
OpenVMS. The system administrator must move the OpenVMS debug client kit
listed in the previous section from the OpenVMS distribution media to a place
accessible to PC users, such as a PATHWORKS share or an FTP server. The
client kit is a self-extracting .EXE file.
Once the appropriate executable file has been transferred to the PC, you can
run the file to install the debug client on the PC. The InstallShield installation
procedure guides you through the installation.
By default, the debug client is installed in the \Program Files\OpenVMS Debugger
folder. You can also click Browse to select an alternate location.
The installation creates an OpenVMS Debugger program folder that contains
shortcuts to the following items:
•
Debug client
•
Debug client Help file
•
README file
•
Uninstall procedure
11–1
Using the Debugger PC Client/Server Interface
11.3 Primary Clients and Secondary Clients
11.3 Primary Clients and Secondary Clients
The primary client is the first client to connect to the server. A secondary client
is an additional client that has connected to the same server. The primary client
controls whether or not any secondary clients can connect to the server.
See Section 11.5 for details about specifying the number of secondary clients
allowed to connect to a debugging session.
11.4 The PC Client Workspace
The PC client workspace is analogous to the workspace of the Motif client (see
Chapter 8). The client workspace contains views to display dynamic information
and toolbars to contain shortcuts to debugger commands. You can configure the
views and toolbars to suit your personal requirements, create your own shortcuts,
and save your personal configurations.
These topics are discussed at length in the PC client Help file. You can access
the PC client Help directly from the OpenVMS Debugger folder that you created
during PC client installation (see Section 11.2), or from the Help menu within the
client. See the following topics:
•
Overview
•
Getting Started
•
Views
•
Toolbars
11.5 Establishing a Server Connection
You can start the debug server after logging in directly to the OpenVMS system,
or you may find it more convenient to log in remotely with a product such as
eXcursion, or a terminal emulator such as Telnet.
Note
You must hold the DBG$ENABLE_SERVER identifier in the rights
database to be able to run the debug server. Exercise care when using the
debug server. Once a debug server is running, anyone on the network has
the ability to connect to the debug server.
Before granting the DBG$ENABLE_SERVER identifier, the system manager
must create it by entering the command DEBUG/SERVER from an account
with write access to the rights database. The system manager needs to do this
only once. The system manager can then run the Authorize utility to grant the
DBG$ENABLE_SERVER identifier to the user.
To start the debug server, enter the following command:
$ DEBUG/SERVER
The server displays its network binding strings. The server port number is
enclosed in square brackets ([ ]). For example:
11–2
Using the Debugger PC Client/Server Interface
11.5 Establishing a Server Connection
$ DEBUG/SERVER
%DEBUG-I-SPEAK:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-WATCH:
%DEBUG-I-AWAIT:
TCP/IP: YES, DECnet: YES, UDP: YES
Network Binding: ncacn_ip_tcp:16.32.16.138[1034]
Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001]
Network Binding: ncadg_ip_udp:16.32.16.138[1045]
Ready for client connection...
Use one of the network binding strings to identify this server when you connect
from the client (see Section 9.9.4).
Note
You can usually identify the server using only the node name and the port
number. For example, nodnam[1034].
To establish a connection from the PC client, invoke the Connection dialog, either
from the File pull-down menu, or by selecting the C/S button on the Main toolbar.
The dialog displays the servers already known to this client, and the sessions
currently active by this client.
You can specify a server for a new connection, or select a particular session for
use.
From the buttons at the bottom of the dialog, you can
•
Connect to the selected (or the default) server
•
Disconnect from a server
•
Test the client/server connection
•
Stop the selected server
In addition, the Advanced button allows you to select the network protocol to
be used (see Section 11.5.1), and to select the number of secondary clients (0-30)
allowed for the client/server connection to be established (see Section 11.5.2).
11.5.1 Choosing a Transport
From the Connection dialog, select the network protocol to be used for the
client/server connection from the following:
•
TCP/IP
•
DECnet
•
UDP
11.5.2 Secondary Connections
From the Connection dialog, you can enable up to 30 secondary clients to connect
to the server. You must be the primary client (the first client to connect to this
server), and perform the following steps:
1. On the Connection dialog, click Advanced.
2. Select the number of secondary clients (0-30) to be permitted.
3. Click Connect on the Connection dialog.
11–3
Using the Debugger PC Client/Server Interface
11.5 Establishing a Server Connection
The debugger dismisses the Connection dialog, makes the connection, and
indicates success (or failure) in the Command view. You can now begin your
debugging procedures.
11.6 Terminating a Server Connection
You can stop a server by entering Ctrl-Y on the node on which the server is
running. If you do so, then enter the DCL STOP command.
To stop the server from the client, perform the following steps:
1. Open the File pull-down menu.
2. Select Exit.
3. Click Server to stop only the server, or click Both to stop both the server and
the client.
An alternative way to stop the server is to perform the following steps:
1. Open the File pull-down menu.
2. Click Connection to invoke the Connection dialog.
3. Select the server connection from the Active Sessions list.
4. Click Stop.
11.6.1 Exiting Both Client and Server
To stop both the server and the client, perform the following steps:
1. Open the File pull-down menu.
2. Click Exit.
3. Click Both.
11.6.2 Exiting the Client Only
To stop only the client, perform the following steps:
1. Open the File pull-down menu.
2. Click Exit.
3. Click Client.
11.6.3 Stopping Only the Server
To stop only the server, perform the following steps:
1. Open the File pull-down menu.
2. Click Exit.
3. Click Server.
11–4
Using the Debugger PC Client/Server Interface
11.7 Documentation
11.7 Documentation
In addition to the PC client Help file, the OpenVMS Debugger Manual is online
in HTML format. To access the manual from within the client, do the following:
1. Open the Help pull-down menu.
2. Click Contents.
3. Click Local Manual.
11–5
Part V
Advanced Topics
This part describes advanced debugging techniques available in the OpenVMS
Debugger.
12
Using the Heap Analyzer
The Heap Analyzer, available on OpenVMS Integrity servers and Alpha systems,
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.
This chapter describes the following:
•
Starting a Heap Analyzer session (Section 12.1)
•
Working with the default display (Section 12.2)
•
Adjusting type determination and display (Section 12.3)
•
Exiting the Heap Analyzer (Section 12.4)
•
Sample session (Section 12.5)
12.1 Starting a Heap Analyzer Session
The following sections describe how to invoke the Heap Analyzer and run your
application.
12.1.1 Invoking the Heap Analyzer
You can invoke the Heap Analyzer during a debugging session in one of the
following ways:
1. In the debugger main window, choose Run Image or Rerun Same from the
File menu. When a dialog box appears, select the program you wish to
execute and click the Heap Analyzer toggle button.
2. At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER
or RERUN/HEAP_ANALYZER program-image command.
3. On Alpha systems: At the DCL prompt ( $ ) in a DECterm window outside the
debugger, enter the following command and then execute your program:
$ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
12–1
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
To use the heap analyzer with a protected image, enter the following
command and then execute your program:
$ DEFINE/EXEC/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
This is necessary if the image was installed with the following command:
$ INSTALL ADD imagename/PROTECTED
You can invoke the Heap Analyzer outside a debugging session by entering
the DEFINE/USER (or DEFINE/SYSTEM) command detailed above, and then
the DCL command RUN/NODEBUG.
4. On Integrity server systems, at the Debug prompt (DBG>), enter the START
HEAP_ANALYZER command.
Note
The Heap Analyzer startup and the Heap Analyzer START command on
the Integrity servers kept debugger (START HEAP_ANALYZER) hangs
for threaded applications with upcalls enabled.
In such instances, for threaded or AST-involved applications, HP strongly
recommends that you either start the Heap Analyzer before setting up
any debug events or after disabling or canceling the debug events. (You
can enable/reset events after the Heap Analyzer startup and START
returns you to debugger control.)
After you successfully invoke the Heap Analyzer, the Heap Analyzer startup
screen appears.
Note
On OpenVMS Alpha systems, the Heap Analyzer does not work on
programs linked with the /NODEBUG qualifier.
On OpenVMS Integrity server systems, the Heap Analyzer does work on
programs linked with the /NODEBUG qualifier, although the traceback
information displayed is minimal.
12.1.2 Viewing Heap Analyzer Windows
The Heap Analyzer contains a main window, six subsidiary windows, and a
control panel (see Figure 12–1.)
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.
12–2
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
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.
12–3
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
Figure 12–1 Heap Analyzer Windows
12–4
1. Memory Map
Shows the graphical representation of memory, that
is, the part of P0-space that is in use. Each allocation
appears as a colored strip, or segment.
2. Message Window
Displays Heap Analyzer informational and error
messages and one-line segment descriptions.
3. Information Window
Shows additional information on segments and
segment types that appear in the Memory Map.
4. Source Window
Shows application source code.
5. Do-not-use Type List
Lists routines not used as segment types, the name
that characterizes segments.
6. Views-and-Types Display
Lists all segment types known to the Heap Analyzer
and allows you to alter the segment display.
7. Push Button Control Panel
Provides Start/Step, Pause, Slow, and Sync buttons
that allow you to control the speed of Memory Map
display.
8. Type Histogram
Shows statistics on segment size and use.
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
12.1.3 Viewing Heap Analyzer Pull-Down Menus
The Heap Analyzer provides pull-down menus that are grouped over the Memory
Map (see Figure 12–2). This figure is adjusted slightly so that all menu items can
be seen.
Figure 12–2 Heap Analyzer Pull-Down Menus
1. File Menu
Allows you to exit from the Heap Analyzer
2. Display Menu
Allows you to adjust the Memory Map display and to clear the
Information window
3. Zoom Menu
Provides a closer or further view of the Memory Map
4. View Menu
Lets you select the granularity of the display
5. Options Menu
Allows you to indicate a search directory list or to adjust the Do-notuse Type List
6. Help Menu
Provides context-sensitive or task-oriented online help
12–5
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
12.1.4 Viewing Heap Analyzer Context-Sensitive Menus
Most operations in the Heap Analyzer, however, are accomplished through
context-sensitive pop-up menus. Most Heap Analyzer windows contain a pop-up
menu listing available tasks (see Figure 12–3). To access a window’s pop-up
menu, position your mouse pointer in the window and click MB3.
Figure 12–3 Heap Analyzer Context-Sensitive Pop-Up Menus
1. Memory Map Pop-Up
Provides additional information on segments
displayed in the Memory Map, allows you to
jump to a segment’s type in the Views-andTypes Display, or adds a segment’s type to the
Do-not-Use Type List.
2. Information Window Pop-Up
Allows you to jump from a line of traceback
displayed in the Information window to the
related source code in the Source window.
3. Do-not-use Type List Pop-Up
Deletes a segment’s type from the Do-not-Use
Type List.
4. Views-and-Types Display Pop-Up
Left side: Provides additional information on
segment types listed, highlights a segment type
within the Views-and-Types Display, or adds a
segment type to the Do-not-Use Type List.
Right side: Allows you to adjust display
characteristics for the segment type highlighted
in the left side of the Views-and-Types Display.
5. Type Histogram Pop-Up
12–6
Provides additional information on segment types
listed, highlights a segment type in the Type
Histogram, or adds the segment type to the
Do-not-Use Type List.
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
12.1.5 Setting a Source Directory
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 Set Source... 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
debugger SET SOURCE command.
For more information on this command, see the SET SOURCE command.
3. Click on OK.
The Heap Analyzer can now access your application.
12.1.6 Starting Your Application
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 Debugger main window
pops forward.
2. Click on the Go button in the 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 (see Section 12.1.7), 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.
12.1.7 Controlling the Speed of Display
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. Figure 12–4 shows these push buttons on the Heap Analyzer
window just after the Start button was pushed.
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 (not shown) 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.
12–7
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
Figure 12–4 Heap Analyzer Control Panel
1. Start Button
Click to start executing your application and enable the Memory Map
display. Once you do so, the Start button changes to a Step button,
which is initially dimmed (inaccessible).
2. Step Button
Click to single-step through memory events in the Memory Map
display. This button is dimmed until you click on the Pause button.
3. Pause Button
Click to stop (or restart) execution of your application and the dynamic
Memory Map display.
4. Slow Button
Click to slow the dynamic Memory Map display.
5. Sync Button
Click to force concurrent execution of your application program and
display of memory events in the Memory Map.
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.
On OpenVMS Alpha systems, anything that uses system service interception,
like the debugger or the Heap Analyzer, is unable to intercept system service call
images activated by shared linkage. The image activator, therefore, avoids shared
linkage for images linked or run with /DEBUG, and instead activates private
12–8
Using the Heap Analyzer
12.1 Starting a Heap Analyzer Session
image copies. This affects performance of applications under Heap Analyzer
control, as images activated by shared linkage run faster.
12.2 Working with the Default Display
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.
12.2.1 Memory Map Display
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.
12.2.2 Options for Memory Map Display
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.
Figure 12–5 shows the display options that appear in the Display pull-down
menu. The figure then lists all the display options available in the Memory Map.
12–9
Using the Heap Analyzer
12.2 Working with the Default Display
Figure 12–5 Heap Analyzer Display Menu and Zoom Menu
1. Display Menu
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 the display
is expanded.
Reduce Scroll Region: When you request a limited or partial
Memory Map display (see Section 12.3.3.2), compresses the display
so that you can see as many segments as possible without scrolling
to their location in the original display.
Display All Segments: Displays segment definitions for all
segments in the Memory Map.
Clear Information Window: Clears text and messages from the
Information window.
2. Zoom Menu
12–10
Options provide a closer or more distant view of the Memory Map.
Using the Heap Analyzer
12.2 Working with the Default Display
12.2.3 Options for Further Information
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
Section 12.3.3.2 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
Figure 12–6 shows the Memory Map context-sensitive pop-up menu. The figure
then lists all the mouse and pop-up menu item choices available in the Memory
Map.
12–11
Using the Heap Analyzer
12.2 Working with the Default Display
Figure 12–6 Heap Analyzer Memory Map Context-Sensitive Pop-Up Menu
1. Memory Map
Click MB1: Displays the segment definition in the Message window.
2. Map Pop-Up
Traceback of Allocation: Displays the traceback information associated
with a segment in the Information window (see Section 12.2.4).
Display Segment: Displays the segment definition in the Information
window.
Display Contents: Displays the segment definition and contents of each
address in the Information window.
Display Address: Displays the position (address) under your cursor and
the type of user access in the Information window.
Display Type: Displays the segment type definition in the Information
window.
Go to Type: Allows you to jump from a segment type listed in the Type
Histogram to the same segment type listed in the Views-and-Types
Display.
Do Not Use Type: Adds a segment type to the Do-not-use Type List.
12–12
Using the Heap Analyzer
12.2 Working with the Default Display
12.2.4 Requesting Traceback Information
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 call stack 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
12.2.5 Correlating Traceback Information with Source Code
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 Section 12.1.5 for information
on setting a search directory.
Figure 12–7 shows the source code that appears when you double click MB1 on
the traceback entry highlighted in the Information window. The figure then lists
all the mouse and menu item choices available for the Source and Information
windows.
12–13
Using the Heap Analyzer
12.2 Working with the Default Display
Figure 12–7 Heap Analyzer Information and Source Windows
12–14
1. Information Window
Double click MB1: Allows you to jump from a line of
traceback displayed in the Information window to the
related source code in the Source window.
2. Information Window Pop-Up
Go to Source: Allows you to jump from a line of
traceback displayed in the Information window to the
related source code in the Source window.
3. Display Menu
Clear Information window: Clears text and messages
from the Information window.
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
12.3 Adjusting Type Determination and Display
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)
•
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 Section 12.2.)
12.3.1 Options for Further Information
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.
Figure 12–8 shows the types listed in the Type Histogram. (This window has
been resized so all types appear.) The figure then lists all the mouse and menu
item choices available in the Type Histogram.
12–15
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
Figure 12–8 Heap Analyzer Type Histogram
1. Type Histogram
Click MB1: Displays the percentage of total segments
and the percentage of total bytes represented by a
segment.
2. Type Histogram Pop-Up
Display Type: Displays a type definition in the
Information window.
Go To Type: Allows you to jump from a segment type
listed in the Type Histogram to the same segment type
listed in the Views-and-Types Display.
Do Not Use Type: Adds a segment type to the Do-notuse Type List.
12–16
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
12.3.2 Altering Type Determination
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 call stack to find a routine
name that then serves as a segment type name.
The analyzer chooses the first routine name on the call stack 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 call stack 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 call stack is less applicationbound 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 call stack 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-notuse 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.
Figure 12–9 shows a LIBRTL\*\* entry in the Add to Do-not-use Type List
dialog box you can choose from the Options menu. The figure then lists all the
mouse and menu item choices available for the Do-not-Use Type List.
12–17
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
Figure 12–9 Heap Analyzer Do-Not-Use Type List
1. Do-not-use Type List Pop-Up
Use Type: Deletes a segment type from the Do-not-use
Type List.
2. Options Menu
Add to Do-not-use Type List: Adds a segment type to
the Do-not-use Type List.
Save Do-not-use Type List: Allows you to save the
segment types listed in your Do-not-use Type List
between Heap Analyzer sessions.
Restore Do-not-use Type List: Deletes additions to the
Do-not-use Type List since the list was last saved.
3. Memory Map Pop-Up,
Histogram Pop-Up,
Views-and-Types Display Pop-Up
12–18
Do Not Use Type: Adds a segment type to the Do-notuse Type List.
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
12.3.3 Altering the Views-and-Types Display
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).
12.3.3.1 Selecting the Scope of Your Change
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, Regions, 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.
Figure 12–10 shows the Block hierarchy item that is highlighted when you click
MB1 to choose all blocks. The figure then lists all the mouse and menu item
choices available in the hierarchy side of the Views-and-Types Display.
12–19
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
Figure 12–10 Heap Analyzer Views-and-Types Hierarchy
1. Double click MB1
Allows you to expand (or collapse) the Views-and-Types
hierarchy.
2. Views Hierarchy Pop-Up
Display Type: Displays a type definition in the
Information window.
Go to Type: Highlights the type you have selected in
the Views-and-Types Display.
Do Not Use Type: Adds a segment type to the Do-notuse Type List.
12–20
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
12.3.3.2 Choosing a Display Option
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 a 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. See Section 12.5 to see how this can be valuable
when you examine interactive commands.
To cancel a choice, click the Reset button, or choose the Reset menu item from the
Show, Expand, or Save pop-up menus.
Figure 12–11 shows the Show pop-up menu that appears when you click MB3 on
the options side of the Views-and-Types Display (the scope of your change, Blocks,
has been previously highlighted). The figure then lists the mouse and menu item
choices available in the options side of the Views-and-Types Display.
12–21
Using the Heap Analyzer
12.3 Adjusting Type Determination and Display
Figure 12–11 Heap Analyzer Views-and-Types Display Options
12–22
1. Click MB1
Toggles the Show, Expand, and Save toggle buttons.
2. Color Pop-Up
Controls the color display for individual types or groups of types.
3. Show Pop-Up
Controls the display of segment types you have chosen. Show and
Hide menu items allow you to restore or suppress display; Reset
cancels your choice.
4. Expand Pop-Up
Controls the display of segments within segment types you have
chosen. Expand and Collapse menu items allow you to restore or
suppress display; Reset cancels your choice.
5. Save Pop-Up
Controls the Heap Analyzer’s ability to show and store information
on the segment types you have selected. The Remove menu item
destroys all information; Save restores the ability to show and
store information; and Reset cancels your choice.
6. Apply Button
Applies your selections to the Memory Map display.
7. Reset Button
Cancels your selections.
Using the Heap Analyzer
12.4 Exiting the Heap Analyzer
12.4 Exiting the Heap Analyzer
To exit the Heap Analyzer, choose Exit from the File menu on the Heap Analyzer
screen.
12.5 Sample Session
This section contains an example that shows how to combine information from
Heap Analyzer windows and menus to locate a particular memory leak in your
application.
The example assumes that you have invoked the Heap Analyzer and run your
application. As you scroll back through the Memory Map display, you focus your
attention on segments that appear when your application calls for an interactive
command.
12.5.1 Isolating Display of Interactive Command
You suspect that the leak occurs when you enter an interactive SHOW UNITS
command, so your first step is to clear the Memory Map and reenter the
command.
To clear the Memory Map and reenter the command:
1. Click on Remove for the Views item within the Views-and-Types Display.
Then click on the Apply button.
The Heap Analyzer clears all previous output from the Memory Map.
2. Click on Save for the Views item. Then click on the Apply button.
The Heap Analyzer will save all subsequent output to the Memory Map.
3. In another DECterm window, at your application’s prompt, enter several
SHOW UNITS commands.
The Heap Analyzer shows a small series of segments that appear to be
incrementing, but the scale is too small for you to be sure.
4. Choose the Extremely Close menu item in the Zoom menu.
The Heap Analyzer provides a closer view of the segments.
The memory space allocated to each SCA_ _MEM_GET_VM segment is slightly
larger with each SHOW UNITS command (see Figure 12–12). This growth in
what should be a same-size allocation indicates a memory leak.
12–23
Using the Heap Analyzer
12.5 Sample Session
Figure 12–12 Incrementing Memory Allocation Indicates a Memory Leak
12.5.2 Adjusting Type Determination
The Heap Analyzer labels the segment type associated with your segments as
SCA_ _MEM_GET_VM. This is a fairly low-level memory management routine
that many segments might share. Your next step is to redefine the segment type
to a more meaningful level of abstraction, perhaps one corresponding to the name
of an application routine.
To redefine the segment type:
1. Position your mouse pointer over one of the segments, and click MB3.
The Heap Analyzer displays the Memory Map’s context-sensitive pop-up
menu.
2. Choose Do Not Use Type from the pop-up menu.
The segment type associated with your segment changes from SCA_ _MEM_
GET_VM to the more meaningful crl_begin_unit_query (see Figure 12–13).
12–24
Using the Heap Analyzer
12.5 Sample Session
Figure 12–13 The Do-Not-Use Type Menu Item Redefines Segment Type
12.5.3 Requesting Traceback Information
After you determine the level of abstraction at which you want to view your
segment, the next step is to examine the state of the call stack when the segment
was allocated. Reviewing the traceback associated with a segment can reveal
when and why it was created, and why a memory problem is occurring.
To request traceback information:
1. Position your mouse pointer over your segment, and click MB3.
The Heap Analyzer displays the Memory Map’s context-sensitive pop-up
menu.
2. Choose the Traceback of Allocation menu item from the pop-up menu.
Traceback information for your segment appears in the Information window.
12–25
Using the Heap Analyzer
12.5 Sample Session
12.5.4 Correlating Traceback with Source Code
The traceback for your segment indicates that the crl_begin_unit_query routine
sets up the environment for the SHOW UNITS command. To examine this event
further, you can request to see the source code associated with it.
To request source code, double click MB1 on the traceback line that refers to
crl_begin_unit_query.
Source code appears in the Source window. The routine call that placed crl_
begin_unit_query on the call stack is highlighted (see Figure 12–14).
Figure 12–14 The Click on Traceback Entry Shows Associated Source Code
12–26
Using the Heap Analyzer
12.5 Sample Session
12.5.5 Locating an Allocation Error in Source Code
After you connect a traceback entry to a routine in your application source code,
you can enlarge the Source window and search for allocation errors in that source
code location.
For example, the highlighted line 5725 in Figure 12–15 makes an allocation
to unit_query. This allocation is not deallocated before line 5740, where an
additional allocation occurs. This coding error is the cause of your memory
leak.
Figure 12–15 Review of Source Code Shows Double Allocation
12–27
13
Additional Convenience Features
This chapter describes the following debugger convenience features not described
elsewhere in this manual:
•
Using debugger command procedures
•
Using an initialization file for a debugging session
•
Logging a debugging session into a file
•
Defining symbols to represent commands, address expressions, or values
•
Assigning debugger commands to function keys
•
Using control structures to enter commands
•
Calling arbitrary routines linked with your program
13.1 Using Debugger Command Procedures
A debugger command procedure is a sequence of commands contained in a file.
You can direct the debugger to execute a command procedure 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. You can pass
parameters to command procedures.
As with DCL command procedures, you execute a debugger command procedure
by preceding its file specification with an at sign ( @ ). The @ is the execute
procedure command.
Debugger command procedures are especially useful when you regularly perform
a number of standard setup debugger commands, as specified in a debugger
initialization file (see Section 13.2). You can also use a debugger log file as a
command procedure (see Section 13.3).
13.1.1 Basic Conventions
The following is a sample debugger command procedure named BREAK7.COM:
! ***** Debugger Command Procedure BREAK7.COM *****
SET BREAK/AFTER:3 %LINE 120 DO (EXAMINE K,N,J,X(K); GO)
SET BREAK/AFTER:3 %LINE 160 DO (EXAMINE K,N,J,X(K),S; GO)
SET BREAK %LINE 90
When you execute this command procedure with the execute procedure ( @ )
command, the commands listed in the procedure are executed in the order they
appear.
The rules for entering commands in command procedures are listed in the
debugger’s online help (type HELP Command_Format).
You can pass parameters to a command procedure. See Section 13.1.2 for
conventions on passing parameters.
13–1
Additional Convenience Features
13.1 Using Debugger Command Procedures
You can enter the execute procedure (@) command like any other debugger
command: directly from the terminal, from within another command procedure,
from within a DO clause in a command such as SET BREAK, or from within a
DO clause in a screen display definition.
If you do not supply a full file specification with the execute procedure (@)
command, the debugger assumes SYS$DISK:[ ]DEBUG.COM as the default file
specification for command procedures. For example, enter the following command
line to execute command procedure BREAK7.COM, located in your current
default directory:
DBG> @BREAK7
The SET ATSIGN command enables you to change any or all fields of the default
file specification, SYS$DISK:[ ]DEBUG.COM. The SHOW ATSIGN command
identifies the default file specification for command procedures.
By default, commands read from a command procedure are not echoed. If you
enter the SET OUTPUT VERIFY command, all commands read from a command
procedure are echoed on the current output device, as specified by DBG$OUTPUT
(the default output device is SYS$OUTPUT). Use the SHOW OUTPUT command
to determine whether commands read from a command procedure are echoed or
not.
If the execution of a command in a command procedure results in a diagnostic
of severity warning or greater, the command is aborted but execution of the
command procedure continues at the next command line.
13.1.2 Passing Parameters to Command Procedures
As with DCL command procedures, you can pass parameters to debugger
command procedures. However, the technique is different in several respects.
Subject to the conventions described here, you can pass as many parameters as
you want to a debugger command procedure. The parameters can be address
expressions, commands, or value expressions in the current language. You must
surround command strings in quotation marks ( " ), and you must separate
parameters by commas ( , ).
A debugger command procedure to which you pass parameters must contain a
DECLARE command line that binds each actual (passed) parameter to a formal
parameter (a symbol) declared within the command procedure.
The DECLARE command is valid only within a command procedure. Its syntax
is as follows:
DECLARE p-name:p-kind[, p-name:p-kind[, . . . ]]
Each p-name:p-kind pair associates a formal parameter (p-name) with a
parameter kind (p-kind). The valid p-kind keywords are as follows:
ADDRESS
Causes the actual parameter to be interpreted as an address expression
COMMAND
Causes the actual parameter to be interpreted as a command
VALUE
Causes the actual parameter to be interpreted as a value expression in
the current language
The following example shows what happens when a parameter is passed to
a command procedure. The command DECLARE DBG:ADDRESS, within
command procedure EXAM.COM, declares the formal parameter DBG. The
actual parameter passed to EXAM.COM is interpreted as an address expression.
The command EXAMINE DBG displays the value of that address expression. The
13–2
Additional Convenience Features
13.1 Using Debugger Command Procedures
command SET OUTPUT VERIFY causes the commands to echo when they are
read by the debugger.
! ***** Debugger Command Procedure EXAM.COM *****
SET OUTPUT VERIFY
DECLARE DBG:ADDRESS
EXAMINE DBG
The next command line executes EXAM.COM by passing the actual parameter
ARR24. Within EXAM.COM, ARR24 is interpreted as an address expression (an
array variable, in this case).
DBG> @EXAM ARR24
%DEBUG-I-VERIFYIC, entering command procedure EXAM
DECLARE DBG:ADDRESS
EXAMINE DBG
PROG_8\ARR24
(1):
Mark A. Hopper
(2):
Rudy B. Hopper
(3):
Tim B. Hopper
(4):
Don C. Hopper
(5):
Mary D. Hopper
(6):
Jeff D. Hopper
(7):
Nancy G. Hopper
(8):
Barbara H. Hopper
(9):
Lon H. Hopper
(10):
Dave H. Hopper
(11):
Andy J. Hopper
(12):
Will K. Hopper
(13):
Art L. Hopper
(14):
Jack M. Hopper
(15):
Karen M. Hopper
(16):
Tracy M. Hopper
(17):
Wanfang M. Hopper
(18):
Jeff N. Hopper
(19):
Nancy O. Hopper
(20):
Mike R. Hopper
(21):
Rick T. Hopper
(22):
Dave W. Hopper
(23):
Jim W. Hopper
(24):
Robert Z. Hopper
%DEBUG-I-VERIFYIC, exiting command procedure EXAM
DBG>
Each p-name:p-kind pair specified by a DECLARE command binds one parameter.
For example, if you want to pass five parameters to a command procedure, you
need five corresponding p-name:p-kind pairs. The pairs are always processed in
the order in which you specify them.
For example, the next command procedure, EXAM_GO.COM, accepts two
parameters: an address expression (L) and a command string (M). The address
expression is then examined and the command is executed:
! ***** Debugger Command Procedure EXAM_GO.COM *****
DECLARE L:ADDRESS, M:COMMAND
EXAMINE L; M
The following example shows how you can execute EXAM_GO.COM by passing a
variable X to be examined and a command @DUMP.COM to be executed:
DBG> @EXAM_GO X, "@DUMP"
13–3
Additional Convenience Features
13.1 Using Debugger Command Procedures
The %PARCNT built-in symbol, which can be used only within a command
procedure, enables you to pass a variable number of parameters to a command
procedure. The value of %PARCNT is the number of actual parameters passed to
the command procedure.
The %PARCNT built-in symbol is shown in the following example. The command
procedure, VAR.DBG, contains the following lines:
! ***** Debugger Command Procedure VAR.DBG *****
SET OUTPUT VERIFY
! Display the number of parameters passed:
EVALUATE %PARCNT
! Loop as needed to bind all passed parameters and obtain their values:
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
The following command line executes VAR.DBG, passing the parameters 12, 37,
and 45:
DBG> @VAR.DBG 12,37,45
%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG
! Display the number of parameters passed:
EVALUATE %PARCNT
3
! Loop as needed to bind all passed parameters
! and get their values:
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
12
37
45
%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
DBG>
When VAR.DBG is executed, %PARCNT has the value 3. Therefore, the FOR
loop within VAR.DBG is repeated 3 times. The FOR loop causes the DECLARE
command to bind each of the three actual parameters (starting with 12) to a new
declaration of X. Each actual parameter is interpreted as a value expression in
the current language, and the EVALUATE X command displays that value.
13.2 Using a Debugger Initialization File
A debugger initialization file is a command procedure, assigned the logical name
DBG$INIT, that the debugger automatically executes at debugger startup. Every
time you start the debugger, the commands contained in the file are automatically
executed.
An initialization file contains any command lines you might always enter at
the start of a debugging session to either tailor your debugging environment or
control the execution of your program in a predetermined way from run to run.
For example, you might have a file DEBUG_START4.COM containing the
following commands:
13–4
Additional Convenience Features
13.2 Using a Debugger Initialization File
! ***** Debugger Initialization File DEBUG_START4.COM *****
! Log debugging session into default log file (SYS$DISK:[]DEBUG.LOG)
SET OUTPUT LOG
!
! Echo commands as they are read from command procedures:
SET OUTPUT VERIFY
!
! If source files are not in current default directory, use [SMITH.SHARE]
SET SOURCE [],[SMITH.SHARE]
!
! Invoke screen mode:
SET MODE SCREEN
!
! Define the symbol SB as the SET BREAK command:
DEFINE/COMMAND SB = "SET BREAK"
!
! Assign the SHOW MODULE * command to KP7:
DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *"
To make this file a debugger initialization file, use the DCL command DEFINE.
For example:
$ DEFINE DBG$INIT WORK:[JONES.DBGCOMFILES]DEBUG_START4.COM
13.3 Logging a Debugging Session into a File
A debugger log file maintains a history of a debugging session. During the
debugging session, each command entered and the resulting debugger output are
stored in the file. The following is an example of a debugger log file:
SHOW OUTPUT
!noverify, terminal, noscreen_log, logging to DSK2:[JONES.P7]DEBUG.LOG;1
SET STEP NOSOURCE
SET TRACE %LINE 30
SET BREAK %LINE 60
SHOW TRACE
!tracepoint at PROG4\%LINE 30
GO
!trace at PROG4\%LINE 30
!break at PROG4\%LINE 60
.
.
.
The DBG> prompt is not recorded, and the debugger output is commented out
with exclamation points so the file can be used as a debugger command procedure
without modification. Thus, if a lengthy debugging session is interrupted, you
can execute the log file as you would any other debugger command procedure.
Executing the log file restores the debugging session to the point at which it was
previously terminated.
To create a debugger log file, use the SET OUTPUT LOG command. By default,
the debugger writes the log to SYS$DISK:[ ]DEBUG.LOG. To name a debugger
log file, use the SET LOG command. You can override any field of the default file
specification. For example, after you enter the following commands, the debugger
logs the session to the file [JONES.WORK2]MONITOR.LOG:
DBG> SET LOG [JONES.WORK2]MONITOR
DBG> SET OUTPUT LOG
You might want to enter the SET OUTPUT LOG command in your debugger
initialization file (see Section 13.2).
13–5
Additional Convenience Features
13.3 Logging a Debugging Session into a File
The SHOW LOG command reports whether the debugger is writing to a log file
and identifies the current log file. The SHOW OUTPUT command identifies all
current output options.
If you are debugging in screen mode, the SET OUTPUT SCREEN_LOG command
enables you to log the screen contents as the screen is updated. To use this
command, you must already be logging your debugging session—that is, the
SET OUTPUT SCREEN_LOG command is valid only after you enter the
SET OUTPUT LOG command. Using SET OUTPUT SCREEN_LOG is not
desirable for a long debugging session, because storing screen information in this
manner results in a large log file. For other techniques on saving screen-mode
information, see the SAVE and EXTRACT command descriptions.
To use a log file as a command procedure, first enter the SET OUTPUT VERIFY
command so that debugger commands are echoed as they are read.
13.4 Defining Symbols for Commands, Address Expressions, and
Values
The DEFINE command enables you both to create a symbol for a lengthy or
often-repeated command sequence or address expression and to store the value of
a language expression in a symbol.
You specify the kind of symbol you want to define by the command qualifier you
use with the DEFINE command (/COMMAND, /ADDRESS, or /VALUE). The
default qualifier is /ADDRESS. If you plan to enter several DEFINE commands
with the same qualifier, you can first use the SET DEFINE command to establish
a new default qualifier (for example, SET DEFINE COMMAND makes the
DEFINE command behave like DEFINE/COMMAND). The SHOW DEFINE
command identifies the default qualifier currently in effect.
Use the SHOW SYMBOL/DEFINED command to identify symbols you have
defined with the DEFINE command. Note that the SHOW SYMBOL command
without the /DEFINED qualifier identifies only the symbols that are defined in
your program, such as the names of routines and variables.
Use the DELETE command to delete symbol definitions created with the DEFINE
command.
When defining a symbol within a command procedure, use the /LOCAL qualifier
to confine the symbol definition to that command procedure.
13.4.1 Defining Symbols for Commands
Use the DEFINE/COMMAND command to equate one or more command strings
to a shorter symbol. The basic syntax is shown in the following example:
DBG> DEFINE/COMMAND SB = "SET BREAK"
DBG> SB PARSER
In the example, the DEFINE/COMMAND command equates the symbol SB
to the string SET BREAK (note the use of the quotation marks to delimit the
command string). When the command line SB PARSER is executed, the debugger
substitutes the string SET BREAK for the symbol SB and then executes the SET
BREAK command.
13–6
Additional Convenience Features
13.4 Defining Symbols for Commands, Address Expressions, and Values
In the following example, the DEFINE/COMMAND command equates the symbol
BT to the string consisting of the SHOW BREAK command followed by the
SHOW TRACE command (use semicolons to separate multiple command strings):
DBG> DEFINE/COMMAND BT = "SHOW BREAK;SHOW TRACE"
The SHOW SYMBOL/DEFINED command identifies the symbol BT as follows:
DBG> SHOW SYM/DEFINED BT
defined BT
bound to: "SHOW BREAK;SHOW TRACE"
was defined /command
DBG>
To define complex commands, you might need to use command procedures with
parameters (see Section 13.1.2 for information about passing parameters to
command procedures). For example:
DBG> DEFINE/COMMAND DUMP = "@DUMP_PROG2.COM"
13.4.2 Defining Symbols for Address Expressions
Use the DEFINE/ADDRESS command to equate an address expression to a
symbol. /ADDRESS is the default qualifier for the DEFINE command, but it is
used in the following examples for emphasis.
In the following example, the symbol B1 is equated to the address of line 378; the
SET BREAK B1 command then sets a breakpoint on line 378:
DBG> DEFINE/ADDRESS B1 = %LINE 378
DBG> SET BREAK B1
The DEFINE/ADDRESS command is useful when you need to specify a long path
name repeatedly to reference the name of a variable or routine that is defined
multiple times. In the next example, the symbol UX is equated to the path name
SCREEN_IO\UPDATE\X; the abbreviated command line EXAMINE UX can
then be used to obtain the value of X in routine UPDATE of module SCREEN_IO:
DBG> DEFINE UX = SCREEN_IO\UPDATE\X
DBG> EXAMINE UX
13.4.3 Defining Symbols for Values
Use the DEFINE/VALUE command to equate the current value of a language
expression to a symbol (the current value is the value at the time the
DEFINE/VALUE command was entered).
The following example shows how you can use the DEFINE/VALUE command to
count the number of calls to a routine:
DBG>
DBG>
DBG>
.
.
.
DBG>
14
DBG>
DEFINE/VALUE COUNT = 0
SET TRACE/SILENT ROUT DO (DEFINE/VALUE COUNT = COUNT + 1)
GO
EVALUATE COUNT
13–7
Additional Convenience Features
13.4 Defining Symbols for Commands, Address Expressions, and Values
In the example, the first DEFINE/VALUE command initializes the value of the
symbol COUNT to 0. The SET TRACE command sets a silent tracepoint on
routine ROUT and (through the DO clause) increments the value of COUNT by 1
every time ROUT is called. After execution is resumed and eventually suspended,
the EVALUATE command obtains the current value of COUNT (the number of
times that ROUT was called).
13.5 Assigning Commands to Function Keys
To facilitate entering commonly used commands, the function keys on the keypad
have predefined debugger functions that are established when you start the
debugger. These predefined functions are identified in Appendix A and the
debugger’s online help (type HELP Keypad). You can modify the functions of the
keypad keys to suit your individual needs. If you have a VT200- or VT300-series
terminal or a workstation, you can also bind commands to the additional function
keys on the LK201 keyboard.
The debugger commands DEFINE/KEY, SHOW KEY, and DELETE/KEY enable
you to assign, identify, and delete key definitions, respectively. Before you can
use this feature, keypad mode must be enabled with the SET MODE KEYPAD
command (keypad mode is enabled by default). Keypad mode also enables you to
use the predefined functions of the keypad keys.
To use the keypad keys to enter numbers rather than debugger commands, enter
the SET MODE NOKEYPAD command.
13.5.1 Basic Conventions
The debugger DEFINE/KEY command, which is similar to the DCL command
DEFINE/KEY, enables you to assign a string to a function key. In the following
example, the DEFINE/KEY command defines KP7 (keypad key 7) to enter and
execute the SHOW MODULE * command:
DBG> DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *"
%DEBUG-I-DEFKEY, DEFAULT key KP7 has been defined
DBG>
You must use a valid key name (such as KP7) with the commands DEFINE/KEY,
SHOW KEY, and DELETE/KEY. See the DEFINE/KEY command for the valid
key names that you can use with these commands for VT52 and VT100-series
terminals and for LK201 keyboards.
In the previous example, the /TERMINATE qualifier indicates that pressing KP7
executes the command. You do not have to press Return after pressing KP7.
You can assign any number of definitions to the same function key as long as each
definition is associated with a different state. The predefined states (DEFAULT,
GOLD, BLUE, and so on) are identified in Appendix A and the debugger’s online
help (type HELP Keypad). In the preceding example, the informational message
indicates that KP7 has been defined for the DEFAULT state (which is the default
key state).
You can enter key definitions in a debugger initialization file (see Section 13.2) so
that these definitions are available whenever you start the debugger.
To display a key definition in the current state, enter the SHOW KEY command.
For example:
13–8
Additional Convenience Features
13.5 Assigning Commands to Function Keys
DBG> SHOW KEY KP7
DEFAULT keypad definitions:
KP7 = "SHOW MODULE *" (echo,terminate,nolock)
DBG>
To display a key definition in a state other than the current state, specify that
state with the /STATE qualifier when entering the SHOW KEY command. To see
all key definitions in the current state, enter the SHOW KEY/ALL command.
To delete a key definition, use the DELETE/KEY command. To delete a key
definition in a state other than the current state, specify that state with the
/STATE qualifier. For example:
DBG> DELETE/KEY/STATE=GOLD KP7
%DEBUG-I-DELKEY, GOLD key KP7 has been deleted
DBG>
13.5.2 Advanced Techniques
This section shows more advanced techniques for defining keys, particularly
techniques related to the use of state keys.
The following command line assigns the unterminated command string "SET
BREAK %LINE" to KP9, for the BLUE state:
DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE"
The predefined DEFAULT key state is established by default. The predefined
BLUE key state is established by pressing the PF4 key. Enter the command
line assigned in the preceding example (SET BREAK %LINE . . . ) by pressing
PF4, pressing KP9, entering a line number, and then pressing the Return key to
terminate and process the command line.
The SET KEY command enables you to change the default state for key
definitions. For example, after entering the SET KEY/STATE=BLUE command,
you do not need to press PF4 to enter the command line in the previous example.
Also, the SHOW KEY command will show key definitions in the BLUE state, by
default, and the DELETE/KEY command will delete key definitions in the BLUE
state by default.
You can create additional key states. For example:
DBG> SET KEY/STATE=DEFAULT
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 ""
In this example, the SET KEY command establishes DEFAULT as the current
state. The DEFINE/KEY command makes F12 (LK201 keyboard) a state key. As
a result, pressing F12 while in the DEFAULT state causes the current state to
become RED. The key definition is not terminated and has no other effect (a null
string is assigned to F12). After pressing F12, you can enter RED commands by
pressing keys that have definitions associated with the RED state.
13.6 Using Control Structures to Enter Commands
The FOR, IF, REPEAT, and WHILE commands enable you to create looping and
conditional constructs for entering debugger commands. The associated command
EXITLOOP is used to exit a FOR, REPEAT, or WHILE loop. The following
sections describe these commands.
See Section 4.1.6 and Section 14.3.2.2 for information about evaluating language
expressions.
13–9
Additional Convenience Features
13.6 Using Control Structures to Enter Commands
13.6.1 FOR Command
The FOR command executes a sequence of commands while incrementing a
variable a specified number of times. It has the following syntax:
FOR name=expression1 TO expression2 [BY expression3] DO(command[; . . . ])
For example, the following command line sets up a loop that initializes the first
10 elements of an array to 0:
DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0)
13.6.2 IF Command
The IF command executes a sequence of commands if a language expression
(Boolean expression) is evaluated as true. It has the following syntax:
IF boolean-expression THEN (command[; . . . ]) [ELSE (command[; . . . ])]
The following Fortran example sets up a condition that issues the command
EXAMINE X2 if X1 is not equal to 09.9, and issues the command EXAMINE Y1
otherwise:
DBG> IF X1 .NE. -9.9 THEN (EXAMINE X2) ELSE (EXAMINE Y1)
The following Pascal example combines a FOR loop and a condition test. The
STEP command is issued if X1 is not equal to 09.9. The test is made four times:
DBG> FOR COUNT = 1 TO 4 DO (IF X1 <> -9.9 THEN (STEP))
13.6.3 REPEAT Command
The REPEAT command executes a sequence of commands a specified number of
times. It has the following syntax:
REPEAT language-expression DO (command[; . . . ])
For example, the following command line sets up a loop that issues a sequence of
two commands (EXAMINE Y then STEP) 10 times:
DBG> REPEAT 10 DO (EXAMINE Y; STEP)
13.6.4 WHILE Command
The WHILE command executes a sequence of commands while the language
expression (Boolean expression) you have specified evaluates as true. It has the
following syntax:
WHILE boolean-expression DO (command[; . . . ])
The following Pascal example sets up a loop that repetitively tests X1 and X2 and
issues the two commands EXAMINE X2 and STEP if X2 is less than X1:
DBG> WHILE X2 < X1 DO (EX X2;STEP)
13.6.5 EXITLOOP Command
The EXITLOOP command exits one or more enclosing FOR, REPEAT, or WHILE
loops. It has the following syntax:
EXITLOOP [integer]
The integer n specifies the number of nested loops to exit from.
13–10
Additional Convenience Features
13.6 Using Control Structures to Enter Commands
The following Pascal example sets up an endless loop that issues a STEP
command with each iteration. After each step, the value of X is tested. If X is
greater than 3, the EXITLOOP command terminates the loop.
DBG> WHILE TRUE DO (STEP; IF X > 3 THEN EXITLOOP)
13.7 Calling Routines Independently of Program Execution
The CALL command enables you to execute a routine independently of the
normal execution of your program. It is one of the four debugger commands that
you can use to execute your program (the others are GO, STEP, and EXIT).
The CALL command executes a routine whether or not your program actually
includes a call to that routine, as long as the routine was linked with your
program. Thus, you can use the CALL command to execute routines for
any purpose (for example, to debug a routine out of the context of program
execution, call a run-time library procedure, call a routine that dumps debugging
information, and so on).
You can debug unrelated routines by linking them with a dummy main program
that has a transfer address, and then using the CALL command to execute them.
The following example shows how you can use the CALL command to display
some process statistics without having to include the necessary code in your
program. The example consists of calls to run-time library routines that initialize
a timer (LIB$INIT_TIMER) and display the elapsed time and various statistics
(LIB$SHOW_TIMER). (Note that the presence of the debugger affects the timings
and counts.)
DBG> SET MODULE SHARE$LIBRTL !
DBG> CALL LIB$INIT_TIMER "
value returned is 1 #
DBG> [ enter various debugger commands ]
.
.
.
DBG> CALL LIB$SHOW_TIMER $
ELAPSED: 0 00:00:21.65 CPU: 0:14:00.21 BUFIO: 16 DIRIO: 0 FAULTS: 3
value returned is 1
DBG>
The comments that follow refer to the callouts in the previous example:
! The routines LIB$INIT_TIMER and LIB$SHOW_TIMER are in the shareable
image LIBRTL. This image must be set by setting its module, because
only its universal symbols are accessible during a debugging session (see
Section 5.4.2.3).
" This CALL command executes the routine LIB$INIT_TIMER.
# The value returned message indicates the value returned in register R0 after
the CALL command has been executed.
By convention, after a called routine has executed, register R0 contains the
function return value (if the routine is a function) or the procedure completion
status (if the routine is a procedure that returns a status value). If a called
procedure does not return a status value or function value, the value in R0
might be meaningless, and the value returned message can be ignored.
$ This CALL command executes the routine LIB$SHOW_TIMER.
13–11
Additional Convenience Features
13.7 Calling Routines Independently of Program Execution
The following example shows how to call LIB$SHOW_VM (also in LIBRTL) to
display memory statistics. Again, note that the presence of the debugger affects
the counts.
DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM,
122216 bytes still allocated value returned is 1
DBG>
You can pass parameters to routines with the CALL command. See the CALL
command description for details and examples.
13–12
14
Debugging Special Cases
This chapter presents debugging techniques for special cases that are not covered
elsewhere in this manual:
•
Optimized code
•
Screen-oriented programs
•
Multilanguage programs
•
Stack corruption
•
Exceptions and condition handlers
•
Exit handlers
•
AST-driven programs
•
Translated images
14.1 Debugging Optimized Code
By default, many compilers optimize the code they produce so that the program
executes faster. With optimization, invariant expressions are removed from DO
loops so that they are evaluated only once at run time; some memory locations
might be allocated to different variables at different points in the program, and
some variables might be eliminated so that you no longer have access to them
while debugging.
The net result is that the code that is executing as you debug might not match
the source code displayed in a screen-mode source display (see Section 7.4.1) or in
a source listing file.
To avoid the problems of debugging optimized code, many compilers allow you
to specify the /NOOPTIMIZE (or equivalent) command qualifier at compile
time. Specifying this qualifier inhibits most compiler optimization and thereby
reduces discrepancies between the source code and executable code caused by
optimization.
If this option is not available to you, or if you have a definite need to debug
optimized code, read this section. It describes the techniques for debugging
optimized code and gives some typical examples of optimized code to show the
potential causes of confusion. It also describes some features you can use to
reduce the confusion inherent in debugging optimized code.
In order to take advantage of the features that improve the ability to debug
optimized code, you need an up-to-date version of your language compiler. For
definitive information about the necessary version of your compiler, please see
your compiler release notes or other compiler documentation.
Note that about one-third more disk space is needed for debugging optimized
code, to accommodate the increased image size.
14–1
Debugging Special Cases
14.1 Debugging Optimized Code
When debugging optimized code, use a screen-mode instruction display, such
as the predefined display INST, to show the decoded instruction stream of your
program (see Section 7.4.4). An instruction display shows the exact code that is
executing.
In screen mode, pressing KP7 places the SRC and INST displays side by
side for easy comparison. Alternatively, you can inspect a compiler-generated
machine-code listing.
In addition, to execute the program at the instruction level and examine
instructions, use the techniques described in Section 4.3.
Using these methods, you should be able to determine what is happening at
the executable code level and be able to resolve the discrepancy between source
display and program behavior.
14.1.1 Eliminated Variables
A compiler might optimize code by eliminating variables, either permanently
or temporarily at various points during execution. For example, if you try to
examine a variable X that no longer is accessible because of optimization, the
debugger might display one of the following messages:
%DEBUG-W-UNALLOCATED, entity X was not allocated in memory
(was optimized away)
%DEBUG-W-NOVALATPC, entity X does not have a value at the
current PC
The following Pascal example shows how this could happen:
PROGRAM DOC(OUTPUT);
VAR
X,Y: INTEGER;
BEGIN
X := 5;
Y := 2;
WRITELN(X*Y);
END.
If you compile this program with the /NOOPTIMIZE (or equivalent) qualifier, you
obtain the following (normal) behavior when debugging:
14–2
Debugging Special Cases
14.1 Debugging Optimized Code
$ PASCAL/DEBUG/NOOPTIMIZE DOC
$ LINK/DEBUG DOC
$ DEBUG/KEEP
.
.
.
DBG> RUN DOC
.
.
.
DBG> STEP
stepped to DOC\%LINE 5
5:
X := 5;
DBG> STEP
stepped to DOC\%LINE 6
6:
Y := 2;
DBG> STEP
stepped to DOC\%LINE 7
7:
WRITELN(X*Y);
DBG> EXAMINE X,Y
DOC\X: 5
DOC\Y: 2
DBG>
If you compile the program with the /OPTIMIZE (or equivalent) qualifier, because
the values of X and Y are not changed after the initial assignment, the compiler
calculates X*Y, stores that value (10), and does not allocate storage for X or Y.
Therefore, after you start debugging, a STEP command takes you directly to line
7 rather than line 5. Moreover, you cannot examine X or Y:
$ PASCAL/DEBUG/OPTIMIZE DOC
$ LINK/DEBUG DOC
$ DEBUG/KEEP
.
.
.
DBG> RUN DOC
.
.
.
DBG> EXAMINE X,Y
%DEBUG-W-UNALLOCATED, entity X was not allocated in memory
(was optimized away)
DBG> STEP
stepped to DOC\%LINE 7
7:
WRITELN(X*Y);
DBG>
In contrast, the following lines show the unoptimized code at the WRITELN
statement:
DBG> STEP
stepped to DOC\%LINE 7
7:
WRITELN(X*Y);
DBG> EXAMINE/OPERAND .%PC
DOC\%LINE 7:
MOVL
S^#10,B^-4(FP)
B^-4(FP) 2146279292 contains 62914576
DBG>
14–3
Debugging Special Cases
14.1 Debugging Optimized Code
14.1.2 Changes in Coding Order
Several methods of optimizing consist of performing operations in a sequence
different from the sequence specified in the source code. Sometimes code is
eliminated altogether.
As a result, the source code displayed by the debugger does not correspond exactly
to the actual code being executed.
The following example depicts a segment of source code from a Fortran program
as it might appear on a compiler listing or in a screen-mode source display. This
code segment sets the first ten elements of array A to the value 1/X.
Line
---5
6
7
Source Code
----------DO 100 I=1,10
A(I) = 1/X
100 CONTINUE
Optimization may produce the following scenario: As the compiler processes the
source program, it determines that the reciprocal of X need only be computed
once, not 10 times as the source code specifies, because the value of X never
changes in the DO loop. The compiler thus may generate optimized code
equivalent to the following code segment:
Line
---5
6
7
Optimized Code Equivalent
------------------------TEMP = 1/X
DO 100 I=1,10
A(I) = TEMP
100 CONTINUE
Depending on the compiler implementation, the moved code may be associated
with the first line of the loop or may retain its original line number (common on
Alpha systems).
If a discrepancy occurs, it is not obvious from looking at the displayed source
line. Furthermore, if the computation of 1/X were to fail because X is 0, it would
appear from inspecting the source display that a division by 0 had occurred on a
source line that contains no division at all.
This kind of apparent mismatch between source code and executable code should
be expected from time to time when you debug optimized programs. It can be
caused not only by code motions out of loops, as in the previous example, but by a
number of other optimization methods as well.
14.1.3 Semantic Stepping (Alpha Only)
Semantic stepping (available only on Alpha systems) makes stepping through
optimized code less confusing. The semantic-stepping mode complements the
traditional step-by-line and step-by-instruction modes. There are two commands
for semantic stepping: SET STEP SEMANTIC_EVENT and STEP/SEMANTIC_
EVENT.
Semantic Events
One problem of stepping through optimized code is that the apparent source
program location "bounces" back and forth with the same line often appearing
again and again. Indeed, sometimes the forward progress in STEP LINE mode
averages barely more than one instruction per STEP command.
14–4
Debugging Special Cases
14.1 Debugging Optimized Code
This problem is addressed through annotating instructions that are semantic
events. Semantic events are important for two reasons:
•
They represent the points in the program where the effects of the program
actually happen.
•
These effects tend to happen in an order that remains close to the source
order of events in the program.
A semantic event is one of the following:
•
Data event — An assignment to a user variable
•
Control event — A control flow decision, with a conditional or unconditional
transfer of control, other than a call
•
Call event — A call (to a routine that is not stepped over) or a return from a
call
It is important to understand that not every assignment, transfer of control, or
call is necessarily a semantic event. The major exceptions are as follows:
•
When two instructions are required to assign to a complex or X_floating value,
only the first instruction is treated as a semantic event.
•
When there are multiple branches that are part of a single higher-level
construct, such as a decision tree of branches that implement a case or select
construct, then only the first is treated as a semantic event.
•
When a call is made to a routine that is a compiler-specific helper routine,
such as a call to OTS$MOVE, which handles certain kinds of string or storage
copy operations, the call is not considered a semantic event. This means that
control will not stop at the call.
To step into such a routine, you must do either of the following:
Set a breakpoint at the routine entry point
Use a series of STEP/INSTRUCTION commands to reach the call of
interest and then use STEP/INSTRUCTION/INTO to enter the called
routine.
•
When there is more than one semantic event in a row with the same line
number, then only the first is used.
SET STEP SEMANTIC_EVENT Command
The SET STEP SEMANTIC_EVENT command establishes the default stepping
mode as semantic.
STEP/SEMANTIC_EVENT Command
STEP/SEMANTIC_EVENT, or simply STEP when semantic mode is in effect,
causes a breakpoint to be set at the next semantic event, whether an assignment,
a transfer of control, or a call. Execution proceeds to that next event. Parts of
any number of different lines/statements may be executed along the way without
interfering with progress. When the semantic event is reached (that is, when the
instruction associated with that event is reached but not yet executed), execution
is suspended (similar to reaching the next line when STEP/LINE is used).
14–5
Debugging Special Cases
14.1 Debugging Optimized Code
Example of Semantic Stepping
The comments in the following C program, doct2, point out some considerations
for optimization:
#include <stdio.h>
#include <stdlib.h>
int main(unsigned argc, char **argv) {
int w, x, y, z=0;
x = atoi(argv[1]);
printf("%d\n", x);
x = 5;
y = x;
if (y > 2) {
printf("y > 2");
}
else {
printf("y <= 2");
}
/* always true */
if (z) {
printf("z");
}
else {
printf("not z");
}
/* always false */
printf("\n");
}
Contrast the following two examples, which show stepping by line and stepping
by semantic event through the optimized doct2 program:
•
Stepping by line:
$ doct2:=$sys$disk:[]doct2
$ doct2 6
Debugger Banner and Version Number
Language:: Module: Doct2: GO to reach DBG> go
break at routine DOCT2\main
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 651
651: int main(unsigned argc, char **argv) {
DBG> step
stepped to DOCT2\main\%LINE 654
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 651
651: int main(unsigned argc, char **argv) {
DBG> step
stepped to DOCT2\main\%LINE 654
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 655
655:
printf("%d\n", x);
DBG> step
stepped to DOCT2\main\%LINE 654
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 655
655:
printf("%d\n", x);
DBG> step
14–6
Debugging Special Cases
14.1 Debugging Optimized Code
6
stepped to DOCT2\main\%LINE 661
661:
printf("y > 2");
DBG> step
y > 2
stepped to DOCT2\main\%LINE 671
671:
printf("not z");
DBG> step
not z
stepped to DOCT2\main\%LINE 674
674:
printf("\n");
DBG> step
stepped to DOCT2\main\%LINE 675
675:
}
DBG> step
’Normal successful completion’
DBG>
•
Stepping by semantic event:
$ doct2:=$sys$disk:[]doct2
$ doct2 6
Debugger Banner and Version Number
Language:: Module: Doct2: GO to reach DBG> set step semantic_event
DBG> go
break at routine DOCT2\main
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 654+8
654:
x = atoi(argv[1]);
DBG> step
stepped to DOCT2\main\%LINE 655+12
655:
printf("%d\n", x);
DBG> step
6
stepped to DOCT2\main\%LINE 661+16
661:
printf("y > 2");
DBG> step
y > 2
stepped to DOCT2\main\%LINE 671+16
671:
printf("not z");
DBG> step
not z
stepped to DOCT2\main\%LINE 674+16
674:
printf("\n");
DBG> step
stepped to DOCT2\main\%LINE 675+24
675:
}
DBG> step
stepped to DOCT2\__main+104
DBG> step
’Normal successful completion’
DBG>
Notice that the semantic stepping behavior is much smoother and more
straightforward than the stepping-by-line example. Further, semantic stepping
results in stopping at significant points of the program. In general, semantic
stepping significantly reduces or eliminates the confusion of "bouncing" around
the code nonsequentially, which characteristically happens with stepping by line
through optimized code. Although some reordering of the source program may be
done to take advantage of better execution characteristics, generally the flow is
from top to bottom.
14–7
Debugging Special Cases
14.1 Debugging Optimized Code
The granularity of stepping is different between stepping by line and stepping
semantically. Sometimes it is greater, sometimes smaller. For example, a
statement that would by its semantic nature constitute a semantic event will
not show up with semantic stepping if it has been optimized away. Thus, the
semantic region will span across several lines, skipping the line that has been
optimized away.
14.1.4 Use of Registers
A compiler might determine that the value of an expression does not change
between two given occurrences and might save the value in a register. In such
cases, the compiler does not recompute the value for the next occurrence, but
assumes the value saved in the register is valid.
If, while debugging a program, you use the DEPOSIT command to change the
value of the variable in the expression, the corresponding value stored in the
register might not be changed. Thus, when execution continues, the value in the
register might be used instead of the changed value in the expression, which will
cause unexpected results.
In addition, when the value of a nonstatic variable (see Section 3.4.3) is held in
a register, its value in memory is generally invalid; therefore, a spurious value
might be displayed if you enter the EXAMINE command for a variable under
these circumstances.
14.1.5 Split-Lifetime Variables
In compiling with optimization, the compiler sometimes performs split-lifetime
analysis on a variable, "splitting" it into several independent subvariables that
can be independently allocated. The effect is that the original variable can be
thought to reside in different locations at different points in time — sometimes in
a register, sometimes in memory, and sometimes nowhere. It is even possible for
the different subvariables to be simultaneously active.
On Alpha processors, in response to the EXAMINE command, the debugger
tells you at which locations in the program the variable was defined. When
the variable has an inappropriate value, this location information can help you
determine where the value of the variable was assigned. (The /DEFINITIONS
qualifier enables you to specify more or fewer than the default five locations.)
Split-lifetime analysis applies only to scalar variables and parameters. It does
not apply to arrays, records, structures, or other aggregates.
Examples of Split-Lifetime Processing
The following examples illustrate the use of split-lifetime processing. For the
first example, a small C program, the numbers in the left column are listing line
numbers.
14–8
Debugging Special Cases
14.1 Debugging Optimized Code
385 doct8 () {
386
387
int i, j, k;
388
389
i = 1;
390
j = 2;
391
k = 3;
392
393
if (foo(i)) {
394
j = 17;
395
}
396
else {
397
k = 18;
398
}
399
400
printf("%d, %d, %d\n", i, j, k);
401
402
}
When compiled, linked, and executed for debugging, the optimized program
results in this dialogue:
$ run doct8
.
.
.
DBG> step/into
stepped to DOCT8\doct8\%LINE 391
391:
k = 3;
DBG> examine i
%W, entity ’i’ was not allocated in memory (was optimized away)
DBG> examine j
%W, entity ’j’ does not have a value at the current PC
DBG> examine k
%W, entity ’k’ does not have a value at the current PC
Note the difference in the message for the variable i compared to j or k. The
variable i was not allocated in memory (registers, core, or otherwise) at all, so
there is no point in ever trying to examine its value again. By contrast, j and k
do not have a value "at the current PC" here; somewhere later in the program
they will.
Stepping one more line results in this:
DBG> step
stepped to DOCT8\doct8\%LINE 385
385: doct8 () {
This looks like a step backward — a common phenomenon in optimized
(scheduled) code. (This problem is dealt with by "semantic stepping mode,"
discussed in Section 14.1.2.) Continuing to step results in this:
14–9
Debugging Special Cases
14.1 Debugging Optimized Code
DBG> step 5
stepped to DOCT8\doct8\%LINE 391
391:
k = 3;
DBG> examine k
%W, entity ’k’ does not have a value at the current PC
DBG> step
stepped to DOCT8\doct8\%LINE 393
393:
if (foo(i)) {
DBG> examine j
%W, entity ’j’ does not have a value at the current PC
DBG> examine k
DOCT8\doct8\k: 3
value defined at DOCT8\doct8\%LINE 391
Here j is still undefined, but k now has a value, namely 3. That value was
assigned at line 391.
Recall from the source that j was assigned a value before k (at line 390), but that
has yet to show up. Again, this is common with optimized (scheduled) code.
DBG> step
stepped to DOCT8\doct8\%LINE 390
390:
j = 2;
Here the value of j appears. Thus:
DBG> examine j
%W, entity ’j’ does not have a value at the current PC
DBG> step
stepped to DOCT8\doct8\%LINE 393
393:
if (foo(i)) {
DBG> examine j
DOCT8\doct8\j: 2
value defined at DOCT8\doct8\%LINE 390
Skipping ahead to the print statement at line 400, examine j again.
DBG> set break %line 400
DBG> g
break at DOCT8\doct8\%LINE 400
400:
printf("%d, %d, %d\n", i, j, k);
DBG> examine j
DOCT8\doct8\j: 2
value defined at DOCT8\doct8\%LINE 390
value defined at DOCT8\doct8\%LINE 394
Here there is more than one definition location given for j. Which applies depends
on which path was taken in the IF clause. If a variable has an apparently
inappropriate value, this mechanism provides a means to take a closer look at
those places, and only those, where that value might have come from.
You can use the SHOW SYMBOL/ADDRESS command to display the splitlifetime information for a symbol, as in the following example:
14–10
Debugging Special Cases
14.1 Debugging Optimized Code
DBG> show symbol/address j
data DOCT8\doct8\j
between PC 131128 and 131140
PC definition locations are
address: %R3
between PC 131144 and 131148
PC definition locations are
address: %R3
between PC 131152 and 131156
PC definition locations are
address: %R3
between PC 131160 and 131208
PC definition locations are
address: %R3
at: 131124
at: 131140
at: 131124
at: 131124, 131140
The variable j has four lifetime segments. The PC addresses are the result of
linking the image, and the comments relate them to line numbers in the source
program.
•
The first segment starts at the assignment of 2 to j and extends through the
test to just before the assignment of 17 to j.
•
The second segment starts at the assignment of 17 to j and extends up to the
ELSE part of the IF statement.
•
The third segment corresponds to the ELSE clause. There is no assignment
to j in this range of PCs. Note that the definition of j that applies here is from
the first segment.
•
The fourth segment starts at the join point following the IF clause and
extends to the end of the program. The definition of j comes from either line
390 or line 394 depending on which path was taken through the IF statement.
On Alpha systems, the debugger tracks and reports which assignments and
definitions might have provided the displayed value of a variable. This additional
information can help you cope with some of the effects of code motion and other
optimizations — effects that cause a variable to have a value coming from an
unexpected place in the program.
EXAMINE/DEFINITIONS Command (Alpha Only)
For a split-lifetime variable, the EXAMINE command not only displays the
value of the active lifetime, it also displays the lifetime’s definition points. The
definition points are places where the lifetime could have received an initial value
(if there is only one definition point, then that is the only place.)
There is more than one definition point if a lifetime’s initial value can come from
more than one place. In the previous example when the program is suspended at
the printf, examining j results in the following:
DBG> examine j
DOCT8\doct8\j: 2
value defined at DOCT8\doct8\%LINE 390
value defined at DOCT8\doct8\%LINE 394
Here, the lifetime of j has two definition points, because the value could have
come from either line 390 or line 394, depending on whether or not the expression
at line 393 was TRUE.
By default, up to five definition locations are displayed when the contents of
a variable are examined. You can specify the number of definition locations to
display with the /DEFINITIONS=n qualifier, as in the following example:
DBG> EXAMINE/DEFINITIONS=74 FOO
14–11
Debugging Special Cases
14.1 Debugging Optimized Code
Note that the minimum abbreviation is /DEFI.
If you want a default number of definitions other than five, you can use a
command definition like the following:
DBG> DEFINE/COMMAND E = "EXAMINE/DEFINITIONS=100"
If the /DEFINITIONS qualifier is set to 100, and the split-lifetime variable
examined has 120 definition points, the debugger displays the 100 as specified,
and then reports:
there are 20 more definition points
14.2 Debugging Screen-Oriented Programs
The debugger uses the terminal screen for input and output (I/O) during a
debugging session. If you use a single terminal to debug a screen-oriented
program that uses most or all of the screen, debugger I/O can overwrite, or can be
overwritten by, program I/O.
Using one terminal for both program I/O and debugger I/O is even more
complicated if you are debugging in screen mode and your screen-oriented
program calls any Run-Time Library (RTL) Screen Management (SMG$) routines.
This is because the debugger’s screen mode also calls SMG routines. In such
cases, the debugger and your program share the same SMG pasteboard, which
causes further interference.
To avoid these problems when debugging a screen-oriented program, use one of
the following techniques to separate debugger I/O from program I/O:
•
If you are at a workstation running VWS, start your debugging session and
then enter the debugger command SET MODE SEPARATE. It creates a
separate terminal-emulator window for debugger I/O. Program I/O continues
to be displayed in the window from which you started the debugger.
•
If you are at a workstation running Compaq DECwindows Motif:
To display the debugger’s DECwindows Motif interface on a separate
workstation (also running DECwindows Motif), see Section 9.8.3.1.
To use the debugger’s command interface rather than the DECwindows
Motif interface, see Section 9.8.3.3. It explains how to create a separate
DECterm window for debugger I/O. The effect is similar to using the
command SET MODE SEPARATE on a workstation running VWS.
•
If you do not have a workstation, use two terminals—one for program I/O
and another for debugger I/O. This technique is described in the rest of this
section.
Assume that TTD1: is your current terminal from which you plan to start the
debugger. You want to display debugger I/O on terminal TTD2: so that TTD1: is
devoted exclusively to program I/O.
Follow these steps:
1. Provide the necessary protection to TTD2: so that you can allocate that
terminal from TTD1: (see Section 14.2.1).
The remaining steps are all performed from TTD1:.
14–12
Debugging Special Cases
14.2 Debugging Screen-Oriented Programs
2. Allocate TTD2:. This provides your process on TTD1: with exclusive access to
TTD2: as follows:
$ ALLOCATE TTD2:
3. Assign the debugger logical names DBG$INPUT and DBG$OUTPUT to
TTD2: as follows:
$ DEFINE DBG$INPUT TTD2:
$ DEFINE DBG$OUTPUT TTD2:
DBG$INPUT and DBG$OUTPUT specify the debugger input device and
output device, respectively. By default, these logical names are equated to
SYS$INPUT and SYS$OUTPUT, respectively. Assigning DBG$INPUT and
DBG$OUTPUT to TTD2: enables you to display debugger commands and
debugger output on TTD2:.
4. Make sure that the terminal type is known to the system. Enter the following
command:
$ SHOW DEVICE/FULL TTD2:
If the device type is unknown, your system manager (or a user with LOG_IO
or PHY_IO privilege) must make it known to the system as shown in the
following example. In the example, the terminal is assumed to be a VT200:
$ SET TERMINAL/PERMANENT/DEVICE=VT200 TTD2:
5. Run the program to be debugged:
$ DEBUG/KEEP
.
.
.
DBG> RUN prog-name
You can now observe debugger I/O on TTD2:
6. When finished with the debugging session, deallocate TTD2: as follows (or log
out):
$ DEALLOCATE TTD2:
14.2.1 Setting the Protection to Allocate a Terminal
On a properly secured system, terminals are protected so that you cannot allocate
a terminal from another terminal.
To set the necessary protection, your system manager (or a user with the
privileges indicated) should follow the steps shown in the following example.
In the example, TTD1: is your current terminal (from which you plan to start
the debugger), and TTD2: is the terminal to be allocated so that it can display
debugger I/O.
1. If both TTD1: and TTD2: are hardwired to the system, go to Step 4.
If TTD1: and TTD2: are connected to the system over a LAT (local area
transport), go to Step 2.
2. Log in to TTD2:.
14–13
Debugging Special Cases
14.2 Debugging Screen-Oriented Programs
3. Enter these commands (you need LOG_IO or PHY_IO privilege):
$ SET PROCESS/PRIV=LOG_IO
$ SET TERMINAL/NOHANG/PERMANENT
$ LOGOUT/NOHANG
4. Enter one of the following commands (you need OPER privilege):
$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENT=[PROJ,JONES],ACCESS=READ+WRITE) TTD2:
$ SET PROTECTION=WORLD:RW/DEVICE TTD2: "
!
! The SET ACL command line is preferred because it uses an access control
list (ACL). In the example, access is restricted to user identification code
(UIC) [PROJ,JONES].
" The SET PROTECTION command line provides world read/write access,
which allows any user to allocate and perform I/O to TTD2:.
14.3 Debugging Multilanguage Programs
The debugger enables you to debug modules whose source code is written in
different languages within the same debugging session. This section highlights
some language-specific behavior that you should be aware of to minimize possible
confusion.
When debugging in any language, be sure to consult:
•
The debugger’s online help (type HELP Language)
•
The documentation supplied with that language
14.3.1 Controlling the Current Debugger Language
When you bring a program under debugger control, the debugger sets the
current language to that in which the module containing the main program
(usually the routine containing the image transfer address) is written. The
current language is identified at that point. For example:
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG> RUN prog-name
Language: PASCAL, Module: FORMS
DBG>
The current language setting determines how the debugger parses and interprets
the names, operators, and expressions you specify in debugger commands,
including things like the typing of variables, array and record syntax, the default
radix for integer data, case sensitivity, and so on. The language setting also
determines how the debugger displays data associated with your program.
Many programs include modules that are written in languages other than that
of the main program. To minimize confusion, by default the debugger language
remains set to the language of the main program throughout a debugging session,
even if execution is paused within a module written in another language.
To take full advantage of symbolic debugging with such modules, use the SET
LANGUAGE command to set the debugging context to that of another language.
For example, the following command causes the debugger to interpret any
symbols, expressions, and so on according to the rules of the COBOL language:
DBG> SET LANGUAGE COBOL
14–14
Debugging Special Cases
14.3 Debugging Multilanguage Programs
On Alpha processors, the SET LANGUAGE command takes the following
keywords:
Ada
BASIC
BLISS
C
C++
COBOL
Fortran
MACRO-321
MACRO–64
Pascal
PL/I
1 Note
that MACRO-32 must be compiled with the AMACRO compiler.
On Integrity server processors, the SET LANGUAGE command takes the
following keywords:
Assembler (IAS)
BASIC
BLISS
C
C++
COBOL
Fortran
MACRO-321
IMACRO
PASCAL
1 Note
that MACRO-32 must be compiled with the AMACRO compiler.
In addition, when debugging a program that is written in an unsupported
language, you can specify the SET LANGUAGE UNKNOWN command. To
maximize the usability of the debugger with unsupported languages, the SET
LANGUAGE UNKNOWN command causes the debugger to accept a large set of
data formats and operators, including some that might be specific to only a few
supported languages. The operators and constructs that are recognized when the
language is set to UNKNOWN are identified in the debugger’s online help (type
HELP Language).
14.3.2 Specific Differences Among Languages
This section lists some of the differences you should keep in mind when debugging
in various languages. Included are differences that are affected by the SET
LANGUAGE command and other differences (for example, language-specific
initialization code and predefined breakpoints).
This section is not intended to be complete. See the debugger’s online help (type
HELP Language) and your language documentation for complete details.
14.3.2.1 Default Radix
The default radix for entering and displaying integer data is decimal for most
languages.
On Alpha processors, the exceptions are BLISS, MACRO–32, and MACRO–64,
which have a hexadecimal default radix.
Use the SET RADIX command to establish a new default radix.
14.3.2.2 Evaluating Language Expressions
Several debugger commands and constructs evaluate language expressions:
•
The EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE commands
•
WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET
WATCH commands
When processing these commands, the debugger evaluates language expressions
in the syntax of the current language and in the current radix as discussed in
Section 4.1.6. At each execution (not when you enter the command), the debugger
checks the syntax of any expressions in WHEN or DO clauses, and then evaluates
them.
14–15
Debugging Special Cases
14.3 Debugging Multilanguage Programs
Note that operators vary widely among different languages. For example, the
following two commands evaluate equivalent expressions in Pascal and Fortran,
respectively:
DBG> SET WATCH X WHEN (Y < 5)
DBG> SET WATCH X WHEN (Y .LT. 5)
! Pascal
! FORTRAN
Assume that the language is set to Pascal and you have entered the first (Pascal)
command. You now step into a Fortran routine, set the language to Fortran,
and resume execution. While the language is set to Fortran, the debugger is
not able to evaluate the expression (Y < 5). As a result, it sets an unconditional
watchpoint and, when the watchpoint is triggered, returns a syntax error for the
< operator.
This type of discrepancy can also occur if you use commands that evaluate
language expressions in debugger command procedures and initialization files.
When the language is set to BLISS, the debugger processes language expressions
that contain variable names (or other address expressions) differently than when
it is set to another language. See Section 4.1.6 for details.
14.3.2.3 Arrays and Records
The syntax for denoting array elements and record components (if applicable)
varies among languages.
For example, some languages use brackets ([ ]), and others use parentheses (( )),
to delimit array elements.
Some languages have zero-based arrays. Some languages have one-based arrays,
as in the following example:
DBG> EXAMINE INTEGER_ARRAY
PROG2\INTEGER_ARRAY
(1,1):
27
(1,2):
31
(1,3):
12
(2,1):
15
(2,2):
22
(2,3):
18
DBG>
For some languages (like Pascal and Ada) the specific array declaration
determines how the array is based.
14.3.2.4 Case Sensitivity
Names and language expressions are case sensitive in C. You must specify
them exactly as they appear in the source code. For example, the following two
commands are not equivalent when the language is set to C:
DBG> SET BREAK SCREEN_IO\%LINE 10
DBG> SET BREAK screen_io\%LINE 10
14–16
Debugging Special Cases
14.3 Debugging Multilanguage Programs
14.3.2.5 Initialization Code
Many programs issue a NOTATMAIN message when a program is brought under
debugger control. For example:
$ DEBUG/KEEP
Debugger Banner and Version Number
DBG> RUN prog-name
Language: ADA, Module: MONITOR
Type GO to reach main program
DBG>
The NOTATMAIN message indicates that execution is paused before the
beginning of the main program. This enables you to execute and check some
initialization code under debugger control.
The initialization code is created by the compiler and is placed in a special
PSECT named LIB$INITIALIZE. For example, in the case of an Ada package,
the initialization code belongs to the package body (which might contain
statements to initialize variables, and so on). In the case of a Fortran program,
the initialization code declares the handler that is needed if you specify the
/CHECK=UNDERFLOW or /CHECK=ALL qualifier.
The NOTATMAIN message indicates that, if you do not want to debug the
initialization code, you can execute immediately to the beginning of the main
program by entering a GO command. You are then at the same point as when
you start debugging any other program. Entering the GO command again starts
program execution.
14.3.2.6 Predefined Breakpoints
If your program is a tasking program, two breakpoints that are associated with
tasking exception events are automatically established when the program is
brought under debugger control. These breakpoints are not affected by a SET
LANGUAGE command. They are established automatically during debugger
initialization when appropriate run-time libraries are present.
To identify these predefined breakpoints, enter the SHOW BREAK command. For
example:
DBG> SHOW BREAK
Predefined breakpoint on ADA event "EXCEPTION_TERMINATED" for any value
Predefined breakpoint on ADA event "DEPENDENTS_EXCEPTION" for any value
DBG>
14.4 Recovering from Stack Corruption
The debugger allocates a certain amount of memory at startup and shares the
stack with the user’s program. If a user process exception results in exhaustion of
resources or corruption of the stack, the debugger may be incapable of regaining
control, and the debug session may terminate.
Be aware of this potential behavior after the occurrence of stack corruption
messages or warnings about continuing from a severe error. In either case, the
integrity of the debug session cannot be guaranteed.
You should try one of the following measures:
•
Change your source code, temporarily or permanently, to reduce resource
consumption or lessen the use of stack space
•
Increase quotas
14–17
Debugging Special Cases
14.4 Recovering from Stack Corruption
•
Specify a larger stack size when linking your program
14.5 Debugging Exceptions and Condition Handlers
A condition handler is a procedure that the operating system executes when an
exception occurs.
Exceptions include hardware conditions (such as an arithmetic overflow or
a memory access violation) or signaled software exceptions (for example, an
exception signaled because a file could not be found).
Operating system conventions specify how, and in what order, various condition
handlers established by the operating system, the debugger, or your own program
are invoked—for example, the primary handler, call frame (application-declared)
handlers, and so on. Section 14.5.3 describes condition handling when you are
using the debugger. See the OpenVMS Run-Time Library Routines Volume for
additional general information about condition handling.
Tools for debugging exceptions and condition handlers include the following:
•
The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands,
which direct the debugger to treat any exception generated by your
program as a breakpoint or tracepoint, respectively (see Section 14.5.1
and Section 14.5.2).
•
Several built-in symbols (such as %EXC_NAME), which enable you to qualify
exception breakpoints and tracepoints (see Section 14.5.4).
•
The SET BREAK/EVENT and SET TRACE/EVENT commands, which enable
you to break on or trace exception events that are specific to Ada, SCAN,
or multithread programs (see the corresponding documentation for more
information).
14.5.1 Setting Breakpoints or Tracepoints on Exceptions
When you enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION
command, you direct the debugger to treat any exception generated by your
program as a breakpoint or tracepoint. As a result of a SET BREAK/EXCEPTION
command, if your program generates an exception, the debugger suspends
execution, reports the exception and the line where execution is paused, and
prompts for commands. The following example shows the effect:
DBG> SET BREAK/EXCEPTION
DBG> GO
.
.
.
%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022
break on exception preceding TEST\%LINE 13
6:
X := 3/Y;
DBG>
Note that an exception breakpoint (or tracepoint) is triggered even if
your program has a condition handler to handle the exception. The SET
BREAK/EXCEPTION command causes a breakpoint to occur before any
handler can execute (and possibly dismiss the exception). Without the exception
breakpoint, the handler will be executed, and the debugger would get control only
if no handler dismissed the exception (see Section 14.5.2 and Section 14.5.3).
14–18
Debugging Special Cases
14.5 Debugging Exceptions and Condition Handlers
The following command line is useful for identifying where an exception occurred.
It causes the debugger to automatically display the sequence of active calls and
the PC value at an exception breakpoint:
DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS)
You can also create a screen-mode DO display that issues a SHOW CALLS
command whenever the debugger interrupts execution. For example:
DBG> DISPLAY CALLS DO (SET MODULE/CALLS; SHOW CALLS)
An exception tracepoint (established with the SET TRACE/EXCEPTION
command) is like an exception breakpoint followed by a GO command without an
address expression specified.
An exception breakpoint cancels an exception tracepoint, and vice versa.
To cancel exception breakpoints or tracepoints, use the CANCEL
BREAK/EXCEPTION or CANCEL TRACE/EXCEPTION command, respectively.
14.5.2 Resuming Execution at an Exception Breakpoint
When an exception breakpoint is triggered, execution is paused before any
application-declared condition handler is invoked. When you resume execution
from the breakpoint with the GO, STEP, or CALL commands, the behavior is as
follows:
•
Entering a GO command without an address-expression parameter, or
entering a STEP command, causes the debugger to resignal the exception.
The GO command enables you to observe which application-declared handler,
if any, next handles the exception. The STEP command causes you to step
into that handler (see the next example).
•
Entering a GO command with an address-expression parameter causes
execution to resume at the specified location, which inhibits the execution of
any application-declared handlers.
•
A common debugging technique at an exception breakpoint is to call a dump
routine with the CALL command (see Chapter 13). When you enter the
CALL command at an exception breakpoint, no breakpoints, tracepoints, or
watchpoints that were previously set within the called routine are active, so
that the debugger does not lose the exception context. After the routine has
executed, the debugger prompts for input. Entering a GO or STEP command
at this point causes the debugger to resignal the exception.
The following Fortran example shows how to determine the presence of a
condition handler at an exception breakpoint and how a STEP command, entered
at the breakpoint, enables you to step into the handler.
At the exception breakpoint, the SHOW CALLS command indicates that the
exception was generated during a call to routine SYS$QIOW:
14–19
Debugging Special Cases
14.5 Debugging Exceptions and Condition Handlers
DBG> SET BREAK/EXCEPTION
DBG> GO
.
.
.
%SYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000
break on exception preceding SYS$QIOW+6
DBG> SHOW CALLS
module name routine name
line
rel PC
abs PC
SYS$QIOW
00000006 7FFEDE06
*EXC$MAIN
EXC$MAIN
23
0000003B 0000063B
DBG>
On VAX processors, the following SHOW STACK command indicates that no
handler is declared in routine SYS$QIOW. However, one level down the call
stack, routine EXC$MAIN has declared a handler named SSHAND:
DBG> SHOW STACK
stack frame 0 (2146296644)
condition handler: 0
SPA:
0
S:
0
mask:
^M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11>
PSW:
0020 (hexadecimal)
saved AP:
2146296780
saved FP:
2146296704
saved PC:
EXC$MAIN\%LINE 25
.
.
.
stack frame 1 (2146296704)
condition handler: SSHAND
SPA:
0
S:
0
mask:
^M<R11>
PSW:
0000 (hexadecimal)
saved AP:
2146296780
saved FP:
2146296760
saved PC:
SHARE$DEBUG+2217
.
.
.
At this exception breakpoint, entering a STEP command enables you to step
directly into condition handler SSHAND:
DBG> STEP
stepped to routine SSHAND
2:
INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS)
DBG> SHOW CALLS
module name routine name
line
rel PC
abs PC
*SSHAND
SSHAND
2
00000002 00000642
----- above condition handler called with exception 0000045C:
%SYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000
----- end of exception message
SYS$QIOW
00000006 7FFEDE06
*EXC$MAIN
EXC$MAIN
23
0000003B 0000063B
DBG>
The debugger symbolizes the addresses of condition handlers into names if that
is possible. However, note that with some languages, exceptions are first handled
by a Run-Time Library (RTL) routine, before any application-declared condition
handler is invoked. In such cases, the address of the first condition handler might
be symbolized to an offset from an RTL shareable image address.
14–20
Debugging Special Cases
14.5 Debugging Exceptions and Condition Handlers
14.5.3 Effect of the Debugger on Condition Handling
When you run your program with the debugger, at least one of the following
condition handlers is invoked, in the order given, to handle any exceptions caused
by the execution of your program:
1. Primary handler
2. Secondary handler
3. Call-frame handlers (application-declared)—also known as stack handlers
4. Final handler
5. Last-chance handler
6. Catchall handler
A handler can return one of the following three status codes to the Condition
Handling Facility:
•
SS$_RESIGNAL—The operating system searches for the next handler.
•
SS$_CONTINUE—The condition is assumed to be corrected and execution
continues.
•
SS$_UNWIND—The call stack is unwound some number of frames, if
necessary, and the signal is dismissed.
For more information about condition handling, see the OpenVMS Programming
Concepts Manual.
14.5.3.1 Primary Handler
When you run your program with the debugger, the primary handler is the
debugger. Therefore, the debugger has the first opportunity to handle an
exception, whether or not the exception is caused by the debugger.
If you enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION command,
the debugger breaks on (or traces) any exceptions caused by your program. The
break (or trace) action occurs before any application-declared handler is invoked.
If you do not enter a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION
command, the primary handler resignals any exceptions caused by your
program.
14.5.3.2 Secondary Handler
The secondary handler is used for special purposes and does not apply to the
types of programs covered in this manual.
14.5.3.3 Call-Frame Handlers (Application-Declared)
Each routine of your program can establish a condition handler, also known as
a call-frame handler. The operating system searches for these handlers starting
with the routine that is currently executing. If no handler was established for
that routine, the system searches for a handler established by the next routine
down the call stack, and so on back to the main program, if necessary.
After it is invoked, a handler might perform one of the following actions:
•
It handles the exception, which allows the program to continue execution.
•
It resignals the exception. The operating system then searches for another
handler down the call stack.
14–21
Debugging Special Cases
14.5 Debugging Exceptions and Condition Handlers
•
It encounters a breakpoint or watchpoint, which suspends execution at the
breakpoint or watchpoint.
•
It generates its own exception. In this case, the primary handler is invoked
again.
•
It exits, which terminates program execution.
14.5.3.4 Final and Last-Chance Handlers
These handlers are controlled by the debugger. They enable the debugger to
regain control and display the DBG> prompt if no application-declared handler
has handled an exception. Otherwise, the debugging session will terminate and
control will pass to the DCL command interpreter.
The final handler is the last frame on the call stack and the first of these two
handlers to be invoked. The following example shows what happens when an
unhandled exception is propagated from an exception breakpoint to the final
handler:
DBG> SET BREAK/EXCEPTION
DBG> GO
.
.
.
%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022
break on exception preceding TEST\%LINE 13
6:
X := 3/Y;
DBG> GO
%SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022
DBG>
In this example, the first INTDIV message is issued by the primary handler, and
the second is issued by the final handler, which then displays the DBG> prompt.
The last-chance handler is invoked only if the final handler cannot gain control
because the call stack is corrupted. For example:
DBG> DEPOSIT %FP = 10
DBG> GO
.
.
.
%SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000A, PC=0000319C, PSL=03C00000
%DEBUG-E-LASTCHANCE, stack exception handlers lost, re-initializing stack
DBG>
The catchall handler, which is part of the operating system, is invoked if the
last-chance handler cannot gain control. The catchall handler produces a register
dump. This should never occur if the debugger has control of your program,
but it can occur if your program encounters an error when running without the
debugger.
If, during a debugging session, you observe a register dump and are returned to
DCL level ( $ ), contact your Compaq support representative.
14–22
Debugging Special Cases
14.5 Debugging Exceptions and Condition Handlers
14.5.4 Exception-Related Built-In Symbols
When an exception is signaled, the debugger sets the following exception-related
built-in symbols:
Symbol
Description
%EXC_FACILITY
Name of facility that issued the current exception
%EXC_NAME
Name of current exception
%ADAEXC_NAME
Ada exception name of current exception (for Ada programs only)
%EXC_NUMBER
Number of current exception
%EXC_SEVERITY
Severity code of current exception
You can use these symbols as follows:
•
To obtain information about the fields of the condition code of the current
exception.
•
To qualify exception breakpoints or tracepoints so that they trigger only on
certain kinds of exceptions.
The following examples show the use of some of these symbols. Note that the
conditional expressions in the WHEN clauses are language-specific.
DBG> EVALUATE %EXC_NAME
’ACCVIO’
DBG> SET TRACE/EXCEPTION WHEN (%EXC_NAME = "ACCVIO")
DBG> EVALUATE %EXC_FACILITY
’SYSTEM’
DBG> EVALUATE %EXC_NUMBER
12
DBG> EVALUATE/CONDITION_VALUE %EXC_NUMBER
%SYSTEM-F-ACCVIO, access violation, reason mask=01, virtual address=FFFFFF30, PC=00007552, PSL=03C00000
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12)
DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEVERITY .NE. "I" .AND. %EXC_SEVERITY .NE. "S")
14.6 Debugging Exit Handlers
Exit handlers are procedures that are called whenever an image requests the
$EXIT system service or runs to completion. A user program can declare one or
more exit handlers. The debugger always declares its own exit handler.
At program termination, the debugger exit handler executes after all applicationdeclared exit handlers have executed.
To debug an application-declared exit handler:
1. Set a breakpoint in that exit handler.
2. Cause the exit handler to execute by using one of the following techniques:
•
Include in your program an instruction that invokes the exit handler
(usually a call to $EXIT).
•
Allow your program to terminate.
•
Enter the EXIT command. (Note that the QUIT command does not
execute any user-declared exit handlers.)
When the exit handler executes, the breakpoint is activated and control is
then returned to the debugger, which prompts for commands.
14–23
Debugging Special Cases
14.6 Debugging Exit Handlers
The SHOW EXIT_HANDLERS command gives a display of the exit handlers
that your program has declared. The exit handler routines are displayed in
the order that they are called. A routine name is displayed symbolically, if
possible. Otherwise, its address is displayed. The debugger’s exit handlers are
not displayed. For example:
DBG> SHOW EXIT_HANDLERS
exit handler at STACKS\CLEANUP
exit handler at BLIHANDLER\HANDLER1
DBG>
14.7 Debugging AST-Driven Programs
A program can use asynchronous system traps (ASTs) either explicitly or
implicitly by calling system services or Run-Time Library (RTL) routines that
call application-defined AST routines. Section 14.7.1 explains how to facilitate
debugging by disabling and enabling the delivery of ASTs originating with your
program.
14.7.1 Disabling and Enabling the Delivery of ASTs
Debugging AST-driven programs can be confusing because interrupts originating
from the program being debugged can occur, but are not processed, while
the debugger is running (processing commands, tracing execution, displaying
information, and so on).
By default, the delivery of ASTs is enabled while the program is running. The
DISABLE AST command disables the delivery of ASTs while the program is
running and causes any such potential interrupts to be queued.
The delivery of ASTs is always disabled when the debugger is running.
If a static watchpoint is in effect, the debugger deactivates the static watchpoint,
ASTs, and thread switching, just before a system service call. The debugger
reactivates them just after the system service call completes. (For more
information, see the SET WATCH command description.)
The ENABLE AST command reenables the delivery of ASTs, including any
pending ASTs. The SHOW AST command indicates whether the delivery of ASTs
is enabled or disabled.
To control the delivery of ASTs during the execution of a routine called with
the CALL command, use the /[NO]AST qualifiers. The command CALL/AST
enables the delivery of ASTs in the called routine. The command CALL/NOAST
disables the delivery of ASTs in the called routine. If you do not specify /AST or
/NOAST with the CALL command, the delivery of ASTs is enabled unless you
have previously entered the DISABLE AST command.
14.8 Debugging Translated Images (Alpha and Integrity servers
Only)
On OpenVMS Alpha and Integrity server systems, the debugger does not support
attempts to debug translated images. If you must debug a translated image,
use the Delta/XDelta Debugger. For more information on this debugger, see the
OpenVMS Delta/XDelta Debugger Manual.
14–24
Debugging Special Cases
14.9 Debugging Programs That Perform Synchronization or Communication Functions
14.9 Debugging Programs That Perform Synchronization or
Communication Functions
Some programs that perform synchronization or communication can pose
problems for debugging. For example, an application being debugged includes the
LCK$M_DEQALL modifier in a $DEQ system service call (this modifier breaks
communication links between the portion of the debugger in the user process (the
kernel) and the debugger main process).
14.10 Debugging Inlined Routines
On OpenVMS systems, the debugger does not support attempts to debug inlined
routines. If you attempt to debug an inlined routine, the debugger issues a
message that it cannot access the routine, as shown in the following example:
%DEBUG-E-ACCESSR, no read access to address 00000000
To work around this problem, compile your program with the /NOOPTIMIZE
qualifier.
14–25
15
Debugging Multiprocess Programs
This chapter describes features of the debugger that are specific to multiprocess
programs (programs that run in more than one process). With these features, you
can display process information and control the execution of specific processes.
You can use these features in addition to those explained in other chapters.
Images discussed in this chapter are debuggable images—that is, images that can
be controlled by debugger. An image that is linked with the /NOTRACEBACK
qualifier cannot be brought under control of the debugger. As explained in
Section 1.2, you get full symbolic information when debugging an image only for
modules that are compiled and linked with the /DEBUG qualifier.
15.1 Basic Multiprocess Debugging Techniques
This section introduces basic concepts of multiprocess debugging. Refer to
subsequent sections for complete details.
15.1.1 Starting a Multiprocess Debugging Session
This section explains the easiest way to start a multiprocess debugging session.
Section 15.16.3 describes additional ways to start the debugger.
To start a multiprocess debugging session, start the kept debugger. For example,
$ debug/keep
OpenVMS Integrity server Debug64
Version T8.2-008
DBG>
In a multiprocess debugging session, the debugger traces each new process that
is brought under control. The debugger identifies each process with a decimal
process number, as shown in Example 15–1.
Example 15–1 RUN/NEW Command
DBG> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C activated
SERVER\__main
DBG> RUN/NEW CLIENT
process 2
%DEBUG-I-INITIAL, Language: C, Module: CLIENT
%DEBUG-I-NOTATMAIN, Type GO to reach MAIN program
predefined trace on activation at CLIENT\__main
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C activated
SERVER\__main
2 USER_2
activated
CLIENT\__main
all>
15–1
Debugging Multiprocess Programs
15.1 Basic Multiprocess Debugging Techniques
The RUN/NEW CLIENT command in Example 15–1 starts the program CLIENT
in a new process. The first time (in a debugging session) that the debugger has
more than one process under its control, it changes its prompt to all> to identify
the set of all processes under its control.
Processes and Process Sets
Once the debugger is aware of more than one process, the debugger prompt
changes to the identifier of the current process set, followed by a right angle
bracket (>).
Conceptually, each process belongs to a set of one, identified by default by the
unique decimal number assigned to it when the debugger takes control of the
process. A process can belong to more than one set. All processes under debugger
control are grouped by default into a set named all.
You can group processes into user-named sets with the DEFINE /PROCESS_SET
command.
Current Process Set
Debugger commands apply by default to the current process set. By default,
the current process set is the set named all. You can change the current process
set with the SET PROCESS command.
Command Process Set
The set of processes at which a command is directed is called the command
process set. The default command process set is the current process set.
Process Set Prefix
You can give a debugger command that applies to a command process set other
than the current process set without changing the current process set. To do so,
prefix the command with the name of the process set followed by a right angle
bracket (>). For example:
all> 1,2,5> GO
1,2,5> is a process set prefix. This syntax allows you to cut and paste
commands from a previous command line.
Visible Process
The visible process is the process that is shown in current displays, and is
identified by an asterisk (*) in column 1 in a SHOW PROCESS display. You
can change the visible process with the SET PROCESS/VISIBLE command. For
example:
all> SHOW PROCESS
Number Name
State
*
1 DBGK$$2727282C activated
2 USER_2
activated
all>
Current PC
SERVER\__main
CLIENT\__main
In the above example, process number 1 is the visible process.
15.2 Obtaining Information About Processes
Use the SHOW PROCESS command to obtain information about processes
that are currently under control of your debugging session. By default, SHOW
PROCESS displays information about all processes under control of the debugger.
(These are the processes in process set all.) Example 15–2 shows the type of
information displayed immediately after you start the debugger.
15–2
Debugging Multiprocess Programs
15.2 Obtaining Information About Processes
Example 15–2 SHOW PROCESS Command
DBG> SHOW PROCESS/BRIEF/ALL
Number Name
State
*
1 JONES
activated
DBG>
Current PC
MAIN_PROG\%LINE 2
Note that the qualifiers /BRIEF and /ALL are the default. Note also that the
debugger displays its default prompt, because the debugger still has only one
process under its control. The SHOW PROCESS command provides the following
information about each process specified:
•
The process number assigned by the debugger. In Example 15–2, the process
number is 1 because this is the first process known to the debugger. The
asterisk in the leftmost column ( * ) marks the visible process.
•
The process name. In this case, the process name is JONES.
•
The current debugging state for that process. A process is in the activated
state when it is first brought under debugger control (that is, before it has
executed any part of the program under debugger control). Table 15–1
summarizes the possible debugging states of a process under debugger
control.
•
The location (symbolized, if possible) where execution of the image is paused
in that process. In Example 15–2, the image has not yet started execution.
Table 15–1 Debugging States
State
Description
Running
Executing under control of the debugger.
Stopped
Activated
The image and its process have just been brought
under debugger control.
Break1
A breakpoint was triggered.
Interrupted
Execution was interrupted in that process, in one of
the following ways:
Step1
Execution was suspended in another process.
•
It was interrupted with the abort-key sequence
(Ctrl/C, by default).
•
It was interrupted by the STOP command.
A STEP command has completed.
1
Trace
1 See
•
A tracepoint was triggered.
Unhandled exception
An unhandled exception was encountered.
Watch of
A watchpoint was triggered.
Terminated
The image has terminated execution but the process
is still under debugger control. Therefore, you can
obtain information about the image and its process.
the SHOW PROCESS command description for a list of additional states.
15–3
Debugging Multiprocess Programs
15.2 Obtaining Information About Processes
Returning to Example 15–2, if you now enter a STEP command followed by a
SHOW PROCESS command, the state column in the SHOW PROCESS display
indicates that execution is paused at the completion of a step. For example:
DBG> STEP
DBG> SHOW PROCESS
Number Name
*
1 JONES
DBG>
State
step
Current PC
MAIN_PROG\%LINE 3
Similarly, if you were to set a breakpoint and then enter a GO command, a
SHOW PROCESS command entered once the breakpoint has triggered identifies
the state as break.
15.3 Process Specification
Each new process to which the debugger connects is identified by a processnumber. The first process is process-number 1, the second process is processnumber 2, and so on. When a process stops, its process number is recycled and is
available to the debugger for assignment to a subsequent process.
Processes are referred to using the process-spec. The most simple process-spec
is either a process-name created by OpenVMS when the process is created, or a
process-number created by the debugger when the debugger gains control of the
process. A process-spec that consists of only numbers is interpreted as a process
number. Within debugger commands, you can use process-numbers to specify
individual processes (for example, "2,3,4,5").
A process-spec-item can be a name, in which case it can refer to a process-name
or a process-set-name. The debugger tries first to find a process-set with that
name. If unsuccessful, the debugger then tries to match a process to the name.
You can explicitly specify the process-name by using the %PROCESS_NAME
lexical function.
Example 15–3 contains the complete process specification syntax.
Example 15–3 Process Specification Syntax
process-spec ::=
process-spec-item [, process-spec-item]
process-spec-item ::= named-item |
numbered-item |
pid-item |
process-set-name |
special-item
named-item ::=
[%PROCESS_NAME] wildcard-name
numbered-item ::= numbered-process
numbered-process ::= [%PROCESS_NUMBER] decimal-number
pid-item ::=
%PROCESS_ID VMS-process-identifier
process-set-name ::= name
special-item ::=
15–4
%NEXT_PROCESS |
%PREVIOUS_PROCESS |
%VISIBLE_PROCESS
Debugging Multiprocess Programs
15.4 Process Sets
15.4 Process Sets
You can place processes into groups called process sets with the DEFINE
PROCESS_SET command followed by a list of processes separated by commas (,).
For example:
all> DEFINE/PROCESS CLIENTS = 2,3
all> SET PROCESS CLIENTS
clients> STEP
process 2,3
stepped to CLIENT\main\%LINE 18796
18796:
status = sys$crembx (0, &mbxchan, 0, 0, 0,
0, &mbxname_dsc, CMB$M_READONLY, 0);
clients> SHOW PROCESS CLIENTS
Number Name
State
Current PC
2 USER1_2
step
CLIENT\main\%LINE 18796
3 USER1_3
step
CLIENT\main\%LINE 18796
clients>
There is a predefined process set named all, which is the default process set when
the debugger is first invoked. You cannot redefine this process set.
Current Process Set
At any time during a debugging session, there is a current process set in effect.
The current process set is the group of processes to which debugger processsensitive commands apply by default. See Section 15.6 for a list of debugger
commands that are process-sensitive.
By default, the current process set is the set of all processes, with the process
set name all. You can change the current process set with the SET PROCESS
command.
The SET PROCESS command does three things:
•
It specifies the current process set.
•
It controls the visible process with the /VISIBLE qualifier.
•
It turns dynamic process setting on or off with the /[NO]DYNAMIC qualifier.
When used without a qualifier, the SET PROCESS command takes a single
parameter, a process-spec, which specifies the current process set. For example:
all> SET PROCESS 1
1> STEP
process 1
stepped to SERVER\main\%LINE 18800
18800:
if (!(status & 1))
1> SET PROCESS ALL
all>
The SET PROCESS/DYNAMIC command directs the debugger to change the
visible process when a debugger event occurs, such as the completion of a STEP
command, or the triggering of a breakpoint. The visible process becomes the
process that triggered the event. For example:
15–5
Debugging Multiprocess Programs
15.4 Process Sets
all> SET PROCESS/DYNAMIC
all> 1> STEP
process 1
stepped to SERVER\main\%LINE 18808
18808:
df_p = fopen (datafile, "r+");
all> SHOW PROCESS/VISIBLE
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18808
all>
Command Process Set
The command process set is the group of processes to which a debugger
command is directed. By default, the command process set is the current
process set. You can use a process set prefix to specify a command process set
for the current command, which overrides the current process set for that single
command. For example:
all> 2,3> STEP
processes 2,3
stepped to CLIENT\main\%LINE 18797
18797:
if (!(status & 1))
all> clients> STEP
processes 2,3
stepped to CLIENT\main\%LINE 18805
18805:
memset (&myiosb, 0, sizeof(myiosb));
all>
Process-independent commands ignore any process set prefix, just as they ignore
the current process set.
15.5 Debugger Prompts
By default, the debugger command prompt indicates the current process set,
using the same syntax as the process-spec. The command prompt is the current
process set process-spec followed by a right angle bracket (>). When you define
the current process set, the debugger changes its prompt to the name of the
current process set, followed by a right angle bracket. For example:
all>
! by default, current process set is all processes
all>
all> SET PROCESS 2,3,4,5
2,3,4,5> DEFINE /PROCESS_SET interesting 1,2,3,7
2,3,4,5> SET PROCESS interesting
interesting> SET PROCESS *
all> SET PROCESS 3
3>
Note
The debugger does not use the process-spec format for the debugger
prompt until the debugger becomes aware of more than one process.
15.6 Process-Sensitive Commands
There are two types of commands, process-sensitive and process-independent.
Process-sensitive commands are those that depend on the state of a process, such
as GO, STEP, CALL, and SET BREAK.
15–6
Debugging Multiprocess Programs
15.6 Process-Sensitive Commands
Process-independent commands are those that depend on and affect the state of
the debugger and ignore the state of processes, such as SET DISPLAY, WAIT,
ATTACH, and SPAWN.
15.7 Visible Process and Process-Sensitive Commands
The visible process is the process shown by default in the source display (and
other such process-oriented displays). When the current process set is changed
with the SET PROCESS command, the visible process is set to be the first process
specified in that command. You can use the SET PROCESS/VISIBLE command
to specify a particular process as the visible one without changing the current
process set.
15.8 Controlling Process Execution
When debugging an application with multiple processes, it is common to have
some process stopped while other processes are still running. It can be useful
to be able to give commands only to those processes that are stopped without
waiting for all processes to stop. Wait mode provides that capability.
15.8.1 WAIT Mode
With regard to executing processes, the debugger has two modes: wait and
nowait. You can control whether or not the debugger waits for all running
processes to stop before the debugger accepts and executes another command by
toggling wait mode with the SET MODE [NO]WAIT command. Wait mode is the
default.
When the debugger is in wait mode and you enter the GO, STEP, or CALL
command, the debugger executes the command in all processes in the command
process set, and waits until all those processes stop (for example, at breakpoints)
before displaying a prompt and accepting another command.
When the debugger is in nowait mode and you enter the GO, STEP, or CALL
command, the debugger executes the command in all processes in the command
process set, and immediately displays a prompt. You can enter a new command
immediately, regardless of whether any or all processes have stopped. This
provides great flexibility, especially when debugging multiprocess programs.
Control over WAIT mode allows you to do the following:
•
While the program is running, you can use the debugger as a source browser.
Because the source view is process-independent, you can change its focus
while processes are executing.
•
You can control separate processes one at a time.
•
You can control more than one process at a time.
A SET MODE [NO]WAIT command remains in effect until the next SET MODE
[NO]WAIT command. For example:
all> SET MODE NOWAIT
all> clients> STEP
all> SHOW PROCESS
Number Name
1 DBGK$$2727282C
2 USER1_2
*
3 USER1_3
all>
State
Current PC
step
SERVER\main\%LINE 18819
running
not available
running
not available
15–7
Debugging Multiprocess Programs
15.8 Controlling Process Execution
You can use the WAIT command to override nowait mode for the duration of
one command, to direct the debugger to wait until all processes in the command
process set stop before prompting for another command. Nowait mode remains in
effect when the command completes. For example:
all> GO;WAIT
processes 2,3
break at CLIENT\main\%LINE 18814
18814:
status = sys$qiow (EFN$C_ENF, mbxchan,
IO$_READVBLK|IO$M_WRITERCHECK, &myiosb,
process 1
break at SERVER\main\%LINE 18834
18834:
if ((myiosb.iosb$w_status ==
SS$_NOREADER) && (pos_status != -1))
all>
When commands are processed in a non-interactive manner (within debugger
command sequences within FOR, REPEAT, WHILE, IF, and @ commands, and
within WHEN clauses), WAIT mode is enabled by default during the execution of
the command sequence.
During NOWAIT mode, an EXAMINE command (similar to all processindependent commands) displays results for those processes in its command
process set that are stopped. If all processes in its command process set are
running, the EXAMINE command reports that condition and the debugger
displays a prompt and accepts a new command. Similarly, a GO command during
NOWAIT mode starts all stopped processes in the command process set.
15.8.2 Interrupt Mode
Use the SET MODE [NO]INTERRUPT command to toggle the state of interrupt
mode. When interrupt mode is toggled on, the debugger stops all processes
when one process stops. This can be a disadvantage if an interrupted process
is deep into a RTL or system service call because it can leave many irrelevant
non-symbolic frames on top of the process stack.
When interrupt mode is toggled off, the debugger does not stop any other process
unless you enter a STOP command. This is the default mode.
15.8.3 STOP Command
Use the STOP command to interrupt running processes. The STOP command
interrupts all of the running processes in its command process set.
The STOP command completes as soon as it sends a stop request to every running
process in the command set. For example:
all> SHOW PROCESS
Number Name
1 DBGK$$2727282C
2 USER1_2
*
3 USER1_3
all> clients> STOP
all> SHOW PROCESS
Number Name
1 DBGK$$2727282C
2 USER1_2
*
3 USER1_3
all>
15–8
State
Current PC
break
SERVER\main\%LINE 18834
running
not available
running
not available
State
Current PC
break
SERVER\main\%LINE 18834
interrupted 0FFFFFFFF800F7A20
interrupted 0FFFFFFFF800F7A20
Debugging Multiprocess Programs
15.9 Connecting to Another Program
15.9 Connecting to Another Program
You can bring a debuggable program under control of the debugger from a kept
debugger session. This could be a client program that runs independently in
another process. Because the debugger is not yet aware of that process, you
cannot obtain information about it from a SHOW PROCESS command. Enter the
CONNECT command and specify the process name of the client program with the
debugger %PROCESS_NAME lexical function. For example:
all> CONNECT %PROCESS_NAME CLIENT2
process 3
predefined trace on activation at 0FFFFFFFF800F7A20
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C activated
SERVER\__main
2 USER1_2
activated
CLIENT\__main
3 CLIENT2
interrupted 0FFFFFFFF800F7A20
activated
all>
Unexpected results can occur if you enter the CONNECT command if any of
the debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG,
DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) differ
between the debugger main process and the process in which the client runs.
15.10 Connecting to a Spawned Process
When a program you are debugging (with the kept debugger) spawns a
debuggable process, the spawned process waits to be connected to the debugger.
At this time the debugger has no information about the newly spawned process,
and you cannot get information about that process from a SHOW PROCESS
command. You can bring the newly spawned process under debugger control
using either of the following methods:
•
Enter a command, such as STEP, that starts execution (if, as in the following
example, your program is of the hierarchical model).
•
Enter the CONNECT command without specifying a parameter. The
CONNECT command is useful in cases when you do not want the process to
execute further.
The following example shows this use of the CONNECT command:
1> STEP
stepped to
18:
1> STEP
stepped to
21:
1> CONNECT
predefined
all>
MAIN_PROG\%LINE 18 in %PROCESS_NUMBER 1
LIB$SPAWN("RUN/DEBUG TEST",,,1)
MAIN_PROG\%LINE 21 in %PROCESS_NUMBER 1
X = 7
trace on activation at routine TEST in %PROCESS_NUMBER 2
In this example, the second STEP command takes you past the LIB$SPAWN call
that spawns the process. The CONNECT command brings the waiting process
under debugger control. After entering the CONNECT command, you might
need to wait a moment for the process to connect. The "predefined trace on . . . "
message indicates that the debugger has taken control of a new process which is
identified as process 2.
15–9
Debugging Multiprocess Programs
15.10 Connecting to a Spawned Process
A SHOW PROCESS command, entered at this point, identifies the debugging
state for each process and the location at which execution is paused:
all> SHOW PROCESS
Number Name
*
1 JONES
2 JONES_1
all>
State
step
activated
Current PC
MAIN_PROG\%LINE 21
TEST\%LINE 1+2
Note that the CONNECT command brings all processes that are waiting to be
connected to the debugger under debugger control. If no processes are waiting,
you can press Ctrl/C to abort the CONNECT command and display the debugger
prompt.
Unexpected results can occur if you enter the CONNECT command if any of
the debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG,
DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) differ
between the debugger process and the spawned process.
15.11 Monitoring the Termination of Images
When the main image of a process runs to completion, the process goes into the
terminated debugging state (not to be confused with process termination in the
operating system sense). This condition is traced by default, as if you had entered
the SET TRACE/TERMINATING command.
When a process is in the terminated debugging state, it is still known to the
debugger and appears in a SHOW PROCESS display. You can enter commands
to examine variables, and so on.
15.12 Releasing a Process From Debugger Control
To release a process from debugger control without terminating the process, enter
the DISCONNECT command. (In contrast, when you specify a process with the
EXIT or QUIT command, the process is terminated.)
15–10
Debugging Multiprocess Programs
15.12 Releasing a Process From Debugger Control
This command is required for programs of the client/server model. For example:
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18823
2 USER1_2
step
CLIENT\main\%LINE 18805
3 USER1_3
step
CLIENT\main\%LINE 18805
all> DISCONNECT 3
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18823
2 USER1_2
step
CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
%DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$
Bear in mind that the debugger kernel runs in the same process as the image
being debugged. If you issue the DISCONNECT command for this process, you
release your process, but the kernel remains activated. This activation continues
until the program image finishes running. If you install a new version of the
debugger while one or more disconnected but activated kernels inhabit user
program space, you can experience problems with debugger behavior if you try to
reconnect to that program image.
15.13 Terminating Specified Processes
To terminate specified processes without ending the debugging session, use
the EXIT or QUIT command, specifying one or more process specifications as
parameters. For example,
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18823
2 USER1_2
step
CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
%DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$
15.14 Interrupting Program Execution
Pressing Ctrl/C (or the abort-key sequence established with the SET ABORT_
KEY command) interrupts execution in every process that is currently running an
image. This is indicated as an interrupted state in a SHOW PROCESS display.
Note that you can also use Ctrl/C to abort a debugger command.
You can also stop a process with the debugger STOP command.
15.15 Ending the Debugging Session
To end the entire debugging session, use the EXIT or QUIT command without
specifying any parameters.
EXIT executes any exit handlers that are declared in the program. QUIT does
not.
15–11
Debugging Multiprocess Programs
15.15 Ending the Debugging Session
QUIT Command
Use the QUIT command to terminate running processes. The QUIT command
terminates all of the running processes in its command process set without
allowing any exit handlers to run. A process set prefix is ignored before a QUIT
command. For example:
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18823
2 USER1_2
step
CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
%DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$
The QUIT command ignores the current process set. If you do not specify a
process, the QUIT command terminates all processes and then terminates the
debugging session.
EXIT Command
Use the EXIT command to terminate running processes. The EXIT command
terminates all of the running processes in its command process set without
allowing any exit handlers to run. A process set prefix is ignored before an EXIT
command. For example:
all> SHOW PROCESS
Number Name
State
Current PC
*
1 DBGK$$2727282C step
SERVER\main\%LINE 18823
2 USER1_2
step
CLIENT\main\%LINE 18805
all> EXIT 1,2
DBG> SHOW PROCESS
%DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$
The EXIT command ignores the current process set. If you do not specify a
process, the EXIT command terminates all processes and then terminates the
debugging session.
15.16 Supplemental Information
This section provides additional details or more advanced concepts and usages
than those covered in Section 15.1.
15.16.0.1 Process Relationships When Debugging
The debugger consists of two parts: a main debugger image (DEBUGSHR.EXE)
that contains most of the debugger code and a smaller kernel debugger image
(DEBUG.EXE). This separation reduces potential interference between the
debugger and the program being debugged and also makes it possible to have a
multiprocess debugging configuration.
When you bring a program under control of the kept debugger, the main debugger
spawns a subprocess to run the program along with the kernel debugger.
An application being debugged might run in several processes. Each process
under debugger control is running a local copy of the kernel debugger. The main
debugger, which is running in its own process, communicates with the other
processes through their kernel debuggers.
15–12
Debugging Multiprocess Programs
15.16 Supplemental Information
Although all processes must be in the same UIC group, they do not have to be
related in a particular process/subprocess hierarchy. Moreover, the program
images running in separate processes do not have to communicate with each
other.
See Section 15.16.6 for system requirements related to multiprocess debugging.
15.16.1 Specifying Processes in Debugger Commands
When specifying processes in debugger commands, you can use any of the forms
listed in Table 15–2, except when specifying processes with the CONNECT
command (see Section 15.9).
Use the CONNECT command to bring a process that is not yet known to the
debugger under debugger control. Until you bring a new process under control
of the debugger, the process does not have a debugger-assigned process number,
nor can you reference it with any of the built-in process symbols (for example,
%NEXT_PROCESS). Therefore, when specifying a process with CONNECT, you
can use only its process name or process identifier (PID).
Table 15–2 Process Specifications
Format
Usage
[%PROCESS_NAME] process-name
The process name, if that name does not
contain spaces or lowercase characters. The
process name can include the asterisk ( * )
wildcard character.
[%PROCESS_NAME] "process-name "
The process name, if that name contains
spaces or lowercase characters. You can also
use apostrophes (’) instead of quotation marks
( " ).
%PROCESS_PID process_id
The process identifier (PID, a hexadecimal
number).
[%PROCESS_NUMBER] process-number
(or %PROC process-number)
The number assigned to a process when it
comes under debugger control. A new number
is assigned sequentially, starting with 1, to
each process. If a process is terminated with
the EXIT or QUIT command, the number
can be assigned again during the debugging
session. Process numbers appear in a SHOW
PROCESS display. Processes are ordered in a
circular list so they can be indexed with the
built-in symbols %PREVIOUS_PROCESS and
%NEXT_PROCESS.
process-set-name
A symbol defined with the
DEFINE/PROCESS_SET command to
represent a group of processes.
%NEXT_PROCESS
The next process after the visible process in
the debugger’s circular process list.
%PREVIOUS_PROCESS
The process previous to the visible process in
the debugger’s circular process list.
(continued on next page)
15–13
Debugging Multiprocess Programs
15.16 Supplemental Information
Table 15–2 (Cont.) Process Specifications
Format
Usage
%VISIBLE_PROCESS
The process whose stack, register set, and
images are the current context for looking
up symbols, register values, routine calls,
breakpoints, and so on.
You can omit the %PROCESS_NAME and %PROCESS_NUMBER built-in
symbols when entering commands. For example:
2> SHOW PROCESS 2, JONES_3
The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and
%PREVIOUS_PROCESS are useful in control structures based on the IF,
WHILE, or REPEAT commands and in command procedures.
15.16.2 Monitoring Process Activation and Termination
By default, a tracepoint is triggered when a process comes under debugger
control and when it performs an image exit. These predefined tracepoints are
equivalent to those resulting from entering the SET TRACE/ACTIVATING
and SET TRACE/TERMINATING commands, respectively. You can set
breakpoints on these events with the SET BREAK/ACTIVATING and SET
BREAK/TERMINATING commands.
To cancel the predefined tracepoints, use the CANCEL TRACE/PREDEFINED
command with the /ACTIVATING and /TERMINATING qualifiers. To cancel any
user-defined activation and termination breakpoints, use the CANCEL BREAK
command with the /ACTIVATING and /TERMINATING qualifiers (the /USER
qualifier is the default when canceling breakpoints or tracepoints).
The debugger prompt is displayed when the first process comes under debugger
control. This enables you to enter commands before the main image has started
execution, as with a one-process program.
Similarly, the debugger prompt is displayed when the last process performs an
image exit. This enables you to enter commands after the program has completed
execution, as with a one-process program.
15.16.3 Interrupting the Execution of an Image to Connect It to the Debugger
You can interrupt a debuggable image that is running without debugger control
in a process and connect that process to the debugger.
15–14
•
To start a new debugging session, use the Ctrl/Y–DEBUG sequence from DCL
level. Note that this starts the unkept debugger, which you cannot use for
debugging multiprocess programs.
•
To interrupt an image and connect it to an existing multiprocess debugging
session, use the debugger CONNECT command.
Debugging Multiprocess Programs
15.16 Supplemental Information
15.16.4 Screen Mode Features for Multiprocess Debugging
By default, the source, instruction, and register displays show information about
the visible process.
By using the /PROCESS qualifier with the DISPLAY command, you can create
process-specific displays or make existing displays process specific, respectively.
The contents of a process-specific display are generated and modified in the
context of that process. You can make any display process specific except for the
PROMPT display. For example, the following command creates the automatically
updated source display SRC_3, which shows the source code where execution is
suspended in process 3:
2> DISPLAY/PROCESS=(3) SRC_3 AT RS23 2> SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC)
Assign attributes to process-specific displays in the same way as for displays
that are not process specific. For example, the following command makes display
SRC_3 the current scrolling and source display; that is, the output of SCROLL,
TYPE, and EXAMINE/SOURCE commands are then directed at SRC_3:
2> SELECT/SCROLL/SOURCE SRC_3
If you enter a DISPLAY/PROCESS command without specifying a process, the
specified display is then specific to the process that was the visible process when
you entered the command. For example, the following command makes display
OUT_X specific to process 2:
2> DISPLAY/PROCESS OUT_X
In a multiprocess configuration, the predefined tracepoint on process activation
automatically creates a new source display and a new instruction display for each
new process that comes under debugger control. The displays have the names
SRC_n and INST_n, respectively, where n is the process number. These displays
are initially marked as removed. They are automatically deleted on process
termination.
Several predefined keypad key sequences enable you to configure your screen with
the process-specific source and instruction displays that are created automatically
when a process is activated. Key sequences that are specific to multiprocess
programs are as follows: PF1 KP9, PF4 KP9, PF4 KP7, PF4 KP3, PF4 KP1.
See Section A.5 for the general effect of these sequences. Use the SHOW KEY
command to determine the exact commands.
15.16.5 Setting Watchpoints in Global Sections (Alpha and Integrity servers
Only)
On Alpha and Integrity servers, you can set watchpoints in global sections. A
global section is a region of memory that is shared among all processes of a
multiprocess program. A watchpoint that is set on a location in a global section
(a global section watchpoint) triggers when any process modifies the contents of
that location.
When setting watchpoints on arrays or records, note that performance is
improved if you specify individual elements rather than the entire structure
with the SET WATCH command.
15–15
Debugging Multiprocess Programs
15.16 Supplemental Information
If you set a watchpoint on a location that is not yet mapped to a global section,
the watchpoint is treated as a conventional static watchpoint. For example:
1> SET WATCH ARR(1)
1> SHOW WATCH
watchpoint of PPL3\ARR(1)
When ARR is subsequently mapped to a global section, the watchpoint is
automatically treated as a global section watchpoint and an informational
message is issued. For example:
1> GO
%DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has
been remapped to a global section
predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 2
predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 3
watch of PPL3\ARR(1) at PPL3\%LINE 93 in %PROCESS_NUMBER 2
93:
ARR(1) = INDEX
old value: 0
new value: 1
break at PPL3\%LINE 94 in %PROCESS_NUMBER 2
94:
ARR(I) = I
After the watched location is mapped to a global section, the watchpoint is visible
from each process. For example:
all> SHOW WATCH
For %PROCESS_NUMBER 1
watchpoint of PPL3\ARR(1) [global-section watchpoint]
For %PROCESS_NUMBER 2
watchpoint of PPL3\ARR(1) [global-section watchpoint]
For %PROCESS_NUMBER 3
watchpoint of PPL3\ARR(1) [global-section watchpoint]
all>
15.16.6 System Requirements for Debugging
Several users debugging programs simultaneously can place a load on a system.
This section describes the resources used by the debugger, so that you or your
system manager can tune your system for this activity.
Note that the discussion covers only the resources used by the debugger. You
might also have to tune your system to support the programs themselves.
15.16.6.1 User Quotas
Each user needs a PRCLM quota sufficient to create an additional process for the
debugger, beyond the number of processes needed by the program.
BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need
to be increased to account for the debugger process as follows:
15–16
•
Each user’s ENQLM quota should be increased by at least the number of
processes being debugged.
•
Each user’s PGFLQUOTA might need to be increased. If a user has an
insufficient PGFLQUOTA, the debugger might fail to activate or might cause
"virtual memory exceeded" errors during execution.
•
Each user’s BYTLM and FILLM quotas might need to be increased. The
debugger requires BYTLM and FILLM quotas sufficient to open each image
file being debugged, the corresponding source files, and the debugger input,
output, and log files.
Debugging Multiprocess Programs
15.16 Supplemental Information
15.16.6.2 System Resources
The kernel debugger and main debugger communicate through global sections.
Each main debugger, regardless of platform, uses at least one 64-Kbyte global
section. On Alpha, the main debugger can communicate with up to six kernel
debuggers. On Integrity servers, it can only communicate with up to 2 kernel
debuggers.
15.17 Examples
Example 15–4 and Example 15–5 contain the C code for the server and client
programs used in examples throughout this chapter.
Example 15–4 server.c
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
<stdio.h>
<starlet.h>
<cmbdef.h>
<types.h>
<descrip.h>
<efndef.h>
<iodef.h>
<iosbdef.h>
<ssdef.h>
<string.h>
#include "mbxtest.h"
int main (int argc, char **argv)
{
unsigned int status, write_ef;
char line_buf [LINE_MAX_LEN + 1];
iosb myiosb;
short mbxchan;
/* Get event flag. Look for or create the mailbox.
*/
status = lib$get_ef (&write_ef);
if (!(status & 1))
{
fprintf (stderr, "Server unable to get eventflag,
status = %x", status);
return 0;
}
status = sys$crembx (0, &mbxchan, 0, 0, 0, 0, &mbxname_dsc,
CMB$M_WRITEONLY, 0);
if (!(status & 1))
{
fprintf (stderr, "Server unable to open mailbox,
status = %x", status);
return 0;
}
/* Open for business. Loop looking for and processing requests.
*/
while (TRUE)
{
printf ("Input command: ");
gets (&line_buf);
(continued on next page)
15–17
Debugging Multiprocess Programs
15.17 Examples
Example 15–4 (Cont.) server.c
status = sys$clref (write_ef);
if (!(status & 1))
{
fprintf (stderr, "Client unable to clear read event flag,
status = %x", status);
return 0;
}
status = sys$qiow (write_ef, mbxchan,
IO$_SETMODE | IO$M_READERWAIT, &myiosb,
0, 0, 0, 0, 0, 0, 0, 0);
if ((status) && (myiosb.iosb$w_status))
{
status = sys$clref (write_ef);
if (!(status & 1))
{
fprintf (stderr, "Client unable to clear read event flag,
status = %x", status);
return 0;
}
if (strlen (line_buf) == 0)
status = sys$qio (write_ef, mbxchan, IO$_WRITEOF | IO$M_READERCHECK, &myiosb,
0, 0, 0, 0, 0, 0, 0, 0);
else
status = sys$qio (write_ef, mbxchan, IO$_WRITEVBLK | IO$M_READERCHECK, &myiosb,
0, 0, line_buf, strlen (line_buf), 0, 0, 0, 0);
if (status)
{
status = sys$waitfr (write_ef);
if ((myiosb.iosb$w_status & 1) && (status & 1))
{
if (strlen (line_buf) == 0)
break;
}
else
fprintf (stderr, "Server failure during write,
status = %x, iosb$w_status = %x\n",
status, myiosb.iosb$w_status);
}
else
fprintf (stderr, "Server failure for write request,
status = %x\n", status);
}
else
fprintf (stderr, "Server failure during wait for reader,
status = %x, iosb$w_status = %x\n",
status, myiosb.iosb$w_status);
}
printf ("\n\nServer done...exiting\n");
return 1;
}
Example 15–5 client.c
(continued on next page)
15–18
Debugging Multiprocess Programs
15.17 Examples
Example 15–5 (Cont.) client.c
#include
#include
#include
#include
#include
#include
#include
#include
#include
#include
<stdio.h>
<starlet.h>
<cmbdef.h>
<types.h>
<descrip.h>
<efndef.h>
<iodef.h>
<iosbdef.h>
<ssdef.h>
<string.h>
#include "mbxtest.h"
int main (int argc, char **argv)
{
unsigned int status, read_ef;
iosb myiosb;
short mbxchan;
char line_buf [LINE_MAX_LEN];
/* Get event flag. Look for or create the mailbox.
*/
status = lib$get_ef (&read_ef);
if (!(status & 1))
{
fprintf (stderr, "Client unable to get eventflag, status = %x", status);
return 0;
}
status = sys$crembx (0, &mbxchan, 0, 0, 0, 0, &mbxname_dsc, CMB$M_READONLY, 0);
if (!(status & 1))
{
fprintf (stderr, "Client unable to open mailbox, status = %x", status);
return 0;
}
/* Loop requesting, receiving, and processing new data.
*/
memset (&myiosb, 0, sizeof(myiosb));
(continued on next page)
15–19
Debugging Multiprocess Programs
15.17 Examples
Example 15–5 (Cont.) client.c
while (myiosb.iosb$w_status != SS$_ENDOFFILE)
{
status = sys$qiow (read_ef, mbxchan, IO$_SETMODE | IO$M_WRITERWAIT, &myiosb,
0, 0, 0, 0, 0, 0, 0, 0);
if ((status) && (myiosb.iosb$w_status))
{
status = sys$clref (read_ef);
if (!(status & 1))
{
fprintf (stderr, "Client unable to clear read event flag, status = %x", status);
return 0;
}
status = sys$qio (read_ef, mbxchan, IO$_READVBLK | IO$M_WRITERCHECK, &myiosb,
0, 0, line_buf, sizeof(line_buf), 0, 0, 0, 0);
if (status)
{
status = sys$waitfr (read_ef);
if ((myiosb.iosb$w_status & 1) && (status & 1))
puts (line_buf);
else if ((myiosb.iosb$w_status != SS$_NOWRITER) &&
(myiosb.iosb$w_status != SS$_ENDOFFILE))
fprintf (stderr, "Client failure during read,
status = %x, iosb$w_status = %x\n",
status, myiosb.iosb$w_status);
}
else
fprintf (stderr, "Client failure for read request, status = %x\n", status);
}
else
fprintf (stderr, "Client failure during wait for writer,
status = %x, iosb$w_status = %x\n",
status, myiosb.iosb$w_status);
status = sys$clref (read_ef);
if (!(status & 1))
{
fprintf (stderr, "Client unable to clear read event flag,
status = %x", status);
return 0;
}
}
printf ("\nClient done...exiting\n");
return 1;
}
The header file included in Example 15–4 and Example 15–5, mbxtest.h is shown
below.
$DESCRIPTOR(mbxname_dsc, "dbg$mptest_mbx");
#define LINE_MAX_LEN 255
15–20
16
Debugging Tasking Programs
This chapter describes features of the debugger that are specific to multithread
programs (also called tasking programs). Tasking programs consist of multiple
tasks, or threads, executing concurrently in a single process. Within the
debugger, the term task denotes such a flow of control regardless of the language
or implementation. The debugger’s tasking support applies to all such programs.
These programs include the following:
•
Programs written in any language that use POSIX Threads or POSIX 1003.1b
services. When debugging these programs, the debugger default event facility
is THREADS. Alpha and Integrity servers makes use of POSIX Threads
services.
•
Programs that use language-specific tasking services (services provided
directly by the language). Currently, Ada is the only language with built-in
tasking services that the debugger supports. When debugging Ada programs,
the debugger default event facility is ADA.
Note
Within the debugger, the terms task and thread are synonyms.
When you are debugging programs linked with PTHREAD$RTL Version
7.1 or greater, you can directly access the Compaq POSIX Threads
debugger with the PTHREAD command.
In this chapter, any language-specific information or information specific to
POSIX Threads is identified as such. Section 16.1 provides a cross-reference
between POSIX Threads terminology and Ada tasking terminology.
The features described in this chapter enable you to perform functions such as:
•
Displaying task information
•
Modifying task characteristics to control task execution, priority, state
transitions, and so on
•
Monitoring task-specific events and state transitions
When using these features, remember that the debugger might alter the
behavior of a tasking program from run to run. For example, while you are
suspending execution of the currently active task at a breakpoint, the delivery
of an asynchronous system trap (AST) or a POSIX signal as some input/output
(I/O) completes might make some other task eligible to run as soon as you allow
execution to continue.
16–1
Debugging Tasking Programs
For more information about POSIX Threads, see the Guide to POSIX Threads
Library. For more information about Ada tasks, see the Compaq Ada
documentation.
The debugging of multiprocess programs (programs that run in more than one
process) is described in Chapter 15.
16.1 Comparison of POSIX Threads and Ada Terminology
Table 16–1 compares POSIX Threads and Ada terminology and concepts.
Table 16–1 Comparison of POSIX Threads and Ada Terminology
POSIX Threads
Terminology
Ada Terminology
Description
Thread
Task
The flow of control within a
process
Thread object
Task object
The data item that represents
the flow of control
Object name or expression
Task name or expression
The data item that represents
the flow of control
Start routine
Task body
The code that is executed by the
flow of control
Not applicable
Master task
A parent flow of control
Not applicable
Dependent task
A child flow of control that is
controlled by some parent
Synchronization object
(mutex, condition variable)
Rendezvous construct
such as an entry call or
accept statement
Method of synchronizing flows
of control
Scheduling policy and
scheduling priority
Task priority
Method of scheduling execution
Alert operation
Abort statement
Method of canceling a flow of
control
Thread state
Task state
Execution state (waiting, ready,
running, terminated)
Thread creation attribute
(priority, scheduling policy,
and so on)
Pragma
Attributes of the parallel entity
16.2 Sample Tasking Programs
The following sections present sample tasking programs with common errors that
you might encounter when debugging tasking programs:
•
Section 16.2.1 describes a C program that uses POSIX Threads services
•
Section 16.2.2 describes an Ada program that uses the built-in Ada tasking
services
Some other examples in this chapter are derived from these programs.
16–2
Debugging Tasking Programs
16.2 Sample Tasking Programs
16.2.1 Sample C Multithread Program
Example 16–1 is a multithread C program that shows incorrect use of condition
variables, which results in blocking.
Explanatory notes are included after the example. Following these notes are
instructions showing how to use the debugger to diagnose the blocking by
controlling the relative execution of the threads.
In Example 16–1, the initial thread creates two worker threads that do some
computational work. After the worker threads are created, a SHOW TASK/ALL
command will show three tasks, each corresponding to a thread (Section 16.4
explains how to use the SHOW TASK command).
•
%TASK 1 is the initial thread, which executes from main( ). (Section 16.3.3
defines task IDs, such as %TASK 1.)
•
%TASK 2 and %TASK 3 are the worker threads.
In Example 16–1, a synchronization point (a condition wait) has been placed in
the workers’ path at line 3893. (The comment starting at line 3877 indicates that
a straight call such as this one is incorrect programming and shows the correct
code.)
When the program executes, the worker threads are busy computing when the
initial thread broadcasts on the condition variable. The first thread to wait on
the condition variable detects the initial thread’s broadcast and clears it, which
leaves any remaining threads stranded. Execution is blocked and the program
cannot terminate.
Example 16–1 Sample C Multithread Program
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3799
3790
3791
3792
3793
3794
3795
3796
3787
3798
3799
3800
3801
3802
3803
3804
/* DEFINES */
#define NUM_WORKERS 2
/* Number of worker threads
/* MACROS
#define check(status,string) \
if (status == -1) perror (string); \
/* GLOBALS
int
pthread_mutex_t
pthread_cond_t
pthread_mutex_t
cv_pred1;
cv_mutex;
cv;
print_mutex;
/*
/*
/*
/*
*/
*/
Condition Variable predicate */
Condition Variable mutex
*/
Condition Variable
*/
Print mutex
*/
/* ROUTINES
static pthread_startroutine_t
worker_routine (pthread_addr_t arg);
main ()
{
pthread_t
int
int
int
int
*/
threads[NUM_WORKERS];
status;
exit;
result;
i;
/*
/*
/*
/*
/*
*/
Worker threads
Return statuses
Join exit status
Join result value
Loop index
*/
*/
*/
*/
*/
/* Initialize mutexes
*/
status = pthread_mutex_init (&cv_mutex, pthread_mutexattr_default);
check (status, "cv_mutex initialization bad status");
(continued on next page)
16–3
Debugging Tasking Programs
16.2 Sample Tasking Programs
Example 16–1 (Cont.) Sample C Multithread Program
3805
status = pthread_mutex_init (&print_mutex, pthread_mutexattr_default);
3806
check (status, "print_mutex intialization bad status");
3807
3808
/* Initialize condition variable
*/
3809
status = pthread_cond_init (&cv, pthread_condattr_default);
3810
check (status, "cv condition init bad status");
3811
3812
/* Initialize condition variable predicate.
*/
3813
cv_pred1 = 1;
!
3814
3815
/* Create worker threads
*/
"
3816
for (i = 0; i < NUM_WORKERS; i++) {
3817
status = pthread_create (
3818
&threads[i],
3819
pthread_attr_default,
3820
worker_routine,
3821
0);
3822
check (status, "threads create bad status");
3823
}
3824
3825
/* Set cv_pred1 to false; do this inside the lock to insure visibility. */
3826
3827
status = pthread_mutex_lock (&cv_mutex);
3828
check (status, "cv_mutex lock bad status");
3829
3830
cv_pred1 = 0;
#
3831
3832
status = pthread_mutex_unlock (&cv_mutex);
3833
check (status, "cv_mutex unlock bad status");
3834
3835
/* Broadcast. */
$
3836
status = pthread_cond_broadcast (&cv);
3837
check (status, "cv broadcast bad status");
3838
3839
/* Attempt to join both of the worker threads. */
%
3840
for (i = 0; i < NUM_WORKERS; i++) {
3841
exit = pthread_join (threads[i], (pthread_addr_t*)&result);
3842
check (exit, "threads join bad status");
3843
}
3844
}
3845
3846 static pthread_startroutine_t
3847 worker_routine(arg)
3848
pthread_addr_t arg;
&
3849
{
3850
int sum;
3851
int iterations;
3852
int count;
3853
int status;
3854
3855
/* Do many calculations
*/
3856
for (iterations = 1; iterations < 10001; iterations++) {
3857
sum = 1;
3858
for (count = 1; count < 10001; count++) {
3859
sum = sum + count;
3860
}
3861
}
3862
3863
/* Printf may not be reentrant, so allow 1 thread at a time */
3864
3865
status = pthread_mutex_lock (&print_mutex);
(continued on next page)
16–4
Debugging Tasking Programs
16.2 Sample Tasking Programs
Example 16–1 (Cont.) Sample C Multithread Program
3866
check (status, "print_mutex lock bad status");
3867
printf (" The sum is %d \n", sum);
3868
status = pthread_mutex_unlock (&print_mutex);
3869
check (status, "print_mutex unlock bad status");
3870
3871
/* Lock the mutex associated with this condition variable. pthread_cond_wait will */
3872
/* unlock the mutex if the thread blocks on the condition variable.
*/
3873
3874
status = pthread_mutex_lock (&cv_mutex);
3875
check (status, "cv_mutex lock bad status");
3876
3877
/* In the next statement, the correct condition-wait syntax would be to loop
*/
3878
/* around the condition-wait call, checking the predicate associated with the
*/
3879
/* condition variable. This would guard against condition waiting on a condition */
3880
/* variable that may have already been broadcast upon, as well as spurious wake */
3881
/* ups. Execution would resume when the thread is woken AND the predicate is
*/
3882
/* false. The call would look like this:
*/
3883
/*
*/
3884
/*
while (cv_pred1) {
*/
3885
/*
status = pthread_cond_wait (&cv, &cv_mutex);
*/
3886
/*
check (status, "cv condition wait bad status");
*/
3887
/*
}
*/
3888
/*
*/
3888
/* A straight call, as used in the following code, might cause a thread to
*/
3890
/* wake up when it should not (spurious) or become permanently blocked, as
*/
3891
/* should one of the worker threads here.
*/
3892
’
3893
status = pthread_cond_wait (&cv, &cv_mutex);
3894
check (status, "cv condition wait bad status");
3895
3896
/* While blocking in the condition wait, the routine lets go of the mutex, but
*/
3897
/* it retrieves it upon return.
*/
3898
3899
status = pthread_mutex_unlock (&cv_mutex);
3900
check (status, "cv_mutex unlock bad status");
3901
3902
return (int)arg;
3903
}
Key to Example 16–1:
! The first few statements of main( ) initialize the synchronization objects
used by the threads, as well as the predicate that is to be associated with
the condition variable. The synchronization objects are initialized with the
default attributes. The condition variable predicate is initialized such that a
thread that is looping on it will continue to loop. At this point in the program,
a SHOW TASK/ALL display lists %TASK 1.
" The worker threads %TASK 2 and %TASK 3 are created. Here the created
threads execute the same start routine (worker_routine) and can also reuse
the same call to pthread_create with a slight change to store the different
thread IDs. The threads are created using the default attributes and are
passed an argument that is not used in this example.
# The predicate associated with the condition variable is cleared in preparation
to broadcast. This ensures that any thread awaking off the condition variable
has received a valid wake-up and not a spurious one. Clearing the predicate
also prevents any new arrivals from waiting on the condition variable because
it has been broadcast or signaled upon. (The desired effect depends on correct
16–5
Debugging Tasking Programs
16.2 Sample Tasking Programs
coding being used for the condition wait call at line 3893, which is not the
case in this example.)
$ The initial thread issues the broadcast call almost immediately, so that none
of the worker threads should yet be at the condition wait. A broadcast should
wake any threads currently waiting on the condition variable.
As the programmer, you should ensure that a broadcast is seen by either
ensuring that all threads are waiting on the condition variable at the time
of broadcast or ensuring that an associated predicate is used to flag that the
broadcast has already happened. (These measures have been left out of this
example on purpose.)
% The initial thread attempts to join with the worker threads to ensure that
they exited properly.
& When the worker threads execute worker_routine, they spend time doing
many computations. This allows the initial thread to broadcast on the
condition variable before either of the worker threads is waiting on it.
’ The worker threads then proceed to execute a pthread_cond_wait call by
performing locks around the call as required. It is here that both worker
threads will block, having missed the broadcast. A SHOW TASK/ALL
command entered at this point will show both of the worker threads waiting
on a condition variable. (After the program is deadlocked in this way, you
must press Ctrl/C to return control to the debugger.)
The debugger enables you to control the relative execution of threads to diagnose
problems of the kind shown in Example 16–1. In this case, you can suspend
the execution of the initial thread and let the worker threads complete their
computations so that they will be waiting on the condition variable at the time of
broadcast. The following procedure explains how:
1. At the start of the debugging session, set a breakpoint on line 3836 to suspend
execution of the initial thread just before broadcast.
2. Enter the GO command to execute the initial thread and create the worker
threads.
3. At this breakpoint, which causes the execution of all threads to be suspended,
put the initial thread on hold with the SET TASK/HOLD %TASK 1 command.
4. Enter the GO command to let the worker threads continue execution. The
initial thread is on hold and cannot execute.
5. When the worker threads block on the condition variable, press Ctrl/C to
return control to the debugger at that point. A SHOW TASK/ALL command
should indicate that both worker threads are suspended in a condition wait
substate. (If not, enter GO to let the worker threads execute, press Ctrl/C,
and enter SHOW TASK/ALL, repeating the sequence until both worker
threads are in a condition wait substate.)
6. Enter the SET TASK/NOHOLD %TASK command 1 and then the GO
command to allow the initial thread to resume execution and broadcast. This
will enable the worker threads to join and terminate properly.
16–6
Debugging Tasking Programs
16.2 Sample Tasking Programs
16.2.2 Sample Ada Tasking Program
Example 16–2 demonstrates a number of common errors that you may encounter
when debugging tasking programs. This is an example from an OpenVMS Alpha
system running the OpenVMS Debugger. The calls to procedure BREAK in the
example mark points of interest where breakpoints could be set and the state of
each task observed. If you ran the example under debugger control, you could
enter the following commands to set breakpoints at each call to the procedure
BREAK and display the current state of each task:
DBG>
DBG>
DBG>
DBG>
DBG>
DBG>
DBG>
SET
SET
SET
SET
SET
SET
SET
BREAK
BREAK
BREAK
BREAK
BREAK
BREAK
BREAK
%LINE
%LINE
%LINE
%LINE
%LINE
%LINE
%LINE
37
61
65
81
87
91
105
DO
DO
DO
DO
DO
DO
DO
(SHOW
(SHOW
(SHOW
(SHOW
(SHOW
(SHOW
(SHOW
TASK/ALL)
TASK/ALL)
TASK/ALL)
TASK/ALL)
TASK/ALL)
TASK/ALL)
TASK/ALL)
The program creates four tasks:
•
An environment task that runs the main program, TASK_EXAMPLE. This
task is created before any library packages are elaborated (in this case,
TEXT_IO). The environment task has the task ID %TASK 1 in the SHOW
TASK displays.
•
A task object named FATHER. This task is declared by the main program,
and is designated %TASK 3 in the SHOW TASK displays.
•
A single task named CHILD. This task is declared by task FATHER, and is
designated %TASK 4 in the SHOW TASK displays.
•
A single task named MOTHER. This task is declared by the main program,
and is designated %TASK 2 in the SHOW TASK displays.
Example 16–2 Sample Ada Tasking Program
1 --Tasking program that demonstrates various tasking conditions.
2
3 with TEXT_IO; use TEXT_IO;
4 procedure TASK_EXAMPLE is !
5
6 pragma TIME_SLICE(0.0); -- Disable time slicing. "
7
8
task type FATHER_TYPE is
9
entry START;
10
entry RENDEZVOUS;
11
entry BOGUS; -- Never accepted, caller deadlocks.
12 end FATHER_TYPE;
13
14 FATHER : FATHER_TYPE; #
15
16 task body FATHER_TYPE is
17
SOME_ERROR : exception;
18
19
task CHILD is $
20
entry E;
21
end CHILD;
(continued on next page)
16–7
Debugging Tasking Programs
16.2 Sample Tasking Programs
Example 16–2 (Cont.) Sample Ada Tasking Program
22
23
task body CHILD is
24
begin
25
FATHER_TYPE.BOGUS; -- Deadlocks on call to its parent.
26
end CHILD;
-- Whenever a task-type name
27
-- (here, FATHER_TYPE) is used within the
28
-- task body, the name denotes the task
29
-- currently executing the body.
30 begin -- (of FATHER_TYPE body)
31
32
accept START do
33
-- Main program is now waiting for this rendezvous completion,
34
-- and CHILD is suspended when it calls the entry BOGUS.
35
36
null;
37 <<B1>>
end START;
38
39
PUT_LINE("FATHER is now active and"); %
40
PUT_LINE("is going to rendezvous with main program.");
41
42
for I in 1..2 loop
43
select
44
accept RENDEZVOUS do
45
PUT_LINE("FATHER now in rendezvous with main program");
46
end RENDEZVOUS;
47
or
48
terminate;
49
end select;
50
51
if I = 2 then
52
raise SOME_ERROR;
53
end if;
54
end loop;
55
56 exception
57
when OTHERS =>
58
-- CHILD is suspended on entry call to BOGUS.
59
-- Main program is going to delay while FATHER terminates.
60
-- Mother in suspended state with "Not yet activated" sub state.
61<<B2>>
abort CHILD;
62
-- CHILD is now abnormal due to the abort statement.
63
64
65<<B3>>
raise; -- SOME_ERROR exception terminates
66
FATHER.
67 end FATHER_TYPE; &
68
69 task MOTHER is ’
70
entry START;
71
pragma PRIORITY (6);
72 end MOTHER;
73
74 task body MOTHER is
75 begin
76
accept START;
77
-- At this point, the main program is waiting for its dependents
78
-- (FATHER and MOTHER) to terminate. FATHER is terminated.
79
80
null;
81<<B4>> end MOTHER;
(continued on next page)
16–8
Debugging Tasking Programs
16.2 Sample Tasking Programs
Example 16–2 (Cont.) Sample Ada Tasking Program
82
83 begin
-- (of TASK_EXAMPLE)(
84
-- FATHER is suspended at accept start, and
85
-- CHILD is suspended in its deadlock.
86
-- Mother in suspended state with "Not yet activated" sub state.
87<<B5>>
FATHER.START; )
88
-- FATHER is suspended at the ’select’ or ’terminate’ statement.
89
90
91<<B6>>
FATHER.RENDEZVOUS;
92
FATHER.RENDEZVOUS; +>
93
loop +?
94
-- This loop causes the main program to busy wait for termination of
95
-- FATHER, so that FATHER can be observed in its terminated state.
96
if FATHER’TERMINATED then
97
exit;
98
end if;
99
delay 10.0;
-- 10.0 so that MOTHER is suspended
100 end loop;
-- at the ’accept’ statement (increases determinism).
101
102 -- FATHER has terminated by now with an unhandled
103
-- exception, and CHILD no longer exists because its
104
-- master (FATHER) has terminated. Task MOTHER is ready.
105<<B7>> MOTHER.START; [email protected]
106
-- The main program enters a wait-for-dependents state
107
-- so that MOTHER can finish executing.
108 end TASK_EXAMPLE; +A
Key to Example 16–2:
! After all of the Ada library packages are elaborated (in this case, TEXT_
IO), the main program is automatically called and begins to elaborate its
declarative part (lines 5 through 68).
" To ensure repeatability from run to run, the example uses no time slicing
The 0.0 value for the pragma TIME_SLICE documents that the procedure
TASK_EXAMPLE needs to have time slicing disabled.
On Alpha processors, pragma TIME_SLICE (0.0) must be used to disable time
slicing.
# Task object FATHER is elaborated, and a task designated %TASK 3 is
created. FATHER has no pragma PRIORITY, and thus assumes a default
priority. FATHER (%TASK 3) is created in a suspended state and is not
activated until the beginning of the statement part of the main program (line
69), in accordance with Ada rules. The elaboration of the task body on lines
16 through 67 defines the statements that tasks of type FATHER_TYPE will
execute.
$ Task FATHER declares a single task named CHILD (line 19). A single task
represents both a task object and an anonymous task type. Task CHILD is
not created or activated until FATHER is activated.
% The only source of asynchronous system traps (ASTs) is this series of TEXT_
IO.PUT_LINE statements (I/O completion delivers ASTs).
& The task FATHER is activated while the main program waits. FATHER has
no pragma PRIORITY and this assumes a default priority of 7. (See the
DEC Ada Language Reference Manual for the rules about default priorities.)
FATHER’s activation consists of the elaboration of lines 16 through 29.
16–9
Debugging Tasking Programs
16.2 Sample Tasking Programs
When task FATHER is activated, it waits while its task CHILD is activated
and a task designated %TASK 4 is created. CHILD executes one entry call
on line 25, and then deadlocks because the entry is never accepted (see
Section 16.7.1).
Because time slicing is disabled and there are no higher priority tasks to be
run, FATHER will continue to execute past its activation until it is blocked at
the ACCEPT statement at line 32.
’ A single task, MOTHER, is defined, and a task designated %TASK 2 is
created. The pragma PRIORITY gives MOTHER a priority of 6.
( The task MOTHER begins its activation and executes line 74. After
MOTHER is activated, the main program (%TASK 1) is eligible to resume its
execution. Because %TASK 1 has the default priority 7, which is higher than
MOTHER’s priority, the main program resumes execution.
) This is the first rendezvous the main program makes with task FATHER.
After the rendezvous FATHER will suspend at the SELECT with
TERMINATE statement at line 43.
+> At the third rendezvous with FATHER, FATHER raises the exception SOME_
ERROR on line 52. The handler on line 57 catches the exception, aborts
the suspended CHILD task, and then reraises the exception; FATHER then
terminates.
+? A loop with a delay statement ensures that when control reaches line 102,
FATHER has executed far enough to be terminated.
[email protected] This entry call ensures that MOTHER does not wait forever for its rendezvous
on line 76. MOTHER executes the accept statement (which involves no other
statements), the rendezvous is completed, and MOTHER is immediately
switched off the processor at line 77 because its priority is only 6.
+A After its rendezvous with MOTHER, the main program (%TASK 1) executes
lines 106 through 108. At line 108, the main program must wait for all its
dependent tasks to terminate. When the main program reaches line 108, the
only nonterminated task is MOTHER (MOTHER cannot terminate until the
null statement at line 80 has been executed). MOTHER finally executes to its
completion at line 81. Now that all tasks are terminated, the main program
completes its execution. The main program then returns and execution
resumes with the command line interpreter.
16.3 Specifying Tasks in Debugger Commands
A task is an entity that executes in parallel with other tasks. A task is
characterized by a unique task ID (see Section 16.3.3), a separate stack, and a
separate register set.
The current definition of the active task and the visible task determine the
context for manipulating tasks. See Section 16.3.1.
When specifying tasks in debugger commands, you can use any of the following
forms:
16–10
•
A task (thread) name as declared in the program (for example, FATHER
in Section 16.2.2) or a language expression that yields a task value.
Section 16.3.2 describes Ada language expressions for tasks.
•
A task ID (for example, %TASK 2). See Section 16.3.3.
Debugging Tasking Programs
16.3 Specifying Tasks in Debugger Commands
•
A task built-in symbol (for example, %ACTIVE_TASK). See Section 16.3.4.
16.3.1 Definition of Active Task and Visible Task
The active task is the task that runs when a STEP, GO, CALL, or EXIT command
executes. Initially, it is the task in which execution is suspended when the
program is brought under debugger control. To change the active task during a
debugging session, use the SET TASK/ACTIVE command.
Note
The SET TASK/ACTIVE command does not work for POSIX Threads
(on OpenVMS Alpha and Integrity server systems) or for Ada on
OpenVMS Alpha and Integrity server systems, the tasking for which
is implemented via POSIX Threads. Instead of SET TASK/ACTIVE, use
the SET TASK/VISIBLE command on POSIX Threads for query-type
actions. Or, to gain control to step through a particular thread, use a
strategic placement of breakpoints.
The following command makes the task named CHILD the active task:
DBG> SET TASK/ACTIVE CHILD
The visible task is the task whose stack and register set are the current context
that the debugger uses when looking up symbols, register values, routine calls,
breakpoints, and so on. For example, the following command displays the value
of the variable KEEP_COUNT in the context of the visible task:
DBG> EXAMINE KEEP_COUNT
Initially, the visible task is the active task. To change the visible task, use the
SET TASK/VISIBLE command. This enables you to look at the state of other
tasks without affecting the active task.
You can specify the active and visible tasks in debugger commands by using
the built-in symbols %ACTIVE_TASK and %VISIBLE_TASK, respectively (see
Section 16.3.4).
See Section 16.5 for more information about using the SET TASK command to
modify task characteristics.
16.3.2 Ada Tasking Syntax
You declare a task either by declaring a single task or by declaring an object of a
task type. For example:
-- TASK TYPE declaration.
-task type FATHER_TYPE is
...
end FATHER_TYPE;
task body FATHER_TYPE is
...
end FATHER_TYPE;
-- A single task.
-task MOTHER is
...
end MOTHER;
16–11
Debugging Tasking Programs
16.3 Specifying Tasks in Debugger Commands
task body MOTHER is
...
end MOTHER;
A task object is a data item that contains a task value. A task object is created
when the program elaborates a single task or task object, when you declare
a record or array containing a task component, or when a task allocator is
evaluated. For example:
-- Task object declaration.
-FATHER : FATHER_TYPE;
-- Task object (T) as a component of a record.
-type SOME_RECORD_TYPE is
record
A, B: INTEGER;
T : FATHER_TYPE;
end record;
HAS_TASK : SOME_RECORD_TYPE;
-- Task object (POINTER1) via allocator.
-type A is access FATHER_TYPE;
POINTER1 : A := new FATHER_TYPE;
A task object is comparable to any other object. You refer to a task object in
debugger commands either by name or by path name. For example:
DBG> EXAMINE FATHER
DBG> EXAMINE FATHER_TYPE$TASK_BODY.CHILD
When a task object is elaborated, a task is created by the Compaq Ada Run-Time
Library, and the task object is assigned its task value. As with other Ada objects,
the value of a task object is undefined before the object is initialized, and the
results of using an uninitialized value are unpredictable.
The task body of a task type or single task is implemented in Compaq Ada as a
procedure. This procedure is called by the Compaq Ada Run-Time Library when a
task of that type is activated. A task body is treated by the debugger as a normal
Ada procedure, except that it has a specially constructed name.
To specify the task body in a debugger command, use the following syntax to refer
to tasks declared as task types:
task-type-identifier$TASK_BODY
Use the following syntax to refer to single tasks:
task-identifier$TASK_BODY
For example:
DBG> SET BREAK FATHER_TYPE$TASK_BODY
The debugger does not support the task-specific Ada attributes T’CALLABLE,
E’COUNT, T’STORAGE_SIZE, and T’TERMINATED, where T is a task type
and E is a task entry (see the Compaq Ada documentation for more information
on these attributes). You cannot enter commands such as EVALUATE
CHILD’CALLABLE. However, you can get the information provided by each
of these attributes with the debugger SHOW TASK command. For more
information, see Section 16.4.
16–12
Debugging Tasking Programs
16.3 Specifying Tasks in Debugger Commands
16.3.3 Task ID
A task ID is the number assigned to a task when it is created by the tasking
system. The task ID uniquely identifies a task during the entire execution of a
program.
A task ID has the following syntax, where n is a positive decimal integer:
%TASK n
You can determine the task ID of a task object by evaluating or examining the
task object. For example (using Ada path-name syntax):
DBG> EVALUATE FATHER
%TASK 3
DBG> EXAMINE FATHER
TASK_EXAMPLE.FATHER: %TASK 3
If the programming language does not have built-in tasking services, you must
use the EXAMINE/TASK command to obtain the task ID of a task.
Note that the EXAMINE/TASK/HEXADECIMAL command, when applied to a
task object, yields the hexadecimal task value. The task value is the address of
the task (or thread) control block of that task. For example (Ada example):
DBG> EXAMINE/HEXADECIMAL FATHER
TASK_EXAMPLE.FATHER: 0085A448
DBG>
The SHOW TASK/ALL command enables you to identify the task IDs that have
been assigned to all currently existing tasks. Some of these existing tasks may
not be immediately familiar to you for the following reasons:
•
A SHOW TASK/ALL display includes tasks created by subsystems such
as POSIX Threads, Remote Procedure Call services, and the C Run-Time
Library, not just the tasks associated with your application.
•
A SHOW TASK/ALL display includes task ID assignments that depend on
your operating system, your tasking service, and the generating subsystem.
The same tasking program, run on different systems or adjusted for different
services, will not identify tasks with the same decimal integer. The only
exception is %TASK 1, which all systems and services assign to the task that
executes the main program.
The following examples are derived from Example 16–1 and Example 16–2,
respectively:
DBG> SHOW
task id
%TASK
%TASK
%TASK
DBG>
TASK/ALL
state hold pri substate
1 READY HOLD 12
2 SUSP
12 Condition Wait
3 SUSP
12 Condition Wait
DBG> SHOW TASK/ALL
task id
state hold pri
%TASK 1
7
SUSP
* %TASK 3
7
READY
%TASK 4
7
SUSP
%TASK 2
6
SUSP
thread_object
Initial thread
THREAD_EX1\main\threads[0].field1
THREAD_EX1\main\threads[1].field1
substate
Entry call
thread_object
SHARE$ADARTL+393712
TASK_EXAMPLE.FATHER
Entry call
TASK_EXAMPLE.FATHER_TYPE$TASK_BODY.CHILD
Not yet activated TASK_EXAMPLE.MOTHER
16–13
Debugging Tasking Programs
16.3 Specifying Tasks in Debugger Commands
You can use task IDs to refer to nonexistent tasks in debugger conditional
statements. For example, if you ran your program once, and you discovered that
%TASK 2 and 3 were of interest, you could enter the following commands at the
beginning of your next debugging session before %TASK 2 or 3 was created:
DBG> SET BREAK %LINE 30 WHEN (%ACTIVE_TASK=%TASK 2)
DBG> IF (%CALLER=%TASK 3) THEN (SHOW TASK/FULL)
You can use a task ID in certain debugger commands before the task has been
created without the debugger reporting an error (as it would if you used a task
object name before the task object came into existence). A task does not exist
until the task is created. Later the task becomes nonexistent sometime after
it terminates. A nonexistent task never appears in a debugger SHOW TASK
display.
Each time a program runs, the same task IDs are assigned to the same tasks
so long as the program statements are executed in the same order. Different
execution orders can result from ASTs (caused by delay statement expiration
or I/O completion) being delivered in a different order. Different execution
orders can also result from time slicing being enabled. A given task ID is never
reassigned during the execution of the program.
16.3.4 Task Built-In Symbols
The debugger built-in symbols defined in Table 16–2 enable you to specify tasks
in command procedures and command constructs.
Table 16–2 Task Built-In Symbols
Built-in Symbol
Description
%ACTIVE_TASK
The task that runs when a GO, STEP, CALL, or EXIT
command executes.
%CALLER_TASK
(Applies only to Ada programs.) When an accept statement
executes, the task that called the entry that is associated with
the accept statement.
%NEXT_TASK
The task after the visible task in the debugger’s task list. The
ordering of tasks is arbitrary but consistent within a single run
of a program.
%PREVIOUS_TASK
The task previous to the visible task in the debugger’s task
list.
%VISIBLE_TASK
The task whose call stack and register set are the current
context for looking up symbols, register values, routine calls,
breakpoints, and so on.
Examples using these task built-in symbols follow.
The following command displays the task ID of the visible task:
DBG> EVALUATE %VISIBLE_TASK
The following command places the active task on hold:
DBG> SET TASK/HOLD %ACTIVE_TASK
The following command sets a breakpoint on line 25 that triggers only when task
CHILD executes that line:
DBG> SET BREAK %LINE 25 WHEN (%ACTIVE_TASK=CHILD)
16–14
Debugging Tasking Programs
16.3 Specifying Tasks in Debugger Commands
The symbols %NEXT_TASK and %PREVIOUS_TASK enable you to cycle through
the total set of tasks that currently exist. For example:
DBG> SHOW TASK %VISIBLE_TASK; SET TASK/VISIBLE %NEXT_TASK
DBG> SHOW TASK %VISIBLE_TASK; SET TASK/VISIBLE %NEXT_TASK
.
.
.
DBG> EXAMINE MONITOR_TASK
MOD\MONITOR_TASK: %TASK 2
DBG> WHILE %NEXT_TASK NEQ %ACTIVE DO (SET TASK %NEXT_TASK; SHOW CALLS)
16.3.4.1 Caller Task Symbol (Ada Only)
The symbol %CALLER_TASK is specific to Ada tasks. It evaluates to the task ID
of the task that called the entry associated with the accept statement. Otherwise,
it evaluates to %TASK 0. For example, %CALLER_TASK evaluates to %TASK 0
if the active task is not currently executing the sequence of statements associated
with the accept statement.
For example, suppose a breakpoint has been set on line 46 of Example 16–2
(within an accept statement). The accept statement in this case is executed
by task FATHER (%TASK 3) in response to a call of entry RENDEZVOUS by
the main program (%TASK 1). Thus, when an EVALUATE %CALLER_TASK
command is entered at this point, the result is the task ID of the calling task, the
main program:
DBG> EVALUATE %CALLER_TASK
%TASK 1
DBG>
When the rendezvous is the result of an AST entry call, %CALLER_TASK
evaluates to %TASK 0 because the caller is not a task.
16.4 Displaying Information About Tasks
To display information about one or more tasks of your program, use the SHOW
TASK command.
The SHOW TASK command displays information about existing (nonterminated)
tasks. By default, the command displays one line of information about the visible
task.
Section 16.4.1 and Section 16.4.2 describe the information displayed by a SHOW
TASK command for POSIX Threads and Ada tasks, respectively.
16.4.1 Displaying Information About POSIX Threads Tasks
The command SHOW TASK displays information about all of the tasks of the
program that currently exist (see Example 16–3).
Example 16–3 Sample SHOW TASK/ALL Display for POSIX Threads Tasks
(continued on next page)
16–15
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Example 16–3 (Cont.) Sample SHOW TASK/ALL Display for POSIX Threads
Tasks
!
task id
%TASK
%TASK
%TASK
%TASK
* %TASK
%TASK
%TASK
%TASK
%TASK
DBG>
"
#
$
%
state hold pri substate
1 SUSP
12 Condition Wait
2 SUSP
12 Mutex Wait
3 SUSP
12 Delay
4 SUSP
12 Mutex Wait
5 RUN
12
6 READY
12
7 SUSP
12 Mutex Wait
8 READY
12
9 TERM
12 Term. by alert
&
thread_object
Initial thread
T_EXAMP\main\threads[0].field1
T_EXAMP\main\threads[1].field1
T_EXAMP\main\threads[2].field1
T_EXAMP\main\threads[3].field1
T_EXAMP\main\threads[4].field1
T_EXAMP\main\threads[5].field1
T_EXAMP\main\threads[6].field1
T_EXAMP\main\threads[7].field1
Key to Example 16–3:
! The task ID (see Section 16.3.3). The active task is marked with an asterisk
( * ) in the leftmost column.
" The current state of the task (see Table 16–3). The task in the RUN
(RUNNING) state is the active task. Table 16–3 lists the state transitions
possible during program execution.
# Whether the task has been put on hold with a SET TASK/HOLD command as
explained in Section 16.5.1.
$ The task priority.
% The current substate of the task. The substate helps indicate the possible
cause of a task’s state. See Table 16–4.
& A debugger path name for the task (thread) object or the address of the task
object if the debugger cannot symbolize the task object.
Table 16–3 Generic Task States
16–16
Task State
Description
RUNNING
Task is currently running on the processor. This is the active task. A
task in this state can make a transition to the READY, SUSPENDED,
or TERMINATED state.
READY
Task is eligible to execute and waiting for the processor to be made
available. A task in this state can make a transition only to the
RUNNING state.
SUSPENDED
Task is suspended, that is, waiting for an event rather than for the
availability of the processor. For example, when a task is created, it
remains in the suspended state until it is activated. A task in this
state can make a transition only to the READY or TERMINATED
state.
TERMINATED
Task is terminated. A task in this state cannot make a transition to
another state.
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Table 16–4 POSIX Threads Task Substates
Task Substate
Description
Condition Wait
Task is waiting on a POSIX Threads condition variable.
Delay
Task is waiting at a call to a POSIX Threads delay.
Mutex Wait
Task is waiting on a POSIX Threads mutex.
Not yet started
Task has not yet executed its start routine.
Term. by alert
Task has been terminated by an alert operation.
Term. by exc
Task has been terminated by an exception.
Timed Cond Wait
Task is waiting on a timed POSIX Threads condition variable.
The SHOW TASK/FULL command provides detailed information about each
task selected for display. Example 16–4 shows the output of this command for a
sample POSIX Threads task.
Example 16–4 Sample SHOW TASK/FULL Display for a POSIX Threads Task
! task id
%TASK
"
#
state hold pri substate
4 SUSP
12 Delay
Alert is pending
Alerts are deferred
thread_object
T_EXAMP\main\threads[1].field1
Next pc:
SHARE$CMA$RTL+46136
Start routine:
T_EXAMP\thread_action
Scheduling policy: throughput
$
%
Stack storage:
Bytes in use:
Bytes available:
Reserved Bytes:
Guard Bytes:
’
1288
40185
10752
4095
Thread control block:
Size:
(
Total storage:
& Base:
293
SP:
Top:
00334C00
003346F8
00329A00
Address: 00311B78
56613
DBG>
Key to Example 16–4:
! Identifying information about the task.
" Bulletin-type information about something unusual.
# Next execution PC value and start routine.
$ Task scheduling policy.
% Stack storage information:
•
"Bytes in use:" the number of bytes of stack currently allocated.
•
"Bytes available:" the unused space in bytes.
•
"Reserved Bytes:" the storage allocated for handling stack overflow.
•
"Guard Bytes:" the size of the guard area or unwritable part of the
stack.
& Minimum and maximum addresses of the task stack.
16–17
Debugging Tasking Programs
16.4 Displaying Information About Tasks
’ Task (thread) control block information. The task value is the address, in
hexadecimal notation, of the task control block.
( The total storage used by the task. Adds together the task control block size,
the number of reserved bytes, the top guard size, and the storage size.
Figure 16–1 shows a task stack.
Figure 16–1 Diagram of a Task Stack
low address
top guard
reserved bytes
001EB600:
:top
address
storage
size
001F2C38:
:sp
001FD2FC:
:base
address
00077D40:
(490816)
bytes
in use
task control block
high address
ZK−5894A−GE
The SHOW TASK/STATISTICS command reports some statistics about
all tasks in your program. Example 16–5 shows the output of the SHOW
TASK/STATISTICS/FULL command for a sample program with POSIX Threads
tasks. This information enables you to measure the performance of your program.
The larger the number of total schedulings (also known as context switches), the
more tasking overhead there is.
16–18
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Example 16–5 Sample SHOW TASK/STAT/FULL Display for POSIX Threads
Tasks
task statistics
Total context switches:
Number of existing threads:
Total threads created:
DBG>
0
0
0
16.4.2 Displaying Task Information About Ada Tasks
The SHOW TASK/ALL command displays information about all of the tasks
of the program that currently exist—namely, tasks that have been created and
whose master has not yet terminated (see Example 16–6).
16–19
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Example 16–6 Sample SHOW TASK/ALL Display for Ada Tasks
DBG> SHOW TASK/ALL
!
task
%TASK
* %TASK
%TASK
%TASK
DBG>
"
id
1
2
3
4
#
$
%
&
state hold pri substate
thread_object
READY
24
main thread
RUN
24
1515464
READY
19
1519768
SUSP
24 Timed Condition Wait 4932680
Key to Example 16–6:
! The task ID (see Section 16.3.3). An asterisk indicates that the task is a
visible task.
" The current state of the task (see Table 16–3). The task that is in the RUN
(RUNNING) state is the active task. Table 16–3 lists the state transitions
possible during program execution.
# Whether the task has been put on hold with a SET TASK/HOLD command
as explained in Section 16.5.1. Placing a task on HOLD restricts the state
transitions it can make after the program is subsequently allowed to execute.
$ The task priority. Ada priorities range from 0 to 15. On Alpha systems, a
task with an undefined priority competes with other tasks, as if having a midrange priority (between 7 and 8). Ada provides the following two mechanisms
for controlling task priorities:
•
Pragma PRIORITY A priority is associated with a task if a pragma
PRIORITY appears in the corresponding task specification or in the
outermost declarative part of a main subprogram.
•
Types and operations in the Ada package SET_TASK_PRIORITY. Ada
allows task priorities to be changed dynamically at run-time to values of
the subtype PRIORITY.
% The current substate of the task. The substate helps indicate the possible
cause of a task’s state. See Table 16–5.
& A debugger path name for the task object or the address of the task object if
the debugger cannot symbolize the task object.
Table 16–5 Ada Task Substates
Task Substate
Description
Abnormal
Task has been aborted.
Accept
Task is waiting at an accept statement that is not inside a select
statement.
Activating
Task is elaborating its declarative part.
Activating tasks
Task is waiting for tasks it has created to finish activating.
(continued on next page)
16–20
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Table 16–5 (Cont.) Ada Task Substates
Task Substate
Description
Completed [abn]
Task is completed due to an abort statement but is not yet
terminated. In Ada, a completed task is one that is waiting
for dependent tasks at its end statement. After the dependent
tasks are terminated, the state changes to terminated.
Completed [exc]
Task is completed due to an unhandled exception1 but is not yet
terminated. In Ada, a completed task is one that is waiting for
dependent tasks at its end statement. After the dependent tasks
are terminated, the state changes to terminated.
Completed
Task is completed. No abort statement was issued and no
unhandled exception1 occurred.
Delay
Task is waiting at a delay statement.
Dependents
Task is waiting for dependent tasks to terminate.
Dependents [exc]
Task is waiting for dependent tasks to allow an unhandled
exception1 to propagate.
Entry call
Task is waiting for its entry call to be accepted.
Invalid state
There is an error in the Compaq Ada Run-Time Library.
I/O or AST
Task is waiting for I/O completion or some AST.
Not yet activated
Task is waiting to be activated by the task that created it.
Select or delay
Task is waiting at a select statement with a delay
alternative.
Select or terminate
Task is waiting at a select statement with a terminate alternative.
Select
Task is waiting at a select statement with no else, delay, or
terminate alternative.
Shared resource
Task is waiting for an internal shared resource.
Terminated [abn]
Task was terminated by an abort statement.
Terminated [exc]
Task was terminated because of an unhandled exception.1
Terminated
Task terminated normally.
Timed entry call
Task is waiting in a timed entry call.
1
An unhandled exception is one for which there is no handler in the current frame or for which there
is a handler that executes a raise statement and propagates the exception to an outer scope.
Figure 16–1 shows a task stack.
The SHOW TASK/FULL command provides detailed information about each
task selected for display. Example 16–7 shows the output of this command for a
sample Ada task.
Example 16–7 Sample SHOW TASK/FULL Display for an Ada Task
! task id
%TASK 1
"
state hold pri substate
RUN
24
thread_object
1515464
Cancellation is enabled
(continued on next page)
16–21
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Example 16–7 (Cont.) Sample SHOW TASK/FULL Display for an Ada Task
Next pc:
Start routine:
Scheduling policy:
#
%
(unknown)
1380128
fifo
Stack storage:
Bytes in use:
Bytes available:
Reserved Bytes:
Guard Bytes:
7069696
-4972544
0
0
Thread control block:
Size:
5856
& Total storage:
DBG>
(real-time)
$ Base:
SP:
Top:
00000000006BE000
0000000000000000
00000000004BE000
Address: 00000000006BF280
2103008
Key to Example 16–7:
! Identifying information about the task.
" Rendezvous information. If the task is a caller task, it lists the entries for
which it is queued. If the task is to be called, it gives information about the
kind of rendezvous that will take place and lists the callers that are currently
queued for any of the task’s entries.
# Stack storage information:
•
"Bytes in use:" the number of bytes of stack currently allocated.
•
"Bytes available:" the unused space in bytes.
•
"Reserved Bytes:" the storage allocated for handling stack overflow.
•
"Guard Bytes:" the size of the guard area or unwritable part of the
stack.
$ Minimum and maximum addresses of the task stack.
•
"SP:" Stack Pointer indicates a location in the stack memory.
•
"TOP:" indicates the last allocated stack location.
% Task (thread) control block information. The task value is the address, in
hexadecimal notation, of the task control block.
& The total storage used by the task. Adds together the task control block size,
the number of reserved bytes, the top guard size, and the storage size.
The SHOW TASK/STATISTICS command reports some statistics about all
tasks in your program. Example 16–8 shows the output of the SHOW
TASK/STATISTICS/FULL command for a sample Ada tasking program on a
VAX system. This information enables you to measure the performance of your
program. The larger the number of total schedulings (also known as context
switches), the more tasking overhead there is.
Example 16–8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks
(continued on next page)
16–22
Debugging Tasking Programs
16.4 Displaying Information About Tasks
Example 16–8 (Cont.) Sample SHOW TASK/STATISTICS/FULL Display for Ada
Tasks
DBG> SHOW TASK/STATISTICS/FULL
task statistics
Total context switches:
Number of existing threads:
Total threads created:
DBG>
0
6
4
16–23
Debugging Tasking Programs
16.5 Changing Task Characteristics
16.5 Changing Task Characteristics
To modify a task’s characteristics or the tasking environment while debugging,
use the SET TASK command, as shown in the following table:
Command
Description
SET TASK/ACTIVE
Makes a specified task the active task; not for POSIX
Threads (on OpenVMS Alpha or Integrity servers) or Ada on
OpenVMS Alpha and Integrity servers (see Section 16.3.1).
SET TASK/VISIBLE
Makes a specified task the visible task (see Section 16.3.1).
SET TASK/ABORT
Requests that a task 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.
SET TASK/PRIORITY
Sets a task’s priority. The exact effect depends on the current
event facility (language dependent).
SET TASK/RESTORE
Restores a task’s priority. The exact effect depends on the
current event facility (language dependent).
SET TASK/[NO]HOLD
Controls task switching (task state transitions, see
Section 16.5.1).
For more information, see the SET TASK command description.
16.5.1 Putting Tasks on Hold to Control Task Switching
Task switching might be confusing when you are debugging a program. Placing a
task on hold with the SET TASK/HOLD command restricts the state transitions
the task can make once the program is subsequently allowed to execute.
A task placed on hold can enter any state except the RUNNING state. If
necessary, you can force it into the RUNNING state by using the SET
TASK/ACTIVE command.
The SET TASK/HOLD/ALL command freezes the state of all tasks except
the active task. You can use this command in combination with the SET
TASK/ACTIVE command, to observe the behavior of one or more specified tasks
in isolation, by executing the active task with the STEP or GO command, and
then switching execution to another task with the SET TASK/ACTIVE command.
For example:
DBG>
DBG>
DBG>
.
.
.
DBG>
DBG>
.
.
.
SET TASK/HOLD/ALL
SET TASK/ACTIVE %TASK 1
GO
SET TASK/ACTIVE %TASK 3
STEP
When you no longer want to hold a task, use the SET TASK/NOHOLD command.
16–24
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
16.6 Controlling and Monitoring Execution
The following sections explain how to do the following functions:
•
Set task-specific and task-independent eventpoints (breakpoints, tracepoints,
and so on)
•
Set breakpoints and tracepoints on task locations specific to POSIX Threads
•
Set breakpoints and tracepoints on task locations specific to Ada
•
Monitor task events with the SET BREAK/EVENT or SET TRACE/EVENT
commands
16.6.1 Setting Task-Specific and Task-Independent Debugger Eventpoints
An eventpoint is an event that you can use to return control to the debugger.
Breakpoints, tracepoints, watchpoints, and the completion of STEP commands
are eventpoints.
A task-independent eventpoint can be triggered by the execution of any task
in a program, regardless of which task is active when the eventpoint is set. Taskindependent eventpoints are generally specified by an address expression such as
a line number or a name. All watchpoints are task-independent eventpoints. The
following are examples of setting task-independent eventpoints:
DBG> SET BREAK COUNTER
DBG> SET BREAK/NOSOURCE %LINE 55, CHILD$TASK_BODY
DBG> SET WATCH/AFTER=3 KEEP_COUNT
A task-specific eventpoint can be set only for the task that is active when
the command is entered. A task-specific eventpoint is triggered only when that
same task is active. For example, the STEP/LINE command is a task-specific
eventpoint: other tasks might execute the same source line and not trigger the
event.
If you use the SET BREAK, SET TRACE, or STEP commands with the following
qualifiers, the resulting eventpoints are task specific:
/BRANCH
/CALL
/INSTRUCTION
/LINE
/RETURN
Any other eventpoints that you set with those commands and any eventpoints
that you set with the SET WATCH command are task independent. The following
are examples of setting task-specific eventpoints:
DBG> SET BREAK/INSTRUCTION
DBG> SET TRACE/INSTRUCTION/SILENT DO (EXAMINE KEEP_COUNT)
DBG> STEP/CALL/NOSOURCE
You can conditionalize eventpoints that are normally task-independent to make
them task specific. For example:
DBG> SET BREAK %LINE 11 WHEN (%ACTIVE_TASK=FATHER)
16–25
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
16.6.2 Setting Breakpoints on POSIX Threads Tasking Constructs
You can set a breakpoint on a thread start routine. The breakpoint will trigger
just before the start routine begins execution. In Example 16–1, this type of
breakpoint is set as follows:
DBG> SET BREAK worker_routine
Unlike Ada tasks, you cannot specify the body of a POSIX Threads task by name
but the start routine is similar.
Specifying a WHEN clause with the SET BREAK command ensures that you
catch the point at which a particular thread begins execution. For example:
DBG> SET BREAK worker_routine _DBG> WHEN (%ACTIVE_TASK = %TASK 4)
In Example 16–1, this conditional breakpoint will trigger when the second worker
thread begins executing its start routine.
Other useful places to set breakpoints are just prior to and immediately after
condition waits, joins, and locking of mutexes. You can set such breakpoints by
specifying either a line number or the routine name.
16.6.3 Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept
Statements
You can set a breakpoint on a task body by using one of the following syntaxes to
refer to the task body (see Section 16.3.2):
task-type-identifier$TASK_BODY
task-identifier$TASK_BODY
For example, the following command sets a breakpoint on the body of task
CHILD. This breakpoint is triggered just before the elaboration of the task’s
declarative part (also called the task’s activation).
DBG> SET BREAK CHILD$TASK_BODY
CHILD$TASK_BODY is a name for the address of the first instruction the task
will execute. It is meaningful to set a breakpoint on an instruction, and hence on
this name. However, you must not name the task object (for example, CHILD) in
a SET BREAK command. The task-object name designates the address of a data
item (the task value). Just as it is erroneous to set a breakpoint on an integer
object, it is erroneous to set a breakpoint on a task object.
You can monitor the execution of communicating tasks by setting breakpoints or
tracepoints on entry calls and accept statements.
Note
Ada task entry calls are not the same as subprogram calls because task
entry calls are queued and may not execute right away. If you use the
STEP command to move execution into a task entry call, the results
might not be what you expect.
There are several points in and around an accept statement where you might
want to set a breakpoint or tracepoint. For example, consider the following
program segment, which has two accept statements for the same entry,
RENDEZVOUS:
16–26
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
task body TWO_ACCEPTS is
begin
for I in 1..2 loop
select
accept RENDEZVOUS do
PUT_LINE("This is the first accept statement");
end RENDEZVOUS;
or
terminate;
end select;
end loop;
accept RENDEZVOUS do
PUT_LINE("This is the second accept statement");
end RENDEZVOUS;
end TWO_ACCEPTS;
You can set a breakpoint or tracepoint in the following places in this example:
•
At the start of an accept statement (line 12 or 19). By setting a breakpoint
or tracepoint here, you can monitor when execution reaches the start of the
accept statement, where the accepting task might become suspended before a
rendezvous actually occurs.
•
At the start of the body (sequence of statements) of an accept statement (line
13 or 20). By setting a breakpoint or tracepoint here, you can monitor when
a rendezvous has started—that is, when the accept statement actually begins
execution.
•
At the end of an accept statement (line 14 or 21). By setting a breakpoint or
tracepoint here, you can monitor when the rendezvous has completed, and
execution is about to switch back to the caller task.
To set a breakpoint or tracepoint in and around an accept statement, you can
specify the associated line number. For example, the following command sets a
breakpoint on the start and also on the body of the first accept statement in the
preceding example:
DBG> SET BREAK %LINE 12, %LINE 13
To set a breakpoint or a tracepoint on an accept statement body, you can also use
the entry name (specifying its expanded name to identify the task body where the
entry is declared). For example:
DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS
If there is more than one accept statement for an entry, the debugger treats the
entry as an overloaded name. The debugger issues a message indicating that
the symbol is overloaded, and you must use the SHOW SYMBOL command to
identify the overloaded names that have been assigned by the debugger. For
example:
DBG> SHOW SYMBOL RENDEZVOUS
overloaded symbol TEST.TWO_ACCEPTS$TASK_BODY.RENDEZVOUS
overloaded instance TEST.TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__1
overloaded instance TEST.TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__2
Overloaded names have an integer suffix preceded by two underscores. For
more information on overloaded names, see the debugger’s online help (type
Help Language_Support Ada).
16–27
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
To determine which of these overloaded names is associated with a particular
accept statement, use the EXAMINE/SOURCE command. For example:
DBG> EXAMINE/SOURCE TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__1
module TEST_ACCEPTS
12:
accept RENDEZVOUS do
DBG> EXAMINE/SOURCE TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__2
module TEST_ACCEPTS
19:
accept RENDEZVOUS do
In the following example, when the breakpoint triggers, the caller task is
evaluated (see Section 16.3.4 for information about the symbol %CALLER_TASK):
DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__2 _DBG> DO (EVALUATE %CALLER_TASK)
The following breakpoint triggers only when the caller task is %TASK 2:
DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__2 _DBG> WHEN (%CALLER_TASK = %TASK 2)
If the calling task has more than one entry call to the same accept statement, you
can use the SHOW TASK/CALLS command to identify the source line where the
entry call was issued. For example:
DBG> SET BREAK TWO_ACCEPTS$TASK_BODY.RENDEZVOUS__2 _DBG> DO (SHOW TASK/CALLS %CALLER_TASK)
16.6.4 Monitoring Task Events
The SET BREAK/EVENT and SET TRACE/EVENT commands enable you to
set breakpoints and tracepoints that are triggered by task and exception events.
For example, the following command sets tracepoints that trigger whenever task
CHILD or %TASK 2 makes a transition to the RUN state:
DBG> SET TRACE/EVENT=RUN CHILD,%TASK 2
When a breakpoint or tracepoint is triggered as a result of an event, the debugger
identifies the event and gives additional information.
The following tables list the event-name keywords that you can specify with the
SET BREAK/EVENT and SET TRACE/EVENT commands:
•
Table 16–6 lists the generic language-independent events common to all
tasks.
•
Table 16–7 lists the events specific to POSIX Threads tasks.
•
Table 16–8 lists the events specific to Ada tasks.
Table 16–6 Generic Low-Level Task Scheduling Events
Event Name
Description
RUN
Triggers when a task is about to run.
(continued on next page)
16–28
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
Table 16–6 (Cont.) Generic Low-Level Task Scheduling Events
Event Name
Description
PREEMPTED
Triggers when a task is being preempted from the RUN state and
its state changes to READY. (See Table 16–3.)
ACTIVATING
Triggers when a task is about to begin its execution.
SUSPENDED
Triggers when a task is about to be suspended.
Table 16–7 POSIX Threads-Specific Events
Event Name
Description
HANDLED
Triggers when an exception is about to be handled in
some TRY block.
TERMINATED
Triggers when a task is terminating (including by alert
or exception).
EXCEPTION_TERMINATED
Triggers when a task is terminating because of an
exception.
FORCED_TERM
Triggers when a task is terminating due to an alert
operation.
Table 16–8 Ada-Specific Events
Event Name
Description
HANDLED
Triggers when an exception is about to be handled
in some Ada exception handler, including an others
handler.
HANDLED_OTHERS
Triggers only when an exception is about to be handled
in an others Ada exception handler.
RENDEZVOUS_EXCEPTION
Triggers when an exception begins to propagate out of
a rendezvous.
DEPENDENTS_EXCEPTION
Triggers when an exception causes a task to
wait for dependent tasks in some scope (includes
unhandled exceptions,1 which, in turn, include special
exceptions internal to the Compaq Ada Run-Time
Library; for more information, see the Compaq
Ada documentation). Often immediately precedes
a deadlock.
TERMINATED
Triggers when a task is terminating, whether
normally, by an abort statement, or by an exception.
EXCEPTION_TERMINATED
Triggers when a task is terminating due to an
unhandled exception.1
ABORT_TERMINATED
Triggers when a task is terminating due to an abort
statement.
1
An unhandled exception is an exception for which there is no handler in the current frame or for
which there is a handler that executes a raise statement and propagates the exception to an outer
scope.
In the previous tables, the exception-related events are included for completeness.
Only the task events are discussed in the following paragraphs. For more
information about the exception events, see the debugger’s online help (type
Help Language_Support Ada).
16–29
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
You can abbreviate an event-name keyword to the minimum number of characters
that make it unique.
The event-name keywords that you can specify with the SET BREAK/EVENT
or SET TRACE/EVENT command depend on the current event facility, which
is either THREADS or ADA in the case of task events. The appropriate event
facility is set automatically when the program is brought under debugger control.
The SHOW EVENT_FACILITY command identifies the facility that is currently
set and lists the valid event name keywords for that facility (including those for
the generic events).
Several examples follow showing the use of the /EVENT qualifier:
DBG> SET BREAK/EVENT=PREEMPTED
DBG> GO
break on THREADS event PREEMPTED
Task %TASK 4 is getting preempted by %TASK 3
.
.
.
DBG> SET BREAK/EVENT=SUSPENDED
DBG> GO
break on THREADS event SUSPENDED
Task %TASK 1 is about to be suspended
.
.
.
DBG> SET BREAK/EVENT=TERMINATED
DBG> GO
break on THREADS event TERMINATED
Task %TASK 4 is terminating normally
DBG>
The following predefined event breakpoints are set automatically when the
program is brought under debugger control:
•
EXCEPTION_TERMINATED event breakpoints are predefined for programs
that call POSIX Threads routines.
•
EXCEPTION_TERMINATED and DEPENDENTS_EXCEPTION event
breakpoints are predefined for Ada programs or programs that call Ada
routines.
Ada examples of the predefined and other types of event breakpoints follow.
Example of EXCEPTION_TERMINATED Event
When the EXCEPTION_TERMINATED event is triggered, it usually indicates an
unanticipated program error. For example:
...
break on ADA event EXCEPTION_TERMINATED
Task %TASK 2 is terminating because of an exception
%ADA-F-EXCCOP, Exception was copied at a "raise;" or "accept"
-ADA-F-EXCEPTION, Exception SOME_ERROR
-ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61
DBG>
16–30
Debugging Tasking Programs
16.6 Controlling and Monitoring Execution
Example of DEPENDENTS_EXCEPTION Event (Ada)
For Ada programs, the DEPENDENTS_EXCEPTION event often unexpectedly
precedes a deadlock. For example:
...
break on ADA event DEPENDENTS_EXCEPTION
Task %TASK 2 may await dependent tasks because of this exception:
%ADA-F-EXCCOP, Exception was copied at a "raise;" or "accept"
-ADA-F-EXCEPTION, Exception SOME_ERROR
-ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61
DBG>
Example of RENDEZVOUS_EXCEPTION Event (Ada)
For Ada programs, the RENDEZVOUS_EXCEPTION event enables you to see an
exception before it leaves a rendezvous (before exception information has been
lost due to copying the exception into the calling task). For example:
...
break on ADA event RENDEZVOUS_EXCEPTION
Exception is propagating out of a rendezvous in task %TASK 2
%ADA-F-CONSTRAINT_ERRO, CONSTRAINT_ERROR
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000BA6
DBG>
To cancel breakpoints (or tracepoints) set with the /EVENT qualifier, use the
CANCEL BREAK/EVENT (or CANCEL TRACE/EVENT) command. Specify the
event qualifier and optional task expression in the CANCEL command exactly as
you did with the SET command, excluding any WHEN or DO clauses.
You might want to set event breakpoints and tracepoints in a debugger
initialization file for your tasking programs. For example:
SET
SET
SET
SET
SET
BREAK/EVENT=ACTIVATING
BREAK/EVENT=HANDLED DO (SHOW CALLS)
BREAK/EVENT=ABORT_TERMINATED DO (SHOW CALLS)
BREAK/EVENT=EXCEPTION_TERM DO (SHOW CALLS)
BREAK/EVENT=TERMINATED
16.7 Additional Task-Debugging Topics
The following sections discuss additional topics related to task debugging:
•
Deadlock
•
Automatic stack checking
•
Using Ctrl/Y
16.7.1 Debugging Programs with Deadlock Conditions
A deadlock is an error condition in which each task in a group of tasks is
suspended and no task in the group can resume execution until some other task
in the group executes. Deadlock is a typical error in tasking programs (in much
the same way that infinite loops are typical errors in programs that use WHILE
statements).
A deadlock is easy to detect: it causes your program to appear to suspend, or
hang, in midexecution. When deadlock occurs in a program that is running under
debugger control, press Ctrl/C to interrupt the deadlock and display the debugger
prompt.
16–31
Debugging Tasking Programs
16.7 Additional Task-Debugging Topics
In general, the SHOW TASK/ALL command (see Section 16.4) or the SHOW
TASK/STATE=SUSPENDED command is useful because it shows which tasks
are suspended in your program and why. The command SET TASK/VISIBLE
%NEXT_TASK is particularly useful when debugging in screen mode. It enables
you to cycle through all tasks and display the code that each task is executing,
including the code in which execution is stopped.
The SHOW TASK/FULL command gives detailed task state information,
including information about rendezvous, entry calls, and entry index values.
The SET BREAK/EVENT or SET TRACE/EVENT command (see Section 16.6.4)
enables you to set breakpoints or tracepoints at or near locations that might lead
to deadlock. The SET TASK/PRIORITY and SET TASK/RESTORE commands
enable you to see if a low-priority task that never runs is causing the deadlock.
Table 16–9 lists a number of tasking deadlock conditions and suggests debugger
commands that are useful in diagnosing the cause.
Table 16–9 Ada Tasking Deadlock Conditions and Debugger Commands for
Diagnosing Them
16–32
Deadlock Condition
Debugger Commands
Self-calling deadlock (a task calls
one of its own entries)
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
Circular-calling deadlock (a task
calls another task, which calls the
first task)
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
Dynamic-calling deadlock (a
circular series of entry calls exists,
and at least one of the calls is a
timed or conditional entry call in a
loop)
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
Exception-induced deadlock (an
exception prevents a task from
answering one of its entry calls,
or the propagation of an exception
must wait for dependent tasks)
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
SET BREAK/EVENT=DEPENDENTS_EXCEPTION
(for Ada programs)
Deadlock because of incorrect
run-time calculations for entry
indexes, when conditions, and
delay statements within select
statements
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
EXAMINE
Deadlock due to entries being
called in the wrong order
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
Deadlock due to busy-waiting on
a variable used as a flag that is to
be set by a lower priority task, and
the lower priority task never runs
because a higher priority task is
always ready to execute
SHOW TASK/ALL
SHOW TASK/STATE=SUSPENDED
SHOW TASK/FULL
SET TASK/PRIORITY
SET TASK/RESTORE
Debugging Tasking Programs
16.7 Additional Task-Debugging Topics
16.7.2 Automatic Stack Checking in the Debugger
In tasking programs, an undetected stack overflow can occur in certain
circumstances and can lead to unpredictable execution. (For more information
on task stack overflow, see the Compaq Ada or POSIX Threads documentation.)
The debugger automatically does the following stack checks to help you detect
the source of stack overflow problems (if the stack pointer is out of bounds, the
debugger displays an error message):
•
A stack check is done for the active task after a STEP command executes or
a breakpoint triggers (see Section 16.6.1). (This check is not done if you have
used the /SILENT qualifier with the STEP or SET BREAKPOINT command.)
•
A stack check is done for each task whose state is displayed in a SHOW
TASK command. Thus, a SHOW TASK/ALL command automatically causes
the stacks of all tasks to be checked.
The following examples show the kinds of error messages displayed by the
debugger when a stack check fails. A warning is issued when most of the stack
has been used up, even if the stack has not yet overflowed.
warning: %TASK 2 has used up over 90% of its stack
SP: 0011194C Stack top at: 00111200 Remaining bytes: 1868
error: %TASK 2 has overflowed its stack
SP: 0010E93C Stack top at: 00111200 Remaining bytes: -10436
error: %TASK 2 has underflowed its stack
SP: 7FF363A4 Stack base at: 001189FC Stack top at: 00111200
One of the unpredictable events that can happen after a stack overflows is that
the stack can then underflow. For example, if a task stack overflows and the stack
pointer remains in the top guard area, the operating system will attempt to signal
an ACCVIO condition. However, because the top guard area is not a writable
area of the stack, the operating system cannot write the signal arguments for the
ACCVIO. When this happens, the operating system cuts back the stack: it causes
the frame pointer and stack pointer to point to the base of the main program
stack area, writes the signal arguments, and then modifies the program counter
to force an image exit.
If a time-slice AST or other AST occurs at this instant, execution can resume in a
different task, and for a while, the program may continue to execute, although not
normally (the task whose stack overflowed may use—and overwrite—the main
program stack). The debugger stack checks help you to detect this situation. If
you step into a task whose stack has been cut back by the operating system, or
if you use the SHOW TASK/ALL command at that time, the debugger issues its
stack underflow message.
16.7.3 Using Ctrl/Y When Debugging Ada Tasks
Pressing Ctrl/C is the recommended method of interrupting program execution
or a debugger command during a debugging session. This returns control to the
debugger; pressing Ctrl/Y returns control to DCL level.
If you interrupt a task debugging session by pressing Ctrl/Y, you might have
some problems when you then start the debugger at DCL level with the DEBUG
command. In such cases, you should insert the following two lines in the source
code at the beginning of your main program to name the Compaq Ada predefined
package CONTROL_C_INTERCEPTION:
16–33
Debugging Tasking Programs
16.7 Additional Task-Debugging Topics
with CONTROL_C_INTERCEPTION;
pragma ELABORATE(CONTROL_C_INTERCEPTION);
For information on this package, see the Compaq Ada documentation.
16–34
VI
Debugger Command Dictionary
1 Overview
The Debugger Command Dictionary contains detailed reference information about
all debugger commands, organized as follows:
•
Section 2 explains how to enter debugger commands.
•
Section 3 lists commands that are disabled in the command/message view of
the debugger’s HP DECwindows Motif for OpenVMS user interface.
•
Section 4 gives general information about debugger diagnostic messages.
•
Section 5 contains detailed reference information about the debugger
commands.
2 Debugger Command Format
You can enter debugger commands interactively at the keyboard or store them
within a command procedure to be executed later with the execute procedure (@)
command.
This section provides the following information:
•
General format for debugger commands
•
Rules for entering commands interactively at the keyboard
•
Rules for entering commands in debugger command procedures
2.1 General Format
A command string is the complete specification of a debugger command.
Although you can continue a command on more than one line, the term command
string is used to define an entire command that is passed to the debugger.
A debugger command string consists of a verb and, possibly, parameters and
qualifiers.
The verb specifies the command to be executed. Some debugger command strings
might consist of only a verb or a verb pair. For example:
DBG> GO
DBG> SHOW IMAGE
A parameter specifies what the verb acts on (for example, a file specification).
A qualifier describes or modifies the action taken by the verb. Some command
strings might include one or more parameters or qualifiers. In the following
examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@ is the
execute procedure command); /SCROLL and /OUTPUT are qualifiers.
DBG>
DBG>
DBG>
DBG>
SET WATCH COUNT
EXAMINE I,J,K
SELECT/SCROLL/OUTPUT OUT2
@PROG4.COM
Some commands accept optional WHEN or DO clauses. DO clauses are also used
in some screen display definitions.
A WHEN clause consists of the keyword WHEN followed by a conditional
expression (within parentheses) that evaluates to true or false in the current
language. A DO clause consists of the keyword DO followed by one or more
command strings (within parentheses) that are to be executed in the order that
they are listed. You must separate multiple command strings with semicolons ( ; ).
These points are illustrated in the next example.
DEBUG–3
The following command string sets a breakpoint on routine SWAP. The breakpoint
is triggered whenever the value of J equals 4 during execution. When the
breakpoint is triggered, the debugger executes the two commands SHOW CALLS
and EXAMINE I,K, in the order indicated.
DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K)
The debugger checks the syntax of the commands in a DO clause when it executes
the DO clause. You can nest commands within DO clauses.
2.2 Entering Commands at the Keyboard
When entering a debugger command interactively at the keyboard, you can
abbreviate a keyword (verb, qualifier, parameter) to as few characters as are
needed to make it unique within the set of all debugger keywords. However, some
commonly used commands (for example, EXAMINE, DEPOSIT, GO, STEP) can be
abbreviated to their first characters. Also, in some cases, the debugger interprets
nonunique abbreviations correctly on the basis of context.
Pressing the Return key terminates the current line, causing the debugger to
process it. To continue a long command string on another line, type a hyphen
( - ) before pressing Return. As a result, the debugger prompt is prefixed with an
underscore character (_DBG>), indicating that the command string is still being
accepted.
You can enter more than one command string on one line by separating command
strings with semicolons ( ; ).
To enter a comment (explanatory text recorded in a debugger log file but
otherwise ignored by the debugger), precede the comment text with an
exclamation point ( ! ). If the comment wraps to another line, start that line
with an exclamation point.
The command line editing functions that are available at the DCL prompt ($)
are also available at the debugger prompt (DBG>), including command recall
with the up arrow and down arrow keys. For example, pressing the left arrow
and right arrow keys moves the cursor one character to the left and right,
respectively; pressing Ctrl/H or Ctrl/E moves the cursor to the start or end of
the line, respectively; pressing Ctrl/U deletes all the characters to the left of the
cursor, and so on.
To interrupt a command that is being processed by the debugger, press Ctrl/C.
See the Ctrl/C command.
2.3 Entering Commands in Command Procedures
To maximize legibility, it is best not to abbreviate command keywords in a
command procedure. Do not abbreviate command keywords to less than four
significant characters (not counting the negation /NO . . . ), to avoid potential
conflicts in future releases.
Start a debugger command line at the left margin. (Do not start a command line
with a dollar sign ( $ ) as you do when writing a DCL command procedure.)
The beginning of a new line ends the previous command line (the end-of-file
character also ends the previous command line). To continue a command string
on another line, type a hyphen ( - ) before starting the new line.
You can enter more than one command string on one line by separating command
strings with semicolons ( ; ).
DEBUG–4
To enter a comment (explanatory text that does not affect the execution of the
command procedure), precede the comment text with an exclamation point ( ! ). If
the comment wraps to another line, start that line with an exclamation point.
3 Commands Disabled in the Debugger’s HP DECwindows Motif
for OpenVMS User Interface
The following commands are disabled in the debugger’s HP DECwindows Motif
for OpenVMS user interface. Several of these commands 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
HELP1
(SET,SHOW) WINDOW
MOVE
(SHOW,CANCEL) DISPLAY
SAVE
SHOW SELECT
SCROLL
SPAWN
1 Help
on commands is available from the Help menu in a debugger window.
The debugger issues an error message if you try to enter any of these disabled
commands at the command prompt or when the debugger executes a command
procedure containing any of these commands.
The MONITOR command works only with the HP DECwindows Motif for
OpenVMS user interface (because the command uses the Monitor View).
4 Debugger Diagnostic Messages
The following example shows the elements of a debugger diagnostic message:
%DEBUG-W-NOSYMBOL, symbol ’X’ is not in the symbol table
!
"
#
$
! The facility name (DEBUG).
" The severity level (W, in this example).
# The message identifier (NOSYMBOL, in this example). The message
identifier is an abbreviation of the message text.
$ The message text.
The identifier enables you to find the explanation for a diagnostic message from
the debugger’s online help (and the action you need to take, if any).
To get online help about a debugger message, use the following command format:
HELP MESSAGES message-identifier
DEBUG–5
4 Debugger Diagnostic Messages
The possible severity levels for diagnostic messages are as follows:
S (success)
I (informational)
W (warning)
E (error)
F (fatal, or severe error)
Success and informational messages inform you that the debugger has performed
your request.
Warning messages indicate that the debugger might have performed some, but
not all, of your request and that you should verify the result.
Error messages indicate that the debugger could not perform your request, but
that the state of the debugging session was not changed. The only exceptions are
if the message identifier was DBGERR or INTERR. These identifiers signify an
internal debugger error, and you should contact your HP support representative.
Fatal messages indicate that the debugger could not perform your request and
that the debugging session is in an indeterminate state from which you cannot
recover reliably. Typically, the error ends the debugging session.
5 Debugger Command Dictionary
The Debugger Command Dictionary describes each debugger command in detail.
Commands are listed alphabetically. The following information is provided
for each command: command description, format, parameters, qualifiers, and
one or more examples. See the preface of this manual for documentation
conventions.
DEBUG–6
@ (Execute Procedure)
@ (Execute Procedure)
Executes a debugger command procedure.
Format
@file-spec [parameter[, . . . ]]
Parameters
file-spec
Specifies the command procedure to be executed. For any part of the full file
specification not provided, the debugger uses the file specification established
with the last SET ATSIGN command, if any. If the missing part of the file
specification was not established by a SET ATSIGN command, the debugger
assumes SYS$DISK:[ ]DEBUG.COM as the default file specification. You can
specify a logical name.
parameter
Specifies a parameter that is passed to the command procedure. The parameter
can be an address expression, a value expression in the current language, or
a debugger command; the command must be enclosed within quotation marks
( " ). Unlike with DCL, you must separate parameters by commas. Also, you
can pass as many parameters as there are formal parameter declarations within
the command procedure. For more information about passing parameters to
command procedures, see the DECLARE command.
Description
A debugger command procedure can contain any debugger commands, including
another execute procedure (@) command. The debugger executes commands from
the command procedure until it reaches an EXIT or QUIT command or reaches
the end of the command procedure. At that point, the debugger returns control to
the command stream that invoked the command procedure. A command stream
can be the terminal, an outer (containing) command procedure, a DO clause in a
command such as SET BREAK, or a DO clause in a screen display definition.
By default, commands read from a command procedure are not echoed. If you
enter the SET OUTPUT VERIFY command, all commands read from a command
procedure are echoed on the current output device, as specified by DBG$OUTPUT
(the default output device is SYS$OUTPUT).
For information about passing parameters to command procedures, see the
DECLARE command.
Related commands:
DECLARE
(SET,SHOW) ATSIGN
SET OUTPUT [NO]VERIFY
SHOW OUTPUT
DEBUG–7
@ (Execute Procedure)
Example
DBG> SET ATSIGN USER:[JONES.DEBUG].DBG
DBG> SET OUTPUT VERIFY
DBG> @CHECKOUT
%DEBUG-I-VERIFYICF, entering command procedure CHECKOUT
SET MODULE/ALL
SET BREAK SUB1
GO
break at routine PROG5\SUB2
EXAMINE X
PROG5\SUB2\X: 376
...
%DEBUG-I-VERIFYICF, exiting command procedure MAIN
DBG>
In this example, the SET ATSIGN command establishes that debugger command
procedures are, by default, in USER:[JONES.DEBUG] and have a file type
of .DBG. The @CHECKOUT command executes the command procedure
USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands
in the command because of the SET OUTPUT VERIFY command.
DEBUG–8
ACTIVATE BREAK
ACTIVATE BREAK
Activates a breakpoint that you have previously set and then deactivated.
Format
ACTIVATE BREAK [address-expression[, . . . ]]
Parameters
address-expression
Specifies a breakpoint to be activated. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Activates a breakpoint established by a previous SET BREAK/ACTIVATING
command.
/ALL
By default, activates all user-defined breakpoints. When used with
/PREDEFINED, activates all predefined breakpoints but no user-defined
breakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a breakpoint established by a previous SET BREAK/BRANCH
command.
/CALL
Activates a breakpoint established by a previous SET BREAK/CALL command.
/EVENT=event-name
Activates a breakpoint established by a previous SET BREAK/EVENT=eventname command. Specify the event name (and address expression, if any) exactly
as specified with the SET BREAK/EVENT command.
To identify the current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
/EXCEPTION
Activates a breakpoint established by a previous SET BREAK/EXCEPTION
command.
/HANDLER
Activates a breakpoint established by a previous SET BREAK/HANDLER
command.
/INSTRUCTION
Activates a breakpoint established by a previous SET BREAK/INSTRUCTION
command.
/LINE
Activates a breakpoint established by a previous SET BREAK/LINE command.
Do not specify an address expression with this qualifier.
DEBUG–9
ACTIVATE BREAK
/PREDEFINED
Activates a specified predefined breakpoint without affecting any user-defined
breakpoints. When used with /ALL, activates all predefined breakpoints.
/SYSEMULATE
(Alpha only) Activates a breakpoint established by a previous SET
BREAK/SYSEMULATE command.
/TERMINATING
Activates a breakpoint established by a previous SET BREAK/TERMINATING
command.
/UNALIGNED_DATA
(Integrity servers and Alpha only) Activates a breakpoint established by a
previous SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint
previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command.
/USER
Activates a specified user-defined breakpoint without affecting any predefined
breakpoints. To activate all user-defined breakpoints, use the /ALL qualifier.
Description
User-defined breakpoints are activated when you set them with the SET BREAK
command. Predefined breakpoints are activated by default. Use the ACTIVATE
BREAK command to activate one or more breakpoints that you deactivated with
DEACTIVATE BREAK.
Activating and deactivating breakpoints enables you to run and rerun your
program with or without breakpoints without having to cancel and then reset
them. By default, the RERUN command saves the current state of all breakpoints
(activated or deactivated).
You can activate and deactivate user-defined breakpoints or predefined
breakpoints or both. To check if a breakpoint is activated, use the SHOW
BREAK command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY
DEBUG–10
ACTIVATE BREAK
Examples
1.
DBG> ACTIVATE BREAK MAIN\LOOP+10
This command activates the user-defined breakpoint set at the address
expression MAIN\LOOP+10.
2.
DBG> ACTIVATE BREAK/ALL
This command activates all user-defined breakpoints.
3.
DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED
This command activates all breakpoints, both user-defined and predefined.
DEBUG–11
ACTIVATE TRACE
ACTIVATE TRACE
Activates a tracepoint that you have previously set and then deactivated.
Format
ACTIVATE TRACE [address-expression[, . . . ]]
Parameters
address-expression
Specifies a tracepoint to be activated. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Activates a tracepoint established with a previous SET TRACE/ACTIVATING
command.
/ALL
By default, activates all user-defined tracepoints. When used with
/PREDEFINED, activates all predefined tracepoints but no user-defined
tracepoints. To activate all tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a tracepoint established with a previous SET TRACE/BRANCH
command.
/CALL
Activates a tracepoint established with a previous SET TRACE/CALL command.
/EVENT=event-name
Activates a tracepoint established with a previous SET TRACE/EVENT=eventname command. Specify the event name (and address expression, if any) exactly
as specified with the SET TRACE/EVENT command.
To identify the current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
/EXCEPTION
Activates a tracepoint established with a previous SET TRACE/EXCEPTION
command.
/INSTRUCTION
Activates a tracepoint established with a previous SET TRACE/INSTRUCTION
command.
/LINE
Activates a tracepoint established with a previous SET TRACE/LINE command.
/PREDEFINED
Activates a specified predefined tracepoint without affecting any user-defined
tracepoints. When used with /ALL, activates all predefined tracepoints.
DEBUG–12
ACTIVATE TRACE
/TERMINATING
Activates a tracepoint established with a previous SET TRACE/TERMINATING
command.
/USER
Activates a specified user-defined tracepoint without affecting any predefined
tracepoints. To activate all user-defined tracepoints, use the /ALL qualifier.
Description
User-defined tracepoints are activated when you set them with the SET TRACE
command. Predefined tracepoints are activated by default. Use the ACTIVATE
TRACE command to activate one or more tracepoints that you deactivated with
DEACTIVATE TRACE.
Activating and deactivating tracepoints enables you to run and rerun your
program with or without tracepoints without having to cancel and then reset
them. By default, the RERUN command saves the current state of all tracepoints
(activated or deactivated).
You can activate and deactivate user-defined tracepoints or predefined tracepoints
or both. To check if a tracepoint is activated, use the SHOW TRACE command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,DEACTIVATE) TRACE
Examples
1.
DBG> ACTIVATE TRACE MAIN\LOOP+10
This command activates the user-defined tracepoint at the location
MAIN\LOOP+10.
2.
DBG> ACTIVATE TRACE/ALL
This command activates all user-defined tracepoints.
DEBUG–13
ACTIVATE WATCH
ACTIVATE WATCH
Activates a watchpoint that you have previously set and then deactivated.
Format
ACTIVATE WATCH [address-expression[, . . . ]]
Parameters
address-expression
Specifies a watchpoint to be activated. With high-level languages, this is typically
the name of a variable. Do not use the asterisk ( * ) wildcard character. Instead,
use the /ALL qualifier. Do not specify an address expression with /ALL.
Qualifiers
/ALL
Activates all watchpoints.
Description
Watchpoints are activated when you set them with the SET WATCH command.
Use the ACTIVATE WATCH command to activate one or more watchpoints that
you deactivated with DEACTIVATE WATCH.
Activating and deactivating watchpoints enables you to run and rerun your
program with or without watchpoints without having to cancel and then reset
them.
By default, the RERUN command saves the current state of all static watchpoints
(activated or deactivated). The state of a particular nonstatic watchpoint might or
might not be saved depending on the scope of the variable being watched relative
to the main program unit (where execution restarts).
To check if a watchpoint is activated, use the SHOW WATCH command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) WATCH
Examples
1.
DBG> ACTIVATE WATCH SUB2\TOTAL
This command activates the watchpoint at variable TOTAL in module SUB2.
2.
DBG> ACTIVATE WATCH/ALL
This command activates all watchpoints you have set and deactivated.
DEBUG–14
ANALYZE/CRASH_DUMP
ANALYZE/CRASH_DUMP
Opens a system dump for analysis by the System Dump Debugger (kept debugger
only).
Format
ANALYZE/CRASH_DUMP
Description
For OpenVMS Integrity servers and Alpha systems, invokes the System Dump
Debugger (SDD) to analyze a system dump.
SDD is similar in concept to the System Code Debugger (SCD). While SCD allows
connection to a running system, with control of the system’s execution and the
examination and modification of variables, SDD allows analysis of memory as
recorded in a system dump.
Use of SDD usually involves two systems, although all of the required
environment can be set up on a single system. The description that follows
assumes that two systems are being used:
•
The build system, where the image that causes the system crash has been
built
•
The test system, where the image is executed and the system crash occurs
In common with SCD, the OpenVMS debugger user interface allows you to specify
variable names, routine names, and so on, precisely as they appear in your source
code. Also, SDD can display the source code where the software was executing at
the time of the system crash.
SDD recognizes the syntax, data typing, operators, expressions, scoping rules,
and other constructs of a given language. If your code or driver is written in more
than one language, you can change the debugging context from one language to
another during a debugging session.
To use SDD you must do the following:
•
Build the system image or device driver that is causing the system crash.
•
Boot a system, including the system image or device driver, and perform the
necessary steps to cause the system crash.
•
Reboot the system and save the dump file.
•
Invoke SDD, which is integrated with the OpenVMS debugger.
For more information about using the SDD, including a sample SDD session, see
the OpenVMS Alpha System Analysis Tools Manual.
Related commands:
ANALYZE/PROCESS_DUMP
CONNECT %NODE
SDA
DEBUG–15
ANALYZE/CRASH_DUMP
Example
DBG> ANALYZE/CRASH_DUMP
DBG>
Invokes SDD from within the kept debugger.
DEBUG–16
ANALYZE/PROCESS_DUMP
ANALYZE/PROCESS_DUMP
Opens a process dump for analysis with the System Code Debugger (kept
debugger only)
Format
ANALYZE/PROCESS_DUMP dumpfile
Parameters
dumpfile
The name of the process dump file to be analyzed. The file type must be .DMP.
Qualifiers
/IMAGE_PATH=directory-spec
Specifies the search path for the debugger to find the files that contains the
debugger symbol tables (DSTs). The files must be of type .DSF or .EXE, with the
same name as the image names in the dumpfile. For example, if image name
foo.exe is in the dump file, then the debugger searches for foo.dsf or foo.exe.
Description
(Kept debugger only.) Opens a process dump for analysis with the System Code
Debugger (SCD). The qualifier /PROCESS_DUMP is required and distinguishes
this command from the one that invokes the System Dump Debugger (SDD),
ANALYZE/CRASH_DUMP.
The qualifier /IMAGE_PATH=directory-spec is optional, and specifies the search
path the debugger is to use to find the debugger symbol table (DST) files. The
debugger builds an image list from the saved process image list. When you set an
image (the main image is automatically set), the debugger attempts to open that
image in order to find the DSTs.
If you include the /IMAGE_PATH=directory-spec qualifier, the debugger searches
for the .DST file in the specified directory. The debugger first tries to translate
directory-spec as the logical name of a directory search list. If that fails, the
debugger interprets directory-spec as a directory specification, and searches that
directory for matching .DSF or .EXE files. A .DSF file takes precedence over an
.EXE file. The name of the .DSF or .EXE file must match the image name.
If you do not include the /IMAGE_PATH=directory-spec qualifier, the debugger
looks for the DST file first in the directory that contains the dump file. If that
fails, the debugger next searches directory SYS$SHARE and then directory
SYS$MESSAGE. If the debugger fails to find a DST file for the image, symbolic
information available to the debugger is limited to global and universal symbol
names.
The debugger checks for link date-time mismatches between the dump file image
and the DST file and issues a warning if one is discovered.
The parameter dumpfile is the name of the process dump file to be analyzed.
Note that the process dump file type must be .DMP and the DST file type must
be either .DSF or .EXE.
DEBUG–17
ANALYZE/PROCESS_DUMP
For more information about using SCD, see the OpenVMS Alpha System Analysis
Tools Manual.
Related commands:
ANALYZE/CRASH_DUMP
CONNECT %NODE
SDA
Example
DBG> ANALYZE/PROCESS/IMAGE_DUMP=my_disk$:[my_dir]
my_disk$:[my_dir]wecrash.dmp
%SYSTEM-F-IMGDMP, dynamic image dump signal at PC=001C0FA0B280099C,
PS=001C003C
break on unhandled exception preceding WECRASH\
th_run
\%LINE 26412 in THREAD 8
26412:
if (verify) {
DBG> SET RADIX HEXADECIMAL; EXAMINE PC
WECRASH\th_run\%PC:
0000000000030244
DBG>
DEBUG–18
ATTACH
ATTACH
Passes control of your terminal from the current process to another process.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
ATTACH process-name
Parameters
process-name
Specifies the process to which your terminal is to be attached. The process
must already exist before you try to attach to it. If the process name contains
nonalphanumeric or space characters, you must enclose it in quotation marks
( " ).
Description
The ATTACH command enables you to go back and forth between a debugging
session and your command interpreter, or between two debugging sessions. To do
so, you must first use the SPAWN command to create a subprocess. You can then
attach to it whenever you want. To return to your original process with minimal
system overhead, use another ATTACH command.
Related command:
SPAWN
Examples
1.
DBG> SPAWN
$ ATTACH JONES
%DEBUG-I-RETURNED, control returned to process JONES
DBG> ATTACH JONES_1
$
In this example, the series of commands creates a subprocess named
JONES_1 from the debugger (currently running in the process JONES) and
then attaches to that subprocess.
2.
DBG> ATTACH "Alpha One"
$
This example illustrates using quotation marks to enclose a process name
that contains a space character.
DEBUG–19
CALL
CALL
Calls a routine that was linked with your program.
Format
CALL routine-name [(argument[, . . . ])]
Parameters
routine-name
Specifies the name or the memory address of the routine to be called.
argument
Specifies an argument required by the routine. Arguments can be passed by
address, by descriptor, by reference, and by value, as follows:
%ADDR
(Default, except for C and C++.) Passes the argument by address.
The format is as follows:
%DESCR
CALL routine-name (%ADDR address-expression)
The debugger evaluates the address expression and passes that
address to the routine specified. For simple variables (such as X),
the address of X is passed into the routine. This passing mechanism
is how Fortran implements ROUTINE(X). In other words, for named
variables, using %ADDR corresponds to a call by reference in
Fortran. For other expressions, however, you must use the %REF
function to call by reference. For complex or composite variables
(such as arrays, records, and access types), the address is passed
when you specify %ADDR, but the called routine might not handle
the passed data properly. Do not specify a literal value (a number or
an expression composed of numbers) with %ADDR.
Passes the argument by descriptor. The format is as follows:
%REF
CALL routine-name (%DESCR language-expression)
The debugger evaluates the language expression and builds a
standard descriptor to describe the value. The descriptor is then
passed to the routine you named. You would use this technique to
pass strings to a Fortran routine.
Passes the argument by reference. The format is as follows:
%VAL
CALL routine-name (%REF language-expression)
The debugger evaluates the language expression and passes a
pointer to the value, into the called routine. This passing mechanism
corresponds to the way Fortran passes the result of an expression.
(Default for C and C++.) Passes the argument by value. The format
is as follows:
CALL routine-name (%VAL language-expression)
The debugger evaluates the language expression and passes the
value directly to the called routine.
DEBUG–20
CALL
Qualifiers
/AST (default)
/NOAST
Controls whether the delivery of asynchronous system traps (ASTs) is enabled or
disabled during the execution of the called routine. The /AST qualifier enables
the delivery of ASTs in the called routine. The /NOAST qualifier disables the
delivery of ASTs in the called routine. If you do not specify /AST or /NOAST with
the CALL command, the delivery of ASTs is enabled unless you have previously
entered the DISABLE AST command.
/SAVE_VECTOR_STATE
/NOSAVE_VECTOR_STATE (default)
Applies to VAX vectorized programs. Controls whether the current state of the
vector processor is saved and then restored when a routine is called with the
CALL command.
The state of the vector processor comprises the following:
•
The values of the vector registers (V0 to V15) and the vector control registers
(VCR, VLR, and VMR)
•
Any vector exception (an exception caused by the execution of a vector
instruction) that might be pending delivery
When you use the CALL command to execute a routine, execution of the routine
might change the state of the vector processor as follows:
•
By changing the values of vector registers or vector control registers
•
By causing a vector exception
•
By causing the delivery of a vector exception that was pending when the
CALL command was issued
The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has
completed execution, the debugger restores the state of the vector processor that
exists before the CALL command is issued. This ensures that, after the called
routine has completed execution:
•
Any vector exception that was pending delivery before the CALL command
was issued is still pending delivery
•
No vector exception that was triggered during the routine call is still pending
delivery
•
The values of the vector registers are identical to their values before the
CALL command was issued
The /NOSAVE_VECTOR_STATE qualifier (which is the default) specifies that the
state of the vector processor that exists before the CALL command is issued is
not restored by the debugger after the called routine has completed execution. In
this case, the state of the vector processor after the routine call depends on the
effect (if any) of the called routine.
The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the general
registers. The values of these registers are always saved and restored when you
execute a routine with the CALL command.
DEBUG–21
CALL
Description
The CALL command is one of the four debugger commands that can be used to
execute your program (the others are GO, STEP, and EXIT). The CALL command
enables you to execute a routine independently of the normal execution of your
program. The CALL command executes a routine whether or not your program
actually includes a call to that routine, as long as the routine was linked with
your program.
When you enter a CALL command, the debugger takes the following actions. For
more information, see the qualifier descriptions.
1. Saves the current values of the general registers.
2. Constructs an argument list.
3. Executes a call to the routine specified in the command and passes any
arguments.
4. Executes the routine.
5. Displays the value returned by the routine in the return status register.
By convention, after a called routine has executed, register R0 contains the
function return value (if the routine is a function) or the procedure completion
status (if the routine is a procedure that returns a status value). If a called
procedure does not return a status value or function value, the value in R0
might be meaningless, and the "value returned" message can be ignored.
6. Restores the values of the general registers to the values they had just before
the CALL command was executed.
7. Issues the prompt.
The debugger assumes that the called routine conforms to the procedure calling
standard (see the OpenVMS Calling Standard). However, the debugger does not
know about all the argument-passing mechanisms for all supported languages.
Therefore, you might need to specify how to pass parameters, for example, use
CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete information
about how arguments are passed to routines, see your language documentation.
When the current language is C or C++, the CALL command by default now
passes arguments by value rather than by reference. In addition, you can now
pass the following arguments without using a passing mechanism lexical (such as
%REF or %VAL):
•
Routine references
•
Quoted strings (treated as %REF strings)
•
Structures, records, and objects
•
Floating-point parameters by value in F_, D_, G_, S_, and T_floating format
by dereferencing a variable of that type.
If the routine contains parameters that are not read-only, the values assigned
to parameters may not be visible, and access to values is unreliable. This is
because the debugger adjusts parameter values in an internal argument list, not
the program argument list. To examine changing values, consider using static
variables instead of parameters.
The CALL command converts all floating-point literals to F_floating format for
Alpha systems and T_floating format for Integrity servers.
DEBUG–22
CALL
On Alpha, passing a floating-point literal in a format other than F_floating is not
supported, as shown in the example below.
A common debugging technique at an exception breakpoint (resulting from a SET
BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine
with the CALL command. When you enter the CALL command at an exception
breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set
within the called routine are temporarily disabled so that the debugger does not
lose the exception context. However, such eventpoints are active if you enter the
CALL command at a location other than an exception breakpoint.
When an exception breakpoint is triggered, execution is suspended before any
application-declared condition handler is invoked. At an exception breakpoint,
entering a GO or STEP command after executing a routine with the CALL
command causes the debugger to resignal the exception (see the GO and STEP
commands).
On Alpha, you cannot debug routines that are activated before the routine
activated by a CALL command. For example, your program is stopped in routine
MAIN, and you set a breakpoint in routine SORT. You issue the debugger
command CALL SORT. While debugging routine SORT, you cannot debug routine
MAIN. You must first return from the call to routine SO RT.
If you are debugging a multiprocess program, the CALL command is executed in
the context of the current process set. In addition, when debugging a multiprocess
program, the way in which execution continues in your process depends on
whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE
[NO]WAIT command. By default (SET MODE NOINTERRUPT), when one
process stops, the debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until all processes in
the current process set have stopped before prompting for a new command. See
Chapter 15 for more information.
Related commands:
GO
EXIT
SET PROCESS
SET MODE [NO]INTERRUPT
STEP
Examples
1.
DBG> CALL SUB1(X)
value returned is 19
DBG>
This command calls routine SUB1, with parameter X (by default, the address
of X is passed). In this case, the routine returns the value 19.
2.
DBG> CALL SUB(%REF 1)
value returned is 1
DBG>
This command passes a pointer to a memory location containing the numeric
literal 1, into the routine SUB.
DEBUG–23
CALL
3.
DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes
still allocated, value returned is 00000001
DBG>
This example calls Run-Time Library routine LIB$SHOW_VM (in shareable
image LIBRTL) to display memory statistics. The SET MODULE command
makes the universal symbols (routine names) in LIBRTL visible in the main
image. See also the SHOW MODULE/SHARE command.
4.
DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33)
This example passes floating-point parameters by value, to a C subroutine
with the function prototype void testsub (float, float, float). The
floating-point parameters are passed in F_floating format.
5.
SUBROUTINE CHECK_TEMP(TEMPERATURE,ERROR_MESSAGE)
REAL TOLERANCE /4.7/
REAL TARGET_TEMP /92.0/
CHARACTER*(*) ERROR_MESSAGE
IF (TEMPERATURE .GT. (TARGET_TEMP + TOLERANCE)) THEN
TYPE *,’Input temperature out of range:’,TEMPERATURE
TYPE *,ERROR_MESSAGE
ELSE
TYPE *,’Input temperature in range:’,TEMPERATURE
END IF
RETURN
END
DBG> CALL CHECK_TEMP(%REF 100.0, %DESCR ’TOLERANCE-CHECK 1 FAILED’)
Input temperature out of range: 100.0000
TOLERANCE-CHECK 1 FAILED
value returned is 0
DBG> CALL CHECK_TEMP(%REF 95.2, %DESCR ’TOLERANCE-CHECK 2 FAILED’)
Input temperature in range: 95.2000
value returned is 0
DBG>
This Fortran routine (CHECK_TEMP) accepts two parameters,
TEMPERATURE (a real number) and ERROR_MESSAGE (a string).
Depending on the value of TEMPERATURE, the routine prints different
output. Each CALL command passes a temperature value (by reference) and
an error message (by descriptor). Because this routine does not have a formal
return value, the value returned is undefined, in this case, 0.
DEBUG–24
CANCEL ALL
CANCEL ALL
Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and
type to their default values. Restores the line, symbolic, and G_floating modes
established with the SET MODE command to their default values.
Format
CANCEL ALL
Qualifiers
/PREDEFINED
Cancels all predefined (but no user-defined) breakpoints and tracepoints.
/USER
Cancels all user-defined (but no predefined) breakpoints, tracepoints, and
watchpoints. This is the default unless you specify /PREDEFINED.
Description
The CANCEL ALL command does the following:
1. Cancels all user-defined eventpoints (those created with the commands
SET BREAK, SET TRACE, and SET WATCH). This is equivalent to
entering the commands CANCEL BREAK/ALL, CANCEL TRACE/ALL,
and CANCEL WATCH/ALL. Depending on the type of program (for example
Ada, multiprocess), certain predefined breakpoints or tracepoints might be
set automatically when you start the debugger. To cancel all predefined
but no user-defined eventpoints, use CANCEL ALL/PREDEFINED.
To cancel all predefined and user-defined eventpoints, use CANCEL
ALL/PREDEFINED/USER.
2. Restores the scope search list to its default value (0,1,2, . . . ,n). This is
equivalent to entering the CANCEL SCOPE command.
3. Restores the data type for memory locations that are associated with a
compiler-generated type to the associated type. Restores the type for locations
that are not associated with a compiler-generated type to "longword integer".
This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET
TYPE LONGWORD commands.
4. Restores the line, symbolic, and G_floating modes established with the SET
MODE command to their default values. This is equivalent to entering the
following command:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
The CANCEL ALL command does not affect the current language setting or
modules included in the run-time symbol table.
DEBUG–25
CANCEL ALL
Related commands:
(CANCEL,DEACTIVATE) BREAK
CANCEL SCOPE
(CANCEL,DEACTIVATE) TRACE
CANCEL TYPE/OVERRIDE
(CANCEL,DEACTIVATE) WATCH
(SET,CANCEL) MODE
SET TYPE
Examples
1.
DBG> CANCEL ALL
This command cancels all user-defined breakpoints and tracepoints and all
watchpoints, and restores scopes, types, and some modes to their default
values. In this example, there are no predefined breakpoints or tracepoints.
2.
DBG> CANCEL ALL
%DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled
This command cancels all user-defined breakpoints and tracepoints and all
watchpoints, and restores scopes, types, and some modes to their default
values. In this example, there is a predefined breakpoint or tracepoint; this is
not canceled by default.
3.
DBG> CANCEL ALL/PREDEFINED
This command cancels all predefined breakpoints and tracepoints, and
restores scopes, types, and some modes to their default values. No userdefined breakpoints or tracepoints are affected.
DEBUG–26
CANCEL BREAK
CANCEL BREAK
Cancels a breakpoint.
Format
CANCEL BREAK [address-expression[, . . . ]]
Parameters
address-expression
Specifies a breakpoint to be canceled. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Cancels the effect of a previous SET BREAK/ACTIVATING command.
/ALL
By default, cancels all user-defined breakpoints. When used with /PREDEFINED,
cancels all predefined breakpoints but no user-defined breakpoints. To cancel all
breakpoints, use CANCEL BREAK/ALL/USER/PREDEFINED.
/BRANCH
Cancels the effect of a previous SET BREAK/BRANCH command.
/CALL
Cancels the effect of a previous SET BREAK/CALL command.
/EVENT=event-name
Cancels the effect of a previous SET BREAK/EVENT=event-name command.
Specify the event name (and address expression, if any) exactly as specified with
the SET BREAK/EVENT command. To identify the current event facility and the
associated event names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Cancels the effect of a previous SET BREAK/EXCEPTION command.
/HANDLER
Cancels the effect of a previous SET BREAK/HANDLER command.
/INSTRUCTION
Cancels the effect of a previous SET BREAK/INSTRUCTION command.
/LINE
Cancels the effect of a previous SET BREAK/LINE command.
/PREDEFINED
Cancels a specified predefined breakpoint without affecting any user-defined
breakpoints. When used with /ALL, cancels all predefined breakpoints.
/SYSEMULATE
(Alpha only) Cancels the effect of a previous SET BREAK/SYSEMULATE
command.
DEBUG–27
CANCEL BREAK
/TERMINATING
Cancels the effect of a previous SET BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Cancels the effect of a previous SET BREAK/UNALIGNED_DATA
command.
/USER
Cancels a specified user-defined breakpoint without affecting any predefined
breakpoints. This is the default unless you specify /PREDEFINED. To cancel all
user-defined breakpoints, use the /ALL qualifier.
Description
Breakpoints can be user defined or predefined. User-defined breakpoints are
set explicitly with the SET BREAK command. Predefined breakpoints, which
depend on the type of program you are debugging (for example, Ada or ZQUIT
multiprocess), are established automatically when you start the debugger. Use
the SHOW BREAK command to identify all breakpoints that are currently set.
Any predefined breakpoints are identified as such.
User-defined and predefined breakpoints are set and canceled independently.
For example, a location or event can have both a user-defined and a predefined
breakpoint. Canceling the user-defined breakpoint does not affect the predefined
breakpoint, and conversely.
To cancel only user-defined breakpoints, do not specify /PREDEFINED with the
CANCEL BREAK command (the default is /USER). To cancel only predefined
breakpoints, specify /PREDEFINED but not /USER. To cancel both predefined
and user-defined breakpoints, specify both /PREDEFINED and /USER.
In general, the effect of the CANCEL BREAK command is symmetrical with
that of the SET BREAK command (even though the SET BREAK command
is used only with user-defined breakpoints). Thus, to cancel a breakpoint
that was established at a specific location, specify that same location (address
expression) with the CANCEL BREAK command. To cancel breakpoints that
were established on a class of instructions or events, specify the class of
instructions or events with the corresponding qualifier (/LINE, /BRANCH,
/ACTIVATING, /EVENT=, and so on). For more information, see the qualifier
descriptions.
If you want the debugger to ignore a breakpoint without your having to cancel it
(for example, if you want to rerun the program with and without breakpoints),
use the DEACTIVATE BREAK instead of the CANCEL BREAK command. Later,
you can activate the breakpoint (with ACTIVATE BREAK).
DEBUG–28
CANCEL BREAK
Related commands:
(ACTIVATE,DEACTIVATE) BREAK
CANCEL ALL
(SET,SHOW) BREAK
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL) TRACE
Examples
1.
DBG> CANCEL BREAK MAIN\LOOP+10
This command cancels the user-defined breakpoint set at the address
expression MAIN\LOOP+10.
2.
DBG> CANCEL BREAK/ALL
This command cancels all user-defined breakpoints.
3.
DBG> CANCEL BREAK/ALL/USER/PREDEFINED
This command cancels all user-defined and predefined breakpoints.
4.
all> CANCEL BREAK/ACTIVATING
This command cancels a previous user-defined SET BREAK/ACTIVATING
command. As a result, the debugger does not suspend execution when a new
process is brought under debugger control.
5.
DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEFINED
This command cancels the predefined breakpoint set on task terminations due
to unhandled exceptions. This breakpoint is predefined for Ada programs and
programs that call POSIX Threads or Ada routines.
DEBUG–29
CANCEL DISPLAY
CANCEL DISPLAY
Permanently deletes a screen display.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
CANCEL DISPLAY [display-name[, . . . ]]
Parameters
display-name
Specifies the name of a display to be canceled. Do not specify the PROMPT
display, which cannot be canceled. Do not use the asterisk ( * ) wildcard character.
Instead, use the /ALL qualifier. Do not specify a display name with /ALL.
Qualifiers
/ALL
Cancels all displays, except the PROMPT display.
Description
When a display is canceled, its contents are permanently lost, it is deleted from
the display list, and all the memory that was allocated to it is released.
You cannot cancel the PROMPT display.
Related commands:
(SHOW) DISPLAY
(SET,SHOW,CANCEL) WINDOW
Examples
1.
DBG> CANCEL DISPLAY SRC2
This command deletes display SRC2.
2.
DBG> CANCEL DISPLAY/ALL
This command deletes all displays, except the PROMPT display.
DEBUG–30
CANCEL MODE
CANCEL MODE
Restores the line, symbolic, and G_floating modes established by the SET MODE
command to their default values. Also restores the default input/output radix.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
CANCEL MODE
Description
The effect of the CANCEL MODE command is equivalent to the following
commands:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
DBG> CANCEL RADIX
The default radix for both data entry and display is decimal for most languages.
On Integrity servers, the exceptions are BLISS, MACRO, and Intel® Assembler
(IAS).
On Alpha, the exceptions are BLISS, MACRO–32, and MACRO–64, which have a
default radix of hexadecimal.
Related commands:
(SET,SHOW) MODE
(SET,SHOW,CANCEL) RADIX
Example
DBG> CANCEL MODE
This command restores the default radix mode and all default mode values.
DEBUG–31
CANCEL RADIX
CANCEL RADIX
Restores the default radix for the entry and display of integer data.
Format
CANCEL RADIX
Qualifiers
/OVERRIDE
Cancels the override radix established by a previous SET RADIX/OVERRIDE
command. This sets the current override radix to "none" and restores the
output radix mode to the value established with a previous SET RADIX or SET
RADIX/OUTPUT command. If you did not change the radix mode with a SET
RADIX or SET RADIX/OUTPUT command, the CANCEL RADIX/OVERRIDE
command restores the radix mode to its default value.
Description
The CANCEL RADIX command cancels the effect of any previous SET RADIX
and SET RADIX/OVERRIDE commands. It restores the input and output radix
to their default value.
The default radix for both data entry and display is decimal for most languages.
The exceptions are BLISS and MACRO, which have a default radix of
hexadecimal.
The effect of the CANCEL RADIX/OVERRIDE command is more limited and is
explained in the description of the /OVERRIDE qualifier.
Related commands:
EVALUATE
(SET,SHOW) RADIX
Examples
1.
DBG> CANCEL RADIX
This command restores the default input and output radix.
2.
DBG> CANCEL RADIX/OVERRIDE
This command cancels any override radix you might have set with the SET
RADIX/OVERRIDE command.
DEBUG–32
CANCEL SCOPE
CANCEL SCOPE
Restores the default scope search list for symbol lookup.
Format
CANCEL SCOPE
Description
The CANCEL SCOPE command cancels the current scope search list established
by a previous SET SCOPE command and restores the default scope search list,
namely 0,1,2, . . . ,n, where n is the number of calls in the call stack.
The default scope search list specifies that, for a symbol without a path-name
prefix, a symbol lookup such as EXAMINE X first looks for X in the routine that
is currently executing (scope 0); if no X is visible there, the debugger looks in the
caller of that routine (scope 1), and so on down the call stack; if X is not found in
scope n, the debugger searches the rest of the run-time symbol table (RST), then
searches the global symbol table (GST), if necessary.
Related commands:
(SET,SHOW) SCOPE
Example
DBG> CANCEL SCOPE
This command cancels the current scope.
DEBUG–33
CANCEL SOURCE
CANCEL SOURCE
Cancels a source directory search list, a source directory search method, or both a
list and method established by a previous SET SOURCE command.
Format
CANCEL SOURCE
Qualifiers
/DISPLAY
Cancels the effect of a previous SET SOURCE/DISPLAY command, which
specifies the directory search list to be used by the debugger when displaying
source code. Canceling this command means the debugger searches for a source
file in the directory in which it was compiled.
/EDIT
Cancels the effect of a previous SET SOURCE/EDIT command, which specifies
the directory search list to be used during execution of the debugger’s EDIT
command. Canceling this command means the debugger searches for a source file
in the directory in which it was compiled.
/EXACT
Cancels the effect of a previous SET SOURCE/EXACT command, which specifies
a directory search method. Canceling this command means that the debugger no
longer searches for the exact version of the source file from compilation; it reverts
to the default behavior of searching for the latest version of the file.
/LATEST
Cancels the effect of a previous SET SOURCE/LATEST command, which specifies
a directory search method. In this case, the CANCEL SOURCE/LATEST
command directs the debugger to return to searching for the exact version
of the source file from compilation. Because /LATEST is the default setting,
this qualifier only makes sense when used with other qualifiers, for example,
/MODULE.
/MODULE=module-name
Cancels the effect of a previous SET SOURCE/MODULE=module-name command
in which the same module name and qualifiers were specified. (The /MODULE
qualifier allows you to specify a unique directory search list, directory search
method, or both, for the named module.) You can append one or more of
the qualifiers listed above to the SET SOURCE/MODULE and CANCEL
SOURCE/MODULE commands.
If you issue a CANCEL SOURCE/MODULE command with additional qualifiers,
you cancel the effect of the specified qualifiers on the module. If you issue an
unqualified CANCEL SOURCE/MODULE command, the debugger no longer
differentiates the module from any other module in your directories.
/ORIGINAL
(Applies to STDL programs only. Requires the installation of the Correlation
Facility (a separate layered product) and invocation of the kept debugger.)
Cancels the effect of a previous SET SOURCE/ORIGINAL command. The SET
DEBUG–34
CANCEL SOURCE
SOURCE/ORIGINAL command is required to debug STDL source files, and must
be canceled when you debug source files written in other languages.
Description
CANCEL SOURCE cancels the effect of a previous SET SOURCE command. The
nature of this cancellation depends on the qualifiers activated in previous SET
SOURCE commands. See the CANCEL SOURCE examples to see how CANCEL
SOURCE and SET SOURCE interact.
When you issue a SET SOURCE command, be aware that one of the two
qualifiers —/LATEST or /EXACT—will always be active. These qualifiers affect
the debugger search method. The /LATEST qualifier directs the debugger
to search for the version last created (the highest-numbered version in your
directory). The /EXACT qualifier directs the debugger to search for the version
last compiled (the version recorded in the debugger symbol table created at
compile time). For example, a SET SOURCE/LATEST command might search
for SORT.FOR;3 while a SET SOURCE/EXACT command might search for
SORT.FOR;1.
CANCEL SOURCE without the /DISPLAY or /EDIT qualifier cancels the effect of
both SET SOURCE/DISPLAY and SET SOURCE/EDIT, if both were previously
given.
The /DISPLAY qualifier is needed when the files to be displayed are no longer in
the compilation directory.
The /EDIT qualifier is needed when the files used for the display of source code
are different from the editable files. This is the case with Ada programs. For Ada
programs, the (SET,SHOW,CANCEL) SOURCE commands affect the search of
files used for source display (the "copied" source files in Ada program libraries);
the (SET,SHOW,CANCEL) SOURCE/EDIT commands affect the search of the
source files that you edit when using the EDIT command.
For information specific to Ada programs,type HELP Language_Support Ada.
Related commands:
(SET,SHOW) SOURCE
Examples
1.
DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD]
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
...
DEBUG–35
CANCEL SOURCE
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
SYSTEM::DEVICE:[PROJD]
source directory list for all other modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
DBG> CANCEL SOURCE
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
SYSTEM::DEVICE:[PROJD]
all other source files will try to match
the latest source file version
In this example, the SET SOURCE command establishes a directory search
list and a search method (the default, latest version) for source files other
than CTEST. The CANCEL SOURCE command cancels the directory search
list but does not cancel the search method.
2.
DBG> SET SOURCE/MODULE=CTEST/EXACT [],SYSTEM::DEVICE:[PROJD]
DBG> SET SOURCE [PROJA],[PROJB],[PETER.PROJC]
...
DBG> SHOW SOURCE
source directory search list for CTEST,
match the exact source file version:
[]
SYSTEM::DEVICE:[PROJD]
source directory list for all other modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
DBG> CANCEL SOURCE/MODULE=CTEST/EXACT
DBG> SHOW SOURCE
source directory search list for CTEST,
match the latest source file version:
[]
SYSTEM::DEVICE:[PROJD]
source directory list for all other modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
DBG> CANCEL SOURCE/MODULE=CTEST
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[PROJA]
[PROJB]
[PETER.PROJC]
In this example, the SET SOURCE/MODULE=CTEST/EXACT command
establishes a directory search list and a search method (exact version) for
the source file CTEST. The CANCEL SOURCE/MODULE=CTEST/EXACT
command cancels the CTEST search method (returning to the default latest
version), and the CANCEL SOURCE/MODULE=CTEST command cancels the
CTEST directory search list.
DEBUG–36
CANCEL SOURCE
3.
DBG> SET SOURCE /EXACT
DBG> SHOW SOURCE
no directory search list in effect,
match the exact source file
DBG> SET SOURCE [JONES]
DBG> SHOW SOURCE
source directory list for all modules,
match the exact source file version:
[JONES]
DBG> CANCEL SOURCE /EXACT
DBG> SHOW SOURCE
source directory list for all modules,
match the latest source file version:
[JONES]
In this example, the SET SOURCE/EXACT command establishes a search
method (exact version) that remains in effect for the SET SOURCE [JONES]
command. The CANCEL SOURCE/EXACT command not only cancels the
SET SOURCE/EXACT command, but also affects the SET SOURCE [JONES]
command.
DEBUG–37
CANCEL TRACE
CANCEL TRACE
Cancels a tracepoint.
Format
CANCEL TRACE [address-expression[, . . . ]]
Parameters
address-expression
Specifies a tracepoint to be canceled. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Cancels the effect of a previous SET TRACE/ACTIVATING command.
/ALL
By default, cancels all user-defined tracepoints. When used with /PREDEFINED,
it cancels all predefined tracepoints but no user-defined tracepoints. To cancel all
tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Cancels the effect of a previous SET TRACE/BRANCH command.
/CALL
Cancels the effect of a previous SET TRACE/CALL command.
/EVENT=event-name
Cancels the effect of a previous SET TRACE/EVENT=event-name command.
Specify the event name (and address expression, if any) exactly as specified with
the SET TRACE/EVENT command. To identify the current event facility and the
associated event names, use the SHOW EVENT_FACILITY command.
/EXCEPTION
Cancels the effect of a previous SET TRACE/EXCEPTION command.
/INSTRUCTION
Cancels the effect of a previous SET TRACE/INSTRUCTION command.
/LINE
Cancels the effect of a previous SET TRACE/LINE command.
/PREDEFINED
Cancels a specified predefined tracepoint without affecting any user-defined
tracepoints. When used with /ALL, it cancels all predefined tracepoints.
/TERMINATING
Cancels the effect of a previous SET TRACE/TERMINATING command.
DEBUG–38
CANCEL TRACE
/USER
Cancels a specified user-defined tracepoint without affecting any predefined
tracepoints. This is the default unless you specify /PREDEFINED. To cancel all
user-defined tracepoints, use /ALL.
Description
Tracepoints can be user defined or predefined. User-defined tracepoints are
explicitly set with the SET TRACE command. Predefined tracepoints, which
depend on the type of program you are debugging (for example, Ada or
multiprocess), are established automatically when you start the debugger.
Use the SHOW TRACE command to identify all tracepoints that are currently
set. Any predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled independently.
For example, a location or event can have both a user-defined and a predefined
tracepoint. Canceling the user-defined tracepoint does not affect the predefined
tracepoint, and conversely.
To cancel only user-defined tracepoints, do not specify /PREDEFINED with the
CANCEL TRACE command (the default is /USER). To cancel only predefined
tracepoints, specify /PREDEFINED but not /USER. To cancel both user-defined
and predefined tracepoints, use CANCEL TRACE/ALL/USER/PREDEFINED.
In general, the effect of CANCEL TRACE is symmetrical with that of SET
TRACE (even though SET TRACE is used only with user-defined tracepoints).
Thus, to cancel a tracepoint that was established at a specific location, specify
that same location (address expression) with CANCEL TRACE. To cancel
tracepoints that were established on a class of instructions or events, specify the
class of instructions or events with the corresponding qualifier (/LINE, /BRANCH,
/ACTIVATING, /EVENT=, and so on). For more information, see the qualifier
descriptions.
To cause the debugger to temporarily ignore a tracepoint, but retain definition of
the tracepoint, use the command DEACTIVATE TRACE. You can later activate
the tracepoint (with ACTIVATE TRACE).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) TRACE
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW) EVENT_FACILITY
Examples
1.
DBG> CANCEL TRACE MAIN\LOOP+10
This command cancels the user-defined tracepoint at the location
MAIN\LOOP+10.
2.
DBG> CANCEL TRACE/ALL
This command cancels all user-defined tracepoints.
DEBUG–39
CANCEL TRACE
3.
all> CANCEL TRACE/TERMINATING
This command cancels a previous SET TRACE/TERMINATING command.
As a result, a user-defined tracepoint is not triggered when a process does an
image exit.
4.
DBG> CANCEL TRACE/EVENT=RUN %TASK 3
This command cancels the tracepoint that was set to trigger when task 3
(task ID = 3) entered the RUN state.
DEBUG–40
CANCEL TYPE/OVERRIDE
CANCEL TYPE/OVERRIDE
Cancels the override type established by a previous SET TYPE/OVERRIDE
command.
Format
CANCEL TYPE/OVERRIDE
Description
The CANCEL TYPE/OVERRIDE command sets the current override type to
"none." As a result, a program location associated with a compiler-generated type
is interpreted according to that type.
Related commands:
DEPOSIT
EXAMINE
(SET,SHOW) EVENT_FACILITY
(SET,SHOW) TYPE/OVERRIDE
Example
DBG> CANCEL TYPE/OVERRIDE
This command cancels the effect of a previous SET TYPE/OVERRIDE command.
DEBUG–41
CANCEL WATCH
CANCEL WATCH
Cancels a watchpoint.
Format
CANCEL WATCH [address-expression[, . . . ]]
Parameters
address-expression
Specifies a watchpoint to be canceled. With high-level languages, this is typically
the name of a variable. Do not use the asterisk ( * ) wildcard character. Instead,
use the /ALL qualifier. Do not specify an address expression with /ALL.
Qualifiers
/ALL
Cancels all watchpoints.
Description
The effect of the CANCEL WATCH command is symmetrical with the effect of
the SET WATCH command. To cancel a watchpoint that was established at a
specific location with the SET WATCH command, specify that same location
with CANCEL WATCH. Thus, to cancel a watchpoint that was set on an entire
aggregate, specify the aggregate in the CANCEL WATCH command; to cancel a
watchpoint that was set on one element of an aggregate, specify that element in
the CANCEL WATCH command.
The CANCEL ALL command also cancels all watchpoints.
To cause the debugger to temporarily ignore a watchpoint, but not delete the
definition of the watchpoint, use the command DEACTIVATE WATCH. You can
later activate the watchpoint (with ACTIVATE WATCH).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) WATCH
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW,CANCEL) TRACE
Examples
1.
DBG> CANCEL WATCH SUB2\TOTAL
This command cancels the watchpoint at variable TOTAL in module SUB2.
2.
DBG> CANCEL WATCH/ALL
This command cancels all watchpoints you have set.
DEBUG–42
CANCEL WINDOW
CANCEL WINDOW
Permanently deletes a screen window definition.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
CANCEL WINDOW [window-name[, . . . ]]
Parameters
window-name
Specifies the name of a screen window definition to be canceled. Do not use the
asterisk ( * ) wildcard character. Instead, use the /ALL qualifier. Do not specify a
window definition name with /ALL.
Qualifiers
/ALL
Cancels all predefined and user-defined window definitions.
Description
When a window definition is canceled, you can no longer use its name in a
DISPLAY command. The CANCEL WINDOW command does not affect any
displays.
Related commands:
(SHOW,CANCEL) DISPLAY
(SET,SHOW) WATCH
Example
DBG> CANCEL WINDOW MIDDLE
This command permanently deletes the screen window definition MIDDLE.
DEBUG–43
CONNECT
CONNECT
(Kept debugger only.) Interrupts an image that is running without debugger
control in another process and brings that process under debugger control. When
used without a parameter, CONNECT brings any spawned process that is waiting
to connect to the debugger under debugger control.
On Alpha systems, the debugger command CONNECT can also be used to bring
a target system running the Alpha operating system under the control of the
OpenVMS Alpha System-Code Debugger. The OpenVMS Alpha System-Code
Debugger is a kernel debugger that you activate through the OpenVMS Debugger.
On Integrity servers, the debugger command CONNECT can also be used to
bring a target system running the Integrity server operating system under the
control of the OpenVMS Integrity server System-Code Debugger. The OpenVMS
Integrity server System-Code Debugger is a kernel debugger that you activate
through the OpenVMS Debugger.
If you are using the CONNECT command to debug the Alpha operating system,
you must complete the instructions described in the System Code Debugger
chapter of the OpenVMS Alpha System Analysis Tools Manual before you issue
the command. (These instructions include the creation of an Alpha device driver
and the setup commands activating the OpenVMS Alpha System-Code Debugger.)
You must also have started the OpenVMS Debugger with the DCL command
DEBUG/KEEP.
Format
CONNECT [process-spec]
CONNECT %NODE_NAME node-name
Parameters
process-spec
Specifies a process in which an image to be interrupted is running. The process
must be in the same OpenVMS job as the process in which the debugger was
started. Use any of the following forms:
[%PROCESS_NAME] proc-name
[%PROCESS_NAME] "proc-name"
%PROCESS_PID proc-id
DEBUG–44
The OpenVMS process name, if that
name contains no space or lowercase
characters. The process name can
include the asterisk ( * ) wildcard
character.
The OpenVMS process name, if that
name contains space or lowercase
characters. You can also use
apostrophes (’) instead of quotation
marks ( " ).
The OpenVMS process identifier (PID,
a hexadecimal number).
CONNECT
node-name
(Alpha or Integrity servers only) When you are debugging an Alpha or Integrity
server operating system, specifies the node name of the machine to which you are
connecting (the target machine running the Alpha or Integrity server operating
system).
Qualifiers
/PASSWORD="password"
(Alpha or Integrity servers only) When you are debugging an Alpha or Integrity
server operating system, specifies the password for the machine to which you are
connecting (the target machine running the Alpha or Integrity server operating
system). If a password has not been established for that machine, this qualifier
can be omitted.
/IMAGE_PATH="image-path"
(Alpha or Integrity servers only) When you are debugging an Alpha operating
system, specifies the image-path for the machine from which you are connecting
(the host machine running the debugger). The image-path is a logical name
that points to the location of system images. The default logical name is
DBGHK$IMAGE_PATH:.
Description
(Kept debugger only.) When you specify a process, the CONNECT command
enables you to interrupt an image that is running without debugger control
in that process and bring the process under debugger control. The command
is useful if, for example, you run a debuggable image with the DCL command
RUN/NODEBUG, or if your program issues a LIB$SPAWN Run-Time Library call
that does not start the debugger. You can connect to a process created through
a $CREPRC system service call only if you specify LOGINOUT.EXE as the
executable image.
Depending on the version of the debugger you are running on your system, you
may be restricted to connection with processes you created, or you may be able to
connect to processes created by any member of your user identification code (UIC)
group. (In some cases, you may have to set the SYSGEN SECURITY_POLICY
parameter to 8 before you create the process.)
If debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG,
DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and
VMSDEBUGUIL) exist, they must translate to the same definitions in both
the debugger and the target process.
The code in the image must be compiled with the /DEBUG qualifier and the
image must be linked with either /DEBUG or /DSF. The image must not be linked
with the /NOTRACEBACK qualifier.
When the process is brought under debugger control, execution of the image is
suspended at the point at which it was interrupted.
When you do not specify a process, the CONNECT command brings any processes
that are waiting to connect to your debugging session under debugger control. If
no process is waiting, you can press Ctrl/C to abort the CONNECT command.
DEBUG–45
CONNECT
By default, a tracepoint is triggered when a process is brought under debugger
control. This predefined tracepoint is equivalent to that resulting from entering
the SET TRACE/ACTIVATING command. The process is then known to the
debugger and can be identified in a SHOW PROCESS display.
You cannot use the CONNECT command to connect to a subprocess of a process
running under debugger control. Use the SET PROCESS command to connect to
such a subprocess.
Related commands:
DISCONNECT
Ctrl/Y
(SET,SHOW,CANCEL) TRACE
Using the CONNECT Command to Debug the OpenVMS Operating System
(Integrity servers and Alpha only)
You can use the CONNECT command to debug Alpha or Integrity server
operating system code with the OpenVMS System Code Debugger (SCD). This
capability requires two systems, one called the host and the other called the
target. The host and target must be running the same operating system (Alpha
or Integrity servers). The host is configured as a standard OpenVMS system,
from which you run the debugger using DEBUG/KEEP, then enter the CONNECT
command. The target is a standalone system that is booted in a special way that
enables SCD. Communication between the host and the target occurs over the
Ethernet network.
For complete information on using the OpenVMS System Code Debugger, see the
OpenVMS Alpha System Analysis Tools Manual.
Examples
1.
DBG_1> CONNECT
This command brings under debugger control any processes that are waiting
to be connected to the debugger.
2.
DBG_1> CONNECT JONES_3
This command interrupts the image running in process JONES_3 and brings
the process under debugger control. Process JONES_3 must be in the same
UIC group as the process in which the debugger was started. Also, the image
must not have been linked with the /NOTRACEBACK qualifier.
3.
DBG> CONNECT %NODE_NAME SCDTST /PASSWORD="eager_beaver"
%DEBUG-I-NOLOCALS, image does not contain local symbols
DBG>
This CONNECT command brings the target system running the OpenVMS
operating system under debugger control. This example specifies that the
target system has a node name of SCDTST and a password of eager_beaver.
DEBUG–46
Ctrl/C
Ctrl/C
When entered from within a debugging session, Ctrl/C aborts the execution of
a debugger command or interrupts program execution without interrupting the
debugging session.
Note
Do not use Ctrl/Y from within a debugging session.
Format
Ctrl/C
Description
Pressing Ctrl/C enables you to abort the execution of a debugger command or to
interrupt program execution without interrupting the debugging session. This is
useful when, for example, the program is executing an infinite loop that does not
have a breakpoint, or you want to abort a debugger command that takes a long
time to complete. The debugger prompt is then displayed, so that you can enter
debugger commands.
If your program already has a Ctrl/C AST service routine enabled, use the SET
ABORT_KEY command to assign the debugger’s abort function to another Ctrlkey sequence. Note, however, that many Ctrl-key sequences have predefined
functions, and the SET ABORT_KEY command enables you to override such
definitions (see the OpenVMS User’s Manual). Some of the Ctrl-key characters
not used by the operating system are G, K, N, and P.
If your program does not have a Ctrl/C AST service routine enabled and you
assign the debugger’s abort function to another Ctrl-key sequence, then Ctrl/C
behaves like Ctrl/Y—that is, it interrupts the debugging session and returns you
to DCL level.
Do not use Ctrl/Y from within a debugging session. Instead, use either Ctrl/C
or an equivalent Ctrl-key sequence established with the SET ABORT_KEY
command.
You can use the SPAWN and ATTACH commands to leave and return to a
debugging session without losing the debugging context.
Note
Pressing Ctrl/C to interrupt a program running under debugger control
works only once. Thereafter, the Ctrl/C interrupt is ignored. The
same is true when using the DECwindows STOP button; the action
is acknowledged only the first time the button is pressed.
Related commands:
ATTACH
Ctrl/Y
DEBUG–47
Ctrl/C
(SET,SHOW) ABORT_KEY
SPAWN
Example
DBG> GO
...
Ctrl/C
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
Ctrl/C
%DEBUG-W-ABORTED, command aborted by user request
DBG>
This example shows how to use Ctrl/C to interrupt program execution and then
to abort the execution of a debugger command.
DEBUG–48
Ctrl/W
Ctrl/W
Ctrl/W refreshes the screen in screen mode (like DISPLAY/REFRESH).
Format
Ctrl/W
Description
For more information about Ctrl/W, see the /REFRESH qualifier to the DISPLAY
command.
DEBUG–49
Ctrl/Y
Ctrl/Y
When entered from DCL level, Ctrl/Y interrupts an image that is running without
debugger control, enabling you then to start the debugger with the DCL command
DEBUG.
Notes
Do not use Ctrl/Y from within a debugging session. Instead, use Ctrl/C or
an equivalent abort-key sequence established with the SET ABORT_KEY
command.
When you start the debugger with the Ctrl/Y–DEBUG sequence, you
cannot then use the debugger RUN or RERUN commands.
Format
Ctrl/Y
Description
Pressing Ctrl/Y at DCL level enables you to interrupt an image that is running
without debugger control, so that you can then start the debugger with the DCL
command DEBUG.
You can bring an image under debugger control only if, as a minimum, that image
was linked with the /TRACEBACK qualifier (/TRACEBACK is the default for the
LINK command).
When you press Ctrl/Y to interrupt the image’s execution, control is passed to
DCL. If you then enter the DCL command DEBUG, the interrupted image is
brought under control of the debugger. The debugger sets its language-dependent
parameters to the source language of the module in which execution was
interrupted and displays its prompt. You can then determine where execution
was suspended by entering a SHOW CALLS command.
The Ctrl/Y–DEBUG sequence is not supported in the kept debugger configuration.
The Ctrl/Y–DEBUG sequence is not supported in the HP DECwindows Motif for
OpenVMS user interface to the debugger. Instead, use the STOP button.
Within a debugging session, you can use the CONNECT command to connect an
image that is running without debugger control in another process (of the same
job) to that debugging session.
Related commands:
CONNECT
Ctrl/C
DEBUG (DCL command)
RUN (DCL command)
DEBUG–50
Ctrl/Y
Examples
1.
$ RUN/NODEBUG TEST_B
...
Ctrl/Y
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: ADA, Module: SWAP
DBG>
In this example, the RUN/NODEBUG command executes the image TEST_B
without debugger control. Execution is interrupted with Ctrl/Y. The DEBUG
command then causes the debugger to be started. The debugger displays its
banner, sets the language-dependent parameters to the language (Ada, in this
case) of the module (SWAP) in which execution was interrupted, and displays
the prompt.
2.
$ RUN/NODEBUG PROG2
...
Ctrl/Y
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: FORTRAN, Module: SUB4
predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1
DBG>
In this example, the DEFINE/JOB command establishes a multiprocess
debugging configuration. The RUN/NODEBUG command executes the
image PROG2 without debugger control. The Ctrl/Y–DEBUG sequence
interrupts execution and starts the debugger. The banner indicates that a
new debugging session has been started. The activation tracepoint indicates
where execution was interrupted when the debugger took control of the
process.
DEBUG–51
Ctrl/Z
Ctrl/Z
Ctrl/Z ends a debugging session (like EXIT).
Format
Ctrl/Z
Description
For more information about Ctrl/Z, see the EXIT command.
DEBUG–52
DEACTIVATE BREAK
DEACTIVATE BREAK
Deactivates a breakpoint, which you can later activate.
Format
DEACTIVATE BREAK [address-expression[, . . . ]]
Parameters
address-expression
Specifies a breakpoint to be deactivated. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Deactivates a breakpoint established by a previous SET BREAK/ACTIVATING
command.
/ALL
By default, deactivates all user-defined breakpoints. When used with
/PREDEFINED, deactivates all predefined breakpoints but no user-defined
breakpoints. To deactivate all breakpoints, use /ALL/USER/PREDEFINED.
/BRANCH
Deactivates a breakpoint established by a previous SET BREAK/BRANCH
command.
/CALL
Deactivates a breakpoint established by a previous SET BREAK/CALL command.
/EVENT=event-name
Deactivates a breakpoint established by a previous SET BREAK/EVENT=eventname command. Specify the event name (and address expression, if any) exactly
as specified with the SET BREAK/EVENT command.
To identify the current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
/EXCEPTION
Deactivates a breakpoint established by a previous SET BREAK/EXCEPTION
command.
/HANDLER
Deactivates a breakpoint established by a previous SET BREAK/HANDLER
command.
/INSTRUCTION
Deactivates a breakpoint established by a previous SET BREAK/INSTRUCTION
command.
/LINE
Deactivates a breakpoint established by a previous SET BREAK/LINE command.
DEBUG–53
DEACTIVATE BREAK
/PREDEFINED
Deactivates a specified predefined breakpoint without affecting any user-defined
breakpoints. When used with /ALL, deactivates all predefined breakpoints.
/SYSEMULATE
(Alpha only) Deactivates a breakpoint established by a previous SET
BREAK/SYSEMULATE command.
/TERMINATING
Deactivates a breakpoint established by a previous SET BREAK/TERMINATING
command.
/UNALIGNED_DATA
(Alpha only) Deactivates a breakpoint established by a previous SET
BREAK/UNALIGNED_DATA command.
/USER
Deactivates a specified user-defined breakpoint. To deactivate all user-defined
breakpoints, use the /ALL qualifier.
Description
User-defined breakpoints are activated when you set them with the SET
BREAK command. Predefined breakpoints are activated by default. Use the
DEACTIVATE BREAK command to deactivate one or more breakpoints.
If you deactivate a breakpoint, the debugger ignores the breakpoint during
program execution. To activate a deactivated breakpoint, use the ACTIVATE
BREAK command. You can activate and deactivate user-defined and predefined
breakpoints separately. Activating and deactivating breakpoints enables you
to run and rerun your program with or without breakpoints without having to
cancel and then reset them. By default, the RERUN command saves the current
state of all breakpoints (activated or deactivated).
To check if a breakpoint is deactivated, use the SHOW BREAK command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,ACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY
Examples
1.
DBG> DEACTIVATE BREAK MAIN\LOOP+10
This command deactivates the user-defined breakpoint set at the address
expression MAIN\LOOP+10.
2.
DBG> DEACTIVATE BREAK/ALL
This command deactivates all user-defined breakpoints.
DEBUG–54
DEACTIVATE TRACE
DEACTIVATE TRACE
Deactivates a tracepoint, which you can later activate.
Format
DEACTIVATE TRACE [address-expression[, . . . ]]
Parameters
address-expression
Specifies a tracepoint to be deactivated. Do not use the asterisk ( * ) wildcard
character. Instead, use the /ALL qualifier. Do not specify an address expression
when using any qualifiers except /EVENT, /PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Deactivates a tracepoint established with a previous SET TRACE/ACTIVATING
command.
/ALL
By default, deactivates all user-defined tracepoints. When used with
/PREDEFINED, it deactivates all predefined tracepoints but no user-defined
tracepoints. To deactivate all tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Deactivates a tracepoint established with a previous SET TRACE/BRANCH
command.
/CALL
Deactivates a tracepoint established with a previous SET TRACE/CALL
command.
/EVENT=event-name
Deactivates a tracepoint established with a previous SET TRACE/EVENT=eventname command. Specify the event name (and address expression, if any) exactly
as specified with the SET TRACE/EVENT command.
To identify the current event facility and the associated event names, use the
SHOW EVENT_FACILITY command.
/EXCEPTION
Deactivates a tracepoint established with a previous SET TRACE/EXCEPTION
command.
/INSTRUCTION
Deactivates a tracepoint established with a previous SET TRACE/INSTRUCTION
command.
/LINE
Deactivates a tracepoint established with a previous SET TRACE/LINE
command.
DEBUG–55
DEACTIVATE TRACE
/PREDEFINED
Deactivates a specified predefined tracepoint without affecting any user-defined
tracepoints. When used with /ALL, it deactivates all predefined tracepoints.
/TERMINATING
Deactivates a tracepoint established with a previous SET
TRACE/TERMINATING command.
/USER
Deactivates a specified user-defined tracepoint without affecting any predefined
tracepoints. When used with /ALL, it deactivates all user-defined tracepoints.
The /USER qualifier is the default unless you specify /PREDEFINED.
Description
User-defined tracepoints are activated when you set them with the SET
TRACE command. Predefined tracepoints are activated by default. Use the
DEACTIVATE TRACE command to deactivate one or more tracepoints.
If you deactivate a tracepoint, the debugger ignores the tracepoint during
program execution. To activate a deactivated tracepoint, use the ACTIVATE
TRACE command. You can activate and deactivate user-defined and predefined
tracepoints separately. Activating and deactivating tracepoints enables you to
run and rerun your program with or without tracepoints without having to cancel
and then reset them. By default, the RERUN command saves the current state of
all tracepoints (activated or deactivated).
To check if a tracepoint is deactivated, use the SHOW TRACE command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,ACTIVATE) TRACE
Examples
1.
DBG> DEACTIVATE TRACE MAIN\LOOP+10
This command deactivates the user-defined tracepoint at the location
MAIN\LOOP+10.
2.
DBG> DEACTIVATE TRACE/ALL
This command deactivates all user-defined tracepoints.
DEBUG–56
DEACTIVATE WATCH
DEACTIVATE WATCH
Deactivates a watchpoint, which you can later activate.
Format
DEACTIVATE WATCH [address-expression[, . . . ]]
Parameters
address-expression
Specifies a watchpoint to be deactivated. With high-level languages, this is
typically the name of a variable. Do not use the asterisk ( * ) wildcard character.
Instead, use the /ALL qualifier. Do not specify an address expression with /ALL.
Qualifiers
/ALL
Deactivates all watchpoints.
Description
Watchpoints are activated when you set them with the SET WATCH command.
Use the DEACTIVATE WATCH command to deactivate one or more watchpoints.
If you deactivate a watchpoint, the debugger ignores the watchpoint during
program execution. To activate a deactivated watchpoint, use the ACTIVATE
WATCH command. Activating and deactivating watchpoints enables you to run
and rerun your program with or without watchpoints without having to cancel
and then reset them.
By default, the RERUN command saves the current state of all static watchpoints
(activated or deactivated). The state of a particular nonstatic watchpoint might or
might not be saved depending on the scope of the variable being watched relative
to the main program unit (where execution restarts).
To check if a watchpoint is deactivated, use the SHOW WATCH command.
Related commands:
CANCEL ALL
RERUN
(SET,SHOW,CANCEL,ACTIVATE) WATCH
Examples
1.
DBG> DEACTIVATE WATCH SUB2\TOTAL
This command deactivates the watchpoint at variable TOTAL in module
SUB2.
2.
DBG> DEACTIVATE WATCH/ALL
This command deactivates all watchpoints you have set.
DEBUG–57
DECLARE
DECLARE
Declares a formal parameter within a command procedure. This enables you to
pass an actual parameter to the procedure when entering an execute procedure
(@) command.
Format
DECLARE p-name:p-kind [,p-name:p-kind[, . . . ]]
Parameters
p-name
Specifies a formal parameter (a symbol) that is declared within the command
procedure.
Do not specify a null parameter (represented either by two consecutive commas
or by a comma at the end of the command).
p-kind
Specifies the parameter kind of a formal parameter. Valid keywords are as
follows:
ADDRESS
COMMAND
VALUE
Specifies that the actual parameter is interpreted
as an address expression. Same effect as
DEFINE/ADDRESS symbol-name = actual-parameter.
Specifies that the actual parameter is
interpreted as a command. Same effect as
DEFINE/COMMAND symbol-name = actual-parameter.
Specifies that the actual parameter is interpreted as a
value expression in the current language. Same effect as
DEFINE/VALUE symbol-name = actual-parameter.
Description
The DECLARE command is valid only within a command procedure.
The DECLARE command binds one or more actual parameters, specified on
the command line following the execute procedure (@) command, to formal
parameters (symbols) declared within a command procedure.
Each p-name:p-kind pair specified by a DECLARE command binds one formal
parameter to one actual parameter. Formal parameters are bound to actual
parameters in the order in which the debugger processes the parameter
declarations. If you specify several formal parameters on a single DECLARE
command, the leftmost formal parameter is bound to the first actual parameter,
the next formal parameter is bound to the second, and so on. If you use a
DECLARE command in a loop, the formal parameter is bound to the first actual
parameter on the first iteration of the loop; the same formal parameter is bound
to the second actual parameter on the next iteration, and so on.
Each parameter declaration acts like a DEFINE command: it associates a formal
parameter with an address expression, a command, or a value expression in
the current language, according to the parameter kind specified. The formal
parameters themselves are consistent with those accepted by the DEFINE
DEBUG–58
DECLARE
command and can in fact be deleted from the symbol table with the DELETE
command.
The %PARCNT built-in symbol, which can be used only within a command
procedure, enables you to pass a variable number of parameters to a command
procedure. The value of %PARCNT is the number of actual parameters passed to
the command procedure.
Related commands:
@ (Execute Procedure)
DEFINE
DELETE
Examples
1.
! ***** Command Procedure EXAM.COM *****
SET OUTPUT VERIFY
DECLARE K:ADDRESS
EXAMINE K
DBG> @EXAM ARR4
%DEBUG-I-VERIFYIC, entering command procedure EXAM
DECLARE K:ADDRESS
EXAMINE K
PROG_8\ARR4
(1):
18
(2):
1
(3):
0
(4):
1
%DEBUG-I-VERIFYIC, exiting command procedure EXAM
DBG>
In this example, the DECLARE K:ADDRESS command declares the formal
parameter K within command procedure EXAM.COM. When EXAM.COM
is executed, the actual parameter passed to EXAM.COM is interpreted as
an address expression, and the EXAMINE K command displays the value of
that address expression. The SET OUTPUT VERIFY command causes the
commands to echo when they are read by the debugger.
At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM,
passing the actual parameter ARR4. Within EXAM.COM, ARR4 is
interpreted as an address expression (an array variable, in this case).
2.
! ***** Debugger Command Procedure EXAM_GO.COM *****
DECLARE L:ADDRESS, M:COMMAND
EXAMINE L; M
DBG> @EXAM_GO X "@DUMP"
In this example, the command procedure EXAM_GO.COM accepts two
parameters, an address expression ( L ) and a command string ( M ). The
address expression is then examined and the command is executed.
At the debugger prompt, the @EXAM_GO X "@DUMP" command executes
EXAM_GO.COM, passing the address expression X and the command string
@DUMP.
DEBUG–59
DECLARE
3.
! ***** Debugger Command Procedure VAR.DBG *****
SET OUTPUT VERIFY
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
DBG> @VAR.DBG 12,37,45
%DEBUG-I-VERIFYIC, entering command procedure VAR.DBG
FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
12
37
45
%DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
DBG>
In this example, the command procedure VAR.DBG accepts a variable number
of parameters. That number is stored in the built-in symbol %PARCNT.
At the debugger prompt, the @VAR.DBG command executes VAR.DBG,
passing the actual parameters 12, 37, and 45. Therefore, %PARCNT has the
value 3, and the FOR loop is repeated 3 times. The FOR loop causes the
DECLARE command to bind each of the three actual parameters (starting
with 12) to a new declaration of X. Each actual parameter is interpreted as
a value expression in the current language, and the EVALUATE X command
displays that value.
DEBUG–60
DEFINE
DEFINE
Assigns a symbolic name to an address expression, command, or value.
Format
DEFINE symbol-name=parameter [,symbol-name=parameter[, . . . ]]
Parameters
symbol-name
Specifies a symbolic name to be assigned to an address, command, or value. The
symbolic name can be composed of alphanumeric characters and underscores.
The debugger converts lowercase alphabetic characters to uppercase. The first
character must not be a number. The symbolic name must be no more than 31
characters long.
parameter
Depends on the qualifier specified.
Qualifiers
/ADDRESS
(Default) Specifies that the defined symbol is an abbreviation for an address
expression. In this case, parameter is an address expression.
/COMMAND
Specifies that the defined symbol is treated as a new debugger command. In this
case, parameter is a quoted character string. This qualifier provides, in simple
cases, essentially the same capability as the following DCL command:
$ symbol := string
To define complex commands, you might need to use command procedures
with formal parameters. For more information about declaring parameters to
command procedures, see the DECLARE command.
/LOCAL
Specifies that the definition is valid only in the command procedure in which it is
defined. The defined symbol is not visible at debugger command level. By default,
a symbol defined within a command procedure is visible outside that procedure.
/VALUE
Specifies that the defined symbol is an abbreviation for a value. In this case,
parameter is a language expression in the current language.
Description
The DEFINE/ADDRESS command assigns a symbolic name to an address
expression in a program. You can define a symbol for a nonsymbolic program
location or for a symbolic program location having a long path-name prefix. You
can then refer to that program location with the symbolic name. The /ADDRESS
qualifier is the default.
The DEFINE/COMMAND command enables you to define abbreviations for
debugger commands or even define new commands, either from the debugger
command level or from command procedures.
DEBUG–61
DEFINE
The DEFINE/VALUE command enables you to assign a symbolic name to a value
(or the result of evaluating a language expression).
The DEFINE/LOCAL command confines symbol definitions to command
procedures. By default, defined symbols are global (visible outside the command
procedure).
To enter several DEFINE commands with the same qualifier, first use the
SET DEFINE command to establish a new default qualifier (for example,
SET DEFINE COMMAND makes subsequent DEFINE commands behave like
DEFINE/COMMAND). You can override the current default qualifier for a single
DEFINE command by specifying another qualifier.
In symbol translation, the debugger searches symbols you define during the
debugging session first. So if you define a symbol that already exists in your
program, the debugger translates the symbol according to its defined definition,
unless you specify a path-name prefix.
If a symbol is redefined, the previous definition is canceled, even if you used
different qualifiers with the DEFINE command.
Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands
are available only when the image in whose context they were created is the
current image. If you use the SET IMAGE command to establish a new current
image, these definitions are temporarily unavailable. However, definitions created
with the DEFINE/COMMAND and DEFINE/KEY commands are always available
for all images.
Use the SHOW SYMBOL/DEFINED command to determine the equivalence
value of a symbol.
Use the DELETE command to cancel a symbol definition.
Related commands:
DECLARE
DELETE
SET IMAGE
SHOW DEFINE
SHOW SYMBOL/DEFINED
Examples
1.
DBG> DEFINE CHK=MAIN\LOOP+10
This command assigns the symbol CHK to the address MAIN\LOOP+10.
2.
DBG> DEFINE/VALUE COUNTER=0
DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1)
In this example, the DEFINE/VALUE command assigns a value of 0 to
the symbol COUNTER. The SET TRACE command causes the debugger to
increment the value of the symbol COUNTER by 1 whenever address R is
encountered. In other words, this example counts the number of calls to R.
3.
DBG> DEFINE/COMMAND BRE = "SET BREAK"
This command assigns the symbol BRE to the debugger command SET
BREAK.
DEBUG–62
DEFINE/KEY
DEFINE/KEY
Assigns a string to a function key.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
DEFINE/KEY key-name "equivalence-string"
Parameters
key-name
Specifies a function key to be assigned a string. Valid key names are as follows:
Key Name
LK201 Keyboard
VT100-type
VT52-type
PF1
PF2
PF3
PF4
KP0–KP9
PERIOD
COMMA
MINUS
ENTER
E1
E2
E3
E4
E5
E6
HELP
DO
F6–F20
PF1
PF2
PF3
PF4
Keypad 0–9
Keypad period ( . )
Keypad comma ( , )
Keypad minus ( – )
Enter
Find
Insert Here
Remove
Select
Prev Screen
Next Screen
Help
Do
F6–F20
PF1
PF2
PF3
PF4
Keypad 0–9
Keypad period ( . )
Keypad comma ( , )
Keypad minus ( – )
ENTER
Blue
Red
Black
Keypad 0–9
ENTER
On LK201 keyboards:
•
You cannot define keys F1 to F5 or the arrow keys (E7 to E10).
•
You can define keys F6 to F14 only if you have first entered the DCL
command SET TERMINAL/NOLINE_EDITING. In that case, the line-editing
functions of the left and right arrow keys (E8 and E9) are disabled.
DEBUG–63
DEFINE/KEY
equivalence-string
Specifies the string to be processed when you press the specified key. Typically,
this is one or more debugger commands. If the string includes any space
or nonalphanumeric characters (for example, a semicolon separating two
commands), enclose the string in quotation marks ( " ).
Qualifiers
/ECHO (default)
/NOECHO
Controls whether the command line is displayed after the key has been pressed.
Do not use /NOECHO with /NOTERMINATE.
/IF_STATE=(state-name[, . . . ])
/NOIF_STATE (default)
Specifies one or more states to which a key definition applies. The /IF_STATE
qualifier assigns the key definition to the specified states. You can specify
predefined states, such as DEFAULT and GOLD, or user-defined states. A state
name can be any appropriate alphanumeric string. The /NOIF_STATE qualifier
assigns the key definition to the current state.
/LOCK_STATE
/NOLOCK_STATE (default)
Controls how long the state set by /SET_STATE remains in effect after the
specified key is pressed. The /LOCK_STATE qualifier causes the state to remain
in effect until it is changed explicitly (for example, with a SET KEY/STATE
command). The /NOLOCK_STATE qualifier causes the state to remain in effect
only until the next terminator character is typed, or until the next defined
function key is pressed.
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the key definition has
been successfully created. The /LOG qualifier displays the message. The /NOLOG
qualifier suppresses the message.
/SET_STATE=state-name
/NOSET_STATE (default)
Controls whether pressing the key changes the current key state. The /SET_
STATE qualifier causes the current state to change to the specified state when
you press the key. The /NOSET_STATE qualifier causes the current state to
remain in effect.
/TERMINATE
/NOTERMINATE (default)
Controls whether the specified string is terminated (processed) when the key is
pressed. The /TERMINATE qualifier causes the string to be terminated when the
key is pressed. The /NOTERMINATE qualifier enables you to press other keys
before terminating the string by pressing the Return key.
DEBUG–64
DEFINE/KEY
Description
Keypad mode must be enabled (SET MODE KEYPAD) before you can use this
command. Keypad mode is enabled by default.
The DEFINE/KEY command enables you to assign a string to a function key,
overriding any predefined function that was bound to that key. When you
then press the key, the debugger enters the currently associated string into
your command line. The DEFINE/KEY command is like the DCL command
DEFINE/KEY.
For a list of the predefined key functions, see the Keypad_Definitions_CI online
help topic.
On VT52- and VT100-series terminals, the function keys you can use include all
of the numeric keypad keys. Newer terminals and workstations have the LK201
keyboard. On LK201 keyboards, the function keys you can use include all of the
numeric keypad keys, the nonarrow keys of the editing keypad (Find, Insert Here,
and so on), and keys F6 to F20 at the top of the keyboard.
A key definition remains in effect until you redefine the key, enter the
DELETE/KEY command for that key, or exit the debugger. You can include
key definitions in a command procedure, such as your debugger initialization file.
The /IF_STATE qualifier enables you to increase the number of key definitions
available on your terminal. The same key can be assigned any number of
definitions as long as each definition is associated with a different state.
By default, the current key state is the DEFAULT state. The current state can be
changed with the SET KEY/STATE command, or by pressing a key that causes
a state change (a key that was defined with DEFINE/KEY/LOCK_STATE/SET_
STATE).
Related commands:
DELETE/KEY
(SET,SHOW) KEY
Examples
1.
DBG> SET KEY/STATE=GOLD
%DEBUG-I-SETKEY, keypad state has been set to GOLD
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX"
%DEBUG-I-DEFKEY, GOLD key KP9 has been defined
In this example, the SET KEY command establishes GOLD as the current
key state. The DEFINE/KEY command assigns the SET RADIX/OVERRIDE
HEX command to keypad key 9 (KP9) for the current state (GOLD). The
command is processed when you press the key.
2.
DBG> DEFINE/KEY/IF_STATE=BLUE KP9 "SET BREAK %LINE "
%DEBUG-I-DEFKEY, BLUE key KP9 has been defined
This command assigns the unterminated command string "SET BREAK
%LINE" to keypad key 9 for the BLUE state. After pressing BLUE-KP9,
you can enter a line number and then press the Return key to terminate and
process the SET BREAK command.
DEBUG–65
DEFINE/KEY
3.
DBG> SET KEY/STATE=DEFAULT
%DEBUG-I-SETKEY, keypad state has been set to DEFAULT
DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE F12 ""
%DEBUG-I-DEFKEY, DEFAULT key F12 has been defined
In this example, the SET KEY command establishes DEFAULT as the
current state. The DEFINE/KEY command makes the F12 key (on an LK201
keyboard) a state key. Pressing F12 while in the DEFAULT state causes the
current state to become RED. The key definition is not terminated and has
no other effect (a null string is assigned to F12). After pressing F12, you can
enter "RED" commands by pressing keys that have definitions associated
with the RED state.
DEBUG–66
DEFINE/PROCESS_SET
DEFINE/PROCESS_SET
Assigns a symbolic name to a list of process specifications.
Format
DEFINE/PROCESS_SET process-set-name =process-spec[, . . . ]
Parameters
process-set-name
Specifies a symbolic name to be assigned to a list of process specifications. The
symbolic name can be composed of alphanumeric characters and underscores.
The debugger converts lowercase alphabetic characters to uppercase. The first
character must not be a number. The symbolic name must be no more than 31
characters long.
process-spec
Specifies a process currently under debugger control. Use any of the following
forms:
[%PROCESS_NAME] process-name
[%PROCESS_NAME] "process-name "
%PROCESS_PID process_id
[%PROCESS_NUMBER] process-number
(or %PROC process-number)
process-set-name
The process name, if that name
does not contain spaces or lowercase
characters. The process name can
include the asterisk ( * ) wildcard
character.
The process name, if that name
contains spaces or lowercase
characters. You can also use
apostrophes (’) instead of quotation
marks ( " ).
The process identifier (PID, a
hexadecimal number).
The number assigned to a process
when it comes under debugger
control. A new number is assigned
sequentially, starting with 1, to each
process. If a process is terminated
with the EXIT or QUIT command,
the number can be assigned again
during the debugging session.
Process numbers appear in a SHOW
PROCESS display. Processes are
ordered in a circular list so they
can be indexed with the built-in
symbols %PREVIOUS_PROCESS
and %NEXT_PROCESS.
A symbol defined with the
DEFINE/PROCESS_SET command
to represent a group of processes.
DEBUG–67
DEFINE/PROCESS_SET
%NEXT_PROCESS
%PREVIOUS_PROCESS
%VISIBLE_PROCESS
The next process after the visible
process in the debugger’s circular
process list.
The process previous to the visible
process in the debugger’s circular
process list.
The process whose stack, register set,
and images are the current context
for looking up symbols, register
values, routine calls, breakpoints,
and so on.
If you do not specify a process, the symbolic name is created but contains no
process entries.
Description
The DEFINE/PROCESS_SET command assigns a symbol to a list of process
specifications. You can then use the symbol in any command where a list of
process specifications is allowed.
The DEFINE/PROCESS_SET command does not verify the existence of a specified
process. This enables you to specify processes that do not yet exist.
To identify a symbol that was defined with the DEFINE/PROCESS_SET
command, use the SHOW SYMBOL/DEFINED command. To delete a symbol
that was defined with the DEFINE/PROCESS_SET command, use the DELETE
command.
Related commands:
DELETE
(SET,SHOW) DEFINE
SHOW SYMBOL/DEFINED
Examples
1.
all> DEFINE/PROCESS_SET SERVERS=FILE_SERVER,NETWORK_SERVER
all> SHOW PROCESS SERVERS
Number Name
State Current PC
*
1 FILE_SERVER
step
FS_PROG\%LINE 37
2 NETWORK_SERVER
break NET_PROG\%LINE 24
all>
This DEFINE/PROCESS_SET command assigns the symbolic name
SERVERS to the process set consisting of FILE_SERVER and NETWORK_
SERVER. The SHOW PROCESS SERVERS command displays information
about the processes that make up the set SERVERS.
2.
all> DEFINE/PROCESS_SET G1=%PROCESS_NUMBER 1,%VISIBLE_PROCESS
all> SHOW SYMBOL/DEFINED G1
defined G1
bound to: "%PROCESS_NUMBER 1, %VISIBLE_PROCESS"
was defined /process_set
all> DELETE G1
This DEFINE/PROCESS_SET command assigns the symbolic name G1 to the
process set consisting of process 1 and the visible process (process 3). The
SHOW SYMBOL/DEFINED G1 command identifies the defined symbol G1.
DEBUG–68
DEFINE/PROCESS_SET
The DELETE G1 command deletes the symbol from the DEFINE symbol
table.
3.
all> DEFINE/PROCESS_SET A = B,C,D
all> DEFINE/PROCESS_SET B = E,F,G
all> DEFINE/PROCESS_SET E = I,J,A
%DEBUG-E-NORECSYM, recursive PROCESS_SET symbol definition
encountered at or near "A"
This series of DEFINE/PROCESS_SET commands illustrate valid and invalid
uses of the command.
DEBUG–69
DELETE
DELETE
Deletes a symbol definition that was established with the DEFINE command.
Format
DELETE [symbol-name[, . . . ]]
Parameters
symbol-name
Specifies a symbol whose definition is to be deleted from the DEFINE symbol
table. Do not use the asterisk ( * ) wildcard character. Instead, use the /ALL
qualifier. Do not specify a symbol name with /ALL. If you use the /LOCAL
qualifier, the symbol specified must have been previously defined with the
DEFINE/LOCAL command. If you do not specify /LOCAL, the symbol specified
must have been previously defined with the DEFINE command without /LOCAL.
Qualifiers
/ALL
Deletes all global DEFINE definitions. Using /ALL/LOCAL deletes all local
DEFINE definitions associated with the current command procedure (but not the
global DEFINE definitions).
/LOCAL
Deletes the (local) definition of the specified symbol from the current
command procedure. The symbol must have been previously defined with
the DEFINE/LOCAL command.
Description
The DELETE command deletes either a global DEFINE symbol or a local
DEFINE symbol. A global DEFINE symbol is defined with the DEFINE command
without the /LOCAL qualifier. A local DEFINE symbol is defined in a debugger
command procedure with the DEFINE/LOCAL command, so that its definition is
confined to that command procedure.
Related commands:
DECLARE
DEFINE
SHOW DEFINE
SHOW SYMBOL/DEFINED
Examples
1.
DBG> DEFINE X = INARR, Y = OUTARR
DBG> DELETE X,Y
In this example, the DEFINE command defines X and Y as global symbols
corresponding to INARR and OUTARR, respectively. The DELETE command
deletes these two symbol definitions from the global symbol table.
DEBUG–70
DELETE
2.
DBG> DELETE/ALL/LOCAL
This command deletes all local symbol definitions from the current command
procedure.
DEBUG–71
DELETE/KEY
DELETE/KEY
Deletes a key definition that was established with the DEFINE/KEY command or,
by default, by the debugger.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
DELETE/KEY
[key-name]
Parameters
key-name
Specifies a key whose definition is to be deleted. Do not use the asterisk ( * )
wildcard character. Instead, use the /ALL qualifier. Do not specify a key name
with /ALL. Valid key names are as follows:
DEBUG–72
Key Name
LK201 Keyboard
VT100-type
VT52-type
PF1
PF2
PF3
PF4
KP0–KP9
PERIOD
COMMA
MINUS
ENTER
ENTER
E1
E2
E3
E4
E5
E6
HELP
DO
F6–F20
PF1
PF2
PF3
PF4
Keypad 0–9
Keypad period ( . )
Keypad comma ( , )
Keypad minus ( – )
Enter
Enter
Find
Insert Here
Remove
Select
Prev Screen
Next Screen
Help
Do
F6–F20
PF1
PF2
PF3
PF4
Keypad 0–9
Keypad period ( . )
Keypad comma ( , )
Keypad minus ( – )
ENTER
ENTER
Blue
Red
Black
Keypad 0–9
ENTER
ENTER
DELETE/KEY
Qualifiers
/ALL
Deletes all key definitions in the specified state. If you do not specify a state, all
key definitions in the current state are deleted. To specify one or more states, use
/STATE=state-name.
/LOG (default)
/NOLOG
Controls whether a message is displayed indicating that the specified key
definitions have been deleted. The /LOG qualifier (which is the default) displays
the message. The /NOLOG qualifier suppresses the message.
/STATE=(state-name [, . . . ])
/NOSTATE (default)
Selects one or more states for which a key definition is to be deleted. The /STATE
qualifier deletes key definitions for the specified states. You can specify predefined
key states, such as DEFAULT and GOLD, or user-defined states. A state name
can be any appropriate alphanumeric string. The /NOSTATE qualifier deletes the
key definition for the current state only.
By default, the current key state is the DEFAULT state. The current state can be
changed with the SET KEY/STATE command, or by pressing a key that causes
a state change (a key that was defined with DEFINE/KEY/LOCK_STATE/SET_
STATE).
Description
The DELETE/KEY command is like the DCL command DELETE/KEY.
Keypad mode must be enabled (SET MODE KEYPAD) before you can use this
command. Keypad mode is enabled by default.
Related commands:
DEFINE/KEY
(SET,SHOW) KEY
Examples
1.
DBG> DELETE/KEY KP4
%DEBUG-I-DELKEY, DEFAULT key KP4 has been deleted
This command deletes the key definition for KP4 in the state last set by the
SET KEY command (by default, this is the DEFAULT state).
2.
DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA
%DEBUG-I-DELKEY, BLUE key COMMA has been deleted
%DEBUG-I-DELKEY, RED key COMMA has been deleted
This command deletes the key definition for the COMMA key in the BLUE
and RED states.
DEBUG–73
DEPOSIT
DEPOSIT
Changes the value of a program variable. More generally, deposits a new value at
the location denoted by an address expression.
Format
DEPOSIT address-expression = language-expression
Parameters
address-expression
Specifies the location into which the value of the language expression is to be
deposited. With high-level languages, this is typically the name of a variable
and can include a path name to specify the variable uniquely. More generally,
an address expression can also be a memory address or a register and can be
composed of numbers (offsets) and symbols, as well as one or more operators,
operands, or delimiters. For information about the debugger symbols for the
registers and about the operators you can use in address expressions, see the
Built_in_Symbols and Address_Expressions help topics.
You cannot specify an entire aggregate variable (a composite data structure such
as an array or a record). To specify an individual array element or a record
component, follow the syntax of the current language.
language-expression
Specifies the value to be deposited. You can specify any language expression that
is valid in the current language. For most languages, the expression can include
the names of simple (noncomposite, single-valued) variables but not the names
of aggregate variables (such as arrays or records). If the expression contains
symbols with different compiler-generated types, the debugger uses the rules of
the current language to evaluate the expression.
If the expression is an ASCII string or an assembly-language instruction, you
must enclose it in quotation marks ( " ) or apostrophes (’). If the string contains
quotation marks or apostrophes, use the other delimiter to enclose the string.
If the string has more characters (1-byte ASCII) than can fit into the program
location denoted by the address expression, the debugger truncates the extra
characters from the right. If the string has fewer characters, the debugger pads
the remaining characters to the right of the string by inserting ASCII space
characters.
Qualifiers
/ASCIC
/AC
Deposits a counted ASCII string into the specified location. You must specify a
quoted string on the right-hand side of the equal sign. The deposited string is
preceded by a 1-byte count field that gives the length of the string.
/ASCID
/AD
Deposits an ASCII string into the address given by a string descriptor that is at
the specified location. You must specify a quoted string on the right-hand side
of the equal sign. The specified location must contain a string descriptor. If the
DEBUG–74
DEPOSIT
string lengths do not match, the string is either truncated on the right or padded
with space characters on the right.
/ASCII:n
Deposits n bytes of an ASCII string into the specified location. You must specify
a quoted string on the right-hand side of the equal sign. If its length is not n, the
string is truncated or padded with space characters on the right. If you omit n,
the actual length of the data item at the specified location is used.
/ASCIW
/AW
Deposits a counted ASCII string into the specified location. You must specify a
quoted string on the right-hand side of the equal sign. The deposited string is
preceded by a 2-byte count field that gives the length of the string.
/ASCIZ
/AZ
Deposits a zero-terminated ASCII string into the specified location. You must
specify a quoted string on the right-hand side of the equal sign. The deposited
string is terminated by a zero byte that indicates the end of the string.
/BYTE
Deposits a 1-byte integer into the specified location.
/D_FLOAT
Converts the expression on the right-hand side of the equal sign to the D_floating
type (length 8 bytes) and deposits the result into the specified location.
/DATE_TIME
Converts a string representing a date and time (for example, 21-DEC-1988
21:08:47.15) to the internal format for date and time and deposits that value
(length 8 bytes) into the specified location. Specify an absolute date and time in
the following format:
[dd-mmm-yyyy[:]] [hh:mm:ss.cc]
/EXTENDED_FLOAT
/X_FLOAT
(Alpha only) Converts the expression on the right-hand side of the equal sign
to the IEEE X_floating type (length 16 bytes) and deposits the result into the
specified location.
/FLOAT
On Alpha, converts the expression on the right-hand side of the equal sign to the
IEEE T_floating type (double precision, length 8 bytes) and deposits the result
into the specified location.
/G_FLOAT
Converts the expression on the right-hand side of the equal sign to the G_floating
type (length 8 bytes) and deposits the result into the specified location.
/LONG_FLOAT
/S_FLOAT
(Integrity servers and Alpha only) Converts the expression on the right-hand side
of the equal sign to the IEEE S_floating type (single precision, length 4 bytes)
and deposits the result into the specified location.
DEBUG–75
DEPOSIT
/LONG_LONG_FLOAT
/T_FLOAT
(Integrity servers and Alpha only) Converts the expression on the right-hand side
of the equal sign to the IEEE T_floating type (double precision, length 8 bytes)
and deposits the result into the specified location.
/LONGWORD
Deposits a longword integer (length 4 bytes) into the specified location.
/OCTAWORD
Deposits an octaword integer (length 16 bytes) into the specified location.
/PACKED:n
Converts the expression on the right-hand side of the equal sign to a packed
decimal representation and deposits the resulting value into the specified
location. The value of n is the number of decimal digits. Each digit occupies one
nibble (4 bits).
/QUADWORD
Deposits a quadword integer (length 8 bytes) into the specified location.
/TASK
Applies to tasking (multithread) programs. Deposits a task value (a task name or
a task ID such as %TASK 3) into the specified location. The deposited value must
be a valid task value.
/TYPE=(name)
Converts the expression to be deposited to the type denoted by name (which must
be the name of a variable or data type declared in the program), then deposits
the resulting value into the specified location. This enables you to specify a
user-declared type. You must use parentheses around the type expression.
/WCHAR_T[:n]
Deposits up to n longwords (n characters) of a converted multibyte file code
sequence into the specified location. The default is 1 longword. You must specify
a string on the right-hand side of the equal sign.
When converting the specified string, the debugger uses the locale database of the
process in which the debugger runs. The default is C locale.
/WORD
Deposits a word integer (length 2 bytes) into the specified location.
Description
You can use the DEPOSIT command to change the contents of any memory
location or register that is accessible in your program. For high-level languages
the command is used mostly to change the value of a variable (an integer, real,
string, array, record, and so on).
The DEPOSIT command is like an assignment statement in most programming
languages. The value of the expression specified to the right of the equal sign is
assigned to the variable or other location specified to the left of the equal sign.
For Ada and Pascal, you can use ":=" instead of "=" in the command syntax.
DEBUG–76
DEPOSIT
The debugger recognizes the compiler-generated types associated with symbolic
address expressions (symbolic names declared in your program). Symbolic
address expressions include the following entities:
•
Variable names. When specifying a variable with the DEPOSIT command,
use the same syntax that is used in the source code.
•
Routine names, labels, and line numbers.
In general, when you enter a DEPOSIT command, the debugger takes the
following actions:
•
It evaluates the address expression specified to the left of the equal sign, to
yield a program location.
•
If the program location has a symbolic name, the debugger associates the
location with the symbol’s compiler-generated type. If the location does not
have a symbolic name (and, therefore, no associated compiler-generated
type) the debugger associates the location with the type longword integer by
default. This means that, by default, you can deposit integer values that do
not exceed 4 bytes into these locations.
•
It evaluates the language expression specified to the right of the equal sign,
in the syntax of the current language and in the current radix, to yield a
value. The current language is the language last established with the SET
LANGUAGE command. By default, if you did not enter a SET LANGUAGE
command, the current language is the language of the module containing the
main program.
•
It checks that the value and type of the language expression is consistent
with the type of the address expression. If you try to deposit a value that
is incompatible with the type of the address expression, the debugger issues
a diagnostic message. If the value is compatible, the debugger deposits the
value into the location denoted by the address expression.
The debugger might do type conversion during a deposit operation if the language
rules allow it. For example, a real value specified to the right of the equal sign
might be converted to an integer value if it is being deposited into a location with
an integer type. In general, the debugger tries to follow the assignment rules for
the current language.
There are several ways of changing the type associated with a program location
so that you can deposit data of a different type into that location:
•
To change the default type for all locations that do not have a symbolic name,
you can specify a new type with the SET TYPE command.
•
To change the default type for all locations (both those that do and do
not have a symbolic name), you can specify a new type with the SET
TYPE/OVERRIDE command.
•
To override the type currently associated with a particular location for the
duration of a single DEPOSIT command, you can specify a new type by using
a qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on).
When debugging a C program, or a program in any case-specific language, you
cannot use the DEPOSIT/TYPE command if the type specified is a mixed or
lowercase name. For example, suppose the program has a function like the
following:
DEBUG–77
DEPOSIT
xyzzy_type foo ()
{
xyzzy_type
z;
z = get_z ();
return (z);
}
If you try to enter the following command, the debugger issues a message that it
cannot find the type ‘‘xyzzy_type’’:
DBG> DEPOSIT/TYPE=(xyzzy_type) z="whatever"
The debugger can interpret and display integer data in any one of four radixes:
binary, decimal, hexadecimal, and octal.
The default radix for both data entry and display is decimal for most languages.
The exceptions are BLISS and MACRO, which have a default radix of
hexadecimal.
You can use the SET RADIX and SET RADIX/OVERRIDE commands to change
the default radix.
The DEPOSIT command sets the current entity built-in symbols %CURLOC and
period ( . ) to the location denoted by the address expression specified. Logical
predecessors (%PREVLOC or the circumflex character ( ^ )) and successors
(%NEXTLOC) are based on the value of the current entity.
Related commands:
CANCEL TYPE/OVERRIDE
EVALUATE
EXAMINE
MONITOR
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
Examples
1.
DBG> DEPOSIT I = 7
This command deposits the value 7 into the integer variable I.
2.
DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 24.80
This command deposits the value of the expression CURRENT_WIDTH +
24.80 into the real variable WIDTH.
3.
DBG> DEPOSIT STATUS = FALSE
This command deposits the value FALSE into the Boolean variable STATUS.
4.
DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84"
This command deposits the string WG-7619.3-84 into the string variable
PART_NUMBER.
5.
DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172
This command deposits the value 02172 into component ZIPCODE of record
EMPLOYEE.
DEBUG–78
DEPOSIT
6.
DBG> DEPOSIT ARR(8) = 35
DBG> DEPOSIT ^ = 14
In this example, the first DEPOSIT command deposits the value 35 into
element 8 of array ARR. As a result, element 8 becomes the current entity.
The second command deposits the value 14 into the logical predecessor of
element 8, namely element 7.
7.
DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0)
This command deposits the value 0 into elements 1 to 4 of array ARR.
8.
DBG> DEPOSIT COLOR = 3
%DEBUG-E-OPTNOTALLOW, operator "DEPOSIT" not allowed on
given data type
The debugger alerts you when you try to deposit data of the wrong type
into a variable (in this case, if you try to deposit an integer value into an
enumerated type variable). The E (error) message severity indicates that the
debugger does not make the assignment.
9.
DBG> DEPOSIT VOLUME = - 100
%DEBUG-I-IVALOUTBNDS, value assigned is out of bounds
at or near ’-’
The debugger alerts you when you try to deposit an out-of-bounds value into
a variable (in this case a negative value). The I (informational) message
severity indicates that the debugger does make the assignment.
10.
DBG> DEPOSIT/BYTE WORK = %HEX 21
This command deposits the expression %HEX 21 into location WORK and
converts it to a byte integer.
11.
DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555
This command deposits the expression 111222333444555 into location
BIGINT and converts it to an octaword integer.
12.
DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35
This command converts 1.11949*10**35 to an F_floating type value and
deposits it into location BIGFLT.
13.
DBG> DEPOSIT/ASCII:10 WORK+20 = ’abcdefghij’
This command deposits the string "abcdefghij" into the location that is 20
bytes beyond that denoted by the symbol WORK.
14.
DBG> DEPOSIT/TASK VAR = %TASK 2
DBG> EXAMINE/HEX VAR
SAMPLE.VAR: 0016A040
DBG> EXAMINE/TASK VAR
SAMPLE.VAR: %TASK 2
DBG>
The DEPOSIT command deposits the Ada task value %TASK 2 into location
VAR. The subsequent EXAMINE commands display the contents of VAR in
hexadecimal format and as a task value, respectively.
DEBUG–79
DISABLE AST
DISABLE AST
Disables the delivery of asynchronous system traps (ASTs) in your program.
Format
DISABLE AST
Description
The DISABLE AST command disables the delivery of ASTs in your program and
thereby prevents interrupts from occurring while the program is running. If ASTs
are delivered while the debugger is running (processing commands, and so on),
they are queued and are delivered when control is returned to the program.
The ENABLE AST command reenables the delivery of ASTs, including any
pending ASTs (ASTs waiting to be delivered).
Note
Any call by your program to the $SETAST system service that enables
ASTs overrides a previous DISABLE AST command.
Related commands:
(ENABLE,SHOW) AST
Example
DBG> DISABLE AST
DBG> SHOW AST
ASTs are disabled
DBG>
The DISABLE AST command disables the delivery of ASTs in your program, as
confirmed by the SHOW AST command.
DEBUG–80
DISCONNECT
DISCONNECT
Releases a process from debugger control without terminating the process (kept
debugger only).
Format
DISCONNECT process-spec
Parameters
process-spec
Specifies a process currently under debugger control. Use any of the following
forms:
[%PROCESS_NAME] process-name
[%PROCESS_NAME] "process-name "
%PROCESS_PID process_id
[%PROCESS_NUMBER] process-number
(or %PROC process-number)
process-set-name
%NEXT_PROCESS
%PREVIOUS_PROCESS
The process name, if that name
does not contain spaces or lowercase
characters. The process name can
include the asterisk ( * ) wildcard
character.
The process name, if that name
contains spaces or lowercase
characters. You can also use
apostrophes (’) instead of quotation
marks ( " ).
The process identifier (PID, a
hexadecimal number).
The number assigned to a process
when it comes under debugger
control. A new number is assigned
sequentially, starting with 1, to each
process. If a process is terminated
with the EXIT or QUIT command,
the number can be assigned again
during the debugging session.
Process numbers appear in a SHOW
PROCESS display. Processes are
ordered in a circular list so they
can be indexed with the built-in
symbols %PREVIOUS_PROCESS
and %NEXT_PROCESS.
A symbol defined with the
DEFINE/PROCESS_SET command
to represent a group of processes.
The next process after the visible
process in the debugger’s circular
process list.
The process previous to the visible
process in the debugger’s circular
process list.
DEBUG–81
DISCONNECT
%VISIBLE_PROCESS
The process whose stack, register set,
and images are the current context
for looking up symbols, register
values, routine calls, breakpoints,
and so on.
Description
(Kept debugger only.) The DISCONNECT command releases a specified process
from debugger control without terminating the process. This is useful if, for
example, you have brought a running program under debugger control with
a CONNECT command and you now want to release it without terminating
the image. (In contrast, when you specify a process with the EXIT or QUIT
command, the process is terminated.)
Caution
The debugger kernel runs in the same process as the image being
debugged. If you issue the DISCONNECT command for this process, you
release your process, but the kernel remains activated.
This activation continues until the program image finishes running.
If you install a new version of the debugger while one or more
disconnected but activated kernels inhabit user program space, you
can experience problems with debugger behavior if you try to reconnect to
one of those kernels.
Related commands:
EXIT
QUIT
CONNECT
Example
DBG> DISCONNECT JONES
This command releases process JONES from debugger control without
terminating the process.
DEBUG–82
DISPLAY
DISPLAY
Creates a new screen display or modifies an existing display.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
DISPLAY display-name [AT window-spec] [display-kind] [, . . . ]
Parameters
display-name
Specifies the display to be created or modified.
If you are creating a new display, specify a name that is not already used as a
display name.
If you are modifying an existing display, you can specify any of the following
entities:
•
A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Integrity servers and Alpha only)
IREG
•
A display previously created with the DISPLAY command
•
A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
You must specify a display unless you use /GENERATE (parameter optional), or
/REFRESH (parameter not allowed).
You can specify more than one display, each with an optional window specification
and display kind.
window-spec
Specifies the screen window at which the display is to be positioned. You can
specify any of the following entities:
•
A predefined window. For example, RH1 (right top half).
DEBUG–83
DISPLAY
•
A window definition previously established with the SET WINDOW command.
•
A window specification of the form (start-line, line-count[, start-column,
column-count]). The specification can include expressions which can be based
on the built-in symbols %PAGE and %WIDTH (for example, %WIDTH/4).
If you omit the window specification, the screen position depends on whether you
are specifying an existing display or a new display:
•
If you are specifying an existing display, the position of the display is not
changed.
•
If you are specifying a new display, it is positioned at window H1 or H2,
alternating between H1 and H2 each time you create another display.
display-kind
Specifies the display kind. Valid keywords are as follows:
DO (command[; . . . ])
INSTRUCTION
OUTPUT
REGISTER
SOURCE
SOURCE (command)
Specifies an automatically updated output
display. The commands are executed in the
order listed each time the debugger gains
control. Their output forms the contents of
the display. If you specify more than one
command, the commands must be separated by
semicolons.
Specifies an instruction display. If selected
as the current instruction display with
the SELECT/INSTRUCTION command,
it displays the output from subsequent
EXAMINE/INSTRUCTION commands.
Specifies an output display. If selected
as the current output display with the
SELECT/OUTPUT command, it displays any
debugger output that is not directed to another
display. If selected as the current input display
with the SELECT/INPUT command, it echoes
debugger input. If selected as the current error
display with the SELECT/ERROR command, it
displays debugger diagnostic messages.
Specifies an automatically updated register
display. The display is updated each time the
debugger gains control.
Specifies a source display. If selected
as the current source display with the
SELECT/SOURCE command, it displays
the output from subsequent TYPE or
EXAMINE/SOURCE commands.
Specifies an automatically updated source
display. The command specified must be a
TYPE or EXAMINE/SOURCE command.
The source display is updated each time the
debugger gains control.
You cannot change the display kind of the PROMPT display.
DEBUG–84
DISPLAY
If you omit the display-kind parameter, the display kind depends on whether
you are specifying an existing display or a new display:
•
If you specify an existing display, the display kind is not changed.
•
If you specify a new display, an OUTPUT display is created.
Qualifiers
/CLEAR
Erases the entire contents of a specified display. Do not use this qualifier with
/GENERATE or when creating a new display.
/DYNAMIC (default)
/NODYNAMIC
Controls whether a display automatically adjusts its window dimensions
proportionally when the screen height or width is changed by a SET TERMINAL
command. By default (/DYNAMIC), all user-defined and predefined displays
adjust their dimensions automatically.
/GENERATE
Regenerates the contents of a specified display. Only automatically generated
displays are regenerated. These include DO displays, register displays,
source (cmd-list) displays, and instruction (cmd-list) displays. The debugger
automatically regenerates all these kinds of displays before each prompt. If you
do not specify a display, it regenerates the contents of all automatically generated
displays. Do not use this qualifier with /CLEAR or when creating a new display.
/HIDE
Places a specified display at the bottom of the display pasteboard (same as
/PUSH). This hides the specified display behind any other displays that share the
same region of the screen. You cannot hide the PROMPT display.
/MARK_CHANGE
/NOMARK_CHANGE (default)
Controls whether the lines that change in a DO display each time it is
automatically updated are marked. Not applicable to other kinds of displays.
When you use /MARK_CHANGE, any lines in which some contents have changed
since the last time the display was updated are highlighted in reverse video. This
qualifier is particularly useful when you want any variables in an automatically
updated display to be highlighted when they change.
The /NOMARK_CHANGE qualifier (default) specifies that any lines that change
in DO displays are not to be marked. This qualifier cancels the effect of a
previous /MARK_CHANGE on the specified display.
/POP (default)
/NOPOP
Controls whether a specified display is placed at the top of the display pasteboard,
ahead of any other displays but behind the PROMPT display. By default (/POP),
the display is placed at the top of the pasteboard and hides any other displays
that share the same region of the screen, except the PROMPT display.
The /NOPOP qualifier preserves the order of all displays on the pasteboard (same
as /NOPUSH).
DEBUG–85
DISPLAY
/PROCESS[=(process-spec)]
/NOPROCESS (default)
Used only when debugging multiprocess programs (kept debugger only). Controls
whether the specified display is process specific (that is, whether the specified
display is associated only with a particular process). The contents of a processspecific display are generated and modified in the context of that process. You
can make any display process specific, except the PROMPT display.
The /PROCESS=(process-spec) qualifier causes the specified display to be
associated with the specified process. You must include the parentheses. Use
any of the following process-spec forms:
[%PROCESS_NAME] proc-name
[%PROCESS_NAME] "proc-name"
%PROCESS_PID proc-id
%PROCESS_NUMBER proc-number
(or %PROC proc-number)
proc-group-name
%NEXT_PROCESS
%PREVIOUS_PROCESS
%VISIBLE_PROCESS
The process name, if that name
contains no space or lowercase
characters. The process name can
include the asterisk ( * ) wildcard
character.
The process name, if that name
contains space or lowercase
characters. You can also use
apostrophes (’) instead of quotation
marks ( " ).
The process identifier (PID, a
hexadecimal number).
The number assigned to a process
when it comes under debugger
control. Process numbers appear
in a SHOW PROCESS display.
A symbol defined with the
DEFINE/PROCESS_GROUP
command to represent a group of
processes. Do not specify a recursive
symbol definition.
The process after the visible process
in the debugger’s circular process
list.
The process previous to the visible
process in the debugger’s circular
process list.
The process whose call stack, register
set, and images are the current
context for looking up symbols,
register values, routine calls,
breakpoints, and so on.
The /PROCESS qualifier causes the specified display to be associated with the
process that was the visible process when the DISPLAY/PROCESS command was
executed.
The /NOPROCESS qualifier (which is the default) causes the specified display
to be associated with the visible process, which might change during program
execution.
If you do not specify /PROCESS, the current process-specific behavior (if any) of
the specified display remains unchanged.
DEBUG–86
DISPLAY
/PUSH
/NOPUSH
The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH qualifier
preserves the order of all displays on the pasteboard (same as /NOPOP).
/REFRESH
Refreshes the terminal screen. Do not specify any command parameters with this
qualifier. You can also use Ctrl/W to refresh the screen.
/REMOVE
Marks the display as being removed from the display pasteboard, so it is not
shown on the screen unless you explicitly request it with another DISPLAY
command. Although a removed display is not visible on the screen, it still exists
and its contents are preserved. You cannot remove the PROMPT display.
/SIZE:n
Sets the maximum size of a display to n lines. If more than n lines are written to
the display, the oldest lines are lost as the new lines are added. If you omit this
qualifier, the maximum size of the display is as follows:
•
If you specify an existing display, the maximum size is unchanged.
•
If you are creating a display, the default size is 64 lines.
For an output or DO display, /SIZE:n specifies that the display should hold the
n most recent lines of output. For a source or instruction display, n gives the
number of source lines or lines of instructions that can be placed in the memory
buffer at any one time. However, you can scroll a source display over the entire
source code of the module whose code is displayed (source lines are paged into
the buffer as needed). Similarly, you can scroll an instruction display over all of
the instructions of the routine whose instructions are displayed (instructions are
decoded from the image as needed).
Description
You can use the DISPLAY command to create a display or to modify an existing
display.
To create a display, specify a name that is not already used as a display name
(the SHOW DISPLAY command identifies all existing displays).
By default, the DISPLAY command places a specified display on top of the display
pasteboard, ahead of any other displays but behind the PROMPT display, which
cannot be hidden. The specified display thus hides the portions of other displays
(except the PROMPT display) that share the same region of the screen.
For a list of the key definitions associated with the DISPLAY command, type
Help Keypad_Definitions_CI. Also, use the SHOW KEY command to determine
the current key definitions.
Related commands:
Ctrl/W
EXPAND
MOVE
SET PROMPT
(SET,SHOW) TERMINAL
(SET,SHOW,CANCEL) WINDOW
SELECT
DEBUG–87
DISPLAY
(SHOW,CANCEL) DISPLAY
Examples
1.
DBG> DISPLAY REG
This command shows the predefined register display, REG, at its current
window location.
2.
DBG> DISPLAY/PUSH INST
This command pushes display INST to the bottom of the display pasteboard,
behind all other displays.
3.
DBG> DISPLAY NEWDISP AT RT2
DBG> SELECT/INPUT NEWDISP
In this example, the DISPLAY command shows the user-defined display
NEWDISP at the right middle third of the screen. The SELECT/INPUT
command selects NEWDISP as the current input display. NEWDISP now
echoes debugger input.
4.
DBG> DISPLAY DISP2 AT RS45
DBG> SELECT/OUTPUT DISP2
In this example, the DISPLAY command creates a display named DISP2
essentially at the right bottom half of the screen, above the PROMPT
display, which is located at S6. This is an output display by default. The
SELECT/OUTPUT command then selects DISP2 as the current output
display.
5.
DBG> SET WINDOW TOP AT (1,8,45,30)
DBG> DISPLAY NEWINST AT TOP INSTRUCTION
DBG> SELECT/INST NEWINST
In this example, the SET WINDOW command creates a window named TOP
starting at line 1 and column 45, and extending down for 8 lines and to the
right for 30 columns. The DISPLAY command creates an instruction display
named NEWINST to be displayed through TOP. The SELECT/INST command
selects NEWINST as the current instruction display.
6.
DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)
This command creates a DO display named CALLS at window Q3. Each time
the debugger gains control from the program, the SHOW CALLS command
is executed and the output is displayed in display CALLS, replacing any
previous contents.
7.
DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C)
This command creates a DO display named EXAM at window Q2. The display
shows the current values of variables A, B, and C whenever the debugger
prompts for input. Any changed values are highlighted.
8.
all> DISPLAY/PROCESS OUT_X AT S4
This command makes display OUT_X specific to the visible process (process
3) and puts the display at window S4.
DEBUG–88
DUMP
DUMP
Displays the contents of memory.
Format
DUMP address-expression1 [:address-expression2]
Parameters
address-expression1
Specifies the first memory location to be displayed.
address-expression2
Specifies the last memory location to be displayed (default is addressexpression1).
Qualifiers
/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity as a byte integer (length 1 byte).
/DECIMAL
Displays each examined entity as a decimal integer.
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/LONGWORD (default)
Displays each examined entity in the longword integer type (length 4 bytes). This
is the default type for program locations that do not have a compiler-generated
type.
/OCTAL
Displays each examined entity as an octal integer.
/QUADWORD
Displays each examined entity in the quadword integer type (length 8 bytes).
/WORD
Displays each examined entity in the word integer type (length 2 bytes).
DEBUG–89
DUMP
Description
The DUMP command displays the contents of memory, including registers,
variables, and arrays. The DUMP command formats its output in a manner
similar to the DCL command DUMP. The debugger DUMP command makes no
attempt to interpret the structure of aggregates.
In general, when you enter a DUMP command, the debugger evaluates addressexpression1 to yield a program location. The debugger then displays the entity
stored at that location as follows:
•
If the entity has a symbolic name, the debugger uses the size of the entity to
determine the address range to display.
•
If the entity does not have a symbolic name (and, therefore, no associated
compiler-generated type) the debugger displays address-expression1
through address-expression2 (if specified).
In either case, the DUMP command displays the contents of these locations as
longword (by default) integer values in the current radix.
The default radix for display is decimal for most languages. The exceptions are
BLISS and MACRO, which have a default radix of hexadecimal.
Use one of the four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL,
/OCTAL) to display data in another radix. You can also use the SET RADIX and
SET RADIX/OVERRIDE commands to change the default radix.
Use one of the size qualifiers (/BYTE, /WORD, /LONGWORD, /QUADWORD) to
change the format of the display.
The DUMP command sets the current entity built-in symbols %CURLOC and
period (.) to the location denoted by the address expression specified. Logical
predecessors (%PREVLOC or the circumflex character (^)) and successors
(%NEXTLOC) are based on the value of the current entity.
Related command:
EXAMINE
DEBUG–90
DUMP
Examples
1.
DBG> DUMP/QUAD R16:R25
0000000000000078 0000000000030038
000000202020786B 0000000000030041
0000000000030140 0000000000007800
0000000000010038 0000000000000007
0000000000000006 0000000000000000
8.......x.......
A.......kx ...
[email protected]
........8.......
................
%R16
%R18
%R20
%R22
%R24
DBG>
This command displays general registers R16 through R25 in quadword
format and hexadecimal radix.
2.
DBG> DUMP
00000000
63724F20
20202020
6166202C
APPLES
00030048
746E6F6D
20202020
73646E61
00000000
646F6F57
20202073
6C747275
00002020
00004220
000041B0
64726168
6F432020
2079636E
B......H.......
°A..Woodmont Orc
hards
Courtlands, fa
ncy ..
00000000000300B0
00000000000300C0
00000000000300D0
00000000000300E0
00000000000300F0
DBG>
This command displays an entity named APPLES in longword format and
hexadecimal radix.
3.
DBG> DUMP/BYTE/DECIMAL 30000:30040
0
0
0
0
0
3
0
0
0
0
0
0
3
1
0
0
0
0
0
3
0
0
0
0
0
0
3
0
0
0
0
0
0
3
0
0
0
0
0
0
3
0
0
0
0
0
0
0
7
101 101 119 32 116 120 101
-80
64
48
56
-64
-80
-50
110
107
°.......
@.......
0.......
8.......
À.......
°.......
Î.......
next wee
k
0000000000030000
0000000000030008
0000000000030010
0000000000030018
0000000000030020
0000000000030028
0000000000030030
0000000000030038
0000000000030040
DBG>
This command displays locations 30000 through 30040 in byte format and
decimal radix.
DEBUG–91
EDIT
EDIT
Starts the editor established with the SET EDITOR command. If you did not
enter a SET EDITOR command, starts the Language-Sensitive Editor (LSE), if
that editor is installed on your system.
Format
EDIT [[module-name\] line-number]
Parameters
module-name
Specifies the name of the module whose source file is to be edited. If you specify a
module name, you must also specify a line number. If you omit the module name
parameter, the source file whose code appears in the current source display is
chosen for editing.
line-number
A positive integer that specifies the source line on which the editor’s cursor is
initially placed. If you omit this parameter, the cursor is initially positioned
at the beginning of the source line that is centered in the debugger’s current
source display, or at the beginning of line 1 if the editor was set to /NOSTART_
POSITION (see the SET EDITOR command.)
Qualifiers
/EXIT
/NOEXIT (default)
Controls whether you end the debugging session prior to starting the editor. If
you specify /EXIT, the debugging session is terminated and the editor is then
started. If you specify /NOEXIT, the editing session is started and you return to
your debugging session after terminating the editing session.
Description
If you have not specified an editor with the SET EDITOR command, the EDIT
command starts the Language-Sensitive Editor (LSE) in a spawned subprocess
(if LSE is installed on your system). The typical (default) way to use the EDIT
command is not to specify any parameters. In this case, the editing cursor is
initially positioned at the beginning of the line that is centered in the currently
selected debugger source display (the current source display).
The SET EDITOR command provides options for starting different editors, either
in a subprocess or through a callable interface.
Related commands:
(SET,SHOW) EDITOR
(SET,SHOW,CANCEL) SOURCE
DEBUG–92
EDIT
Examples
1.
DBG> EDIT
This command spawns the Language-Sensitive Editor (LSE) in a subprocess
to edit the source file whose code appears in the current source display. The
editing cursor is positioned at the beginning of the line that was centered in
the source display.
2.
DBG> EDIT SWAP\12
This command spawns the Language-Sensitive Editor (LSE) in a subprocess
to edit the source file containing the module SWAP. The editing cursor is
positioned at the beginning of source line 12.
3.
DBG> SET EDITOR/CALLABLE_EDT
DBG> EDIT
In this example, the SET EDITOR/CALLABLE_EDT command establishes
that EDT is the default editor and is started through its callable interface
(rather than spawned in a subprocess). The EDIT command starts EDT to
edit the source file whose code appears in the current source display. The
editing cursor is positioned at the beginning of source line 1, because the
default qualifier /NOSTART_POSITION applies to EDT.
DEBUG–93
ENABLE AST
ENABLE AST
Enables the delivery of asynchronous system traps (ASTs) in your program.
Format
ENABLE AST
Description
The ENABLE AST command enables the delivery of ASTs while your program is
running, including any pending ASTs (ASTs waiting to be delivered). If ASTs are
delivered while the debugger is running (processing commands, and so on), they
are queued and are delivered when control is returned to the program. Delivery
of ASTs in your program is initially enabled by default.
Note
Any call by your program to the $SETAST system service that disables
ASTs overrides a previous ENABLE AST command.
Related commands:
(DISABLE,SHOW) AST
Example
DBG> ENABLE AST
DBG> SHOW AST
ASTs are enabled
DBG>
The ENABLE AST command enables the delivery of ASTs in your program, as
confirmed with the SHOW AST command.
DEBUG–94
EVALUATE
EVALUATE
Displays the value of a language expression in the current language (by default,
the language of the module containing the main program).
Format
EVALUATE language-expression[, . . . ]
Parameters
language-expression
Specifies any valid expression in the current language.
Qualifiers
/BINARY
Specifies that the result be displayed in binary radix.
/CONDITION_VALUE
Specifies that the expression be interpreted as a condition value (the kind of
condition value you would specify using the condition-handling mechanism).
The message text corresponding to that condition value is then displayed. The
specified value must be an integer value.
/DECIMAL
Specifies that the result be displayed in decimal radix.
/HEXADECIMAL
Specifies that the result be displayed in hexadecimal radix.
/OCTAL
Specifies that the result be displayed in octal radix.
Description
The debugger interprets the expression specified in an EVALUATE command as a
language expression, evaluates it in the syntax of the current language and in the
current radix, and displays its value as a literal (for example, an integer value) in
the current language.
The current language is the language last established with the SET LANGUAGE
command. If you did not enter a SET LANGUAGE command, the current
language is, by default, the language of the module containing the main program.
If an expression contains symbols with different compiler-generated types, the
debugger uses the type-conversion rules of the current language to evaluate the
expression.
The debugger can interpret and display integer data in any one of four radixes:
binary, decimal, hexadecimal, and octal. The current radix is the radix last
established with the SET RADIX command.
If you did not enter a SET RADIX command, the default radix for both data
entry and display is decimal for most languages. The exceptions are BLISS and
MACRO, which have a default radix of hexadecimal.
DEBUG–95
EVALUATE
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display integer
data in another radix. These qualifiers do not affect how the debugger interprets
the data you specify; they override the current output radix, but not the input
radix.
The EVALUATE command sets the current value of built-in symbols %CURVAL
and backslash ( \ ) to the value denoted by the specified expression.
You cannot evaluate a language expression that includes a function call. For
example, if PRODUCT is a function that multiplies two integers, you cannot use
the command EVALUATE PRODUCT(3,5). If your program assigns the returned
value of a function to a variable, you can examine the resulting value of that
variable. On Alpha, the command EVALUATE procedure-name displays the
procedure descriptor address (not the code address) of a specified routine, entry
point, or Ada package.
For more information about debugger support for language-specific operators and
constructs, type HELP Language.
Related commands:
EVALUATE/ADDRESS
MONITOR
(SET,SHOW) LANGUAGE
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
Examples
1.
DBG> EVALUATE 100.34 * (14.2 + 7.9)
2217.514
DBG>
This command uses the debugger as a calculator by multiplying 100.34 by
(14.2 + 7.9).
2.
DBG> EVALUATE/OCTAL X
00000001512
DBG>
This command evaluates the symbol X and displays the result in octal radix.
3.
DBG> EVALUATE TOTAL + CURR_AMOUNT
8247.20
DBG>
This command evaluates the sum of the values of two real variables, TOTAL
and CURR_AMOUNT.
4.
DBG> DEPOSIT WILLING = TRUE
DBG> DEPOSIT ABLE = FALSE
DBG> EVALUATE WILLING AND ABLE
False
DBG>
In this example, the EVALUATE command evaluates the logical AND of the
current values of two Boolean variables, WILLING and ABLE.
DEBUG–96
EVALUATE
5.
DBG> EVALUATE COLOR’FIRST
RED
DBG>
In this Ada example, this command evaluates the first element of the
enumeration type COLOR.
DEBUG–97
EVALUATE/ADDRESS
EVALUATE/ADDRESS
Evaluates an address expression and displays the result as a memory address or
a register name.
Format
EVALUATE/ADDRESS address-expression[, . . . ]
Parameters
address-expression
Specifies an address expression of any valid form (for example, a routine name,
variable name, label, line number, and so on).
Qualifiers
/BINARY
Displays the memory address in binary radix.
/DECIMAL
Displays the memory address in decimal radix.
/HEXADECIMAL
Displays the memory address in hexadecimal radix.
/OCTAL
Displays the memory address in octal radix.
Description
The EVALUATE/ADDRESS command enables you to determine the memory
address or register associated with an address expression.
The debugger can interpret and display integer data in any one of four radixes:
binary, decimal, hexadecimal, and octal.
The default radix for both data entry and display is decimal for most languages.
The exceptions are BLISS and MACRO, which have a default radix of
hexadecimal.
You can use a radix qualifier (/BINARY, /OCTAL, and so on) to display address
values in another radix. These qualifiers do not affect how the debugger
interprets the data you specify; that is, they override the current output radix,
but not the input radix.
If the value of a variable is currently stored in a register instead of memory, the
EVALUATE/ADDRESS command identifies the register. The radix qualifiers have
no effect in that case.
The EVALUATE/ADDRESS command sets the current entity built-in symbols
%CURLOC and period ( . ) to the location denoted by the address expression
specified. Logical predecessors (%PREVLOC or the circumflex character ( ^ )) and
successors (%NEXTLOC) are based on the value of the current entity.
On Alpha, the command EVALUATE/ADDRESS procedure-name displays the
procedure descriptor address (not the code address) of a specified routine, entry
point, or Ada package.
DEBUG–98
EVALUATE/ADDRESS
Related commands:
EVALUATE
(SET,SHOW,CANCEL) RADIX
SHOW SYMBOL/ADDRESS
SYMBOLIZE
Routine names in debugger expressions have different meanings on Integrity
server and Alpha systems.
On Alpha systems, the command EVALUATE/ADDRESS RTN-NAME evaluates to the
address of the procedure descriptor:
Examples
1.
DBG> EVALUATE/ADDRESS RTN-NAME
On Integrity server systems, instead of displaying the address of the official
function descriptor, the debugger just displays the code address. For example,
on Alpha systems, you can enter the following command and then set a
breakpoint when a variable contains the address, FOO:
2.
DBG> SET BREAK .PC WHEN (.SOME_VARIABLE EQLA FOO)
The breakpoint occurs when the variable contains the address of the
procedure descriptor. However, when you enter the same command on
Integrity server systems, the breakpoint is never reached because, although
the user variable might contain the address of the function descriptor for
FOO, the "EQLA FOO" in the WHEN clause compares it to the code address
for FOO. As a result, the user variable never contains the code address of
FOO. However, the first quadword of an Integrity server function descriptor
contains the code address, you can write it as:
3.
DBG> SET BREAK .PC WHEN (..SOME_VARIABLE EQLA FOO)
Note
On Integrity server systems, you cannot copy the following line from your
BLISS code: IF .SOME_VARIABLE EQLA FOO THEN do-something;
4.
DBG> EVALUATE/ADDRESS MODNAME\%LINE 110
3942
DBG>
This command displays the memory address denoted by the address
expression MODNAME\%LINE 110.
5.
DBG> EVALUATE/ADDRESS/HEX A,B,C
000004A4
000004AC
000004A0
DBG>
This command displays the memory addresses denoted by the address
expressions A, B, and C in hexadecimal radix.
DEBUG–99
EVALUATE/ADDRESS
6.
DBG> EVALUATE/ADDRESS X
MOD3\%R1
DBG>
This command indicates that variable X is associated with register R1. X is a
nonstatic (register) variable.
DEBUG–100
EXAMINE
EXAMINE
Displays the current value of a program variable. More generally, displays the
value of the entity denoted by an address expression.
Format
EXAMINE [address-expression[:address-expression] [, . . . ]]
Parameters
address-expression
Specifies an entity to be examined. With high-level languages, this is typically the
name of a variable and can include a path name to specify the variable uniquely.
More generally, an address expression can also be a memory address or a register
and can be composed of numbers (offsets) and symbols, as well as one or more
operators, operands, or delimiters. For information about the debugger symbols
for the registers and about the operators you can use in address expressions, type
Help Built_in_Symbols or Help Address_Expressions.
If you specify the name of an aggregate variable (a composite data structure
such as an array or record structure) the debugger displays the values of all
elements. For an array, the display shows the subscript (index) and value of each
array element. For a record, the display shows the name and value of each record
component.
To specify an individual array element, array slice, or record component, follow
the syntax of the current language.
If you specify a range of entities, the value of the address expression that denotes
the first entity in the range must be less than the value of the address expression
that denotes the last entity in the range. The debugger displays the entity
specified by the first address expression, the logical successor of that address
expression, the next logical successor, and so on, until it displays the entity
specified by the last address expression. You can specify a list of ranges by
separating ranges with a comma.
For information specific to vector registers and vector instructions, see /TMASK,
/FMASK, /VMR, and /OPERANDS qualifiers.
Qualifiers
/ASCIC
/AC
Interprets each examined entity as a counted ASCII string preceded by a 1-byte
count field that gives the length of the string. The string is then displayed.
/ASCID
/AD
Interprets each examined entity as the address of a string descriptor pointing to
an ASCII string. The CLASS and DTYPE fields of the descriptor are not checked,
but the LENGTH and POINTER fields provide the character length and address
of the ASCII string. The string is then displayed.
DEBUG–101
EXAMINE
/ASCII:n
Interprets and displays each examined entity as an ASCII string of length n bytes
(n characters). If you omit n, the debugger attempts to determine a length from
the type of the address expression.
/ASCIW
/AW
Interprets each examined entity as a counted ASCII string preceded by a 2-byte
count field that gives the length of the string. The string is then displayed.
/ASCIZ
/AZ
Interprets each examined entity as a zero-terminated ASCII string. The ending
zero byte indicates the end of the string. The string is then displayed.
/BINARY
Displays each examined entity as a binary integer.
/BYTE
Displays each examined entity in the byte integer type (length 1 byte).
/CONDITION_VALUE
Interprets each examined entity as a condition-value return status and displays
the message associated with that return status.
/D_FLOAT
Displays each examined entity in the D_floating type (length 8 bytes).
/DATE_TIME
Interprets each examined entity as a quadword integer (length 8 bytes) containing
the internal representation of date and time. Displays the value in the format
dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each examined entity as a decimal integer.
/DEFAULT
Displays each examined entity in the default radix.
The minimum abbreviation is /DEFA.
/DEFINITIONS=n
(Alpha only, Integrity servers when optimized code is supported) When the code
is optimized, displays n definition points for a split-lifetime variable. A definition
point is a location in the program where the variable could have received its
value. By default, up to five definition points are displayed. If more than the
given number of definitions (explicit or default) are available, then the number of
additional definitions is reported as well. (For more information on split-lifetime
variables, see
The minimum abbreviation is /DEFI.
DEBUG–102
EXAMINE
/EXTENDED_FLOAT
/X_FLOAT
(Integrity servers and Alpha only) Displays each examined entity in the IEEE
X_floating type (length 16 bytes).
/FLOAT
On Alpha, same as T_FLOAT. Displays each examined entity in the IEEE T_
floating type (double precision, length 8 bytes).
/FPCR
(Alpha only) Displays each examined entity in FPCR (floating-point control
register) format.
/G_FLOAT
Displays each examined entity in the G_floating type (length 8 bytes).
/HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
/INSTRUCTION
Displays each examined entity as an assembly-language instruction (variable
length, depending on the number of instruction operands and the kind of
addressing modes used). See also the /OPERANDS qualifier.
In screen mode, the output of an EXAMINE/INSTRUCTION command is directed
at the current instruction display, if any, not at an output or DO display. The
arrow in the instruction display points to the examined instruction.
On Alpha, the command EXAMINE/INSTRUCTION procedure-name displays the
first instruction at the code address of a specified routine, entry point, or Ada
package.
/LINE (default)
/NOLINE
Controls whether program locations are displayed in terms of line numbers
(%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger
symbolizes program locations in terms of line numbers.
/LONG_FLOAT
/S_FLOAT
(Integrity servers and Alpha only) Displays each examined entity in the IEEE
S_floating type (single precision, length 4 bytes).
/LONG_LONG_FLOAT
/T_FLOAT
(Integrity servers and Alpha only) Displays each examined entity in the IEEE
T_floating type (double precision, length 8 bytes).
/LONGWORD
Displays each examined entity in the longword integer type (length 4 bytes). This
is the default type for program locations that do not have a compiler-generated
type.
/OCTAL
Displays each examined entity as an octal integer.
DEBUG–103
EXAMINE
/OCTAWORD
Displays each examined entity in the octaword integer type (length 16 bytes).
/PACKED:n
Interprets each examined entity as a packed decimal number. The value of n is
the number of decimal digits. Each digit occupies one nibble (4 bits).
/PS
(Alpha only) Displays each examined entity in PS (processor status register)
format.
/PSR
(Integrity servers only) Displays each examined entity in PSR (processor status
register) format.
/PSR
(Integrity servers only) Displays each examined entity in PSR (processor status
register) format.
/QUADWORD
Displays each examined entity in the quadword integer type (length 8 bytes).
/S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating type (single
precision, length 4 bytes).
/SFPCR
(Alpha only) Displays each examined entity in SFPCR (software floating-point
control register) format.
/SOURCE
Note
This qualifier is not available in the HP DECwindows Motif for OpenVMS
user interface to the debugger.
Displays the source line corresponding to the location of each examined entity.
The examined entity must be associated with a machine code instruction and,
therefore, must be a line number, a label, a routine name, or the memory address
of an instruction. The examined entity cannot be a variable name or any other
address expression that is associated with data.
In screen mode, the output of an EXAMINE/SOURCE command is directed at the
current source display, if any, not at an output or DO display. The arrow in the
source display points to the source line associated with the last entity specified
(or the last one specified in a list of entities).
On Alpha, the command EXAMINE/SOURCE procedure-name displays the source
code at the code address of a specified routine, entry point, or Ada package.
/SYMBOLIC (default)
/NOSYMBOLIC
Controls whether symbolization occurs. By default (/SYMBOLIC), the debugger
symbolizes all addresses, if possible; that is, it converts numeric addresses into
DEBUG–104
EXAMINE
their symbolic representation. If you specify /NOSYMBOLIC, the debugger
suppresses symbolization of entities you specify as absolute addresses. If you
specify entities as variable names, symbolization still occurs. The /NOSYMBOLIC
qualifier is useful if you are interested in identifying numeric addresses rather
than their symbolic names (if symbolic names exist for those addresses). Using
/NOSYMBOLIC may speed up command processing because the debugger does
not need to convert numbers to names.
/TASK
Applies to tasking (multithread) programs. Interprets each examined entity as
a task (thread) object and displays the task value (the name or task ID) of that
task object. When examining a task object, use /TASK only if the programming
language does not have built-in tasking services.
/TYPE=(name)
/TYPE:(name)
/TYPE(name)
Interprets and displays each examined entity according to the type specified
by name and (which must be the name of a variable or data type declared in
the program). This enables you to specify a user-declared type. You must use
parentheses around the type expression.
/VARIANT=variant-selector address-expression
/VARIANT=(variant-selector,...) address-expression
Enables the debugger to display the correct item when it encounters an
anonymous variant.
In a C program, a union contains members, only one of which is valid at any one
time. When displaying a union, the debugger does not know which member is
currently valid.
In a PASCAL program, a record with a variant part contains variants, only one
of which is valid at any one time. When displaying a record with an anonymous
variant part, the debugger does not know which variant is currently valid, and
displays all variants by default.
You can use the /VARIANT qualifier of the EXAMINE command to select which
member of a union (C) or anonymous variant (PASCAL) to display.
/WCHAR_T[:n]
Interprets and displays each examined entity as a multibyte file code sequence of
length n longwords (n characters). The default is 1 longword.
When converting the examined string, the debugger uses the locale database of
the process in which the debugger runs. The default is C locale.
/WORD
Displays each examined entity in the word integer type (length 2 bytes).
/X_FLOAT
(Alpha and Integrity servers only) Displays each examined entity in the IEEE
X_floating type (length 16 bytes).
DEBUG–105
EXAMINE
Description
The EXAMINE command displays the entity at the location denoted by an
address expression. You can use the command to display the contents of any
memory location or register that is accessible in your program. For high-level
languages, the command is used mostly to obtain the current value of a variable
(an integer, real, string, array, record, and so on).
If you are debugging optimized code on Alpha systems, the EXAMINE command
displays the definition points at which a split-lifetime variable could have
received its value. Split-lifetime variables are discussed in Chapter 14. By
default, the EXAMINE command displays up to five definition points. With the
/DEFINITIONS qualifier, you can specify the number of definition points.
The debugger recognizes the compiler-generated types associated with symbolic
address expressions (symbolic names declared in your program). Symbolic
address expressions include the following entities:
•
Variable names. When specifying a variable with the EXAMINE command,
use the same syntax that is used in the source code.
•
Routine names, labels, and line numbers. These are associated with
instructions. You can examine instructions using the same techniques as
when examining variables.
In general, when you enter an EXAMINE command, the debugger evaluates
the address expression specified to yield a program location. The debugger then
displays the value stored at that location as follows:
•
If the location has a symbolic name, the debugger formats the value according
to the compiler-generated type associated with that symbol (that is, as a
variable of a particular type or as an instruction).
•
If the location does not have a symbolic name (and, therefore, no associated
compiler-generated type) the debugger formats the value in the type longword
integer by default. This means that, by default, the EXAMINE command
displays the contents of these locations as longword (4-byte) integer values.
There are several ways of changing the type associated with a program location
so that you can display the data at that location in another data format:
•
To change the default type for all locations that do not have a symbolic name,
you can specify a new type with the SET TYPE command.
•
To change the default type for all locations (both those that do and do
not have a symbolic name), you can specify a new type with the SET
TYPE/OVERRIDE command.
•
To override the type currently associated with a particular location for the
duration of a single EXAMINE command, you can specify a new type by using
a type qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). Most qualifiers
for the EXAMINE command are type qualifiers.
The debugger can interpret and display integer data in any one of four radixes:
binary, decimal, hexadecimal, and octal.
The default radix for both data entry and display is decimal for most languages.
The exceptions are BLISS and MACRO, which have a default radix of
hexadecimal.
DEBUG–106
EXAMINE
The EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL,
/HEXADECIMAL, /OCTAL) that enable you to display data in another radix. You
can also use the SET RADIX and SET RADIX/OVERRIDE commands to change
the default radix.
In addition to the type and radix qualifiers, the EXAMINE command has
qualifiers for other purposes:
•
The /SOURCE qualifier enables you to identify the line of source code
corresponding to a line number, routine name, label, or any other address
expression that is associated with an instruction rather than data.
•
The /[NO]LINE and /[NO]SYMBOLIC qualifiers enable you to control the
symbolization of address expressions.
The EXAMINE command sets the current entity built-in symbols %CURLOC and
period ( . ) to the location denoted by the address expression specified. Logical
predecessors (%PREVLOC or the circumflex character ( ^ )) and successors
(%NEXTLOC) are based on the value of the current entity.
The /VARIANT qualifier enables the debugger to display the correct item when it
encounters an anonymous variant.
In a C program, a union contains members, only one of which is valid at any
one time. When displaying a union, the debugger does not know which member
is currently valid. In a PASCAL program, a record with a variant part contains
variants, only one of which is valid at any one time. When displaying a record
with an anonymous variant part, the debugger does not know which variant is
currently valid, and displays all variants by default.
You can use the /VARIANT qualifier of the EXAMINE command to select which
member of a union (C program) or anonymous variant (PASCAL program) to
display. The format is as follows:
DBG> EXAMINE /VARIANT=variant-selector address-expression
DBG> EXAMINE /VARIANT=(variant-selector,...) address-expression
The variant selector variant-selector specifies a name, a discriminant (PASCAL
only), or a position; that is, one of the following:
•
NAME = name-string
•
DISCRIMINANT = expression
•
POSITION = expression
The /VARIANT qualifier takes a list of zero or more variant selectors. /VARIANT
without any variant selectors is the default: the first variant of all anonymous
variant lists will be displayed.
Each variant selector specifies either the name, the discriminant, or the position
of the variant to be displayed.
The debugger uses the variant selector as follows:
1. If the debugger encounters an anonymous variable list while displaying
address-expression, the debugger uses the variant selector to choose which
variant to display.
DEBUG–107
EXAMINE
2. Each time the debugger encounters an anonymous variant list, it attempts to
use the next variant selector to choose which variant to display. If the variant
selector matches one of the variants of the variant list (union), the debugger
displays that variant.
3. The debugger walks the structure top-to-bottom, depth first, so that children
are encountered before siblings.
4. If the debugger encounters an anonymous variant list and does not have a
variant selector to match it with, the debugger displays the first variant.
5. If the variant selector does not match any of the variants of an anonymous
variant list, the debugger displays a single line to indicate that. This is
similar to what the debugger does if the discriminant value fails to match any
of the variants in a discriminated variant list. For example:
[Variant Record omitted - null or illegal Tag Value: 3]
A name specifies a name string. A name matches a variant if that variant
contains a field with the name specified by name.
A discriminant specifies a language expression that must be type compatible
with the tag type of the variant part it is meant to match. The discriminant
expression matches a variant if it evaluates to a value in the variant’s case-label
list. Discriminants apply only to Pascal programs, because C and C++ unions do
not have discriminants.
A positional-selector specifies a language expression, which should evaluate to
a integer between 1 and N, where N is the number of variants in a variant list.
A positional-selector that evaluates to I specifies that the Ith variant is to be
displayed.
You can use asterisk (*) as a wildcard, which matches all variants of an
anonymous variant list.
Each of these variant selectors can be used to match all variants. In particular,
each of the following variant selectors indicates that all of the variants of the first
anonymous variant list are to be displayed.
/VAR=D=*
/VAR=N=*
/VAR=P=*
The variant selectors can themselves contain a list of selectors. For example, the
following commands all mean the same thing.
EXAMINE /VARIANT=(DIS=3,DIS=1,DIS=54) x
EXAMINE /VARIANT=(DIS=(3,1,54)) x
EXAMINE /VARIANT=DIS=(3,1,54) x
You can specify a single discriminant or position value without parentheses if
the value is a simple decimal integer. To use a general expression to specify
the value, you enclose the expression in parentheses. In the following list of
commands, the first four are legal while the last three are not.
DEBUG–108
EXAMINE
EXAMINE
EXAMINE
EXAMINE
EXAMINE
EXAMINE
EXAMINE
EXAMINE
/VARIANT=POS=3
/VARIANT=POS=(3)
/VARIANT=(POS=(3))
/VARIANT=(POS=3)
/VARIANT=(POS=foo)
/VARIANT=POS=(foo)
/VARIANT=(POS=3-1)
!
!
!
!
!
!
parentheses
parentheses
parentheses
parentheses
parentheses
parentheses
unnecessary
unnecessary
unnecessary
necessary
necessary
necessary
Related Commands:
CANCEL TYPE/OVERRIDE
DEPOSIT
DUMP
EVALUATE
SET MODE [NO]OPERANDS
SET MODE [NO]SYMBOLIC
(SET,SHOW,CANCEL) RADIX
(SET,SHOW) TYPE
Examples
1.
DBG> EXAMINE COUNT
SUB2\COUNT: 27
DBG>
This command displays the value of the integer variable COUNT in module
SUB2.
2.
DBG> EXAMINE PART_NUMBER
INVENTORY\PART_NUMBER: "LP-3592.6-84"
DBG>
This command displays the value of the string variable PART_NUMBER.
3.
DBG> EXAMINE
SUB1\ARR3
(1,1):
(1,2):
(1,3):
(2,1):
(2,2):
(2,3):
DBG>
SUB1\ARR3
27.01000
31.01000
12.48000
15.08000
22.30000
18.73000
This command displays the value of all elements in array ARR3 in module
SUB1. ARR3 is a 2 by 3 element array of real numbers.
4.
DBG> EXAMINE
SUB1\ARR3
(2,1):
(2,2):
(2,3):
DBG>
SUB1\ARR3(2,1:3)
15.08000
22.30000
18.73000
This command displays the value of the elements in a slice of array
SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2.
5.
DBG> EXAMINE VALVES.INTAKE.STATUS
MONITOR\VALVES.INTAKE.STATUS: OFF
DBG>
This command displays the value of the nested record component
VALVES.INTAKE.STATUS in module MONITOR.
DEBUG–109
EXAMINE
6.
DBG> EXAMINE/SOURCE SWAP
module MAIN
47: procedure SWAP(X,Y: in out INTEGER) is
DBG>
This command displays the source line in which routine SWAP is declared
(the location of routine SWAP).
7.
DBG> DEPOSIT/ASCII:7 WORK+20 = ’abcdefg’
DBG> EXAMINE/ASCII:7 WORK+20
DETAT\WORK+20: "abcdefg"
DBG> EXAMINE/ASCII:5 WORK+20
DETAT\WORK+20: "abcde"
DBG>
In this example, the DEPOSIT command deposits the entity ’abcdefg’ as
an ASCII string of length 7 bytes into the location that is 20 bytes beyond
the location denoted by the symbol WORK. The first EXAMINE command
displays the value of the entity at that location as an ASCII string of length
7 bytes (abcdefg). The second EXAMINE command displays the value of the
entity at that location as an ASCII string of length 5 bytes (abcde).
8.
DBG> EXAMINE/OPERANDS=FULL .0\%PC
X\X$START+0C: mov
r12 = r15 ;;
DBG>
On Integrity servers, this command displays the instruction (MOV) at the
current PC value. Using /OPERANDS=FULL displays the maximum level of
operand information.
9.
DBG> SET RADIX HEXADECIMAL
DBG> EVALUATE/ADDRESS WORKDATA
0000086F
DBG> EXAMINE/SYMBOLIC 0000086F
MOD3\WORKDATA: 03020100
DBG> EXAMINE/NOSYMBOLIC 0000086F
0000086F: 03020100
DBG>
In this example, the EVALUATE/ADDRESS command indicates that the
memory address of variable WORKDATA is 0000086F, hexadecimal. The
two EXAMINE commands display the value contained at that address using
/[NO]SYMBOL to control whether the address is symbolized to WORKDATA.
10.
DBG> EXAMINE/HEX FIDBLK
FDEX1$MAIN\FIDBLK
(1):
00000008
(2):
00000100
(3):
000000AB
DBG>
This command displays the value of the array variable FIDBLK in
hexadecimal radix.
DEBUG–110
EXAMINE
11.
DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6
SUB2\NEWDATA: 256
SUB2\NEWDATA+2: 770
SUB2\NEWDATA+4: 1284
SUB2\NEWDATA+6: 1798
DBG>
This command displays, in decimal radix, the values of word integer entities
(2-byte entities) that are in the range of locations denoted by NEWDATA to
NEWDATA + 6 bytes.
12.
DBG> EXAMINE/TASK SORT_INPUT
MOD3\SORT_INPUT: %TASK 12
DBG>
This command displays the task ID of a task object named SORT_INPUT.
13.
DBG> EXAMINE /VARIANT=(NAME=m,DIS=4,POS=1) x
This command specifies that, for the first anonymous variant list encountered,
display the variant part containing a field named "m", for the second
anonymous variant list, display the part with the discriminant value 4,
and, for the third anonymous variant list, display the first variant part.
14.
DBG> ex %r9:%r12
TEST\%R9:
TEST\%R10:
TEST\%R11:
TEST\%SP:
0000000000000000
0000000000000000
0000000000000000
000000007AC8FB70
DBG> ex/bin grnat0 <9,4,0>
TEST\%GRNAT0+1: 0110
DBG>
Debugger displays the string "NaT" when the integer register’s NaT bit is
set.
DEBUG–111
EXIT
EXIT
Ends a debugging session, or terminates one or more processes of a multiprocess
program, allowing any application-declared exit handlers to run. If used within
a command procedure or DO clause and no process is specified, it exits the
command procedure or DO clause at that point.
Format
EXIT [process-spec[, . . . ]]
Parameters
process-spec
Specifies a process currently under debugger control. Use any of the following
forms:
[%PROCESS_NAME] process-name
[%PROCESS_NAME] "process-name "
%PROCESS_PID process_id
[%PROCESS_NUMBER] process-number
(or %PROC process-number)
process-set-name
%NEXT_PROCESS
DEBUG–112
The process name, if that name
does not contain spaces or lowercase
characters. The process name can
include the asterisk ( * ) wildcard
character.
The process name, if that name
contains spaces or lowercase
characters. You can also use
apostrophes (’) instead of quotation
marks ( " ).
The process identifier (PID, a
hexadecimal number).
The number assigned to a process
when it comes under debugger
control. A new number is assigned
sequentially, starting with 1, to each
process. If a process is terminated
with the EXIT or QUIT command,
the number can be assigned again
during the debugging session.
Process numbers appear in a SHOW
PROCESS display. Processes are
ordered in a circular list so they
can be indexed with the built-in
symbols %PREVIOUS_PROCESS
and %NEXT_PROCESS.
A symbol defined with the
DEFINE/PROCESS_SET command
to represent a group of processes.
The next process after the visible
process in the debugger’s circular
process list.
EXIT
%PREVIOUS_PROCESS
%VISIBLE_PROCESS
The process previous to the visible
process in the debugger’s circular
process list.
The process whose stack, register set,
and images are the current context
for looking up symbols, register
values, routine calls, breakpoints,
and so on.
You can also use the asterisk ( * ) wildcard character to specify all processes.
Description
The EXIT command is one of the four debugger commands that can be used to
execute your program (the others are CALL, GO, and STEP).
Ending a Debugging Session
To end a debugging session, enter the EXIT command at the debugger prompt
without specifying any parameters. This causes orderly termination of the
session: the program’s application-declared exit handlers (if any) are executed,
the debugger exit handler is executed (closing log files, restoring the screen and
keypad states, and so on), and control is returned to the command interpreter.
You cannot then continue to debug your program by entering the DCL command
DEBUG or CONTINUE (you must restart the debugger).
Because EXIT runs any application-declared exit handlers, you can set
breakpoints in such exit handlers, and the breakpoints are triggered upon typing
EXIT. Thus, you can use EXIT to debug your exit handlers.
To end a debugging session without running any application-declared exit
handlers, use the QUIT command instead of EXIT.
Using the EXIT Command in Command Procedures and DO Clauses
When the debugger executes an EXIT command (without any parameters) in
a command procedure, control returns to the command stream that invoked
the command procedure. A command stream can be the terminal, an outer
(containing) command procedure, or a DO clause in a command or screen display
definition. For example, if the command procedure was invoked from within a DO
clause, control returns to that DO clause, where the debugger executes the next
command (if any remain in the command sequence).
When the debugger executes an EXIT command (without any parameters) in a
DO clause, it ignores any remaining commands in that clause and displays its
prompt.
Terminating Specified Processes
If you are debugging a multiprocess program you can use the EXIT command to
terminate specified processes without ending the debugging session. The same
techniques and behavior apply, whether you enter the EXIT command at the
prompt or use it within a command procedure or DO clause.
To terminate one or more processes, enter the EXIT command, specifying these
processes as parameters. This causes orderly termination of the images in these
processes, executing any application-declared exit handlers associated with these
images. Subsequently, the specified processes are no longer identified in a SHOW
PROCESS/ALL display. If any specified processes were on hold as the result of a
SET PROCESS command, the hold condition is ignored.
DEBUG–113
EXIT
When the specified processes begin to exit, any unspecified process that is not on
hold begins execution. After execution is started, the way in which it continues
depends on whether you entered a SET MODE [NO]INTERRUPT command. By
default (SET MODE INTERRUPT), execution continues until it is suspended in
any process. At that point, execution is interrupted in any other processes that
were executing images, and the debugger prompts for input.
To terminate specified processes without running any application-declared exit
handlers or otherwise starting execution, use the QUIT command instead of
EXIT.
Related commands:
DISCONNECT
@ (Execute Procedure)
Ctrl/C
Ctrl/Y
Ctrl/Z
QUIT
RERUN
RUN
SET ABORT_KEY
SET MODE [NO]INTERRUPT
SET PROCESS
Examples
1.
DBG> EXIT
$
This command ends the debugging session and returns you to DCL level.
2.
all> EXIT %NEXT_PROCESS, JONES_3, %PROC 5
all>
This command causes orderly termination of three processes of a multiprocess
program: the process after the visible process on the process list, process
JONES_3, and process 5. Control is returned to the debugger after the
specified processes have exited.
DEBUG–114
EXITLOOP
EXITLOOP
Exits one or more enclosing FOR, REPEAT, or WHILE loops.
Format
EXITLOOP [integer]
Parameters
integer
A decimal integer that specifies the number of nested loops to exit from. The
default is 1.
Description
Use the EXITLOOP command to exit one or more enclosing FOR, REPEAT, or
WHILE loops.
Related commands:
FOR
REPEAT
WHILE
Example
DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP)
The WHILE 1 command generates an endless loop that executes a STEP
command with each iteration. After each STEP, the value of X is tested. If
X is greater than 3, the EXITLOOP command terminates the loop (Fortran
example).
DEBUG–115
EXPAND
EXPAND
Expands or contracts the window associated with a screen display.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
EXPAND [display-name[, . . . ]]
Parameters
display-name
Specifies a display to be expanded or contracted. You can specify any of the
following entities:
•
A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Integrity servers and Alpha only)
IREG
•
A display previously created with the DISPLAY command
•
A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you do not specify a display, the current scrolling display, as established by the
SELECT command, is chosen.
Qualifiers
/DOWN[:n]
Moves the bottom border of the display down by n lines (if n is positive) or up by
n lines (if n is negative). If you omit n, the border is moved down by 1 line.
/LEFT[:n]
Moves the left border of the display to the left by n lines (if n is positive) or to the
right by n lines (if n is negative). If you omit n, the border is moved to the left by
1 line.
DEBUG–116
EXPAND
/RIGHT[:n]
Moves the right border of the display to the right by n lines (if n is positive) or
to the left by n lines (if n is negative). If you omit n, the border is moved to the
right by 1 line.
/UP[:n]
Moves the top border of the display up by n lines (if n is positive) or down by n
lines (if n is negative). If you omit n, the border is moved up by 1 line.
Description
You must specify at least one qualifier.
The EXPAND command moves one or more display-window borders according to
the qualifiers specified (/UP:[n], /DOWN:[n], RIGHT:[n], /LEFT:[n]).
The EXPAND command does not affect the order of a display on the display
pasteboard. Depending on the relative order of displays, the EXPAND command
can cause the specified display to hide or uncover another display or be hidden by
another display, partially or totally.
Except for the PROMPT display, any display can be contracted to the point where
it disappears (at which point it is marked as "removed"). It can then be expanded
from that point. Contracting a display to the point where it disappears causes it
to lose any attributes that were selected for it. The PROMPT display cannot be
contracted or expanded horizontally but can be contracted vertically to a height of
2 lines.
A window border can be expanded only up to the edge of the screen. The left
and top window borders cannot be expanded beyond the left and top edges of the
display, respectively. The right border can be expanded up to 255 columns from
the left display edge. The bottom border of a source or instruction display can be
expanded down only to the bottom edge of the display (to the end of the source
module or routine’s instructions). A register display cannot be expanded beyond
its full size.
For a list of the key definitions associated with the EXPAND command, type Help
Keypad_Definitions_CI. Also, use the SHOW KEY command to determine the
current key definitions.
Related commands:
DISPLAY
MOVE
SELECT/SCROLL
(SET,SHOW) TERMINAL
Examples
1.
DBG> EXPAND/RIGHT:6
This command moves the right border of the current scrolling display to the
right by 6 columns.
2.
DBG> EXPAND/UP/RIGHT:-12 OUT2
This command moves the top border of display OUT2 up by 1 line, and the
right border to the left by 12 columns.
DEBUG–117
EXPAND
3.
DBG> EXPAND/DOWN:99 SRC
This command moves the bottom border of display SRC down to the bottom
edge of the screen.
DEBUG–118
EXTRACT
EXTRACT
Saves the contents of screen displays in a file or creates a debugger command
procedure with all of the commands necessary to re-create the current screen
state later on.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
EXTRACT [display-name[, . . . ]] [file-spec]
Parameters
display-name
Specifies a display to be extracted. You can specify any of the following entities:
•
A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Integrity servers and Alpha only)
IREG
•
A display previously created with the DISPLAY command
You can use the asterisk ( * ) wildcard character in a display name. Do not specify
a display name with the /ALL qualifier.
file-spec
Specifies the file to which the information is written. You can specify a logical
name.
If you specify /SCREEN_LAYOUT, the default specification for the file is
SYS$DISK:[ ]DBGSCREEN.COM. Otherwise, the default specification is
SYS$DISK:[ ]DEBUG.TXT.
Qualifiers
/ALL
Extracts all displays. Do not specify /SCREEN_LAYOUT with this qualifier.
/APPEND
Appends the information at the end of the file, rather than creating a new file.
By default, a new file is created. Do not specify /SCREEN_LAYOUT with this
qualifier.
DEBUG–119
EXTRACT
/SCREEN_LAYOUT
Writes a file that contains the debugger commands describing the current state of
the screen. This information includes the screen height and width, message wrap
setting, and the position, display kind, and display attributes of every existing
display. This file can then be executed with the execute procedure (@) command
to reconstruct the screen at a later time. Do not specify /ALL with this qualifier.
Description
When you use the EXTRACT command to save the contents of a display into a
file, only those lines that are currently stored in the display’s memory buffer (as
determined by the /SIZE qualifier on the DISPLAY command) are written to the
file.
You cannot extract the PROMPT display into a file.
Related commands:
DISPLAY
SAVE
Examples
1.
DBG> EXTRACT SRC
This command writes all the lines in display SRC into file
SYS$DISK:[ ]DEBUG.TXT.
2.
DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE
This command appends all the lines in display OUT to the end of file
[JONES.WORK]MYFILE.TXT.
3.
DBG> EXTRACT/SCREEN_LAYOUT
This command writes the debugger commands needed to reconstruct the
screen into file SYS$DISK:[ ]DBGSCREEN.COM.
DEBUG–120
FOR
FOR
Executes a sequence of commands while incrementing a variable a specified
number of times.
Format
FOR name=expression1 TO expression2 [BY expression3]
DO (command[; . . . ])
Parameters
name
Specifies the name of a count variable.
expression1
Specifies an integer or enumeration type value. The expression1 and
expression2 parameters must be of the same type.
expression2
Specifies an integer or enumeration type value. The expression1 and
expression2 parameters must be of the same type.
expression3
Specifies an integer.
command
Specifies a debugger command. If you specify more than one command, you must
separate the commands with semicolons. At each execution, the debugger checks
the syntax of any expressions in the commands and then evaluates them.
Description
The behavior of the FOR command depends on the value of the expression3
parameter, as detailed in the following table:
expression3
Action of the FOR Command
Positive
name parameter is incremented from the value of expression1
by the value of expression3 until it is greater than the value of
expression2
name is decremented from the value of expression1 by
the value of expression3 until it is less than the value of
expression2
The debugger returns an error message
The debugger assumes it to have the value +1
Negative
0
Omitted
Related commands:
EXITLOOP
REPEAT
WHILE
DEBUG–121
FOR
Examples
1.
DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I))
This command examines an array backwards.
2.
DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0)
This command initializes an array to zero.
DEBUG–122
GO
GO
Starts or resumes program execution.
Format
GO [address-expression]
Parameters
address-expression
Specifies that program execution resume at the location denoted by the address
expression. If you do not specify an address expression, execution resumes at
the point of suspension or, in the case of debugger startup, at the image transfer
address.
Description
The GO command starts program execution or resumes execution from the point
at which it is currently suspended. GO is one of the four debugger commands
that can be used to execute your program (the others are CALL, EXIT, and
STEP).
Specifying an address expression with the GO command can produce unexpected
results because it alters the normal control flow of your program. For example,
during a debugging session you can restart execution at the beginning of the
program by entering the GO %LINE 1 command. However, because the program
has executed, the contents of some variables might now be initialized differently
from when you first ran the program.
If an exception breakpoint is triggered (resulting from a SET
BREAK/EXCEPTION or a STEP/EXCEPTION command), execution is suspended
before any application-declared condition handler is invoked. If you then resume
execution with the GO command, the behavior is as follows:
•
Entering a GO command to resume execution from the current location causes
the debugger to resignal the exception. This enables you to observe which
application-declared handler, if any, next handles the exception.
•
Entering a GO command to resume execution from a location other than the
current location inhibits the execution of any application-declared handler for
that exception.
If you are debugging a multiprocess program, the GO command is executed in the
context of the current process set. In addition, when debugging a multiprocess
program, the way in which execution continues in your process depends on
whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE
[NO]WAIT command. By default (SET MODE NOINTERRUPT), when one
process stops, the debugger takes no action with regard to the other processes.
Also by default (SET MODE WAIT), the debugger waits until all process in the
current process set have stopped before prompting for a new command. See
Chapter 15 for more information.
Related commands:
CALL
EXIT
RERUN
DEBUG–123
GO
SET BREAK
SET MODE [NO]INTERRUPT
SET MODE [NO]WAIT
SET PROCESS
SET STEP
SET TRACE
SET WATCH
STEP
WAIT
Examples
1.
DBG> GO
...
’Normal successful completion’
DBG>
This command starts program execution, which then completes successfully.
2.
DBG> SET BREAK RESTORE
DBG> GO
! start execution
...
break at routine INVENTORY\RESTORE
137: procedure RESTORE;
DBG> GO
! resume execution
...
In this example, the SET BREAK command sets a breakpoint on routine
RESTORE. The first GO command starts program execution, which is then
suspended at the breakpoint on routine RESTORE. The second GO command
resumes execution from the breakpoint.
3.
DBG> GO %LINE 42
This command resumes program execution at line 42 of the module in which
execution is currently suspended.
DEBUG–124
HELP
HELP
Displays online help on debugger commands and selected topics.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger. Help on commands is available
from the Help menu in a DECwindows debugger window.
Format
HELP topic [subtopic [ . . . ]]
Parameters
topic
Specifies the name of a debugger command or topic about which you want help.
You can specify the asterisk ( * ) wildcard character, either singly or within a
name.
subtopic
Specifies a subtopic, qualifier, or parameter about which you want further
information. You can specify the asterisk wildcard ( * ), either singly or within a
name.
Description
The debugger’s online help facility provides the following information about
any debugger command, including a description of the command, its format,
explanations of any parameters that can be specified with the command, and
explanations of any qualifiers that can be specified with the command.
To get information about a particular qualifier or parameter, specify it as a
subtopic. If you want information about all qualifiers, specify "qualifier" as a
subtopic. If you want information about all parameters, specify "parameter" as a
subtopic. If you want information about all parameters, qualifiers, and any other
subtopics related to a command, specify an asterisk ( * ) as a subtopic.
In addition to help on commands, you can get online help on various topics such
as screen features, keypad mode, and so on. Topic keywords are listed along with
the commands when you type HELP.
For help on the predefined keypad-key functions, type Help Keypad_Definitions_
CI. Also, use the SHOW KEY command to determine the current key definitions.
Example
DBG> HELP GO
This command displays help for the GO command.
DEBUG–125
IF
IF
Executes a sequence of commands if a language expression (Boolean expression)
is evaluated as true.
Format
IF Boolean-expression THEN (command[; . . . ])
[ELSE (command[; . . . ])]
Parameters
Boolean-expression
Specifies a language expression that evaluates as a Boolean value (true or false)
in the currently set language.
command
Specifies a debugger command. If you specify more than one command, you must
separate the commands with semicolons ( ; ).
Description
The IF command evaluates a Boolean expression. If the value is true (as defined
in the current language), the command list in the THEN clause is executed. If
the expression is false, the command list in the ELSE clause (if any) is executed.
Related commands:
EXITLOOP
FOR
REPEAT
WHILE
Example
DBG> SET BREAK R DO (IF X .LT. 5 THEN (GO) ELSE (EXAMINE X))
This command causes the debugger to suspend program execution at location R
(a breakpoint) and then resume program execution if the value of X is less than 5
(Fortran example). If the value of X is 5 or more, its value is displayed.
DEBUG–126
MONITOR
MONITOR
Displays the current value of a program variable or language expression in the
monitor view of the HP DECwindows Motif for OpenVMS user interface.
Note
Requires the HP DECwindows Motif for OpenVMS user interface.
Format
MONITOR expression
Parameters
expression
Specifies an entity to be monitored. With high-level languages, this is typically
the name of a variable. Currently, MONITOR does not handle composite
expressions (language expressions containing operators).
If you specify the name of an aggregate variable (a composite data structure such
as an array or record structure), the monitor view lists ‘‘Aggregate’’ for the value
of the variable. You can then double-click on the variable name to get the values
of all the elements (see Section 10.5.4.1).
To specify an individual array element, array slice, or record component, follow
the syntax of the current language.
Qualifiers
/ASCIC
/AC
Interprets each monitored entity as a counted ASCII string preceded by a 1-byte
count field that gives the length of the string. The string is then displayed.
/ASCID
/AD
Interprets each monitored entity as the address of a string descriptor pointing to
an ASCII string. The CLASS and DTYPE fields of the descriptor are not checked,
but the LENGTH and POINTER fields provide the character length and address
of the ASCII string. The string is then displayed.
/ASCII:n
Interprets and displays each monitored entity as an ASCII string of length n
bytes (n characters). If you omit n, the debugger attempts to determine a length
from the type of the address expression.
/ASCIW
/AW
Interprets each monitored entity as a counted ASCII string preceded by a 2-byte
count field that gives the length of the string. The string is then displayed.
DEBUG–127
MONITOR
/ASCIZ
/AZ
Interprets each monitored entity as a zero-terminated ASCII string. The ending
zero byte indicates the end of the string. The string is then displayed.
/BINARY
Displays each monitored entity as a binary integer.
/BYTE
Displays each monitored entity in the byte integer type (length 1 byte).
/DATE_TIME
Interprets each monitored entity as a quadword integer (length 8 bytes)
containing the internal OpenVMS representation of date and time. Displays
the value in the format dd-mmm-yyyy hh:mm:ss.cc.
/DECIMAL
Displays each monitored entity as a decimal integer.
/DEFAULT
Displays each monitored entity in the default radix.
/EXTENDED_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in the IEEE
X_floating type (length 16 bytes).
/FLOAT
On Alpha, displays each monitored entity in the IEEE T_floating type (double
precision, length 8 bytes).
/G_FLOAT
Displays each monitored entity in the G_floating type (length 8 bytes).
/HEXADECIMAL
Displays each monitored entity as a hexadecimal integer.
/INSTRUCTION
Displays each monitored entity as an assembly-language instruction (variable
length, depending on the number of instruction operands and the kind of
addressing modes used). See also the /OPERANDS qualifier.
/INT
Same as /LONGWORD qualifier.
/LONG_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in the IEEE
S_floating type (single precision, length 4 bytes).
/LONG_LONG_FLOAT
(Integrity servers and Alpha only) Displays each monitored entity in the IEEE
T_floating type (double precision, length 8 bytes).
DEBUG–128
MONITOR
/LONGWORD
/INT
/LONG
Displays each monitored entity in the longword integer type (length 4 bytes). This
is the default type for program locations that do not have a compiler-generated
type.
/OCTAL
Displays each monitored entity as an octal integer.
/OCTAWORD
Displays each monitored entity in the octaword integer type (length 16 bytes).
/QUADWORD
Displays each monitored entity in the quadword integer type (length 8 bytes).
/REMOVE
Removes a monitored item or items with the address expression specified from
the Monitor View.
/SHORT
Same as /WORD qualifier.
/TASK
Applies to tasking (multithread) programs. Interprets each monitored entity as
a task (thread) object and displays the task value (the name or task ID) of that
task object. When monitoring a task object, use /TASK only if the programming
language does not have built-in tasking services.
/WORD
/SHORT
Displays each monitored entity in the word integer type (length 2 bytes).
Description
You can use the MONITOR command only with the debugger’s HP DECwindows
Motif for OpenVMS user interface, because the output of that command is
directed at the monitor view. With the command interface, you typically use the
EVALUATE, EXAMINE or SET WATCH command instead.
The MONITOR command does the following:
1. Displays the monitor view (if it is not already displayed by a previous
MONITOR command).
2. Puts the name of the specified variable or expression and its current value in
the monitor view.
The debugger updates the monitor view whenever the debugger regains control
from the program, regardless of whether the value of the variable or location you
are monitoring has changed. (By contrast, a watchpoint halts execution when the
value of the watched variable changes.)
For more information about the monitor view and the MONITOR command, see
Section 10.5.4.
Related commands:
DEPOSIT
DEBUG–129
MONITOR
EVALUATE
EXAMINE
SET WATCH
Example
DBG> MONITOR COUNT
This command displays the name and current value of the variable COUNT in
the monitor view of the debugger’s HP DECwindows Motif for OpenVMS user
interface. The value is updated whenever the debugger regains control from the
program.
DEBUG–130
MOVE
MOVE
Moves a screen display vertically or horizontally across the screen.
Note
This command is not available in the HP DECwindows Motif for
OpenVMS user interface to the debugger.
Format
MOVE [display-name[, . . . ]]
Parameters
display-name
Specifies a display to be moved. You can specify any of the following entities:
•
A predefined display:
SRC
OUT
PROMPT
INST
REG
FREG (Integrity servers and Alpha only)
IREG
•
A display previously created with the DISPLAY command
•
A display built-in symbol:
%CURDISP
%CURSCROLL
%NEXTDISP
%NEXTINST
%NEXTOUTPUT
%NEXTSCROLL
%NEXTSOURCE
If you do not specify a display, the current scrolling display, as established by the
SELECT command, is chosen.
Qualifiers
/DOWN[:n]
Moves the display down by n lines (if n is positive) or up by n lines (if n is
negative). If you omit n, the display is moved down by 1 line.
/LEFT[:n]
Moves the display to the left by n lines (if n is positive) or right by n lines (if n is
negative). If you omit n, the display is moved to the left by 1 line.
/RIGHT[:n]
Moves the display to the right by n lines (if n is positive) or left by n lines (if n is
negative). If you omit n, the display is moved to the right by 1 line.
DEBUG–131
MOVE
/UP[:n]
Moves the display up by n lines (if n is positive) or down by n lines (if n is
negative). If you omit n, the display is moved up by 1 line.
Description
You must specify at least one qualifier.
For each display specified, the MOVE command simply creates a window of
the same dimensions elsewhere on the screen and maps the display to it, while
maintaining the relative position of the text within the window.
The MOVE command does not change the order of a display on the display
pasteboard. Depending on the relative order of displays, the MOVE command
can cause t