1 DEBUGUI =Title Debug Top Level This is the only level 1 module in this help library. 2 src_workarea_hlp =Title Source View on Main Window =include debugui popup_src =include debugui src_display =include debugui break =include debugui setscope =include debugui src_file_pd_menu_hlp =include debugui src_edit_pd_menu_hlp =include debugui src_break_pd_menu_hlp =include debugui src_commands_pd_menu_hlp =include debugui cnt_options_pd_menu_hlp =include debugui help_pd_menu_hlp =include debugui callstack_menu_hlp =include debugui on_mwindow_hlp Use the source view on the main window to do the following: Location Function ------- --------- Source display Display program source code, and, optionally, compiler-generated line numbers to the left of the code. Breakpoint Set breakpoints on specific source lines or toggles routines in your program, check breakpoint status, and activate or deactivate breakpoints. Current line Identify the line of source code that will be indicator executed when program execution resumes. Call stack Identify the sequence of routine calls on the stack. 2 popup_src =Title Context-Sensitive Pop-up Menus in Source View =include debugui src_workarea_hlp To use pop-up menus in the source view, select text or position your mouse pointer in the source view, and press MB3. The debugger inserts the selected text or line number in the menu items of the pop-up menu. If you press MB3 while your mouse pointer rests on a source line in the source view, a pop-up menu with the following items appears: Examine [selection] Evaluates the selected expression and prints its value in the command view. Monitor [selection] Inserts the selected expression in the monitor list of the monitor view. Deposit [selection] Provides the Assign/Deposit dialog box. Break on Routine Sets a breakpoint on a selected routine name. [selection] Toggle Breakpoint Activates/deactivates breakpoint at mouse pointer. at Line [line number] Temporary Breakpoint Sets temporary breakpoint at mouse pointer. at Line [line number] Go to Line Branches to [line number] without executing source [line number] code betwen the line at which execution is suspended and [line number]. Display Instruction Displays decoded instruction stream of your program. Step Step to next line, stepping over routine calls. Go Resume execution of program. If you press MB3 while your mouse pointer rests in the annotation area of the source view, a pop-up menu with the following items appears: Toggle Breakpoint Activates/deactivates breakpoint at mouse pointer. at Line [line number] Temporary Breakpoint Sets temporary breakpoint at mouse pointer. at Line [line number] Go to Line Executes until [line number] is reached. [line number] Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 callstack_menu_hlp =Title Call Stack Menu on Main Window =include debugui setscope Use the Call Stack menu on the main window to do the following: Action Function ------- --------- None Identifies the routine whose source code is executing in the source view. Pull-down Identifies the sequence of routines on the menu call stack. Click on Sets the context (scope) for source display, routine instruction display, register display, name and symbol searches to any routine on the call stack. 2 cnt_button_hlp =Title Push Button View on Main Window =include debugui stop_btn_hlp =include debugui examine =include debugui monitor =include debugui exam_deposit =include debugui execute =include debugui custom_button The push-button view on the main window contains push buttons that correspond to debugger commands. You can modify, add, remove, and resequence push buttons and the commands associated with them. Use the default push buttons to complete the following functions. Push Button Function ------ -------- Stop Interrupts program execution or a debugger operation without ending the debugging session. Go Starts or resumes execution from the current program location. Step Executes the program one step unit of execution. By default, this is one executable line of source code. S-into (Step into) When execution is suspended at a routine call statement, moves execution into the called routine just past the start of the routine. If not at a routine call statement, this push button has the same behavior as the Step push button. S-ret (Step return) Executes the program directly to the end of the routine. S/call (Step call) Executes the program to the next call or return instruction. EX (Examine) Displays, in the command view, the current value of a variable whose name you have selected in a window. E/az Displays, in the command view, the current value of a variable whose name you have selected in a window. The variable is interpreted as a zero-terminated ASCII string. E/ac Displays, in the command view, the current value of a variable whose name you have selected in a window. The variable is interpreted as a counted ASCII string preceded by a one-byte count field that contains the length of the string. EVAL Displays, in the command view, the value of a language expression in the current language (by default, the language of the module containing the main program. MON (Monitor) Displays, in the monitor view, a variable name that you have selected in a window and the current value of that variable. Whenever the debugger regains control from your program, it automatically checks the value and updates the displayed value accordingly. 2 stop_btn_hlp =Title Stop Button in Push-Button View on Main Window =include debugui stop =include debugui cnt_button_hlp Use the Stop push button to interrupt program execution or a debugger operation without ending the debugging session. 2 msg_region_hlp =Title Command View on Main Window =include debugui popup_msgregion =include debugui cmd_entry =include debugui command_help =include debugui on_mwindow_hlp The command view on the main window accepts command-line entry input, echoes GUI actions (in a command-line format), and displays debugger messages. 2 popup_msgregion =Title Context-Sensitive Pop-up Menus in Command View =include debugui msg_region_hlp To use the pop-up menu in the command view, position your mouse pointer in the message region, and press MB3. The debugger automatically inserts your last command in the [last command] menu item of this pop-up menu. Menu items are as follows: Repeat Command Re-enters your last command. [last command] Clear Command Window Clears the command view and displays the DBG> prompt. Clear Command Line Clears command line. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 src_window_menubar_hlp =Title Menu Bar on Main Window =include debugui src_file_pd_menu_hlp =include debugui src_edit_pd_menu_hlp =include debugui src_break_pd_menu_hlp =include debugui src_commands_pd_menu_hlp =include debugui cnt_options_pd_menu_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp Use the menus on the menu bar as explained in the Additional Topics. 2 src_file_pd_menu_hlp =Title File Menu on Main Window =include debugui run_new_hlp =include debugui run_foreign_hlp =include debugui rerun_same_hlp =include debugui break_routine =include debugui src_display_module =include debugui browse_src_hlp =include debugui show_line_numb =include debugui server_connection_help Use the File menu on the main window as follows: Action Function ------ -------- Run Image... Brings a program under debugger control by specifying an executable image. Run Foreign Brings a program under debugger Command... control by specifying a foreign command symbol. Rerun Same... Reruns the same program under debugger control. Browse Sources Lists the modules in your program. You can choose to list all modules, or only those for which symbolic information is available. You can display the source code in any module of your program for which symbolic information is available. Can also be used to set breakpoints on routines. Display Line Displays or hides line numbers in the Numbers main window. Server Connection... (Client-Server only) Invokes the Server Connection dialog to allow you to set up and control a connection between a debug client and a debug server. Exit Debug? Exits from the debugger. If running in client-server mode, allows you to exit either the client, server, or both. 2 src_edit_pd_menu_hlp =Title Edit Menu on Main Window =include debugui cmd_entry Use the Edit menu on the main window as follows: Action Function ------ -------- Cut Cuts selected text from the current command line and copies it to the clipboard. If selected text is anywhere other than the current command line, copies the text to the clipboard. Copy Copies selected text from the window to the clipboard without removing it from the window. Paste Pastes text from the clipboard to the insert point on the current command line in the command view. See the DECwindows Motif documentation for more information. 2 src_break_pd_menu_hlp =Title Break Menu on Main Window =include debugui break =include debugui breakpoint_set_show_hlp =include debugui break_activ =include debugui break_exception Use the Break menu on the main window as follows: Action Function ------ -------- On Exception Breaks on any exception signaled during program execution. Activate All Activates all breakpoints that have not been canceled, causing the debugger to suspend program execution when a breakpoint is reached. Deactivate All Deactivates all breakpoints, causing the debugger to ignore them during program execution. Cancel All Removes all breakpoints from the debugger's database. You cannot reactivate these breakpoints without explicitly setting them first. Set... Displays the Set/Nodify Breakpoint dialog box to set an individual breakpoint (see Additional Topics). 2 src_commands_pd_menu_hlp =Title Commands Menu on Main Window =include debugui examine_hlp =include debugui examine =include debugui deposit_hlp =include debugui deposit =include debugui editor_hlp Use the Commands menu on the main window as follows: Action Function ------ -------- Examine... Examines the value of a variable or expression. Deposit... Changes the value of a variable. Edit File Opens the editable source window with the current file displayed. 2 cnt_options_pd_menu_hlp =Title Options Menu =include debugui options_viewsel_hlp =include debugui custm_db_hlp =include debugui custom_button =include debugui save_edit_options =include debugui restore_default_options =include debugui edit_options_file =include debugui custom_resource Use the Options menu on the main or the optional view window as follows: Action Function ------ -------- Views... Displays one or more of the debugger's optional views: Breakpoint View Monitor View Instruction View Threads View Register View .!Track Language Notify you when the debugger .! Changes enters a module written in .! a different source language .! than the previous module. Show Message Display a dotted line between Separators debugger messages and commands. Customize Adds, removes, or resequences Buttons... a push button in the push-button view. Also changes a button's label or the debugger command associated with a button. Save Options Saves the current definitions of the debugger user-interface options for use in subsequent debugger sessions. Restore Default Copies and saves the default definitions Options of the the debugger user-interface options for use in subsequent debugger sessions. Edit Options File Loads and displays local debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT in the Debug Editor for review and modification. 2 save_edit_options =include debugui restore_default_options =include debugui edit_options_file =Title Saving Debugger User-Interface Options The Save Options command in the Options menu of the source view saves the current definitions of the debugger user-interface options in the user-specific debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT. You can use the debugger editor or another editor to change the definitions in the debugger resource file. 2 restore_default_options =include debugui save_edit_options =include debugui edit_options_file =Title Restoring Default Debugger User-Interface Options The Restore Default Options in the Options menu of the source view copies the system default debugger resource file DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT to the user-specific debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT. It does not purge previous versions of the user-specific debugger resources file. You must exit and restart the debugger to invoke the default definitions in the restored debugger resource file. 2 edit_options_file =include debugui save_edit_options =include debugui restore_default_options =include debugui custom_resource =Title Editing Debugger User-Interface Options The Edit Options File in the Options menu of the source view loads and displays the local debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT in the Debug Editor for review and modification. If there is no local debugger resource file, the Debug Editor buffer is empty. To create a local debugger resource file, exit the Debug Editor and select Save Options or Restore Default Options from the Options menu of the source view. You must exit and restart the debugger to invoke the default definitions in the edited debugger resource file. 2 help_pd_menu_hlp =Title Help Menu =include debugui on_context =include debugui on_window =include debugui on_help =include debugui on_version =include debugui on_command =include debugui cmd_entry =include debugui on_help_hlp =include debugui on_mwindow_hlp The Help menu contains the following items that let you display online help about the debugger: On Context On Window On Help On Version On Commands For more information about using a Help menu item, double click on an item from the list of Additional Topics below. 2 run_new_hlp =Title Bringing a Program Under Debugger Control =include debugui run_foreign_hlp =include debugui rerun_same_hlp =include debugui src_file_pd_menu_hlp =include debugui starting_debugger =include debugui on_mwindow_hlp =include debugui ha_on_window_hlp After starting the debugger as explained in the topic Starting the Debugger, bring a program under debugger control using one of the following two techniques: - Run a specified image. This is the most common technique and is described below. - Run an image by specifying a symbol for a foreign command or a DCL command. This technique is described in the topic Running an Image by Specifying a Symbol. To run a specified image: 1. Choose Run Image... from the File menu on the main window. The Run Image... dialog box appears, which lists: - A Directories list that contains the parent directory and any subdirectories contained in the current directory - A Filter field; by default this specifies the .EXE files in your current directory - An Images list that contains the names of images in the current directory that meet the filter specification - An Arguments field to pass any required arguments to the image to be run - A Heap Analyzer button to run the Heap Analyzer - An Image field to display and specify the full file specification of the image to be run - An OK button to run the image specified in the Image field and dismiss the dialog box - A Filter button to display a list of files that meet the specification in the Filter field - A Cancel button to dismiss the dialog box without taking and further action - A Help button to display this help information 2. In the Directories list, click on the name of the appropriate subdirectory and click on Filter to list the (filtered) files in the subdirectory. The debugger also displays, in the Directories list, the parent directory and any subdirectories of the selected directory. 3. In the Images list, click on the name of the image to be debugged. The Image field now shows the image specification. You can edit this specification as needed. 4. If applicable, enter arguments to be passed to the program in the Arguments field. Quoted strings, may require additional quotation marks because the debugger strips quotes when parsing the string. 5. To run the Heap Analyzer, click the Heap Analyzer button. 6. Click on OK to dismiss the dialog box and run the spcified image. When the program is under debugger control, the debugger: - Displays the program's source code in the main window. - Suspends execution at the start of the main program. The current-location pointer, to the left of the source code, shows the line whose code will be executed next. The message displayed in the command view indicates the name of the main program unit and also indicates that the debugging session is initialized for the source language of the program. The initialization sets up language-dependent debugger parameters. These parameters control the way the debugger parses names and expressions, formats debugger output, and so on. You can now debug your program. With certain programs, the debugger suspends execution at the start of some initialization code, before the main program, and displays the following message: Type GO to reach main program With some of these programs (for example, Ada programs), the first breakpoint lets you debug the initialization code using full symbolic information. Note the following restrictions about running a program under debugger control: - You cannot use the procedure just described to connect the debugger to a running program. - You cannot run a program under debugger control over a DECnet link. Both the image to be debugged and the debugger must reside on the same node. 2 run_foreign_hlp =title Running an Image by Specifying a Symbol =include debugui run_new_hlp =include debugui rerun_same_hlp =include debugui cnt_file_pd_menu_hlp =include debugui starting_debugger =include debugui on_mwindow_hlp =include debugui ha_on_window_hlp To run an image by specifying a symbol for a foreign (DCL) command: 1. Choose Run Foreign Command... from the File menu on the main window. The Run Foreign Command dialog box appears. 2. Enter a symbol for a DCL command in the Foreign Command field. The symbol might be defined as "RUN long_file_name.ext" or a similar command. 3. Enter any arguments to be passed with the command in the Arguments field. If you specify a quoted string, you might have to add quotation marks because the debugger strips quotes when parsing the string. 4. To run the Heap Analyzer, click the Heap Analyzer button. 5. Click on OK. For information about startup conditions, see the Bringing a Program Under Debugger Control topic. 2 rerun_same_hlp =title Rerunning the Same Program =include debugui break_activ =include debugui run_new_hlp You can rerun the program currently under debugger control at any time during a debugging session. To rerun your program: 1. Choose Rerun Same... from the File menu on the main window. The Rerun Same dialog box appears. 2. If applicable, enter any arguments to be passed to the program in the Arguments field. 3. Choose whether to save or not save the current state of any breakpoints or static watchpoints that you previously set, activated, or deactivated. Nonstatic watchpoints might or might not be saved, depending on the scope of the variable being watched relative to the main program unit (where execution restarts). 4. To run the Heap Analyzer, click the Heap Analyzer button. 5. Click on OK. When you rerun a program, it is in the same initial state as a program that is initially brought under debugger control, except for any saved breakpoints or static watchpoints. The source display and current location pointer are updated accordingly. When you rerun a program, the debugger uses the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, choose Run Image... or Run Foreign Command... from the File menu on the main window. 2 browse_src_hlp =Title Browse Source Dialog Box =include debugui popup_browser =include debugui src_display_module =include debugui break_routine =include debugui src_file_pd_menu_hlp Use the Browse Source dialog box to: - Display the source code in any module of your program - Set breakpoints on routines 2 popup_browser =Title Context-Sensitive Pop-up Menus in Source Browser =include debugui browse_src_hlp To use pop-up menus in the Source Browser dialog box, position your mouse pointer in the dialog box, and press MB3. A pop-up menu with the following items appears: Expand Expand the selected image or module to include its component modules or functions in the Source Browser display. Collapse Collapse an expanded image, module, or function display. Display Source Display (in the source display of the source view on the main window) the source code associated with the selected module. Set Breakpoint Set a breakpoint on the selected function. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 show_line_numb =Title Displaying or Hiding Line Numbers =include debugui breakpoint_disp_hlp =include debugui custom_lineno =include debugui src_file_pd_menu_hlp To hide or display source line numbers in the main window, click on Show Line Numbers in the File menu of that window. Line numbers help you identify breakpoints that are listed in the breakpoint view. If you hide line numbers, more of the source code shows through a window of a given width. 2 exit_db_hlp =title Exit Debug? Confirmation Box =include debugui rerun_same_hlp =include debugui run_new_hlp To exit the kept debugger, which will terminate the current debugging session, click on Yes. Otherwise, click on No to return to the current session. In client-server mode, the default is to exit both the client and the server. Make sure that the correct buttons are selected, then click on OK to exit, or click on Cancel to return to the current session. 2 cancel_all_break_hlp =Title Cancel All Breakpoints Confirmation Box =include debugui break =include debugui src_break_pd_menu_hlp =include debugui cnt_break_pd_menu_hlp To cancel all breakpoints, click on Yes. Otherwise, click on No to preserve all breakpoints. 2 breakpoint_set_show_hlp =Title Set/Modify Breakpoint Dialog Box =include debugui break_cond =include debugui break_action =include debugui break If you are displaying the Set/Modify Breakpoint dialog box from the Set... menu item in the Break menu on the main or instruction window, use the Set/Modify Breakpoint dialog box to SET a conditional breakpoint or an action breakpoint. If you are displaying the Set/Modify Breakpoint dialog box from the Set/Modify... menu item in the Break menu on the optional view window use the Set/Modify Breakpoint dialog box to SET OR MODIFY a conditional breakpoint or an action breakpoint. When the Set/Modify Breakpoint dialog box appears, complete the fields as follows: Field Action ----- ------ Location field If the dialog box does not display the location of the breakpoint you are setting or modifying, enter the location using one of the following forms: \%line routine Condition field Optionally, enter a condition or edit an existing condition. The relational expression must be valid in the source language of the program module. Action field Optionally, enter an action or edit an existing action by substituting one or more new debugger commands (separated by a semi-colon). Activate/Deactivate Optionally, activate a deactivated Breakpoint button breakpoint by accepting the default, or deactivate an activated breakpoint by toggling this button. OK button Click on OK to set the breakpoint and dismiss the dialog box. Apply button Click on Apply to set the breakpoint and clear the dialog box. Cancel Breakpoint Click on Cancel Breakpoint to remove button a breakpoint. Note that you can no longer reactivate this breakpoint unless you again explicitly set it. Cancel button Click on Cancel to dismiss the dialog box. Help button Click on Help to display this help information. 2 examine_hlp =Title Examine Dialog Box =include debugui src_commands_pd_menu_hlp The Examine dialog box allows you to display the current value of a variable or expression in the command view. If you choose, you can change the type or output radix of the displayed value. To use the Examine dialog box, perform the following steps: 1. Do one of the following: - Find and select the variable name or expression symbols in a window, and choose the Examine menu item from the Commands menu on the main window. The Examine dialog box appears, with the name you selected in the Variable/Expression field. - Choose the Examine menu item from the Commands menu on the main window. The Examine dialog box appears. Enter the name of the variable or symbols of the expression you are examining in the Variable/Expression field of the dialog box. 2. If you are changing the output type, pull down the menu in the Typecast entry box and click on the desired data type. 3. If you are changing the output radix, pull down the menu in the Output Radix entry box and click on the desired radix. 4. Click on Apply to give the command or click on OK to give the command and dismiss the dialog box. Your echoed command and the current value appear in the command view. Click on Cancel to dismiss the dialog box. Click on Help to display this Help information. 2 deposit_hlp =Title Deposit Dialog Box =include debugui src_commands_pd_menu_hlp The Deposit dialog box allows you to change the current value of a variable. If you choose, you can change the input radix of the deposited value. To use the Deposit dialog box, perform the following steps: 1. Do one of the following: - Find and select the variable name in a window, and choose the Deposit menu item from the Commands menu on the main window. The Deposit dialog box appears, with the name you selected in the Variable field. - Choose the Deposit menu item from the Commands menu on the main window. The Deposit dialog box appears. Enter the name of the variable to which you are depositing a value in the Variable field of the dialog box. 2. Enter the value you are depositing in the Value field of the dialog box. 3. If you are changing the input radix, pull down the menu in the Input Radix entry box and click on the desired radix. 4. Click on Apply to give the command or click on OK to give the command and dismiss the dialog box. Your echoed command and the current value appear in the command view. Click on Cancel to dismiss the dialog box. Click on Help to display this Help information. Your echoed command appears in the command view, indicating that the value is changed. 2 editor_hlp =Title Editable Source Window =include debugui fill_buffer =include debugui search_text =include debugui recompile_edits =include debugui editor_pd_menu_hlp =include debugui editor_text_buffer_menu =include debugui src_commands_pd_menu_hlp Use the editable source window to edit the source code of the program you are currently debugging, or any other source code file. Location Function --------- ----------- Buffer Displays an empty text buffer for text entry, or a full text buffer containing the text you will edit. Search String Accepts a string for forward or backward search. Entry Box Directional Indicates the direction (forward, backward) of Arrows a search. Replace String Indicates whether search string is replaced when Toggle found. Replace String Accepts a string that replaces the specified Entry Box search string. Buffer Menu Provides a list of active buffers, any of which you can choose to display. 2 editor_find_hlp =Title Find Text Field in Editor Window =include Use the Find Text field to search for a specified string. The direction of the search is controlled as follows: - Press an arrow key to search text in the direction indicated by that arrow. This also sets the default search direction. - Press Ctrl/N to search forward (down) through the file, regardless of the arrow indicator position. - Press Ctrl/P to search backwards (up) through the file, regardless of the arrow indicator position. If you click the "Replace with" toggle button, the editor replaces each instance of the search string with the text entered in the Replace with field. 2 editor_replace_hlp =Title Replace With Field in Editor Window =include Use the Replace with field to replace a specified string. After you enter the search string in the Find Text field and indicate a search direction, click the "Replace with" toggle button and enter the replacement string. The editor replaces each instance of the search string with the replacement string. 2 editor_pd_menu_hlp =Title Menu Bar on Editable Source Window =include debugui editor_file_pd_menu_hlp =include debugui editor_edit_pd_menu_hlp =include debugui help_pd_menu_hlp Use the menus on the menu bar as explained in the Additional Topics. 2 fill_buffer =Title Editing Single and Multiple Text Buffers =include debugui editor_hlp By default,the editor window displays an empty text buffer, called dbg_editor_main. If you are debugging a program at the time you invoke the editor, however, the editor window displays this program, names the filled text buffer with its specification, and places dbg_editor_main on the buffer menu as an alternative text buffer. The editor allows you to create any number of text buffers by choosing New (for empty text buffers) or Open (for existing files) from the File menu. The name of each buffer appears in the buffer menu. You can cut, copy, and paste text across buffers by choosing items from the Edit menu and selecting buffers from the buffer menu. 2 search_text =Title Searching and Replacing Text =include debugui editor_hlp Forward and backward search and replace operations can be performed by entering strings in the Find text and Replace with entry boxes and clicking on a directional arrow. If you continue to click on a directional arrow, or if you continue to press the Return key, a repeated search for the string occurs in the direction you indicate. You can also continue a search by choosing the Find/Replace Next or Find/Replace Previous items in the Edit menu. 2 recompile_edits =Title Recompiling and Relinking Edited Source Code =include debugui editor_hlp When you complete your edits, and save these to your file by choosing the Save or Save As items from the editor's File menu, you need to recompile and relink your source file. You do not need to exit the debugger to do this. Enter the compile and link commands in another DECterm window, and when you return to the debugger, choose the Rerun Same item in the File menu on the main window. Your edited source code will appear in the debugger's source view. 2 editor_file_pd_menu_hlp =Title File Menu on Editor Window =include debugui editor_filesel_hlp =include debugui src_commands_pd_menu_hlp Use the File menu on the editable source window as follows: Action Function ------ -------- New Opens a buffer for a new file. Open... Opens a buffer for an existing file. Save Saves the current buffer using same file name. Save As... Saves the current buffer using specified file name. Close Closes the editable source window. Editor 2 editor_filesel_hlp =Title Open/Save Dialog Box =include debugui editor_hlp =include debugui src_commands_pd_menu_hlp Use the Open/Save dialog box to specify the file you are opening (before editing) or the file you are saving to (after editing), as follows: 1. If the default value (for your current directory) is not acceptable, click on the name of another directory from the directory list. 2. In the list of files, click on the file name you are opening or saving to. 3. Click on OK. 2 editor_edit_pd_menu_hlp =Title Edit Menu on Editor Window =include debugui src_commands_pd_menu_hlp Use the Edit menu on the editable source window as follows: Action Function ------ -------- Cut Cuts selected text from the window and copies it to the clipboard. Copy Copies selected text from the window to the clipboard without removing it from the window. Paste Pastes text from the clipboard to a text-entry field or region. Clear Clears the text selected (highlighted) in the window. Find/Replace Finds and replaces the next instance. Next (or Ctrl/N) Find/Replace Finds and replace the previous instance. Previous (or Ctrl/P) Refresh File Loads and displays the latest version of the file in the selected editor buffer. This is convenient for checking .LOG and other results files during debugging. Close File Removes the currently selected edit buffer from the display and menu, closes the file, and frees associated memory. Prompts the user to save or ignore any modifications to the edit buffer. 2 editor_text_buffer_menu =Title Buffer Menu on Editor Window =include debugui src_commands_pd_menu_hlp Use the Buffer menu on the editable source window as follows: Action Function ------ -------- None Identifies the text buffer that is currently active. Pull-down menu Identifies all other text buffers that are currently active, including the empty text buffer, dbg_editor_main. Clicking on Allows you to switch from one active a buffer in buffer to another. You can cut, copy, the pull-down and paste text across buffers by choosing menu items from the Edit menu and selecting buffers from the Buffer menu. 2 options_viewsel_hlp =Title Views Dialog Box =include debugui breakpoint_disp_hlp =include debugui monitor_disp_hlp =include debugui inst_workarea_hlp =include debugui register_view_hlp =include debugui task_view_hlp =include debugui cnt_options_pd_menu_hlp =include debugui on_owindow_hlp Use the Views dialog box as follows: Action Function ------ -------- File View Closes dialog box or exits debugger. Breakpoint View Displays the breakpoint view. Monitor View Displays the monitor view. Instruction View Displays the instruction view. Register View Displays the register view. Threads View Displays the threads view. 2 optional_view_sel_hlp =Title Views Dialog Box =include debugui breakpoint_disp_hlp =include debugui monitor_disp_hlp =include debugui inst_workarea_hlp =include debugui register_view_hlp =include debugui task_view_hlp =include debugui cnt_options_pd_menu_hlp =include debugui on_owindow_hlp Use the Views dialog box as follows: Action Function ------ -------- Breakpoint View Displays the breakpoint view. Monitor View Displays the monitor view. Instruction View Displays the instruction view. Register View Displays the register view. Threads View Displays the threads view. 2 views =title Displaying Views in the Optional View Window =include debugui on_owindow_hlp At startup, the debugger displays only one window, the main window. To display additional information on your program in the optional view window, perform the following steps: 1. Choose the Views... menu item from the Options menu on the main window. The Views dialog box appears. 2. Click on one or more of the following views in the dialog box: Breakpoint View Displays the breakpoint view. Monitor View Displays the monitor view. Instruction View Displays the instruction view. Register View Displays the register view. Threads View Displays the threads view. These views appear within the optional view window on your screen. To select different views, repeat this process, clicking on different views within the View dialog box. 2 close_views =Title Closing the Optional View Window =include debugui on_owindow_hlp To dismiss all views and close the optional view window, do one of the following: - Choose the Views... menu item from the Options menu on the main or optional view window. When the Views dialog box appears, clear all the toggle buttons within the dialog box, and click on OK. - Choose the Close menu item from the File menu on the optional view window to close the optional view window. - Choose the Close menu item from the File menu on the instruction window to close the instruction window. 2 custm_db_hlp =title Customize Dialog Box =include debugui custom_button =include debugui custm_add_hlp =include debugui custm_mod_hlp =include debugui custm_remove_hlp =include debugui custm_larrow_hlp =include debugui custm_rarrow_hlp =include debugui custom_resource =include debugui custom Use the Customize Button Dialog box to modify, add, remove, or resequence push buttons and the associated debugger commands. NOTE: You cannot modify or remove the Stop push button. 2 custm_add_hlp =title Add Button on Customize Dialog Box =include debugui custom_button =include debugui custm_db_hlp Use the Add push button to add a new push button to the push-button view in the main window. 2 custm_mod_hlp =title Modify Button on Customize Dialog Box =include debugui custom_button =include debugui custm_db_hlp Use the Modify push button to modify the label, icon, or debugger command associated with a push button in the push-button view. 2 custm_remove_hlp =title Remove Button on Customize Dialog Box =include debugui custom_button =include debugui custm_db_hlp Use the Remove push button to remove a push button from the push-button view in the main window. 2 custm_larrow_hlp =title Left Arrow Button on Customize Dialog Box =include debugui custom_button =include debugui custm_db_hlp Use the Left Arrow button to move a push button one push button to the left in the push-button view. 2 custm_rarrow_hlp =title Right Arrow Button on Customize Dialog Box =include debugui custom_button =include debugui custm_db_hlp Use the Right Arrow push button to move a push button one push button to the right in the push-button view. 2 on_context_hlp =Title On Context Item in Help Menu =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp Invisible: Brings up the ? pointer for context-sensitive help. 2 on_mwindow_hlp =title Using the Main Window =include debugui decwindows_basics =include debugui on_help_hlp =include debugui interfaces =include debugui windows_menus =include debugui run_new_hlp =include debugui src_display =include debugui execute =include debugui break =include debugui exam_deposit =include debugui stop =include debugui exit =include debugui rerun_same_hlp =include debugui starting_debugger =include debugui task =include debugui custom =include debugui cmd_entry =include debugui language_support The OpenVMS Debugger helps you locate run-time programming or logic errors, also known as bugs. You use the debugger with a program that has been compiled and linked successfully but does not run correctly. For example, the program might give incorrect output, go into an infinite loop, or terminate prematurely. You locate errors with the debugger by observing and manipulating your program interactively as it executes. The debugger lets you: - Display and edit the source code for your program, and browse through other source code files. - Monitor, examine, and change program variable and data structure values and examine their type. - Examine and manipulate the currently active functions on the call stack. - Set breakpoints that suspend program execution or issue debugger command sequences. - Step through execution one line of source code or machine instruction at a time. - Disassemble and examine machine code; examine and modify machine-register values. - Customize the debugging environment. These are the basic debugging techniques. After you are satisfied that you have found the error in the program, you can edit the source code and compile, link, and execute the corrected version. As you use the debugger and its documentation, you will discover variations on the basic techniques. You can also customize the debugger to meet your own needs. The debugger is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code. You do not need to specify memory addresses or registers when referring to program locations, but you can if you want. You can also use the debugger with programs written in any of the languages identified in the topic Debugger Support for Languages. 2 on_owindow_hlp =title Using the Optional View Window =include debugui on_help_hlp =include debugui views =include debugui break =include debugui monitor =include debugui variable =include debugui register =include debugui instruction =include debugui close_views =include debugui starting_debugger =include debugui task The OpenVMS Debugger helps you locate run-time programming or logic errors, also known as bugs. You use the debugger with a program that has been compiled and linked successfully but does not run correctly. For example, the program might give incorrect output, go into an infinite loop, or terminate prematurely. You locate errors with the debugger by observing and manipulating your program interactively as it executes. The debugger lets you: - Display and edit the source code for your program, and browse through other source code files. - Monitor, examine, and change program variable and data structure values and examine their type. - Examine and manipulate the currently active functions on the call stack. - Set breakpoints that suspend program execution or issue debugger command sequences. - Step through execution one line of source code or machine instruction at a time. - Disassemble and examine machine code; examine and modify machine-register values. - Customize the debugging environment. These are the basic debugging techniques. After you are satisfied that you have found the error in the program, you can edit the source code and compile, link, and execute the corrected version. As you use the debugger and its documentation, you will discover variations on the basic techniques. You can also customize the debugger to meet your own needs. The debugger is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code. You do not need to specify memory addresses or registers when referring to program locations, but you can if you want. You can also use the debugger with programs written in any of the languages identified in the topic Debugger Support for Languages. 2 on_ewindow_hlp =title Using the Editable Source Window =include debugui on_help_hlp =include debugui fill_buffer =include debugui search_text =include debugui recompile_edits Use the editable source window to edit the source code of the program you are currently debugging, or any other source code file. For information on tasks in the editable source window, see the Additional Topics below. 2 on_iwindow_hlp =title Using the Instruction View Window =include debugui on_help_hlp =include debugui instruction =include debugui break_identify =include debugui break_activ =include debugui break_instruction =include debugui break_cond =include debugui break_action Use the instruction window to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions For information on tasks in the instruction window, see the Additional Topics below. 2 on_help_hlp =title Using Debugger Online Help =include debugui context_sensitive_help =include debugui overview_help =include debugui command_help =include debugui msg_help =include debugui help_pd_menu_hlp Several 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 topics describing the tasks that can be accomplished in each window of the debugger and several subtopics on specific debugging tasks - Help on debugger commands and various topics, such as language support - Help on debugger diagnostic messages Related context-sensitive and task-oriented topics are connected through the list of Additional Topics in the Help windows. 2 on_version_hlp =Title About the OpenVMS Debugger =include debugui trademarks =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp =include debugui on_owindow_hlp =include debugui on_ewindow_hlp =include debugui on_iwindow_hlp OpenVMS Debugger Software Version: OpenVMS Debugger Version 8.4-1H1 Copyright 2015 VMS Software, Inc. All rights reserved. For more information about the OpenVMS Debugger, double click on Using the Main Window from the list of Additional Topics below. 2 on_command_hlp =Title On Commands Item in Help Menu =include debugui interfaces =include debugui cmd_entry =include debugui msg_region_hlp =include debugui command_help =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp 2 debug_error_hlp =Title Debugger Internal Errors The error dialog box contains a brief description of an internal inconsistency detected by the debugger. If the cause of the error is not obvious, select the Help Menu on the Main Window, select On_Commands, select Messages, and scroll through the display until you can select the message code that is displayed in the error dialog box. You may find more information about the error in the OpenVMS System Messages and Recovery Procedures manual. 2 breakpoint_disp_hlp =Title Breakpoint View =include debugui popup_break =include debugui break =include debugui break_identify =include debugui break_activ =include debugui break_cond =include debugui cnt_options_pd_menu_hlp Use the breakpoint view to do the following: - Identify the breakpoints that are currently set in your program - Review or change breakpoint status - Display conditions or actions associated with breakpoints - Modify conditions or actions associated with breakpoints - Set new breakpoints Breakpoints are listed in the Identification column of the view, including the module name and line number for each breakpoint. All breakpoints listed in the breakpoint view have been previously set. A filled-in button in the State column indicates that the breakpoint is set and active. A cleared button indicates that the breakpoint has been deactivated. (If you delete a breakpoint, the breakpoint entry disappears from the breakpoint view.) If you have set a conditional breakpoint, the button shape changes from a square to a diamond. You can also double-click on a breakpoint entry to determine whether conditions or actions are associated with it. 2 popup_break =Title Context-Sensitive Pop-up Menus in Breakpoint View =include debugui breakpoint_disp_hlp To use the pop-up menu in the breakpoint view, position your mouse pointer in the breakpoint list or annotation area of the breakpoint view, and press MB3. A pop-up menu with the following items appears: Toggle Toggles a selected breakpoint. Set/Modify... Provides the Set/Modify Breakpoint dialog box, which contains information about a selected breakpoint. Cancel Removes a selected breakpoint. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 monitor_disp_hlp =Title Monitor View =include debugui popup_monitor =include debugui monitor =include debugui cnt_button_hlp =include debugui watch =include debugui deposit =include debugui examine =include debugui exam_deposit =include debugui cnt_options_pd_menu_hlp Use the monitor view to: - Monitor the value of a variable or an expression during the execution of your program - Watch a variable during the execution of your program - Change the value of a variable To add an entry to the monitor list, select a variable name or expression in the source view and click on the Monitor push button. The debugger displays the current value in the monitor view and checks and updates the displayed value whenever it regains control from your program (for example, after a step or at a breakpoint). Monitored variables and expressions are listed in the Monitor Expression column. Their values are listed in the Value/Deposit column. The button in the Watched column indicates whether the variable is being watched (button filled) or not (button empty). 2 popup_monitor =Title Context-Sensitive Pop-up Menus in Monitor View =include debugui monitor_disp_hlp To use the pop-up menu in the monitor view, position your mouse pointer in the monitor view, and press MB3. A pop-up menu with the following items appears: Expand Expand a monitored aggregate to show its members. Collapse Collapse an expanded aggregate. Toggle Watchpoint Activates or deactivates a selected watchpoint. Typecast -> Provides the list of type choices for modifying values. Change Radix -> Provides the list of radix choices for modifying values. Remove Remove the selected expression from the monitor list of the monitor view. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 register_view_hlp =Title Register View =include debugui popup_register =include debugui register =include debugui cnt_options_pd_menu_hlp Use the register view to: - Display the current values stored in the machine registers. - Modify the value stored in a register Any values that change as your program executes are highlighted whenever the debugger regains control from your program. 2 popup_register =Title Context-Sensitive Pop-up Menus in Register View =include debugui register_view_hlp To use the pop-up menu in the register view, position your mouse pointer in the register view, and press MB3. A pop-up menu with the following menu items appears: Change Radix -> Provides the list of radix choices for modifying values. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 inst_view_hlp =Title Instruction View =include debugui popup_instruction =include debugui instruction =include debugui cnt_options_pd_menu_hlp Use the instruction view to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions 2 inst_workarea_hlp =Title Instruction View =include debugui popup_instruction =include debugui instruction =include debugui cnt_options_pd_menu_hlp Use the instruction view to: - Display the decoded instruction stream of your program - Set, activate, deactivate, or delete breakpoints on instructions 2 popup_instruction =Title Context-Sensitive Pop-up Menus in Instruction View =include debugui inst_workarea_hlp =include debugui inst_view_hlp To use pop-up menus in the instruction view, select text or position your mouse pointer in the instruction window, and press MB3. The debugger inserts the selected text or line number in the menu items of the pop-up menu. If you press MB3 while your mouse pointer rests on an instruction source line in the instruction window, a pop-up menu with the following items appears: Examine [selection] Evaluates the selected text and prints its value in the command view. Toggle Breakpoint Toggle breakpoint at your mouse pointer location. [line number] Display Source Display source associated with instruction. Step-Instructions Step to next instruction, stepping over routine calls. Step Step to next line, stepping over routine calls. Go Resume execution of program. If you press MB3 while your mouse pointer rests in the annotation area of the instruction window, a pop-up menu with the following items appears: Toggle Breakpoint Toggle breakpoint at your mouse pointer location. Step Step to next line, stepping over routine calls. Go Resume execution of program. 2 task_view_hlp =Title Thread View =include debugui task =include debugui cnt_task_pd_menu_hlp =include debugui cnt_options_pd_menu_hlp =include debugui popup_task Use the thread view to display information about the threads (tasks) of a multithreaded program. 2 task_workarea_hlp =Title Threads View =include debugui task =include debugui cnt_options_pd_menu_hlp =include debugui popup_task Use the threads view to display information about the threads (tasks) of a multithreaded program. 2 cnt_window_hlp =Title Threads View =include debugui task =include debugui cnt_options_pd_menu_hlp =include debugui popup_task Use the threads view to display information about the threads (tasks) of a multithreaded program. 2 popup_task =Title Context-Sensitive Pop-up Menus in Threads View =include debugui task_view_hlp =include debugui task_workarea_hlp =include debugui cnt_window_hlp To use pop-up menus in the threads view, select a thread from the list or position your mouse pointer in the threads view, and press MB3. A pop-up menu with the following menu items appears: Abort Requests that the selected thread be terminated at the next allowed opportunity. The exact effect depends on the current event facility (which is language dependent). For Ada tasks, this is equivalent to executing an abort statement. Activate Makes the selected thread the active thread. Hold Places the selected thread on hold. Nohold Releases the selected thread on hold. Visible Makes the selected thread the visible thread. 2 cnt_window_menubar_hlp =Title Menu Bar on Optional View Window =include debugui cnt_file_pd_menu_hlp =include debugui cnt_break_pd_menu_hlp =include debugui cnt_monitor_pd_menu_hlp =include debugui cnt_register_pd_menu_hlp =include debugui cnt_task_pd_menu_hlp =include debugui cnt_options_pd_menu_hlp =include debugui help_pd_menu_hlp =include debugui optional_view_sel_hlp Use the menus on the menu bar as explained in the Additional Topics. 2 cnt_file_pd_menu_hlp =Title File Menu on Optional View Window =include debugui close_views =include debugui exit Use the File menu on the optional view window as follows: Action Function ------ -------- Close Closes the optional view window. Exit Debug? In the kept debugger, ends the debugging session, and exits the debugger. In client-server mode, allows you to exit the client, server, or both. 2 cnt_break_pd_menu_hlp =Title Break Menu on Optional View Window =include debugui break_activ =include debugui break =include debugui break_exception Use the Break menu on the optional view window as follows: Action Function ------ -------- On Exception Breaks on any exception signaled during program execution. Activate All Activates any previously set breakpoints. Deactivate All Deactivates any previously set breakpoints. Cancel All... Removes all breakpoints from the debugger's breakpoint list and from the breakpoint view. Toggle Toggles an individual breakpoint. Set/Modify... Sets or modifies an individual breakpoint. Cancel Removes an individual breakpoint. 2 cnt_monitor_pd_menu_hlp =Title Monitor Menu on Optional View Window =include debugui monitor Use the Monitor menu on the optional view window as follows: Action Function ------ -------- Expand Expands a selected nonscalar variable. Collapse Collapses a selected nonscalar variable. Deposit... Changes the value of variable. Toggle Watchpoint Activates or deactivates a watchpoint. Typecast -> Typecasts a selected variable. Change Radix -> Changes the radix for a selected variable. Change All Radix -> Changes the default radix for all subsequent monitor entries. Remove Removes the monitor entry from display. 2 cnt_register_pd_menu_hlp =Title Register Menu on Optional View Window =include debugui register Use the Register menu on the optional view window as follows: Action Function ------ -------- Assign... Modifies the selected register. Change Radix -> Changes the radix for a selected register. Change All Radix -> Changes the radix for all registers. 2 cnt_task_pd_menu_hlp =Title Tasks Menu on Optional View Window =include debugui task =include debugui cnt_options_pd_menu_hlp Use the Threads menu on the optional view window as follows: Action Function ------ -------- Abort Requests that the selected thread be terminated at the next allowed opportunity. The exact effect depends on the current event facility (which is language dependent). For Ada tasks, this is equivalent to executing an abort statement. Activate Makes the selected thread the active thread. Hold Places the selected thread on hold. Nohold Releases the selected thread on hold. Make Makes the selected thread the visible thread. Visible All -> Uses the submenu to: Abort all threads. Hold all threads. NoHold all threads. 2 inst_window_menubar_hlp =Title Menubar on Instruction Window =include debugui inst_file_pd_menu_hlp =include debugui inst_edit_pd_menu_hlp =include debugui inst_break_pd_menu_hlp =include debugui help_pd_menu_hlp Use the menus on the menu bar as explained in the Additional Topics. 2 inst_file_pd_menu_hlp =Title File Menu on Instruction View =include debugui instruction =include debugui inst_workarea_hlp Use the File menu on the Instruction View as follows: Action Function ------ -------- Show Instruction Displays the address associated Addresses with each instruction listed in the instruction view. Display Line Displays the line number of your Numbers source-code program associated with each instruction or set of instructions listed in the instruction view. Close Closes the instruction window. 2 inst_edit_pd_menu_hlp =Title Edit Menu on Instruction View =include debugui instruction =include debugui inst_workarea_hlp Use the Edit menu on the instruction view as follows: Action Function ------ -------- Copy Copies text that you have selected in the window to the clipboard without removing it from the window. (To paste your text from the clipboard to a text-entry field or region, choose the Paste item from the Edit menu on the main window.) 2 inst_break_pd_menu_hlp =Title Break Menu on Instruction Window =include debugui break_activ =include debugui break =include debugui break_exception Use the Break menu on the instruction window as follows: Action Function ------ -------- Activate All Activates any previously set breakpoints. Deactivate All Deactivates any previously set breakpoints. Cancel All Removes all breakpoints from the debugger's breakpoint list and from the instruction view. Set... Sets an individual breakpoint. 2 server_connection_help =Title Server Connection Dialog =include debugui conn_dialog_connect =include debugui conn_dialog_disconnect =include debugui conn_dialog_stop =include debugui conn_dialog_test =include debugui conn_dialog_options =include debugui conn_dialog_cancel =include debugui conn_dialog_connections =include debugui conn_dialog_active_sessions The Connection dialog is used to manage connections between a DECwindows Motif debug client and a debug server running on OpenVMS. You can use the Server Connection dialog to make new connections to servers, reconnect to servers that you have connected to before, monitor the status of existing active sessions, switch the display context among active sessions, test and shutdown servers, and limit the number of clients that a server will accept. See Additional Topics for specific information about the Server Connection dialog. To display the Server Options dialog of the Connection dialog box, click the Properties button, or open the Options menu, then click Connection dialog on the Properties submenu. Click sections of the Connection dialog box below to see a description of each control on the dialog box. Please refer to the OpenVMS Debugger manual for more information.. 2 conn_dialog_connect =Title Server Connection Dialog - Connect =include debugui conn_dialog_connections =include debugui server_connection_help Click Connect to initiate the connection request to the server identified in the Connection list. Status of the connection request is displayed in the message display of the Command view. Additional status is displayed at the bottom of the Server Connection dialog to indicate whether the requested connection has been established as a new active session. When a connection has been successfully made to a server the Server Connection dialog is dismissed and the Command view displays a client prompt to indicate that the server is ready to accept debugger commands. A new Source view is created, and all other active views display information in the context of the active session. 2 conn_dialog_disconnect =Title Server Connection Dialog - Disconnect =include debugui conn_dialog_active_sessions =include debugui server_connection_help Click Disconnect to disconnect the client from the currently active session as indicated in the Active Sessions list. 2 conn_dialog_test =Title Server Connection Dialog - Test =include debugui server_connection_help Click Test to test the connection between the debug client and the debug server. If the connection is operating correctly, the status "Server is Listening" appears in the lower portion of the Connection dialog box. 2 conn_dialog_stop =Title Server Connection Dialog - Stop =include debugui server_connection_help Click Stop to cause the debug server associated with the currently active session to be shut down. Note: Once a server has been shut down, clients can no longer connect to it. To restart a server, type DEBUG/SERVER at the command prompt on the OpenVMS system. 2 conn_dialog_options =Title Server Connection Dialog - Options =include debugui conn_dialog_active_sessions =include debugui c_s_primary_client =include debugui c_s_secondary_client =include debugui server_connection_help Click Options in the Server Connection dialog to display the Server Options dialog for the currently selected session as indicated by the Active Sessions list in the Server Connection dialog. The Server Options dialog lets you select the connection protocol, and the maximum number of clients that are allowed to connect to a server. Once a session has been established, you cannot change the connection protocol. If you are the first client (the primary client) to connect to a server, you can control the maximum number of secondary clients that are allowed to connect to the server. 2 c_s_primary_client =Title Primary Client =include debugui conn_dialog_options =include debugui c_s_secondary_client =include debugui server_connection_help The primary client is the first client to connect to the server. The primary client uses the Server Options dialog to control whether or not any secondary clients can connect to the server. 2 c_s_secondary_client =Title Secondary Client =include debugui c_s_primary_client =include debugui conn_dialog_options =include debugui server_connection_help A secondary client is an additional client that has connected to the same server. Each clients that is connected to a session can enter debugger commands in the context of that session. The debugger display of each client connected to that session is updated reflect the current context of the session. Whether or not secondary clients are allowed is controlled by the primary client in the Server Options dialog. 2 conn_dialog_connections =Title Server Connection Dialog - Connection List =include debugui server_connection_help Use the Connection [local] list to specify the identification string of the debug server with which you want to establish a session. Type or select the identification string in the New Connection box. The New Connection list contains the last 10 connections that you have made and provides a convenient way to reconnect to a server from which you previously disconnected and left running. Note that the presence of a connection path in the list does not guarantee that the server is still available The most simple connection string contains the name of the OpenVMS node followed by the port number within square brackets. For example: NODNAM[4111] Other examples of valid connection strings: ncacn_ip_tcp:16.32.16.138[4111] 16.32.16.138 nodnam.bld.dec.com nodnam.bld.dec.com[4112] ncacn_dnet_nsp:19.10[RPC2BE08EF00001] 2 conn_dialog_active_sessions =Title Server Connection Dialog - Active Sessions List =include debugui server_connection_help The Active Sessions list contains the sessions (connections to debug servers) that this client has already established. The session at the top of the list is the currently active session. All debugger views reflect the context of the program being debugged on the currently active session. You can switch between active sessions by selecting a session from the Active Sessions list. The Source view for that session is activated and all other debugger views are updated to reflect the program context of that session. All buttons on the Server Connection dialog, including Disconnect, Stop Server, Test and Properties as well as the status section of the Server Connection dialog are related to and act upon the currently active session. 2 conn_dialog_cancel =Title Server Connection Dialog - Cancel =include debugui server_connection_help Click Cancel to dismiss the Server Connection dialog. 2 interfaces =title Debugger User-Interface Options =include debugui windows_menus =include debugui cmd_entry =include debugui custom_button =include debugui on_mwindow_hlp The debugger has the following user-interface options to accommodate different needs and debugging styles: - The debugger has a DECwindows Motif interface for workstations. The default DECwindows Motif interface provides the basic debugging and convenience features that you will probably need most of the time. - The debugger has a command interface for character-cell terminals and workstations. In addition to general-purpose debugging features, the command interface provides special features not available through the default DECwindows Motif interface. - The DECwindows Motif interface is layered on the command interface and has a command-entry prompt (in the command view of the main window). From the DECwindows Motif interface, you can enter debugger commands for the following purposes: + As an alternative to using the DECwindows Motif interface for certain operations + To do tasks not available through the DECwindows Motif interface - You can customize the DECwindows Motif interface with many of the special features of the command interface by modifying the push buttons in the push-button view (and their associated debugger commands) or by adding new push buttons. 2 windows_menus =title Debugger Main Window at Startup =include debugui src_workarea_hlp =include debugui starting_debugger =include debugui run_new_hlp =include debugui on_mwindow_hlp By default, the debugger starts up in the main window, which includes a source view, a push-button view, and a command view. When you start the debugger with the command DEBUG/KEEP from DCL level, the source view is initially empty. You can then bring a program under debugger control. 2 cmd_entry =Title Entering Commands at the Prompt =include debugui command_help =include debugui disabled_vms_cmds =include debugui custom_button =include debugui on_mwindow_hlp The debugger's DECwindows Motif interface is layered on the command interface. The command-entry prompt (DBG>), located in the command view, lets you enter debugger commands for the following purposes: - As an alternative to using the DECwindows Motif interface for certain operations - To do debugging tasks not available through the DECwindows Motif interface When you use the DECwindows Motif interface, the debugger translates your input into debugger commands. These commands are echoed in the command view, at the prompt, so that you can correlate your input with the corresponding command line that the debugger processes. Echoed commands are visually indistinguishable from commands that you enter explicitly. In addition to entering debugger commands interactively at the prompt, you can also enter them in debugger initialization files and command files for execution under the DECwindows Motif environment. 2 disabled_vms_cmds =title Debugger Commands Not Available in DECwindows Motif Interface =include debugui cmd_entry =include debugui msg_region_hlp =include debugui command_help The following table lists the debugger commands that are not available in the debugger's DECwindows Motif interface. Many of them are relevant only to the command interface's screen mode. ATTACH SELECT CANCEL MODE (SET,SHOW) ABORT_KEY CANCEL WINDOW (SET,SHOW) KEY DEFINE/KEY (SET,SHOW) MARGINS DELETE/KEY SET MODE [NO]KEYPAD DISPLAY SET MODE [NO]SCREEN EXAMINE/SOURCE SET MODE [NO]SCROLL EXPAND SET OUTPUT [NO]TERMINAL EXTRACT (SET,SHOW) TERMINAL HELP (SET,SHOW) WINDOW MOVE (SHOW,CANCEL) DISPLAY SAVE SHOW SELECT SCROLL SPAWN The debugger issues an error message if you try to enter any of these disabled commands at the command-entry prompt, or when the debugger executes a command procedure containing any of these commands. 2 language_support =title Debugger Support for Languages =include debugui on_help_hlp =include debugui on_mwindow_hlp On VAX processors, you can use the debugger with programs written in any of the following source languages: Ada BASIC BLISS C C++ COBOL DIBOL Fortran MACRO-32 Pascal PL/I RPG II SCAN On Alpha processors, you can use the debugger with programs written in any of the following source languages: Ada BASIC BLISS C C++ COBOL Fortran MACRO-32 MACRO-64 Pascal PL/I On I64 processors, you can use the debugger with programs written in any of the following source languages: Assembler (IAS) BASIC BLISS C C++ COBOL Fortran MACRO-32 IMACRO Pascal The debugger recognizes the syntax, data types, operators, expressions, scoping rules, and other constructs of a supported language. For more information about debugger support for a particular language: 1. Choose On Commands from the Help menu in a debugger window. 2. Choose Language_Support from the list of Additional Topics. 3. Choose the language name from the list of Additional Topics. 2 trademarks =title Additional Trademark and Product Information =include debugui on_version_hlp Confidential computer software. Valid license from VSI required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice. The only warranties for VSI products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. VSI shall not be liable for technical or editorial errors or omissions contained herein. Intel® and Itanium® are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. 2 compile =title Compiling and Linking Your Program for Debugging =include debugui language_support =include debugui starting_debugger =include debugui run_new_hlp =include debugui on_mwindow_hlp To bring a program under debugger control and take full advantage of symbolic debugging, you must first compile and link the program as explained here. You can use the debugger with programs written in any of the source languages listed in the topic Debugger Support for Languages. The following example shows how to compile and link a C program named EIGHTQUEENS before using the debugger. The compiler and linker are invoked from DCL level ($). The program's source code is in the file EIGHTQUEENS.C. On VAX systems, you explicitly identify linker options files in your LINK command: $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS $ LINK/DEBUG EIGHTQUEENS,OPTIONS_FILE/OPTIONS On Alpha and I64 systems, you do not identify linker options files: $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS $ LINK/DEBUG EIGHTQUEENS The /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults for some languages. These qualifiers are used in the example for emphasis. (For more information about compiling and linking that is specific to a particular language, see the documentation furnished with that language.) The /DEBUG qualifier on the compiler command (CC in this case) directs the compiler to write the symbol information associated with EIGHTQUEENS.C into the object module, EIGHTQUEENS.OBJ, in addition to the code and data for the program. This symbol information lets you use the names of variables, routines, and other symbols declared in EIGHTQUEENS.C when using the debugger. If your program's source code is in several files, you must compile each file whose symbols you want to reference with the /DEBUG qualifier. Some compilers optimize the object code to reduce the size of the program or to make it run faster. In such cases you should compile your program with the /NOOPTIMIZE command qualifier (or equivalent) when preparing for debugging. Otherwise, the contents of some program locations might be inconsistent with what you would expect from viewing the source code. For example, some optimization techniques eliminate certain variables so that you no longer have access to them while debugging. (After the program has been debugged, you will probably want to recompile it without the /NOOPTIMIZE qualifier to take advantage of optimization.) The /DEBUG qualifier on the LINK command directs the linker to include all symbol information that is contained in EIGHTQUEENS.OBJ in the executable image. The qualifier also causes the image activator to start the debugger at run time if you start the debugger by running a program, using the following DCL command syntax: $ DEBUG/KEEP If your program has several object modules, you need to specify those modules in the LINK command (for most languages). On VAX processors, the /OPTIONS qualifier indicates that OPTIONS_FILE is a linker options file. In the OpenVMS VAX example, the file specifies a run-time library to be linked with the program. Even if you compile and link an image with the /DEBUG command qualifier, you can execute that image normally without it being under debugger control. To do so, use the /NODEBUG qualifier on the DCL RUN command. For example: $ RUN/NODEBUG EIGHTQUEENS This is convenient for checking your program after you think it is error free. Note that the data required by the debugger occupies space within the executable image. So, when you think your program is correct, you might want to link your program again without the /DEBUG qualifier. This creates an image with only traceback data in the debug symbol table, which uses less disk space. On Alpha and I64 systems, you can debug programs that have been linked with the /DSF qualifier (and therefore have a separate debug symbol file). The /DSF qualifer to the LINK command directs the linker to create a separate .DSF file to contain the symbol information. This allows more flexible debugging options. Debugging such a program requires the following: 1. The name of the .DSF file must match the name of the .EXE file being debugged. 2. You must define DBG$IMAGE_DSF_PATH to point to the directory that contains the .DSF file. For example: $ CC/DEBUG/NOOPTIMIZE TESTPROGRAM $ LINK/DSF=TESTDISK:[TESTDIR]TESTPROGRAM.DSF TESTPROGRAM $ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR] $ DEBUG/KEEP TESTPROGRAM 2 stop =title Interrupting Program Execution and Debugger Operations =include debugui run_new_hlp =include debugui rerun_same_hlp =include debugui on_mwindow_hlp To interrupt program execution during a debugging session, click on the Stop push button on the push-button view in the main window. This is useful if, for example, the program is in an infinite loop. To abort a debugger operation in progress, click on Stop. This is useful if, for example, the debugger is displaying a long stream of data. Clicking on Stop does not end the debugging session. Clicking on Stop when the program is not running or when the debugger is not doing an operation has no effect. 2 exit =title Ending a Debugging Session =include debugui rerun_same_hlp =include debugui run_new_hlp To end a debugging session and exit the debugger, choose Exit Debug? from the File menu on the main window. This invokes a Confirm Exit dialog box to verify that you wish to exit the debugger. In the kept debugger, clicking on Yes returns control to system level. In client-server mode, allows you to exit the client, the server, or both. To rerun your program from the current debugging session, see the Rerunning the Same Program topic. To run another program from the current debugging session, see the Bringing a Program Under Debugger Control topic. 2 src_display =title Displaying the Source Code of Your Program =include debugui break_identify =include debugui callstack_menu_hlp =include debugui src_display_module =include debugui src_display_nosrc =include debugui setscope =include debugui src_display_srcfile =include debugui compile =include debugui on_mwindow_hlp The debugger displays the source code of your program in the source view of the main window. Whenever execution is suspended (for example, at a breakpoint), the debugger updates the source view, which displays the code surrounding the point at which execution is paused. The current-location pointer, to the left of the source code, marks the line whose code will execute next. (A source line corresponds to one or more programming language statements, depending on the language and coding style.) By default, the debugger displays compiler-generated line numbers to the left of the source code. These numbers help you identify breakpoints that are listed in the breakpoint view. You can choose not to display line numbers so that more of the source code can show in the window. To hide or display line numbers, choose Show Line Numbers from the File menu on the main window. The Call Stack menu, at the bottom right of the source window, shows the name of the routine whose source code is displayed. The current-location pointer is normally filled in. It is cleared if the displayed code is not that of the routine in which execution is paused (see the Making Source Code Available for Display and the Setting the Current Scope Relative to the Call Stack topics). You can use the scroll bars to show more of the source code. However, you can scroll vertically through only one module of your program at a time. (A module corresponds generally to a compilation unit. With many programming languages, a module corresponds to the contents of a source file. With some languages, such as Ada, a source file might contain one or more modules.) The Displaying Source Code in Another Module topic explains how to display source code for other parts of your program so that you can set breakpoints in various modules, and so on. The Making Source Code Available for Display topic explains what to do if the debugger cannot find source code for display. The Setting the Current Scope Relative to the Call Stack topic explains how to display source code for routines that are currently active on the call stack. After navigating through the source view, you can redisplay the location at which execution is paused by clicking on the Call Stack menu. If your program was optimized during compilation, the source code displayed might not reflect the actual contents of some program locations (see the Compiling and Linking Your Program for Debugging topic). 2 src_display_module =Title Displaying Source Code in Another Module =include debugui src_display To display source code in another module: 1. Choose Browse Source from the File menu on the main window. From the submenu, select All to list all modules, select Symbolic to list only those modules for which symbolic information is available. The Browse Source dialog box appears, listing your executable image, which is highlighted, and all the shareable images linked with it (for example, DEBUG and LIBRTL). If the name of an image is dimmed, no symbolic information is available for that image. 2. Double click on the name of your executable image. The names of the modules in that image are displayed (indented) under the image name. 3. Click on the name of the module whose source code you want to display. The Display Source button is now highlighted. 4. Click on Display Source. The source view now displays that module's source code. 2 src_display_nosrc =Title Making Source Code Available for Display =include debugui step_return =include debugui src_display_srcfile =include debugui src_display In certain cases, the debugger cannot display source code. Possible causes are: - Execution might be paused within a module of your program that was compiled without the debug option. - Execution might be paused within a system or library routine for which no symbolic information is intended to be available. In such cases you can quickly return execution to the calling routine by clicking one or more times on the Step-Return push button on the push-button view of the main window. - The source file might have been moved to a different directory after it was compiled. The Specifying the Location of Source Files topic explains how to tell the debugger where to look for source files. If the debugger cannot find source code for display, it tries to display the source code for the next routine down on the call stack for which source code is available. If the debugger can display source code for such a routine, the current-location pointer is cleared and marks the source line to which execution returns in the calling routine. 2 src_display_srcfile =Title Specifying the Location of Source Files =include debugui cmd_entry =include debugui src_display Information about the characteristics and the location of source files is embedded in the debug symbol table of your program. If a source file has been moved to a different directory since compile time, the debugger might not find the file. To direct the debugger to your source files, use the SET SOURCE command at the command-entry prompt. 2 execute =title Executing Your Program =include debugui exec_paused =include debugui start_exec =include debugui step_one_line =include debugui step_in =include debugui step_return =include debugui rerun_same_hlp =include debugui run_new_hlp =include debugui on_mwindow_hlp The Additional Topics explain techniques for executing your program. 2 exec_paused =title Determining Where Execution is Currently Paused =include debugui src_display =include debugui callstack_menu_hlp =include debugui execute To determine where execution is currently paused within your program: 1. If the current-location pointer is not visible in the source view, click on the Call Stack menu of that window to display the pointer. 2. Look at the current-location pointer: - If the pointer is filled in, it marks the source line whose code will execute next. The Call Stack menu always shows the routine at level 0 (where execution is paused) when the pointer is filled in. - If the pointer is cleared, the source code displayed is that of a calling routine, and the pointer marks the source line to which execution returns in that routine as follows: + If the Call Stack menu shows level 0, source code is not available for display for the routine in which execution is paused. + If the Call Stack menu shows a level other than 0, you are displaying the source code for a calling routine. To list the sequence of routine calls that are currently active on the call stack, click on the Call Stack menu. Level 0 denotes the routine in which execution is paused, level 1 denotes the calling routine, and so on. 2 start_exec =title Starting or Resuming Program Execution =include debugui cnt_button_hlp =include debugui break =include debugui src_display =include debugui execute To start program execution or resume execution from the current location, click on the Go push button on the push-button view of the main window. Letting your program run freely without debugger intervention is useful in situations such as the following: - To test for an infinite loop. In this case, you start execution; then, if your program does not terminate and you suspect that it is looping, click on the Stop push button. The source view will show where you interrupted program execution, and the Call Stack menu will identify the sequence of routine calls at that point. - To execute your program directly to a particular location. In this case, you first set a breakpoint at the location and then start execution. Once started, program execution continues until one of the following events occurs: - The program completes execution - A breakpoint is reached (including a conditional breakpoint whose condition is true) - A watchpoint is triggered - An exception is signaled - You click on the Stop push button in the push-button view on the main window. Whenever the debugger suspends execution of the program, the source view is updated and the current-location pointer marks the line whose code will execute next. 2 step_one_line =title Executing Your Program One Source Line at a Time =include debugui cnt_button_hlp =include debugui src_display =include debugui compile =include debugui execute To execute one source line of your program, click on the Step push button on the push-button view of the main window. This debugging technique (called stepping) is one of the most commonly used. After the line executes, the source view is updated and the current-location pointer marks the line whose code will execute next. Note the following points about source lines and the stepping behavior: - A source line can consist of one or more programming language elements, depending on the language and coding style used. - When you click on the Step push button, the debugger executes one executable line and suspends execution at the start of the next executable line, by skipping over any intervening nonexecutable lines. - Executable lines are those for which instructions were generated by the compiler (for example, lines with routine call or assignment statements). Executable lines have a toggle button to their left in the source view. - Examples of nonexecutable lines are comment lines or lines with variable declarations without value assignments. Nonexecutable lines do not have a toggle button to their left in the source view. Keep in mind that if you optimized your code at compilation time, the source code displayed might not reflect the code that is actually executing. 2 step_in =title Stepping into a Called Routine =include debugui break =include debugui cnt_button_hlp =include debugui src_display =include debugui setscope =include debugui execute When program execution is paused at a routine call statement, clicking on the Step push button typically executes the called routine in one step (depending on the coding style used), and the debugger suspends execution at the next source line in the calling routine (assuming no breakpoint was set within the called routine). This lets you step through the code quickly without having to trace execution through any called routines (some of which might be system or library routines). This is called stepping over called routines. To step into a called routine so that you can execute it one line at a time: 1. Suspend execution at the routine call statement, for example, by setting a breakpoint (see the Suspending Execution with Breakpoints topic) and then clicking on the Go push button on the push-button view of the main window. 2. When execution is paused at the call statement, click on the Step-In push button on the push-button view of the main window. This moves execution just past the start of the called routine. Once execution is within the called routine, use the Step push button to execute the routine line by line. Clicking on the Step-In push button when execution is not paused at a routine call statement is the same as clicking on the Step push button. 2 step_return =title Returning from a Called Routine =include debugui cnt_button_hlp =include debugui src_display =include debugui src_display_nosrc =include debugui setscope =include debugui execute When execution is suspended within a called routine, you can execute your program directly to the end of that routine by clicking on the Step-Return push button on the push-button view of the main window. The debugger suspends execution just before the routine's return instruction executes. At that point, the routine's call frame has not been deleted from the call stack, so you can still get the values of variables local to that routine, and so on. The Step-Return push button is particularly useful if you have inadvertently stepped into a system or library routine. 2 break =title Suspending Execution with (Setting) Breakpoints =include debugui break_identify =include debugui break_activ =include debugui break_srclin =include debugui break_routine =include debugui break_exception =include debugui break_cond =include debugui break_action A breakpoint is a location in your program at which you want execution to stop so that you can check the current value of a variable, step into a routine, and so on. When using the debugger's DECwindows Motif interface, you can set breakpoints on: - Specific source lines - Specific routines (functions, subprograms, and so on) - Specific instructions (displayed in the instruction view) - Exceptions signaled during the execution of your program The debugger provides two ways to qualify breakpoints: - You can set a conditional breakpoint. It triggers only when a specified relational expression is evaluated as true. - You can set an action breakpoint. It executes one or more specified system-specific commands when the breakpoint triggers. You can set a breakpoint that is both a conditional and action breakpoint. 2 break_srclin =title Setting Breakpoints on Source Lines =include debugui src_display =include debugui break You can set a breakpoint on any source line that has a toggle button to its left in the source view. These are the lines for which the compiler has generated executable code (routine declarations, assignment statements, and so on). To set a breakpoint on a source line: 1. Find the source line on which you want to set a breakpoint. 2. Click on the toggle button to the left of that line. (The breakpoint is set when the toggle button is filled in.) The breakpoint is set at the start of the source line--that is, on the first machine-code instruction associated with that line. 2 break_routine =Title Setting Breakpoints on Routines =include debugui break Setting a breakpoint on a routine lets you move execution directly to the routine and inspect the local environment. To set a breakpoint on a routine: 1. Choose Browse Source from the File menu on the main window. From the submenu, select All to list all modules, select Symbolic to list only those modules for which symbolic information is available. The Browse Source dialog box appears listing your executable image, which is highlighted, and all the shareable images linked with it (for example, DEBUG and LIBRTL). If the name of an image is dimmed, no symbolic information is available for that image. 2. Double click on the name of your executable image. The names of the modules in that image are displayed (indented) under the image name. 3. Double click on the name of the module whose source code you want to display. The names of the routines in that module are displayed in the Routine column. 4. Do one of the following: - Double-click on the name of the routine on which you want to set a breakpoint. - Click on the name of the routine and then on the Set Breakpoint button. Either of these actions sets a breakpoint at the start of the routine (directly after any prolog code). In the source view, the toggle button to the left of the source line that contains the start of the routine is now filled in, confirming that the breakpoint is set. (If the breakpoint view is open, the breakpoint will appear in the breakpoint list. If the instruction window is open, the breakpoint will also display for the corresponding instruction.) 2 break_instruction =title Setting Breakpoints on Instructions =include debugui inst_workarea_hlp =include debugui on_iwindow_hlp You can set a breakpoint on any instruction that has a toggle button to its left in the annotation area. These are the lines for which the compiler has generated executable code (routine declarations, assignment statements, and so on). To set a breakpoint on an instruction: 1. Find the instruction on which you want to set a breakpoint. 2. Click on the toggle button to the left of that line. (The breakpoint is set when the toggle button is filled in.) 2 break_exception =title Setting an Exception Breakpoint =include debugui src_break_pd_menu_hlp =include debugui cnt_break_pd_menu_hlp =include debugui break An exception breakpoint suspends execution when an exception is signaled and before any exception handler declared by your program executes. This allows you to step into the exception handler (if one is available) to check the flow of control. To set an exception breakpoint, choose On Exception from the Break menu. The exception breakpoint triggers whenever any exception is signaled. 2 break_identify =title Identifying the Currently Set Breakpoints =include debugui break_activ =include debugui src_display =include debugui break There are two ways to determine which breakpoints are currently set: - Scroll through your source or instruction code and note the lines whose breakpoint button is filled in. This method can be time consuming and also does not show which breakpoints were set and then deactivated. - Choose Views... from the Options menu on the main or optional view window. When the Views dialog box appears, toggle breakpoint view. Within the breakpoint view display, breakpoints are listed in the Identification column of the view, including the module name and line number for each breakpoint. A filled-in button in the State column indicates that the breakpoint is set and active. A cleared button indicates that the breakpoint is deactivated. (The breakpoint view does not provide information on breakpoints that have not been set or that have been deleted.) 2 break_activ =title Deactivating, Activating, Canceling Breakpoints =include debugui break_srclin =include debugui break_routine =include debugui break_instruction =include debugui break After you set a breakpoint, you can deactivate it, activate it, or cancel it. Deactivating a breakpoint causes the debugger to ignore it during program execution. However, the debugger keeps the breakpoint listed in the breakpoint view so that you can activate it at a later time, for example, when you rerun the program. Note the following points: - To deactivate a specific breakpoint, clear the button for that breakpoint in the source view, the instruction code display, or in the breakpoint view. In the breakpoint view, you can also choose Toggle from the Break menu, if the breakpoint is currently activated. - To deactivate all breakpoints, choose Deactivate All from the Break menu on the main, instruction, or optional view window. Activating a breakpoint causes it to take effect during program execution: - To activate a breakpoint, click on the button for that breakpoint in the source view, instruction code display, or in the breakpoint view. In the breakpoint view, you can also choose Toggle from the Break menu, if the breakpoint is currently deactivated. - To activate all breakpoints, choose Activate All from the Break menu on the main, instruction, or optional view window. Canceling a breakpoint causes all information about the breakpoint to be lost. Once you cancel a breakpoint, you cannot later reactivate it, but must again explicitly set the breakpoint. Note the following points: - To cancel a specific breakpoint, choose Cancel from the Break menu on the optional view window. - To cancel all breakpoints, choose Cancel All from the Break menu on the main, instruction, or optional view window. 2 break_cond =Title Setting a Conditional Breakpoint =include debugui src_display =include debugui custom_key_breakdb =include debugui breakpoint_disp_hlp =include debugui break A conditional breakpoint suspends execution only when a specified expression is evaluated as true. For example, you can specify that a breakpoint take effect when the value of a variable in your program is 4. The breakpoint is ignored if the value is other than 4. The debugger evaluates the conditional expression when the breakpoint triggers during execution of your program. The following procedure sets a conditional breakpoint: 1. Display the source or instruction line on which you want to set the conditional breakpoint. 2. Display the Set/Modify Breakpoint dialog box in one of the following ways: - Press Ctrl/MB1 on the button to the left of a source line, an instruction line, or a breakpoint entry in the breakpoint view. This causes the Set/Modify Breakpoint dialog box to display, showing the line you selected in the Location: field. - Choose the Set (main or instruction window) or Set/Modify (optional view window) menu item from the Break menu. When the Set/Modify dialog box appears, enter the line in the Location: field. 3. Enter a relational expression in the Condition: field of the dialog box. The expression must be valid in the source language. For example, a[3] == 0 is a valid relational expression in the C language. 4. Click on OK. The conditional breakpoint is now set. The debugger indicates that a breakpoint is conditional by changing the shape of the breakpoint's button from a square to a diamond. The following procedure modifies a conditional breakpoint; that is, it can be used to change the condition associated with an existing conditional breakpoint, or to change an unqualified breakpoint into a conditional breakpoint: 1. Do one of the following: - Press Ctrl/MB1 on the button to the left of a source line, an instruction code line, or a breakpoint entry in the breakpoint view. - Click on a breakpoint entry in the breakpoint view, and choose the Set/Modify item from the Break Menu. 2. Follow steps 3 and 4 of the previous procedure, as appropriate. 2 break_action =Title Setting an Action Breakpoint =include debugui custom_key_breakdb =include debugui breakpoint_disp_hlp =include debugui break When an action breakpoint triggers, the debugger suspends execution and then executes a specified list of commands. The following procedure sets an action breakpoint: 1. Display the source or instruction line on which you want to set the action breakpoint. 2. Display the Set/Modify Breakpoint dialog box in one of the following ways: - Press Ctrl/MB1 on the button to the left of a source line, an instruction line, or a breakpoint entry in the breakpoint view. This causes the Set/Modify Breakpoint dialog box to display, showing the source line you selected in the Location: field. - Choose the Set (main window) or Set/Modify (optional view window) menu item from the Break menu. When the Set/Modify dialog box appears, enter the source line in the Location: field. 3. Enter one or more debugger commands in the Action: field of the dialog box. For example: DEPOSIT x[j] = 3; STEP; EXAMINE a 4. Click on OK. The action breakpoint is now set. The following procedure modifies an action breakpoint; that is, it can be used to change the command associated with an existing action breakpoint, or to change an unqualified breakpoint into an action breakpoint: 1. Do one of the following: - Press Ctrl/MB1 on the button to the left of a source line, an instruction code line, or a breakpoint entry in the breakpoint view. - Click on a breakpoint entry in the breakpoint view, and choose the Set/Modify item from the Break Menu. 2. Follow steps 3 and 4 of the previous procedure, as appropriate. 2 exam_deposit =title Examining and Manipulating Variables or Expressions =include debugui select =include debugui examine =include debugui monitor =include debugui watch =include debugui deposit =include debugui access_var =include debugui on_mwindow_hlp The Additional Topics explain how to do various operations to display and modify the values of variables declared in your program. 2 select =title Selecting Variable Names from Windows =include debugui src_display =include debugui custom_key_select =include debugui examine =include debugui monitor =include debugui watch =include debugui deposit =include debugui exam_deposit Use the following techniques to select variable names from windows for the operations described in the Additional Topics. When selecting names, follow the syntax of the source programming language: - To specify a scalar (nonaggregate) variable, such as an integer, real, Boolean, or enumeration type, select the variable's name. - To specify an entire aggregate, such as array or structure (record), select the variable's name. - To specify a single element of an aggregate variable, select the entity using the language syntax. For example: + The string arr2[7] specifies element 7 of array arr2 in the C language. + The string employee.address specifies the component address of record (structure) employee in the Pascal language. - To specify the object designated by a pointer variable, select the entity following the language syntax. For example, the string *int_point specifies the object designated by pointer int_point in the C language. Select character strings from windows as follows: - In any window, to select a string delimited by blank spaces, use the standard DECwindows Motif word-selection technique: position the mouse pointer on that string and then double click MB1. - In any window, to select an arbitrary character string, use the standard DECwindows Motif text-selection technique: position the mouse pointer on the first character, press and hold MB1 while dragging the mouse pointer over the string, and then release MB1. - In the debugger source view, you also have the option of using language-sensitive text selection. To select a string delimited by language-dependent identifier boundaries, position the mouse pointer on that string and press Ctrl/MB1. For example, suppose the source view contains the character string arr2[m], then: + To select arr2, position the mouse pointer on arr2 and press Ctrl/MB1. + To select m, position the mouse pointer on m and press Ctrl/MB1. You can change the key sequence for language-sensitive text selection as explained in the Defining the Key Sequence for Language-Sensitive Text Selection topic. 2 examine =title Displaying the Current Value of a Variable or Expression =include debugui src_display =include debugui select =include debugui cnt_button_hlp =include debugui monitor =include debugui exam_deposit You can display the current value of a variable or expression in the following ways: - Using the Examine push button in the push-button view - Using the Examine dialog box, accessed through the Command menu on the main window The Examine push button displays a current value most quickly, but the Examine dialog box allows you to request typecasting or an altered output radix in the displayed result. To display the current value using the Examine push button: 1. Find and select the variable name or expression in a window. 2. Click on the Examine push button on the push-button view of the main window. The debugger displays the variable or expression and its current value in the command view. Note that this is the value of the variable or expression in the current scope, which might not be the same as the source location where you selected the variable name or expression. To display the current value using the Examine dialog box, perform the following steps: 1. Do one of the following: - Find and select the variable name or expression symbols in a window, and choose the Examine menu item from the Commands menu on the main window. The Examine dialog box appears, with the name you selected in the Variable/Expression field. - Choose the Examine menu item from the Commands menu on the main window. The Examine dialog box appears. Enter the name of the variable or symbols of the expression you are examining in the Variable/Expression field of the dialog box. 2. If you are changing the output type, pull down the menu in the Typecast entry box and click on the desired data type. 3. If you are changing the output radix, pull down the menu in the Output Radix entry box and click on the desired radix. 4. Click on OK. Your echoed command and the current value appear in the command view. 2 monitor =Title Monitoring a Variable or Expression =include debugui monitor_aggregate =include debugui monitor_pointer =include debugui watch =include debugui src_display =include debugui select =include debugui cnt_button_hlp =include debugui examine =include debugui exam_deposit When you monitor a variable or expression, the debugger displays the value in the monitor view and checks and updates the displayed value whenever the debugger regains control from your program (for example, after a step or at a breakpoint). To monitor a variable or expression: 1. Choose the Views... menu item in the Options menu on the main window. The Views dialog box appears. 2. Click on monitor view within the dialog box. The monitor view appears in the optional view window. 3. Find and select the variable name or expression in a window. 4. Click on the Monitor push button on the push-button view of the main window. The debugger: - Puts the selected variable name or expression, along with its qualifying path name, in the Monitor Expression column - Puts the current value of the variable in the Value/Deposit column - Puts a cleared button in the Watched column 2 monitor_aggregate =Title Monitoring an Aggregate (Array, Structure) Variable =include debugui monitor If you select the name of an aggregate variable, such as an array or structure (record) and click on the Monitor push button, the debugger displays the word Aggregate in the Value/Deposit column of the monitor view. To display the values of all elements (components) of an aggregate variable, double click on the variable name in the Monitor Expression column. The displayed element names are indented relative to the parent name. If an element is also an aggregate, you can double click on its name to display its elements, and so on. To contract an expanded display so that only the aggregate parent name is shown in the monitor view, double click on the name in the Monitor Expression column. If you have selected a component of an aggregate variable, and the component expression is itself a variable, the debugger monitors the component that was active when you made the selection. For example, if you select the array component arr[i] and the current value of i is 9, the debugger monitors arr[9] even if the value of i subsequently changes to 10. 2 monitor_pointer =Title Monitoring a Pointer (Access) Variable =include debugui monitor =include debugui custom_button_add If you select the name of a pointer (access) variable and click on the Monitor push button, the debugger displays the address of the referenced object in the Value/Deposit column of the monitor view. To monitor the value of the referenced object (to dereference the pointer variable), double click on the pointer name in the Monitor Expression column. This adds an entry for the referenced object in the monitor view, which is indented under the pointer entry. If a referenced object is an aggregate, you can double click on its name to display its elements, and so on. If you are debugging programs written in C or C++, you may want to add a new push button to the push button view, one that monitors a dereferenced value. If so, you enter the following command in the Command field of the Customize dialog box: monitor *%s For more information, see the Adding a New Push Button and Associated Command help topic. 2 watch =title Watching a Variable =include debugui monitor =include debugui static_nonstatic_var =include debugui examine =include debugui exam_deposit Whenever the program changes the value of a watched variable, the debugger suspends execution and displays the old and new values in the command view. To watch a variable (also known as setting a watchpoint on a variable), proceed as follows: 1. Monitor the variable as explained in the Monitoring a Variable topic. The debugger puts a button in the Watched column of the monitor view whenever you monitor a variable. 2. Click on the button in the Watched column. A filled-in button indicates that the watchpoint is set. To deactivate a watchpoint, clear its Watched button in the monitor view (by clicking on the button). To activate a watchpoint, fill in its Watched button. The Accessing Static and Nonstatic (Automatic) Variables topic explains static and nonstatic (automatic) variables and how to access them. The debugger deactivates a nonstatic watchpoint when execution moves out of (returns from) the variable's defining routine. When a nonstatic variable is no longer active, its entry is dimmed in the monitor view and its Watched button is cleared. The debugger does not reactivate nonstatic watchpoints automatically if execution later returns to the variable's defining routine. You must reactivate nonstatic watchpoints yourself. 2 deposit =title Changing the Value of a Variable =include debugui monitor =include debugui monitor_aggregate =include debugui examine =include debugui exam_deposit You can change the value of a variable in the following ways: - Using the Deposit dialog box, accessed from the Commands menu on the main window - Clicking on a monitored value within the monitor view To change the value of a variable using the Deposit dialog box: 1. Do one of the following: - Find and select the variable name in a window, and choose the Deposit menu item from the Commands menu on the main window. The Deposit dialog box appears, with the name you selected in the Variable field. - Choose the Deposit menu item from the Commands menu on the main window. The Deposit dialog box appears. Enter the name of the variable to which you are depositing a value in the Variable field of the dialog box. 2. Enter the value you are depositing in the Value field of the dialog box. 3. If you are changing the input radix, pull down the menu in the Input Radix entry box and click on the desired radix. 4. Click on OK. Your echoed command appears in the command view, indicating that the value is changed. To change the value of a monitored value within the monitor view: 1. Monitor the variable as explained in the Monitoring a Variable topic. 2. Click on the variable's value in the Value/Deposit column of the monitor view. A small dialog box appears over that value, which you can now edit. 3. Enter the new value in the dialog box. 4. Click on the check mark (OK) in the dialog box. The dialog box is removed and replaced by the new value, which indicates that the variable now has that value. The debugger notifies you if you try to enter a value that is incompatible with the variable's type, range, and so on. To cancel a text entry and dismiss the dialog box, click on X (Cancel). You can change the value of only one component of an aggregate variable (such as an array or structure) at a time. To change the value of an aggregate-variable component: 1. Display the value of the component as explained in the Monitoring an Aggregate (Array or Structure) Variable topic. 2. Follow the procedure for changing the value of a scalar variable. 2 variable =Title Monitoring Local Variables and Parameters =include debugui watch =include debugui src_display In the Local Variable view, you can monitor the values of all local variables and parameters passed to a routine. The debugger displays these values, and checks and updates all displayed values whenever the debugger regains control from your program (for example, after a step or at a breakpoint). You cannot add or remove an entry to the local variables and parameters list. The debugger automatically removes previous entries and adds new entries when a new routine appears at the top of the call stack. To monitor a local variable or parameter: 1. Choose the Views... menu item in the Options menu on the main or optional view window. The Views dialog box appears. 2. Click on the Local Variable View item in the Views dialog box. The Local Variable view appears. The debugger automatically lists all local variable and parameter names (in the Expression column) and current values (in the Value/Deposit column). To change the value of a monitored value within the local variable view: 1. Monitor the local variable as explained above. 2. Click on the variable's value in the Value/Deposit column of the local variable view. A small dialog box appears over that value, which you can now edit. 3. Enter the new value in the dialog box. 4. Click on the check mark (OK) in the dialog box. The dialog box is removed and replaced by the new value, which indicates that the variable now has that value. The debugger notifies you if you try to enter a value that is incompatible with the variable's type, range, and so on. To cancel a text entry and dismiss the dialog box, click on X (Cancel). You can change the value of only one component of an aggregate variable (such as an array or structure) at a time. To change the value of an aggregate-variable component: 1. Display the value of the component as explained in the Monitoring an Aggregate (Array or Structure) Variable topic. 2. Follow the procedure for changing the value of a scalar variable. 2 access_var =title Accessing Program Variables =include debugui compile =include debugui static_nonstatic_var =include debugui setscope =include debugui symbol_search =include debugui exam_deposit The Additional Topics give some general considerations about accessing program variables while debugging. If your program was optimized during compilation, you might not have access to certain variables while debugging. When you compile a program for debugging, it is best to disable optimization, if possible. Before you check on the value of a variable, always execute the program beyond the point where the variable is declared and initialized. The value contained in any uninitialized variable should be considered invalid. 2 static_nonstatic_var =title Accessing Static and Nonstatic (Automatic) Variables =include debugui monitor =include debugui watch =include debugui access_var NOTE: The generic term nonstatic variable is used here to denote what is called an automatic variable in some languages. The technique for accessing a variable varies according to whether it is a static or nonstatic variable. The system differentiates between static and nonstatic variables by determining how they are stored. A static variable is associated with the same memory address throughout execution of the program. You can always access a static variable. A nonstatic variable is allocated on the stack or in a register and has a value only when its defining routine or block is active. Therefore, you can access a nonstatic variable only when program execution is paused within the scope of its defining routine or block (which includes any routine called by the defining routine). A common technique for accessing a nonstatic variable is first to set a breakpoint on the defining routine and then to execute the program to the breakpoint. Whenever the execution of your program makes a nonstatic variable inaccessible, the debugger notifies you as follows: - If you try to display the value of the variable or monitor the variable, the debugger issues a message that the variable is not active or not in scope. - If the variable is currently being monitored, its entry becomes dimmed in the monitor view. When the entry is dimmed, the debugger does not check or update the variable's displayed value; also, you cannot change that value. The entry is fully displayed whenever the variable becomes accessible again. 2 instruction =Title Displaying the Decoded Instruction Stream of your Program =include debugui cnt_options_pd_menu_hlp =include debugui compile =include debugui setscope =include debugui on_iwindow_hlp The instruction view displays the decoded instruction stream of your program---the code that is actually executing. This is useful if the program you are debugging has been optimized by the compiler so that the information in the source view does not exactly reflect the code that is executing. To display the instruction view, choose Views... from the Options menu on the main or optional view window. When the View Selection dialog box appears, toggle Instruction View. By default, the instruction view automatically displays the decoded instruction stream of the routine in which execution is currently paused. The current-location pointer, to the left of the instructions, marks the instruction that will execute next. By default, the debugger displays line numbers and memory addresses to the left of the instructions You can choose not to display numbers or addresses so that more space is devoted to showing instructions. To hide or display line numbers, toggle the Display Line Numbers button from the File menu on the instruction view. To hide or display memory addresses, choose Show Instruction Addresses from the File menu on the instruction view. To copy memory addresses or instructions into a command you are entering at the command entry prompt, select text and choose Copy from the Edit menu in the instruction window. Then, position your mouse pointer at the command you have entered and choose Paste from the Edit menu on the main window. (You can also select instruction text to be used with a push button command you click in the push button view of the main window.) To set breakpoints from the instruction view, toggle the breakpoint button next to the instruction of interest. The breakpoint is set in the source display, instruction display (if the instruction view is open), and breakpoint view (if the breakpoint view is open). Information on the breakpoint is continuously updated in the source view, and in the instruction view and breakpoint view if they are open. You can also set breakpoints and change breakpoint status by pulling down the Break menu from the main or optional view window. After navigating through the instruction view, to redisplay the location at which execution is paused, click on the Call Stack menu. To display the instruction stream of any routine on the call stack, choose its name from the Call Stack menu on the main window. 2 register =Title Displaying and Modifying Register Values =include debugui cnt_options_pd_menu_hlp =include debugui setscope =include debugui on_owindow_hlp The register view displays the current contents of all machine registers. To display the register view, choose Views... from the Options menu, then click on the button for Registers. By default, the register view automatically displays the register values associated with the routine in which execution is currently paused. Any values that change as your program executes are highlighted whenever the debugger regains control from your program. To display the register values associated with any routine on the call stack, choose its name from the Call Stack menu on the main window. To change the value stored in a register: 1. Click on the register value in the register view. A small dialog box appears over the current value, which you can now edit. 2. Enter the new value in the dialog box. 3. Click on the check mark (OK) in the dialog box. The dialog box is removed and replaced by the new value, which indicates that the register now contains that value. To cancel a text entry and dismiss the dialog box, click on X (Cancel). 2 task =Title Debugging Multithread Programs =include debugui cnt_options_pd_menu_hlp =include debugui cnt_task_pd_menu_hlp =include debugui on_owindow_hlp Multithread programs have multiple threads of execution within a process and include the following: - Programs written in any language that use DECthreads or POSIX 1003.1b services. - Programs that use language-specific threads services (services provided directly by the language). Currently, Ada is the only language with built-in threads services that the debugger supports. Within the debugger, the term thread or task denotes such a flow of control regardless of the language or implementation. The debugger's threads support applies to all such programs. The debugger lets you display thread information and modify task characteristics to control thread execution, priority, state transitions, and so on. The following paragraphs summarize the multithread features of the debugger's DECwindows Motif interface. For more information about the debugger's threads support, see the manual provided with this debugger. Displaying Information about Threads: To display information about one or more threads of your program, choose Views... from the Options menu on the main or optional view window. When the Views dialog box appears, click the button for Threads. The Threads View dialog box is displayed. The thread view gives information about all currently existing (nonterminated) tasks of your program. The information is updated whenever the debugger regains control from the program. The displayed information includes: - The Thread ID. The arrow in the left column marks the active thread, that is, the task that runs when you click on the Go or Step push button. - The current state of the thread. The running thread (thread in the RUN state) is the active thread. - Whether the thread has been put on hold. - The thread priority. - The current substate of the thread. The substate helps indicate the possible cause of a thread's state. - A debugger path name for the thread object or the address of the thread object if the debugger cannot symbolize the thread object. Changing Thread Characteristics: To modify thread characteristics or the thread environment while debugging, choose one of the following items from the Threads menu on the optional view window: Action Function ------ -------- Abort Requests that the selected thread be terminated at the next allowed opportunity. The exact effect depends on the current event facility (language dependent). For Ada tasks, this is equivalent to executing an abort statement. Activate Makes the selected thread the active thread. Hold Places the selected thread on hold. Nohold Releases the selected thread from hold. Make Makes the selected thread the visible task. Visible All -> Uses the submenu to: Abort all threads Hold all threads NoHold all threads To save these modifications for subsequent debugger sessions, choose Save Options from the Options menu on the main or optional view window. This creates a new version of the debugger resource file with the new definitions. 2 setscope =Title Setting the Current Scope Relative to the Call Stack =include debugui callstack_menu_hlp =include debugui src_display =include debugui instruction =include debugui register =include debugui symbol_search =include debugui access_var While debugging a routine in your program, you might want to set the current scope to a calling routine (a routine down the stack from the routine in which execution is currently paused). This enables you to: - Determine where the current routine call originated - Determine the value of a variable declared in a calling routine - Determine the value of a variable during a particular invocation of a routine that is called recursively - Change the value of a variable in the context of a routine call The Call Stack menu on the source view lists the names of the routines of your program that are currently active on the stack, up to the maximum number of lines that can be displayed on your screen. The numbers on the left side of the menu indicate the level of each routine on the stack relative to level 0, which denotes the routine in which execution is paused. To set the current scope to a particular routine on the stack, choose its name from the Call Stack menu. This causes the following to occur: - The Call Stack menu, when released, shows the name and relative level of the routine that is now the current scope. - The source view shows that routine's source code. - The instruction view (if displayed) shows that routine's decoded instructions. - The register view (if displayed) shows the register values associated with that routine call. - If the scope is set to a calling routine (call-stack level other than 0), the debugger clears the current-location pointer. - The debugger sets the scope for symbol searches to the chosen routine, so that you can examine variables, and so on, in the context of that scope. When you set the scope to a calling routine, the current-location pointer (which is cleared) marks the source line to which execution will return in that routine. Depending on the source language and coding style used, this might be the line that contains the call statement or some subsequent line. 2 symbol_search =title How the Debugger Searches for Names and Symbols =include debugui setscope =include debugui access_var Symbol ambiguities can occur when a symbol (for example, a variable name X) is defined in more than one routine or other program unit. In most cases, the debugger resolves symbol ambiguities automatically. First, it uses the scope and visibility rules of the currently set language. In addition, because the debugger permits you to specify symbols in arbitrary modules (to set breakpoints and so on), the debugger uses the ordering of routine calls on the call stack to resolve symbol ambiguities. In some cases, however, the debugger might respond as follows when you specify a symbol that is defined multiple times: - It might issue a "symbol not unique" message because it is not able to determine the particular declaration of the symbol that you intended. - It might reference the symbol declaration that is visible in the current scope, which is not the one you want. To resolve such problems, you must specify a scope where the debugger should search for the particular declaration of the symbol: - If the different declarations of the symbol are within routines that are currently active on the call stack, use the Call Stack menu on the source window to reset the current scope. - Otherwise, enter the appropriate command at the command-entry prompt (EXAMINE or MONITOR, for example), specifying a path-name prefix with the symbol. For example, if the variable X is defined in two modules named COUNTER and SWAP, the following command uses the path name SWAP\X to specify the declaration of X that is in module SWAP: DBG> EXAMINE SWAP\X 2 starting_debugger =title Starting the Debugger =include debugui run_new_hlp =include debugui rerun_same_hlp =include debugui on_mwindow_hlp To start the debugger, enter the following command from DCL level: $ DEBUG/KEEP This startup method enables you to rerun your program or run another program from the same debugging session without exiting the debugger. Additional options for starting the debugger are discussed in the manual provided with this debugger. With some of these startup methods, you cannot rerun your program or run another program from the same debugging session. 2 custom =title Customizing the Debugger =include debugui custom_views =include debugui custom_lineno =include debugui custom_button =include debugui custom_resource =include debugui custom_key_breakdb =include debugui custom_key_select =include debugui custom_font =include debugui on_mwindow_hlp You can customize the debugger's DECwindows Motif interface as follows: - Define the startup configuration of the debugger windows and views - Show or hide line numbers in the source view at debugger startup - Modify, add, or remove push buttons and associated debugger commands - Define the key sequence to display the dialog box for conditional and action breakpoints - Define the key sequence to make text selection language-sensitive in the source view - Define the character font for text displayed in specific windows and views - Define or redefine the commands bound to individual keys on your computer's keypad. You can control the first three of these customizations interactively from the DECwindows Motif interface, as explained in the Additional Topics. In each of these three cases, you can save the current settings by choosing Save Options from the Options menu on the main or optional view window. In addition, you can control all customizations by editing the debugger resource file (DECW$USER_DEFAULTS:VMSDEBUG.DAT). 2 custom_views =title Defining the Startup Configuration of Debugger Windows =include debugui custom_resource =include debugui custom To define the startup configuration of the debugger windows and views: 1. While using the debugger, set up the desired configuration of the windows and views. 2. Choose Save Options from the Options menu on the main or optional view window. This creates a new version of the debugger resource file with the new settings. When you later start the debugger, the new configuration appears automatically. Note that adding views to the startup configuration increases the startup time accordingly. You can also define the startup window configuration by editing the current definition of the following resources in the VMSDEBUG.DAT resource file: DebugSource.width DebugSource.x DebugSource.height DebugSource.y DebugControl.width DebugControl.x DebugControl.height DebugControl.y 2 custom_lineno =title Displaying or Hiding Source Line Numbers by Default =include debugui custom_resource =include debugui custom The source view displays source line numbers by default at debugger startup. To hide (or display) line numbers at debugger startup: 1. While using the debugger, choose Show Line Numbers from the File menu on the main window. Line numbers are displayed when a filled-in button appears next to that menu item, and vice versa. 2. Choose Save Options from the Options menu on the main or optional view window. This creates a new version of the debugger resource file with the new settings. When you later start the debugger, line numbers are either displayed or hidden accordingly. You can also set the startup default for line numbers by setting the following resource to either True or False in the VMSDEBUG.DAT resource file. DebugSource.StartupShowSourceLineno 2 custom_button =title Modifying, Adding, Removing, and Resequencing Push Buttons =include debugui custom_button_mod =include debugui custom_button_add =include debugui custom_button_remove =include debugui custom_button_move =include debugui custom_resource =include debugui custom The push buttons on the push-button view are associated with debugger commands. You can: - Change a push button's label or the command associated with a push button - Add a new push button and assign a command to that button - Remove a push button - Resequence a push button NOTE: You cannot modify or remove the Stop push button. The Additional Topics explain how to customize push buttons interactively through the DECwindows Motif interface. To save these modifications for subsequent debugger sessions, choose Save Options from the Options menu on the main window or an optional view. This creates a new version of the debugger resource file with the new definitions. 2 custom_button_move =title Resequencing a Push Button and Associated Command To resequence a push button: 1. Choose Customize Buttons... from the Options menu on the main window or an optional view. The Customize dialog box appears. 2. Click on the push button in the control panel of the Customize dialog box. 3. Click on Right Arrow or Left Arrow. The push button is resequenced one place to the right or left in the dialog box control panel. 4. Click on OK. The push button is resequenced one place to the right or left in the push-button view on the main window. 2 custom_button_mod =title Changing a Push Button's Label or Associated Command =include debugui command_help =include debugui custom_button To change a push button's label or the debugger command associated with a push button: 1. Choose Customize Buttons... from the Options menu on the main window or an optional view. The Customize dialog box appears. 2. Click on the push button in the control panel of the dialog box. 3. If changing the push button label, enter the new label in the Label field or choose a predefined icon from the Icon menu. (If changing the push button label, verify that the Icon menu is set to None.) 4. If changing the command associated with the push button, enter the new command in the Command field. If the command is to operate on a name or language expression selected in a window, include %s in the command name. For example, the following command displays the current value of the variable whose name is currently selected: EXAMINE %s If the command is to operate on a name that has a a percent sign (%) as the first character, specify two percent signs. 5. Click on Modify. The push button is modified in the dialog box control panel. 6. Click on OK. The push button is modified in the push-button view on the main window. 2 custom_button_add =title Adding a New Push Button and Associated Command =include debugui command_help =include debugui custom_button To add a new push button to the push-button view and assign a debugger command to that push button: 1. Choose Customize Buttons... from the Options menu on the main window. The Customize dialog box appears. 2. Enter the debugger command for that push button in the Command field. 3. Enter a label for that push button in the Label field or choose a predefined icon from the Icon menu. 4. Click on Add. The push button is added to the control panel within the dialog box. 5. Click on OK. The push button is added to the push-button view in the main window. If you are debugging programs written in C or C++, you may want to add a new push button to the push button view, one that monitors a dereferenced value. If so, you enter the following command in the Command field of the Customize dialog box: monitor *%s 2 custom_button_remove =title Removing a Push Button =include debugui custom_button To remove a push button: 1. Choose Customize Buttons... from the Options menu on the main window. The Customize dialog box appears 2. Click on the push button in the control panel of the Customize dialog box. 3. Click on Remove. The push button is removed from the control panel within the dialog box. 4. Click on OK. The push button is removed from the push button view in the main window. 2 custom_resource =title Customizing Your Debugger Resource File =include debugui save_edit_options =include debugui restore_default_options =include debugui edit_options_file =include debugui custom The debugger is installed on your system with a debugger resource file DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT that defines the startup default settings for the following debugger user-interface options: - Configuration of windows and views - Whether to show or hide line numbers in the source view - Button names and associated debugger commands - Key sequence to display the dialog box for conditional and action breakpoints - Key sequence for language-sensitive text selection in the source view - Character fonts for text in the windows and views - Key bindings for commands associated with the computer keypad - Colors for elements of the source and instruction views and Editor - Command echo - Title Bar label format A listing of the system default debugger resource file with explanatory comments is contained in the manual provided with this debugger. You can customize the following features from the DECwindows Motif interface: - Configuration of windows and views - Whether to show or hide line numbers in the source view - Push button names and associated debugger commands You can redefine the rest of the customizable parameters by editing your local debugger resource file. See Additional Topics for information about changing and saving the debugger user-interface options, and restoring system default debugger user-interface options. 2 custom_key_breakdb =title Defining the Key Sequence for the Breakpoint Dialog Box =include debugui break_cond =include debugui break_action =include debugui custom_resource =include debugui custom By default, the key sequence for displaying the dialog box for conditional and action breakpoints is Ctrl/MB1. To define another key sequence, edit the current definition of the following resource in the VMSDEBUG.DAT resource file: DebugSource.ModifyBreakpointToggleSequence 2 custom_key_select =title Defining the Key Sequence for Text Selection =include debugui select =include debugui custom_resource =include debugui custom By default, the key sequence for language-sensitive text selection in the source view is Ctrl/MB1. To define another key sequence, edit the current definition of the following resource in the VMSDEBUG.DAT resource file: DebugSource.IdentifierSelectionSequence To avoid conflict with standard DECwindows Motif word selection, do not use a double-click combination, such as Ctrl(2). 2 custom_font =title Defining the Font for Displayed Text =include debugui custom_resource =include debugui custom To define another font for the text displayed in various debugger windows and views, edit the current definition of the following resources in the VMSDEBUG.DAT resource file: DebugDefault.Font DebugSource.Font DebugInstruction.Font DebugMessage.Font DebugOptions.Font 2 custom_key_binding =title Defining the Key Bindings on the Keypad =include debugui custom_resource =include debugui custom The following commands have been mapped to individual keys on your computer's keypad: Command Keypad Label Key Designation -------- ------------ --------------- Step/Line KP0 0xFFB0 Examine KP1 0xFFB1 Go KPcomma 0xFFAC Step/Into GOLD-KP0 0xFF91,0xFFB0 Step/Over BLUE-KP0 0xFF94,0xFFB0 Examine^ GOLD-KP1 0xFF91,0xFFB1 Show Calls KP5 0xFFB5 Show Calls 3 GOLD-KP5 0xFF91,0xFFB5 Activate ENTER 0xFF8D 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 VMSDEBUG.DAT resource file: DebugSource.*DXmCSText.translations:#override\n\ 0xFFB0: EnterCmdOnCmdLine("step\line") \n\ 0xFFB1: EnterCmdOnCmdLine("examine") \n\ 0xFFAC: EnterCmdOnCmdLine("go") \n\ 0xFF91,0xFFB0: EnterCmdOnCmdLine("step\into") \n\ 0xFF94,0xFFB0: EnterCmdOnCmdLine("step\over") \n\ 0xFF91,0xFFB1: EnterCmdOnCmdLine("examine^") \n\ 0xFFB5: EnterCmdOnCmdLine("show calls") \n\ 0xFF91,0xFFB5: EnterCmdOnCmdLine("show calls 3") \n\ 0xFF8D: activate()\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. 2 decwindows_basics =title DECwindows Motif Basics =include debugui on_mwindow_hlp Information about using DECwindows Motif, such as how to use windows, dialog boxes, and scroll bars, is available from Session Manager help. To get Session Manager help: 1. Move the mouse pointer to the Session Manager icon (the icon that contains a small key in it) in the Icon Box. 2. Press mouse button 1 (MB1) twice to display the Session Manager window. 3. Move the mouse pointer to the Help menu; press and hold MB1 to pull down this menu. 4. Move the mouse pointer to the On Basics menu item and release MB1. The Session Manager displays a Help window, which includes a list of Additional Topics about using DECwindows Motif. 2 on_context =Title On Context Item in Help Menu =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp =include debugui on_owindow_hlp =include debugui on_ewindow_hlp =include debugui on_iwindow_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 a debugger window. The pointer shape changes to a question mark (?). 2. Place the question mark on an object or area in a debugger window or dialog box. 3. Click on MB1. Information about 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. 2 on_window =Title On Window Item in Help Menu =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp =include debugui on_owindow_hlp =include debugui on_ewindow_hlp =include debugui on_iwindow_hlp Choose On Window in the Help menu for an overview of the debugger along with information on how to do various tasks using the debugger. 2 on_help =Title On Help Item in Help Menu =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp =include debugui on_owindow_hlp =include debugui on_ewindow_hlp =include debugui on_iwindow_hlp Choose On Help in the Help menu for instructions on how to use the help system. 2 on_version =Title On Version Item in Help Menu =include debugui on_version_hlp =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp =include debugui on_owindow_hlp =include debugui on_ewindow_hlp =include debugui on_iwindow_hlp Choose On Version in the Help menu for version and copyright information about the OpenVMS Debugger. 2 on_command =Title On Commands Item in Help Menu =include debugui interfaces =include debugui cmd_entry =include debugui msg_region_hlp =include debugui command_help =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp Choose On Commands in the Help menu for information about debugger commands. The debugger's DECwindows Motif interface is layered on the command interface. You can enter debugger commands at the DBG> command-entry prompt in the command view. 2 context_sensitive_help =title Displaying Context-Sensitive Help =include debugui 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 a debugger window. The pointer shape changes to a question mark (?). 2. Place the question mark on an object or area in a debugger 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. 2 overview_help =title Displaying the On Window Help Topic and Subtopics =include debugui on_mwindow_hlp =include debugui on_help_hlp =include debugui help_pd_menu_hlp The On Window help topic (Using the Main Window, Using the Optional View Window, Using the Editor Window, Using the Instruction Window) and their subtopics provide task-oriented information about the debugger and debugging. To display the On Window topics, use either of these techniques: - Choose On Window from the Help menu in a debugger window. - Choose Go To Overview from the View menu of a debugger help window. Then, to display information about a particular subject, choose a topic from the list of Additional Topics. 2 command_help =title Displaying Help on Debugger Commands and Various Topics =include debugui interfaces =include debugui cmd_entry =include debugui msg_region_hlp =include debugui disabled_vms_cmds =include debugui custom_button_mod =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp You can enter debugger commands as follows: - At the command-entry prompt in the command view. - In certain debugger dialog boxes (for example, when assigning a new command to a push button on the push-button view). To display help on debugger commands and various topics: - Choose On Commands from the Help menu of a debugger window. - Choose the command name or other topic (for example, Language_Support) from the list of Additional Topics. 2 msg_help =title Displaying Help on Debugger Diagnostic Messages =include debugui msg_region_hlp =include debugui on_help_hlp =include debugui help_pd_menu_hlp =include debugui on_mwindow_hlp Debugger diagnostic messages are displayed in the command view. To display help on a particular message: 1. Choose On Commands from the Help menu of a debugger window. 2. Choose Messages from the list of Additional Topics. 3. Choose the message identifier from the list of Additional Topics. 2 ha_map_pane_hlp =Title Memory Map on Heap Analyzer Window =include debugui ha_map_cs =include debugui ha_file_menu_hlp =include debugui ha_display_menu_hlp =include debugui ha_zoom_menu_hlp =include debugui ha_options_menu_hlp =include debugui ha_help_menu_hlp The Memory Map, located at the upper left of the heap analyzer screen, displays a graphical representation of memory use in real time. Each memory allocation appears as a colored strip, or 'segment'. By searching for segments that seem too large, too numerous, or in other ways anomalous, you can identify areas in your application where one of the following memory events may be occurring: - Memory leaks - Fragmentation - Repetitive allocations - Insufficient allocation - Inefficient memory use For information on Memory Map context-sensitive pop-up menus and pull-down menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_hist_pane_hlp =Title Type Histogram =include debugui ha_type_cs The Type Histogram, located in the upper right of the heap analyzer screen, allows you to see statistical summaries on segments of the same segment type. Use the Type Histogram to: - Check the percentage of total segments represented by a segment type. The left histogram shows this percentage graphically. Click on an individual segment type to see a numerical percentage. - Check the percentage of the total bytes allocated to a segment type. The right histogram shows this percentage graphically. Click on an individual segment type to see a numerical percentage. The total number of segments and the total number of bytes (recognized by the heap analyzer) appear at the top of the histogram window. For information on Type Histogram context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_type_cs =Title Type Histogram Context-Sensitive Menus =include debugui ha_interpret_typedef =include debugui ha_interpret_gototype =include debugui ha_interpret_donotuse Most of the work you do in the heap analyzer is accomplished through context-sensitive pop-up menus. The menu items available on the Type Histogram are as follows: Action Function ------ -------- Display Type Displays the segment's type definition in the Information Window. Go to Type Moves the cursor to the segment's type in the Views-and-Types Display. Do Not Use Type Adds the segment's type to the Do-not-use Type List. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_msg_pane_hlp =Title Message Window =include debugui ha_interpret_segdef The Message Window, located beneath the Memory Map, displays output from the heap analyzer. Use the Message Window on the heap analyzer window to do the following: - Read informational and error messages generated by the heap analyzer. - Read one-line informational descriptions on individual segments. (Click on MB1 while your mouse pointer rests on the segments of interest.) For information on Message Window context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_map_cs =Title Memory Map Context-Sensitive Menus =include debugui ha_interpret_trace =include debugui ha_interpret_segdef =include debugui ha_interpret_contdef =include debugui ha_interpret_adddef =include debugui ha_interpret_typedef =include debugui ha_interpret_gototype =include debugui ha_interpret_donotuse Most of the work you do in the heap analyzer is accomplished through context-sensitive pop-up menus. The menu items available on the Memory Map are as follows: Action Function ------ -------- Traceback of Allocation Displays a traceback, that is, the sequence of routine calls on the callstack, for the segment under your mouse arrow. Display Segment Displays the segment definition of the segment under your mouse arrow in the Information Window. Display Contents Displays the contents of the segment under your mouse arrow. Display Address Displays the address under your mouse arrow in the Information Window. Display Type Displays the segment's type definition in the Information Window. Go to Type Moves the cursor to the segment's type in the Views-and-Types Display. Do Not Use Type Adds the segment's type to the Do-not-use Type List. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_trace =Title Requesting a Segment Traceback The heap analyzer displays traceback information when you choose the Traceback of Allocation context-sensitive menu item from the Memory Map. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_gototype =Title Requesting the Views-and-Types Display =include debugui ha_color_type =include debugui ha_show_type =include debugui ha_expand_type =include debugui ha_save_type The heap analyzer moves you to the Views-and-Types Display when you choose the Go to Type context-sensitive menu item from the Memory Map or the Type Histogram. Your mouse arrow rests on the segment type associated with the segment you selected in the Memory Map or Type Histogram. You can choose one of the following options for the display of this type in the Memory Map: - Change the color of the type - Show (or hide) the type - Expand (or collapse) the type - Save (or remove) the type For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_color_type =Title Changing the Type Color The heap analyzer allows you to change the color assigned to a segment type in the Memory Map by clicking MB3 on the color spectrum for a segment type or types. This feature can be useful if the colors of adjacent types are too similar to distinguish each type clearly. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_show_type =Title Choosing the Show or Hide Option The heap analyzer allows you to hide (and then, show again) the display of a segment type in the Memory Map by doing one of the following: - Toggling the Show toggle button and clicking the Apply button in the Views-and-Types Display. - Selecting the Show or Hide menu item and clicking the Apply button in the Views-and-Types Display. This feature can be useful when you need to isolate a segment or segments in the Memory Map in order to see them better. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_expand_type =Title Choosing the Expand or Collapse Option The heap analyzer allows you to expand (or collapse) the display of a segment type contained inside the display of other segment types in the Memory Map by doing one of the following: - Toggling the Expand toggle button and clicking the Apply button in the Views-and-Types Display. - Selecting the Expand or Collapse menu item and clicking the Apply button in the Views-and-Types Display. This feature can be useful when you need a more or less detailed picture of an area in the Memory Map. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_save_type =Title Choosing the Save or Remove Option The heap analyzer allows you to save (or remove) the display of a segment type in the Memory Map by doing one of the following: - Toggling the Save toggle button and clicking the Apply button in the Views-and-Types Display. - Selecting the Save or Remove menu item and clicking the Apply button in the Views-and-Types display. This feature can be useful when you need to improve heap analyzer performance by discarding information on unimportant segments. It is also useful when you need to discard all information before a point in time, so you can perform a series of actions and see the display resulting from them. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_donotuse =Title Adding to the Do-not-use Type List The heap analyzer adds a new segment type name to the Do-not-use Type List when you perform one of the following actions: - Choose the Do Not Use Type context-sensitive menu item from the Memory Map or the Type Histogram. The segment type added is the one associated with the segment your mouse arrow is pointing to. - Choose the Add to Do-not-use Type List pull-down menu item from the Options menu on the Memory Map. The segment type added is the one you type into the dialog box that appears for your input. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_segdef =Title Interpreting a Segment Definition The heap analyzer displays segment type definitions when: - You click MB1 on a segment displayed in the Memory Map. - You choose the Display Segment context-sensitive menu item from the Memory Map. A segment definition has the following form: 0004ECA5 15: 00040000_0001CA00=0005CA00 LIBRTL (Image) which includes: - 0004ECA5: The address underneath your cursor when you pressed MB1 (This information does not appear when you choose from the context-sensitive menu) - 15: The segment number in the Memory Map display - 00040000: The initial address of the segment - 0001CA00: The length in bytes of the segment - 005CA00: The final address of the segment - LIBRTL: The segment name, or segment type - Image: The segment classification (image, block, region, or zone) For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_typedef =Title Interpreting a Type Definition The heap analyzer displays type definitions when you choose the Display Type item in the context-sensitive menu for the Memory Map. A type definition has the following form: LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments using 00002160 bytes which includes: - LIBRTL\LI$VM\LIB$GET_VM: The segment type name - (Block): The type classification (image, block, region, or zone) - 39 segments: Number of segments - 00002160 bytes: Number of bytes For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_adddef =Title Interpreting an Address Definition The heap analyzer displays segment address definitions when you choose the Display Address item in the context-sensitive menu for the Memory Map. An address definition has the following form: 001C710B is read and write accessible by the user which includes: - 001C710B: The address of the segment - read and write accessible: The access to the user For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_interpret_contdef =Title Interpreting a Contents Definition The heap analyzer displays segment contents definitions when you choose the Display Contents item in the context-sensitive menu for the Memory Map. A contents definition has the following form: contents of: 38: 001C7000+000000C0=001C70C0 LIBTRL\LIB$VM\LIB$GET_VM (Block) 00000000 00000000 00000000 001C7108 00345000 00000000 00000000 ~#@ 001C7118 00000B10 00000000 06503000 <> 001C7128 00C45000 00113000 00000000 * +*, 001C7138 00000000 000C4000 0000E000 .. ? 001C7148 which includes: - 15: The segment number in the Memory Map display - 001C7000: The initial address of the segment - 000000C0: The length in bytes of the segment - 001C70C0: The final address of the segment - LIBRTL\LIB$VM\LIB$GET_VM: The segment name, or segment type - Block: The segment classification (image, block, region, or zone) - An ASCII representation of the contents of the segment For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_info_pane_hlp =Title Information Window =include debugui ha_info_cs The Information Window, located in the lower left of the heap analyzer screen, displays output from context-sensitive menu items in the Memory Map. These items request the following information: - Traceback entries for an allocation - Segment definitions - Contents definitions - Address definitions - Segment type definitions For information on Information Window context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_info_cs =Title Information Window Context-Sensitive Menus Most of the work you do in the heap analyzer is accomplished through context-sensitive pop-up menus. The menu item available on the Information Window is as follows: Action Function ------ -------- Go to Source Displays the source code associated with the traceback entry under your mouse arrow. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_source_pane_hlp =Title Source Window The Source Window, located between the Information Window and the Do-not-use Type List, displays the source code associated with a traceback entry. To display source code, perform the following steps: 1. Choose the Traceback of Allocation item in the context-sensitive menu on the Memory Map. 2. When traceback information appears in the Information Window, click on an individual traceback entry. The routine call associated with the traceback is highlighted when your source code appears. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_hidelist_view_hlp =Title Do-not-use Type List =include debugui ha_hidelist_cs The Do-not-use Type List, located between the Source Window and the Views-and-Types Display, lists the routines the heap analyzer does not use as "segment types," the names that characterize segments. For example, the display showing in the Memory Map may include many segments labeled with the names of low-level memory management routines. If you include these names in the Do-not-use Type List, the heap analyzer will search further for names to characterize segments, and each segment's purpose will become clearer. For information on Do-not-use Type List context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_hidelist_cs =Title Do-not-use Type List Context-Sensitive Menus Most of the work you do in the heap analyzer is accomplished through context-sensitive pop-up menus. The menu item available on the Do-not-use Type List is as follows: Action Function ------ -------- Use Type Removes a segment type from the Do-not-use Type List. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_typelist_pane_hlp =Title Views-and-Types Display =include debugui ha_typelist_cs The Views-and-Types Display, located in the lower right of the heap analyzer screen, displays the segment types known to the heap analyzer and allows you to alter the display of these types. Since the type list is organized into images, blocks, regions, and zones, you can choose the scope of your change, as follows: - All views (all segments) - All blocks (or individual blocks) - All images (or individual images) - All regions (or individual regions) - All zones (or individual zones) Then, move to the right side of the display to choose your display change: - Change colors used in display - Suppress (or restore) types in display - Expand (or collapse) detail of types in display - Remove (or save) information on types displayed in session For information on View-and-Types Display context-sensitive pop-up menus, see the additional topics below. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_typelist_cs =Title Views-and-Types Display Context-Sensitive Menus =include debugui ha_interpret_typedef =include debugui ha_interpret_gototype =include debugui ha_interpret_donotuse Most of the work you do in the heap analyzer is accomplished through context-sensitive pop-up menus. The menu items available from the left side of the Views-and-Types Display are as follows: Action Function ------ -------- Display Type Displays the segment's type definition in the Information Window. Go to Type Moves the cursor to the segment's type in the Views-and-Types Display. Do Not Use Type Adds the segment's type to the Do-not-use Type List. The menu items available from the right side of the Views-and-Types Display are as follows: Action Function ------ -------- Color Spectrum Changes the color assigned to a segment type or types in the Memory Map. -------- Show Restores full Memory Map display. Hide Suppresses the display of one or more segment types. Reset Cancels the options chosen. --------- Expand Includes the display of segment types occurring within other segment types in the Memory Map. Collapse Suppresses the display of segment types occurring within other segment types in the Memory Map. Reset Cancels the options chosen. --------- Save Saves all subsequent information about a segment type or types. Remove Deletes absolutely all information about a segment type or types. Reset Cancels the options chosen. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_source_db_hlp =Title Set Source Dialog Box Use the Set Source Dialog Box to specify a source directory search list. 2 ha_add_hidetype_db_hlp =Title Add to Do-not-use Type List Dialog Box Use the Add to Do-not-use Type List Dialog Box to add additional routines to the Do-not-use Type List. 2 ha_button_pane_hlp =Title Control Panel The push buttons on the control panel allow you to control the speed your application executes and the Memory Map displays. Use the push buttons on the control panel to do the following: Button Function -------- --------- Start/Step Initially, the Start push button starts your application. Once your application is running, this push button becomes the Step push button, which you can use when your application is paused to single-step through the Memory Map display. Pause Stops the updating of the Memory Map. Slow Slows the updating of the Memory Map. Sync Off: A small histogram shows how far behind your application's processing the Memory Map displays events (a slight discrepancy improves heap analyzer performance). On: Directs the heap analyzer to update the Memory Map at exactly the same time your application executes the event. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_file_menu_hlp =Title File Menu Use the File menu on the heap analyzer window as follows: Action Function ------ -------- Exit Exits the heap analyzer. For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_display_menu_hlp =Title Display Menu Use the Display menu on the heap analyzer window as follows: Action Function ------ -------- 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 memory is expanded. Reduce Scroll When you request a limited or partial Memory Region Map display, compresses the display so you can see as many segments as possible without scrolling to their location in the original display. Display All Restores the complete Memory Map display after Segments you have requested a limited or partial display. Clear Clears text from the Information Window. Information Window For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_zoom_menu_hlp =Title Zoom Menu Use the Zoom menu on the heap analyzer window to specify a closer or more distant view of the Memory Map by choosing from the following options: Extraordinarily Close Extremely Close Very Close Close Medium (Default) Far Very Far For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_options_menu_hlp =Title Options Menu Use the Options menu on the heap analyzer window as follows: Action Function ------ -------- Set Source... Allows you to specify a search directory when you display source code in the debugger or in the source window. Add to Allows you to specify additional segment types Do-not-use to be included in the Do-not-use Type List. Type List... Save Allows you to save the segment types listed in Do-not-use your Do-not-use Type List between heap analyzer Type List sessions. Restore Deletes additions to the Do-not-use Type List Do-not-use since the last heap analyzer session. Type List For information on other heap analyzer screen locations and pop-up menus, click the 'On Context' menu item in the heap analyzer Help menu, then click the location of interest. For information on using the heap analyzer, see the 'On Window' menu item in the heap analyzer Help menu. 2 ha_help_menu_hlp =Title Help Menu =include debugui on_context_ha =include debugui on_window_ha =include debugui on_version_ha =include debugui on_help_ha =include debugui glossary_ha =include debugui ha_on_window_hlp =include debugui ha_on_version_hlp =include debugui ha_on_help_hlp Use the Help menu on the heap analyzer window as follows: Action Function ------ -------- On Context Provides context-sensitive help for the heap analyzer. On Window Provides task-oriented information on heap analyzer windows. On Version Provides copyright and version information on the heap analyzer. On Help Provides task-oriented information on DECwindows Motif online help. Glossary Defines terms associated with the heap analyzer. 2 on_context_ha =Title On Context Item in Help Menu =include debugui ha_on_help_hlp =include debugui ha_on_window_hlp =include debugui ha_help_menu_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 a debugger window. The pointer shape changes to a question mark (?). 2. Place the question mark on an object or area in a debugger window or dialog box. 3. Click on MB1. Information about 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. 2 on_window_ha =Title On Window Item in Help Menu =include debugui ha_on_help_hlp =include debugui ha_on_window_hlp =include debugui ha_help_menu_hlp Choose On Window in the Help menu for an overview of the heap analyzer along with information on how to do various tasks using the heap analyzer. 2 On_help_ha =Title On Help Item in Help Menu =include debugui ha_on_help_hlp =include debugui ha_on_window_hlp =include debugui ha_help_menu_hlp Choose On Help in the Help menu for instructions on how to use the help system. 2 on_version_ha =Title On Version Item in Help Menu =include debugui ha_on_help_hlp =include debugui ha_on_window_hlp =include debugui ha_help_menu_hlp Choose On Version in the Help menu for version and copyright information about the heap analyzer. 2 glossary_ha =Title Glossary Item in Help Menu =include debugui ha_on_help_hlp =include debugui ha_on_window_hlp =include debugui ha_help_menu_hlp TBS: This information will appear in a later version release. 2 ha_on_window_hlp =Title Using the Heap Analyzer =include debugui ha_window_start =include debugui ha_window_sourcedir =include debugui ha_window_run =include debugui ha_window_contbutton =include debugui ha_window_defwork =include debugui ha_window_optwork =include debugui ha_window_exit The heap analyzer 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. The additional topics below, read in sequence, describe the steps involved in using the heap analyzer. 2 ha_window_start =Title Starting a Heap Analyzer Session =include debugui ha_window_windows You can invoke the heap analyzer during a debugging session in one of the following ways: - In the debugger main window, choose the Run Image or Rerun Same items from the File menu. When a dialog box appears, select the program you wish to execute and click the heap analyzer toggle button. - At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER or RERUN/HEAP_ANALYZER command. - On VAX and Alpha systems, at the DCL prompt ($) in a DECterm window outside the debugger, enter the following commands and then execute your program: $ DEFINE/USER LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED - To display the Heap Analyzer graphical display on I64 systems, at the DCL prompt ($) enter the command START HEAP_ANALYZER You can also invoke the heap analyzer outside a debugging session by entering the DEFINE/USER command detailed above, and then the DCL command RUN/NODEBUG. After you successfully invoke the heap analyzer, the heap analyzer startup screen appears. 2 ha_window_windows =Title Viewing the Heap Analyzer Startup Screen The heap analyzer contains a main window, six subsidiary windows, and a control panel. 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. 2 ha_window_sourcedir =Title 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 the Set Source... menu item 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 OpenVMS Debugger SET SOURCE command. For more information on this command, see the debugger SET SOURCE command in online help. 3. Click on OK. The heap analyzer can now access your application. 2 ha_window_run =Title Running 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 Debbugger main window pops forward. 2. Click on the Go button in the OpenVMS 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 (by clicking one of the push buttons in the heap analyzer control panel), 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. 2 ha_window_contbutton =Title Controlling the Speed of Display If you decide 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. 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 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. 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. 2 ha_window_defwork =Title Working with the Default Display =include debugui ha_window_def_mmdisp =include debugui ha_window_def_optmmdisp =include debugui ha_window_def_optinfo =include debugui ha_window_def_trace =include debugui ha_window_def_final 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. 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.