CONTENTS Title Page Copyright Page Preface Part I Using the Debugger: DECwindows Interface 1 Introduction to the Debugger: DECwindows Interface 1.1 Overview of the Debugger 1.2 Starting a Debugging Session 1.2.1 Compiling and Linking a Program to Prepare for Debugging 1.2.2 Establishing the Debugging Configuration 1.2.3 Invoking the Debugger 1.3 Debugger Windows and Menus 1.3.1 Debugger Main Window 1.3.2 Debugger Predefined Windows 1.3.2.1 Predefined Source Window (SRC) 1.3.2.2 Predefined Output Window (OUT) 1.3.2.3 Predefined Automatic Window (AUTO) 1.3.2.4 Predefined Instruction Window (INST) 1.3.2.5 Predefined Register Window (REG) 1.3.3 Using the Pop-Up Menu 1.4 Getting Started with the Debugger 1.4.1 Setting a Breakpoint 1.4.2 Executing the Program to the Breakpoint 1.4.3 Executing the Program into a Called Routine 1.4.4 Displaying the Current Value of a Variable 1.4.5 Assigning a Value to the Variable 1.4.6 Displaying Source Code for the Calling Routine 1.5 Using the Debugger 1.5.1 Displaying Online Help About the Debugger 1.5.1.1 Displaying Context-Sensitive Help 1.5.1.2 Displaying the Overview Help Topic and Subtopics 1.5.1.3 Displaying Help About the Debugger's Command Interface 1.5.2 Debugger Diagnostic Messages 1.5.3 Interrupting Program Execution and Aborting Debugger Operations 1.5.4 Ending a Debugging Session 1.5.5 Displaying Source Code 1.5.6 Displaying Decoded VAX Instructions 1.5.7 Specifying Address Expressions in Dialog Boxes 1.5.8 Controlling and Monitoring Program Execution 1.5.8.1 Starting or Resuming Program Execution 1.5.8.2 Executing the Program by Step Unit 1.5.8.3 Suspending and Tracing Execution with Breakpoints and Tracepoints 1.5.8.4 Monitoring Changes in Variables with Watchpoints 1.5.9 Examining and Manipulating Program Data 1.5.9.1 Operations with Variables 1.5.9.2 Operations with Code Locations 1.5.9.3 Operations with Addresses or Registers 1.5.9.4 Evaluating Language Expressions 1.5.10 Controlling Access to Symbols in Your Program 1.5.10.1 Setting and Canceling Modules 1.5.10.2 Resolving Symbol Ambiguities 1.5.11 Using the Debugger's Command Interface 1.5.12 Using Log Files, Initialization Files, Command Procedures 1.5.13 Debugging Multilanguage Programs 1.5.14 Debugging Shareable Images and Ada Tasking Programs 1.5.15 Debugging Multiprocess Programs 1.5.16 Debugging Vectorized Programs 1.5.17 Using the Keypad to Enter Commands 1.6 Additional Options for Invoking the Debugger 1.6.1 Invoking the Debugger from a FileView Window 1.6.2 Invoking the Debugger with the DCL DEBUG Command 1.6.3 Overriding the Debugger's Default Interface 1.6.3.1 Displaying the Debugger's DECwindows Interface on Another Workstation 1.6.3.2 Displaying the Command Interface in a DECterm Window 1.6.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm Windows 1.6.3.4 Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY 1.7 Sample Program EIGHTQUEENS Part II Using the Debugger: Command Interface 2 Introduction to the Debugger: Command Interface 2.1 Overview of the Debugger 2.1.1 Functional Features 2.1.2 Convenience Features 2.2 Getting Started with the Debugger 2.2.1 Compiling and Linking a Program to Prepare for Debugging 2.2.2 Establishing the Debugging Configuration 2.2.3 Invoking the Debugger 2.2.4 Ending a Debugging Session 2.2.5 Interrupting Program Execution and Aborting Debugger Commands 2.2.6 Entering Debugger Commands 2.2.7 Displaying Source Code 2.2.7.1 Noscreen Mode 2.2.7.2 Screen Mode 2.2.8 Controlling and Monitoring Program Execution 2.2.8.1 Starting or Resuming Program Execution 2.2.8.2 Executing the Program by Step Unit 2.2.8.3 Determining Where Execution Is Suspended 2.2.8.4 Suspending Program Execution with Breakpoints 2.2.8.5 Tracing Program Execution with Tracepoints 2.2.8.6 Monitoring Changes in Variables with Watchpoints 2.2.9 Examining and Manipulating Program Data 2.2.9.1 Displaying the Value of a Variable 2.2.9.2 Assigning a Value to a Variable 2.2.9.3 Evaluating Language Expressions 2.2.10 Controlling Access to Symbols in Your Program 2.2.10.1 Setting and Canceling Modules 2.2.10.2 Resolving Symbol Ambiguities 2.3 A Sample Debugging Session 2.4 Debugger Command Summary 2.4.1 Starting and Ending a Debugging Session 2.4.2 Controlling and Monitoring Program Execution 2.4.3 Examining and Manipulating Data 2.4.4 Controlling Type Selection and Radix 2.4.5 Controlling Symbol Lookup and Symbolization 2.4.6 Displaying Source Code 2.4.7 Using Screen Mode 2.4.8 Editing Source Code 2.4.9 Defining Symbols 2.4.10 Using Keypad Mode 2.4.11 Using Command Procedures, Log Files, and Initialization Files 2.4.12 Using Control Structures 2.4.13 Debugging Multiprocess Programs 2.4.14 Additional Commands 3 Controlling and Monitoring Program Execution 3.1 Starting and Ending a Debugging Session 3.1.1 Invoking the Debugger with the DCL RUN Command 3.1.2 Invoking the Debugger with the DCL DEBUG Command 3.1.3 Ending a Debugging Session 3.2 Interrupting and Resuming a Debugging Session 3.3 Commands Used to Execute the Program 3.4 Executing the Program by Step Unit 3.4.1 Changing the STEP Command Behavior 3.4.2 Stepping into and over Routines 3.5 Suspending and Tracing Execution with Breakpoints and Tracepoints 3.5.1 Setting Breakpoints or Tracepoints on Individual Program Locations 3.5.1.1 Specifying Symbolic Addresses 3.5.1.2 Specifying Locations in Memory 3.5.1.3 Obtaining and Symbolizing Memory Addresses 3.5.2 Setting Breakpoints or Tracepoints on Lines or Instructions 3.5.3 Controlling Debugger Action at Breakpoints or Tracepoints 3.5.4 Setting Breakpoints or Tracepoints on Exceptions 3.5.5 Setting Breakpoints or Tracepoints on Language-Specific Events 3.5.6 Canceling Breakpoints or Tracepoints 3.6 Monitoring Changes in Variables and Other Program Locations 3.6.1 Watchpoint Options 3.6.2 Watching Nonstatic Variables 3.6.2.1 Execution Speed 3.6.2.2 Setting a Watchpoint on a Nonstatic Variable 3.6.2.3 Options for Watching Nonstatic Variables 3.6.2.4 Setting Watchpoints in Installed Writeable Shareable Images 3.7 How the Debugger Controls Program Execution 4 Examining and Manipulating Program Data 4.1 General Concepts 4.1.1 Accessing Variables While Debugging 4.1.2 Using the EXAMINE Command 4.1.3 Using the DEPOSIT Command 4.1.4 Address Expressions and Their Associated Types 4.1.5 Evaluating Language Expressions 4.1.5.1 Using Variables in Language Expressions 4.1.5.2 Numeric Type Conversion by the Debugger 4.1.6 Address Expressions Compared to Language Expressions 4.1.7 Specifying the Current, Previous, and Next Entity 4.1.8 Language Dependencies and the Current Language 4.1.9 Specifying a Radix for Entering or Displaying Integer Data 4.1.10 Obtaining and Symbolizing Memory Addresses 4.2 Examining and Depositing into Variables 4.2.1 Scalar Types 4.2.2 ASCII String Types 4.2.3 Array Types 4.2.4 Record Types 4.2.5 Pointer (Access) Types 4.3 Examining and Depositing VAX Instructions 4.3.1 Examining VAX Instructions 4.3.2 Depositing VAX Instructions 4.4 Examining and Depositing into Registers 4.4.1 The Processor Status Longword (PSL) 4.5 Specifying a Type When Examining and Depositing 4.5.1 Defining a Type for Locations Without a Symbolic Name 4.5.2 Overriding the Current Type 4.5.2.1 Integer Types 4.5.2.2 ASCII String Type 4.5.2.3 User-Declared Types 5 Controlling Access to Symbols in Your Program 5.1 Controlling Symbol Information When Compiling and Linking 5.1.1 Compiling 5.1.2 Local and Global Symbols 5.1.3 Linking 5.1.4 Controlling Symbol Information in Debugged Images 5.2 Setting and Canceling Modules 5.3 Resolving Symbol Ambiguities 5.3.1 Symbol Lookup Conventions 5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely 5.3.2.1 Simplifying Path Names 5.3.2.2 Specifying Symbols in Routines on the Call Stack 5.3.2.3 Specifying Global Symbols 5.3.2.4 Specifying Routine Invocations 5.3.3 Using SET SCOPE to Specify a Symbol Search Scope 5.4 Debugging Shareable Images 5.4.1 Compiling and Linking Shareable Images for Debugging 5.4.2 Accessing Symbols in Shareable Images 5.4.2.1 Accessing Symbols in the PC Scope (Dynamic Mode) 5.4.2.2 Accessing Symbols in Arbitrary Images 5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images 6 Controlling the Display of Source Code 6.1 How the Debugger Obtains Source Code Information 6.2 Specifying the Location of Source Files 6.3 Displaying Source Code by Specifying Line Numbers 6.4 Displaying Source Code by Specifying Code Address Expressions 6.5 Displaying Source Code by Searching for Strings 6.6 Controlling Source Display After Stepping and at Event Points 6.7 Setting Margins for Source Display 7 Using Screen Mode 7.1 Concepts and Terminology 7.2 Debugger Predefined Displays 7.2.1 Predefined Source Display (SRC) 7.2.1.1 Displaying Source Code in Arbitrary Program Locations 7.2.1.2 Displaying Source Code for a Routine on the Call Stack 7.2.2 Predefined Output Display (OUT) 7.2.3 Predefined Prompt Display (PROMPT) 7.2.4 Predefined Instruction Display (INST) 7.2.4.1 Displaying the Instruction Display 7.2.4.2 Displaying Instructions in Arbitrary Program Locations 7.2.4.3 Displaying Instructions for a Routine on the Call Stack 7.2.5 Predefined Register Display (REG) 7.3 Manipulating Existing Displays 7.3.1 Scrolling a Display 7.3.2 Showing, Hiding, Removing, and Canceling a Display 7.3.3 Moving a Display Across the Screen 7.3.4 Expanding or Contracting a Display 7.4 Creating a New Display 7.5 Specifying a Display Window 7.5.1 Specifying a Window in Terms of Lines and Columns 7.5.2 Predefined Windows 7.5.3 Creating a New Window Definition 7.6 Specifying the Display Kind 7.6.1 DO (command[; . . . ]) Display Kind 7.6.2 INSTRUCTION Display Kind 7.6.3 INSTRUCTION (command) Display Kind 7.6.4 OUTPUT Display Kind 7.6.5 REGISTER Display Kind 7.6.6 SOURCE Display Kind 7.6.7 SOURCE (command) Display Kind 7.6.8 PROGRAM Display Kind 7.7 Assigning Display Attributes 7.8 A Sample Display Configuration 7.9 Saving Displays and the Screen State 7.10 Changing the Screen Height and Width 8 Additional Convenience Features 8.1 Using Debugger Command Procedures 8.1.1 Basic Conventions 8.1.2 Passing Parameters to Command Procedures 8.2 Using a Debugger Initialization File 8.3 Logging a Debugging Session into a File 8.4 Defining Symbols for Commands, Address Expressions, and Values 8.4.1 Defining Symbols for Commands 8.4.2 Defining Symbols for Address Expressions 8.4.3 Defining Symbols for Values 8.5 Assigning Commands to Function Keys 8.5.1 Basic Conventions 8.5.2 Advanced Techniques 8.6 Using Control Structures to Enter Commands 8.6.1 FOR Command 8.6.2 IF Command 8.6.3 REPEAT Command 8.6.4 WHILE Command 8.6.5 EXITLOOP Command 8.7 Calling Routines Independently of Program Execution 9 Debugging Special Cases 9.1 Debugging Optimized Code 9.1.1 Eliminated Variables 9.1.2 Changes in Coding Order 9.1.3 Use of Registers 9.1.4 Use of Condition Codes 9.2 Debugging Screen-Oriented Programs 9.2.1 Setting the Protection to Allocate a Terminal 9.3 Debugging Multilanguage Programs 9.3.1 Controlling the Current Debugger Language 9.3.2 Specific Differences Among Languages 9.3.2.1 Default Radix 9.3.2.2 Evaluating Language Expressions 9.3.2.3 Arrays and Records 9.3.2.4 Case Sensitivity 9.3.2.5 Initialization Code 9.3.2.6 Ada Predefined Breakpoints 9.4 Debugging Exceptions and Condition Handlers 9.4.1 Setting Breakpoints or Tracepoints on Exceptions 9.4.2 Resuming Execution at an Exception Breakpoint 9.4.3 Effect of Debugger on Condition Handling 9.4.3.1 Primary Handler 9.4.3.2 Secondary Handler 9.4.3.3 Call-Frame Handlers (Application-Declared) 9.4.3.4 Final and Last-Chance Handlers 9.4.4 Exception-Related Built-In Symbols 9.5 Debugging Exit Handlers 9.6 Debugging AST-Driven Programs 9.6.1 Disabling and Enabling the Delivery of ASTs 9.6.2 Call Frames Associated with ASTs in SHOW CALLS Display 10 Debugging Multiprocess Programs 10.1 Getting Started 10.1.1 Establishing a Multiprocess Debugging Configuration 10.1.2 Invoking the Debugger 10.1.3 Visible Process and Process-Specific Commands 10.1.4 Obtaining Information about Processes 10.1.5 Bringing a Spawned Process Under Debugger Control 10.1.6 Broadcasting Commands to Specified Processes 10.1.7 Controlling Execution 10.1.7.1 Controlling Execution with SET MODE NOINTERRUPT 10.1.7.2 Putting Specified Processes on Hold 10.1.8 Changing the Visible Process 10.1.9 Dynamic Process Setting 10.1.10 Monitoring the Termination of Images 10.1.11 Ending the Debugging Session 10.1.12 Terminating Specified Processes 10.1.13 Interrupting Program Execution 10.2 Supplemental Information 10.2.1 Debugging Configurations and Process Relationships 10.2.1.1 Establishing a Default Debugging Configuration 10.2.1.2 Establishing a Multiprocess Debugging Configuration 10.2.1.3 Process Relationships When Debugging 10.2.2 Specifying Processes in Debugger Commands 10.2.3 Monitoring Process Activation and Termination 10.2.4 Interrupting the Execution of an Image to Connect it to the Debugger 10.2.4.1 Using the CTRL/Y-DEBUG Sequence to Invoke the Debugger 10.2.4.2 Using the CONNECT Command to Interrupt an Image 10.2.5 Screen Mode Features for Multiprocess Debugging 10.2.6 Setting Watchpoints in Global Sections 10.2.7 Using Multiprocess Commands with the Default Configuration 10.2.8 Advanced Concepts and Possible Errors 10.2.9 System Requirements For Multiprocess Debugging 10.2.9.1 User Quotas 10.2.9.2 System Resources 11 Debugging Vectorized Programs 11.1 Obtaining Information About the Vector Processor 11.2 Controlling and Monitoring the Execution of Vector Instructions 11.2.1 Executing the Program to the Next Vector Instruction 11.2.2 Setting Breakpoints and Tracepoints on Vector Instructions 11.2.3 Setting Watchpoints on Vector Registers 11.3 Examining and Depositing into Vector Registers 11.3.1 Specifying the Vector Registers and Vector Control Registers 11.3.2 Examining and Depositing into the Vector Count Register (VCR) 11.3.3 Examining and Depositing into the Vector Length Register (VLR) 11.3.4 Examining and Depositing into the Vector Mask Register (VMR) 11.3.5 Examining and Depositing into the Vector Registers (V0 to V15) 11.4 Examining and Depositing Vector Instructions 11.4.1 Examining Vector Instructions and Their Operands 11.4.2 Depositing Vector Instructions 11.5 Using a Mask When Examining Vector Registers or Instructions 11.5.1 Using VMR as the Default Mask 11.5.2 Using a Slice of VMR as the Mask 11.5.3 Using a Mask Other than VMR 11.6 Examining Composite Vector Address Expressions 11.7 Displaying the Results of Vector Floating-Point Exceptions 11.8 Controlling Scalar-Vector Synchronization 11.9 Calling Routines That Might Affect the Program's Vector State 11.10 Displaying Vector Register Data in Screen Mode Debugger Command Dictionary 1 Debugger Command Format 1.1 General Format 1.2 Entering Commands at the Keyboard 1.3 Entering Commands in Command Procedures 2 Debugger Diagnostic Messages 3 Commands Recognized Only on Workstations Running VWS 4 Debugger Command Dictionary @ (Execute Procedure) ATTACH CALL CANCEL ALL CANCEL BREAK CANCEL DISPLAY CANCEL IMAGE CANCEL MODE CANCEL MODULE CANCEL RADIX CANCEL SCOPE CANCEL SOURCE CANCEL TRACE CANCEL TYPE/OVERRIDE CANCEL WATCH CANCEL WINDOW CONNECT CTRL/C CTRL/W, CTRL/Z CTRL/Y DECLARE DEFINE DEFINE/KEY DEFINE/PROCESS_GROUP DELETE DELETE/KEY DEPOSIT DISABLE AST DISPLAY DO EDIT ENABLE AST EVALUATE EVALUATE/ADDRESS EXAMINE EXIT EXITLOOP EXPAND EXTRACT FOR GO HELP IF MOVE QUIT REPEAT SAVE SCROLL SEARCH SELECT SET ABORT_KEY SET ATSIGN SET BREAK SET DEFINE SET EDITOR SET EVENT_FACILITY SET IMAGE SET KEY SET LANGUAGE SET LOG SET MARGINS SET MAX_SOURCE_FILES SET MODE SET MODULE SET OUTPUT SET PROCESS SET PROMPT SET RADIX SET SCOPE SET SEARCH SET SOURCE SET STEP SET TASK SET TERMINAL SET TRACE SET TYPE SET VECTOR_MODE 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 SHOW MAX_SOURCE_FILES 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 SHOW TERMINAL SHOW TRACE SHOW TYPE SHOW VECTOR_MODE SHOW WATCH SHOW WINDOW SPAWN STEP SYMBOLIZE SYNCHRONIZE VECTOR_MODE TYPE WHILE A Command Defaults B Predefined Key Functions B.1 DEFAULT, GOLD, BLUE Functions B.2 Key Definitions Specific to LK201 Keyboards B.3 Keys that Scroll, Move, Expand, Contract Displays B.4 Online Keypad Key Diagrams B.5 Debugger Key Definitions C Screen Mode Reference Information C.1 Display Kinds C.2 Display Attributes C.3 Predefined Displays C.3.1 SRC (Source Display) C.3.2 OUT (Output Display) C.3.3 PROMPT (Prompt Display) C.3.4 INST (Instruction Display) C.3.5 REG (Register Display) C.4 Screen-Related Built-In Symbols C.4.1 Screen Height and Width C.4.2 Display Built-In Symbols C.5 Screen Dimensions and Predefined Windows D Built-In Symbols and Logical Names D.1 SS$_DEBUG Condition D.2 Logical Names D.3 Built-In Symbols D.3.1 Specifying the VAX Registers D.3.2 Constructing Identifiers D.3.3 Counting Parameters Passed to Command Procedures D.3.4 Controlling the Input Radix D.3.5 Specifying Program Locations and the Current Value of an Entity D.3.6 Using Symbols and Operators in Address Expressions D.3.7 Obtaining Information About Exceptions D.3.8 Specifying Ada Tasks D.3.9 Specifying the Current, Next, and Previous Scope on the Call Stack E Summary of Debugger Support for Languages E.1 Ada E.2 BASIC E.3 BLISS E.4 C E.5 COBOL E.6 DIBOL E.7 FORTRAN E.8 MACRO E.9 Pascal E.10 PL/I E.11 RPG E.12 SCAN E.13 Language UNKNOWN EXAMPLES 1-1 Command Procedure SEPARATE_WINDOW.COM 1-2 Sample Program EIGHTQUEENS 2-1 Sample Program SQUARES 2-2 Sample Debugging Session Using Program SQUARES FIGURES 1-1 Debugger Windows at Startup 1-2 Debugger Main Window 1-3 Main Window Pull-Down Menus 1-4 Data Menu and Submenus 1-5 Customize Menu and Submenus 1-6 Pop-Up Menu Over Source Window 1-7 Source Window at Debugger Startup 1-8 Setting a Breakpoint with the Pop-Up Menu 1-9 Execution Suspended at Line 60 1-10 Stepping into a Called Routine 1-11 Execution Suspended Within the Called Routine 1-12 Examining a Selected Variable with the Pop-Up Menu 1-13 Assigning a Value to a Variable 1-14 Displaying Source Code in the Calling Routine 1-15 Keypad Key Functions Predefined by the Debugger-DECwindows Interface 2-1 Keypad Key Functions Predefined by the Debugger-Command Interface 2-2 Default Screen Mode Display Configuration 7-1 Default Screen Mode Display Configuration 7-2 Screen Mode Source Display When Source Code Is Not Available 7-3 Screen Mode Instruction Display 7-4 Screen Mode Register Display 11-1 Masked Loading of Array Elements from Memory into a Vector Register B-1 Keypad Key Functions Predefined by the Debugger-Command Interface TABLES 1-1 Main Window Pull-Down Menus 1-2 Main Window Status Region 1-3 Main Window Buttons 3-1 Controlling Debugger Activation with the LINK and RUN Commands 5-1 Compiler Options for DST Symbol Information 5-2 Effect of Compiler and Linker on DST and GST Symbol Information 10-1 Debugging States 10-2 Process Specifications CD-1 Debugging States B-1 Key Definitions Specific to LK201 Keyboards B-2 Keys that Change the Key State B-3 Keys that Invoke Online Help to Display Keypad Diagrams B-4 Debugger Key Definitions