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. 2 ha_window_def_mmdisp =Title 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. 2 ha_window_def_optmmdisp =Title 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. 2 ha_window_def_optinfo =Title 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 the 'Altering the Views and Types Display' help topic 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 2 ha_window_def_trace =Title 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 callstack 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 2 ha_window_def_final =Title 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 the 'Setting a Source Directory' help topic for information on setting a search directory. 2 ha_window_optwork =Title Adjusting Type Determination and Display =include debugui ha_window_opt_info =include debugui ha_window_opt_type =include debugui ha_window_opt_disp 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) Buff - 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 the 'Working with the Default Display' help topic.) 2 ha_window_opt_info =Title 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. 2 ha_window_opt_type =Title 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 callstack to find a routine name that then serves as a segment type name. The analyzer chooses the first routine name on the callstack 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 callstack 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 callstack 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 callstack 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. 2 ha_window_opt_disp =Title Altering the Views-and-Types Display =include debugui ha_window_opt_scope =include debugui ha_window_opt_dispopt 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). 2 ha_window_opt_scope =Title 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, 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. 2 ha_window_opt_dispopt =Title Choosing a Display Option The right window of the Views-and-Types Display shows the display options available, as follows: - Color To change the color of all segment types, all segment types in a particular view, or individual segment types, click MB3 on the color button in the display. When the vertical color strip appears, click MB1 on the color of your choice. Then, click the Apply button to apply your change. - Show (or hide) status To suppress (or restore) the display of all segment types, all segment types in particular view, or individual segment types, toggle the Show button to the Hide (or Show) setting and click MB1. (Alternatively, you can choose the appropriate menu item from the Show pop-up menu.) Then, click the Apply button to apply your change. Use this option to clear the Memory Map of segments you are not examining. You can also use this option to find all segments of a particular type (by hiding every other segment). - Expand (or collapse) status To collapse (or expand) the display of segment types contained within all segment types, all segment types in a particular view, or individual segment types, toggle the Expand button to the Collapse (or Expand) setting and click MB1. (Alternatively, you can choose the appropriate menu item from the Expand pop-up menu.) Then, click the Apply button to apply your change. Use this option to clear the Memory Map of nested segments you are not examining. Depending on your application, heap analyzer performance may also improve. - Save (or remove) status To destroy (or save) information on all segment types, all segment types in a particular view, or individual segment types, toggle the Save button to the Remove (or Save) setting and click MB1. (Alternatively, you can choose the appropriate menu item from the Save pop-up menu.) Then, click the Apply button to apply your change. Use this option to clear the Memory Map completely, and then resume Memory Map display. To cancel a choice, click the Reset button, or choose the Reset menu item from the Show, Expand, or Save pop-up menus. 2 ha_window_exit =Title Exiting the Heap Analyzer To exit the heap analyzer, choose the Exit item from the File menu on the heap analyzer screen. 2 ha_on_version_hlp =Title About the Heap Analyzer =include debugui ha_on_window_hlp The heap analyzer is a feature of the OpenVMS Debugger Software Version: OpenVMS Debugger Version 8.2 Copyright 2015, VMS Software, Inc. All rights reserved. For more information about the heap analyzer, double click on 'Using the Heap Analyzer' from the list of Additional Topics below. 2 ha_on_help_hlp =Title Using Heap Analyzer Online Help =include debugui ha_context_sensitive_help =include debugui ha_help_menu_hlp =include debugui ha_on_window_hlp Two kinds of online help about the debugger and debugging are available during a debugging session: Context-sensitive help, which is information about an area or object in a window or dialog box - Task-oriented help, which consists of an introductory help topic named 'Using the Heap Analyzer' and several subtopics on specific debugging tasks Related context-sensitive and task-oriented topics are connected through the list of Additional Topics in the Help windows. 2 ha_context_sensitive_help =title Displaying Context-Sensitive Help =include debugui ha_on_help_hlp Context-sensitive help is information about an area or object in a window or a dialog box. To display context-sensitive help: 1. Choose On Context from the Help menu in the heap analyzer screen. The pointer shape changes to a question mark (?). 2. Place the question mark on an object or area in a heap analyzer window or dialog box. 3. Click on MB1. Help for that area or object is displayed in a Help window. Additional Topics provide task-oriented discussions, where applicable. To display context-sensitive help for a dialog box, you can also click on the Help button in the dialog box.