HP OpenVMS Systems Documentation

The following commands control the display of source code:

The following commands control screen mode and screen displays:

The following commands control source editing from a debugging session:

The following commands define and delete symbols for addresses, commands, or values:

The following commands control keypad mode and key definitions:

The following commands are used with command procedures and log files:

The following commands establish conditional and looping structures for debugger commands:

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=).

The following commands are used for miscellaneous purposes:

For information about the debugger's DECwindows Motif user interface, see Part 3.

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

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
VWS_Workstations

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.

Figure 2-1 Keypad Key Functions Predefined by the Debugger---Command Interface

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 Displaying Source Code

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

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>

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.