HP OpenVMS Systems Documentation

Content starts here

OpenVMS Debugger Manual

Previous Contents Index

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:


The new display is removed from the pasteboard. To view its contents, use the DISPLAY command:


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:


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.


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:


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:

  • %SOURCE_SCOPE---To display source code. %SOURCE_SCOPE is described in Section 7.4.1.
  • %INST_SCOPE---To display instructions. %INST_SCOPE is described in Section 7.4.4.
  • %PAGE, %WIDTH---To specify the current screen height and width.
  • %CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE---To specify displays in the display list.

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:


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:

  • Dividing the screen vertically into equal fractions: halves, thirds, quarters, sixths, or eighths
  • Combining vertically contiguous equal fractions: halves, thirds, quarters, sixths, or eighths
  • Dividing the vertical fractions into left and right halves

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:

  • Windows T1, T2, and T3 occupy the top, middle, and bottom thirds of the screen, respectively.
  • Window RH2 occupies the right bottom half of the screen.
  • Window LQ23 occupies the left middle two quarters of the screen.
  • Window S45 occupies the fourth and fifth sixths of the screen.

The following four commands create displays that have windows identical in size and location (the top half of the screen):


The horizontal boundaries (start-column, column-count) of the predefined windows for the default terminal screen width of 80 columns are as follows:

  • Left-hand windows: (1,40)
  • Right-hand windows: (42,39)

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

7.13 Internationalization of Screen Mode

You can enable country-specific features for screen mode by defining logical names, as follows:

  • DBG$SMGSHR --- For specifying the Screen Management (SMG) shareable image. The debugger uses the SMG shareable image in its implementation of screen mode. Asian variants of the SMG shareable image handle multibyte characters. Hence, if an Asian variant of SMG is used by the debugger, the screen mode interface to the debugger will be able to display and manipulate multibyte characters.
    Define the DBG$SMGSHR logical name as follows:

    $  DEFINE/JOB DBG$SMGSHR <name_of_Asian_SMG>

    where <name_of_Asian_SMG> varies according to the variants of Asian OpenVMS. For example, the name of the Asian SMG in Japanese OpenVMS is JSY$SMGSHR.EXE.
  • SMG$DEFAULT_CHARACTER_SET --- For the Asian SMG and multibyte characters. This logical need only be defined if DBG$SMGSHR has been defined. See the documentation on Asian or Japanese screen management routines for details on how to define this logical name.

Part 3
DECwindows Interface

This part describes the Compaq DECwindows Motif for OpenVMS user interface of the debugger.

For information about the debugger's command interface, see Part 2.

Chapter 8

This chapter introduces the Compaq DECwindows Motif for OpenVMS user interface of the debugger. For information about the command interface, see Part 2.


The Compaq DECwindows Motif for OpenVMS user interface to the OpenVMS Debugger Version 7.1 or later requires Version 1.2 or later of Compaq DECwindows Motif for OpenVMS.

This chapter provides the following information:

  • A functional overview of the OpenVMS Debugger, including its user interface options---Compaq DECwindows Motif for OpenVMS and command ( Section 8.1)
  • An orientation to the debugger's Compaq DECwindows Motif for OpenVMS screen features, such as windows, menus, and so on ( Section 8.2)
  • Instructions for entering debugger commands at the command-entry prompt ( Section 8.3)
  • Instructions for accessing online help ( Section 8.4)

For information about starting a debugging session, see Chapter 9. For detailed information about using the Motif interface for debugging, see Chapter 10. For the source code of program EIGHTQUEENS.EXE, shown in the figures of this chapter, see Appendix D.

8.1 Introduction

The OpenVMS Debugger has a Compaq DECwindows Motif for OpenVMS graphical user interface (GUI) for workstations. This enhancement to the screen-mode command interface 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 Compaq DECwindows Motif for OpenVMS GUI menus and push buttons provide the functions for most basic debugging tasks.

The Compaq DECwindows Motif for OpenVMS 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 Compaq DECwindows Motif for OpenVMS GUI command line, you can enter debugger commands for the following purposes:

  • To perform certain operations by using the Compaq DECwindows Motif for OpenVMS user interface menus and push buttons for certain operations
  • To do debugging tasks not available through the Compaq DECwindows Motif for OpenVMS GUI menus and push buttons

You can customize the Compaq DECwindows Motif for OpenVMS GUI to associate other debugger commands with new or existing push buttons.

You can run the Compaq DECwindows Motif for OpenVMS GUI in local mode or in client/server mode. Client/server mode allows you to debug programs remotely from another OpenVMS node. The user interface in both Motif modes is virtually identical. Chapter 9 describes how to start interfaces.


The Compaq DECwindows Motif for OpenVMS 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 Compaq DECwindows Motif for OpenVMS 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.

8.1.1 Convenience Features

The following paragraphs highlight some of the convenience features of the debugger's default Compaq DECwindows Motif for OpenVMS 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:

  • List the images, modules, and routines of your program
  • Display source code from selected modules or routines
  • Display the underlying hierarchy of modules and routines
  • Set breakpoints by double-clicking on selected routines

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

  • Source code display (in the source view)
  • Register display (in the register view)
  • Instruction display (in the instruction view)
  • Symbol searches


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.

Client/Server Configuration

You can run the debugger in a client/server configuration, which allows you to debug programs that run on an OpenVMS node remotely from another OpenVMS node using the Compaq DECwindows Motif for OpenVMS interface, or from a PC using the Microsoft Windows interface. Up to 31 debug clients can simultaneously access the same debug server, which allows many debugging options.

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.

Debugger Status Indicator

The debugger has a status indicator to identify the state of the debugger, which can be one of the following:

  • D---the program being debugged is running
  • U---the Debugger is executing a user command

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 Compaq DECwindows Motif for OpenVMS GUI is an enhancement to the character-cell debugger. It is layered on, and closely integrated with, the command-driven character-cell debugger:

  • When you use the Compaq DECwindows Motif for OpenVMS GUI menus and push buttons, the debugger echoes your commands in the command view to provide a record of your actions.
  • When you enter commands at the prompt, the debugger updates the Compaq DECwindows Motif for OpenVMS views accordingly.

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 Compaq DECwindows Motif for OpenVMS 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).


You can modify the following and other aspects of the debugger's Compaq DECwindows Motif for OpenVMS 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 order, labels, and associated debugger commands (this includes adding and removing push buttons)
  • Character fonts for displayed text

Online Help

Online help is available for the debugger's Compaq DECwindows Motif for OpenVMS interface (context-sensitive help) and for its command interface.

Previous Next Contents Index