OpenVMS Debugger Manual

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)
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 compiler-generated 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

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.

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.

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

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.

Set... Set a new breakpoint, optionally associated with a particular condition or action, at a specified location.

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

Options Views... Display one or more of the following:
Breakpoint view
Monitor view
Instruction view
Tasking view
Register view (see Table 8-2)

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.

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-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. 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.
Edit	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.
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.
	Set...	Set a new breakpoint, optionally associated with a particular condition or action, at a specified location.
Commands	Examine...	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.
Options	Views...	Display one or more of the following: Breakpoint view Monitor view Instruction view Tasking view Register view (see Table 8-2)
	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.
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-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

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

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

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

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

Figure 8-5 Monitor, Breakpoint, and Register Views

Figure 8-6 Instruction View

Figure 8-7 Thread View

8.2.3.1 Menus on Optional Views Window

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

Figure 8-8 Menus on Optional Views Window

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.

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
Instruction view
Tasking view
Register 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 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.

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-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.
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 Instruction view Tasking view Register 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 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.
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.

Contents

Index