Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

#### 10.10.4.1 Defining the Key Sequence to Display the Breakpoint Dialog Box

By default, the key sequence for displaying the dialog box for conditional and action breakpoints is Ctrl/MB1 (see Section 10.4.6 and Section 10.4.7). To define another key sequence, edit the current definition of the following resource in the resource file. For example:

    DebugSource.ModifyBreakpointToggleSequence:   Ctrl<Btn1Down>(2)

#### 10.10.4.2 Defining the Key Sequence for Language-Sensitive Text Selection

By default, the key sequence for language-sensitive text selection in the main window and instruction view is Ctrl/MB1 (see Section 10.5.1). To define another key sequence, edit the current definition of the following resource in the resource file. For example:

    DebugSource.IdentifierSelectionSequence:  Ctrl<Btn1Down>

To avoid conflict with standard Compaq DECwindows Motif for OpenVMS word selection, do not use a double-click combination, such as Ctrl<Btn1Down>(2).

#### 10.10.4.3 Defining the Font for Displayed Text

To define another font for the text displayed in various debugger windows and views, edit the current definition of the following resources in the resource file. For example:

    DebugDefault.Font:  -*-COURIER-BOLD-R-*--*-120-*-*-*-*-ISO8859-1

#### 10.10.4.4 Defining the Key Bindings on the Keypad

To bind a different command to a key that is already associated with a command, edit the current definition of the following resources in the resource file. For example:

        <literal>(<Key>)0xFFB0: EnterCmdOnCmdLine("step/line 3") \n\

To bind a command to a key that is not currently associated with a command, refer to the Keysym Encoding chapter of the X and Motif Quick Reference Guide for key designations.

## 10.11 Debugging Detached Processes

You cannot use the Compaq DECwindows Motif for OpenVMS user interface to the debugger to debug detached processes, such as print symbionts, which run without a command line interpreter (CLI).

To debug a detached process that runs without a CLI, use the character-cell (screen mode) interface to the debugger (see Section 1.11).

## Part 4
PC Client Interface

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.

## Chapter 11
Introduction to the Debugger PC Client/Server Interface

This chapter describes the PC client interface to the debugger.

Note that the OpenVMS Version 7.3 debugger does not support previous versions of the PC client. You must install the Version 1.1 PC client that is found in the kit on the OpenVMS Version 7.3 distribution media, as identified in Section 11.2.

The Version 1.1 PC client is compatible with Version 7.3 and prior debug servers.

## 11.1 Introduction

The OpenVMS Debugger Version 7.2 and later 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

Note If you are running TCP/IP Services for OpenVMS (UCX) Version 4.1, you must have ECO2 installed. You can also run a later version of UCX.

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_CLIENTS011.KIT]DEBUGX86010.EXE
Intel | Microsoft Windows NT | [DEBUG_CLIENTS011.KIT]DEBUGX86010.EXE
Alpha | Microsoft Windows NT | [DEBUG_CLIENTS011.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

## 11.3 Primary Clients and Secondary Clients

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

## 11.5 Establishing a Server Connection

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.

Note You must hold the DBG$ENABLE_SERVER identifier in the rights database to be able to run the debug server. Exercise care when using the debug server. Once a debug server is running, anyone on the network has the ability to connect to the debug server.

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

Note You can usually identify the server using only the node name and the port number. For example, `nodnam[1034]` .

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

From the Connection dialog, select the network protocol to be used for the client/server connection from the following:

- TCP/IP
- DECnet
- UDP

### 11.5.2 Secondary Connections

From the Connection dialog, you can enable up to 30 secondary clients to connect to the server. You must be the primary client (the first client to connect to this server), and perform the following steps:

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.

### 11.6.1 Exiting Both Client and Server

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.

### 11.6.2 Exiting the Client Only

To stop only the client, perform the following steps:

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

### 11.6.3 Stopping Only the Server

To stop only the server, perform the following steps:

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

## 11.7 Documentation

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.

## Part 5
Advanced Topics

This part describes advanced debugging techniques available in the OpenVMS Debugger.

## Chapter 12
Using the Heap Analyzer

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)

## 12.1 Starting a Heap Analyzer Session

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.

Note On OpenVMS Alpha systems, the Heap Analyzer does not work on programs linked with the /NODEBUG qualifier. On OpenVMS VAX systems, the Heap Analyzer does work on programs linked with the /NODEBUG qualifier, although the traceback information displayed is minimal.

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

1. Memory Map | Shows the graphical representation of memory, that is, the part of P0-space that is in use. Each allocation appears as a colored strip, or segment.
2. Message Window | Displays Heap Analyzer informational and error messages and one-line segment descriptions.
3. Information Window | Shows additional information on segments and segment types that appear in the Memory Map.
4. Source Window | Shows application source code.
5. Do-not-use Type List | Lists routines not used as segment types, the name that characterizes segments.
6. Views-and-Types Display | Lists all segment types known to the Heap Analyzer and allows you to alter the segment display.
7. Push Button Control Panel | Provides Start/Step, Pause, Slow, and Sync buttons that allow you to control the speed of Memory Map display.
8. Type Histogram | Shows statistics on segment size and use.

### 12.1.3 Viewing Heap Analyzer Pull-Down Menus

The Heap Analyzer provides pull-down menus that are grouped over the Memory Map (see Figure 12-2). This figure is adjusted slightly so that all menu items can be seen.

Figure 12-2 Heap Analyzer Pull-Down Menus

1. File Menu | Allows you to exit from the Heap Analyzer
2. Display Menu | Allows you to adjust the Memory Map display and to clear the Information window
3. Zoom Menu | Provides a closer or further view of the Memory Map
4. View Menu | Lets you select the granularity of the display
5. Options Menu | Allows you to indicate a search directory list or to adjust the Do-not-use Type List
6. Help Menu | Provides context-sensitive or task-oriented online help

### 12.1.4 Viewing Heap Analyzer Context-Sensitive Menus

Most operations in the Heap Analyzer, however, are accomplished through context-sensitive pop-up menus. Most Heap Analyzer windows contain a pop-up menu listing available tasks (see Figure 12-3). To access a window's pop-up menu, position your mouse pointer in the window and click MB3.

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

1. Memory Map Pop-Up | Provides additional information on segments displayed in the Memory Map, allows you to jump to a segment's type in the Views-and-Types Display, or adds a segment's type to the Do-not-Use Type List.
2. Information Window Pop-Up | Allows you to jump from a line of traceback displayed in the Information window to the related source code in the Source window.
3. Do-not-use Type List Pop-Up | Deletes a segment's type from the Do-not-Use Type List.
4. Views-and-Types Display Pop-Up | Left side: Provides additional information on segment types listed, highlights a segment type within the Views-and-Types Display, or adds a segment type to the Do-not-Use Type List. Right side: Allows you to adjust display characteristics for the segment type highlighted in the left side of the Views-and-Types Display.
5. Type Histogram Pop-Up | Provides additional information on segment types listed, highlights a segment type in the Type Histogram, or adds the segment type to the Do-not-Use Type List.

Previous | Next | Contents | Index

| privacy and legal statement |
4538PRO_023.HTML