2 Introduction to the Ladebug Debugger: Graphical User Interface

This chapter introduces the Ladebug debugger graphical user interface and provides the following information:

An orientation to the debugger's screen features, such as windows, menus, and so on (Section 2.2)
Instructions for using context-sensitive pop-up menus (Section 2.3)
Instructions for entering debugger commands at the command-entry prompt (Section 2.4)
Instructions for accessing online help (Section 2.5)

For information about starting a debugger session, see Chapter 3. For information about using the debugger, see Chapter 4. For information about advanced debugging techniques, see Chapter 5.

2.1 Convenience Features

This section highlights some of the convenience features of the debugger's window interface. Figure 2-1 gives visual details of the Main Window.

Figure 2-1 Default Main Window Configuration

Source View

The Source View is used for examining the source code of an object. The source-code display in the Source View is automatically updated to show where program execution is currently paused. The Source View has a line number area for setting breakpoints. You can enable and disable the display of line numbers.

A source browser feature lists the images, modules, and routines of your program and lets you display source code in arbitrary modules or routines and set breakpoints on routines. By double clicking on image and module names, you can list the underlying hierarchy of modules and routines. See Section 4.1.1 for more information about the source browser.

Source View Context Panel

The Source View Context Panel has pull-down menu buttons that allow the user to select a process or thread to be displayed in the Source View or to replace the currently displayed process or thread with a different process or thread.

The Source View Context Panel has three option menu buttons:

The Process menu lists the available processes (processes the debugger knows about)
The Thread menu lists the threads within the current process. If the current process has only one thread, the thread menu button is blank.
The Call Stack menu lists the sequence of routine calls currently on the Call Stack.

See Chapter 5 for more information about using the current process and thread.

Command Message View

The Command Message View, located directly under the push-button panel in the Main Window, displays user commands and debugger output.

Breakpoints

A breakpoint is a location in your program at which you want execution to stop so that you can perform actions such as checking the current value of a variable or stepping into a routine. You set, deactivate, and activate breakpoints by clicking on buttons next to the source lines in the main window or the instruction window.

Optionally you can set, deactivate, or activate breakpoints by selecting items in window pull-down menus, context-sensitive menus, or dialog boxes. You can set conditional breakpoints or action breakpoints. See Section 4.4 for more information about breakpoints.

Push-Button Panel

Push buttons in the push-button panel control common operations: by clicking on a 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 buttons and the associated debugger commands. See Section 4.9.3 for more information about customizing the push- button panel.

Context-Sensitive Pop-Up Menus

Context-sensitive pop-up menus in debugger windows and views list common operations associated with your location: when you click on MB3, the menu lists actions for the text you have selected, the source line at which you are pointing, or the window pane in which you are working. For more information about using context-sensitive pop-up menus (see Section 2.3).

Displaying and Manipulating Data

To display the value of a variable or expression, you select text from the main window and click on the Print button. If you choose, you can display values in different type or radix formats.

Run/Rerun Program

You can rerun the same program or run another program from the same debugging session without exiting the debugger. When rerunning a program, you can choose to save the current state (activated or deactivated) of breakpoints.

Optional Views

Optional Views include several context-related views. The Optional View Window also contains process and thread visual cues (indicators), which show the currently active process or thread (see Chapter 5).

Optional Views include:

Breakpoint
Instruction
Register
Monitor
Local Variables

These views are described in more detail in Section 2.2.2.

Debugger I/O Window

The Debugger I/O Window displays user input and program output for interactive programs. This isolates program I/O from debugger I/O, which appears in the Command Message View.

A Debugger I/O Window displays by default if you invoke the debugger in any of the following ways:

If you invoke the debugger within DEC FUSE.
If you invoke the debugger from the command line using the -iow option.

If you invoke the debugger within CDE, by default a terminal window opens to display I/O.

Integration with Command Interface

The debugger's window interface is layered on, and closely integrated with, the command-driven debugger as follows:

When you use the window interface, the resulting commands are echoed in the Command Message View so that you can correlate input to and output from the debugger.
When you enter commands at the prompt, they update the window views accordingly.

Integration with the Source-Level Editor

After you locate an error in your source code, you do not need to exit the debugger to edit your source code. You can display the source code in an editor window, search and replace text, or add additional text.

Customization

You can modify the following and other aspects of the debugger's window interface and save the current settings in a resource file to customize your debugger startup environment:

Configuration of windows and views (for example, size, screen location, order)
Push-button labels and associated debugger commands, including adding and removing buttons and commands

