Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Debugger Manual


Previous Contents Index

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:

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:

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:

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.

7.10 Changing the Screen Height and Width

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.

7.11 Screen-Related Built-In Symbols

The following built-in symbols are available for specifying displays and screen parameters in language expressions:

7.11.1 Screen Height and Width

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)

7.11.2 Display Built-In Symbols

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.
%CURDISP The current display. This is the display most recently referenced with a DISPLAY command---the least occluded display.
%CURSCROLL The current scrolling display. This is the default display for the SCROLL, MOVE, and EXPAND commands, as well as for the associated keypad keys (KP2, KP4, KP6, and KP8).
%NEXTDISP The next display in the list after the current display. The next display is the display that follows the topmost display. Because the display list is circular, this is the display at the bottom of the pasteboard---the most occluded display.
%NEXTINST The next instruction display in the display list after the current instruction display. The current instruction display is the display that receives the output from the EXAMINE/INSTRUCTION commands.
%NEXTOUTPUT The next output display in the display list after the current output display. An output display receives debugger output that is not already directed to another display.
%NEXTSCROLL The next display in the display list after the current scrolling display.
%NEXTSOURCE The next source display in the display list after the current source display. The current source display is the display that receives the output from the TYPE and EXAMINE/SOURCE commands.

7.12 Screen Dimensions and Predefined Windows

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

Table 7-2 Predefined Windows
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


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4538PRO_016.HTML