HP OpenVMS Systems Documentation

HP OpenVMS Debugger Manual

By default, if your workstation is running HP DECwindows Motif for OpenVMS, the debugger starts up in the HP DECwindows Motif for OpenVMS user interface, which is displayed on the workstation specified by the HP DECwindows Motif for OpenVMS applicationwide logical name DECW$DISPLAY. DECW$DISPLAY is defined in the job table by FileView or DECterm and points to the display device for the workstation.

For information about DECW$DISPLAY, see the description of the DCL commands SET DISPLAY and SHOW DISPLAY in the HP OpenVMS DCL Dictionary.

The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent of DECW$DISPLAY. DBG$DECW$DISPLAY is similar to the debugger-specific logical names DBG$INPUT and DBG$OUTPUT. These logical names enable you to reassign SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on which debugger input and output are to appear.

The default user interface of the debugger results when DBG$DECW$DISPLAY is undefined or has the same translation as DECW$DISPLAY. By default, DBG$DECW$DISPLAY is undefined.

The algorithm that the debugger follows when using the logical definitions of DECW$DISPLAY and DBG$DECW$DISPLAY is as follows:

1. If the logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise, use the logical name DECW$DISPLAY.
2. Translate the logical name. If its value is not null (if the string contains characters other than spaces), the HP DECwindows Motif for OpenVMS user interface is displayed on the specified workstation. If the value is null (if the string consists only of spaces), the command interface is displayed in the DECterm window.

To enable the OpenVMS Debugger to start up in the HP DECwindows Motif for OpenVMS user interface, first enter one of the following DCL commands:

$DEFINE DBG$DECW$DISPLAY "WSNAME::0"

$SET DISPLAY/CREATE/NODE=WSNAME

where WSNAME is the nodename of your workstation.

9.9 Starting the Motif Debug Client

The debugger client/server retains the functionality of the kept debugger, but splits the debugger into two components: the debug server and the debug client. The debug server runs on an OpenVMS system, and is just like the kept debugger without the user interface. The debug client contains the user interface, and runs on an OpenVMS system using HP DECwindows Motif for OpenVMS, or on a PC running Microsoft Windows 95 or Microsoft Windows NT.

9.9.1 Software Requirements

The debug server requires OpenVMS Version 7.2 or later.

The debug client can run on any of the following:

• OpenVMS Version 7.2 or later, along with HP DECwindows Motif for OpenVMS Version 1.2-4
• Microsoft Windows 95
• Microsoft Windows NT Version 3.51 or later (Intel or Alpha)

The OpenVMS Debugger client/server configuration also requires that the following be installed on the OpenVMS node running the server:

• A TCP/IP stack
• DCE RPC

You can start the debug server after logging in directly to the OpenVMS system, or you may find it more convenient to log in remotely with a product such as eXcursion, or an emulator such as Telnet.

To start the debug server, enter the following command:

$ DEBUG/SERVER

The server displays its network binding strings. The server port number is enclosed in square brackets ([]). For example:

$ DEBUG/SERVER

%DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: YES
%DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.138[1034]
%DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001]
%DEBUG-I-WATCH: Network Binding: ncadg_ip_udp:16.32.16.138[1045]
%DEBUG-I-AWAIT: Ready for client connection...

Use one of the network binding strings to identify this server when you connect from the client (see Section 9.9.4). The following table matches the network binding string prefix with its associated network transport:

The following example contains an error message that indicates that DCE is not installed:

$ debug/server
%LIB-E-ACTIMAGE, error activating image disk:[SYSn.SYSCOMMON.][SYSLIB]DTSS$SHR.EXE;
-RMS-E-FNF, file not found

This indicates that DCE is installed but not configured.

9.9.3 Primary Clients and Secondary Clients

The debugger client/server interface allows more than one client to be connected to the same server. This allows team debugging, classroom sessions, and other applications.

The primary client is the first client to connect to the server. A secondary client is an additional client that has connected to the same server. The primary client controls whether or not any secondary clients can connect to the server.

Section 9.9.4 describes how to specify the number of secondary clients allowed in a session.

9.9.4 Starting the Motif Client

A session is the connection between a particular client and a particular server. Each session is identified within the client by the network binding string the client used to connect to the server. Once the debug server is running, start the Motif debug client. To do so, enter the following command:

$ DEBUG/CLIENT

To establish a session from the Motif debug client, click on Server Connection from the File menu. The Server Connection dialog displays, in the Connection list, the default network binding string. This string is based on the last string you entered, or the node on which the client is running. There is not necessarily a server associated with the default binding string. Figure 9-6 shows the Server Connection dialog.

Figure 9-6 Debug Server Connection Dialog

From the buttons at the bottom of the Server Connection dialog, you can

• Connect to the selected server to begin and activate a new session
• Disconnect from a session
• Test whether the session is still available
• Stop the server
• Cancel the connection operation and dismiss the dialog

In addition, the Options button invokes the Server Options dialog, which allows you to select the network transport to be used (see Section 11.5.1).