Online Help

You can get context-sensitive online help for the debugger's window interface. You can also display reference pages for debugger commands. For more information about getting online help, see Section 2.5.

2.2 Debugger Windows and Menus

The following sections describe the debugger windows, menus, views, and other screen features.

2.2.1 Default Main Window Configuration

By default at startup, the debugger displays a Main Window which consists of:

Banner
Menu Bar (see Section 2.2.1.1)
Source View (see Section 2.2.1.2)
Source View Context Panel (see Section 2.2.1.3)
- Process menu
- Thread menu
- Call Stack menu
Push-button panel (see Section 2.2.1.4)
Command Message View (see Section 2.2.1.5)

The Main Window is shown in Figure 2-1.

When you start the debugger as explained in Section 3.1, the Source View is initially empty. Figure 2-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 4.9.1.

2.2.1.1 Menus on the Main Window

Figure 2-2 and Table 2-1 show and describe the menus on the Main Window.

Figure 2-2 Menus on the Main Window

Table 2-1 Menus on the Main Window

Menu	Item	Description
File	Run New Program...	Brings a program under debugger control by specifying an executable image.
	Rerun Same Program...	Reruns the previous program under debugger control.
	Browse Source...	Displays the source code in any module of your program. You may set breakpoints on routines.
	Display Line Numbers	Displays or hides line numbers in the source display.
	Exit Debugger	Ends the debugging session, terminating the debugger.
Edit	Cut	Cuts selected text from the window and copies it to the clipboard.
	Copy	Copies selected text from the window to the clipboard without removing it from the window.
	Paste	Pastes text from the clipboard to a text-entry field or region.
Views	Manage Views...	Displays a dialog box which you can use to manage all the views.
	Breakpoint View	Toggles the Breakpoint View.
	Instruction View	Toggles the Instruction View.
	Register View	Toggles the Register View.
	Monitor View	Toggles the Monitor View.
	Local Variables View	Toggles the Local Variables View.
Commands	Print...	Prints the current value of a variable or expression.
	Assign...	Changes the value of a variable.
	Edit File	Opens the editable source file with the current file displayed.
	Attach to Process...	Replace the currently active process with a selected process, leaving the previous process under debugger control.
	Detach from Process...	Allows you to detach from a previously attached process.
Options	Customize...	Modifies, adds, removes, or resequences a button in the push-button pane and the associated debugger command.
	Save Options	Saves the customizations that you have made for use in subsequent debugger sessions.
Help	On Context	Provides context-sensitive help.
	On Window	Provides information about the main window.
	On Help	Provides information about the online help system.
	On Version	Provides the current version of the debugger.
	On Commands	Provides information about debugger commands.

2.2.1.2 Source View

The Source View in the Main Window shows the following:

