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

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.

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 and Zoom Menu

12.2.3 Options for Further Information

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

12.2.4 Requesting Traceback Information

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

12.3 Adjusting Type Determination and Display

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

12.3.2 Altering Type Determination

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

12.3.3 Altering the Views-and-Types Display

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