The Server Options dialog also allows you to select the number of secondary clients (0-31) allowed for a new session.

Figure 9-7 shows the Server Options dialog.

Figure 9-7 Server Options Dialog

To connect the client to a server, perform the following steps:

1. Open the File menu.
2. Click Server Connection.
3. Enter the server network binding string in the Connection field, or select the default string.
4. Click Options.
5. In the Server Options dialog, click on the network transport: TCP/IP, DECnet, or UDP.
6. In the Server Options dialog. select the number of secondary clients (0-31) to be allowed.
7. Click OK to dismiss the Server Options dialog.
8. In the Server Connection dialog, click Connect.

You can establish connections to an unlimited number of servers by repeating the sequence above and specifying the new network binding string each time.

9.9.5 Switching Between Sessions

Each time you connect to a server and initiate a session, the session is listed in the Active Sessions list in the Server Connection dialog (see Figure 9-8). You can switch back and forth between sessions. Each time you switch to a new session, the debugger updates the contents of any open debugger displays with the new context.

To switch to a different session, perform the following steps:

1. Open the File menu.
2. Click Server Connection.
3. Click the Active Sessions list to display the list of active sessions.
4. Double click the required session in the Active Sessions list. This selects the session as the current session, dismisses the Server Connection dialog, and updates the debugger displays with the current context.

Note that you cannot change the number of secondary clients allowed on a session while that session is active. To change the number of clients allowed on a session, you must be the primary client, and perform the following steps:

1. Open the File menu.
2. Specify the network binding string of the session.
3. Click Disconnect.
4. Click Options.
5. In the Server Options dialog, click on the network transport: TCP/IP, DECnet, or UDP.
6. In the Server Options dialog, select the number of secondary clients (0-31) to be allowed.
7. Click OK to dismiss the Server Options dialog.
8. In the Server Connection dialog, click Connect.

Figure 9-8 Active Sessions List

Click on Exit Debug? on the File menu to invoke the Confirm Exit dialog. Figure 9-9 shows the Confirm Exit dialog.

Figure 9-9 Confirm Exit Dialog

Once you have invoked the Confirm Exit dialog, perform one of the following:

• To terminate both the client and the server (default) click OK.
• To dismiss the Confirm Exit dialog without taking any action, click Cancel.
• To terminate only the debug client, perform the following steps:
  1. Click Exit Server.
  2. Click OK.
• To terminate only the debug server, perform the following steps:
  1. Click Exit Client.
  2. Click OK.

If you do not terminate the debug server, you can connect to the server from another debug client. If you do not terminate the client, you can connect to another server for which you know the network binding string.

This chapter explains how to:

• Display the source code of your program ( Section 10.1)
• Edit your program under debugger control ( Section 10.2)
• Execute your program under debugger control ( Section 10.3)
• Suspend execution with breakpoints ( Section 10.4)
• Examine and manipulate program variables ( Section 10.5)
• Access program variables ( Section 10.6)
• Display and modify values stored in registers ( Section 10.7)
• Display the decoded instruction stream of your program ( Section 10.8)
• Debug tasking programs ( Section 10.9)
• Customize the debugger's HP DECwindows Motif for OpenVMS user interface ( Section 10.10)

The chapter describes window actions and window menu choices, but you can perform most common debugger operations by choosing items from context-sensitive pop-up menus. To access these menus, click MB3 while the mouse pointer is in the window area.

You can also enter commands at the HP DECwindows Motif for OpenVMS command prompt. For information about entering debugger commands, see Section 8.3.

For the source code of programs EIGHTQUEENS.EXE and 8QUEENS.EXE, shown in the figures of this chapter, see Appendix D.

10.1 Displaying the Source Code of Your Program

The debugger displays the source code of your program in the main window (see Figure 10-1).

Figure 10-1 Source Display

Whenever execution is suspended (for example, at a breakpoint), the debugger updates the source display by displaying the code surrounding the point at which execution is paused. The current-location pointer, to the left of the source code, marks which line of code will execute next. (A source line corresponds to one or more programming-language statements, depending on the language and coding style.)

By default, the debugger displays compiler-generated line numbers to the left of the source code. These numbers help identify breakpoints, which are listed in the breakpoint view (see Section 10.4.4). You can choose not to display line numbers so that more of the source code can show in the window. To hide or display line numbers, toggle Display Line Numbers from the File menu on the main window.

The Call Stack menu, between the source view and the push button view, shows the name of the routine whose source code is displayed.

The current-location pointer is normally filled in as shown in Figure 10-1. It is cleared if the displayed code is not that of the routine in which execution is paused (see Section 10.1.3 and Section 10.6.2).

You can use the scroll bars to show more of the source code. However, you can scroll vertically through only one module of your program at a time. (A module corresponds generally to a compilation unit. With many programming languages, a module corresponds to the contents of a source file. With some languages, such as Ada, a source file might contain one or more modules.)

The following sections explain how to display source code for other parts of your program so that you can set breakpoints in various modules, and so on. Section 10.1.3 explains what to do if the debugger cannot find source code for display. Section 10.6.2 explains how to display the source code associated with routines that are currently active on the call stack.