Source display of the code you are debugging and, optionally, the line numbers to the left of the code. (To choose not to display line numbers, select File:Display Line Numbers.
Breakpoint toggles allow you to activate or deactivate breakpoints on specific source lines or routines in your program.
Current location pointer to the left of the breakpoint toggles, which points to the line of source code that will be executed when program execution resumes.

The portion of the source display pane containing the breakpoint toggles and current location pointer is referrred to as the annotation area.

For more information about displaying source code, see Section 2.2.1.1 and Section 4.1.

2.2.1.3 Source View Context Panel

Figure 2-3 and Table 2-2 show and describe the menu buttons on the Source View Context Panel of the Main Window.

Figure 2-3 Menu Buttons on Source View Context Panel

Table 2-2 Source View Context Panel

Button	Function
Process	Allows the user to detach the Source View from the current process and to attach it to a different process (see Chapter 5).
Thread	Allows the user to detach the Source View from the current thread and to attach it to a different thread (see Chapter 5).
Call Stack	Identifies the routine where execution is stopped. This menu lists the sequence of routine calls currently on the stack and lets you set the scope for source display and symbol searches to any routine on the stack (see Section 4.6.1).

2.2.1.4 Push-Button Panel

Figure 2-4 and Table 2-3 show and describe the default push buttons in the push-button panel. You can modify, add, remove, and resequence buttons and their associated commands as explained in Section 4.9.3.

Figure 2-4 Default Buttons in the Push-Button Panel

Table 2-3 Default Buttons in the Push- Button Panel

Button	Description
Interrupt	Interrupts program execution or a debugger operation without ending the debugging session.
Monitor	In the Monitor View, displays the name and current value of a variable that you have selected in a window. Whenever the debugger regains control from your program, it automatically checks the variable and updates the displayed value accordingly.
Print	In the Command Message View, displays the current value of a variable whose name you have selected in a window.
Next	Executes the program one step unit of execution. By default, this is one executable line of source code.
Step	When execution is suspended at a routine call statement, moves execution into the called routine just past the start of the routine. If not at a routine call statement, this push button has the same behavior as the Next push button.
Return	Executes the program directly to the end of the current routine.
Continue	Starts or resumes execution from the current program location.

2.2.1.5 Command Message View

The Command Message View, located directly under the push-button panel in the main window, displays any debugger output. Examples of such output are:

The result of a debugger operation.
Diagnostic messages.
Command echo. The debugger translates your window input into commands. The command echo enables you to correlate your input with the corresponding command line that the debugger processes.

The Command Message View has a command-entry prompt (ladebug) that enables you to enter commands as explained in Section 2.4.

2.2.2 Optional Views Window

Table 2-4 lists the optional views. They are accessible from either the Views menu on the Main or the Optional Views Window.

Table 2-4 Optional Views

View	Description
Breakpoint	Lists all breakpoints that are currently set and identifies those which are activated, deactivated, or qualified as conditional breakpoints. The Breakpoint View also allows you to modify the state of each breakpoint (see Section 4.4).
Monitor	Lists 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). If you choose, you can also change the values of variables (see Section 4.5.3.3).
Local Variables	Lists local variables and parameters passed to a routine. If you change the Call Stack level, this view is updated to show the variables at the routine in the given stack. When a new routine is detected at the top of the stack, all variables for the previous routine are removed and variables for the new routine are displayed, (see Section 4.5.4.1).
Register	Displays the current contents of all machine registers. The debugger updates the values whenever it regains control from your program. The Register View also enables you to change the values in registers (see Section 4.7).
Instruction	Displays the decoded instruction stream of your program and allows you to set breakpoints on instructions. By default, the debugger displays the corresponding source-code line numbers to the left of the instructions. You can choose to suppress these, if you wish (see Section 4.8).

All views by default are not displayed at startup.

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

Figure 2-5 shows the Breakpoint View.

Figure 2-5 Breakpoint View

Figure 2-6 shows the Monitor View.

Figure 2-6 Monitor View

Figure 2-7 shows the Register View.

Figure 2-7 Register View

Figure 2-8 shows the Instruction View.

Figure 2-8 Instruction View

Figure 2-9 shows the Local Variables View.

Figure 2-9 Local Variables View

2.2.2.1 Menus on Optional Views Window

Figure 2-10 shows the menus in the Optional Views Window.

Figure 2-10 Menus on Optional Views Window

Table 2-5 describes the menus in the Optional Views Window.

Table 2-5 Menus in Optional Views Window

Menu	Item	Description
File	Exit Debugger	Ends the debugging session, terminating the debugger.
Views	Manage Views...	Allows you to manage all views.
	Breakpoint View	Toggles the Breakpoint View.
	Instruction View	Toggles the Instruction View.
	Register View	Toggles the Register View.
	Monitor View	Toggles the Monitor View.
	Local Variables View	Toggles the Local Variables View.
Break	Activate All	Activates any previously deactivated breakpoints (see Section 4.4.4).
	Deactivate All	Deactivates any previously activated breakpoints (see Section 4.4.4).
	Delete All...	Removes all breakpoints from the debugger's breakpoint list and from the Breakpoint View (see Section 4.4.4).
	Toggle	Toggles a breakpoint (see Section 4.4.4).
	Set/Modify...	Sets a new breakpoint, optionally associated with a particular condition or action, at a specified location. (See Section 4.4.5 and Section 4.4.6).
	Delete	Deletes an individual breakpoint (see Section 4.4.4).
Monitor	Assign...	Changes the value of a monitored element.
	Typecast	Uses the submenu to typecast output for a selected variable to int, long, short, or char*.
	Change Radix	Uses the submenu to change the output radix for a selected variable to hex, octal, or decimal.
	Change All Radix	Uses the submenu to change the output radix for all subsequent monitored elements to hex, octal, or decimal.
	Remove	Removes an element from the Monitor View.
Register	Modify...	Changes the value of a selected register (see Section 4.7).
	Change Radix	Uses the submenu to change current and previous output for selected register to hex, octal, or decimal.
	Change All Radix	Uses the submenu to change current and previous output for all registers to hex, octal, or decimal.
