% Librarian I01-42OfKvfK5QDEBUGUI vfK 1 DEBUGUI=Title Debug Top Level6 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 ------- ---------C Source display Display program source code, and, optionally,A compiler-generated line numbers to the left" of the code.A Breakpoint Set breakpoints on specific source lines or@ toggles routines in your program, check breakpointE status, and activate or deactivate breakpoints.C 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_src4=Title Context-Sensitive Pop-up Menus in Source View!=include debugui src_workarea_hlpE To use pop-up menus in the source view, select text or positi on yourG mouse pointer in the source view, and press MB3. The debugger insertsG the selected text or line number in the menu items of the pop-up menu.H 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:E Examine [selection] Evaluates the selected expression and prints 6 its value in the command view.G Monitor [selection] Inserts the selected expression in the monitor 1  list of the monitor view.? Deposit [selection] Provides the Assign/Deposit dialog box.E Break on Routine Sets a breakpoint on a selected routine name. [selection]J Toggle Breakpoint Activates/deactivates breakpoint at mouse pointer. at Line  [line number]C Temporary Breakpoint Sets temporary breakpoint at mouse pointer. at Line  [line number]J Go to Line Branches to [line number] without executing sourceL [li!ne number] code betwen the line at which execution is suspended* and [line number].O Display Instruction Displays decoded instruction stream of your program. G Step Step to next line, stepping over routine calls.4 Go Resume execution of program.G If you press MB3 while your mouse pointer rests in the annotation areaD of the source view, a pop-up menu with the following items appears:J Toggle Breakpoint "Activates/deactivates breakpoint at mouse pointer. at Line  [line number]C Temporary Breakpoint Sets temporary breakpoint at mouse pointer. at Line  [line number]@ Go to Line Executes until [line number] is reached. [line number]G Step Step to next line, stepping over routine calls.4 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 ------- ---------A None Identifies the routine whose source code is3 executing in the source view.@ Pull-down Identifies the sequence of routines on the! menu call stack.B 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_buttonC The push-button view on the main window contains push buttons thatC correspond to debugger commands. You can modify, add, remove, and? resequence push buttons and the commands %associated with them.B Use the default push buttons to complete the following functions. Push  Button Function ------ --------9 Stop Interrupts program execution or a debugger5 operation without ending the debugging session. E Go Starts or resumes execution from the current ! program location. 4 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 ro'utine. < S/call (Step call) Executes the program to the next * call or return instruction.8 EX (Examine) Displays, in the command view, : the current value of a variable whose name - you have selected in a window. 9 E/az Displays, in the command view, the current6 value of a variable whose name you haveA selected in a window. The variable is interpreted1 as a zero-ter (minated ASCII string.9 E/ac Displays, in the command view, the current6 value of a variable whose name you haveA selected in a window. The variable is interpreted? as a counted ASCII string preceded by a one-byteB count field that contains the length of the string.7 EVAL Displays, in the command view, the value? of a language expression in the current languageA (by default, the lang)uage of the module containing the main program.: MON (Monitor) Displays, in the monitor view, a ? variable name that you have selected in a windowC 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_hlp5=Title Stop Button in Push-Button View on Ma*in Window=include debugui stop=include debugui cnt_button_hlpF Use the Stop push button to interrupt program execution or a debugger0 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_hlpF The command view on the main window accepts command-line entry input,E echoes GUI actions (in a command-line format), and di+splays debugger messages.2 popup_msgregion5=Title Context-Sensitive Pop-up Menus in Command View=include debugui msg_region_hlpH To use the pop-up menu in the command view, position your mouse pointerB in the message region, and press MB3. The debugger automaticallyB inserts your last command in the [last command] menu item of this pop-up menu. Menu items are as follows:4 Repeat Command Re-enters your last command. [last command] < Clear Command Windo,w Clears the command view and displays( the DBG> prompt., Clear Command Line Clears command line.G Step Step to next line, stepping over routine calls.4 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_hlpE 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_help1. Use the File menu on the main window as follows: Action Function- ------ -------- 5 Run Image... Brings a program under debugger9 control by specifying an executable. image. 5 Run Foreign Brings a program under debugger5 Command... control by specifying a foreign% command symbol.4 Rerun Same... Reruns the same program unde /r ' debugger control.8 Browse Sources Lists the modules in your program.9 You can choose to list all modules,6 or only those for which symbolic9 information is available. You can ; display the source code in any module9 of your program for which symbolic / information is available.< Can also be used to set break 0points on routines. ; Display Line Displays or hides line numbers in the# Numbers main window. 7 Server Connection... (Client-Server only) Invokes the > Server Connection dialog to allow you to? set up and control a connection between a6 debug client and a debug server.: Exit Debug? Exits from the debugger. If running7 in client-server mode, allow1s you8 to exit either the client, server, or both.2 src_edit_pd_menu_hlp=Title Edit Menu on Main Window=include debugui cmd_entry1 Use the Edit menu on the main window as follows: Action Function ------ --------8 Cut Cuts selected text from the current command1 line and copies it to the clipboard.4 If selected text is anywhere other than1 the current command line, copies the#2 text to the clipboard. 4 Copy Copies selected text from the window to. the clipboard without removing it from the window. 9 Paste Pastes text from the clipboard to the insert5 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 b3reakpoint_set_show_hlp=include debugui break_activ =include debugui break_exception2 Use the Break menu on the main window as follows: Action Function ------ --------2 On Exception Breaks on any exception signaled+ during program execution. 5 Activate All Activates all breakpoints that have9 not been canceled, causing the debugger6 to suspend program execution when a ( 4 breakpoint is reached.6 Deactivate All Deactivates all breakpoints, causing5 the debugger to ignore them during $ program execution. 2 Cancel All Removes all breakpoints from the3 debugger's database. You cannot 6 reactivate these breakpoints without0 explicitly setting them first.4 Set... Displays the Set/Nodify Breakpoint< dialog box to set an i5ndividual 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_hlp5 Use the Commands menu on the main window as follows: Action Function ------ --------? Examine... Examines the value of a variable or expression.0 Deposit... Changes the value of a variabl6e.A 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 7 Function ------ --------0 Views... Displays one or more of the . debugger's optional views: & Breakpoint View# Monitor View' Instruction View# Threads View# Register View 2 .!Track Language Notify you when the debugger0 .! Changes enters a module written in1 .! 8 a different source language/ .! than the previous module.1 Show Message Display a dotted line between3 Separators debugger messages and commands.1 Customize Adds, removes, or resequences: Buttons... a push button in the push-button view.5 Also changes a button's label or 8 the debugger command associated with a button.8 Save Options Saves the current defi 9nitions of the< debugger user-interface options for use 6 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 an :d modification. 2 save_edit_options(=include debugui restore_default_options"=include debugui edit_options_file-=Title Saving Debugger User-Interface OptionsF The Save Options command in the Options menu of the source view savesF the current definitions of the debugger user-interface options in theF 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 res ;ource file.2 restore_default_options"=include debugui save_edit_options"=include debugui edit_options_file8=Title Restoring Default Debugger User-Interface OptionsC The Restore Default Options in the Options menu of the source view1 copies the system default debugger resource file@ DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT to the user-specific debuggerB 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 default4 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 OptionsG The Edit Options File in the Options menu of the source view loads and* displays the local debugger resource fileC DECW$USER_DEFAULTS:VMSDEBUG.DAT in the Debug Editor for review andF modification. If there is =no local debugger resource file, the Debug Editor buffer is empty.D To create a local debugger resource file, exit the Debug Editor andH 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 default2 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_hlpG 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 F For more information about using a Help menu item, double click on an/ item from the list of Additional Topics below. 2 run_new_hlp0=Title Bringing a Program Un?der 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_hlpC After starting the debugger as explained in the topic Starting theB Debugger, bring a program under debugger control using one of the following two techniques:E - Run a specified image. This is the most common technique and is described below.G - @ Run an image by specifying a symbol for a foreign command or a DCLH command. This technique is described in the topic Running an Image by Specifying a Symbol. To run a specified image:E 1. Choose Run Image... from the File menu on the main window. The3 Run Image... dialog box appears, which lists:F - A Directories list that contains the parent directory and any: subdirectories contained in the current directoryD - A Filter field; by default thAis specifies the .EXE files in your current directoryH - An Images list that contains the names of images in the current5 directory that meet the filter specificationG - An Arguments field to pass any required arguments to the image to be run8 - 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 runG - An OK button to run the imageB specified in the Image field and dismiss the dialog boxA - A Filter button to display a list of files that meet the* specification in the Filter fieldE - A Cancel button to dismiss the dialog box without taking and further action7 - A Help button to display this help informationB 2. In the Directories list, click on the name of the appropriateE subdirectory and click on Filter to list the (filtered) files inF the subdirect Cory. The debugger also displays, in the DirectoriesF list, the parent directory and any subdirectories of the selected directory.G 3. In the Images list, click on the name of the image to be debugged.E The Image field now shows the image specification. You can edit" this specification as needed.F 4. If applicable, enter arguments to be passed to the program in theG Arguments field. Quoted strings, may require additional quotationF marks because the debuggeDr strips quotes when parsing the string.> 5. To run the Heap Analyzer, click the Heap Analyzer button.F 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. TheH current-location pointer, to the left of the source code, shows the+ line whose code will be executed next.D The messa Ege displayed in the command view indicates the name of theC main program unit and also indicates that the debugging session isH initialized for the source language of the program. The initializationB sets up language-dependent debugger parameters. These parametersC control the way the debugger parses names and expressions, formats debugger output, and so on. You can now debug your program.G With certain programs, the debugger suspends execution at the start ofD some initialization cFode, before the main program, and displays the following message: Type GO to reach main programC With some of these programs (for example, Ada programs), the firstF breakpoint lets you debug the initialization code using full symbolic information.G Note the following restrictions about running a program under debugger control:H - You cannot use the procedure just described to connect the debugger to a running program.H - You cannot run a program under debugger conGtrol over a DECnet link.F 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_hlpD To run an image by specifying a symbol for a foreign (DCL) command:B 1. Choose Run Foreign Command... Hfrom the File menu on the main9 window. The Run Foreign Command dialog box appears.H 2. Enter a symbol for a DCL command in the Foreign Command field. TheE symbol might be defined as "RUN long_file_name.ext" or a similar command.G 3. Enter any arguments to be passed with the command in the ArgumentsB field. If you specify a quoted string, you might have to addH quotation marks because the debugger strips quotes when parsing the string.> 4. To run the IHeap Analyzer, click the Heap Analyzer button. 5. Click on OK.E 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_hlpG You can rerun the program currently under debugger control at any time during a debugging session. To rerun your program:F 1. Choose Rerun Same... from the File menu on the main window. The# R Jerun Same dialog box appears.F 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,E activated, or deactivated. Nonstatic watchpoints might or mightG not be saved, depending on the scope of the variable being watchedB relative to the main program unit (where execution restarts).> 4. To run the Heap A Knalyzer, click the Heap Analyzer button. 5. Click on OK.G When you rerun a program, it is in the same initial state as a programG that is initially brought under debugger control, except for any savedC breakpoints or static watchpoints. The source display and current* location pointer are updated accordingly.D When you rerun a program, the debugger uses the same version of theF image that is currently under debugger control. To debug a different? version of that program (or a difLferent program) from the sameH 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 routines2 popup_browser7=Title C Montext-Sensitive Pop-up Menus in Source Browser=include debugui browse_src_hlpD To use pop-up menus in the Source Browser dialog box, position yourH mouse pointer in the dialog box, and press MB3. A pop-up menu with the following items appears:J Expand Expand the selected image or module to include itsD component modules or functions in the Source( Browser display.P Collapse Collapse an expanded image, moduNle, or function display.I Display Source Display (in the source display of the source viewG on the main window) the source code associated 1 with the selected module.B Set Breakpoint Set a breakpoint on the selected function.G Step Step to next line, stepping over routine calls.4 Go Resume execution of program.2 show_line_numb(=Title Displaying or Hiding Line Numbers$=include dOebugui breakpoint_disp_hlp=include debugui custom_lineno%=include debugui src_file_pd_menu_hlpD To hide or display source line numbers in the main window, click on3 Show Line Numbers in the File menu of that window.B Line numbers help you identify breakpoints that are listed in theD 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=includeP debugui run_new_hlpF To exit the kept debugger, which will terminate the current debugging session, click on Yes.9 Otherwise, click on No to return to the current session.F In client-server mode, the default is to exit both the client and theH server. Make sure that the correct buttons are selected, then click onA 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 dQebugui src_break_pd_menu_hlp&=include debugui cnt_break_pd_menu_hlp) To cancel all breakpoints, click on Yes.4 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 breakD If you are displaying the Set/Modify Breakpoint dialog box from theG Set... menu item in the Break menu on the main or instruction window,> use the Set/Modify Breakpoint diaRlog box to SET a conditional$ breakpoint or an action breakpoint.D If you are displaying the Set/Modify Breakpoint dialog box from theG Set/Modify... menu item in the Break menu on the optional view windowH use the Set/Modify Breakpoint dialog box to SET OR MODIFY a conditional$ breakpoint or an action breakpoint.G When the Set/Modify Breakpoint dialog box appears, complete the fields as follows:$ Field Action$ ----- ------C Location Sfield If the dialog box does not display the ? location of the breakpoint you are E setting or modifying, enter the location = using one of the following forms:> \%line 2 routine -  A Condition field Optionally, enter a condition or editB T an existing condition. The relational< expression must be valid in the B source language of the program module.? Action field Optionally, enter an action or edit> an existing action by substituting= one or more new debugger commands8 (separated by a semi-colon).> Activate/Deactivate Optionally, activate a deactiv Uated@ Breakpoint button breakpoint by accepting the default,A or deactivate an activated breakpoint4 by toggling this button.= OK button Click on OK to set the breakpoint8 and dismiss the dialog box. @ Apply button Click on Apply to set the breakpoint5 and clear the dialog box.A Cancel Breakpoint Click on Cancel Breakpoint to remoVve F button a breakpoint. Note that you can no longer B reactivate this breakpoint unless you 4 again explicitly set it.A 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_hlpD T Whe Examine dialog box allows you to display the current value of aD variable or expression in the command view. If you choose, you can8 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:E - Find and select the variable name or expression symbols in aH window, and choose the Examine menu item from the Commands menuF on the main window. The Examine dialog box appears, wi Xth the< name you selected in the Variable/Expression field.H - Choose the Examine menu item from the Commands menu on the mainH window. The Examine dialog box appears. Enter the name of theG variable or symbols of the expression you are examining in the5 Variable/Expression field of the dialog box.C 2. If you are changing the output type, pull down the menu in the; Typecast entry box and click on the desired data type.D 3. If you are chYanging the output radix, pull down the menu in the; Output Radix entry box and click on the desired radix.B 4. Click on Apply to give the command or click on OK to give the( command and dismiss the dialog box.F Your echoed command and the current value appear in the command view.+ Click on Cancel to dismiss the dialog box.0 Click on Help to display this Help information. 2 deposit_hlp=Title Deposit Dialog Box)=include debugui src_commands_pd_menu_hlpC The Deposit dialoZg 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:F - Find and select the variable name in a window, and choose theE Deposit menu item from the Commands menu on the main window.F The Deposit dialog box appears, with the name you selected in the Variable field.H - Choose the [Deposit menu item from the Commands menu on the mainH window. The Deposit dialog box appears. Enter the name of theE variable to which you are depositing a value in the Variable! field of the dialog box.H 2. Enter the value you are depositing in the Value field of the dialog box.C 3. If you are changing the input radix, pull down the menu in the: Input Radix entry box and click on the desired radix.B 4. Click on Apply to give the command or cli\ck on OK to give the( command and dismiss the dialog box.F Your echoed command and the current value appear in the command view.+ Click on Cancel to dismiss the dialog box.0 Click on Help to display this Help information.E 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_hlpF 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,F or a full text buffer containing the text you will  edit.C Search String Accepts a string for forward ^or backward search. Entry Box A Directional Indicates the direction (forward, backward) of Arrows a search.C Replace String Indicates whether search string is replaced when Toggle found.? Replace String Accepts a string that replaces the specified! Entry Box search string.B 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.6 The direction of the search is controlled as follows:D - Press an arrow key to search text in the direction indicated by> that arrow. This also sets the default search direction.G - Press Ctrl/N to search forward (down) through the file, regardless% of the arrow indicator position.G - Press Ctrl/P to search backwards (up) through the file, regardless% of the ar`row indicator position.H If you click the "Replace with" toggle button, the editor replaces eachH 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.H After you enter the search string in the Find Text field and indicate aG search direction, click the "Replace with" toggle button and enter theE replacement string. The editaor 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_hlpE 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_hlpC By default,the editor window displays an empty text buffer, calledH b dbg_editor_main. If you are debugging a program at the time you invokeH the editor, however, the editor window displays this program, names theF filled text buffer with its specification, and places dbg_editor_main2 on the buffer menu as an alternative text buffer.G The editor allows you to create any number of text buffers by choosingH New (for empty text buffers) or Open (for existing files) from the FileD menu. The name of each buffer appears in the buffer menu. You canD cut, copy, an cd paste text across buffers by choosing items from the6 Edit menu and selecting buffers from the buffer menu. 2 search_text#=Title Searching and Replacing Text=include debugui editor_hlpG Forward and backward search and replace operations can be performed byC entering strings in the Find text and Replace with entry boxes and! clicking on a directional arrow.G If you continue to click on a directional arrow, or if you continue toE press the Return key, a repeated search for the strding occurs in the direction you indicate.D You can also continue a search by choosing the Find/Replace Next or. Find/Replace Previous items in the Edit menu.2 recompile_edits3=Title Recompiling and Relinking Edited Source Code=include debugui editor_hlpF When you complete your edits, and save these to your file by choosingC the Save or Save As items from the editor's File menu, you need to' recompile and relink your source file.1 You do not need to exit the debugger to do thise.H Enter the compile and link commands in another DECterm window, and whenH 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 ------ --------f, New Opens a buffer for a new file. 1 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. Editor2 editor_filesel_hlp=Title Open/Save Dialog Box=include debugui editor_hlp)=include debugui src_commands_pd_menu_hlpA Use the Open/Save dialog box to specify the file you are openingC (before edigting) or the file you are saving to (after editing), as follows:= 1. If the default value (for your current directory) is notA acceptable, click on the name of another directory from the  directory list.D 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 follhows: Action Function ------ --------6 Cut Cuts selected text from the window and+ copies it to the clipboard.7 Copy Copies selected text from the window to1 the clipboard without removing it! from the window. 3 Paste Pastes text from the clipboard to a, text-entry field or region. 6 Clear Clears the text selected (highlighted) in the window.5i Find/Replace Finds and replaces the next instance. Next  (or Ctrl/N) 8 Find/Replace Finds and replace the previous instance. Previous  (or Ctrl/P)5 Refresh File Loads and displays the latest version2 of the file in the selected editor8 buffer. This is convenient for checking3 .LOG and other results files during debugging.3 Close File Removes the currently selected edit1 jbuffer from the display and menu,5 closes the file, and frees associated; memory. Prompts the user to save or ignore5 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 ------ --------7 None Identifies the text buffer that is k% currently active.; Pull-down menu Identifies all other text buffers that > are currently active, including the empty 1 text buffer, dbg_editor_main.9 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 B menu items from the Edit menu and selecting buffers) from thel 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 ------ --------7 File View Closes dialog box or exits debugger.0 Breakpoint View m Displays the breakpoint view.3 Monitor View Displays the monitor view. 1 Instruction View Displays the instruction view.1 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_optionns_pd_menu_hlp=include debugui on_owindow_hlp% Use the Views dialog box as follows: Action Function ------ --------0 Breakpoint View Displays the breakpoint view.2 Monitor View Displays the monitor view. 1 Instruction View Displays the instruction view.1 Register View Displays the register view. - Threads View Displays the threads view.2 views3=title Displaying Views in the Optional View Window=include debugui on_owoindow_hlpD At startup, the debugger displays only one window, the main window.G To display additional information on your program in the optional view% window, perform the following steps:E 1. Choose the Views... menu item from the Options menu on the main+ window. The Views dialog box appears.C 2. Click on one or more of the following views in the dialog box:4 Breakpoint View Displays the breakpoint view.1 Monitor View Displays the monitor view.5 p Instruction View Displays the instruction view.2 Register View Displays the register view.2 Threads View Displays the threads view. C These views appear within the optional view window on your screen.F 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_hlpG To dismiss all views and close the optional view window, do one of qthe following:H - Choose the Views... menu item from the Options menu on the main orH optional view window. When the Views dialog box appears, clear all? the toggle buttons within the dialog box, and click on OK.G - Choose the Close menu item from the File menu on the optional view. window to close the optional view window.E - Choose the Close menu item from the File menu on the instruction, window to close the instruction window.2 custm_db_hlp=title Crustomize 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.9 NOTE: You cannot modify or remove the Stop push button.2 custm_add_hlp)=title Asdd Button on Customize Dialog Box=include debugui custom_button=include debugui custm_db_hlpD 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_hlpB 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 otn Customize Dialog Box=include debugui custom_button=include debugui custm_db_hlpH Use the Remove push button to remove a push button from the push-button view in the main window.2 custm_larrow_hlp0=title Left Arrow Button on Customize Dialog Box=include debugui custom_button=include debugui custm_db_hlpG Use the Left Arrow button to move a push button one push button to the left in the push-button view.2 custm_rarrow_hlp1=title Right Arrow Button on Customize Dialog Boxu=include debugui custom_button=include debugui custm_db_hlpF 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_hlpA Invisible: Brings up the ? pointer for context-sensitive help.2 on_mwindow_hlp=title Using the Main Window"=include debugui decwindows_basics=include debugui ovn_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_supportD The OpenVMS Debugger helps you locate run-time programmin wg or logicF errors, also known as bugs. You use the debugger with a program thatF has been compiled and linked successfully but does not run correctly.A For example, the program might give incorrect output, go into anE infinite loop, or terminate prematurely. You locate errors with theH debugger by observing and manipulating your program interactively as it" executes. The debugger lets you:B - Display and edit the source code for your program, and browse% through other source codex files.E - Monitor, examine, and change program variable and data structure# values and examine their type.F - Examine and manipulate the currently active functions on the call stack.E - 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.) y - Customize the debugging environment.H These are the basic debugging techniques. After you are satisfied thatF you have found the error in the program, you can edit the source code6 and compile, link, and execute the corrected version.A 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.F The debugger is a symbolic debugger. You can specify variable names,H routine nzames, and so on, precisely as they appear in your source code.H You do not need to specify memory addresses or registers when referring/ to program locations, but you can if you want.B You can also use the debugger with programs written in any of theB 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 taskD The OpenVMS Debugger helps you locate run-time programming or logicF errors, also known as bugs. You use the debugger with a program thatF has been compiled and linked successfully but does not run correctly.A For example, the program might give incorrect output, go into anE infinite loop, or terminate prematurely. You locate errors wit|h theH debugger by observing and manipulating your program interactively as it" executes. The debugger lets you:B - Display and edit the source code for your program, and browse% through other source code files.E - Monitor, examine, and change program variable and data structure# values and examine their type.F - Examine and manipulate the currently active functions on the call stack.E - 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.H These are the basic debugging techniques. After you are satisfied thatF you have found the error in the program, you can edit the source code6 and compile, link, and execute the corrected version.A As you use the debugger and its doc ~umentation, you will discover@ variations on the basic techniques. You can also customize the! debugger to meet your own needs.F The debugger is a symbolic debugger. You can specify variable names,H routine names, and so on, precisely as they appear in your source code.H You do not need to specify memory addresses or registers when referring/ to program locations, but you can if you want.B You can also use the debugger with programs written in any of theB 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_editsF 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 programE - Set, activate, deactivate, or delete breakpoints on instructionsG 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_hlpB Several kinds of online help about the debugger and debugging are& available during a debugging session:B - Context-sensitive help, which is information about an area or% object in a window or dialog boxF - Task-oriented help, which consists of an introductory help topicsH  describing the tasks that can be accomplished in each window of the? debugger and several subtopics on specific debugging tasksC - Help on debugger commands and various topics, such as language support) - Help on debugger diagnostic messagesA 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 Debugger6 Software Version: OpenVMS Debugger Version 8.4-1H1" Copyright 2015 VMS Software, Inc. All rights reserved.G 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_hlp2 debug_error_hlp=Title Debugger Internal ErrorsA The error dialog box contains a brief description of an internalF inconsistency detected by the debugger. If the cause of the error is= not obvious, select the Help Menu on the Main Window, selectG On_Commands, select Messages, and scroll through the display until youG can select the message code that is displayed in the error dialog box.D 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:D - 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 breakpointsA Breakpoints are listed in the Identification column of the view,? including the module name and line number for each breakpoint.H All breakpoints listed in the breakpoint view have be en previously set.H A filled-in button in the State column indicates that the breakpoint isD set and active. A cleared button indicates that the breakpoint hasE been deactivated. (If you delete a breakpoint, the breakpoint entry& disappears from the breakpoint view.)H If you have set a conditional breakpoint, the button shape changes fromH a square to a diamond. You can also double-click on a breakpoint entryC to determine whether conditions or actions are associated with it. 2 popup_break8=Title Context-Sensitive Pop-up Menus in Breakpoint View$=include debugui breakpoint_disp_hlpC To use the pop-up menu in the breakpoint view, position your mouseD pointer in the breakpoint list or annotation area of the breakpoint view, and press MB3.0 A pop-up menu with the following items appears:6 Toggle Toggles a selected breakpoint.F Set/Modify... Provides the Set/Modify Breakpoint dialog box,C which contains information about a selected- breakpoint. 6 Cancel Removes a selected breakpoint.G Step Step to next line, stepping over routine calls.4 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 orD expression in the source view and click on the Monitor push button.G The debugger displays the current value in the monitor view and checksF and updates the displayed value whenever it regains control from your8 program (for example, after a step or at a breakpoint).> Monitored variables and expressions are listed in the MonitorA Expression column. Their values are listed in the Value/Deposit column.C The button in the Watched column indicates whether the variable is5 being watched (button filled) or not (button empty).2 popup_monitor5=Title Context-Sensitive Pop-up Menus in Monitor View!=include debugui monitor_disp_hlpH To use the pop-up menu in the monitor view, position your mouse pointer$ in the monitor view, and press MB3.0 A pop-up menu with the following items appears:I Expand Expand a monitored aggregate to show its members.7 Collapse Collapse an expanded aggregate.G Toggle Watchpoint Activates or deactivates a selected watchpoint.O Typecast -> Provides the list of type choices for modifying values.P Change Radix -> Provides the list of radix choices for modifying values.H Remove Remove the selected expression from the monitor 1 list of the monitor view.G Step Step to next line, stepping over routine calls.4 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 highlighted9 whenever the debugger regains control from your program.2 popup_register6=Title Context-Sensitive Pop-up Menus in Register View"=include debugui register_view_hlpA To use the pop-up menu in the register view, position your mouse- pointer in the register view, and press MB3.5 A pop-up menu with the following menu items appears:P Change Radix -> Provides the list of radix choices for modifying values.G Step Step to next line, stepping over routine calls.4 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 programE - Set, activate, deactivate, or delete breakpoints on instructions2 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 programE - Set, activate, deactivate, or delete breakpoints on instructions2 popup_instruction9=Title Context-Sensitive Pop-up Menus in Instruction View"=include debugui inst_workarea_hlp=include debugui inst_view_hlp E To use pop-up menus in the instruction view, select text or positionB your mouse pointer in the instruction window, and press MB3. TheG debugger inserts the selected text or line number in the menu items of the pop-up menu.B If you press MB3 while your mouse pointer rests on an instructionH source line in the instruction window, a pop-up menu with the following items appears:? Examine [selection] Evaluates the selected text and prints 6 its value in the command view.I Toggle Breakpoint Toggle breakpoint at your mouse pointer location. [line number]C Display Source Display source associated with instruction.G Step-Instructions Step to next instruction, stepping over routine calls.G Step Step to next line, stepping over routine calls.4 Go Resume execution of program.G If you press MB3 while your mouse pointer rests in the annotation areaB of the instruction window, a pop-up menu with the following items appears:I Toggle Breakpoint Toggle breakpoint at your mouse pointer location.G Step Step to next line, stepping over routine calls.4 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_taskH 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_taskF 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_taskF Use the threads view to display information about the threads (tasks) of a multithreaded program. 2 popup_task5=Title Context-Sensitive Pop-up Menus in Threads View=include debugui task_view_hlp"=include debugui task_workarea_hlp=include debugui cnt_window_hlpG To use pop-up menus in the threads view, select a thread from the listC or position your mouse pointer in the threads view, and press MB3.5 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 9 equivalent to executing an abort statement.: Activate Makes the selected thread the active thread.1 Hold Places the selected thread on hold.3 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_hlpE 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 ------ --------6 Close Closes the optional view window.5 Exit Debug? In the kept debugger, ends the 7 debugging session, and exits the 7 debugger. In client-server mode,4 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 ------ --------2 On Exception Breaks on any exception signaled+ during program execution. . Activate All Activates any previously set breakpoints.0 Deactivate All Deactivates any previously set breakpoints. 2 Cancel All... Removes all breakpoints from the0 debugger's breakpoint list and, from the breakpoint view. 3 Toggle Toggles an individual breakpoint.= Set/Modify... Sets or modifies an individual breakpoint. 3 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.2 Deposit... Changes the value of variable. Toggle : Watchpoint Activates or deactivates a watchpoint.2 Typecast -> Typecasts a selected variable.> Change Radix -> Changes the radix for a selected variable. Change All A 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 ------ --------3 Assign... Modifies the selected register.> Change Radix -> Changes the radix for a selected register. Change All8 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 is9 language dependent). For Ada tasks, this is 8 equivalent to executing an abort statement.9 Activate Makes the selected thread the active thread.0 Hold Places the selected thread on hold.2 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_hlpE 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_hlp6 Use the File menu on the Instruction View as follows: Action Function ------ --------5 Show Instruction Displays the address associated5 Addresses with each instruction listed in+ the instruction view.6 Display Line Displays the line number of your: Numbers source-code program associated with = each instruction or set of instructions5 listed in the instruction view.4 Close Closes the instruction window.2 inst_edit_pd_menu_hlp$=Title Edit Menu on Instruction View=include debugui instruction"=include debugui inst_workarea_hlp6 Use the Edit menu on the instruction view as follows: Action Function ------ --------5 Copy Copies text that you have selected in the 6 window to the clipboard without removing it from the window.4 (To paste your text from the clipboard to3 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_exception9 Use the Break menu on the instruction window as follows: Action Function ------ --------. Activate All Activates any previously set breakpoints.0 Deactivate All Deactivates any previously set  breakpoints. 2 Cancel All Removes all breakpoints from the0 debugger's breakpoint list and- from the instruction view. 1 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 aE DECwindows Motif debug client and a debug server running on OpenVMS.D You can use the Server Connection dialog to make new connections toA servers, reconnect to servers that you have connected to before,C monitor the status of existing active sessions, switch the displayH context among active sessions, test and shutdown server s, 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 theH Connection dialog box, click the Properties button, or open the Options> menu, then click Connection dialog on the Properties submenu.G 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 serverH identified in the Connection list. Status of the connection request isB displayed in the message display of the Command view. AdditionalE status is displayed at the bottom of the Server Connection dialog toH indicate whether the requested connection has been establ ished as a new active session.D When a connection has been successfully made to a server the ServerF Connection dialog is dismissed and the Command view displays a client? prompt to indicate that the server is ready to accept debuggerD 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 debug ui server_connection_helpD Click Disconnect to disconnect the client from the currently active2 session as indicated in the Active Sessions list.2 conn_dialog_test&=Title Server Connection Dialog - Test'=include debugui server_connection_helpC Click Test to test the connection between the debug client and theD debug server. If the connection is operating correctly, the statusE "Server is Listening" appears in the lower portion of the Connection dialog box.2 conn_dialog_stop&=Title S erver Connection Dialog - Stop'=include debugui server_connection_helpC Click Stop to cause the debug server associated with the currently active session to be shut down.G Note: Once a server has been shut down, clients can no longer connectH 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%=inc lude debugui c_s_secondary_client'=include debugui server_connection_helpD Click Options in the Server Connection dialog to display the ServerF Options dialog for the currently selected session as indicated by theB Active Sessions list in the Server Connection dialog. The ServerH Options dialog lets you select the connection protocol, and the maximum; number of clients that are allowed to connect to a server.F Once a session has been established, you cannot change the connectionG protoco l. If you are the first client (the primary client) to connectE 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_helpF The primary client is the first client to connect to the server. TheH primary client uses the Server Options dialog to control whether or not1 any secon dary 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_helpE A secondary client is an additional client that has connected to theD same server. Each clients that is connected to a session can enterH debugger commands in the context of that session. The debugger displayH of each client connected to that session is updated reflect the current conte xt of the session.B Whether or not secondary clients are allowed is controlled by the- primary client in the Server Options dialog.2 conn_dialog_connections1=Title Server Connection Dialog - Connection List'=include debugui server_connection_helpH Use the Connection [local] list to specify the identification string ofF the debug server with which you want to establish a session. Type orE select the identification string in the New Connection box. The NewH Connection list contains th e last 10 connections that you have made andB provides a convenient way to reconnect to a server from which youG previously disconnected and left running. Note that the presence of aH connection path in the list does not guarantee that the server is still availableH The most simple connection string contains the name of the OpenVMS nodeB 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_sessions6=Title Server Connection Dialog - Active Sessions List'=include debugui server_connection_helpE The Active Sessions list contains the sessions (connections to debugG servers) that this client has already established. The session at theE top of the list is the currently active session. All debugger viewsC reflect the context of the pr ogram being debugged on the currently active session.G You can switch between active sessions by selecting a session from theE Active Sessions list. The Source view for that session is activatedH and all other debugger views are updated to reflect the program context of that session.H All buttons on the Server Connection dialog, including Disconnect, StopH Server, Test and Properties as well as the status section of the ServerC 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_help6 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_hlpE The debugger has the following user-interface options to accommodate& different needs and debugging styles:D - The debugger has a DECwindows Motif interface for workstations.H The default DECwindows Motif interface provides the basic debuggingE and convenience features that you will probably need most of the time.F - The debugger has a command interface for character-cell terminals@ and workstations. In addition to general-purpose debuggingB features, the command interface provides special features not> available through the default DECwindows Motif interface.G - The DECwindows Motif interface is layered on the command interfaceD and has a command-entry prompt (in the command view of the mainA window). From the DECwindows Motif interface, you can enter2 debugger commands for the following purposes:F + As an alternative to using the DECwindows Motif interface for certain operations? + To do tasks not available through the DECwindows Motif interfaceF - You can customize the DECwindows Motif interface with many of theD special features of the command interface by modifying the pushC 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_hlpH By default, the debugger starts up in the main window, which includes a5 source view, a push-button view, and a command view.H When you start the debugger with the command DEBUG/KEEP from DCL level,H 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_hlpD The debugger's DECwindows Motif interface is layered on the commandD interface. The command-entry prompt (DBG>), located in the command C view, lets you enter debugger commands for the following purposes:B - As an alternative to using the DECwindows Motif interface for certain operationsE - To do debugging tasks not available through the DECwindows Motif interfaceE When you use the DECwindows Motif interface, the debugger translatesE your input into debugger commands. These commands are echoed in theG command view, at the prompt, so that you can correlate your input withD the corresponding command l ine that the debugger processes. EchoedE commands are visually indistinguishable from commands that you enter explicitly.G In addition to entering debugger commands interactively at the prompt,E you can also enter them in debugger initialization files and command< files for execution under the DECwindows Motif environment.2 disabled_vms_cmdsD=title Debugger Commands Not Available in DECwindows Motif Interface=include debugui cmd_entry=include debugui msg_region_hlp=include deb ugui command_helpG The following table lists the debugger commands that are not available@ in the debugger's DECwindows Motif interface. Many of them are6 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 F The debugger issues an error message if you try to enter any of theseD 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_hlpE 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 SCANG 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 E On I64 processors, you can use the debugger with programs written in' any of the following source languages:: Assembler (IAS) BASIC BLISS C 9 C++ COBOL Fortran MACRO-32( IMACRO Pascal H The debugger recognizes the syntax, data types, operators, expressions,= scoping rules, and other constructs of a supported language.G 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.A 3. Choose the language name from the list of Additional Topics. 2 trademarks3=title Additional Trademark and Product Information=include debugui on_version_hlpE Confidential computer software. Valid license from VSI required forD possession, use or copyin g. Consistent with FAR 12.211 and 12.212,C Commercial Computer Software, Computer Software Documentation, and= Technical Data for Commercial Items are licensed to the U.S.7 Government under vendor's standard commercial license.F The information contained herein is subject to change without notice.G The only warranties for VSI products and services are set forth in theE express warranty statements accompanying such products and services.A Nothing herein should be construed as constituting an additionalH warranty. VSI shall not be liable for technical or editorial errors or omissions contained herein.E Intel and Itanium are trademarks or registered trademarks of Intel? Corporation or its subsidiaries in the United States and other countries. 2 compile7=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_hlpE To bring a program un der debugger control and take full advantage ofC symbolic debugging, you must first compile and link the program as explained here.D You can use the debugger with programs written in any of the sourceC languages listed in the topic Debugger Support for Languages. TheB following example shows how to compile and link a C program namedD EIGHTQUEENS before using the debugger. The compiler and linker areF invoked from DCL level ($). The program's source code is in the file EIGHTQUEENS.C.E On VAX systems, you explicitly identify linker options files in your LINK command:$ $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS0 $ LINK/DEBUG EIGHTQUEENS,OPTIONS_FILE/OPTIONSD On Alpha and I64 systems, you do not identify linker options files:$ $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS $ LINK/DEBUG EIGHTQUEENSH The /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults forH some languages. These qualifiers are used in the example for emphasis.H (For more information about com piling and linking that is specific to a? particular language, see the documentation furnished with that language.)G The /DEBUG qualifier on the compiler command (CC in this case) directs= the compiler to write the symbol information associated withF EIGHTQUEENS.C into the object module, EIGHTQUEENS.OBJ, in addition toE the code and data for the program. This symbol information lets youD use the names of variables, routines, and other symbols declared inF EIGHTQUEENS.C when using the debugger. If your program's source codeG is in several files, you must compile each file whose symbols you want( to reference with the /DEBUG qualifier.B Some compilers optimize the object code to reduce the size of theD program or to make it run faster. In such cases you should compileD your program with the /NOOPTIMIZE command qualifier (or equivalent)G when preparing for debugging. Otherwise, the contents of some programH locations might be inconsistent with what you would expect from viewingF the source code. For example, some optimization techniques eliminateB certain variables so that you no longer have access to them whileD debugging. (After the program has been debugged, you will probably? want to recompile it without the /NOOPTIMIZE qualifier to take advantage of optimization.)G The /DEBUG qualifier on the LINK command directs the linker to includeC all symbol information that is contained in EIGHTQUEENS.OBJ in theD executable image. The qualifier also causes the image activator toF start the debugger at run time if you start the debugger by running a1 program, using the following DCL command syntax: $ DEBUG/KEEPF If your program has several object modules, you need to specify those2 modules in the LINK command (for most languages).F 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 commandF qualifier, you can execute that image normally without it being underG debugger control. To do so, use the /NODEBUG qualifier on the DCL RUN command. For example: $ RUN/NODEBUG EIGHTQUEENSC This is convenient for checking your program after you think it isH error free. Note that the data required by the debugger occupies spaceA within the executable image. So, when you think your program isF correct, you might want to li nk your program again without the /DEBUGH qualifier. This creates an image with only traceback data in the debug* symbol table, which uses less disk space.G On Alpha and I64 systems, you can debug programs that have been linkedD with the /DSF qualifier (and therefore have a separate debug symbolD file). The /DSF qualifer to the LINK command directs the linker toE create a separate .DSF file to contain the symbol information. ThisB allows more flexible debugging options. Debugging such a program requires the following:C 1. The name of the .DSF file must match the name of the .EXE file being debugged.F 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 TESTPROGRAM2 $ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR] $ DEBUG/KEEP TESTPROGRAM2 stop==title Interrupting Program Execution and Debugger Operations=include debugui run_new_hlp=include debugui rerun_same_hlp=include debugui on_mwindow_hlpH To interrupt program execution during a debugging session, click on theF 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.C To abort a debugger operation in progress, click on Stop. This isD useful if, for example, the debugger is displaying a long stream of data.G Clicking on Stop does not end the debugging session. Clicking on StopE 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_hlpE To end a debugging session and exit the debugger, choose Exit Debug?D from the File menu on the main window. This invokes a Confirm ExitF dialog box to verify that you wish to exit the debugger. In the kept? debugger, clicking on Yes returns control to system level. InH client-server mode, allows you to exit the client, the server, or both.B To rerun your program from the current debugging session, see the" Rerunning the Same Program topic.C To run another program from the current debugging session, see the1 Bringing a Program Under Debugger Control topic. 2 src_display1=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_hlpD The debugger displays the source code of your program in the source view of the main window.D Whenever execution is suspended (for example, at a breakpoint), theF debugger updates the source view, which displays the code surroundingG the point at which execution is paused. The current-location pointer,G to the left of the source code, marks the line whose code will executeF next. (A source line corresponds to one or more programming language9 statements, depending on the language and coding style.)E By default, the debugger displays compiler-generated line numbers to> the left of the source code. These numbers help you identifyH breakpoints that are listed in the breakpoint view. You can choose notH to display line numbers so that more of the source code can show in theH window. To hide or display line number s, choose Show Line Numbers from" the File menu on the main window.E The Call Stack menu, at the bottom right of the source window, shows8 the name of the routine whose source code is displayed.F The current-location pointer is normally filled in. It is cleared ifD the displayed code is not that of the routine in which execution isA paused (see the Making Source Code Available for Display and the> Setting the Current Scope Relative to the Call Stack topics).G You can use the scroll ba rs to show more of the source code. However,G you can scroll vertically through only one module of your program at aD time. (A module corresponds generally to a compilation unit. WithF many programming languages, a module corresponds to the contents of aD source file. With some languages, such as Ada, a source file might contain one or more modules.)C The Displaying Source Code in Another Module topic explains how toH display source code for other parts of your program so that you can set+ breakpoints in various modules, and so on.G The Making Source Code Available for Display topic explains what to do5 if the debugger cannot find source code for display.H The Setting the Current Scope Relative to the Call Stack topic explainsE how to display source code for routines that are currently active on the call stack.@ After navigating through the source view, you can redisplay theD location at which execution is paused by clicking on the Call Stack menu.B If your program was optimized during compilation, the source code@ displayed might not reflect the actual contents of some programD 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:F 1. Choose Browse Source from the File menu on the main window. FromD the submenu, select All to list all modules, select Symbolic to> l ist only those modules for which symbolic information isC available. The Browse Source dialog box appears, listing yourB executable image, which is highlighted, and all the shareableH images linked with it (for example, DEBUG and LIBRTL). If the nameD of an image is dimmed, no symbolic information is available for that image.E 2. Double click on the name of your executable image. The names ofG the modules in that image are displayed (indented) under the image  name.B 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_displayE In certain cases, the debugger cannot display source code. Possible causes are:G - Execution might be paused within a module of your program that was' compiled without the debug option.E - Execution might be paused within a system or library routine forH which no symbolic information is intended to be available. In suchE cases you can quickly return execution to the calling routine byE clicking one or more times on the Step-Return push button on the) push-button view of the main window.C - The source file might have been moved to a differen t directoryH after it was compiled. The Specifying the Location of Source FilesE topic explains how to tell the debugger where to look for source files.A If the debugger cannot find source code for display, it tries toH display the source code for the next routine down on the call stack forD which source code is available. If the debugger can display sourceE code for such a routine, the current-location pointer is cleared and@ marks the source line to which execution retu rns in the calling routine.2 src_display_srcfile.=Title Specifying the Location of Source Files=include debugui cmd_entry=include debugui src_displayG Information about the characteristics and the location of source filesD is embedded in the debug symbol table of your program. If a sourceE file has been moved to a different directory since compile time, theB debugger might not find the file. To direct the debugger to yourF 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_hlpE The Additional Topics explain techniques for executing your program. 2 exec_paused6=title Determining Where Execution is Currently Paused=include debugui src_display#=include debugui callsta ck_menu_hlp=include debugui executeF To determine where execution is currently paused within your program:G 1. If the current-location pointer is not visible in the source view,H click on the Call Stack menu of that window to display the pointer.* 2. Look at the current-location pointer:D - If the pointer is filled in, it marks the source line whoseF code will execute next. The Call Stack menu always shows theH routine at level 0 (where execution is paused ) when the pointer is filled in.H - If the pointer is cleared, the source code displayed is that ofD a calling routine, and the pointer marks the source line to< which execution returns in that routine as follows:E + If the Call Stack menu shows level 0, source code is notH available for display for the routine in which execution is paused.G + If the Call Stack menu shows a level other than 0, you are>  displaying the source code for a calling routine.G To list the sequence of routine calls that are currently active on theG call stack, click on the Call Stack menu. Level 0 denotes the routineG 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 res ume execution from the currentE location, click on the Go push button on the push-button view of the main window.H Letting your program run freely without debugger intervention is useful% in situations such as the following:F - To test for an infinite loop. In this case, you start execution;H then, if your program does not terminate and you suspect that it isG looping, click on the Stop push button. The source view will showE where you interrupted program execution, and the Call Stack menu? will identify the sequence of routine calls at that point.H - To execute your program directly to a particular location. In thisD case, you first set a breakpoint at the location and then start execution.E Once started, program execution continues until one of the following events occurs:$ - The program completes executionF - A breakpoint is reached (including a conditional breakpoint whose condition is true) - A watchpoint is triggered - An exception is signaledE - You click on the Stop push button in the push-button view on the main window.D Whenever the debugger suspends execution of the program, the sourceF view is updated and the current-location pointer marks the line whose code will execute next.2 step_one_line7=title Executing Your Program One Source Line at a Time=include debugui cnt_button_hlp=include debugui src_display=include debugui compile=include debugui executeC To execute one source line of your program, click on the Step pushC 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 theF current-location pointer marks the line whose code will execute next.H Note the following points about source lines and the stepping behavior:B - A source line can consist of one or more programming language? elements, depen ding on the language and coding style used.F - When you click on the Step push button, the debugger executes oneD executable line and suspends execution at the start of the nextD executable line, by skipping over any intervening nonexecutable lines.H - Executable lines are those for which instructions were generated byE the compiler (for example, lines with routine call or assignmentF statements). Executable lines have a toggle button to their left in the source view.D - Examples of nonexecutable lines are comment lines or lines withD variable declarations without value assignments. NonexecutableH lines do not have a toggle button to their left in the source view.F Keep in mind that if you optimized your code at compilation time, theB 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 executeG When program execution is paused at a routine call statement, clickingE on the Step push button typically executes the called routine in oneE step (depending on the coding style used), and the debugger suspendsF execution at the next source line in the calling routine (assuming noC breakpoint was set within the called routine). This lets you stepG through the code quickly without having to trace execution through anyE called routines (some of which might be system or library routines).. This is called stepping over called routines.G To step into a called routine so that you can execute it one line at a time:E 1. Suspend execution at the routine call statement, for example, byH setting a breakpoint (see the Suspending Execution with BreakpointsF topic) and then clicking on the Go push button on the push-button view of the main window.A 2. When execution is paused at t he call statement, click on theD Step-In push button on the push-button view of the main window.D This moves execution just past the start of the called routine.F Once execution is within the called routine, use the Step push button% to execute the routine line by line.F Clicking on the Step-In push button when execution is not paused at aH routine call statement is the same as clicking on the Step push button. 2 step_return&=title Returning from a Called Routine=include deb ugui cnt_button_hlp=include debugui src_display"=include debugui src_display_nosrc=include debugui setscope=include debugui executeE When execution is suspended within a called routine, you can executeD your program directly to the end of that routine by clicking on theD Step-Return push button on the push-button view of the main window.A The debugger suspends execution just before the routine's returnG instruction executes. At that point, the routine's call frame has notE 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 have8 inadvertently stepped into a system or library routine.2 break6=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_actionG A breakpoint is a location in your program at which you want executionD to stop so that you can check the current value of a variable, step into a routine, and so on.B 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 program7 The debugger provides two ways to qualify breakpoints:C - 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 moreE 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 breakH 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.) TheG 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 breakF 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:F 1. Choose Browse Source from the File menu on the main window. FromD the submenu, select All to list all m odules, select Symbolic to> list only those modules for which symbolic information isB available. The Browse Source dialog box appears listing yourB executable image, which is highlighted, and all the shareableH images linked with it (for example, DEBUG and LIBRTL). If the nameD of an image is dimmed, no symbolic information is available for that image.E 2. Double click on the name of your executable image. The names ofG the modules in that image are displayed (indented) under the image name.F 3. Double click on the name of the module whose source code you wantH to display. The names of the routines in that module are displayed in the Routine column. 4. Do one of the following:E - Double-click on the name of the routine on which you want to set a breakpoint.H - Click on the name of the routine and then on the Set Breakpoint button.B Either of these actions sets a breakpoint at th e start of theG routine (directly after any prolog code). In the source view, theC toggle button to the left of the source line that contains the? start of the routine is now filled in, confirming that theH breakpoint is set. (If the breakpoint view is open, the breakpointF will appear in the breakpoint list. If the instruction window isA open, the breakpoint will also display for the corresponding instruction.)2 break_instruction*=title Setting Break points on Instructions"=include debugui inst_workarea_hlp=include debugui on_iwindow_hlpH You can set a breakpoint on any instruction that has a toggle button toD 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 isC signaled and before any exception handler declared by your programF executes. This allows you to step into the exception handler (if one, is available) to check the flow of control.C To se t an exception breakpoint, choose On Exception from the BreakC menu. The exception breakpoint triggers whenever any exception is signaled.2 break_identify0=title Identifying the Currently Set Breakpoints=include debugui break_activ=include debugui src_display=include debugui breakE There are two ways to determine which breakpoints are currently set:F - Scroll through your source or instruction code and note the linesC whose breakpoint button is filled in. This method can be timeD consuming and also does not show which breakpoints were set and then deactivated.H - Choose Views... from the Options menu on the main or optional viewH window. When the Views dialog box appears, toggle breakpoint view.F Within the breakpoint view display, breakpoints are listed in theE Identification column of the view, including the module name andF line number for each breakpoint. A filled-in button in the StateG column indicates that the breakpoint is set and active. A cleared? button indicates that the breakpoint is deactivated. (TheE breakpoint view does not provide information on breakpoints that2 have not been set or that have been deleted.) 2 break_activ6=title Deactivating, Activating, Canceling Breakpoints=include debugui break_srclin=include debugui break_routine"=include debugui break_instruction=include debugui breakC After you set a breakpoint, you can deactivate it, activate it, or cancel it.B Deactivating a breakpoint causes the debugger to ignore it duringF program execution. However, the debugger keeps the breakpoint listedH in the breakpoint view so that you can activate it at a later time, forA example, when you rerun the program. Note the following points:C - To deactivate a specific breakpoint, clear the button for thatG breakpoint in the source view, the instruction code display, or in the breakpoint view.F In the breakpoint view, you can also choose Toggle from the Break4 menu, if the breakpoint is currently activated.H - 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:F - To activate a breakpoint, click on the button for that breakpointG in the source view, instruction code display, or in the breakpoint view.F In the breakpoint view, you can also choose Toggle from the Break6 menu, if the breakpoint is currently deactivated.D - To activate all breakpoints, choose Activate All from the Break< menu on the main, instruction, or optional view window.F Canceling a breakpoint causes all information about the breakpoint toH be lost. Once you cancel a breakpoint, you cannot later reactivate it,B but must again explicitly set the breakpoint. Note the following points:G - To cancel a specific breakpoint, choose Cancel from the Break menu! on the optional view window.H - To cancel all breakpoints, choose Cancel All from the Break menu on4 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 breakB A conditional breakpoint suspends execution only when a specifiedF expression is evaluated as true. For example, you can specify that aG 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.F The debugger evaluates the conditional expression when the breakpoint+ triggers during execution of your program.7 The following procedure sets a conditional breakpoint:H 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:F - Press Ctrl/MB1 on the button to the left of a source line, anH instruction line, or a breakpoint entry in the breakpoint view.E This causes the Set/Modify Breakpoint dialog box to display,? showing the line you selected in the Location: field.B - Choose the Set (main or instruction window) or Set/ModifyH (optional view window) menu item from the Break menu. When theG Set/Modify dialog box appears, enter the line in the Location: field.B 3. Enter a relational expression in the Condition: field of theF dialog box. The expression must be valid in the source language.E For example, a[3] == 0 is a valid relational expression in the C language.G 4. Click on OK. The conditional breakpoint is now set. The debuggerH indicates that a breakpoint is conditional by changing the shape of8 the breakpoint's button from a square to a diamond.G The following procedure mod ifies a conditional breakpoint; that is, it@ can be used to change the condition associated with an existingF conditional breakpoint, or to change an unqualified breakpoint into a conditional breakpoint: 1. Do one of the following:F - Press Ctrl/MB1 on the button to the left of a source line, anG instruction code line, or a breakpoint entry in the breakpoint view.G - Click on a breakpoint entry in the breakpoint view, and choose1 the Set/Modify item from the Break Menu.D 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 breakH When an action breakpoint triggers, the debugger suspends execution and, then executes a specified list of commands.3 The following procedure sets an action breakpoint:H 1. Display the source or instruction line on which you want to s et the action breakpoint.? 2. Display the Set/Modify Breakpoint dialog box in one of the following ways:F - Press Ctrl/MB1 on the button to the left of a source line, anH instruction line, or a breakpoint entry in the breakpoint view.E This causes the Set/Modify Breakpoint dialog box to display,F showing the source line you selected in the Location: field.B - Choose the Set (main window) or Set/Modify (optional viewD window) menu item from the Break menu. When the Set/ModifyC dialog box appears, enter the source line in the Location: field.E 3. Enter one or more debugger commands in the Action: field of the dialog box. For example:( DEPOSIT x[j] = 3; STEP; EXAMINE a4 4. Click on OK. The action breakpoint is now set.G The following procedure modifies an action breakpoint; that is, it canA be used to change the command associated with an existing actionB breakpoint, or to change an unqualified breakpoint into an action breakpoint: 1. Do one of the following:F - Press Ctrl/MB1 on the button to the left of a source line, anG instruction code line, or a breakpoint entry in the breakpoint view.G - Click on a breakpoint entry in the breakpoint view, and choose1 the Set/Modify item from the Break Menu.D 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_hlpF 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_depositG Use the following techniques to select variable names from windows for3 the operations described in the Additional Topics.B When selecting names, follow the syntax of the source programming language:E - To specify a scalar (nonaggregate) variable, such as an integer,D 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.E - To specify a single element of an aggregate variable, select the4 entity using the language syntax. For example:F + The string arr2[7] specifies element 7 of array arr2 in the C language.G + The string employee.address specifies the component address of< record (structure) employee in the Pascal language.G - To specify the object designated by a pointer variable,  select theC entity following the language syntax. For example, the stringG *int_point specifies the object designated by pointer int_point in the C language.2 Select character strings from windows as follows:E - In any window, to select a string delimited by blank spaces, useF the standard DECwindows Motif word-selection technique: position@ the mouse pointer on that string and then double click MB1.D - In any window, to select an arbitrary character strin g, use theF standard DECwindows Motif text-selection technique: position theC mouse pointer on the first character, press and hold MB1 whileF dragging the mouse pointer over the string, and then release MB1.C - In the debugger source view, you also have the option of usingH language-sensitive text selection. To select a string delimited byA language-dependent identifier boundaries, position the mouse/ pointer on that string and press Ctrl/MB1.G For example, suppose the source view contains the character string arr2[m], then:E + 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_depositE You can display the current value of a variable or expression in the following ways:: - Using the Examine push button in the push-button viewG - Using the Examine dialog box, accessed through the Command menu on the main windowG The Examine push button displays a current value most quickly, but theC 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:A 1. Find and select the variable name or expression in a window.D 2. Click on the Examine push button on the push-button view of theG main window. The debugger displays the variable or expression andH its current value in the command view. Note that this is the valueH of the variable or expression in the current scope, which might notG be the same as the source location where you selected the variable name or expression.G To display the current value using the Examine dialog box, perform the following steps: 1. Do one of the following:E - Find and select the variable name or expression symbols in aH window, and choose the Examine menu item from the Commands menuF on the main window. The Examine dialog box appears, with the< name you selected in the Variable/Expression field.H - Choose the Examine menu item from the Commands menu on the mainH window. The Examine dialog box appears. Enter the name of theG variable or symbols of the expression you are examining in the5 Variable/Expression field of the dialog box.C 2. If you are changing the output type, pull down the menu in the; Typecast entry box and click on the desired data type.D 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.F 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_depositE When you monitor a variable or expression, the debugger displays theE value in the monitor view and checks and updates the displayed valueF whenever the debugger regains control from your program (for example," after a step or at a breakpoint).% To monitor a variable or expression:C 1. Choose the Views... menu item in the Options menu on the main+ window. The Views dialog box appears.C 2. Click on monitor view within the dialog box. The monitor view) appears in the optional view window.A 3. Fin d and select the variable name or expression in a window.D 4. Click on the Monitor push button on the push-button view of the main window. The debugger:F - Puts the selected variable name or expression, along with its? qualifying path name, in the Monitor Expression columnD - Puts the current value of the variable in the Value/Deposit column4 - Puts a cleared button in the Watched column2 monitor_aggregate:=Title Monitoring an Aggre gate (Array, Structure) Variable=include debugui monitorE If you select the name of an aggregate variable, such as an array orF structure (record) and click on the Monitor push button, the debuggerG displays the word Aggregate in the Value/Deposit column of the monitor@ view. To display the values of all elements (components) of anE aggregate variable, double click on the variable name in the MonitorF Expression column. The displayed element names are indented relativeH to the parent nam e. If an element is also an aggregate, you can double6 click on its name to display its elements, and so on.G To contract an expanded display so that only the aggregate parent nameF is shown in the monitor view, double click on the name in the Monitor Expression column.C If you have selected a component of an aggregate variable, and theE component expression is itself a variable, the debugger monitors theH component that was active when you made the selection. For example, ifG you s elect the array component arr[i] and the current value of i is 9,A 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_addG If you select the name of a pointer (access) variable and click on the> Monitor push button, the debugger displays the address of theC referenced object in the Value/Deposit column of the monitor view.B To monito r the value of the referenced object (to dereference theC pointer variable), double click on the pointer name in the MonitorH Expression column. This adds an entry for the referenced object in the? monitor view, which is indented under the pointer entry. If aG referenced object is an aggregate, you can double click on its name to! display its elements, and so on.G 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 aC dereferenced value. If so, you enter the following command in the+ Command field of the Customize dialog box:  monitor *%sF 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_depositB Whenever the program changes the value of a watched variable, theG debugger suspends execution and displays the old and new values in the command view.H To watch a variable (also known as setting a watchpoint on a variable), proceed as follows:C 1. Monitor the variable as explained in the Monitoring a VariableD topic. The debugger puts a button in the Watched column of the2 monitor view whenever you monitor a variable.C 2. Click on the button in the Watched column. A filled-in button* indicates that the watchpoint is set.D To deactivate a watchpoin t, clear its Watched button in the monitorE view (by clicking on the button). To activate a watchpoint, fill in its Watched button.H The Accessing Static and Nonstatic (Automatic) Variables topic explainsH static and nonstatic (automatic) variables and how to access them. TheH debugger deactivates a nonstatic watchpoint when execution moves out ofB (returns from) the variable's defining routine. When a nonstaticF variable is no longer active, its entry is dimmed in the monitor view# and its Watched button is cleared.H The debugger does not reactivate nonstatic watchpoints automatically ifF 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:E - 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:F - Find and select the variable name in a window, and choose theE Deposit menu item from the Commands menu on the main window.F The Deposit dialog box appears, with the name you selected in the Variable field.H - Choose the Deposit menu item from the Commands menu on the mainH window. The Deposit dialog box appears. Enter the name of theE variable to which you are depositing a value in the Variable! field of the dialog box.H 2. Enter the value you are depositing in the Value field of the dialog box.C 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.E Your echoed command appears in the command view, indicating that the value is changed.B To change the value of a monitored value within the monitor view:C 1. Monitor the variable as explained in the Monitoring a Variable topic.E 2. Click on the variable's value in the Value/Deposit column of theE monitor view. A small dialog box appears over that value, which you can now edit.+ 3. Enter the new value in the dialog box.G 4. Click on the check mark (OK) in the dialog box. The dialog box is D removed and replaced by the new value, which indicates that theG variable now has that value. The debugger notifies you if you tryD to enter a value that is incompatible with the variable's type, range, and so on.H To cancel a text entry and dismiss the dialog box, click on X (Cancel).H You can change the value of only one component of an aggregate variableF (such as an array or structure) at a time. To change the value of an aggregate-variable component:F 1. Display the value of the component as explained in the Monitoring6 an Aggregate (Array or Structure) Variable topic.F 2. Follow the procedure for changing the value of a scalar variable. 2 variable0=Title Monitoring Local Variables and Parameters=include debugui watch=include debugui src_displayD 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 allA displ ayed values whenever the debugger regains control from your8 program (for example, after a step or at a breakpoint).H You cannot add or remove an entry to the local variables and parametersH list. The debugger automatically removes previous entries and adds newA entries when a new routine appears at the top of the call stack.* To monitor a local variable or parameter:F 1. Choose the Views... menu item in the Options menu on the main or9 optional view window. The Views dialog box appears.H 2. Click on the Local Variable View item in the Views dialog box. TheG Local Variable view appears. The debugger automatically lists allF local variable and parameter names (in the Expression column) and2 current values (in the Value/Deposit column).C To change the value of a monitored value within the local variable view:3 1. Monitor the local variable as explained above.E 2. Click on the variable's value in the Value/Deposit column of theF loc al variable view. A small dialog box appears over that value, which you can now edit.+ 3. Enter the new value in the dialog box.G 4. Click on the check mark (OK) in the dialog box. The dialog box isD removed and replaced by the new value, which indicates that theG variable now has that value. The debugger notifies you if you tryD to enter a value that is incompatible with the variable's type, range, and so on.H To cancel a text entry and dismiss the dialog box, click on X (Cancel).H You can change the value of only one component of an aggregate variableF (such as an array or structure) at a time. To change the value of an aggregate-variable component:F 1. Display the value of the component as explained in the Monitoring6 an Aggregate (Array or Structure) Variable topic.F 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_depositG The Additional Topics give some general considerations about accessing# program variables while debugging.E If your program was optimized during compilation, you might not haveA access to certain variables while debugging. When you compile aH program for debugging, it is best to disable optimization, if possible.H Before you check on the value of a variable, always execute the programF beyond the point where the variable is declared and initialized. TheC 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_varG NOTE: The generic term nonstatic variable is used here to denote what3 is called an automatic variable in some languages.F The technique for accessing a variabl e varies according to whether it# is a static or nonstatic variable.D The system differentiates between static and nonstatic variables by! determining how they are stored.H A static variable is associated with the same memory address throughoutD execution of the program. You can always access a static variable.H A nonstatic variable is allocated on the stack or in a register and hasG a value only when its defining routine or block is active. Therefore,C you can access a nonstatic va riable only when program execution is@ paused within the scope of its defining routine or block (which6 includes any routine called by the defining routine).H A common technique for accessing a nonstatic variable is first to set aF breakpoint on the defining routine and then to execute the program to the breakpoint.B Whenever the execution of your program makes a nonstatic variable4 inaccessible, the debugger notifies you as follows:C - If you try to display the value of the variable  or monitor theE variable, the debugger issues a message that the variable is not active or not in scope.D - If the variable is currently being monitored, its entry becomesH dimmed in the monitor view. When the entry is dimmed, the debuggerG does not check or update the variable's displayed value; also, youE cannot change that value. The entry is fully displayed whenever+ the variable becomes accessible again. 2 instruction@=Title Displaying the Decode d Instruction Stream of your Program(=include debugui cnt_options_pd_menu_hlp=include debugui compile=include debugui setscope=include debugui on_iwindow_hlpE The instruction view displays the decoded instruction stream of yourF program---the code that is actually executing. This is useful if theE program you are debugging has been optimized by the compiler so thatE the information in the source view does not exactly reflect the code that is executing.H To display the instructio !n view, choose Views... from the Options menuE on the main or optional view window. When the View Selection dialog& box appears, toggle Instruction View.D By default, the instruction view automatically displays the decodedB instruction stream of the routine in which execution is currentlyH paused. The current-location pointer, to the left of the instructions,. marks the instruction that will execute next.G By default, the debugger displays line numbers and memory addresses toF the lef "t of the instructions You can choose not to display numbers orE addresses so that more space is devoted to showing instructions. ToE hide or display line numbers, toggle the Display Line Numbers buttonG from the File menu on the instruction view. To hide or display memoryG addresses, choose Show Instruction Addresses from the File menu on the instruction view.@ To copy memory addresses or instructions into a command you areG entering at the command entry prompt, select text and choose #Copy fromD the Edit menu in the instruction window. Then, position your mouseG pointer at the command you have entered and choose Paste from the EditF menu on the main window. (You can also select instruction text to beE used with a push button command you click in the push button view of the main window.)D To set breakpoints from the instruction view, toggle the breakpointF button next to the instruction of interest. The breakpoint is set inD the source display, instruction display ( $if the instruction view is= open), and breakpoint view (if the breakpoint view is open).D Information on the breakpoint is continuously updated in the sourceH view, and in the instruction view and breakpoint view if they are open.E 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 theE location at which execution is paused, click on the Call Stack me%nu.D 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.F To display the register view, choose Views... from the Options menu,( then click on the button for Registers. &B By default, the register view automatically displays the registerC values associated with the routine in which execution is currently= paused. Any values that change as your program executes areE highlighted whenever the debugger regains control from your program.G To display the register values associated with any routine on the callD stack, choose its name from the Call Stack menu on the main window.* To change the value stored in a register:F 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.G 3. Click on the check mark (OK) in the dialog box. The dialog box isD removed and replaced by the new value, which indicates that the& register now contains that value.H 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%=i (nclude debugui cnt_task_pd_menu_hlp=include debugui on_owindow_hlpA Multithread programs have multiple threads of execution within a# process and include the following:B - Programs written in any language that use DECthreads or POSIX 1003.1b services.C - Programs that use language-specific threads services (servicesD provided directly by the language). Currently, Ada is the onlyH language with built-in threads services that the debugger supports.D Within the debu )gger, the term thread or task denotes such a flow ofF control regardless of the language or implementation. The debugger's. threads support applies to all such programs.A The debugger lets you display thread information and modify task= characteristics to control thread execution, priority, state transitions, and so on.C The following paragraphs summarize the multithread features of theG debugger's DECwindows Motif interface. For more information about theH debugger's threads suppor *t, see the manual provided with this debugger.& Displaying Information about Threads:B To display information about one or more threads of your program,D choose Views... from the Options menu on the main or optional viewA window. When the Views dialog box appears, click the button for4 Threads. The Threads View dialog box is displayed.? The thread view gives information about all currently existingC (nonterminated) tasks of your program. The information is updated8 whenever the de+bugger regains control from the program.$ The displayed information includes:B - The Thread ID. The arrow in the left column marks the activeD thread, that is, the task that runs when you click on the Go or Step push button.H - 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.E - The current substate of the thread. The substate helps i,ndicate, the possible cause of a thread's state.E - A debugger path name for the thread object or the address of theF thread object if the debugger cannot symbolize the thread object.! Changing Thread Characteristics:A To modify thread characteristics or the thread environment whileF debugging, choose one of the following items from the Threads menu on the optional view window: Action Function ------ --------D Abort Requests that the selected th-read be terminated at the @ next allowed opportunity. The exact effect depends A on the current event facility (language dependent). ? For Ada tasks, this is equivalent to executing an  abort statement.9 Activate Makes the selected thread the active thread.0 Hold Places the selected thread on hold.4 Nohold Releases the selected thread from hold.8 Make Makes the selected thread the visible task. Visible! A.ll -> Uses the submenu to:! Abort all threads Hold all threads" NoHold all threadsE To save these modifications for subsequent debugger sessions, chooseH Save Options from the Options menu on the main or optional view window.F 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_varE While debugging a routine in your program, you might want to set theF current scope to a calling routine (a routine down the stack from theG routine in which execution is currently paused). This enables you to:8 - Determine where the current routine call originatedD - Determine the value of a variable declared in a calling routineH - Determine the v 0alue of a variable during a particular invocation of) a routine that is called recursivelyD - Change the value of a variable in the context of a routine callG The Call Stack menu on the source view lists the names of the routinesB of your program that are currently active on the stack, up to the> maximum number of lines that can be displayed on your screen.D The numbers on the left side of the menu indicate the level of eachG routine on the stack relative to level 0, which denotes1 the routine in which execution is paused.F To set the current scope to a particular routine on the stack, chooseH its name from the Call Stack menu. This causes the following to occur:D - The Call Stack menu, when released, shows the name and relative8 level of the routine that is now the current scope.6 - The source view shows that routine's source code.E - The instruction view (if displayed) shows that routine's decoded instructions.? - The register view (if 2 displayed) shows the register values' associated with that routine call.E - If the scope is set to a calling routine (call-stack level other? than 0), the debugger clears the current-location pointer.B - The debugger sets the scope for symbol searches to the chosenB routine, so that you can examine variables, and so on, in the context of that scope.B When you set the scope to a calling routine, the current-locationD pointer (which is cleared) marks the source l 3ine to which executionC will return in that routine. Depending on the source language andA coding style used, this might be the line that contains the call# statement or some subsequent line.2 symbol_search6=title How the Debugger Searches for Names and Symbols=include debugui setscope=include debugui access_varD Symbol ambiguities can occur when a symbol (for example, a variableC name X) is defined in more than one routine or other program unit.G In most cases, the debugger r 4esolves symbol ambiguities automatically.C First, it uses the scope and visibility rules of the currently setD language. In addition, because the debugger permits you to specifyA symbols in arbitrary modules (to set breakpoints and so on), theA debugger uses the ordering of routine calls on the call stack to resolve symbol ambiguities.G In some cases, however, the debugger might respond as follows when you1 specify a symbol that is defined multiple times:H - It might issue a "sym 5bol not unique" message because it is not ableC to determine the particular declaration of the symbol that you intended.E - It might reference the symbol declaration that is visible in the2 current scope, which is not the one you want.F To resolve such problems, you must specify a scope where the debugger< should search for the particular declaration of the symbol:D - If the different declarations of the symbol are within routinesD that are currently active on the 6call stack, use the Call Stack: menu on the source window to reset the current scope.B - Otherwise, enter the appropriate command at the command-entryE prompt (EXAMINE or MONITOR, for example), specifying a path-nameG prefix with the symbol. For example, if the variable X is definedF in two modules named COUNTER and SWAP, the following command usesD the path name SWAP\X to specify the declaration of X that is in module SWAP: DBG> EXAMINE SWAP\X72 starting_debugger=title Starting the Debugger=include debugui run_new_hlp=include debugui rerun_same_hlp=include debugui on_mwindow_hlpC To start the debugger, enter the following command from DCL level: $ DEBUG/KEEPE This startup method enables you to rerun your program or run anotherF program from the same debugging session without exiting the debugger.B Additional options for starting the debugger are discussed in the@ manual provided with this debugger. With some of8 these startupG 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_hlpH You can customize the debugger's DECwindows Motif interface as follows:G 9- Define the startup configuration of the debugger windows and viewsE - Show or hide line numbers in the source view at debugger startup@ - Modify, add, or remove push buttons and associated debugger commandsF - Define the key sequence to display the dialog box for conditional and action breakpointsF - Define the key sequence to make text selection language-sensitive in the source viewE - Define the character font for text displayed in specific windows : and viewsE - Define or redefine the commands bound to individual keys on your computer's keypad.F You can control the first three of these customizations interactivelyD from the DECwindows Motif interface, as explained in the Additional@ Topics. In each of these three cases, you can save the currentG settings by choosing Save Options from the Options menu on the main or optional view window.H In addition, you can control all customizations by editing the debugger1 res ;ource file (DECW$USER_DEFAULTS:VMSDEBUG.DAT).2 custom_views==title Defining the Startup Configuration of Debugger Windows =include debugui custom_resource=include debugui customG To define the startup configuration of the debugger windows and views:F 1. While using the debugger, set up the desired configuration of the windows and views.F 2. Choose Save Options from the Options menu on the main or optionalF view window. This creates a new version of the debugger resour<ce file with the new settings.A When you later start the debugger, the new configuration appears automatically.B Note that adding views to the startup configuration increases the startup time accordingly.D You can also define the startup window configuration by editing theB current definition of the following resources in the VMSDEBUG.DAT resource file: DebugSource.width DebugSource.x DebugSource.height DebugSource.y DebugControl.width DebugControl.x DebugCo =ntrol.height DebugControl.y2 custom_lineno:=title Displaying or Hiding Source Line Numbers by Default =include debugui custom_resource=include debugui customD The source view displays source line numbers by default at debuggerA startup. To hide (or display) line numbers at debugger startup:E 1. While using the debugger, choose Show Line Numbers from the File@ menu on the main window. Line numbers are displayed when aE filled-in button appears next to that menu item, an>d vice versa.F 2. Choose Save Options from the Options menu on the main or optionalF view window. This creates a new version of the debugger resource file with the new settings.H When you later start the debugger, line numbers are either displayed or hidden accordingly.E You can also set the startup default for line numbers by setting theH following resource to either True or False in the VMSDEBUG.DAT resource file.$ DebugSource.StartupShowSourceLineno2 custom_butto?nA=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 customF The push buttons on the push-button view are associated with debugger commands. You can:G - 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 button9 NOTE: You cannot modify or remove the Stop push button.< The Additional Topics explain how to customize push buttons6 interactively through the DECwindows Motif interface.E To save these modifications for subsequent debugger sessions, chooseE Save Options from the Options menu on the main window or an optionalE view. This creates a new version of the debugger resource file with the new definitAions.2 custom_button_move8=title Resequencing a Push Button and Associated Command To resequence a push button:C 1. Choose Customize Buttons... from the Options menu on the mainC window or an optional view. The Customize dialog box appears.C 2. Click on the push button in the control panel of the Customize dialog box.H 3. Click on Right Arrow or Left Arrow. The push button is resequencedD one place to the right or left in the dialog box control panel.H 4. B Click on OK. The push button is resequenced one place to the right8 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_buttonH To change a push button's label or the debugger command associated with a push button:C 1. Choose Customize Buttons... from the Options menu on the mainC window or an optional view. The Customize dialog box app Cears.E 2. Click on the push button in the control panel of the dialog box.H 3. If changing the push button label, enter the new label in the LabelH field or choose a predefined icon from the Icon menu. (If changingF the push button label, verify that the Icon menu is set to None.)G 4. If changing the command associated with the push button, enter the& new command in the Command field.B If the command is to operate on a name or language expressionH selected inD a window, include %s in the command name. For example,E the following command displays the current value of the variable& whose name is currently selected: EXAMINE %sE If the command is to operate on a name that has a a percent sign; (%) as the first character, specify two percent signs.D 5. Click on Modify. The push button is modified in the dialog box control panel.F 6. Click on OK. The push button is modified in the push-button view on the Emain window.2 custom_button_add6=title Adding a New Push Button and Associated Command=include debugui command_help=include debugui custom_buttonG To add a new push button to the push-button view and assign a debugger command to that push button:C 1. Choose Customize Buttons... from the Options menu on the main/ window. The Customize dialog box appears.C 2. Enter the debugger command for that push button in the Command field.F 3. Enter a label for that puFsh button in the Label field or choose a( predefined icon from the Icon menu.H 4. Click on Add. The push button is added to the control panel within the dialog box.F 5. Click on OK. The push button is added to the push-button view in the main window.G 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 aC dereferenced value. If so, you enter the following command in the+ Command fieGld of the Customize dialog box:  monitor *%s2 custom_button_remove=title Removing a Push Button=include debugui custom_button To remove a push button:C 1. Choose Customize Buttons... from the Options menu on the main. window. The Customize dialog box appearsC 2. Click on the push button in the control panel of the Customize dialog box.H 3. Click on Remove. The push button is removed from the control panel within the dialog box.G 4. ClickH 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 customG The debugger is installed on your system with a debugger resource fileC DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT that defines the startup default< settings for the following debugger user-interface optionIs:' - Configuration of windows and views< - Whether to show or hide line numbers in the source view2 - Button names and associated debugger commandsF - Key sequence to display the dialog box for conditional and action breakpointsE - Key sequence for language-sensitive text selection in the source view6 - Character fonts for text in the windows and viewsB - Key bindings for commands associated with the computer keypadG - Colors for elements of the Jsource and instruction views and Editor - Command echo - Title Bar label formatH A listing of the system default debugger resource file with explanatoryA comments is contained in the manual provided with this debugger.C 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 view7 - Push button names and associated debugger commandsD You canK redefine the rest of the customizable parameters by editing# your local debugger resource file.D See Additional Topics for information about changing and saving theG 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 seqLuence for displaying the dialog box forG conditional and action breakpoints is Ctrl/MB1. To define another keyG sequence, edit the current definition of the following resource in the VMSDEBUG.DAT resource file:+ DebugSource.ModifyBreakpointToggleSequence2 custom_key_select3=title Defining the Key Sequence for Text Selection=include debugui select =include debugui custom_resource=include debugui customF By default, the key sequence for language-sensitive text selection inG tMhe source view is Ctrl/MB1. To define another key sequence, edit theA current definition of the following resource in the VMSDEBUG.DAT resource file:( DebugSource.IdentifierSelectionSequenceH 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 customB To define another font for the text displNayed 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.Font2 custom_key_binding.=title Defining the Key Bindings on the Keypad =include debugui custom_resource=include debugui customC The following commands have been mapped to individual keys on your computer's keypad:@ Command Keypad Labe Ol Key Designation@ -------- ------------ ---------------= Step/Line KP0 0xFFB0= Examine KP1 0xFFB1= Go KPcomma 0xFFACI Step/Into GOLD-KP0 0xFF91,0xFFB0J Step/Over BLUE-KP0 0xFF94,0xFFB0 I Examine^ GOLD-KP1 0xFF91,0xFFB1= Show Calls KP5 0xFFB5I Show Calls 3 GOLD-KP5 0xFF91,0xFFB5= Activate ENTER 0xFF8DG To bind a different command to a key that is already associated with aG command, edit the current definition of the following resources in the VMSDEBUG.DAT resource file:1 DebugSource.*DXmCSText.translations:#override\n\3 0xFFB0: EnterCmdOnCmdLine("step\line") \n\1 Q0xFFB1: EnterCmdOnCmdLine("examine") \n\, 0xFFAC: EnterCmdOnCmdLine("go") \n\? 0xFF91,0xFFB0: EnterCmdOnCmdLine("step\into") \n\? 0xFF94,0xFFB0: EnterCmdOnCmdLine("step\over") \n\> 0xFF91,0xFFB1: EnterCmdOnCmdLine("examine^") \n\4 0xFFB5: EnterCmdOnCmdLine("show calls") \n\B 0xFF91,0xFFB5: EnterCmdOnCmdLine("show calls 3") \n\ 0xFF8D: activate()\n\C To bind a command to a key that is not currently associated R with aH 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_hlpF Information about using DECwindows Motif, such as how to use windows,G dialog boxes, and scroll bars, is available from Session Manager help. To get Session Manager help:F 1. Move the mouse pointer to the Session Manager icon (the icon that1 contains a small key in it) in thSe Icon Box.D 2. Press mouse button 1 (MB1) twice to display the Session Manager window.H 3. Move the mouse pointer to the Help menu; press and hold MB1 to pull down this menu.G 4. Move the mouse pointer to the On Basics menu item and release MB1.F The Session Manager displays a Help window, which includes a list7 of Additional Topics about using DECwindows Motif. 2 on_context#=Title On Context Item in Help Menu=include debugui on_help_hlp!=include debuguiT help_pd_menu_hlp=include debugui on_mwindow_hlp=include debugui on_owindow_hlp=include debugui on_ewindow_hlp=include debugui on_iwindow_hlpC Context-sensitive help is information about an area or object in a window or a dialog box.# To display context-sensitive help:D 1. Choose On Context from the Help menu in a debugger window. The2 pointer shape changes to a question mark (?).F 2. Place the question mark on an object or area in a debugger window or dialog bUox.F 3. Click on MB1. Information about that area or object is displayed? in a Help window. Additional Topics provide task-oriented# discussions, where applicable.G 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_Vewindow_hlp=include debugui on_iwindow_hlpH 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_hlpH Choose On Help in the Help menu for instructions on how to use the Whelp 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 dXebugui 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_hlpC Choose On Commands in the Help menu for information about debugger commands.D The debugger's DECwindows Motif interface is layered on the commandF interface. You can enter debugger commands at the DBG> command-entry prompt in the command view.2 context_sensitive_help(=title Displaying Context-Sensitive HeYlp=include debugui on_help_hlpC Context-sensitive help is information about an area or object in a window or a dialog box.# To display context-sensitive help:D 1. Choose On Context from the Help menu in a debugger window. The2 pointer shape changes to a question mark (?).F 2. Place the question mark on an object or area in a debugger window or dialog box.G 3. Click on MB1. Help for that area or object is displayed in a HelpH window. Additional Topics provide Ztask-oriented discussions, where applicable.G To display context-sensitive help for a dialog box, you can also click& on the Help button in the dialog box.2 overview_help8=title Displaying the On Window Help Topic and Subtopics=include debugui on_mwindow_hlp=include debugui on_help_hlp!=include debugui help_pd_menu_hlpD The On Window help topic (Using the Main Window, Using the OptionalH View Window, Using the Editor Window, Using the Instruction Window) andE their subtopics[ provide task-oriented information about the debugger and debugging.A To display the On Window topics, use either of these techniques:> - Choose On Window from the Help menu in a debugger window.H - Choose Go To Overview from the View menu of a debugger help window.H 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 interfa\ces=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:5 - At the command-entry prompt in the command view.H - In certain debugger dialog boxes (for example, when assigning a new7 command to a push button on the push-button view).9 To display help on debugg]er commands and various topics:@ - Choose On Commands from the Help menu of a debugger window.9 - Choose the command name or other topic (for example,: Language_Support) from the list of Additional Topics. 2 msg_help6=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_hlpD 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.8 2. Choose Messages from the list of Additional Topics.F 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__hlpG The Memory Map, located at the upper left of the heap analyzer screen,@ displays a graphical representation of memory use in real time.E Each memory allocation appears as a colored strip, or 'segment'. ByF searching for segments that seem too large, too numerous, or in otherH ways anomalous, you can identify areas in your application where one of. the following memory events may be occurring: - Memory leaks - Fragmentation - Repetitive allocations - Insuffi`cient allocation - Inefficient memory useA For information on Memory Map context-sensitive pop-up menus and2 pull-down menus, see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 Typae Histogram=include debugui ha_type_csD The Type Histogram, located in the upper right of the heap analyzerH screen, allows you to see statistical summaries on segments of the same segment type. Use the Type Histogram to:D - Check the percentage of total segments represented by a segmentH type. The left histogram shows this percentage graphically. ClickA on an individual segment type to see a numerical percentage.C - Check the percentage of the total bytes allocat bed to a segmentB type. The right histogram shows this percentage graphically.G Click on an individual segment type to see a numerical percentage.G The total number of segments and the total number of bytes (recognizedA by the heap analyzer) appear at the top of the histogram window.F For information on Type Histogram context-sensitive pop-up menus, see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On cContext' menu item in the heap analyzer Help menu,% then click the location of interest.E 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_donotuseE Most of the work you do in the heap analyzer is accomplished throughF context-sensitive pop-up menus. The menud items available on the Type Histogram are as follows: Action Function ------ --------> Display Type Displays the segment's type definition2 in the Information Window.> Go to Type Moves the cursor to the segment's type7 in the Views-and-Types Display.7 Do Not Use Type Adds the segment's type to the - Do-not-use Type List.C For information on otheer heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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_segdefD The Message Window, located beneath the Memory Map, displays output from the heap analyzer.H Use the Message Window on the heap analyzer winfdow to do the following:@ - Read informational and error messages generated by the heap analyzer.E - Read one-line informational descriptions on individual segments.D (Click on MB1 while your mouse pointer rests on the segments of interest.)F For information on Message Window context-sensitive pop-up menus, see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap agnalyzer Help menu,% then click the location of interest.E 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_donotusehE Most of the work you do in the heap analyzer is accomplished throughH 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, the9 sequence of routine calls on the 8 callstack, for the segment under) your mouse arrow.: Dis iplay Segment Displays the segment definition of; the segment under your mouse arrow 2 in the Information Window.< Display Contents Displays the contents of the segment/ under your mouse arrow.= Display Address Displays the address under your mouse8 arrow in the Information Window.> Display Type Displays the segment's type definition2 in the Inforjmation Window.> Go to Type Moves the cursor to the segment's type7 in the Views-and-Types Display.7 Do Not Use Type Adds the segment's type to the - Do-not-use Type List.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menku% item in the heap analyzer Help menu.2 ha_interpret_trace%=Title Requesting a Segment TracebackE The heap analyzer displays traceback information when you choose theD Traceback of Allocation context-sensitive menu item from the Memory Map.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Wlindow' 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_typeD The heap analyzer moves you to the Views-and-Types Display when youF choose the Go to Type context-sensitive menu item from the Memory Map or the Type Histogram.G Your mouse arrow rests on the segment type associated with the segment2m you selected in the Memory Map or Type Histogram.D 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 typeC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on usinng the heap analyzer, see the 'On Window' menu% item in the heap analyzer Help menu.2 ha_color_type=Title Changing the Type ColorG The heap analyzer allows you to change the color assigned to a segmentC type in the Memory Map by clicking MB3 on the color spectrum for a segment type or types.C This feature can be useful if the colors of adjacent types are too* similar to distinguish each type clearly.C For information on other heap analyzer screen locations and pop-upH menuso, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 OptionH The heap analyzer allows you to hide (and then, show again) the displayC of a segment type in the Memory Map by doing one of the following:E - Toggling the Show toggle button and clicking the Apply button in! p the Views-and-Types Display.G - Selecting the Show or Hide menu item and clicking the Apply button$ in the Views-and-Types Display.A This feature can be useful when you need to isolate a segment or8 segments in the Memory Map in order to see them better.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzeqr, see the 'On Window' menu% item in the heap analyzer Help menu.2 ha_expand_type-=Title Choosing the Expand or Collapse OptionF The heap analyzer allows you to expand (or collapse) the display of aH segment type contained inside the display of other segment types in the* Memory Map by doing one of the following:G - Toggling the Expand toggle button and clicking the Apply button in! the Views-and-Types Display.F - Selecting the Expand or Collapse menu item and clicking trhe Apply+ button in the Views-and-Types Display.A This feature can be useful when you need a more or less detailed& picture of an area in the Memory Map.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 sSave or Remove OptionB 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:E - Toggling the Save toggle button and clicking the Apply button in! the Views-and-Types Display.B - Selecting the Save or Remove menu item and clicking the Apply+ button in the Views-and-Types display.B This feature can be useful when you need to improve heap analyzerF performance by discarding information on unimport tant segments. It isG also useful when you need to discard all information before a point inA time, so you can perform a series of actions and see the display resulting from them.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menu% item in the heap analyzer Help menu.2 ha_interpret_duonotuse)=Title Adding to the Do-not-use Type ListF The heap analyzer adds a new segment type name to the Do-not-use Type4 List when you perform one of the following actions:D - Choose the Do Not Use Type context-sensitive menu item from the& Memory Map or the Type Histogram.G The segment type added is the one associated with the segment your mouse arrow is pointing to.H - Choose the Add to Do-not-use Type List pull-down menu item from the$ Options menu on the Mvemory Map.H The segment type added is the one you type into the dialog box that appears for your input.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 analyzwer displays segment type definitions when:< - You click MB1 on a segment displayed in the Memory Map.H - You choose the Display Segment context-sensitive menu item from the Memory Map.- A segment definition has the following form: 9 0004ECA5 15: 00040000_0001CA00=0005CA00 LIBRTL (Image) which includes:G - 0004ECA5: The address underneath your cursor when you pressed MB1? (This information does not appear when you choose from the context-sxensitive menu)6 - 15: The segment number in the Memory Map display2 - 00040000: The initial address of the segment2 - 0001CA00: The length in bytes of the segment/ - 005CA00: The final address of the segment/ - LIBRTL: The segment name, or segment typeG - Image: The segment classification (image, block, region, or zone)C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menyu,% then click the location of interest.E 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 DefinitionH 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:2 LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments  using 00002160 bytes which includes:z4 - LIBRTL\LI$VM\LIB$GET_VM: The segment type nameF - (Block): The type classification (image, block, region, or zone)% - 39 segments: Number of segments% - 00002160 bytes: Number of bytesC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menu% item in the heap analyzer H{elp menu.2 ha_interpret_adddef)=Title Interpreting an Address DefinitionG The heap analyzer displays segment address definitions when you chooseF the Display Address item in the context-sensitive menu for the Memory Map.. An address definition has the following form:2 001C710B is read and write accessible by the user which includes:* - 001C710B: The address of the segment7 - read and write accessible: The access to the userC For information on other heap ana|lyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 DefinitionH The heap analyzer displays segment contents definitions when you chooseG the Display Contents item in the context-sensitive menu for the Memory Map.. A contents de}finition has the following form:- contents of: 38: 001C7000+000000C0=001C70C0 $ LIBTRL\LIB$VM\LIB$GET_VM (Block)3 00000000 00000000 00000000 001C71083 00345000 00000000 00000000 ~#@ 001C71183 00000B10 00000000 06503000 <> 001C71283 00C45000 00113000 00000000 * +*, 001C71383 00000000 000C4000 0000E000 .. ? 001C7148 which includes:6 - 15: The segment number in the Memory Map display2 - 001C7000: The initial ad~dress of the segment2 - 000000C0: The length in bytes of the segment0 - 001C70C0: The final address of the segmentA - LIBRTL\LIB$VM\LIB$GET_VM: The segment name, or segment typeG - Block: The segment classification (image, block, region, or zone); - An ASCII representation of the contents of the segmentC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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_csG The Information Window, located in the lower left of the heap analyzerH screen, displays output from context-sensitive menu items in the Memory5 Map. These items request the following information:( - Traceback entries for an allocation - Segment definitions - Contents definitions - Address definitions - Segment type definitionsF For information on Information Window context-sensitive pop-up menus,! see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menu% item in the heap analyzer Help menu. 2 ha_info_cs1=Title Information Window Context-Sensitive MenusE 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 withC the traceback entry under your mouse arrow.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 WindowB The Source Window, located between the Information Window and theA Do-not-use Type List, displays the source code associated with a traceback entry.5 To display source code, perform the following steps:E 1. Choose the Traceback of Allocation item in the context-sensitive menu on the Memory Map.H 2. When traceback information appears in the Information Window, click& on an individual traceback entry.G The routine call associated with the traceback is highlighted when your source code appears.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For i nformation 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_csD The Do-not-use Type List, located between the Source Window and theG Views-and-Types Display, lists the routines the heap analyzer does not> use as "segment types," the names that characterize segments.D For example, the display showing in the Memory Map may include many? segments labeled with the nam es of low-level memory managementG routines. If you include these names in the Do-not-use Type List, theF heap analyzer will search further for names to characterize segments,0 and each segment's purpose will become clearer.H For information on Do-not-use Type List context-sensitive pop-up menus,! see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menu% item in the heap analyzer Help menu.2 ha_hidelist_cs3=Title Do-not-use Type List Context-Sensitive MenusE 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.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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_csD The Views-and-Types Display, located in the lower right of the heapG analyzer screen, displays the segment types known to the heap analyzer4 and allows you to alter the display of these types.C 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)C Then, move to the right side of the display to choose your display change:" - Change colors used in display+ - Suppress (or restore) types in display4 - Expand (or collapse) detail of types in display? - Remove (or save) information on types displayed in session C For information on View-and-Types Display context-sensitive pop-up( menus, see the additional topics below.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E For information on using the heap analyzer, see the 'On Window' menu% item in the heap analyzer Help menu.2 ha_typelist_cs6=Title Views-and-Types Display Context-Sensitive Menus%=include debugui ha_interpret_typedef&=include debugui ha_interpret_gototype&=include debugui ha_interpret_donotuseE Most of the work you do in the heap analyzer is accomplished throughH context-sensitive pop-up menus. The menu items available from the left4 side of the Views-and-Types Display are as follows: Action Function ------ --------> Display Type Displays the segment's type definition2 in the Information Window.> Go to Type Moves the cursor to the segment's type7 in the Views-and-Types Display.7 Do Not Use Type Adds the segment's type to the - Do-not-use Type List.D The menu items available from the right side of the Views-and-Types Display are as follows: Action Function ------ --------E Color Spectrum Changes the color assigned to a segment type4 or types in the Memory Map. --------: Show Restores full Memory Map display.G Hide Suppresses the display of one or more segment  types.4 Reset Cancels the options chosen. ---------H Expand Includes the display of segment types occurringF within other segment types in the Memory Map.J Collapse Suppresses the display of segment types occurringF within other segment types in the Memory Map.4 Reset Cancels the options chosen. ---------A Save Saves all subsequent information about a/  segment type or types.C Remove Deletes absolutely all information about a/ segment type or types.4 Reset Cancels the options chosen.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 BoxC 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 BoxA 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 PanelE The push buttons on the control panel allow you to control the speedE your application executes and the Memory Map displays. Use the  push2 buttons on the control panel to do the following:  Button Function -------- ---------B Start/Step Initially, the Start push button starts your E application. Once your application is running, I this push button becomes the Step push button, whichC you can use when your application is paused to@ single-step through the Memory Map display.: Pause S tops the updating of the Memory Map.: Slow Slows the updating of the Memory Map.@ Sync Off: A small histogram shows how far behindA your application's processing the Memory MapC displays events (a slight discrepancy improves0 heap analyzer performance). G On: Directs the heap analyzer to update the MemoryB Map at exactly the same time your application*  executes the event. C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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.C For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 ------ --------? T ext Visible (Default.) Labels each segment in the Memory= Map with a segment name, provided that theA segment is large enough to carry a name label.A 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 MemoryA Region Map display, compresses the displ ay so you canE see as many segments as possible without scrolling= to their location in the original display.A Display All Restores the complete Memory Map display afterC Segments you have requested a limited or partial display.; Clear Clears text from the Information Window. Information WindowC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 MenuE Use the Zoom menu on the heap analyzer window to specify a closer orC more distant view of the Memory Map by choosing from the following options:! Extraordinarily Close Extremely Close Very Close Close Medium (Default) Far Very FarC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 inA Do-not-use your Do-not-use Type List between heap analyzer Type List sessions.? Restore Deletes additions to the Do-not-use Type List7 Do-not-use since the last heap analyzer session. Type ListC For information on other heap analyzer screen locations and pop-upH menus, click the 'On Context' menu item in the heap analyzer Help menu,% then click the location of interest.E 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 ------ --------E On Context Provides context-sensitive help for the heap analyzer.K On Window Provides task-oriented information on heap analyzer windows.9 On Version Provides copyright and version information$ on the heap analyzer. 4 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_hlpC Context-sensitive help is information about an area or object in a window or a dialog box.# To display context-sensitive help:D 1. Choose On Context from the Help menu in a debugger window. The2 pointer shape changes to a question mark (?).F 2. Place the question mark on an object or area in a debugger window or dialog box.F 3. Click on MB1. Information about that area or object is displayed? in a Help window. Additional Topics provide task-oriented# discussions, where applicable.G 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_hlpG Choose On Window in the Help menu for an overview of the heap analyzerA 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_hlpH 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 aG graphical representation of memory use in real time. By studying thisH representation, you can identify areas in your application where memoryF usage and performance can be improved. For example, you might noticeG allocations that are made too often, memory blocks that are too large,, evidence of fragmentation, or memory leaks.H After you locate an area of interest, you can request an enlarged, moreH detailed, or altered view. You can also request additional information< on the size, contents, or address of the allocations shown.D After you narrow your interest to an individual allocation, you canE request traceback information. The analyzer allows you to correlate? the traceback entry for an allocation with source code in yourH application program. By scrolling through the source-code display, youA can then identify problematic code and decide how to correct it.B The additional topics below, read in sequence, describe the steps% involved in using the heap analyzer.2 ha_window_start'=Tit le Starting a Heap Analyzer Session"=include debugui ha_window_windowsF You can invoke the heap analyzer during a debugging session in one of the following ways:D - In the debugger main window, choose the Run Image or Rerun SameE items from the File menu. When a dialog box appears, select theC program you wish to execute and click the heap analyzer toggle button.F - At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER$ or RERUN/HEAP_ANALYZER command.H - On VAX and Alpha systems, at the DCL prompt ($) in a DECterm windowH outside the debugger, enter the following commands and then execute your program:9 $ DEFINE/USER LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTEDF - To display the Heap Analyzer graphical display on I64 systems, at) the DCL prompt ($) enter the command START HEAP_ANALYZERE You can also invoke the heap analyzer outside a debugging session byB entering the DEFINE/USER command detailed above, and then the DCL command RUN/NODEBUG.C After you successfully invoke the heap analyzer, the heap analyzer startup screen appears.2 ha_window_windows/=Title Viewing the Heap Analyzer Startup ScreenH The heap analyzer contains a main window, six subsidiary windows, and a control panel.H The Memory Map, the most important window, displays a representation ofC your application's dynamic memory use. At startup, the Memory MapF shows the images that comprise your application. As yo ur applicationC executes, you can see the relative location and size of individualB memory blocks, images, program regions, memory zones, and dynamic? strings as they are allocated and deallocated in memory space.G The Message Window displays information on your heap analyzer session.C At startup, the Message Window contains the message 'Heap AnalyzerH initialization complete. Press Start button to begin program.' As yourF application executes, informational and error messages appear in this window.A The Push Button Control Panel contains buttons that allow you toG control the speed of the Memory Map display. At startup, you click on? the Start button to begin executing your application. As yourE application executes, you can click on other buttons in the panel to9 pause, slow, or otherwise affect the continuous display.H The Information Window displays information on Memory Map segments. AsB your application executes, you can pause execution at any time to request specific information.G The Source Window displays the application source code associated with a segment in the Memory Map.H The Do-not-use Type List allows you to adjust the Memory Map display by/ redetermining a segment's type, or group name.H The Views-and-Types Display allows you to adjust the Memory Map display. by selectively viewing certain segment types.C The Type Histogram displays summary and statistical information on segment types.G As you use the heap analyze r, you may need to increase or decrease theC size of the window in which you are working. To do this, pull theD window pane sashes between windows or resize the screen as a whole.2 ha_window_sourcedir!=Title Setting a Source DirectoryF If you are invoking the heap analyzer from a directory other than theC one that stores your application source code, you can set a sourceG directory for the heap analyzer as soon as the startup screen appears. To set a source directory:E 1. Choose the Set Source... menu item from the Options menu on the heap analyzer screen.' The Set Source dialog box appears.G 2. Enter the directory specification for your source directory as you7 would for the OpenVMS Debugger SET SOURCE command.F For more information on this command, see the debugger SET SOURCE command in online help. 3. Click on OK.3 The heap analyzer can now access your application.2 ha_window_run=Title Running Your ApplicationH If you invoked the heap analyzer from within a debugging session, start4 your application by performing the following steps:@ 1. Click on the Start button in the Push Button Control Panel.G The Message Window displays an "application starting" message, andH the Start button label changes to Step. The OpenVMS Debbugger main window pops forward.H 2. Click on the Go button in the OpenVMS Debugger's control panel, and) iconize the OpenVMS Debugger window.H Mem ory events associated with your application begin showing in the Memory Map.E (If you invoked the heap analyzer outside a debugging session, start3 your application by performing only step 1 above.)F After your application is running, the Memory Map (and other parts ofC the heap analyzer display) are continuously updated to reflect the state of your application.F Unless you intervene (by clicking one of the push buttons in the heapE analyzer control panel), this updating cont inues until an occurrenceC 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 DisplayF If you decide to examine events in the Memory Map as your applicationD is executing, you can use the heap analyzer's push buttons to slow,6 pause, and otherwise affect the speed of the display.H The Slow and Pause push buttons all ow you to slow or pause the display.F The Step push button allows you to single-step through memory events.E The Sync histogram to the right of the Sync button indicates how farG behind your application the heap analyzer is running. For performanceF reasons, the heap analyzer displays memory events a few seconds after& their occurrence in your application.E 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_finalB The following sections describe how to use the heap analyzer whenG memory problems are clearly visible in the default Memory Map display.F Visible problems include allocations that are larger than you expect,H that repeat numerous times, that increment at each allocation, and that% could occur in a more efficient way.D 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).F 3. Request additional information on individual segments (optional).: 4. Request traceback information on individual segments.; 5. Correlate traceba ck entries with source code routines.2 ha_window_def_mmdisp=Title Memory Map DisplayG Depending on the size of your application, you may wish to examine theE Memory Map display as your application is running (by using the push> buttons to slow, pause, or step through events) or after yourB application completes running (by using the Memory Map's vertical0 scroll bar to scroll back through the display).B You can identify segments whose size or location are not what youB expect by r emembering that a segment's location in the Memory MapC corresponds to its location in dynamic memory. Lower addresses inC dynamic memory are represented in the upper left of the Memory MapG display. Addresses increase to the right and wrap at each line of the display.2 ha_window_def_optmmdisp%=Title Options for Memory Map DisplayF As you examine the Memory Map, you may wish to select display optionsF that allow you to see more clearly those parts of the display you are most inte rested in.D The Display Menu allows you to control whether you see segment typeG names within the Memory Map display, whether the display automaticallyG scrolls to show the most recent activity, and whether you can compress the display.E The Zoom Menu allows you to control the degree of magnification withG which you see segments in the Memory Map. Choosing the Far menu item,D 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 InformationG As you examine the Memory Map display, you may find that you need moreH 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:F cursor-address n:init-address + length = end-address name ( view )E cursor-address The address beneath your cursor when you click MB3.C n The number of your segment within the sequence of! total segments.6 init-address The initial address of your segment.8 length The length (in bytes) of your segment.3 end-address The last address of your segment. 8 name The segment type name of your segment.+ view The view of your segment:0 block, image, region, or zone.F (See the 'Altering the Views and Types Display' help7 topic for more information on views.)A For example, the following segment definition describes the 15thG segment in your Memory Map display, which is a segment of type LIBRTL:C 0004ECA5 15: 00040000+0001CA00=0005CA00 LIBRTL (Image)B A contents definition consists of a partial segment definition (a: segment definition without a cursor-address) and an ASCIIC representation of the contents of segment addresses. For example:, contents of: 38: 001C7000+000000C0=001C70C0$ LIBTRL\LIB$VM\LIB$GET_VM (Block)! [ASCII representation]D An address definition takes the form of a statement describing user* access to a stated address. For example: 2 001C710B is read and write accessible by the userF A type definition takes the form of a statement summarizing the totalH number of segments and total number of bytes devoted to a segment type. For example:1 LIBRTL\LIB$VM\LIB$GET_VM (Block) has 39 segments using 00002160 bytes2 ha_window_def_trace'=Title Requesting Traceback InformationA After you identify an individual segment of interest, choose theA Traceback of Allocation menu item in the Memory Map pop-up menu.C Traceback information can help you understand why your segment wasE created. Viewing traceback is also a preliminary step to displaying application code.B Traceback information consists of a partial segment definition (aF segment definition without a cursor address) and the list of elementsF on the callstack at the moment your segment was created. The element naming convention is: 3 image name\module name\routine name\line number For example:= traceback: 8:000BA800+00065C00=00120400 DECC$SHR (Image) 00066EDE DBG$HA_KERNELH 00005864 CRL$MAIN_DB\CRL_LIBRARY\crl__initialize_libraries\%LINE 55922 ha_window_def_final9=Title Correlating Traceback Information with Source CodeE When the traceback disp lay appears, you identify the traceback entryF most closely associated with the segment you are investigating. MostE often, you can do this by comparing segment type names and traceback routine names.C When you double click MB1 on this traceback entry, the source codeF associated with the entry appears (highlighted) in the Source Window.> You can then scroll through the source code display, identify0 problematic code, and decide how to correct it.B If you cannot identify any problems  in the displayed source code,E return to the Information Window and double click MB1 on the routine1 immediately above or below your previous choice.> If you double click MB1 on a traceback entry, and 'Source NotH Available' messages appear in the Source Window, you may have forgottenA 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 Adj usting Type Determination and Display#=include debugui ha_window_opt_info#=include debugui ha_window_opt_type#=include debugui ha_window_opt_dispE The following sections describe the steps to perform when the memoryE events represented in the default Memory Map are not clear; that is,1 you cannot tell whether a problem exists or not.F This circumstance can occur when the segment type names chosen by theG heap analyzer are too broad to be useful for your application, or whenD the M emory Map is so full that you cannot easily see the segment of interest.G In such cases, you can choose one or both of the following strategies:H - Review the type summary in the Type Histogram (to see a summary, inE total segments and total bytes, of each segment type's use) BuffH - Adjust the type determination in the Memory Map (directing the heapC analyzer to select type names that are more meaningful to you)B - Adjust the type display in the Memory Map (directing the heap: analyzer to suppress some types and highlight others)F If, by adjusting the type determination or display, you then identifyH visible problems, you can resolve them in the same way you would if you= were working with the default Memory Map display. (For moreE information, see the 'Working with the Default Display' help topic.)2 ha_window_opt_info&=Title Options for Further InformationG As you examine the Memory Map, you may wish to see a summary of MemoryF Map activity in the Type Histogram. The Type Histogram, which is twoH histograms back-to-back, shows the percentage of total segments and theE percentage of total bytes devoted to each segment type in the Memory Map.E To see these graphical representations in numeric form, click MB1 on the segment type of interest.H 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 DeterminationC As you examine the Memo ry Map, you may find that some segment type? names are not meaningful to you. By adding these names to theF Do-not-use Type List, you direct the heap analyzer to rename segments6 and, if necessary, regenerate the Memory Map display.G By default, the analyzer assigns segment type names at the creation ofE a segment. In some cases, the analyzer assigns an element name (forF example, LIBRTL). In most cases, however, the analyzer searches downH the callstack to find a routine name that then serves as a segment type name.E The analyzer chooses the first routine name on the callstack that isE not prohibited by the Do-not-use Type List. If the first routine isD prohibited, the analyzer examines the next routine down, and so on.C This default behavior can cause the following Memory Map problems:@ - The same few type names appear repeatedly in the Memory Map display.G This occurs when the first routines on the callstack are low-level> memory management  or utility routines. Since most of theF allocation events in your application use these routines, you seeD unrelated allocations grouped together with the same type name.A To prevent this problem, add any application-specific memoryD management or utility routine names to the Do-not-use Type List% before you run your application.G - The type names assigned provide a higher level of abstraction than you require.C This can occur when the first routine o n the callstack is lessF application-bound than your level of examination. If you need toA see type names that reflect application functions, it is not? helpful to see type names derived from intermediary memory! management routines instead.H This can also occur when the first routine on the callstack focusesG on a part of your application you are not interested in examining.H If you need to see type names that reflect subsystem functions (forG example, initialize_death_star), it is not helpful to see only one8 type name for all subsystem functions (for example, initialize_star).> To correct this problem, add the current type name to theC Do-not-use Type List until the Memory Map display reflects the% level of abstraction you desire.G To add a segment type name to the Do-not-use Type List, you can selectC the Add to Do-not-use Type List pull-down menu item in the OptionsD menu, or you can choose the Do Not Use Type pop-up menu item in theE Memory Map, Type Histogram, or Views-and-Types Display. To delete aE segment type from this list, choose the Use Type pop-up menu item in the Do-not-use Type List.H To save the contents of a Do-not-use Type List, you can choose the SaveD Do-not-use Type List menu item in the Options menu. This saves theE list for future heap analyzer sessions. The Restore Do-not-use TypeH List menu item removes recent additions to the list since the last time the list wa s saved.2 ha_window_opt_disp+=Title Altering the Views-and-Types Display$=include debugui ha_window_opt_scope&=include debugui ha_window_opt_dispoptH As you examine the Memory Map, you may find that you need to adjust theB type display to focus more clearly on your area of interest. TheE Views-and-Types Display allows you to specify changes to multiple or& individual segments of the same type.C The Views-and-Types Display is actually two windows separated by aC window sash. You can  expand the left window to show all the knownB 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 ChangeH The heap analyzer receives information about segments from four OpenVMSE memory managers that perform allocations and deallocations in memoryF space. Each memory manager has a slightly different view, or overall picture, of dynamic memory.G Each memory manager recognizes a different set of segment types. ThisB means that, within the heap analyzer, where views from the memoryD managers are layered on each other, a single memory location can be+ associated with one or more segment types.D The left window of the Views-and-Types Display contains a hierarchy that reflects this integration:& - Views (integrates all four views)3 - Blocks (block view from LIB$VM memory manager)6 - Images (image view from SYS$IMAGE memory manager)D - Regions (system services view from SYS$SERVICES memory manager)6 - Zones (zone view from LIB$VM_ZONE memory manager)G To see the individual segment types recognized by each memory manager,E expand the default display by double clicking MB1 on Blocks, Images,F 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:8 Click MB1 on the Blocks, Images, or Zones keywords.( - To affect individual segment types:F 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 OptionB The right window of the Views-and-Types Display shows the display options available, as follows: - ColorE To change the color of all segment types, all segment types in aC particular view, or individual segment types, click MB3 on the@ color button in the display. When the vertical color stripE appears, click MB1 on the color of your choice. Then, click the' Apply button to apply your change. - Show (or hide) statusC To suppress (or restore) the display of all segment types, allC segment types in particular view, or individual segment types,H toggle the Show  button to the Hide (or Show) setting and click MB1.F (Alternatively, you can choose the appropriate menu item from theB Show pop-up menu.) Then, click the Apply button to apply your change.D Use this option to clear the Memory Map of segments you are notG examining. You can also use this option to find all segments of a5 particular type (by hiding every other segment). - Expand (or collapse) statusC To collapse (or expand) the display of segment types containedF within all segment types, all segment types in a particular view,A or individual segment types, toggle the Expand button to theE Collapse (or Expand) setting and click MB1. (Alternatively, youG can choose the appropriate menu item from the Expand pop-up menu.)7 Then, click the Apply button to apply your change.G Use this option to clear the Memory Map of nested segments you areA not examining. Depending on your application, heap analyzer" p erformance may also improve. - Save (or remove) statusG To destroy (or save) information on all segment types, all segmentH types in a particular view, or individual segment types, toggle the? Save button to the Remove (or Save) setting and click MB1.F (Alternatively, you can choose the appropriate menu item from theB Save pop-up menu.) Then, click the Apply button to apply your change.H Use this option to clear the Memory Map completely, and then resume Memory Map display.E To cancel a choice, click the Reset button, or choose the Reset menu2 item from the Show, Expand, or Save pop-up menus.2 ha_window_exit =Title Exiting the Heap AnalyzerF 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_hlp7 The heap analyzer is a feature of the OpenVMS Debugger2 Software Version: OpenVMS Debugger Version 8.2# Copyright 2015, VMS Software, Inc. All rights reserved.E 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_hlpH Two kinds of online help about the debugger and debugging are available during a debugging session:B Context-sen sitive help, which is information about an area or% object in a window or dialog boxE - Task-oriented help, which consists of an introductory help topicF named 'Using the Heap Analyzer' and several subtopics on specific debugging tasksA 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_hlpC Context -sensitive help is information about an area or object in a window or a dialog box.# To display context-sensitive help:F 1. Choose On Context from the Help menu in the heap analyzer screen.6 The pointer shape changes to a question mark (?).D 2. Place the question mark on an object or area in a heap analyzer window or dialog box.G 3. Click on MB1. Help for that area or object is displayed in a HelpH window. Additional Topics provide task-oriented discussions, where applicable.G To display context-sensitive help for a dialog box, you can also click& on the Help button in the dialog box.ww