After navigating the main window, you can redisplay the location at which execution is paused by clicking on the Call Stack menu.

If your program was optimized during compilation, the source code displayed might not reflect the actual contents of some program locations (see Section 1.2).

10.1.1 Displaying the Source Code of Another Routine

To display source code of another routine:

1. Choose Browse Sources from the File menu on the main window (see Figure 10-2).
   Select SYMBOLIC display the names of all modules linked in the image. Select ALL to display the names of only those modules for which the debugger has symbolic information.
   The Source Browser dialog box displays the name of your executable image, which is highlighted, and the class of shareable images linked with it (SYMBOLIC or ALL). The name of a linked image is dimmed if no symbolic information is available for that image.
2. Double click on the name of your executable image. The names of the modules in that image are displayed (indented) under the image name.
3. Double click on the name of the module containing the routine of interest. The names of the routines in that module are displayed (indented) under the module name, and the Display Source button is now highlighted.
4. Click on the name of the routine whose source code you want to display.
5. Click on the Display Source push button. The debugger displays in the source view the source code of the target routine, along with an empty breakpoint button to the left of the source code. If the instruction view is open, this display is updated to show the machine code of the target routine.

Section 10.6.2 describes an alternative way to display routine source code for routines currently active on the call stack.

Figure 10-2 Displaying Source Code of Another Routine

10.1.2 Displaying the Source Code of Another Module

1. Choose Browse Sources from the File menu on the main window.
   Select SYMBOLIC display the names of all modules linked in the image. Select ALL to display the names of only those modules for which the debugger has symbolic information.
   The Source Browser dialog box displays the name of your executable image, which is highlighted, and the class of shareable images linked with it (SYMBOLIC or ALL). The names of the shareable images are dimmed if no symbolic information is available for them.
2. Double click on the name of your executable image. The names of the modules in that image are displayed (indented) under the image name.
3. Click on the name of the module whose source code you want to display. The Display Source button is now highlighted.
4. Click on Display Source. The source display in the main window now shows the routine's source code. (If the instruction display in the instruction view is open, this display is updated to show the routine's instruction code.)

In certain cases, the debugger cannot display source code. Possible causes are:

• Execution might be paused within a module of your program that was compiled or linked without the debug option (see Section 1.2).
• Execution might be paused within a system or library routine for which no symbolic information is intended to be available. In such cases you can quickly return execution to the calling routine by clicking one or more times on the S/ret button in the push button view (see Section 10.3.5).
• The source file might have been moved to a different directory after it was compiled. Section 10.1.4 explains how to tell the debugger where to look for source files.

If the debugger cannot find source code for display, it tries to display the source code for the next routine down on the call stack for which source code is available. If the debugger can display source code for such a routine, the current-location pointer is moved to point to the source line to which execution returns in the calling routine.

10.1.4 Specifying the Location of Source Files

Information about the characteristics and the location of source files is embedded in the debug symbol table of your program. If a source file has been moved to a different directory since compile time, the debugger might not find the file. To direct the debugger to your source files, use the SET SOURCE command at the DBG> prompt (see Section 6.2).

10.2 Editing Your Program

The debugger provides a simple text editor you can use to edit your source files while debugging your program (see Figure 10-3).

The text editor available through the debugger's HP 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). You cannot substitute a more sophisticated editor for the text editor invoked with the Edit File item in the Commands menu. To use a different editor, enter the EDIT command at the DBG> prompt in the command view (see EDIT in the Command Reference Dictionary of this manual).

Figure 10-3 Editor Window

To invoke the editor, choose the Edit File item in the Commands menu on the main window. By default, the editor opens a buffer and displays the module currently displayed in the source view. The buffer is named with the file specification of the file in the buffer. If no file is displayed in the source view, the editor displays an empty text buffer, called main_buffer. The buffer name appears in the buffer menu, which is just under the menu bar of the editor view.

The editor allows you to create any number of text buffers by choosing New (for empty text buffers) or Open (for existing files) from the File menu. The name of each text buffer appears in the buffer menu. You can cut, copy, and paste text from buffer to buffer by choosing items from the Edit menu and selecting buffers from the buffer menu.

You can perform forward and backward search and replace operations by entering strings in the Find and Replace with fields and clicking on a directional arrow. You can perform a repeated search for the string by continuing to press the Return key. You can also continue a search by choosing the Find/Replace Next or Find/Replace Previous items in the Edit menu.

To save the file, choose the Save or Save As... items from the File menu. If you do not save your corrections before closing a modified buffer or exiting the debugger, the debugger displays a warning message.

To test any changes to the source code:

1. Select a DECterm window separate from that in which the debugger is running.
2. Recompile the program.
3. Relink the program.
4. Return to the debugging session.
5. Choose the Run Image... item in the File menu on the main window.

This section explains how to:

• Determine where execution is currently paused within your program
• Start or resume program execution
• Execute the program one source line at a time, step by step

For information about rerunning your program or running another program from the current debugging session, see Section 9.3 and Section 9.4.