Options	Customize...	Modifies, adds, removes, or resequences a button in the push-button panel and the associated debugger command (see Section 4.9.1).
	Save Options...	Saves the current settings of all window features of the debugger that you can customize interactively, such as the configuration of the windows and views, button definitions, and so on. These settings are observed when you subsequently start up the debugger (see Section 4.9.1).
Help	On Context	Provides context-sensitive help (see Section 2.5).
	On Window	Provides information about the Optional Views Window.
	On Help	Provides information about the online help system.
	On Version	Provides the current version of the debugger.
	On Commands	Provides information about debugger commands.

2.2.2.2 Menus on Instruction View

Figure 2-11 shows the menus in the Instruction View.

Figure 2-11 Menus on Instruction View

Table 2-6 describes the menus on the Instruction View.

Table 2-6 Menus on Instruction View

Menu	Item	Description
File	Show Instruction Addresses	Displays the address associated with each instruction listed in the Instruction View.
	Display Line Numbers	Displays the line number of your source-code program associated with each instruction or set of instructions listed in the Instruction View.
Edit	Copy	Copies text you have selected in the window to the clipboard without removing it from the window. To paste your text from the clipboard to a text-entry field or region, choose Edit:Paste item on the main window.
Break	Activate All	Activates any previously set breakpoints.
	Deactivate All	Deactivates any previously set breakpoints.
	Delete All...	Removes all breakpoints from the debugger's breakpoint list and from the Instruction View.
	Set...	Sets an individual breakpoint (see Section 4.4.5 and Section 4.4.6.)
Help	On Context	Provides context-sensitive help (see Section 2.5).
	On Window	Provides information about the Instruction View.
	On Help	Provides information about the online help system.
	On Version	Provides the current version of the debugger.
	On Commands	Provides information about debugger commands.

2.3 Using Context-Sensitive Pop-Up Menus

Context-sensitive pop-up menus in debugger windows and views list common operations associated with your location: when you click MB3, the menu lists actions for the text you have selected, the source line at which you are pointing, or the window pane in which you are working.

2.3.1 Source View Pop-Up Menu

To use pop-up menus in the source view, select text or position your mouse pointer in the source display, and press MB3. A pop- up menu appears with the items in Table 2-7. The debugger inserts the selected text or line number in the menu items of the pop-up menu.

Table 2-7 Source View Pop-Up Menu

Menu Item	Description
Print [selection]	Evaluates the selected expression and prints its value in the Command Message View.
Monitor [selection]	Inserts the selected expression in the monitor list of the Monitor View.
Assign [selection]	Provides the Assign dialog box.
Stop in Routine [selection]	Sets a breakpoint on a selected routine name.
Toggle Breakpoint at Line [line number]	Activates/deactivates a breakpoint at the mouse pointer.
Temporary Breakpoint at Line [line number]	Sets a temporary breakpoint at the mouse pointer.
Go until Line [line number]	Sets a breakpoint and executes until [line number] is reached.
Go to Line [line number]	Branches to a specified line without executing source code between the line at which execution is suspended and the specified line.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.2 Annotation Area Pop-Up Menu

The annotation area is at the left side of the source pane and contains the breakpoint toggles and current location pointer. If you press MB3 while your mouse pointer rests in the annotation area of the source pane, a pop-up menu with the items in Table 2-8 appears.

Table 2-8 Annotation Area Pop-Up Menu

Menu Item	Description
Set/Modify Breakpoints...	Displays a dialog box you can use to activate or deactivate a breakpoint and modify the breakpoint attributes (location, condition, or action).
Toggle Breakpoint at Line [line number]	Activates/deactivates a breakpoint at the mouse pointer.
Temporary Breakpoint at Line [line number]	Sets a temporary breakpoint at the mouse pointer.
Go until Line [line number]	Sets a temporary breakpoint and executes until [line number] is reached.
Go to Line [line number]	Branches to a specified line without executing source code between the line at which execution is suspended and the specified line.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.3 Command Message View Pop-Up Menu

If you press MB3 while your mouse pointer rests in the Command Message View, a pop-up menu with the items in Table 2-9 appears.

Table 2-9 Message Region Pop-Up Menu

Menu Item	Description
Repeat Command [last command]	Reenters your last command.
Clear Command Line	Clears the command line.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.4 Browse Source Pop-Up Menu

If you press MB3 while your mouse pointer rests in the Browse Source dialog box, a pop-up menu with the items in Table 2-10 appears.

