Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

### 12.1.5 Setting a Source Directory

If you are invoking the Heap Analyzer from a directory other than the one that stores your application source code, you can set a source directory for the Heap Analyzer as soon as the startup screen appears.

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.

### 12.1.7 Controlling the Speed of Display

To examine events in the Memory Map as your application is executing, you can use the Heap Analyzer's push buttons to slow, pause, and otherwise affect the speed of the display. Figure 12-4 shows these push buttons on the Heap Analyzer window just after the Start button was pushed.

The Slow and Pause push buttons allow you to slow or pause the display.

The Step push button allows you to single-step through memory events.

The Sync histogram (not shown) to the right of the Sync button indicates how far behind your application the Heap Analyzer is running. For performance reasons, the Heap Analyzer displays memory events a few seconds after their occurrence in your application.

Figure 12-4 Heap Analyzer Control Panel

1. Start Button | Click to start executing your application and enable the Memory Map display. Once you do so, the Start button changes to a Step button, which is initially dimmed (inaccessible).
2. Step Button | Click to single-step through memory events in the Memory Map display. This button is dimmed until you click on the Pause button.
3. Pause Button | Click to stop (or restart) execution of your application and the dynamic Memory Map display.
4. Slow Button | Click to slow the dynamic Memory Map display.
5. Sync Button | Click to force concurrent execution of your application program and display of memory events in the Memory Map.

The Sync push button allows you to synchronize Heap Analyzer display and application execution, if this is important to you. Your application runs more slowly when you request synchronization.

On OpenVMS Alpha systems, anything that uses system service interception, like the debugger or the Heap Analyzer, is unable to intercept system service call images activated by shared linkage. The image activator, therefore, avoids shared linkage for images linked or run with /DEBUG, and instead activates private image copies. This affects performance of applications under Heap Analyzer control, as images activated by shared linkage run faster.

## 12.2 Working with the Default Display

The following sections describe how to use the Heap Analyzer when memory problems are clearly visible in the default Memory Map display.

Visible problems include allocations that are larger than you expect, that repeat numerous times, that increment at each allocation, and that could occur in a more efficient way.

In such cases, your Heap Analyzer session consists of the following steps:

1. Examine the Memory Map display.
2. Set display characteristics in the Memory Map (optional).
3. Request additional information on individual segments (optional).
4. Request traceback information on individual segments.
5. Correlate traceback entries with source code routines.

### 12.2.1 Memory Map Display

