Updated: 11 December 1998

OpenVMS Debugger Manual

This part introduces the debugger's PC client interface.

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

For information about the debugger's Decwindows Motif interface, see Part 3.

This chapter describes the PC client interface to the debugger.

The OpenVMS Debugger Version 7.2 features an optional client/server interface that separates the debugger into two components: the debug client and the debug server. The debug server runs on an OpenVMS system. There is a debug client that runs on OpenVMS systems, and a client that runs on Microsoft Windows 95 and Microsoft Windows NT. The interface is identical for both Windows 95 and Windows NT.

The PC client interface offers essentially the same features as the DECwindows Motif client interface (see Section 9.8).

The client and server communicate using DCE RPC over one of the following transports:

• TCP/IP
• UDC
• DECnet

See Section 9.8.1 for the description of the software required to run the PC Client/Server interface.

11.2 Installation

There is no special installation procedure for the components that run on OpenVMS. This section describes the procedure for installing the debug client on a PC.

The system administrator should move the OpenVMS debug client kits from the OpenVMS distribution media to a place accessible to PC users, such as a PATHWORKS share or FTP server. The client kits can be found on the distribution media in the following directories:

CPU	Operating System	Client Kit
Intel	Microsoft Windows 95, 98	[DEBUG_CLIENTS010.KIT]DEBUGX86010.EXE
Intel	Microsoft Windows NT	[DEBUG_CLIENTS010.KIT]DEBUGX86010.EXE
Alpha	Microsoft Windows NT	[DEBUG_CLIENTS010.KIT]DEBUGALPHA010.EXE

These client kits are self-extracting .EXE files.

Once the appropriate executable file has been transferred to the PC, you can run the file to install the debug client on the PC. The INSTALLSHIELD installation procedure guides you through the installation.

By default, the debug client is installed in the \Program Files\OpenVMS Debugger folder. You can also click Browse to select an alternate location.

You can choose one of the following options:

Install Option	Details
Typical	Debug client and OpenVMS Debugger Manual in HTML format
Compact	Debug client only
Custom	Choice of Debug client and/or OpenVMS Debugger Manual in HTML format

The Typical installation option creates an OpenVMS Debugger program folder that contains shortcuts to the following items:

• The Debug client
• The Debug client Help file
• The OpenVMS Debugger Manual in HTML format
• A Readme file
• An Uninstall procedure

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.

See Section 11.5 for details about specifying the number of secondary clients allowed to connect to a debugging session.

11.4 The PC Client Workspace

The PC client workspace is analogous to the workspace of the Motif client (see Chapter 8). The client workspace contains views to display dynamic information and toolbars to contain shortcuts to debugger commands. You can configure the views and toolbars to suit your personal requirements, create your own shortcuts, and save your personal configurations.

These topics are discussed at length in the PC client Help file. You can access the PC client Help directly from the OpenVMS Debugger folder that you created during PC client installation (see Section 11.2), or from the Help menu within the client. See the following topics:

• Overview
• Getting Started
• Views
• Toolbars

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 a terminal emulator such as Telnet.

Before granting the DBG$ENABLE_SERVER identifier, the system manager must create it by entering the command DEBUG/SERVER from an account with write access to the rights database. The system manager needs to do this only once. The system manager can then run the Authorize utility to grant the DBG$ENABLE_SERVER identifier to the user.

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

To establish a connection from the PC client, invoke the Connection dialog, either from the File pull-down menu, or by selecting the C/S button on the Main toolbar. The dialog displays the servers already known to this client, and the sessions currently active by this client.

You can specify a server for a new connection, or select a particular session for use.

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

• Connect to the selected (or the default) server
• Disconnect from a server
• Test the client/server connection
• Stop the selected server

In addition, the Advanced button allows you to select the network protocol to be used (see Section 11.5.1), and to select the number of secondary clients (0-30) allowed for the client/server connection to be established (see Section 11.5.2).

11.5.1 Choosing a Transport

• TCP/IP
• DECnet
• UDP

1. On the Connection dialog, click Advanced.
2. Select the number of secondary clients (0-30) to be permitted.
3. Click Connect on the Connection dialog.

The debugger dismisses the Connection dialog, makes the connection, and indicates success (or failure) in the Command view. You can now begin your debugging procedures.

11.6 Terminating a Server Connection

You can stop a server by entering Ctrl-Y on the node on which the server is running. If you do so, then enter the DCL STOP command.

To stop the server from the client, perform the following steps:

1. Open the File pull-down menu.
2. Select Exit.
3. Click Server to stop only the server, or click Both to stop both the server and the client.

An alternative way to stop the server is to perform the following steps:

1. Open the File pull-down menu.
2. Click Connection to invoke the Connection dialog.
3. Select the server connection from the Active Sessions list.
4. Click Stop.

To stop both the server and the client, perform the following steps:

1. Open the File pull-down menu.
2. Click Exit.
3. Click Both.

To stop only the client, perform the following steps:

1. Open the File pull-down menu.
2. Click Exit.
3. Click Client.

To stop only the server, perform the following steps:

1. Open the File pull-down menu.
2. Click Exit.
3. Click Server.

