![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
The debugger maintains a display list, which is the pasting order of displays. Several keypad key definitions use the display list to cycle through the displays currently on the pasteboard.
Every display belongs to a display kind (see Section 7.2). The display kind determines what type of information the display can capture and display, such as source code, or debugger output. The display kind defines whether displayed data is paged into the memory buffer or discarded when the memory buffer overflows. The display kind also determines how the contents of the display are generated.
The contents of a display are generated in two ways:
The names of any attributes assigned to a display appear to the right of the display name, in lowercase letters. In Figure 7-1, SRC has the source and scroll attributes (SRC is the current source display and the current scrolling display), OUT has the output attribute (it is the current output display), and so on. Note that, although SRC is automatically updated by its own built-in command, it can also receive the output of certain interactive commands (such as EXAMINE/SOURCE) because it has the source attribute.
The concepts introduced in this section are developed in more detail in the rest of this chapter.
Every display has a display kind. The display kind determines the type of information a display contains, how that information is generated, and whether the memory buffer associated with the display is paged.
Typically, you specify a display kind when you use the DISPLAY command to create a new display (if you do not specify a display kind, an output display is created). You can also use the DISPLAY command to change the display kind of an existing display with the following keywords:
The contents of a register display are generated and updated automatically by the debugger. The contents of other kinds of displays are generated by commands, and these display kinds fall into two general groups.
A display that belongs to one of the following display kinds has its contents updated automatically according to the command or command list you supply when defining that display:
The command list specified is executed each time the debugger gains control from your program, if the display is not marked as removed. The output of the commands forms the new contents of the display. If the display is marked as removed, the debugger does not execute the command list until you view that display (marking that display as unremoved).
A display that belongs to one of the following display kinds derives its contents from commands that you enter interactively:
To direct debugger output to a specific display in this group, you must first select it with the SELECT command. The technique is explained in the following sections and in Section 7.3. After a display is selected for a certain type of output, the output from your commands forms the contents of the display.
A DO display is an automatically updated display. The commands in the command list are executed in the order listed each time the debugger gains control from your program. Their output forms the contents of the display and erases any previous contents.
For example, the following command creates the DO display CALLS at window Q3. Each time the debugger gains control from the program, the SHOW CALLS command is executed and the output is displayed in CALLS, replacing any previous contents.
DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS)
The following command creates a DO display named V2_DISP that shows the contents of elements 4 to 7 of the vector register V2 (using Fortran array syntax). The display is automatically updated whenever the debugger gains control from the program:
DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7))
The default size of the memory buffer associated with any DO display is 64 lines. When the memory buffer is full, the oldest lines are discarded to make room for new text. You can use the DISPLAY/SIZE command to change the buffer size.
An instruction display shows the output of an EXAMINE/INSTRUCTION command within the instruction stream of a routine. Because the instructions displayed are decoded from the image being debugged and show the exact code that is executing, this kind of display is particularly useful in helping you debug optimized code (see Section 13.1).
In the display, one line is devoted to each instruction. Source-line numbers corresponding to the instructions are displayed in the left column. The instruction at the location being examined is centered in the display and is marked by an arrow in the left column.
Before anything can be written to an instruction display, you must select it as the current instruction display with the SELECT/INSTRUCTION command.
In the following example, the DISPLAY command creates the instruction display INST2 at RH1. The SELECT/INSTRUCTION command then selects INST2 as the current instruction display. When the EXAMINE/INSTRUCTION X command is executed, window RH1 fills with the instruction stream surrounding the location denoted by X. The arrow points to the instruction at location X, which is centered in the display.
DBG> DISPLAY INST2 AT RH1 INSTRUCTION DBG> SELECT/INSTRUCTION INST2 DBG> EXAMINE/INSTRUCTION X
Each subsequent EXAMINE/INSTRUCTION command updates the display.
The default size of the memory buffer associated with any instruction display is 64 lines; however, you can scroll back and forth to view all the instructions within the routine. You can use the DISPLAY/SIZE command to change the buffer size and improve performance.
This is an instruction display that is automatically updated with the
output of the command specified. That command, which must be an
EXAMINE/INSTRUCTION command, is executed each time the debugger gains
control from your program.
For example, the following command creates the instruction display INST3 at window RS45. Each time the debugger gains control, the built-in command EXAMINE/INSTRUCTION .%INST_SCOPE\%PC is executed, updating the display.
DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST .%INST_SCOPE\%PC)
This command creates a display that functions like the predefined display INST. The built-in EXAMINE/INSTRUCTION command displays the instruction at the current PC value in the current scope (see Section 7.4.4).
If an automatically updated instruction display is selected as the current instruction display, it is updated like a simple instruction display by an interactive EXAMINE/INSTRUCTION command (in addition to being updated by its built-in command).
The default size of the memory buffer associated with any instruction display is 64 lines; however, you can scroll back and forth to view all the instructions within the routine. You can use the DISPLAY/SIZE command to change the buffer size and improve performance.
An output display shows any debugger output that is not directed to another display. New output is appended to the previous contents of the display.
Before anything can be written to an output display, it must be selected as the current output display with the SELECT/OUTPUT command, or as the current error display with the SELECT/ERROR command, or as the current input display with the SELECT/INPUT command. See Section 7.3 for more information about using the SELECT command with output displays.
In the following example, the DISPLAY command creates the output display OUT2 at window T2 (the display kind OUTPUT can be omitted from this example, because it is the default kind). The SELECT/OUTPUT command then selects OUT2 as the current output display. These two commands create a display that functions like the predefined display OUT:
DBG> DISPLAY OUT2 AT T2 OUTPUT DBG> SELECT/OUTPUT OUT2
OUT2 now collects any debugger output that is not directed to another display. For example:
The default size of the memory buffer associated with any output display is 64 lines. When the memory buffer is full, the oldest lines are discarded to make room for new text. You can use the DISPLAY/SIZE command to change the buffer size.
A register display is an automatically updated display that shows the current values, in hexadecimal format, of the processor registers and as many of the top call-stack values as will fit in the display.
The register values displayed are for the routine in which execution is currently paused. The values are updated whenever the debugger takes control. Any changed values are highlighted.
On VAX processors, the predefined display REG contains, in hexadecimal format, general-purpose registers R0 to R15 and the PSL, but does not contain the vector registers. To display data contained in vector registers or vector control registers in screen mode, use a DO display (see Section 7.2.1).
On VAX processors, the predefined display IREG contains the same information as the predefined display REG, but the display window is configured differently. Display IREG is included in the VAX implementation to allow debugger .COM and .INI files to be ported more easily between VAX and Alpha debugging applications.
On Alpha processors, the predefined display REG contains, in hexadecimal format, general-purpose registers R0 to R28, FP (R29), SP (R30), R31, PC, PS floating-point registers F0 to F31, FPCR, SFPCR, and as many of the top call-stack values as will fit in the display.
On Alpha processors, the predefined display IREG contains, in hexadecimal format, general-purpose registers R0 to R28, FP, and as many of the top call-stack values as can be displayed in the window.
On Alpha processors, the predefined display FREG contains floating-point registers F0 to F31, FPCR, SFPCR, displayed in floating-point format and as many of the top call-stack values (in hexadecimal format) as can be displayed in the window.
The default size of the memory buffer associated with any register display is 64 lines. When the memory buffer is full, the oldest lines are discarded to make room for new text. You can use the DISPLAY/SIZE command to change the buffer size.
A source display shows the output of a TYPE or EXAMINE/SOURCE command within the source code of a module, if that source code is available. Source line numbers are displayed in the left column. The source line that is the output of the command is centered in the display and is marked by an arrow in the left column. If a range of lines is specified with the TYPE command, the lines are centered in the display, but no arrow is shown.
Before anything can be written to a source display, you must select it as the current source display with the SELECT/SOURCE command.
In the following example, the DISPLAY command creates source display SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 as the current source display. When the TYPE 34 command is executed, window RH1 fills with the source code surrounding line 34 of the module being debugged. The arrow points to line 34, centered in the display.
DBG> DISPLAY SRC2 AT Q2 SOURCE DBG> SELECT/SOURCE SRC2 DBG> TYPE 34
Each subsequent TYPE or EXAMINE/SOURCE command updates the display.
The default size of the memory buffer of a source display is 64 lines. The memory buffer of a source display is paged, enabling you to can scroll back and forth through the entire source module or routine. You can use the DISPLAY/SIZE command to change the buffer size to improve performance.
This is a source display that is automatically updated with the output of the command specified. That command, which must be an EXAMINE/SOURCE or TYPE command, is executed each time the debugger gains control from your program.
For example, the following command creates source display SRC3 at window RS45. Each time the debugger gains control, it executes the built-in command EXAMINE/SOURCE .%SOURCE_SCOPE\%PC and updates the display.
DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .%SOURCE_SCOPE\%PC)
This command creates a display that functions like the predefined display SRC. The built-in EXAMINE/SOURCE command displays the source line for the current PC value in the current scope (see Section 7.4.1).
If you select an automatically updated source display as the current
source display, it displays the output generated by an interactive
EXAMINE/SOURCE or TYPE command in addition to the output generated by
its built-in command.
The default size of the memory buffer of a source display is 64 lines. The memory buffer of an automatically updated source display is paged, enabling you to scroll back and forth through the entire source module or routine. You can use the DISPLAY/SIZE command to change the buffer size to improve performance.
A program display can receive the output of the program being debugged. The predefined PROMPT display belongs to the program display kind, and is the only display permitted of that kind. You cannot create a new display of the program display kind.
To avoid possible confusion, the PROMPT display has several restrictions (see Section 7.4.3).
In screen mode, the output from commands you enter interactively is directed to various displays according to the type of output and the display attributes assigned to these displays. For example, debugger diagnostic messages go to the display that has the error attribute (the current error display). By assigning one or more attributes to a display, you can mix or isolate different kinds of information.
The attributes have the following names:
When a display is assigned an attribute, the name of that attribute appears in lowercase letters on the top border of its window to the right of the display name. Note that the scroll attribute does not affect debugger output but is used to control the default display for the SCROLL, MOVE, and EXPAND commands.
By default, attributes are assigned to the predefined displays as follows:
To assign an attribute to a display, use the SELECT command with the qualifier of the same name as the attribute. In the following example, the DISPLAY command creates the output display ZIP. The SELECT/OUTPUT command then selects ZIP as the current output display---the display that has the output attribute. After this command is executed, the word "output" disappears from the top border of the predefined output display OUT and appears instead on display ZIP, and all the debugger output formerly directed to OUT is now directed to ZIP.
DBG> DISPLAY ZIP OUTPUT DBG> SELECT/OUTPUT ZIP
You can assign specific attributes only to certain display kinds. The following list identifies each of the SELECT command qualifiers, its effect, and the display kinds to which you can assign that attribute:
Subject to the restrictions listed, a display can have several attributes. In the preceding example, ZIP was selected as the current output display. In the next example, ZIP is further selected as the current input, error, and scrolling display. After these commands are executed, debugger input, output, and diagnostics are logged in ZIP in the proper sequence as they occur, and ZIP is the current scrolling display.
DBG> SELECT/INPUT/ERROR/SCROLL ZIP
To identify the displays currently selected for each of the display attributes, use the SHOW SELECT command.
If you use the SELECT command with a particular qualifier but without specifying a display name, the effect is typically to deassign that attribute (to unselect the display that had the attribute). The exact effect depends on the attribute, as described in the preceding table.
The debugger provides the following predefined displays that you can use to capture and display different kinds of data:
When you enter screen mode, the debugger puts SRC in the top half of the screen, PROMPT in the bottom sixth, and OUT between SRC and PROMPT, as shown in Figure 7-1. Displays INST, REG, FREG (Alpha only), and IREG are initially removed from the screen by default.
To re-create this default configuration, press BLUE MINUS on the keypad (PF4 followed by the MINUS (--) key).
The basic features of the predefined displays are described in the next sections. As explained in other parts of this chapter, you can change certain characteristics of these displays, such as the buffer size or display attributes. You can also create additional displays similar to the predefined displays.
To display summary information about the characteristics of any display, use the SHOW DISPLAY command.
Table 7-1 summarizes key information about the predefined displays.
| Display Name | Display Kind | Valid Display Attributes | Visible on Startup |
|---|---|---|---|
| SRC | Source |
Scroll
Source (By Default) |
X |
| OUT | Output |
Error
Input Output (By Default) Scroll |
X |
| PROMPT | Output |
Error (By Default)
Output Program (By Default) Prompt (By Default) Scroll ¹ |
X |
| INST | Instruction |
Instruction
Scroll |
|
| REG | Register | Scroll | |
| FREG (Alpha only) | Register | Scroll | |
| IREG | Register | Scroll |
Note
See Chapter 6 for information about how to make source code available for display during a debugging session.
The predefined display SRC (see Figure 7-1) is an automatically updated source display.
You can use SRC to display source code in two basic ways:
The name of the module whose source code is displayed is shown at the right of the display name, SRC. The numbers displayed at the left of the source code are the compiler-generated line numbers, as they might appear in a compiler-generated listing file.
As you execute the program under debugger control, SRC is automatically updated whenever execution is paused. The arrow in the leftmost column indicates the source line to be executed next. Specifically, execution is paused at the first instruction associated with that source line. Thus, the line indicated by the arrow corresponds to the current program counter (PC) value. The PC is a register that contains the memory address of the next instruction to be executed.
If the debugger cannot locate source code for the routine in which execution is paused (because, for example, the routine is a run-time library routine), it tries to display source code in the next routine down on the call stack for which source code is available. When displaying source code for such a routine, the debugger issues the following message:
%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC.
Displaying source in a caller of the current routine.
Figure 7-2 shows this feature. The source display shows that a call to routine TYPE is currently active. TYPE corresponds to a Fortran run-time library procedure. No source code is available for that routine, so the debugger displays the source code of the calling routine. The output of a SHOW CALLS command, shown in the output display, identifies the routine where execution is paused and the call sequence leading to that routine.
In such cases, the arrow in the source window identifies the line to which execution returns after the routine call. Depending on the source language and coding style, this might be the line that contains the call statement or the next line.
Figure 7-2 Screen Mode Source Display When Source Code Is Not Available
If your program was optimized during compilation, the source code displayed in SRC might not always represent the code that is actually executing. The predefined instruction display INST is useful in such cases, because it shows the exact instructions that are executing (see Section 7.4.4).
4538P011.HTM OSSG Documentation 22-NOV-1996 13:01:46.43
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.