OpenVMS Debugger Manual

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-3 lists the optional views. They are accessible by choosing Views... from the Options menu on the main window.

Table 8-3 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.

**Table 8-3 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 VAX-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).

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

Figure 8-5 Breakpoint, Monitor, and Register Views

Figure 8-6 Instruction View

Figure 8-7 Tasking View

8.2.3.1 Menus on Optional Views Window

Figure 8-8 and Table 8-4 describe the menus on the optional views window.

Figure 8-8 Menus on Optional Views Window

Table 8-4 Menus on Optional Views Window
Menu Item Description

File Close Close the optional views window.

Exit Debugger End the debugging session, terminating the debugger.

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

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.

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

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

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

Options Views... Display one or more of the following:

Breakpoint view
Monitor view
Register view
Tasking view
Instruction view

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

Help 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-4 Menus on Optional Views Window**
Menu	Item	Description
File	Close	Close the optional views window.
	Exit Debugger	End the debugging session, terminating the debugger.
Break	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.
	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.
Monitor	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.
Register	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.
Tasks	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.
Options	Views...	Display one or more of the following: Breakpoint view Monitor view Register view Tasking view Instruction view
	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 DECwindows Motif 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.
Help	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 DECwindows Motif 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 DECwindows Motif GUI menus and push buttons for certain operations
To do debugging tasks not available through the DECwindows Motif GUI pull-down menus and push buttons

Figure 8-9 shows the RUN command in the command view.

Figure 8-9 Entering Commands at the Prompt

When you use the DECwindows Motif 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 2. 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 DECwindows Motif environment.

You can also take advantage of the keypad support available at the command-entry 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-5 are mapped to individual keys on your computer keypad.

Table 8-5 Keypad Definitions in the DECwindows Motif 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

**Table 8-5 Keypad Definitions in the DECwindows Motif 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.3.1 Debugger Commands That Are Not Available in the DECwindows Motif Interface

Table 8-6 lists the debugger commands that are disabled in the debugger's DECwindows Motif interface. Many of them are relevant only to the debugger's screen mode.

Table 8-6 Debugger Commands not Available in the DECwindows Motif 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¹ (SET,SHOW) WINDOW

MOVE (SET,CANCEL) DISPLAY

SAVE SHOW SELECT

SCROLL SPAWN

**Table 8-6 Debugger Commands not Available in the DECwindows Motif 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¹	(SET,SHOW) WINDOW
MOVE	(SET,CANCEL) DISPLAY
SAVE	SHOW SELECT
SCROLL	SPAWN

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

Choose On Context from the Help menu in a debugger window. The pointer shape changes to a question mark (?).
Place the question mark on an object or area in a debugger window or dialog box.
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 11, which is organized by task, explains how to use the debugger's Heap Analyzer.
You cannot get 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:

Choose On Commands from the Help menu of a debugger window.
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:

Choose On Commands from the Help menu of a debugger window.
Choose Messages from the list of additional topics.
Choose the message identifier from the list of additional topics.

Chapter 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.5)
End a debugging session (Section 9.6)
Start the debugger in additional ways for specific purposes (Section 9.7)

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.7 explains optional ways to start the debugger.

Starting the kept debugger as explained here enables you to use the Rerun (see Section 9.3) and Run (see Section 9.4) features.

To start the debugger and bring your program under debugger control:

Verify that you have compiled and linked the program as explained in Section 1.2.
Verify that the debugging configuration (default or multiprocess) is appropriate for the kind of program you are going to debug (see Section 1.9). For a program that runs in only one process (the typical case), use the default configuration.
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 12.2).
Figure 9-1 Debugger at Startup
Bring your program under debugger control using one of the following two techniques:
- 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 box 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.
  Figure 9-2 Running a Program by Specifying an Image
- 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 box 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:[MYDIRECTORY.MYSUBDIRECTORY]EIGHTQUEENS.EXE 
```
  3. Enter any arguments to be passed with the command in the Arguments: field.
  4. Click on OK.

Figure 9-3 Running a Program by Specifying a Command Symbol

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.

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.7.2).
You cannot run a program under debugger control over a DECnet link. Both the image to be debugged and the debugger must reside on the same node.

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

To avoid this problem, make sure the Select an application to run box in the File Selection popup contains a valid file specification.

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

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:

Choose Rerun Same... from the File menu on the main window. The Rerun dialog box is displayed (see Figure 9-5).
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.
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).
Click on OK.

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

  4538P014.HTM
  OSSG Documentation
  22-NOV-1996 13:01:51.32