Depending on the size of your application, you may wish to examine the Memory Map display as your application is running (by using the push buttons to slow, pause, or step through events) or after your application completes running (by using the Memory Map's vertical scroll bar to scroll back through the display).

You can identify segments whose size or location are not what you expect by remembering that a segment's location in the Memory Map corresponds to its location in dynamic memory. Lower addresses in dynamic memory are represented in the upper left of the Memory Map display. Addresses increase to the right and wrap at each line of the display.

### 12.2.2 Options for Memory Map Display

As you examine the Memory Map, you may wish to select display options that allow you to see more clearly those parts of the display you are most interested in.

The Display Menu allows you to control whether you see segment type names within the Memory Map display, whether the display automatically scrolls to show the most recent activity, and whether you can compress the display.

The Zoom Menu allows you to control the degree of magnification with which you see segments in the Memory Map. Choosing the Far menu item, for example, shows an overview of memory. Choosing Extremely Close shows a more detailed view of memory.

Figure 12-5 shows the display options that appear in the Display pull-down menu. The figure then lists all the display options available in the Memory Map.

Figure 12-5 Heap Analyzer Display Menu

1. Display Menu | Text Visible: (Default.) Labels each segment in the Memory Map with a segment name, provided that the segment is large enough to carry a name label. Auto Scroll: (Default.) Automatically scrolls the Memory Map to the highest memory addresses (lower right) whenever the display is expanded. Reduce Scroll Region: When you request a limited or partial Memory Map display (see Section 12.3.3.2), compresses the display so that you can see as many segments as possible without scrolling to their location in the original display. Display All Segments: Displays segment definitions for all segments in the Memory Map. Clear Information Window: Clears text and messages from the Information window.
2. Zoom Menu | Options provide a closer or more distant view of the Memory Map.

### 12.2.3 Options for Further Information

As you examine the Memory Map display, you may find that you need more information on those segments that interest you. The Memory Map pop-up menu allows you to request segment, contents, address, and type definitions for an individual segment.

A segment definition has the following form:

    cursor-address   n:init-address + length = end-address  name ( view )

cursor-address | The address beneath your cursor when you click MB3.
n | The number of your segment within the sequence of total segments.
init-address | The initial address of your segment.
length | The length (in bytes) of your segment.
end-address | The last address of your segment.
name | The segment type name of your segment.
view | The view of your segment: block, image, region, or zone. (See Section 12.3.3.2 for more information on views.)

For example, the following segment definition describes the 15th segment in your Memory Map display, which is a segment of type LIBRTL:

            0004ECA5     15: 00040000+0001CA00=0005CA00 LIBRTL (Image)

A contents definition consists of a partial segment definition (a segment definition without a cursor-address) and an ASCII representation of the contents of segment addresses. For example:

    contents of: 38: 001C7000+000000C0=001C70C0
       LIBTRL\LIB$VM\LIB$GET_VM (Block)

              [ASCII representation]

An address definition takes the form of a statement describing user access to a stated address. For example:

    001C710B is read and write accessible by the user

A type definition takes the form of a statement summarizing the total number of segments and total number of bytes devoted to a segment type. For example:

    LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments
       using 00002160 bytes

Figure 12-6 shows the Memory Map context-sensitive pop-up menu. The figure then lists all the mouse and pop-up menu item choices available in the Memory Map.

Figure 12-6 Heap Analyzer Memory Map Context-Sensitive Pop-Up Menu

1. Memory Map | Click MB1: Displays the segment definition in the Message window.
2. Map Pop-Up | Traceback of Allocation: Displays the traceback information associated with a segment in the Information window (see Section 12.2.4). Display Segment: Displays the segment definition in the Information window. Display Contents: Displays the segment definition and contents of each address in the Information window. Display Address: Displays the position (address) under your cursor and the type of user access in the Information window. Display Type: Displays the segment type definition in the Information window. Go to Type: Allows you to jump from a segment type listed in the Type Histogram to the same segment type listed in the Views-and-Types Display. Do Not Use Type: Adds a segment type to the Do-not-use Type List.

### 12.2.4 Requesting Traceback Information

After you identify an individual segment of interest, choose the Traceback of Allocation menu item in the Memory Map pop-up menu. Traceback information can help you understand why your segment was created. Viewing traceback is also a preliminary step to displaying application code.

Traceback information consists of a partial segment definition (a segment definition without a cursor address) and the list of elements on the call stack at the moment your segment was created. The element naming convention is image name\module name\routine name \line number. For example:

    traceback:     8:000BA800+00065C00=00120400 DECC$SHR (Image)
    00066EDE   DBG$HA_KERNEL
    00005864   CRL$MAIN_DB\CRL_LIBRARY\crl__initialize_libraries\%LINE 5592

### 12.2.5 Correlating Traceback Information with Source Code

When the traceback display appears, you identify the traceback entry most closely associated with the segment you are investigating. Most often, you can do this by comparing segment type names and traceback routine names.

When you double click MB1 on this traceback entry, the source code associated with the entry appears (highlighted) in the Source window. You can then scroll through the source code display, identify problematic code, and decide how to correct it.

If you cannot identify any problems in the displayed source code, return to the Information window and double click MB1 on the routine immediately above or below your previous choice.

If you double click MB1 on a traceback entry, and 'Source Not Available' messages appear in the Source window, you may have forgotten to set a source directory at the beginning of your Heap Analyzer session. See Section 12.1.5 for information on setting a search directory.

Figure 12-7 shows the source code that appears when you double click MB1 on the traceback entry highlighted in the Information window. The figure then lists all the mouse and menu item choices available for the Source and Information windows.

Figure 12-7 Heap Analyzer Information and Source Windows

1. Information Window | Double click MB1: Allows you to jump from a line of traceback displayed in the Information window to the related source code in the Source window.
2. Information Window Pop-Up | Go to Source: Allows you to jump from a line of traceback displayed in the Information window to the related source code in the Source window.
3. Display Menu | Clear Information window: Clears text and messages from the Information window.

## 12.3 Adjusting Type Determination and Display

The following sections describe the steps to perform when the memory events represented in the default Memory Map are not clear; that is, you cannot tell whether a problem exists or not.

This circumstance can occur when the segment type names chosen by the Heap Analyzer are too broad to be useful for your application, or when the Memory Map is so full that you cannot easily see the segment of interest.

In such cases, you can choose one or both of the following strategies:

- Review the type summary in the Type Histogram (to see a summary, in total segments and total bytes, of each segment type's use)
- Adjust the type determination in the Memory Map (directing the Heap Analyzer to select type names that are more meaningful to you)
- Adjust the type display in the Memory Map (directing the Heap Analyzer to suppress some types and highlight others)

If, by adjusting the type determination or display, you then identify visible problems, you can resolve them in the same way you would if you were working with the default Memory Map display. (For more information, see Section 12.2.)

### 12.3.1 Options for Further Information

As you examine the Memory Map, you may wish to see a summary of Memory Map activity in the Type Histogram. The Type Histogram, which is two histograms back-to-back, shows the percentage of total segments and the percentage of total bytes devoted to each segment type in the Memory Map.

To see these graphical representations in numeric form, click MB1 on the segment type of interest.

To see the total number of segments or total number of bytes, check the top of each histogram.

Figure 12-8 shows the types listed in the Type Histogram. (This window has been resized so all types appear.) The figure then lists all the mouse and menu item choices available in the Type Histogram.

Figure 12-8 Heap Analyzer Type Histogram

1. Type Histogram | Click MB1: Displays the percentage of total segments and the percentage of total bytes represented by a segment.
2. Type Histogram Pop-Up | Display Type: Displays a type definition in the Information window. Go To Type: Allows you to jump from a segment type listed in the Type Histogram to the same segment type listed in the Views-and-Types Display. Do Not Use Type: Adds a segment type to the Do-not-use Type List.

### 12.3.2 Altering Type Determination

As you examine the Memory Map, you may find that some segment type names are not meaningful to you. By adding these names to the Do-not-use Type List, you direct the Heap Analyzer to rename segments and, if necessary, regenerate the Memory Map display.

By default, the analyzer assigns segment type names at the creation of a segment. In some cases, the analyzer assigns an element name (for example, LIBRTL). In most cases, however, the analyzer searches down the call stack to find a routine name that then serves as a segment type name.

The analyzer chooses the first routine name on the call stack that is not prohibited by the Do-not-use Type List. If the first routine is prohibited, the analyzer examines the next routine down, and so on.

This default behavior can cause the following Memory Map problems:

- The same few type names appear repeatedly in the Memory Map display.
  This occurs when the first routines on the call stack are low-level memory management or utility routines. Since most of the allocation events in your application use these routines, you see unrelated allocations grouped together with the same type name.
  To prevent this problem, add any application-specific memory management or utility routine names to the Do-not-use Type List before you run your application.
- The type names assigned provide a higher level of abstraction than you require.
  This can occur when the first routine on the call stack is less application-bound than your level of examination. If you need to see type names that reflect application functions, it is not helpful to see type names derived from intermediary memory management routines instead.
  This can also occur when the first routine on the call stack focuses on a part of your application you are not interested in examining. If you need to see type names that reflect subsystem functions (for example, initialize_death_star), it is not helpful to see only one type name for all subsystem functions (for example, initialize_star).
  To correct this problem, add the current type name to the Do-not-use Type List until the Memory Map display reflects the level of abstraction you desire.

To add a segment type name to the Do-not-use Type List, you can select the Add to Do-not-use Type List pull-down menu item in the Options menu, or you can choose the Do Not Use Type pop-up menu item in the Memory Map, Type Histogram, or Views-and-Types Display. To delete a segment type from this list, choose the Use Type pop-up menu item in the Do-not-use Type List.

To save the contents of a Do-not-use Type List, you can choose the Save Do-not-use Type List menu item in the Options menu. This saves the list for future Heap Analyzer sessions. The Restore Do-not-use Type List menu item removes recent additions to the list since the last time the list was saved.

Figure 12-9 shows a LIBRTL\*\* entry in the Add to Do-not-use Type List dialog box you can choose from the Options menu. The figure then lists all the mouse and menu item choices available for the Do-not-Use Type List.

Figure 12-9 Heap Analyzer Do-Not-Use Type List

1. Do-not-use Type List Pop-Up | Use Type: Deletes a segment type from the Do-not-use Type List.
2. Options Menu | Add to Do-not-use Type List: Adds a segment type to the Do-not-use Type List. Save Do-not-use Type List: Allows you to save the segment types listed in your Do-not-use Type List between Heap Analyzer sessions. Restore Do-not-use Type List: Deletes additions to the Do-not-use Type List since the list was last saved.
3. Memory Map Pop-Up, Histogram Pop-Up, Views-and-Types Display Pop-Up | Do Not Use Type: Adds a segment type to the Do-not-use Type List.

### 12.3.3 Altering the Views-and-Types Display

As you examine the Memory Map, you may find that you need to adjust the type display to focus more clearly on your area of interest. The Views-and-Types Display allows you to specify changes to multiple or individual segments of the same type.

The Views-and-Types Display is actually two windows separated by a window sash. You can expand the left window to show all the known types in your application. The right window contains the display options (color, show status, expand status, and save status).

#### 12.3.3.1 Selecting the Scope of Your Change

The Heap Analyzer receives information about segments from four OpenVMS memory managers that perform allocations and deallocations in memory space. Each memory manager has a slightly different view, or overall picture, of dynamic memory.

Each memory manager recognizes a different set of segment types. This means that, within the Heap Analyzer, where views from the memory managers are layered on each other, a single memory location can be associated with one or more segment types.

The left window of the Views-and-Types Display contains a hierarchy that reflects this integration:

- Views (integrates all four views)
- Blocks (block view from LIB$VM memory manager)
- Images (image view from SYS$IMAGE memory manager)
- Regions (system services view from SYS$SERVICES memory manager)
- Zones (zone view from LIB$VM_ZONE memory manager)

To see the individual segment types recognized by each memory manager, expand the default display by double clicking MB1 on Blocks, Images, Regions, or Zones keywords. To collapse an individual listing, click MB3 on the keyword you previously selected.

This hierarchy offers you the following choices in scope:

- To affect all segment types in all views:
  Click MB1 on the Views keyword.
- To affect all segment types in one view:
  Click MB1 on the Blocks, Images, Regions, or Zones keywords.
- To affect individual segment types:
  Double click MB1 on the view of your choice, and click MB1 on one or more single segment types.

Figure 12-10 shows the Block hierarchy item that is highlighted when you click MB1 to choose all blocks. The figure then lists all the mouse and menu item choices available in the hierarchy side of the Views-and-Types Display.

Figure 12-10 Heap Analyzer Views-and-Types Hierarchy

1. Double click MB1 | Allows you to expand (or collapse) the Views-and-Types hierarchy.
2. Views Hierarchy Pop-Up | Display Type: Displays a type definition in the Information window. Go to Type: Highlights the type you have selected in the Views-and-Types Display. Do Not Use Type: Adds a segment type to the Do-not-use Type List.

Previous | Next | Contents | Index

| privacy and legal statement |
4538PRO_024.HTML