[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

OpenVMS Debugger Manual


Previous Contents Index

7.4.3 Predefined Prompt Display (PROMPT)

The predefined display PROMPT is the display in which the debugger prompts for input. Figure 7-1 and Figure 7-2 show PROMPT in its default location, the bottom sixth of the screen.

By default, PROMPT has the prompt attribute. In addition, PROMPT also has (by default) the program and error attributes, which force program output and diagnostic messages to that display.

PROMPT has different properties and restrictions than other displays. This is to eliminate possible confusion when manipulating that display:

  • The PROMPT display window is always fully visible. You cannot hide PROMPT (with the DISPLAY/HIDE command), remove PROMPT from the pasteboard (with the DISPLAY/REMOVE command), or delete PROMPT (with the CANCEL DISPLAY command).
  • You can assign PROMPT the scroll attribute so that it receives the output of the MOVE and EXPAND commands. However, you cannot scroll through the PROMPT display.
  • The PROMPT display window always occupies the full width of the screen, beginning in the first column.
  • You can move PROMPT vertically anywhere on the screen, expand it to fill the full screen height, or contract it down to two lines.

The debugger alerts you if you try to move or expand a display such that it is hidden by PROMPT.

7.4.4 Predefined Instruction Display (INST)

Note

By default, the predefined instruction display INST is not shown on the screen and does not have the instruction attribute (see Section 7.4.4.1 and Section 7.4.4.2).

Display INST is an automatically updated instruction display. It shows the decoded instruction stream of your program. This is the exact code that is executing, including the effects of any compiler optimization.

A VAX example is shown in Figure 7-3.

This type of display is useful when debugging code that has been optimized. In such cases some of the code being executed might not match the source code that is shown in a source display. See Section 14.1 for information about the effects of optimization.

You can use INST in two basic ways:

  • By default, INST automatically displays the decoded instructions for the routine in which execution is currently paused. This enables you to quickly determine your current debugging context.
  • In addition, if INST has the instruction attribute, you can use it to display the decoded instructions for any part of your program as explained in Section 7.4.4.2.

The name of the routine whose instructions are displayed is shown at the right of the display name, INST. The numbers displayed at the left of the instructions are the compiler-generated source line numbers.

As you execute the program under debugger control, INST is updated automatically whenever execution is paused. The arrow in the leftmost column points to the instruction at which execution is paused. This is the instruction that will be executed next and whose address is the current PC value.

Figure 7-3 Screen Mode Instruction Display (VAX Example)


The built-in command that automatically updates display INST is EXAMINE/INSTRUCTION .%INST_SCOPE\%PC. For information about the EXAMINE/INSTRUCTION command, see Section 4.3.1. The built-in debugger symbol %INST_SCOPE denotes a scope and has the following properties:

  • By default %INST_SCOPE denotes scope 0, which is the scope of the routine where execution is currently paused.
  • If you have reset the scope search list relative to the call stack by means of the SET SCOPE/CURRENT command (see Section 7.4.4.3), %INST_SCOPE denotes the current scope specified (the scope of the routine at the start of the search list).

7.4.4.1 Displaying the Instruction Display

By default, display INST is marked as removed (see Section 7.5.2) from the display pasteboard and is not visible. To show display INST, use one of the following methods:

  • Press KP7 to place displays SRC and INST side by side. This enables you to compare the source code and the decoded instruction stream.
  • Press PF1 KP7 to place displays INST and REG side by side.
  • Enter the DISPLAY INST command to place INST in its default or most recently defined location (see Section 7.5.2).

7.4.4.2 Displaying Instructions in Arbitrary Program Locations

You can use display INST to display decoded instructions throughout your program as follows:

  • You can scroll through the entire instruction display by pressing KP2 (scroll down) or KP8 (scroll up) as explained in Section 7.5.1. This enables you to view any instruction within the routine in which execution is paused.
  • You can display the instruction stream for any routine that is currently on the call stack by using the SET SCOPE/CURRENT command (see Section 7.4.4.3).
  • If INST has the instruction attribute, you can display the instructions for any code location throughout your program by using the EXAMINE/INSTRUCTION command as follows:
    • To assign INST the instruction attribute, use the SELECT/INSTRUCTION INST command (see Section 7.2.2 and Section 7.3). Note that the instruction attribute is automatically assigned to INST when you display it by pressing either KP7 or PF1 KP7.
    • To display the instructions associated with a code location (for example, a routine declaration), use the EXAMINE/INSTRUCTION command (see Section 4.3.1).

    If no display has the instruction attribute, the output of an EXAMINE/INSTRUCTION command is directed at display OUT.

After manipulating the contents of display INST, you can redisplay the location at which execution is currently paused (the default behavior of INST) by pressing KP5.

7.4.4.3 Displaying Instructions for a Routine on the Call Stack

The SET SCOPE/CURRENT command lets you display the instructions for any routine that is currently on the call stack. For example, the following command updates display INST so that it shows the instructions for the caller of the routine in which execution is currently paused:


DBG> SET SCOPE/CURRENT 1

To reset the default scope for displaying instructions, enter the CANCEL SCOPE command. The command causes display INST to show the instructions for the routine at the top of the call stack where execution is paused.

7.4.4.4 Displaying Register Values for a Routine on the Call Stack

The SET SCOPE/CURRENT command lets you display the register values associated with any routine that is currently on the call stack. For example, the following command updates display REG so that it shows the register values for the caller of the routine in which execution is currently paused:


DBG> SET SCOPE/CURRENT 1

To reset the default scope for displaying register values, enter the CANCEL SCOPE command. This command causes display REG to show the register values for the routine at the top of the call stack, where execution is paused.

7.5 Manipulating Existing Displays

This section explains how to perform the following functions:

  • Use the SELECT and SCROLL commands to scroll a display.
  • Use the DISPLAY command to show, hide, or remove a display; the CANCEL DISPLAY command to permanently delete a display; and the SHOW DISPLAY command to identify the displays that currently exist and their order in the display list.
  • Use the MOVE command to move a display across the screen.
  • Use the EXPAND command to expand or contract a display.

Section 7.7 and Section 7.2 discuss more advanced techniques for modifying existing displays with the DISPLAY command---how to change the display window and the type of information displayed.

7.5.1 Scrolling a Display

A display usually has more lines of text (and possibly longer lines) than can be seen through its window. The SCROLL command lets you view text that is hidden beyond a window's border. You can scroll through all displays except for the PROMPT display.

The easiest way to scroll displays is with the keypad keys, described later in this section. Using the relevant commands is explained first.

You can specify a display explicitly with the SCROLL command. Typically, however, you first use the SELECT/SCROLL command to select the current scrolling display. This display then has the scroll attribute and is the default display for the SCROLL command. You then use the SCROLL command with no parameter to scroll that display up or down by a specified number of lines, or to the right or left by a specified number of columns. The direction and distance scrolled are specified with the command qualifiers (/UP:n, /RIGHT:n, and so on).

In the following example, the SELECT command selects display OUT as the current scrolling display (/SCROLL can be omitted because it is the default qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines down:


DBG> SELECT OUT
DBG> SCROLL/DOWN:18

Several useful SELECT and SCROLL command lines are assigned to keypad keys (See Appendix A for a keypad diagram):

  • Pressing KP3 assigns the scroll attribute to the next display in the display list after the current scrolling display. To select a display as the current scrolling display, press KP3 repeatedly until the word "scroll" appears on the top line of that display.
  • Press KP8, KP2, KP6, or KP4 to scroll up, down, right, or left, respectively. The amount of scroll depends on which key state you use (DEFAULT, GOLD, or BLUE).

7.5.2 Showing, Hiding, Removing, and Canceling a Display

The DISPLAY command is the most versatile command for creating and manipulating displays. In its simplest form, the command puts an existing display on top of the pasteboard where it appears through its current window. For example, the following command shows the display INST through its current window:


DBG> DISPLAY INST

Pressing KP9, which is bound to the DISPLAY %NEXTDISP command, enables you to achieve this effect conveniently. The built-in function %NEXTDISP signifies the next display in the display list. (Appendix B identifies all screen-related built-in functions.) Each time you press KP9, the next display in the list is put on top of the pasteboard in its current window.

By default, the top line of display OUT (which identifies the display) coincides with the bottom line of display SRC. If SRC is on top of the pasteboard, its bottom line hides the top line of OUT (keep this in mind when using the DISPLAY command and associated keypad keys to put various displays on top of the pasteboard).

To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE command. This command changes the order of that display in the display list.

To remove a display from the pasteboard so that it is no longer seen (yet is not permanently deleted), use the DISPLAY/REMOVE command. To put a removed display back on the pasteboard, use the DISPLAY command.

To delete a display permanently, use the CANCEL DISPLAY command. To re-create the display, use the DISPLAY command as described in Section 7.6.

Note that you cannot hide, remove, or delete the PROMPT display.

To identify the displays that currently exist, use the SHOW DISPLAY command. They are listed according to their order on the display list. The display that is on top of the pasteboard is listed last.

For more information about the DISPLAY options, see the DISPLAY command. Note that the DISPLAY command accepts optional parameters that let you modify other characteristics of existing displays, namely the display window and the type of information displayed. The techniques are discussed in Section 7.7 and Section 7.2.

7.5.3 Moving a Display Across the Screen

Use the MOVE command to move a display across the screen. The qualifiers /UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of lines or columns by which to move the display. If you do not specify a display, the current scrolling display is moved.

The easiest way to move a display is by using keypad keys:

  • Press KP3 repeatedly as needed to select the current scrolling display.
  • Put the keypad in the MOVE state, then press KP8, KP2, KP4, or KP6 to move the display up, down, left, or right, respectively. See Appendix A.

7.5.4 Expanding or Contracting a Display

Use the EXPAND command to expand or contract a display. The qualifiers /UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of lines or columns by which to expand or contract the display (to contract a display, specify negative integer values with these qualifiers). If you do not specify a display, the current scrolling display is expanded or contracted.

The easiest way to expand or contract a display is to use the keypad keys:

  • Press KP3 repeatedly as needed to select the current scrolling display.
  • Put the keypad in the EXPAND or CONTRACT state, then press KP8, KP2, KP4, or KP6 to expand or contract the display vertically or horizontally. See Appendix A.

The PROMPT display cannot be contracted (or expanded) horizontally. Also, it cannot be contracted vertically to less than two lines.

7.6 Creating a New Display

To create a new screen display, use the DISPLAY command. The basic syntax is as follows:


DISPLAY display-name [AT window-spec] [display-kind] 

The display name can be any name that is not already used to name a display (use the SHOW DISPLAY command to identify all existing displays). A newly created display is placed on top of the pasteboard, on top of any existing displays (except for the predefined PROMPT display, which cannot be hidden). The display name appears at the top left corner of the display window.

Section 7.7 explains the options for specifying windows. If you do not provide a window specification, the display is positioned in the upper or lower half of the screen, alternating between these locations as you create new displays.

Section 7.2 explains the options for specifying display kinds. If you do not specify a display kind, an output display is created.

For example, the following command creates a new output display named OUT2. The window associated with OUT2 is either the top or bottom half of the screen.


DBG> DISPLAY OUT2

The following command creates a new DO display named EXAM_XY that is located in the right third quarter (RQ3) of the screen. This display shows the current value of variables X and Y and is updated whenever the debugger gains control from the program.


DBG> DISPLAY EXAM_XY AT RQ3 DO (EXAMINE X,Y)

For more information, see the DISPLAY command.

7.7 Specifying a Display Window

Display windows can occupy any rectangular portion of the screen.

You can specify a display window when you create a display with the DISPLAY command. You can also change the window currently associated with a display by specifying a new window with the DISPLAY command. When specifying a window, you have the following options:

  • Specify a window in terms of lines and columns.
  • Use the name of a predefined window, such as H1.
  • Use the name of a window definition previously established with the SET WINDOW command.

Each of these techniques is described in the following sections. When specifying windows, keep in mind that the PROMPT display always remains on top of the display pasteboard and, therefore, occludes any part of another display that shares the same region of the screen.

Display windows, regardless of how specified, are dynamic. This means that, if you use a SET TERMINAL command to change the screen height or width, the window associated with a display expands or contracts in proportion to the new screen height or width.

7.7.1 Specifying a Window in Terms of Lines and Columns

The general form of a window specification is (start-line,line-count[,start-column,column-count]). For example, the following command creates the output display CALLS and specifies that its window be 7 lines deep starting at line 10, and 30 columns wide starting at column 50:


DBG> DISPLAY CALLS AT (10,7,50,30)

If you do not specify start-column or column-count, the window occupies the full width of the screen.

7.7.2 Using a Predefined Window

The debugger provides many predefined windows. These have short, symbolic names that you can use in the DISPLAY command instead of having to specify lines and columns. For example, the following command creates the output display ZIP and specifies that its window be RH1 (the top right half of the screen):


DBG> DISPLAY ZIP AT RH1

The SHOW WINDOW command identifies all predefined window definitions as well as those you create with the SET WINDOW command.

7.7.3 Creating a New Window Definition

The predefined windows should be adequate for most situations, but you can also create a new window definition with the SET WINDOW command. This command, which has the following syntax, associates a window name with a window specification:


SET WINDOW window-name AT (start-line,line-count[, 
start-column,column-count]) 

After creating a window definition, you can use its name (like that of a predefined window) in a DISPLAY command. In the following example, the window definition MIDDLE is established. That definition is then used to display OUT through the window MIDDLE.


DBG> SET WINDOW MIDDLE AT (9,4,30,20)
DBG> DISPLAY OUT AT MIDDLE

To identify all current window definitions, use the SHOW WINDOW command. To delete a window definition, use the CANCEL WINDOW command.

7.8 Sample Display Configuration

How to best use screen mode depends on your personal style and on what type of error you are looking for. You might be satisfied to use the predefined displays. If you have access to a larger screen, you might want to create additional displays for various purposes. The following example gives some ideas.

Assume you are debugging in a high-level language and are interested in tracing the execution of your program through several routine calls.

First set up the default screen configuration---that is, SRC in H1, OUT in S45, and PROMPT in S6 (the keypad key sequence PF4 MINUS gives this configuration). SRC shows the source code of the module in which execution is paused.

The following command creates a source display named SRC2 in RH1 that shows the PC value at scope 1 (one level down the call stack, at the call to the routine in which execution is paused):


DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC)

Thus the left half of your screen shows the currently executing routine and the right half shows the caller of that routine.

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.

7.9 Saving Displays and the Screen State

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.


Previous Next Contents Index