![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
The following command creates a DO display named CALLS at S4 that executes the SHOW CALLS command each time the debugger gains control from the program:
DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS)
Because the top half of OUT is now hidden by CALLS, make OUT's window smaller as follows:
DBG> DISPLAY OUT AT S5
You can create a similar display configuration with instruction displays instead of source displays.
The SAVE command enables you to make a snapshot of an existing display and save that copy as a new display. This is useful if, for example, you later want to refer to the current contents of an automatically updated display (such as a DO display).
In the following example, the SAVE command saves the current contents of display CALLS into display CALLS4, which is created by the command:
DBG> SAVE CALLS AS CALLS4
The new display is removed from the pasteboard. To view its contents, use the DISPLAY command:
DBG> DISPLAY CALLS4
The EXTRACT command has two uses. First, it enables you to save the contents of a display in a text file. For example, the following command extracts the contents of display CALLS, appending the resulting text to the file COB34.TXT:
DBG> EXTRACT/APPEND CALLS COB34
Second, the EXTRACT/SCREEN_LAYOUT command enables you to create a command procedure that can later be executed during a debugging session to re-create the previous state of the screen. In the following example, the EXTRACT/SCREEN_LAYOUT command creates a command procedure with the default specification SYS$DISK:[]DBGSCREEN.COM. The file contains all the commands needed to re-create the current state of the screen.
DBG> EXTRACT/SCREEN_LAYOUT . . . DBG> @DBGSCREEN
Note that you cannot save the PROMPT display as another display, or extract it into a file.
During a debugging session, you can change the height or width of your terminal screen. One reason might be to accommodate long lines that would wrap if displayed across 80 columns. Or, if you are at a workstation, you might want to reformat your debugger window relative to other windows.
To change the screen height or width, use the SET TERMINAL command. The general effect of the command is the same whether you are at a VT-series terminal or at a workstation.
In this example, assume you are using a workstation window in its default emulated VT100-screen mode, with a screen size of 24 lines by 80 columns. You have started the debugger and are using it in screen mode. You now want to take advantage of the larger screen. The following command increases the screen height and width of the debugger window to 35 lines and 110 columns respectively:
DBG> SET TERMINAL/PAGE:35/WIDTH:110
By default, all displays are dynamic. A dynamic display automatically adjusts its window dimensions in proportion when a SET TERMINAL command changes the screen height or width. This means that, when using the SET TERMINAL command, you preserve the relative positions of your displays. The /[NO]DYNAMIC qualifier on the DISPLAY command lets you control whether or not a display is dynamic. If a display is not dynamic, it does not change its window coordinates after you enter a SET TERMINAL command (you can then use the DISPLAY, MOVE, or EXPAND commands, or various keypad key combinations, to move or resize a display).
To see the current terminal width and height being used by the debugger, use the SHOW TERMINAL command.
Note that the debugger's SET TERMINAL command does not affect the terminal screen size at DCL level. When you exit the debugger, the original screen size is maintained.
The following built-in symbols are available for specifying displays and screen parameters in language expressions:
The built-in symbols %PAGE and %WIDTH return, respectively, the current height and width of the terminal screen. These symbols can be used in various expressions, such as for window specifications. For example, the following command defines a window named MIDDLE that occupies a region around the middle of the screen:
DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2,%WIDTH/4,%WIDTH/2)
Each time you refer to a specific display with a DISPLAY command, the display list is updated and reordered, if necessary. The most recently referenced display is put at the tail of the display list, because that display is pasted last on the pasteboard (you can identify the display list by entering a SHOW DISPLAY command).
You can use display built-in symbols to specify displays relative to their positions in the display list. These symbols, listed as follows, enable you to refer to displays by their relative positions in the list instead of by their explicit names. The symbols are used mainly in keypad key definitions or command procedures.
Display symbols treat the display list as a circular list. Therefore, you can enter commands that use display symbols to cycle through the display list until you reach the display you want.
On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. On a workstation, the screen is larger in both height and width. The debugger can accommodate screen sizes up to 100 lines by 255 columns.
The debugger has many predefined windows that you can use to position displays on the screen. In addition to the full height and width of the screen, the predefined windows include all possible regions that result from:
The SHOW WINDOW command identifies all predefined display windows.
The following conventions apply to the names of predefined windows. The prefixes L and R denote left and right windows, respectively. Other letters denote the full screen (FS) or fractions of the screen height (H: half, T: third, Q: quarter, S: sixth, E: eighth). The trailing numbers denote specific segments of the screen height, starting from the top. For example:
The following four commands create displays that have windows identical in size and location (the top half of the screen):
DBG> DISPLAY XYZ AT H1 SOURCE DBG> DISPLAY XYZ AT Q12 SOURCE DBG> DISPLAY XYZ AT S123 SOURCE DBG> DISPLAY XYZ AT E1234 SOURCE
The horizontal boundaries (start-column, column-count) of the predefined windows for the default terminal screen width of 80 columns are as follows:
Table 7-2 lists the vertical boundaries (start-line, line-count) of single-segment display windows predefined for the default terminal screen height of 24 lines. Table 7-2 does not list windows that consist of multiple segments such as E23 (a display window created from the combination of display windows E2 and E3).
| Window Name | Start-line,Line-count | Window Location |
|---|---|---|
| FS | (1,23) | Full screen |
| H1 | (1,11) | Top half |
| H2 | (13,11) | Bottom half |
| T1 | (1,7) | Top third |
| T2 | (9,7) | Middle third |
| T3 | (17,7) | Bottom third |
| Q1 | (1,5) | Top quarter |
| Q2 | (7,5) | Second quarter |
| Q3 | (13,5) | Third quarter |
| Q4 | (19,5) | Bottom quarter |
| S1 | (1,3) | Top sixth |
| S2 | (5,3) | Second sixth |
| S3 | (9,3) | Third sixth |
| S4 | (13,3) | Fourth sixth |
| S5 | (17,3) | Fifth sixth |
| S6 | (21,3) | Bottom sixth |
| E1 | (1,2) | Top eighth |
| E2 | (4,2) | Second eighth |
| E3 | (7,2) | Third eighth |
| E4 | (10,2) | Fourth eighth |
| E5 | (13,2) | Fifth eighth |
| E6 | (16,2) | Sixth eighth |
| E7 | (19,2) | Seventh eighth |
| E8 | (22,2) | Bottom eighth |
You can enable country-specific features for screen mode by defining logical names, as follows:
$ DEFINE/JOB DBG$SMGSHR <name_of_Asian_SMG>
This part describes the debugger's DECwindows Motif interface.
For information about the debugger's command interface, see Part 2.
This chapter introduces the debugger's DECwindows Motif interface. For information about the command interface, see Part 2.
Note
The DECwindows Motif interface to the OpenVMS Debugger Version 7.1 or later requires Version 1.2 or later of DECwindows Motif.
This chapter provides the following information:
For information about starting a debugging session, see Chapter 9. For information about using the debugger, see Chapter 10. For the source code of program EIGHTQUEENS.EXE, shown in the figures of this chapter, see Appendix D.
The OpenVMS Debugger has a DECwindows Motif graphical user interface (GUI) for workstations. This interface is an enhancement to the screen-mode command interface that accepts mouse input to choose items from menus and to activate or deactivate push buttons, to drag the pointer to select text in windows, and so on. The debugger's DECwindows Motif GUI menus and push buttons provide the functions for most basic debugging tasks.
The DECwindows Motif GUI is layered on the character-cell command interface and has a command-entry prompt on the command line (in the command view). From the DECwindows Motif GUI command line, you can enter debugger commands for the following purposes:
You can customize the DECwindows Motif GUI to associate other debugger commands with new or existing push buttons.
Notes
The DECwindows Motif GUI does not recognize the HELP command at its command-entry prompt. Choose the On Commands item in the Help menu for online help on debugger commands.You cannot use the DECwindows Motif GUI to debug detached processes such as print symbionts that run without a command line interpreter (CLI). See Section 1.11 for details about debugging detached processes that do not have a CLI.
The following paragraphs highlight some of the convenience features of the debugger's default DECwindows Motif interface. Section 8.2 gives visual details. (Convenience features of the debugger's command interface are described in detail in Section 1.1.2.)
Source-Code Display
The OpenVMS Debugger is a source-level debugger. The debugger displays in the source view the source code that surrounds the instruction where program execution is paused currently. You can enable and disable the display of compiler-generated line numbers.
A source browser lets you:
Call-Stack Navigation
The call-stack menu on the main window lists the sequence of routine calls currently on the call stack. Click on a routine name in the call-stack menu to set (to that routine) the context (scope) for
Breakpoints
You set, activate, and deactivate breakpoints by clicking on buttons next to the source lines in the source view or the instruction view. Optionally, you can set, deactivate, or activate breakpoints by selecting items in window pull-down menus, pop-up menus, context-sensitive menus, or dialog boxes. You can set conditional breakpoints, which suspend program execution if the specified condition is true. You can set action breakpoints, which execute one or more debugger commands when the breakpoint suspends program execution. The main window push buttons, the instruction view push buttons, and the breakpoint view give a visual indication of activated, deactivated, and conditional breakpoints.
Push Buttons
Push buttons in the push button view control common operations: by clicking on a push 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 push buttons and the associated debugger commands.
Context-Sensitive Pop-Up Menus
Context-sensitive pop-up menus list common operations associated with your view (source view, command view, and so on.) When you click MB3, the pop-up menu lists actions for the text you have selected, the source line at which you are pointing, or the view in which you are working.
Displaying and Manipulating Data
To display the value of a variable or expression, select the variable or expression in the source view and click on a push button, such as EVAL (evaluate expression) or EX (examine variable). You can also display selected values by choosing items from window pull-down menus (such as Examine, in the Commands pull-down menu), context-sensitive menus, or dialog boxes. You can display values in different type or radix formats.
To change the value of a variable, edit the currently displayed value in the monitor view. You can also change values by selecting items in window pull-down menus (such as Deposit, in the Commands pull-down menu), context-sensitive pop-up menus, or dialog boxes.
The monitor view displays the updated values of specified variables whenever the debugger regains control from your program.
Kept Debugger RERUN Command
You can run the debugger in a state known as the kept debugger from which you can rerun the same program or run another program without exiting the debugger. When rerunning a program, you can choose to save the current state of breakpoints, tracepoints, and static watchpoints. The kept debugger is also available in the screen mode debugger. See Section 9.1 for information on starting the kept debugger.
Instruction and Register Views
The instruction view shows the decoded instruction stream (the code that is actually executing) of your program. This view is useful if the program you are debugging has been optimized by the compiler, in which case the source code in the source view may not reflect the code that is executing. You can set breakpoints on instructions and display the memory addresses and source-code line numbers associated with each instruction.
The register view displays the current contents of all machine registers. You can edit the displayed values to deposit other values into the registers.
Two Wait Cursors
The debugger has two different wait cursors to indicate wait states. One wait cursor is the standard clock cursor. This cursor indicates that the debugger is performing an action as a result of a user command.
The second wait cursor is a spider. This cursor indicates that the program being debugged is executing.
Tasking Program Support
The tasking view displays information about the current state of all tasks of a tasking program (also called a multithread program). You can modify task characteristics to control task execution, priority, state transitions, and so on.
Integration with Command Interface
The debugger's DECwindows Motif GUI is an enhancement to the character-cell debugger. It is layered on, and closely integrated with, the command-driven character-cell debugger:
Integration with Source-Level Editor
You can edit program source code without exiting from the debugger. In the editor view, you can display the source code, search and replace text, or add additional text. Editor view text buffers allow you to move quickly back and forth between new or existing files, and copy, cut, and paste text from buffer to buffer.
The text editor available through the debugger's DECwindows Motif menu interface is a simple convenience feature, not intended to replace sophisticated text editors such as the Language-Sensitive Editor (LSE). To use a different editor, enter the Edit command at the DBG> prompt in the command view (see the EDIT command).
Customization
You can modify the following and other aspects of the debugger's DECwindows Motif interface and save the current settings in a resource file to customize your debugger startup environment:
Online Help
Online help is available for the debugger's DECwindows Motif interface (context-sensitive help) and for its command interface.
The following sections describe the debugger windows, menus, views, and other features of the OpenVMS Debugger DECwindows Motif interface.
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 Default Window Configuration
The main window (see Figure 8-1) includes:
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.
The source view shows the following:
For more information about displaying source code, see Section 8.2.2.3 and Section 10.1.
Figure 8-2 and Table 8-1 describe the menus on the main window.
Figure 8-2 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. | |
| Display Line Numbers | Display or hide line numbers in the source view. | |
| Exit Debugger | 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:
|
| 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 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. |
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).
Figure 8-3 and Table 8-2 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
| 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. |
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:
4538P013.HTM OSSG Documentation 22-NOV-1996 13:01:49.66
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.