HP OpenVMS Systems Documentation

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) 

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 HP 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 

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

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/server interface to the debugger.

The debug server runs on OpenVMS systems. The client is the user interface to the debugger, from which you enter debugger commands that are sent to the server. The server executes the commands and sends the results to the client for display. The client runs on Microsoft Windows 95, Windows 98, Windows NT, Windows 2000, and Windows XP.

[DEBUG_CLIENTS011.KIT]DEBUGX86011.EXE

11.2 Installation of PC Client

There is no special installation procedure for the components that run on OpenVMS. The system administrator must move the OpenVMS debug client kit listed in the previous section from the OpenVMS distribution media to a place accessible to PC users, such as a PATHWORKS share or an FTP server. The client kit is a self-extracting .EXE file.

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.

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

• Debug client
• Debug client Help file
• README file
• 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.9.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

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.

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.

11.7 Documentation

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

The Heap Analyzer, available on OpenVMS Integrity servers and Alpha 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. On Alpha systems: 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.
4. On Integrity server systems, at the Debug prompt (DBG>), enter the START HEAP_ANALYZER command.

   Note The Heap Analyzer startup and the Heap Analyzer START command on the Integrity servers kept debugger (START HEAP_ANALYZER) hangs for threaded applications with upcalls enabled. In such instances, for threaded or AST-involved applications, HP strongly recommends that you either start the Heap Analyzer before setting up any debug events or after disabling or canceling the debug events. (You can enable/reset events after the Heap Analyzer startup and START returns you to debugger control.)

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

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