In addition to the PC client Help file, the OpenVMS Debugger Manual is online in HTML format. To access the manual from within the client, do the following:

1. Open the Help pull-down menu.
2. Click Contents.
3. Click Local Manual.

The Heap Analyzer, available on both OpenVMS Alpha and OpenVMS VAX systems, is a feature of the debugger that provides a graphical representation of memory use in real time. By studying this representation, you can identify areas in your application where memory usage and performance can be improved. For example, you might notice allocations that are made too often, memory blocks that are too large, evidence of fragmentation, or memory leaks.

After you locate an area of interest, you can request an enlarged, more detailed, or altered view. You can also request additional information on the size, contents, or address of the allocations shown.

After you narrow your interest to an individual allocation, you can request traceback information. The analyzer allows you to correlate the traceback entry for an allocation with source code in your application program. By scrolling through the source code display, you can then identify problematic code and decide how to correct it.

This chapter describes the following:

• Starting a Heap Analyzer session ( Section 12.1)
• Working with the default display ( Section 12.2)
• Adjusting type determination and display ( Section 12.3)
• Exiting the Heap Analyzer ( Section 12.4)
• Sample session ( Section 12.5)

The following sections describe how to invoke the Heap Analyzer and run your application.

12.1.1 Invoking the Heap Analyzer

You can invoke the Heap Analyzer during a debugging session in one of the following ways:

1. In the debugger main window, choose Run Image or Rerun Same from the File menu. When a dialog box appears, select the program you wish to execute and click the Heap Analyzer toggle button.
2. At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER or RERUN/HEAP_ANALYZER program-image command.
3. At the DCL prompt ($) in a DECterm window outside the debugger, enter the following command and then execute your program:

   $ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED

To use the heap analyzer with a protected image, enter the following command and then execute your program:

$ DEFINE/EXEC/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED

This is necessary if the image was installed with the following command:

$ INSTALL ADD imagename/PROTECTED

You can invoke the Heap Analyzer outside a debugging session by entering the DEFINE/USER (or DEFINE/SYSTEM) command detailed above, and then the DCL command RUN/NODEBUG.

After you successfully invoke the Heap Analyzer, the Heap Analyzer startup screen appears.

12.1.2 Viewing Heap Analyzer Windows

The Heap Analyzer contains a main window, six subsidiary windows, and a control panel (see Figure 12-1.)

The Memory Map, the most important window, displays a representation of your application's dynamic memory use. At startup, the Memory Map shows the images that comprise your application. As your application executes, you can see the relative location and size of individual memory blocks, images, program regions, memory zones, and dynamic strings as they are allocated and deallocated in memory space.

The Message window displays information on your Heap Analyzer session. At startup, the Message window contains the message "Heap Analyzer initialization complete. Press Start button to begin program." As your application executes, informational and error messages appear in this window.

The Push Button Control Panel contains buttons that allow you to control the speed of the Memory Map display. At startup, you click on the Start button to begin executing your application. As your application executes, you can click on other buttons in the panel to pause, slow, or otherwise affect the continuous display.

The Information window displays information on Memory Map segments. As your application executes, you can pause execution at any time to request specific information.

The Source window displays the application source code associated with a segment in the Memory Map.

The Do-not-use Type List allows you to adjust the Memory Map display by redetermining a segment's type, or group name.

The Views-and-Types Display allows you to adjust the Memory Map display by selectively viewing certain segment types.

The Type Histogram displays summary and statistical information on segment types.

As you use the Heap Analyzer, you may need to increase or decrease the size of the window in which you are working. To do this, pull the window pane sashes between windows or resize the screen as a whole.

Figure 12-1 Heap Analyzer Windows

12.1.3 Viewing Heap Analyzer Pull-Down Menus

Figure 12-2 Heap Analyzer Pull-Down Menus

12.1.4 Viewing Heap Analyzer Context-Sensitive Menus

Figure 12-3 Heap Analyzer Context-Sensitive Pop-Up Menus

12.1.5 Setting a Source Directory

To set a source directory:

1. Choose Set Source... from the Options menu on the Heap Analyzer screen.
   The Set Source dialog box appears.
2. Enter the directory specification for your source directory as you would for the debugger SET SOURCE command.
   For more information on this command, see the SET SOURCE command.
3. Click on OK.

The Heap Analyzer can now access your application.

12.1.6 Starting Your Application

If you invoked the Heap Analyzer from within a debugging session, start your application by performing the following steps:

1. Click on the Start button in the Push Button Control Panel.
   The Message window displays an "application starting" message, and the Start button label changes to Step. The OpenVMS Debugger main window pops forward.
2. Click on the Go button in the debugger's control panel, and iconize the OpenVMS Debugger window.
   Memory events associated with your application begin showing in the Memory Map.

If you invoked the Heap Analyzer outside a debugging session, start your application by performing only step 1 above.

After your application is running, the Memory Map (and other parts of the Heap Analyzer display) are continuously updated to reflect the state of your application.

Unless you intervene (see Section 12.1.7), this updating continues until an occurrence causes memory events to stop. For example, your application might prompt for input, the debugger might prompt for input, or your application might finish execution.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_024.HTML