Table 2-10 Source Browser Pop-Up Menu

Menu Item	Description
Expand	Expands the selected image or module to include its component modules or functions in the Source Browser display.
Collapse	Collapses an expanded image, module, or function display.
Set Breakpoint	Sets a breakpoint on the selected function.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.5 Breakpoint View Pop-Up Menu

If you position your mouse pointer in the breakpoint list or annotation area of the Breakpoint View and press MB3, a pop-up menu with the items in Table 2-11 appears.

Table 2-11 Breakpoint View Pop-Up Menu

Menu Item	Description
Toggle	Toggles a selected breakpoint.
Set/Modify...	Provides the Set /Modify Breakpoint dialog box, which contains information about a selected breakpoint.
Delete	Deletes a selected breakpoint.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.6 Monitor View and Local Variables View Pop-Up Menu

If you position your mouse pointer in the Monitor View or Local Variables View and press MB3, a pop-up menu with the items in Table 2-12 appears.

Table 2-12 Monitor View and Local Variables View Pop-Up Menu

Menu Item	Description
Monitor	When selected from the Monitor View, this menu item has no effect. When selected from the Local Variables View, inserts the selected expression in the monitor list of the Monitor View.
Expand	Expands a monitored aggregate to show its members.
Collapse	Collapses an expanded aggregate.
Typecast->	Provides the list of type choices for modifying values.
Change Radix- >	Provides the list of radix choices for modifying values.
Next	Steps to the next line by stepping over routine calls.

2.3.7 Register View Pop-Up Menu

If you position your mouse pointer in the Register View and press MB3, a pop-up menu with the items in Table 2-13 appears.

Table 2-13 Register View Pop-Up Menu

Menu Item	Description
Change Radix->	Provides a list of radix choices for modifying values.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.3.8 Instruction View Pop-Up Menu

If you position your mouse pointer in the Instruction View and press MB3, a pop-up menu with the items in Table 2-14 appears.

Table 2-14 Instruction View Pop-Up Menu

Menu Item	Description
Print [selection]	Evaluates the selected text and prints its value in the Command Message View.
Toggle Breakpoint [line number]	Toggles the breakpoint at your mouse pointer location.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

The annotation area of the Instruction View contains the breakpoint toggles. If you press MB3 while your mouse pointer rests in the annotation area of the Instruction View, a pop-up menu with the items in Table 2-15 appears.

Table 2-15 Instruction View Annotation Area Pop-Up Menu

Menu Item	Description
Toggle Breakpoint [address number]	Toggles the breakpoint at your mouse pointer location.
Next	Steps to the next line by stepping over routine calls.
Continue	Resumes execution of the program.

2.4 Entering Commands at the Prompt

The debugger command-entry prompt, (ladebug) is located in the Command Message View. The command-entry prompt:

Echoes the command equivalent for each mouse action you make in the window interface.
Accepts debugger command or internal commands that you choose to enter for the following purposes:
- As an alternative to using the window interface
- Because command functionality has no window interface equivalent

Figure 2-12 shows an example of the run command entered at the prompt.

Figure 2-12 Command Prompt

For more information about bringing a program under debugger control from the prompt, see Section 7.1.2.

When you use the window interface, it translates your input into debugger commands. These commands are echoed in the Command Message View, at the prompt, so that you can correlate your input with the corresponding command line that the debugger processes. Echoed commands are visually indistinguishable from commands that you enter explicitly.

Choose Help:On Commands for online help on debugger commands or type help at the command line. For more information about displaying online help, see Section 2.5.

In addition to entering debugger commands interactively at the prompt, you can:

Recall previously entered commands, using the Up and Down arrow keys.
Execute commands in debugger initialization files and command files for noninteractive execution.
Assign commands to new push buttons you define for the debugger's push-button panel. This option allows you to add debugger features of your choice to the window interface.

See Part V, Command Reference for information about Ladebug engine commands with no exact mouse action equivalent.

2.5 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 (Section 2.5.1)
Command-oriented help-information on debugger commands (Section 2.5.2)

2.5.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 Help:On Context 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 on MB1. Help for that area or object is displayed in a Help window.

To display context-sensitive help for a dialog box, you can also click on the Help button in the dialog box.

2.5.2 Displaying Command-Oriented Help

You can display help about debugger commands using the following methods:

Choose Help:On Commands on the main or optional views window.
Enter help at the command-entry prompt to display common Ladebug commands.