DBG$UIHELP.HLB  —  DEBUGUI
  This is the only level 1 module in this help library.

1  –  src_workarea_hlp

  Use the source view on the main window to do the following:

  Location             Function
  -------              ---------

  Source display       Display program source code, and, optionally,
                       compiler-generated line numbers to the left
                       of the code.

  Breakpoint           Set breakpoints on specific source lines or
     toggles           routines in your program, check breakpoint
                       status, and activate or deactivate breakpoints.

  Current line         Identify the line of source code that will be
     indicator         executed when program execution resumes.

  Call stack           Identify the sequence of routine calls on
                       the stack.

2  –  popup_src

  To use pop-up menus in the source view, select text or position your
  mouse pointer in the source view, and press MB3.  The debugger inserts
  the selected text or line number in the menu items of the pop-up menu.

  If you press MB3 while your mouse pointer rests on a source line in the
  source view, a pop-up menu with the following items appears:

  Examine [selection]    Evaluates the selected expression and prints
                         its value in the command view.

  Monitor [selection]    Inserts the selected expression in the monitor
                         list of the monitor view.

  Deposit [selection]    Provides the Assign/Deposit dialog box.

  Break on Routine       Sets a breakpoint on a selected routine name.
    [selection]

  Toggle Breakpoint      Activates/deactivates breakpoint at mouse pointer.
    at Line
    [line number]

  Temporary Breakpoint   Sets temporary breakpoint at mouse pointer.
    at Line
    [line number]

  Go to Line             Branches to [line number] without executing source
    [line number]        code betwen the line at which execution is suspended
                         and [line number].

  Display Instruction    Displays decoded instruction stream of your program.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

  If you press MB3 while your mouse pointer rests in the annotation area
  of the source view, a pop-up menu with the following items appears:

  Toggle Breakpoint      Activates/deactivates breakpoint at mouse pointer.
    at Line
    [line number]

  Temporary Breakpoint   Sets temporary breakpoint at mouse pointer.
    at Line
    [line number]

  Go to Line             Executes until [line number] is reached.
    [line number]

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

3  –  callstack_menu_hlp

  Use the Call Stack menu on the main window to do the following:

  Action               Function
  -------              ---------

  None                 Identifies the routine whose source code is
                       executing in the source view.

  Pull-down            Identifies the sequence of routines on the
     menu              call stack.

  Click on             Sets the context (scope) for source display,
     routine           instruction display, register display,
     name              and symbol searches to any routine on the
                       call stack.

4  –  cnt_button_hlp

  The push-button view on the main window contains push buttons that
  correspond to debugger commands.  You can modify, add, remove, and
  resequence push buttons and the commands associated with them.

  Use the default push buttons to complete the following functions.

   Push
   Button       Function
   ------       --------
   Stop         Interrupts program execution or a debugger
                operation without ending the debugging
                session.

   Go           Starts or resumes execution from the current
                program location.

   Step         Executes the program one step unit of
                execution. By default, this is one executable
                line of source code.

   S-into       (Step into)  When execution is suspended at a
                routine call statement, moves execution into
                the called routine just past the start of the
                routine. If not at a routine call statement,
                this push button has the same behavior as the
                Step push button.

   S-ret        (Step return) Executes the program directly to
                the end of the routine.

   S/call       (Step call) Executes the program to the next
                call or return instruction.

   EX           (Examine) Displays, in the command view,
                the current value of a variable whose name
                you have selected in a window.

   E/az         Displays, in the command view, the current
                value of a variable whose name you have
                selected in a window.  The variable is interpreted
                as a zero-terminated ASCII string.

   E/ac         Displays, in the command view, the current
                value of a variable whose name you have
                selected in a window.  The variable is interpreted
                as a counted ASCII string preceded by a one-byte
                count field that contains the length of the string.

   EVAL         Displays, in the command view, the value
                of a language expression in the current language
                (by default, the language of the module containing
                the main program.

   MON          (Monitor) Displays, in the monitor view, a
                variable name that you have selected in a window
                and the current value of that variable. Whenever the
                debugger regains control from your program, it
                automatically checks the value and updates the
                displayed value accordingly.

5  –  stop_btn_hlp

  Use the Stop push button to interrupt program execution or a debugger
  operation without ending the debugging session.

6  –  msg_region_hlp

  The command view on the main window accepts command-line entry input,
  echoes GUI actions (in a command-line format), and displays debugger
  messages.

7  –  popup_msgregion

  To use the pop-up menu in the command view, position your mouse pointer
  in the message region, and press MB3.  The debugger automatically
  inserts your last command in the [last command] menu item of this
  pop-up menu.

  Menu items are as follows:

  Repeat Command         Re-enters your last command.
    [last command]

  Clear Command Window   Clears the command view and displays
                         the DBG> prompt.

  Clear Command Line     Clears command line.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

8  –  src_window_menubar_hlp

  Use the menus on the menu bar as explained in the Additional Topics.

9  –  src_file_pd_menu_hlp

  Use the File menu on the main window as follows:

  Action               Function
  ------               --------

  Run Image...         Brings a program under debugger
                       control by specifying an executable
                       image.

  Run Foreign          Brings a program under debugger
   Command...          control by specifying a foreign
                       command symbol.

  Rerun Same...        Reruns the same program under
                       debugger control.

  Browse Sources       Lists the modules in your program.
                       You can choose to list all modules,
                       or only those for which symbolic
                       information is available.  You can
                       display the source code in any module
                       of your program for which symbolic
                       information is available.

                      Can also be used to set breakpoints on
                       routines.

  Display Line         Displays or hides line numbers in the
   Numbers             main window.

  Server Connection... (Client-Server only) Invokes the
                       Server Connection dialog to allow you to
                       set up and control a connection between a
                       debug client and a debug server.

  Exit Debug?          Exits from the debugger.  If running
                       in client-server mode, allows you
                       to exit either the client, server,
                       or both.

10  –  src_edit_pd_menu_hlp

  Use the Edit menu on the main window as follows:

  Action      Function
  ------      --------

  Cut         Cuts selected text from the current command
              line and copies it to the clipboard.
              If selected text is anywhere other than
              the current command line, copies the
              text to the clipboard.

  Copy        Copies selected text from the window to
              the clipboard without removing it
              from the window.

  Paste       Pastes text from the clipboard to the insert
              point on the current command line in the
              command view.

  See the DECwindows Motif documentation for more information.

11  –  src_break_pd_menu_hlp

  Use the Break menu on the main window as follows:

  Action           Function
  ------           --------

  On Exception     Breaks on any exception signaled
                   during program execution.

  Activate All     Activates all breakpoints that have
                   not been canceled, causing the debugger
                   to suspend program execution when a
                   breakpoint is reached.

  Deactivate All   Deactivates all breakpoints, causing
                   the debugger to ignore them during
                   program execution.

  Cancel All       Removes all breakpoints from the
                   debugger's database.  You cannot
                   reactivate these breakpoints without
                   explicitly setting them first.

  Set...           Displays the Set/Nodify Breakpoint
                   dialog box to set an individual breakpoint
                   (see Additional Topics).

12  –  src_commands_pd_menu_hlp

  Use the Commands menu on the main window as follows:

  Action          Function
  ------          --------

  Examine...     Examines the value of a variable or expression.

  Deposit...     Changes the value of a variable.

  Edit File      Opens the editable source window with the current
                  file displayed.

13  –  cnt_options_pd_menu_hlp

  Use the Options menu on the main or the optional view window as
  follows:

  Action             Function
  ------             --------

  Views...           Displays one or more of the
                     debugger's optional views:

                        Breakpoint View
                        Monitor View
                        Instruction View
                        Threads View
                       Register View

  .!Track Language     Notify you when the debugger
  .!   Changes         enters a module written in
  .!                   a different source language
  .!                   than the previous module.

  Show Message       Display a dotted line between
     Separators      debugger messages and commands.

  Customize          Adds, removes, or resequences
     Buttons...      a push button in the push-button view.
                     Also changes a button's label or
                     the debugger command associated with
                     a button.

  Save Options       Saves the current definitions of the
                     debugger user-interface options for use
                     in subsequent debugger sessions.

  Restore Default    Copies and saves the default definitions
      Options        of the the debugger user-interface options
                     for use in subsequent debugger sessions.

  Edit Options File  Loads and displays local debugger resource
                     file DECW$USER_DEFAULTS:VMSDEBUG.DAT in the
                     Debug Editor for review and modification.

14  –  save_edit_options

  The Save Options command in the Options menu of the source view saves
  the current definitions of the debugger user-interface options in the
  user-specific debugger resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT.

  You can use the debugger editor or another editor to change the
  definitions in the debugger resource file.

15  –  restore_default_options

  The Restore Default Options in the Options menu of the source view
  copies the system default debugger resource file
  DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT to the user-specific debugger
  resource file DECW$USER_DEFAULTS:VMSDEBUG.DAT.  It does not purge
  previous versions of the user-specific debugger resources file.

  You must exit and restart the debugger to invoke the default
  definitions in the restored debugger resource file.

16  –  edit_options_file

  The Edit Options File in the Options menu of the source view loads and
  displays the local debugger resource file
  DECW$USER_DEFAULTS:VMSDEBUG.DAT in the Debug Editor for review and
  modification.  If there is no local debugger resource file, the Debug
  Editor buffer is empty.

  To create a local debugger resource file, exit the Debug Editor and
  select Save Options or Restore Default Options from the Options menu of
  the source view.

  You must exit and restart the debugger to invoke the default
  definitions in the edited debugger resource file.

17  –  help_pd_menu_hlp

  The Help menu contains the following items that let you display online
  help about the debugger:

    On Context
    On Window
    On Help
    On Version
    On Commands

  For more information about using a Help menu item, double click on an
  item from the list of Additional Topics below.

18  –  run_new_hlp

  After starting the debugger as explained in the topic Starting the
  Debugger, bring a program under debugger control using one of the
  following two techniques:

   -  Run a specified image.  This is the most common technique and is
      described below.

   -  Run an image by specifying a symbol for a foreign command or a DCL
      command.  This technique is described in the topic Running an Image
      by Specifying a Symbol.

  To run a specified image:

  1.  Choose Run Image...  from the File menu on the main window.  The
      Run Image...  dialog box appears, which lists:

       -  A Directories list that contains the parent directory and any
          subdirectories contained in the current directory

       -  A Filter field; by default this specifies the .EXE files in
          your current directory

       -  An Images list that contains the names of images in the current
          directory that meet the filter specification

       -  An Arguments field to pass any required arguments to the image
          to be run

       -  A Heap Analyzer button to run the Heap Analyzer

       -  An Image field to display and specify the full file
          specification of the image to be run

       -  An OK button to run the image specified in the Image field and
          dismiss the dialog box

       -  A Filter button to display a list of files that meet the
          specification in the Filter field

       -  A Cancel button to dismiss the dialog box without taking and
          further action

       -  A Help button to display this help information

  2.  In the Directories list, click on the name of the appropriate
      subdirectory and click on Filter to list the (filtered) files in
      the subdirectory.  The debugger also displays, in the Directories
      list, the parent directory and any subdirectories of the selected
      directory.

  3.  In the Images list, click on the name of the image to be debugged.
      The Image field now shows the image specification.  You can edit
      this specification as needed.

  4.  If applicable, enter arguments to be passed to the program in the
      Arguments field.  Quoted strings, may require additional quotation
      marks because the debugger strips quotes when parsing the string.

  5.  To run the Heap Analyzer, click the Heap Analyzer button.

  6.  Click on OK to dismiss the dialog box and run the spcified image.

  When the program is under debugger control, the debugger:

   -  Displays the program's source code in the main window.

   -  Suspends execution at the start of the main program.  The
      current-location pointer, to the left of the source code, shows the
      line whose code will be executed next.

  The message displayed in the command view indicates the name of the
  main program unit and also indicates that the debugging session is
  initialized for the source language of the program.  The initialization
  sets up language-dependent debugger parameters.  These parameters
  control the way the debugger parses names and expressions, formats
  debugger output, and so on.

  You can now debug your program.

  With certain programs, the debugger suspends execution at the start of
  some initialization code, before the main program, and displays the
  following message:

  Type GO to reach main program

  With some of these programs (for example, Ada programs), the first
  breakpoint lets you debug the initialization code using full symbolic
  information.

  Note the following restrictions about running a program under debugger
  control:

   -  You cannot use the procedure just described to connect the debugger
      to a running program.

   -  You cannot run a program under debugger control over a DECnet link.
      Both the image to be debugged and the debugger must reside on the
      same node.

19  –  run_foreign_hlp

  To run an image by specifying a symbol for a foreign (DCL) command:

  1.  Choose Run Foreign Command...  from the File menu on the main
      window.  The Run Foreign Command dialog box appears.

  2.  Enter a symbol for a DCL command in the Foreign Command field.  The
      symbol might be defined as "RUN long_file_name.ext" or a similar
      command.

  3.  Enter any arguments to be passed with the command in the Arguments
      field.  If you specify a quoted string, you might have to add
      quotation marks because the debugger strips quotes when parsing the
      string.

  4.  To run the Heap Analyzer, click the Heap Analyzer button.

  5.  Click on OK.

  For information about startup conditions, see the Bringing a Program
  Under Debugger Control topic.

20  –  rerun_same_hlp

  You can rerun the program currently under debugger control at any time
  during a debugging session.

  To rerun your program:

  1.  Choose Rerun Same...  from the File menu on the main window.  The
      Rerun Same dialog box appears.

  2.  If applicable, enter any arguments to be passed to the program in
      the Arguments field.

  3.  Choose whether to save or not save the current state of any
      breakpoints or static watchpoints that you previously set,
      activated, or deactivated.  Nonstatic watchpoints might or might
      not be saved, depending on the scope of the variable being watched
      relative to the main program unit (where execution restarts).

  4.  To run the Heap Analyzer, click the Heap Analyzer button.

  5.  Click on OK.

  When you rerun a program, it is in the same initial state as a program
  that is initially brought under debugger control, except for any saved
  breakpoints or static watchpoints.  The source display and current
  location pointer are updated accordingly.

  When you rerun a program, the debugger uses the same version of the
  image that is currently under debugger control.  To debug a different
  version of that program (or a different program) from the same
  debugging session, choose Run Image...  or Run Foreign Command...  from
  the File menu on the main window.

21  –  browse_src_hlp

  Use the Browse Source dialog box to:

   -  Display the source code in any module of your program

   -  Set breakpoints on routines

22  –  popup_browser

  To use pop-up menus in the Source Browser dialog box, position your
  mouse pointer in the dialog box, and press MB3.  A pop-up menu with the
  following items appears:

  Expand                 Expand the selected image or module to include its
                         component modules or functions in the Source
                         Browser display.

  Collapse               Collapse an expanded image, module, or function display.

  Display Source         Display (in the source display of the source view
                         on the main window) the source code associated
                         with the selected module.

  Set Breakpoint         Set a breakpoint on the selected function.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

23  –  show_line_numb

  To hide or display source line numbers in the main window, click on
  Show Line Numbers in the File menu of that window.

  Line numbers help you identify breakpoints that are listed in the
  breakpoint view.  If you hide line numbers, more of the source code
  shows through a window of a given width.

24  –  exit_db_hlp

  To exit the kept debugger, which will terminate the current debugging
  session, click on Yes.

  Otherwise, click on No to return to the current session.

  In client-server mode, the default is to exit both the client and the
  server.  Make sure that the correct buttons are selected, then click on
  OK to exit, or click on Cancel to return to the current session.

25  –  cancel_all_break_hlp

  To cancel all breakpoints, click on Yes.

  Otherwise, click on No to preserve all breakpoints.

26  –  breakpoint_set_show_hlp

  If you are displaying the Set/Modify Breakpoint dialog box from the
  Set...  menu item in the Break menu on the main or instruction window,
  use the Set/Modify Breakpoint dialog box to SET a conditional
  breakpoint or an action breakpoint.

  If you are displaying the Set/Modify Breakpoint dialog box from the
  Set/Modify...  menu item in the Break menu on the optional view window
  use the Set/Modify Breakpoint dialog box to SET OR MODIFY a conditional
  breakpoint or an action breakpoint.

  When the Set/Modify Breakpoint dialog box appears, complete the fields
  as follows:

     Field                     Action
     -----                     ------

  Location field             If the dialog box does not display the
                             location of the breakpoint you are
                             setting or modifying, enter the location
                             using one of the following forms:

                             <routine-name>\%line <line-number>
                             routine <routine-name>
                             <numeric-address>

  Condition field            Optionally, enter a condition or edit
                             an existing condition.  The relational
                             expression must be valid in the
                             source language of the program module.

  Action field               Optionally, enter an action or edit
                             an existing action by substituting
                             one or more new debugger commands
                             (separated by a semi-colon).

  Activate/Deactivate        Optionally, activate a deactivated
    Breakpoint button        breakpoint by accepting the default,
                             or deactivate an activated breakpoint
                             by toggling this button.

  OK button                  Click on OK to set the breakpoint
                             and dismiss the dialog box.

  Apply button               Click on Apply to set the breakpoint
                             and clear the dialog box.

  Cancel Breakpoint          Click on Cancel Breakpoint to remove
    button                   a breakpoint. Note that you can no longer
                             reactivate this breakpoint unless you
                             again explicitly set it.

  Cancel button              Click on Cancel to dismiss the dialog
                             box.

  Help button                Click on Help to display this help
                             information.

27  –  examine_hlp

  The Examine dialog box allows you to display the current value of a
  variable or expression in the command view.  If you choose, you can
  change the type or output radix of the displayed value.

  To use the Examine dialog box, perform the following steps:

  1.  Do one of the following:

       -  Find and select the variable name or expression symbols in a
          window, and choose the Examine menu item from the Commands menu
          on the main window.  The Examine dialog box appears, with the
          name you selected in the Variable/Expression field.

       -  Choose the Examine menu item from the Commands menu on the main
          window.  The Examine dialog box appears.  Enter the name of the
          variable or symbols of the expression you are examining in the
          Variable/Expression field of the dialog box.

  2.  If you are changing the output type, pull down the menu in the
      Typecast entry box and click on the desired data type.

  3.  If you are changing the output radix, pull down the menu in the
      Output Radix entry box and click on the desired radix.

  4.  Click on Apply to give the command or click on OK to give the
      command and dismiss the dialog box.

  Your echoed command and the current value appear in the command view.

  Click on Cancel to dismiss the dialog box.

  Click on Help to display this Help information.

28  –  deposit_hlp

  The Deposit dialog box allows you to change the current value of a
  variable.  If you choose, you can change the input radix of the
  deposited value.

  To use the Deposit dialog box, perform the following steps:

  1.  Do one of the following:

       -  Find and select the variable name in a window, and choose the
          Deposit menu item from the Commands menu on the main window.
          The Deposit dialog box appears, with the name you selected in
          the Variable field.

       -  Choose the Deposit menu item from the Commands menu on the main
          window.  The Deposit dialog box appears.  Enter the name of the
          variable to which you are depositing a value in the Variable
          field of the dialog box.

  2.  Enter the value you are depositing in the Value field of the dialog
      box.

  3.  If you are changing the input radix, pull down the menu in the
      Input Radix entry box and click on the desired radix.

  4.  Click on Apply to give the command or click on OK to give the
      command and dismiss the dialog box.

  Your echoed command and the current value appear in the command view.

  Click on Cancel to dismiss the dialog box.

  Click on Help to display this Help information.

  Your echoed command appears in the command view, indicating that the
  value is changed.

29  –  editor_hlp

  Use the editable source window to edit the source code of the program
  you are currently debugging, or any other source code file.

  Location          Function
  ---------        -----------

  Buffer            Displays an empty text buffer for text entry,
                    or a full text buffer containing the text you will
                    edit.

  Search String     Accepts a string for forward or backward search.
     Entry Box

  Directional       Indicates the direction (forward, backward) of
     Arrows         a search.

  Replace String    Indicates whether search string is replaced when
     Toggle         found.

  Replace String    Accepts a string that replaces the specified
     Entry Box      search string.

  Buffer Menu       Provides a list of active buffers, any of which
                    you can choose to display.

30  –  editor_find_hlp

  Use the Find Text field to search for a specified string.

  The direction of the search is controlled as follows:

   -  Press an arrow key to search text in the direction indicated by
      that arrow.  This also sets the default search direction.

   -  Press Ctrl/N to search forward (down) through the file, regardless
      of the arrow indicator position.

   -  Press Ctrl/P to search backwards (up) through the file, regardless
      of the arrow indicator position.

  If you click the "Replace with" toggle button, the editor replaces each
  instance of the search string with the text entered in the Replace with
  field.

31  –  editor_replace_hlp

  Use the Replace with field to replace a specified string.

  After you enter the search string in the Find Text field and indicate a
  search direction, click the "Replace with" toggle button and enter the
  replacement string.  The editor replaces each instance of the search
  string with the replacement string.

32  –  editor_pd_menu_hlp

  Use the menus on the menu bar as explained in the Additional Topics.

33  –  fill_buffer

  By default,the editor window displays an empty text buffer, called
  dbg_editor_main.  If you are debugging a program at the time you invoke
  the editor, however, the editor window displays this program, names the
  filled text buffer with its specification, and places dbg_editor_main
  on the buffer menu as an alternative text buffer.

  The editor allows you to create any number of text buffers by choosing
  New (for empty text buffers) or Open (for existing files) from the File
  menu.  The name of each buffer appears in the buffer menu.  You can
  cut, copy, and paste text across buffers by choosing items from the
  Edit menu and selecting buffers from the buffer menu.

34  –  search_text

  Forward and backward search and replace operations can be performed by
  entering strings in the Find text and Replace with entry boxes and
  clicking on a directional arrow.

  If you continue to click on a directional arrow, or if you continue to
  press the Return key, a repeated search for the string occurs in the
  direction you indicate.

  You can also continue a search by choosing the Find/Replace Next or
  Find/Replace Previous items in the Edit menu.

35  –  recompile_edits

  When you complete your edits, and save these to your file by choosing
  the Save or Save As items from the editor's File menu, you need to
  recompile and relink your source file.

  You do not need to exit the debugger to do this.

  Enter the compile and link commands in another DECterm window, and when
  you return to the debugger, choose the Rerun Same item in the File menu
  on the main window.  Your edited source code will appear in the
  debugger's source view.

36  –  editor_file_pd_menu_hlp

  Use the File menu on the editable source window as follows:

  Action      Function
  ------      --------

  New         Opens a buffer for a new file.

  Open...     Opens a buffer for an existing file.

  Save        Saves the current buffer using same file name.

  Save As...  Saves the current buffer using specified file name.

  Close       Closes the editable source window.
   Editor

37  –  editor_filesel_hlp

  Use the Open/Save dialog box to specify the file you are opening
  (before editing) or the file you are saving to (after editing), as
  follows:

  1.  If the default value (for your current directory) is not
      acceptable, click on the name of another directory from the
      directory list.

  2.  In the list of files, click on the file name you are opening or
      saving to.

  3.  Click on OK.

38  –  editor_edit_pd_menu_hlp

  Use the Edit menu on the editable source window as follows:

  Action         Function
  ------         --------

  Cut            Cuts selected text from the window and
                 copies it to the clipboard.

  Copy           Copies selected text from the window to
                 the clipboard without removing it
                 from the window.

  Paste          Pastes text from the clipboard to a
                 text-entry field or region.

  Clear          Clears the text selected (highlighted)
                 in the window.

  Find/Replace   Finds and replaces the next instance.
    Next
    (or Ctrl/N)

  Find/Replace   Finds and replace the previous instance.
    Previous
    (or Ctrl/P)

  Refresh File   Loads and displays the latest version
                 of the file in the selected editor
                 buffer.  This is convenient for checking
                 .LOG and other results files during
                 debugging.

  Close File     Removes the currently selected edit
                 buffer from the display and menu,
                 closes the file, and frees associated
                 memory.  Prompts the user to save or ignore
                 any modifications to the edit buffer.

39  –  editor_text_buffer_menu

  Use the Buffer menu on the editable source window as follows:

  Action             Function
  ------             --------

  None               Identifies the text buffer that is
                     currently active.

  Pull-down menu     Identifies all other text buffers that
                     are currently active, including the empty
                     text buffer, dbg_editor_main.

  Clicking on        Allows you to switch from one active
  a buffer in        buffer to another.  You can cut, copy,
  the pull-down      and paste text across buffers by choosing
  menu               items from the Edit menu and selecting buffers
                     from the Buffer menu.

40  –  options_viewsel_hlp

  Use the Views dialog box as follows:

  Action            Function
  ------            --------

  File View         Closes dialog box or exits debugger.

  Breakpoint View   Displays the breakpoint view.

  Monitor View      Displays the monitor view.

  Instruction View  Displays the instruction view.

  Register View     Displays the register view.

  Threads View      Displays the threads view.

41  –  optional_view_sel_hlp

  Use the Views dialog box as follows:

  Action            Function
  ------            --------

  Breakpoint View   Displays the breakpoint view.

  Monitor View      Displays the monitor view.

  Instruction View  Displays the instruction view.

  Register View     Displays the register view.

  Threads View      Displays the threads view.

42  –  views

  At startup, the debugger displays only one window, the main window.

  To display additional information on your program in the optional view
  window, perform the following steps:

  1.  Choose the Views...  menu item from the Options menu on the main
      window.  The Views dialog box appears.

  2.  Click on one or more of the following views in the dialog box:

      Breakpoint View   Displays the breakpoint view.

      Monitor View      Displays the monitor view.

      Instruction View  Displays the instruction view.

      Register View     Displays the register view.

      Threads View      Displays the threads view.

  These views appear within the optional view window on your screen.

  To select different views, repeat this process, clicking on different
  views within the View dialog box.

43  –  close_views

  To dismiss all views and close the optional view window, do one of the
  following:

   -  Choose the Views...  menu item from the Options menu on the main or
      optional view window.  When the Views dialog box appears, clear all
      the toggle buttons within the dialog box, and click on OK.

   -  Choose the Close menu item from the File menu on the optional view
      window to close the optional view window.

   -  Choose the Close menu item from the File menu on the instruction
      window to close the instruction window.

44  –  custm_db_hlp

  Use the Customize Button Dialog box to modify, add, remove, or
  resequence push buttons and the associated debugger commands.

  NOTE:  You cannot modify or remove the Stop push button.

45  –  custm_add_hlp

  Use the Add push button to add a new push button to the push-button
  view in the main window.

46  –  custm_mod_hlp

  Use the Modify push button to modify the label, icon, or debugger
  command associated with a push button in the push-button view.

47  –  custm_remove_hlp

  Use the Remove push button to remove a push button from the push-button
  view in the main window.

48  –  custm_larrow_hlp

  Use the Left Arrow button to move a push button one push button to the
  left in the push-button view.

49  –  custm_rarrow_hlp

  Use the Right Arrow push button to move a push button one push button
  to the right in the push-button view.

50  –  on_context_hlp

  Invisible:  Brings up the ?  pointer for context-sensitive help.

51  –  on_mwindow_hlp

  The OpenVMS Debugger helps you locate run-time programming or logic
  errors, also known as bugs.  You use the debugger with a program that
  has been compiled and linked successfully but does not run correctly.
  For example, the program might give incorrect output, go into an
  infinite loop, or terminate prematurely.  You locate errors with the
  debugger by observing and manipulating your program interactively as it
  executes.  The debugger lets you:

   -  Display and edit the source code for your program, and browse
      through other source code files.

   -  Monitor, examine, and change program variable and data structure
      values and examine their type.

   -  Examine and manipulate the currently active functions on the call
      stack.

   -  Set breakpoints that suspend program execution or issue debugger
      command sequences.

   -  Step through execution one line of source code or machine
      instruction at a time.

   -  Disassemble and examine machine code; examine and modify
      machine-register values.

   -  Customize the debugging environment.

  These are the basic debugging techniques.  After you are satisfied that
  you have found the error in the program, you can edit the source code
  and compile, link, and execute the corrected version.

  As you use the debugger and its documentation, you will discover
  variations on the basic techniques.  You can also customize the
  debugger to meet your own needs.

  The debugger is a symbolic debugger.  You can specify variable names,
  routine names, and so on, precisely as they appear in your source code.
  You do not need to specify memory addresses or registers when referring
  to program locations, but you can if you want.

  You can also use the debugger with programs written in any of the
  languages identified in the topic Debugger Support for Languages.

52  –  on_owindow_hlp

  The OpenVMS Debugger helps you locate run-time programming or logic
  errors, also known as bugs.  You use the debugger with a program that
  has been compiled and linked successfully but does not run correctly.
  For example, the program might give incorrect output, go into an
  infinite loop, or terminate prematurely.  You locate errors with the
  debugger by observing and manipulating your program interactively as it
  executes.  The debugger lets you:

   -  Display and edit the source code for your program, and browse
      through other source code files.

   -  Monitor, examine, and change program variable and data structure
      values and examine their type.

   -  Examine and manipulate the currently active functions on the call
      stack.

   -  Set breakpoints that suspend program execution or issue debugger
      command sequences.

   -  Step through execution one line of source code or machine
      instruction at a time.

   -  Disassemble and examine machine code; examine and modify
      machine-register values.

   -  Customize the debugging environment.

  These are the basic debugging techniques.  After you are satisfied that
  you have found the error in the program, you can edit the source code
  and compile, link, and execute the corrected version.

  As you use the debugger and its documentation, you will discover
  variations on the basic techniques.  You can also customize the
  debugger to meet your own needs.

  The debugger is a symbolic debugger.  You can specify variable names,
  routine names, and so on, precisely as they appear in your source code.
  You do not need to specify memory addresses or registers when referring
  to program locations, but you can if you want.

  You can also use the debugger with programs written in any of the
  languages identified in the topic Debugger Support for Languages.

53  –  on_ewindow_hlp

  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.

54  –  on_iwindow_hlp

  Use the instruction window to:

   -  Display the decoded instruction stream of your program

   -  Set, activate, deactivate, or delete breakpoints on instructions

  For information on tasks in the instruction window, see the Additional
  Topics below.

55  –  on_help_hlp

  Several kinds of online help about the debugger and debugging are
  available during a debugging session:

   -  Context-sensitive help, which is information about an area or
      object in a window or dialog box

   -  Task-oriented help, which consists of an introductory help topics
      describing the tasks that can be accomplished in each window of the
      debugger and several subtopics on specific debugging tasks

   -  Help on debugger commands and various topics, such as language
      support

   -  Help on debugger diagnostic messages

  Related context-sensitive and task-oriented topics are connected
  through the list of Additional Topics in the Help windows.

56  –  on_version_hlp

  OpenVMS Debugger

  Software Version:    OpenVMS Debugger Version 8.4-1H1

  Copyright 2015 VMS Software, Inc.

  All rights reserved.

  For more information about the OpenVMS Debugger, double click on Using
  the Main Window from the list of Additional Topics below.

57  –  on_command_hlp

58  –  debug_error_hlp

  The error dialog box contains a brief description of an internal
  inconsistency detected by the debugger.  If the cause of the error is
  not obvious, select the Help Menu on the Main Window, select
  On_Commands, select Messages, and scroll through the display until you
  can select the message code that is displayed in the error dialog box.
  You may find more information about the error in the OpenVMS System
  Messages and Recovery Procedures manual.

59  –  breakpoint_disp_hlp

  Use the breakpoint view to do the following:

   -  Identify the breakpoints that are currently set in your program

   -  Review or change breakpoint status

   -  Display conditions or actions associated with breakpoints

   -  Modify conditions or actions associated with breakpoints

   -  Set new breakpoints

  Breakpoints are listed in the Identification column of the view,
  including the module name and line number for each breakpoint.

  All breakpoints listed in the breakpoint view have been previously set.
  A filled-in button in the State column indicates that the breakpoint is
  set and active.  A cleared button indicates that the breakpoint has
  been deactivated.  (If you delete a breakpoint, the breakpoint entry
  disappears from the breakpoint view.)

  If you have set a conditional breakpoint, the button shape changes from
  a square to a diamond.  You can also double-click on a breakpoint entry
  to determine whether conditions or actions are associated with it.

60  –  popup_break

  To use the pop-up menu in the breakpoint view, position your mouse
  pointer in the breakpoint list or annotation area of the breakpoint
  view, and press MB3.

  A pop-up menu with the following items appears:

  Toggle                 Toggles a selected breakpoint.

  Set/Modify...          Provides the Set/Modify Breakpoint dialog box,
                         which contains information about a selected
                         breakpoint.

  Cancel                 Removes a selected breakpoint.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

61  –  monitor_disp_hlp

  Use the monitor view to:

   -  Monitor the value of a variable or an expression during the
      execution of your program

   -  Watch a variable during the execution of your program

   -  Change the value of a variable

  To add an entry to the monitor list, select a variable name or
  expression in the source view and click on the Monitor push button.
  The debugger displays the current value in the monitor view and checks
  and updates the displayed value whenever it regains control from your
  program (for example, after a step or at a breakpoint).

  Monitored variables and expressions are listed in the Monitor
  Expression column.  Their values are listed in the Value/Deposit
  column.

  The button in the Watched column indicates whether the variable is
  being watched (button filled) or not (button empty).

62  –  popup_monitor

  To use the pop-up menu in the monitor view, position your mouse pointer
  in the monitor view, and press MB3.

  A pop-up menu with the following items appears:

  Expand                 Expand a monitored aggregate to show its members.

  Collapse               Collapse an expanded aggregate.

  Toggle Watchpoint      Activates or deactivates a selected watchpoint.

  Typecast ->            Provides the list of type choices for modifying values.

  Change Radix ->        Provides the list of radix choices for modifying values.

  Remove                 Remove the selected expression from the monitor
                         list of the monitor view.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

63  –  register_view_hlp

  Use the register view to:

   -  Display the current values stored in the machine registers.

   -  Modify the value stored in a register

  Any values that change as your program executes are highlighted
  whenever the debugger regains control from your program.

64  –  popup_register

  To use the pop-up menu in the register view, position your mouse
  pointer in the register view, and press MB3.

  A pop-up menu with the following menu items appears:

  Change Radix ->        Provides the list of radix choices for modifying values.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

65  –  inst_view_hlp

  Use the instruction view to:

   -  Display the decoded instruction stream of your program

   -  Set, activate, deactivate, or delete breakpoints on instructions

66  –  inst_workarea_hlp

  Use the instruction view to:

   -  Display the decoded instruction stream of your program

   -  Set, activate, deactivate, or delete breakpoints on instructions

67  –  popup_instruction

  To use pop-up menus in the instruction view, select text or position
  your mouse pointer in the instruction window, and press MB3.  The
  debugger inserts the selected text or line number in the menu items of
  the pop-up menu.

  If you press MB3 while your mouse pointer rests on an instruction
  source line in the instruction window, a pop-up menu with the following
  items appears:

  Examine [selection]    Evaluates the selected text and prints
                         its value in the command view.

  Toggle Breakpoint      Toggle breakpoint at your mouse pointer location.
    [line number]

  Display Source         Display source associated with instruction.

  Step-Instructions      Step to next instruction, stepping over routine
                         calls.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

  If you press MB3 while your mouse pointer rests in the annotation area
  of the instruction window, a pop-up menu with the following items
  appears:

  Toggle Breakpoint      Toggle breakpoint at your mouse pointer location.

  Step                   Step to next line, stepping over routine calls.

  Go                     Resume execution of program.

68  –  task_view_hlp

  Use the thread view to display information about the threads (tasks) of
  a multithreaded program.

69  –  task_workarea_hlp

  Use the threads view to display information about the threads (tasks)
  of a multithreaded program.

70  –  cnt_window_hlp

  Use the threads view to display information about the threads (tasks)
  of a multithreaded program.

71  –  popup_task

  To use pop-up menus in the threads view, select a thread from the list
  or position your mouse pointer in the threads view, and press MB3.

  A pop-up menu with the following menu items appears:

  Abort        Requests that the selected thread be terminated
               at the next allowed opportunity.  The exact effect
               depends on the current event facility (which is
               language dependent).  For Ada tasks, this is
               equivalent to executing an abort statement.

  Activate     Makes the selected thread the active thread.

  Hold         Places the selected thread on hold.

  Nohold       Releases the selected thread on hold.

  Visible      Makes the selected thread the visible thread.

72  –  cnt_window_menubar_hlp

  Use the menus on the menu bar as explained in the Additional Topics.

73  –  cnt_file_pd_menu_hlp

  Use the File menu on the optional view window as follows:

  Action               Function
  ------               --------

  Close                Closes the optional view window.

  Exit Debug?          In the kept debugger, ends the
                       debugging session, and exits the
                       debugger.  In client-server mode,
                       allows you to exit the client,
                       server, or both.

74  –  cnt_break_pd_menu_hlp

  Use the Break menu on the optional view window as follows:

  Action           Function
  ------           --------

  On Exception     Breaks on any exception signaled
                   during program execution.

  Activate All     Activates any previously set
                   breakpoints.

  Deactivate All   Deactivates any previously set
                   breakpoints.

  Cancel All...    Removes all breakpoints from the
                   debugger's breakpoint list and
                   from the breakpoint view.

  Toggle           Toggles an individual breakpoint.

  Set/Modify...    Sets or modifies an individual breakpoint.

  Cancel           Removes an individual breakpoint.

75  –  cnt_monitor_pd_menu_hlp

  Use the Monitor menu on the optional view window as follows:

  Action             Function
  ------             --------

  Expand             Expands a selected nonscalar variable.

  Collapse           Collapses a selected nonscalar variable.

  Deposit...         Changes the value of variable.

  Toggle
     Watchpoint      Activates or deactivates a watchpoint.

  Typecast ->        Typecasts a selected variable.

  Change Radix ->    Changes the radix for a selected variable.

  Change All
     Radix ->        Changes the default radix for all subsequent
                     monitor entries.

  Remove             Removes the monitor entry from display.

76  –  cnt_register_pd_menu_hlp

  Use the Register menu on the optional view window as follows:

  Action             Function
  ------             --------

  Assign...          Modifies the selected register.

  Change Radix ->    Changes the radix for a selected register.

  Change All
     Radix ->        Changes the radix for all registers.

77  –  cnt_task_pd_menu_hlp

  Use the Threads menu on the optional view window as follows:

  Action      Function
  ------      --------

  Abort       Requests that the selected thread be terminated
              at the next allowed opportunity. The exact effect
              depends on the current event facility (which is
              language dependent). For Ada tasks, this is
              equivalent to executing an abort statement.

  Activate    Makes the selected thread the active thread.

  Hold        Places the selected thread on hold.

  Nohold      Releases the selected thread on hold.

  Make        Makes the selected thread the visible thread.
  Visible

  All ->      Uses the submenu to:
                 Abort all threads.
                 Hold all threads.
                 NoHold all threads.

78  –  inst_window_menubar_hlp

  Use the menus on the menu bar as explained in the Additional Topics.

79  –  inst_file_pd_menu_hlp

  Use the File menu on the Instruction View as follows:

  Action               Function
  ------               --------

  Show Instruction     Displays the address associated
     Addresses         with each instruction listed in
                       the instruction view.

  Display Line         Displays the line number of your
     Numbers           source-code program associated with
                       each instruction or set of instructions
                       listed in the instruction view.

  Close                Closes the instruction window.

80  –  inst_edit_pd_menu_hlp

  Use the Edit menu on the instruction view as follows:

  Action    Function
  ------    --------

  Copy      Copies text that you have selected in the
            window to the clipboard without removing it
            from the window.

            (To paste your text from the clipboard to
            a text-entry field or region, choose the
            Paste item from the Edit menu on the
            main window.)

81  –  inst_break_pd_menu_hlp

  Use the Break menu on the instruction window as follows:

  Action           Function
  ------           --------

  Activate All     Activates any previously set
                   breakpoints.

  Deactivate All   Deactivates any previously set
                   breakpoints.

  Cancel All       Removes all breakpoints from the
                   debugger's breakpoint list and
                   from the instruction view.

  Set...           Sets an individual breakpoint.

82  –  server_connection_help

  The Connection dialog is used to manage connections between a
  DECwindows Motif debug client and a debug server running on OpenVMS.

  You can use the Server Connection dialog to make new connections to
  servers, reconnect to servers that you have connected to before,
  monitor the status of existing active sessions, switch the display
  context among active sessions, test and shutdown servers, and limit the
  number of clients that a server will accept.

  See Additional Topics for specific information about the Server
  Connection dialog.  To display the Server Options dialog of the
  Connection dialog box, click the Properties button, or open the Options
  menu, then click Connection dialog on the Properties submenu.

  Click sections of the Connection dialog box below to see a description
  of each control on the dialog box.  Please refer to the OpenVMS
  Debugger manual for more information..

83  –  conn_dialog_connect

  Click Connect to initiate the connection request to the server
  identified in the Connection list.  Status of the connection request is
  displayed in the message display of the Command view.  Additional
  status is displayed at the bottom of the Server Connection dialog to
  indicate whether the requested connection has been established as a new
  active session.

  When a connection has been successfully made to a server the Server
  Connection dialog is dismissed and the Command view displays a client
  prompt to indicate that the server is ready to accept debugger
  commands.  A new Source view is created, and all other active views
  display information in the context of the active session.

84  –  conn_dialog_disconnect

  Click Disconnect to disconnect the client from the currently active
  session as indicated in the Active Sessions list.

85  –  conn_dialog_test

  Click Test to test the connection between the debug client and the
  debug server.  If the connection is operating correctly, the status
  "Server is Listening" appears in the lower portion of the Connection
  dialog box.

86  –  conn_dialog_stop

  Click Stop to cause the debug server associated with the currently
  active session to be shut down.

  Note:  Once a server has been shut down, clients can no longer connect
  to it.  To restart a server, type DEBUG/SERVER at the command prompt on
  the OpenVMS system.

87  –  conn_dialog_options

  Click Options in the Server Connection dialog to display the Server
  Options dialog for the currently selected session as indicated by the
  Active Sessions list in the Server Connection dialog.  The Server
  Options dialog lets you select the connection protocol, and the maximum
  number of clients that are allowed to connect to a server.

  Once a session has been established, you cannot change the connection
  protocol.  If you are the first client (the primary client) to connect
  to a server, you can control the maximum number of secondary clients
  that are allowed to connect to the server.

88  –  c_s_primary_client

  The primary client is the first client to connect to the server.  The
  primary client uses the Server Options dialog to control whether or not
  any secondary clients can connect to the server.

89  –  c_s_secondary_client

  A secondary client is an additional client that has connected to the
  same server.  Each clients that is connected to a session can enter
  debugger commands in the context of that session.  The debugger display
  of each client connected to that session is updated reflect the current
  context of the session.

  Whether or not secondary clients are allowed is controlled by the
  primary client in the Server Options dialog.

90  –  conn_dialog_connections

  Use the Connection [local] list to specify the identification string of
  the debug server with which you want to establish a session.  Type or
  select the identification string in the New Connection box.  The New
  Connection list contains the last 10 connections that you have made and
  provides a convenient way to reconnect to a server from which you
  previously disconnected and left running.  Note that the presence of a
  connection path in the list does not guarantee that the server is still
  available

  The most simple connection string contains the name of the OpenVMS node
  followed by the port number within square brackets.  For example:
    NODNAM[4111]
  Other examples of valid connection strings:

    ncacn_ip_tcp:16.32.16.138[4111]
    16.32.16.138
    nodnam.bld.dec.com
    nodnam.bld.dec.com[4112]
    ncacn_dnet_nsp:19.10[RPC2BE08EF00001]

91  –  conn_dialog_active_sessions

  The Active Sessions list contains the sessions (connections to debug
  servers) that this client has already established.  The session at the
  top of the list is the currently active session.  All debugger views
  reflect the context of the program being debugged on the currently
  active session.

  You can switch between active sessions by selecting a session from the
  Active Sessions list.  The Source view for that session is activated
  and all other debugger views are updated to reflect the program context
  of that session.

  All buttons on the Server Connection dialog, including Disconnect, Stop
  Server, Test and Properties as well as the status section of the Server
  Connection dialog are related to and act upon the currently active
  session.

92  –  conn_dialog_cancel

  Click Cancel to dismiss the Server Connection dialog.

93  –  interfaces

  The debugger has the following user-interface options to accommodate
  different needs and debugging styles:

   -  The debugger has a DECwindows Motif interface for workstations.
      The default DECwindows Motif interface provides the basic debugging
      and convenience features that you will probably need most of the
      time.

   -  The debugger has a command interface for character-cell terminals
      and workstations.  In addition to general-purpose debugging
      features, the command interface provides special features not
      available through the default DECwindows Motif interface.

   -  The DECwindows Motif interface is layered on the command interface
      and has a command-entry prompt (in the command view of the main
      window).  From the DECwindows Motif interface, you can enter
      debugger commands for the following purposes:

       +  As an alternative to using the DECwindows Motif interface for
          certain operations

       +  To do tasks not available through the DECwindows Motif
          interface

   -  You can customize the DECwindows Motif interface with many of the
      special features of the command interface by modifying the push
      buttons in the push-button view (and their associated debugger
      commands) or by adding new push buttons.

94  –  windows_menus

  By default, the debugger starts up in the main window, which includes a
  source view, a push-button view, and a command view.

  When you start the debugger with the command DEBUG/KEEP from DCL level,
  the source view is initially empty.  You can then bring a program under
  debugger control.

95  –  cmd_entry

  The debugger's DECwindows Motif interface is layered on the command
  interface.  The command-entry prompt (DBG>), located in the command
  view, lets you enter debugger commands for the following purposes:

   -  As an alternative to using the DECwindows Motif interface for
      certain operations

   -  To do debugging tasks not available through the DECwindows Motif
      interface

  When you use the DECwindows Motif interface, the debugger translates
  your input into debugger commands.  These commands are echoed in the
  command view, at the prompt, so that you can correlate your input with
  the corresponding command line that the debugger processes.  Echoed
  commands are visually indistinguishable from commands that you enter
  explicitly.

  In addition to entering debugger commands interactively at the prompt,
  you can also enter them in debugger initialization files and command
  files for execution under the DECwindows Motif environment.

96  –  disabled_vms_cmds

  The following table lists the debugger commands that are not available
  in the debugger's DECwindows Motif interface.  Many of them are
  relevant only to the command interface's screen mode.

   ATTACH             SELECT
   CANCEL MODE        (SET,SHOW) ABORT_KEY
   CANCEL WINDOW      (SET,SHOW) KEY
   DEFINE/KEY         (SET,SHOW) MARGINS
   DELETE/KEY         SET MODE [NO]KEYPAD
   DISPLAY            SET MODE [NO]SCREEN
   EXAMINE/SOURCE     SET MODE [NO]SCROLL
   EXPAND             SET OUTPUT [NO]TERMINAL
   EXTRACT            (SET,SHOW) TERMINAL
   HELP               (SET,SHOW) WINDOW
   MOVE               (SHOW,CANCEL) DISPLAY
   SAVE               SHOW SELECT
   SCROLL             SPAWN

  The debugger issues an error message if you try to enter any of these
  disabled commands at the command-entry prompt, or when the debugger
  executes a command procedure containing any of these commands.

97  –  language_support

  On VAX processors, you can use the debugger with programs written in
  any of the following source languages:

      Ada       BASIC      BLISS      C
      C++       COBOL      DIBOL      Fortran
      MACRO-32  Pascal     PL/I       RPG II
      SCAN

  On Alpha processors, you can use the debugger with programs written in
  any of the following source languages:

      Ada       BASIC      BLISS      C
      C++       COBOL      Fortran    MACRO-32
      MACRO-64  Pascal     PL/I

  On I64 processors, you can use the debugger with programs written in
  any of the following source languages:

      Assembler (IAS)       BASIC      BLISS      C
      C++                   COBOL      Fortran    MACRO-32
      IMACRO                Pascal

  The debugger recognizes the syntax, data types, operators, expressions,
  scoping rules, and other constructs of a supported language.

  For more information about debugger support for a particular language:

  1.  Choose On Commands from the Help menu in a debugger window.

  2.  Choose Language_Support from the list of Additional Topics.

  3.  Choose the language name from the list of Additional Topics.

98  –  trademarks

  Confidential computer software.  Valid license from VSI required for
  possession, use or copying.  Consistent with FAR 12.211 and 12.212,
  Commercial Computer Software, Computer Software Documentation, and
  Technical Data for Commercial Items are licensed to the U.S.
  Government under vendor's standard commercial license.

  The information contained herein is subject to change without notice.
  The only warranties for VSI products and services are set forth in the
  express warranty statements accompanying such products and services.
  Nothing herein should be construed as constituting an additional
  warranty.  VSI shall not be liable for technical or editorial errors or
  omissions contained herein.

  Intel® and Itanium® are trademarks or registered trademarks of Intel
  Corporation or its subsidiaries in the United States and other
  countries.

99  –  compile

  To bring a program under debugger control and take full advantage of
  symbolic debugging, you must first compile and link the program as
  explained here.

  You can use the debugger with programs written in any of the source
  languages listed in the topic Debugger Support for Languages.  The
  following example shows how to compile and link a C program named
  EIGHTQUEENS before using the debugger.  The compiler and linker are
  invoked from DCL level ($).  The program's source code is in the file
  EIGHTQUEENS.C.

  On VAX systems, you explicitly identify linker options files in your
  LINK command:

    $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS
    $ LINK/DEBUG EIGHTQUEENS,OPTIONS_FILE/OPTIONS

  On Alpha and I64 systems, you do not identify linker options files:

    $ CC/DEBUG/NOOPTIMIZE EIGHTQUEENS
    $ LINK/DEBUG EIGHTQUEENS

  The /DEBUG and /NOOPTIMIZE qualifiers are compiler command defaults for
  some languages.  These qualifiers are used in the example for emphasis.
  (For more information about compiling and linking that is specific to a
  particular language, see the documentation furnished with that
  language.)

  The /DEBUG qualifier on the compiler command (CC in this case) directs
  the compiler to write the symbol information associated with
  EIGHTQUEENS.C into the object module, EIGHTQUEENS.OBJ, in addition to
  the code and data for the program.  This symbol information lets you
  use the names of variables, routines, and other symbols declared in
  EIGHTQUEENS.C when using the debugger.  If your program's source code
  is in several files, you must compile each file whose symbols you want
  to reference with the /DEBUG qualifier.

  Some compilers optimize the object code to reduce the size of the
  program or to make it run faster.  In such cases you should compile
  your program with the /NOOPTIMIZE command qualifier (or equivalent)
  when preparing for debugging.  Otherwise, the contents of some program
  locations might be inconsistent with what you would expect from viewing
  the source code.  For example, some optimization techniques eliminate
  certain variables so that you no longer have access to them while
  debugging.  (After the program has been debugged, you will probably
  want to recompile it without the /NOOPTIMIZE qualifier to take
  advantage of optimization.)

  The /DEBUG qualifier on the LINK command directs the linker to include
  all symbol information that is contained in EIGHTQUEENS.OBJ in the
  executable image.  The qualifier also causes the image activator to
  start the debugger at run time if you start the debugger by running a
  program, using the following DCL command syntax:

    $ DEBUG/KEEP

  If your program has several object modules, you need to specify those
  modules in the LINK command (for most languages).

  On VAX processors, the /OPTIONS qualifier indicates that OPTIONS_FILE
  is a linker options file.  In the OpenVMS VAX example, the file
  specifies a run-time library to be linked with the program.

  Even if you compile and link an image with the /DEBUG command
  qualifier, you can execute that image normally without it being under
  debugger control.  To do so, use the /NODEBUG qualifier on the DCL RUN
  command.  For example:

    $ RUN/NODEBUG EIGHTQUEENS

  This is convenient for checking your program after you think it is
  error free.  Note that the data required by the debugger occupies space
  within the executable image.  So, when you think your program is
  correct, you might want to link your program again without the /DEBUG
  qualifier.  This creates an image with only traceback data in the debug
  symbol table, which uses less disk space.

  On Alpha and I64 systems, you can debug programs that have been linked
  with the /DSF qualifier (and therefore have a separate debug symbol
  file).  The /DSF qualifer to the LINK command directs the linker to
  create a separate .DSF file to contain the symbol information.  This
  allows more flexible debugging options.  Debugging such a program
  requires the following:

  1.  The name of the .DSF file must match the name of the .EXE file
      being debugged.

  2.  You must define DBG$IMAGE_DSF_PATH to point to the directory that
      contains the .DSF file.

  For example:

     $ CC/DEBUG/NOOPTIMIZE TESTPROGRAM
     $ LINK/DSF=TESTDISK:[TESTDIR]TESTPROGRAM.DSF TESTPROGRAM
     $ DEFINE DBG$IMAGE_DSF_PATH TESTDISK:[TESTDIR]
     $ DEBUG/KEEP TESTPROGRAM

100  –  stop

  To interrupt program execution during a debugging session, click on the
  Stop push button on the push-button view in the main window.  This is
  useful if, for example, the program is in an infinite loop.

  To abort a debugger operation in progress, click on Stop.  This is
  useful if, for example, the debugger is displaying a long stream of
  data.

  Clicking on Stop does not end the debugging session.  Clicking on Stop
  when the program is not running or when the debugger is not doing an
  operation has no effect.

101  –  exit

  To end a debugging session and exit the debugger, choose Exit Debug?
  from the File menu on the main window.  This invokes a Confirm Exit
  dialog box to verify that you wish to exit the debugger.  In the kept
  debugger, clicking on Yes returns control to system level.  In
  client-server mode, allows you to exit the client, the server, or both.

  To rerun your program from the current debugging session, see the
  Rerunning the Same Program topic.

  To run another program from the current debugging session, see the
  Bringing a Program Under Debugger Control topic.

102  –  src_display

  The debugger displays the source code of your program in the source
  view of the main window.

  Whenever execution is suspended (for example, at a breakpoint), the
  debugger updates the source view, which displays the code surrounding
  the point at which execution is paused.  The current-location pointer,
  to the left of the source code, marks the line whose code will execute
  next.  (A source line corresponds to one or more programming language
  statements, depending on the language and coding style.)

  By default, the debugger displays compiler-generated line numbers to
  the left of the source code.  These numbers help you identify
  breakpoints that are listed in the breakpoint view.  You can choose not
  to display line numbers so that more of the source code can show in the
  window.  To hide or display line numbers, choose Show Line Numbers from
  the File menu on the main window.

  The Call Stack menu, at the bottom right of the source window, shows
  the name of the routine whose source code is displayed.

  The current-location pointer is normally filled in.  It is cleared if
  the displayed code is not that of the routine in which execution is
  paused (see the Making Source Code Available for Display and the
  Setting the Current Scope Relative to the Call Stack topics).

  You can use the scroll bars to show more of the source code.  However,
  you can scroll vertically through only one module of your program at a
  time.  (A module corresponds generally to a compilation unit.  With
  many programming languages, a module corresponds to the contents of a
  source file.  With some languages, such as Ada, a source file might
  contain one or more modules.)

  The Displaying Source Code in Another Module topic explains how to
  display source code for other parts of your program so that you can set
  breakpoints in various modules, and so on.

  The Making Source Code Available for Display topic explains what to do
  if the debugger cannot find source code for display.

  The Setting the Current Scope Relative to the Call Stack topic explains
  how to display source code for routines that are currently active on
  the call stack.

  After navigating through the source view, you can redisplay the
  location at which execution is paused by clicking on the Call Stack
  menu.

  If your program was optimized during compilation, the source code
  displayed might not reflect the actual contents of some program
  locations (see the Compiling and Linking Your Program for Debugging
  topic).

103  –  src_display_module

  To display source code in another module:

  1.  Choose Browse Source from the File menu on the main window.  From
      the submenu, select All to list all modules, select Symbolic to
      list only those modules for which symbolic information is
      available.  The Browse Source dialog box appears, listing your
      executable image, which is highlighted, and all the shareable
      images linked with it (for example, DEBUG and LIBRTL).  If the name
      of an image is dimmed, no symbolic information is available for
      that image.

  2.  Double click on the name of your executable image.  The names of
      the modules in that image are displayed (indented) under the image
      name.

  3.  Click on the name of the module whose source code you want to
      display.  The Display Source button is now highlighted.

  4.  Click on Display Source.  The source view now displays that
      module's source code.

104  –  src_display_nosrc

  In certain cases, the debugger cannot display source code.  Possible
  causes are:

   -  Execution might be paused within a module of your program that was
      compiled without the debug option.

   -  Execution might be paused within a system or library routine for
      which no symbolic information is intended to be available.  In such
      cases you can quickly return execution to the calling routine by
      clicking one or more times on the Step-Return push button on the
      push-button view of the main window.

   -  The source file might have been moved to a different directory
      after it was compiled.  The Specifying the Location of Source Files
      topic explains how to tell the debugger where to look for source
      files.

  If the debugger cannot find source code for display, it tries to
  display the source code for the next routine down on the call stack for
  which source code is available.  If the debugger can display source
  code for such a routine, the current-location pointer is cleared and
  marks the source line to which execution returns in the calling
  routine.

105  –  src_display_srcfile

  Information about the characteristics and the location of source files
  is embedded in the debug symbol table of your program.  If a source
  file has been moved to a different directory since compile time, the
  debugger might not find the file.  To direct the debugger to your
  source files, use the SET SOURCE command at the command-entry prompt.

106  –  execute

  The Additional Topics explain techniques for executing your program.

107  –  exec_paused

  To determine where execution is currently paused within your program:

  1.  If the current-location pointer is not visible in the source view,
      click on the Call Stack menu of that window to display the pointer.

  2.  Look at the current-location pointer:

       -  If the pointer is filled in, it marks the source line whose
          code will execute next.  The Call Stack menu always shows the
          routine at level 0 (where execution is paused) when the pointer
          is filled in.

       -  If the pointer is cleared, the source code displayed is that of
          a calling routine, and the pointer marks the source line to
          which execution returns in that routine as follows:

           +  If the Call Stack menu shows level 0, source code is not
              available for display for the routine in which execution is
              paused.

           +  If the Call Stack menu shows a level other than 0, you are
              displaying the source code for a calling routine.

  To list the sequence of routine calls that are currently active on the
  call stack, click on the Call Stack menu.  Level 0 denotes the routine
  in which execution is paused, level 1 denotes the calling routine, and
  so on.

108  –  start_exec

  To start program execution or resume execution from the current
  location, click on the Go push button on the push-button view of the
  main window.

  Letting your program run freely without debugger intervention is useful
  in situations such as the following:

   -  To test for an infinite loop.  In this case, you start execution;
      then, if your program does not terminate and you suspect that it is
      looping, click on the Stop push button.  The source view will show
      where you interrupted program execution, and the Call Stack menu
      will identify the sequence of routine calls at that point.

   -  To execute your program directly to a particular location.  In this
      case, you first set a breakpoint at the location and then start
      execution.

  Once started, program execution continues until one of the following
  events occurs:

   -  The program completes execution

   -  A breakpoint is reached (including a conditional breakpoint whose
      condition is true)

   -  A watchpoint is triggered

   -  An exception is signaled

   -  You click on the Stop push button in the push-button view on the
      main window.

  Whenever the debugger suspends execution of the program, the source
  view is updated and the current-location pointer marks the line whose
  code will execute next.

109  –  step_one_line

  To execute one source line of your program, click on the Step push
  button on the push-button view of the main window.  This debugging
  technique (called stepping) is one of the most commonly used.

  After the line executes, the source view is updated and the
  current-location pointer marks the line whose code will execute next.

  Note the following points about source lines and the stepping behavior:

   -  A source line can consist of one or more programming language
      elements, depending on the language and coding style used.

   -  When you click on the Step push button, the debugger executes one
      executable line and suspends execution at the start of the next
      executable line, by skipping over any intervening nonexecutable
      lines.

   -  Executable lines are those for which instructions were generated by
      the compiler (for example, lines with routine call or assignment
      statements).  Executable lines have a toggle button to their left
      in the source view.

   -  Examples of nonexecutable lines are comment lines or lines with
      variable declarations without value assignments.  Nonexecutable
      lines do not have a toggle button to their left in the source view.

  Keep in mind that if you optimized your code at compilation time, the
  source code displayed might not reflect the code that is actually
  executing.

  <here>

110  –  step_in

  When program execution is paused at a routine call statement, clicking
  on the Step push button typically executes the called routine in one
  step (depending on the coding style used), and the debugger suspends
  execution at the next source line in the calling routine (assuming no
  breakpoint was set within the called routine).  This lets you step
  through the code quickly without having to trace execution through any
  called routines (some of which might be system or library routines).
  This is called stepping over called routines.

  To step into a called routine so that you can execute it one line at a
  time:

  1.  Suspend execution at the routine call statement, for example, by
      setting a breakpoint (see the Suspending Execution with Breakpoints
      topic) and then clicking on the Go push button on the push-button
      view of the main window.

  2.  When execution is paused at the call statement, click on the
      Step-In push button on the push-button view of the main window.
      This moves execution just past the start of the called routine.

  Once execution is within the called routine, use the Step push button
  to execute the routine line by line.

  Clicking on the Step-In push button when execution is not paused at a
  routine call statement is the same as clicking on the Step push button.

111  –  step_return

  When execution is suspended within a called routine, you can execute
  your program directly to the end of that routine by clicking on the
  Step-Return push button on the push-button view of the main window.

  The debugger suspends execution just before the routine's return
  instruction executes.  At that point, the routine's call frame has not
  been deleted from the call stack, so you can still get the values of
  variables local to that routine, and so on.

  The Step-Return push button is particularly useful if you have
  inadvertently stepped into a system or library routine.

112  –  break

  A breakpoint is a location in your program at which you want execution
  to stop so that you can check the current value of a variable, step
  into a routine, and so on.

  When using the debugger's DECwindows Motif interface, you can set
  breakpoints on:

   -  Specific source lines

   -  Specific routines (functions, subprograms, and so on)

   -  Specific instructions (displayed in the instruction view)

   -  Exceptions signaled during the execution of your program

  The debugger provides two ways to qualify breakpoints:

   -  You can set a conditional breakpoint.  It triggers only when a
      specified relational expression is evaluated as true.

   -  You can set an action breakpoint.  It executes one or more
      specified system-specific commands when the breakpoint triggers.

  You can set a breakpoint that is both a conditional and action
  breakpoint.

113  –  break_srclin

  You can set a breakpoint on any source line that has a toggle button to
  its left in the source view.  These are the lines for which the
  compiler has generated executable code (routine declarations,
  assignment statements, and so on).

  To set a breakpoint on a source line:

  1.  Find the source line on which you want to set a breakpoint.

  2.  Click on the toggle button to the left of that line.  (The
      breakpoint is set when the toggle button is filled in.) The
      breakpoint is set at the start of the source line--that is, on the
      first machine-code instruction associated with that line.

114  –  break_routine

  Setting a breakpoint on a routine lets you move execution directly to
  the routine and inspect the local environment.

  To set a breakpoint on a routine:

  1.  Choose Browse Source from the File menu on the main window.  From
      the submenu, select All to list all modules, select Symbolic to
      list only those modules for which symbolic information is
      available.  The Browse Source dialog box appears listing your
      executable image, which is highlighted, and all the shareable
      images linked with it (for example, DEBUG and LIBRTL).  If the name
      of an image is dimmed, no symbolic information is available for
      that image.

  2.  Double click on the name of your executable image.  The names of
      the modules in that image are displayed (indented) under the image
      name.

  3.  Double click on the name of the module whose source code you want
      to display.  The names of the routines in that module are displayed
      in the Routine column.

  4.  Do one of the following:

       -  Double-click on the name of the routine on which you want to
          set a breakpoint.

       -  Click on the name of the routine and then on the Set Breakpoint
          button.

      Either of these actions sets a breakpoint at the start of the
      routine (directly after any prolog code).  In the source view, the
      toggle button to the left of the source line that contains the
      start of the routine is now filled in, confirming that the
      breakpoint is set.  (If the breakpoint view is open, the breakpoint
      will appear in the breakpoint list.  If the instruction window is
      open, the breakpoint will also display for the corresponding
      instruction.)

115  –  break_instruction

  You can set a breakpoint on any instruction that has a toggle button to
  its left in the annotation area.  These are the lines for which the
  compiler has generated executable code (routine declarations,
  assignment statements, and so on).

  To set a breakpoint on an instruction:

  1.  Find the instruction on which you want to set a breakpoint.

  2.  Click on the toggle button to the left of that line.  (The
      breakpoint is set when the toggle button is filled in.)

116  –  break_exception

  An exception breakpoint suspends execution when an exception is
  signaled and before any exception handler declared by your program
  executes.  This allows you to step into the exception handler (if one
  is available) to check the flow of control.

  To set an exception breakpoint, choose On Exception from the Break
  menu.  The exception breakpoint triggers whenever any exception is
  signaled.

117  –  break_identify

  There are two ways to determine which breakpoints are currently set:

   -  Scroll through your source or instruction code and note the lines
      whose breakpoint button is filled in.  This method can be time
      consuming and also does not show which breakpoints were set and
      then deactivated.

   -  Choose Views...  from the Options menu on the main or optional view
      window.  When the Views dialog box appears, toggle breakpoint view.
      Within the breakpoint view display, breakpoints are listed in the
      Identification column of the view, including the module name and
      line number for each breakpoint.  A filled-in button in the State
      column indicates that the breakpoint is set and active.  A cleared
      button indicates that the breakpoint is deactivated.  (The
      breakpoint view does not provide information on breakpoints that
      have not been set or that have been deleted.)

118  –  break_activ

  After you set a breakpoint, you can deactivate it, activate it, or
  cancel it.

  Deactivating a breakpoint causes the debugger to ignore it during
  program execution.  However, the debugger keeps the breakpoint listed
  in the breakpoint view so that you can activate it at a later time, for
  example, when you rerun the program.  Note the following points:

   -  To deactivate a specific breakpoint, clear the button for that
      breakpoint in the source view, the instruction code display, or in
      the breakpoint view.

      In the breakpoint view, you can also choose Toggle from the Break
      menu, if the breakpoint is currently activated.

   -  To deactivate all breakpoints, choose Deactivate All from the Break
      menu on the main, instruction, or optional view window.

  Activating a breakpoint causes it to take effect during program
  execution:

   -  To activate a breakpoint, click on the button for that breakpoint
      in the source view, instruction code display, or in the breakpoint
      view.

      In the breakpoint view, you can also choose Toggle from the Break
      menu, if the breakpoint is currently deactivated.

   -  To activate all breakpoints, choose Activate All from the Break
      menu on the main, instruction, or optional view window.

  Canceling a breakpoint causes all information about the breakpoint to
  be lost.  Once you cancel a breakpoint, you cannot later reactivate it,
  but must again explicitly set the breakpoint.  Note the following
  points:

   -  To cancel a specific breakpoint, choose Cancel from the Break menu
      on the optional view window.

   -  To cancel all breakpoints, choose Cancel All from the Break menu on
      the main, instruction, or optional view window.

119  –  break_cond

  A conditional breakpoint suspends execution only when a specified
  expression is evaluated as true.  For example, you can specify that a
  breakpoint take effect when the value of a variable in your program is
  4.  The breakpoint is ignored if the value is other than 4.

  The debugger evaluates the conditional expression when the breakpoint
  triggers during execution of your program.

  The following procedure sets a conditional breakpoint:

  1.  Display the source or instruction line on which you want to set the
      conditional breakpoint.

  2.  Display the Set/Modify Breakpoint dialog box in one of the
      following ways:

       -  Press Ctrl/MB1 on the button to the left of a source line, an
          instruction line, or a breakpoint entry in the breakpoint view.
          This causes the Set/Modify Breakpoint dialog box to display,
          showing the line you selected in the Location:  field.

       -  Choose the Set (main or instruction window) or Set/Modify
          (optional view window) menu item from the Break menu.  When the
          Set/Modify dialog box appears, enter the line in the Location:
          field.

  3.  Enter a relational expression in the Condition:  field of the
      dialog box.  The expression must be valid in the source language.
      For example, a[3] == 0 is a valid relational expression in the C
      language.

  4.  Click on OK.  The conditional breakpoint is now set.  The debugger
      indicates that a breakpoint is conditional by changing the shape of
      the breakpoint's button from a square to a diamond.

  The following procedure modifies a conditional breakpoint; that is, it
  can be used to change the condition associated with an existing
  conditional breakpoint, or to change an unqualified breakpoint into a
  conditional breakpoint:

  1.  Do one of the following:

       -  Press Ctrl/MB1 on the button to the left of a source line, an
          instruction code line, or a breakpoint entry in the breakpoint
          view.

       -  Click on a breakpoint entry in the breakpoint view, and choose
          the Set/Modify item from the Break Menu.

  2.  Follow steps 3 and 4 of the previous procedure, as appropriate.

120  –  break_action

  When an action breakpoint triggers, the debugger suspends execution and
  then executes a specified list of commands.

  The following procedure sets an action breakpoint:

  1.  Display the source or instruction line on which you want to set the
      action breakpoint.

  2.  Display the Set/Modify Breakpoint dialog box in one of the
      following ways:

       -  Press Ctrl/MB1 on the button to the left of a source line, an
          instruction line, or a breakpoint entry in the breakpoint view.
          This causes the Set/Modify Breakpoint dialog box to display,
          showing the source line you selected in the Location:  field.

       -  Choose the Set (main window) or Set/Modify (optional view
          window) menu item from the Break menu.  When the Set/Modify
          dialog box appears, enter the source line in the Location:
          field.

  3.  Enter one or more debugger commands in the Action:  field of the
      dialog box.  For example:

        DEPOSIT x[j] = 3; STEP; EXAMINE a

  4.  Click on OK.  The action breakpoint is now set.

  The following procedure modifies an action breakpoint; that is, it can
  be used to change the command associated with an existing action
  breakpoint, or to change an unqualified breakpoint into an action
  breakpoint:

  1.  Do one of the following:

       -  Press Ctrl/MB1 on the button to the left of a source line, an
          instruction code line, or a breakpoint entry in the breakpoint
          view.

       -  Click on a breakpoint entry in the breakpoint view, and choose
          the Set/Modify item from the Break Menu.

  2.  Follow steps 3 and 4 of the previous procedure, as appropriate.

121  –  exam_deposit

  The Additional Topics explain how to do various operations to display
  and modify the values of variables declared in your program.

122  –  select

  Use the following techniques to select variable names from windows for
  the operations described in the Additional Topics.

  When selecting names, follow the syntax of the source programming
  language:

   -  To specify a scalar (nonaggregate) variable, such as an integer,
      real, Boolean, or enumeration type, select the variable's name.

   -  To specify an entire aggregate, such as array or structure
      (record), select the variable's name.

   -  To specify a single element of an aggregate variable, select the
      entity using the language syntax.  For example:

       +  The string arr2[7] specifies element 7 of array arr2 in the C
          language.

       +  The string employee.address specifies the component address of
          record (structure) employee in the Pascal language.

   -  To specify the object designated by a pointer variable, select the
      entity following the language syntax.  For example, the string
      *int_point specifies the object designated by pointer int_point in
      the C language.

  Select character strings from windows as follows:

   -  In any window, to select a string delimited by blank spaces, use
      the standard DECwindows Motif word-selection technique:  position
      the mouse pointer on that string and then double click MB1.

   -  In any window, to select an arbitrary character string, use the
      standard DECwindows Motif text-selection technique:  position the
      mouse pointer on the first character, press and hold MB1 while
      dragging the mouse pointer over the string, and then release MB1.

   -  In the debugger source view, you also have the option of using
      language-sensitive text selection.  To select a string delimited by
      language-dependent identifier boundaries, position the mouse
      pointer on that string and press Ctrl/MB1.

      For example, suppose the source view contains the character string
      arr2[m], then:

       +  To select arr2, position the mouse pointer on arr2 and press
          Ctrl/MB1.

       +  To select m, position the mouse pointer on m and press
          Ctrl/MB1.

      You can change the key sequence for language-sensitive text
      selection as explained in the Defining the Key Sequence for
      Language-Sensitive Text Selection topic.

123  –  examine

  You can display the current value of a variable or expression in the
  following ways:

   -  Using the Examine push button in the push-button view

   -  Using the Examine dialog box, accessed through the Command menu on
      the main window

  The Examine push button displays a current value most quickly, but the
  Examine dialog box allows you to request typecasting or an altered
  output radix in the displayed result.

  To display the current value using the Examine push button:

  1.  Find and select the variable name or expression in a window.

  2.  Click on the Examine push button on the push-button view of the
      main window.  The debugger displays the variable or expression and
      its current value in the command view.  Note that this is the value
      of the variable or expression in the current scope, which might not
      be the same as the source location where you selected the variable
      name or expression.

  To display the current value using the Examine dialog box, perform the
  following steps:

  1.  Do one of the following:

       -  Find and select the variable name or expression symbols in a
          window, and choose the Examine menu item from the Commands menu
          on the main window.  The Examine dialog box appears, with the
          name you selected in the Variable/Expression field.

       -  Choose the Examine menu item from the Commands menu on the main
          window.  The Examine dialog box appears.  Enter the name of the
          variable or symbols of the expression you are examining in the
          Variable/Expression field of the dialog box.

  2.  If you are changing the output type, pull down the menu in the
      Typecast entry box and click on the desired data type.

  3.  If you are changing the output radix, pull down the menu in the
      Output Radix entry box and click on the desired radix.

  4.  Click on OK.

  Your echoed command and the current value appear in the command view.

124  –  monitor

  When you monitor a variable or expression, the debugger displays the
  value in the monitor view and checks and updates the displayed value
  whenever the debugger regains control from your program (for example,
  after a step or at a breakpoint).

  To monitor a variable or expression:

  1.  Choose the Views...  menu item in the Options menu on the main
      window.  The Views dialog box appears.

  2.  Click on monitor view within the dialog box.  The monitor view
      appears in the optional view window.

  3.  Find and select the variable name or expression in a window.

  4.  Click on the Monitor push button on the push-button view of the
      main window.  The debugger:

       -  Puts the selected variable name or expression, along with its
          qualifying path name, in the Monitor Expression column

       -  Puts the current value of the variable in the Value/Deposit
          column

       -  Puts a cleared button in the Watched column

125  –  monitor_aggregate

  If you select the name of an aggregate variable, such as an array or
  structure (record) and click on the Monitor push button, the debugger
  displays the word Aggregate in the Value/Deposit column of the monitor
  view.  To display the values of all elements (components) of an
  aggregate variable, double click on the variable name in the Monitor
  Expression column.  The displayed element names are indented relative
  to the parent name.  If an element is also an aggregate, you can double
  click on its name to display its elements, and so on.

  To contract an expanded display so that only the aggregate parent name
  is shown in the monitor view, double click on the name in the Monitor
  Expression column.

  If you have selected a component of an aggregate variable, and the
  component expression is itself a variable, the debugger monitors the
  component that was active when you made the selection.  For example, if
  you select the array component arr[i] and the current value of i is 9,
  the debugger monitors arr[9] even if the value of i subsequently
  changes to 10.

126  –  monitor_pointer

  If you select the name of a pointer (access) variable and click on the
  Monitor push button, the debugger displays the address of the
  referenced object in the Value/Deposit column of the monitor view.

  To monitor the value of the referenced object (to dereference the
  pointer variable), double click on the pointer name in the Monitor
  Expression column.  This adds an entry for the referenced object in the
  monitor view, which is indented under the pointer entry.  If a
  referenced object is an aggregate, you can double click on its name to
  display its elements, and so on.

  If you are debugging programs written in C or C++, you may want to add
  a new push button to the push button view, one that monitors a
  dereferenced value.  If so, you enter the following command in the
  Command field of the Customize dialog box:

         monitor *%s

  For more information, see the Adding a New Push Button and Associated
  Command help topic.

127  –  watch

  Whenever the program changes the value of a watched variable, the
  debugger suspends execution and displays the old and new values in the
  command view.

  To watch a variable (also known as setting a watchpoint on a variable),
  proceed as follows:

  1.  Monitor the variable as explained in the Monitoring a Variable
      topic.  The debugger puts a button in the Watched column of the
      monitor view whenever you monitor a variable.

  2.  Click on the button in the Watched column.  A filled-in button
      indicates that the watchpoint is set.

  To deactivate a watchpoint, clear its Watched button in the monitor
  view (by clicking on the button).  To activate a watchpoint, fill in
  its Watched button.

  The Accessing Static and Nonstatic (Automatic) Variables topic explains
  static and nonstatic (automatic) variables and how to access them.  The
  debugger deactivates a nonstatic watchpoint when execution moves out of
  (returns from) the variable's defining routine.  When a nonstatic
  variable is no longer active, its entry is dimmed in the monitor view
  and its Watched button is cleared.

  The debugger does not reactivate nonstatic watchpoints automatically if
  execution later returns to the variable's defining routine.  You must
  reactivate nonstatic watchpoints yourself.

128  –  deposit

  You can change the value of a variable in the following ways:

   -  Using the Deposit dialog box, accessed from the Commands menu on
      the main window

   -  Clicking on a monitored value within the monitor view

  To change the value of a variable using the Deposit dialog box:

  1.  Do one of the following:

       -  Find and select the variable name in a window, and choose the
          Deposit menu item from the Commands menu on the main window.
          The Deposit dialog box appears, with the name you selected in
          the Variable field.

       -  Choose the Deposit menu item from the Commands menu on the main
          window.  The Deposit dialog box appears.  Enter the name of the
          variable to which you are depositing a value in the Variable
          field of the dialog box.

  2.  Enter the value you are depositing in the Value field of the dialog
      box.

  3.  If you are changing the input radix, pull down the menu in the
      Input Radix entry box and click on the desired radix.

  4.  Click on OK.

  Your echoed command appears in the command view, indicating that the
  value is changed.

  To change the value of a monitored value within the monitor view:

  1.  Monitor the variable as explained in the Monitoring a Variable
      topic.

  2.  Click on the variable's value in the Value/Deposit column of the
      monitor view.  A small dialog box appears over that value, which
      you can now edit.

  3.  Enter the new value in the dialog box.

  4.  Click on the check mark (OK) in the dialog box.  The dialog box is
      removed and replaced by the new value, which indicates that the
      variable now has that value.  The debugger notifies you if you try
      to enter a value that is incompatible with the variable's type,
      range, and so on.

  To cancel a text entry and dismiss the dialog box, click on X (Cancel).

  You can change the value of only one component of an aggregate variable
  (such as an array or structure) at a time.  To change the value of an
  aggregate-variable component:

  1.  Display the value of the component as explained in the Monitoring
      an Aggregate (Array or Structure) Variable topic.

  2.  Follow the procedure for changing the value of a scalar variable.

129  –  variable

  In the Local Variable view, you can monitor the values of all local
  variables and parameters passed to a routine.

  The debugger displays these values, and checks and updates all
  displayed values whenever the debugger regains control from your
  program (for example, after a step or at a breakpoint).

  You cannot add or remove an entry to the local variables and parameters
  list.  The debugger automatically removes previous entries and adds new
  entries when a new routine appears at the top of the call stack.

  To monitor a local variable or parameter:

  1.  Choose the Views...  menu item in the Options menu on the main or
      optional view window.  The Views dialog box appears.

  2.  Click on the Local Variable View item in the Views dialog box.  The
      Local Variable view appears.  The debugger automatically lists all
      local variable and parameter names (in the Expression column) and
      current values (in the Value/Deposit column).

  To change the value of a monitored value within the local variable
  view:

  1.  Monitor the local variable as explained above.

  2.  Click on the variable's value in the Value/Deposit column of the
      local variable view.  A small dialog box appears over that value,
      which you can now edit.

  3.  Enter the new value in the dialog box.

  4.  Click on the check mark (OK) in the dialog box.  The dialog box is
      removed and replaced by the new value, which indicates that the
      variable now has that value.  The debugger notifies you if you try
      to enter a value that is incompatible with the variable's type,
      range, and so on.

  To cancel a text entry and dismiss the dialog box, click on X (Cancel).

  You can change the value of only one component of an aggregate variable
  (such as an array or structure) at a time.  To change the value of an
  aggregate-variable component:

  1.  Display the value of the component as explained in the Monitoring
      an Aggregate (Array or Structure) Variable topic.

  2.  Follow the procedure for changing the value of a scalar variable.

130  –  access_var

  The Additional Topics give some general considerations about accessing
  program variables while debugging.

  If your program was optimized during compilation, you might not have
  access to certain variables while debugging.  When you compile a
  program for debugging, it is best to disable optimization, if possible.

  Before you check on the value of a variable, always execute the program
  beyond the point where the variable is declared and initialized.  The
  value contained in any uninitialized variable should be considered
  invalid.

131  –  static_nonstatic_var

  NOTE:  The generic term nonstatic variable is used here to denote what
  is called an automatic variable in some languages.

  The technique for accessing a variable varies according to whether it
  is a static or nonstatic variable.

  The system differentiates between static and nonstatic variables by
  determining how they are stored.

  A static variable is associated with the same memory address throughout
  execution of the program.  You can always access a static variable.

  A nonstatic variable is allocated on the stack or in a register and has
  a value only when its defining routine or block is active.  Therefore,
  you can access a nonstatic variable only when program execution is
  paused within the scope of its defining routine or block (which
  includes any routine called by the defining routine).

  A common technique for accessing a nonstatic variable is first to set a
  breakpoint on the defining routine and then to execute the program to
  the breakpoint.

  Whenever the execution of your program makes a nonstatic variable
  inaccessible, the debugger notifies you as follows:

   -  If you try to display the value of the variable or monitor the
      variable, the debugger issues a message that the variable is not
      active or not in scope.

   -  If the variable is currently being monitored, its entry becomes
      dimmed in the monitor view.  When the entry is dimmed, the debugger
      does not check or update the variable's displayed value; also, you
      cannot change that value.  The entry is fully displayed whenever
      the variable becomes accessible again.

132  –  instruction

  The instruction view displays the decoded instruction stream of your
  program---the code that is actually executing.  This is useful if the
  program you are debugging has been optimized by the compiler so that
  the information in the source view does not exactly reflect the code
  that is executing.

  To display the instruction view, choose Views...  from the Options menu
  on the main or optional view window.  When the View Selection dialog
  box appears, toggle Instruction View.

  By default, the instruction view automatically displays the decoded
  instruction stream of the routine in which execution is currently
  paused.  The current-location pointer, to the left of the instructions,
  marks the instruction that will execute next.

  By default, the debugger displays line numbers and memory addresses to
  the left of the instructions You can choose not to display numbers or
  addresses so that more space is devoted to showing instructions.  To
  hide or display line numbers, toggle the Display Line Numbers button
  from the File menu on the instruction view.  To hide or display memory
  addresses, choose Show Instruction Addresses from the File menu on the
  instruction view.

  To copy memory addresses or instructions into a command you are
  entering at the command entry prompt, select text and choose Copy from
  the Edit menu in the instruction window.  Then, position your mouse
  pointer at the command you have entered and choose Paste from the Edit
  menu on the main window.  (You can also select instruction text to be
  used with a push button command you click in the push button view of
  the main window.)

  To set breakpoints from the instruction view, toggle the breakpoint
  button next to the instruction of interest.  The breakpoint is set in
  the source display, instruction display (if the instruction view is
  open), and breakpoint view (if the breakpoint view is open).
  Information on the breakpoint is continuously updated in the source
  view, and in the instruction view and breakpoint view if they are open.

  You can also set breakpoints and change breakpoint status by pulling
  down the Break menu from the main or optional view window.

  After navigating through the instruction view, to redisplay the
  location at which execution is paused, click on the Call Stack menu.

  To display the instruction stream of any routine on the call stack,
  choose its name from the Call Stack menu on the main window.

133  –  register

  The register view displays the current contents of all machine
  registers.

  To display the register view, choose Views...  from the Options menu,
  then click on the button for Registers.

  By default, the register view automatically displays the register
  values associated with the routine in which execution is currently
  paused.  Any values that change as your program executes are
  highlighted whenever the debugger regains control from your program.

  To display the register values associated with any routine on the call
  stack, choose its name from the Call Stack menu on the main window.

  To change the value stored in a register:

  1.  Click on the register value in the register view.  A small dialog
      box appears over the current value, which you can now edit.

  2.  Enter the new value in the dialog box.

  3.  Click on the check mark (OK) in the dialog box.  The dialog box is
      removed and replaced by the new value, which indicates that the
      register now contains that value.

  To cancel a text entry and dismiss the dialog box, click on X (Cancel).

134  –  task

  Multithread programs have multiple threads of execution within a
  process and include the following:

   -  Programs written in any language that use DECthreads or POSIX
      1003.1b services.

   -  Programs that use language-specific threads services (services
      provided directly by the language).  Currently, Ada is the only
      language with built-in threads services that the debugger supports.

  Within the debugger, the term thread or task denotes such a flow of
  control regardless of the language or implementation.  The debugger's
  threads support applies to all such programs.

  The debugger lets you display thread information and modify task
  characteristics to control thread execution, priority, state
  transitions, and so on.

  The following paragraphs summarize the multithread features of the
  debugger's DECwindows Motif interface.  For more information about the
  debugger's threads support, see the manual provided with this debugger.

  Displaying Information about Threads:

  To display information about one or more threads of your program,
  choose Views...  from the Options menu on the main or optional view
  window.  When the Views dialog box appears, click the button for
  Threads.  The Threads View dialog box is displayed.

  The thread view gives information about all currently existing
  (nonterminated) tasks of your program.  The information is updated
  whenever the debugger regains control from the program.

  The displayed information includes:

   -  The Thread ID.  The arrow in the left column marks the active
      thread, that is, the task that runs when you click on the Go or
      Step push button.

   -  The current state of the thread.  The running thread (thread in the
      RUN state) is the active thread.

   -  Whether the thread has been put on hold.

   -  The thread priority.

   -  The current substate of the thread.  The substate helps indicate
      the possible cause of a thread's state.

   -  A debugger path name for the thread object or the address of the
      thread object if the debugger cannot symbolize the thread object.

  Changing Thread Characteristics:

  To modify thread characteristics or the thread environment while
  debugging, choose one of the following items from the Threads menu on
  the optional view window:

  Action      Function
  ------      --------

  Abort       Requests that the selected thread be terminated at the
              next allowed opportunity. The exact effect depends
              on the current event facility (language dependent).
              For Ada tasks, this is equivalent to executing an
              abort statement.

  Activate    Makes the selected thread the active thread.

  Hold        Places the selected thread on hold.

  Nohold      Releases the selected thread from hold.

  Make        Makes the selected thread the visible task.
    Visible

  All ->      Uses the submenu to:
                 Abort all threads
                 Hold all threads
                 NoHold all threads

  To save these modifications for subsequent debugger sessions, choose
  Save Options from the Options menu on the main or optional view window.
  This creates a new version of the debugger resource file with the new
  definitions.

135  –  setscope

  While debugging a routine in your program, you might want to set the
  current scope to a calling routine (a routine down the stack from the
  routine in which execution is currently paused).  This enables you to:

   -  Determine where the current routine call originated

   -  Determine the value of a variable declared in a calling routine

   -  Determine the value of a variable during a particular invocation of
      a routine that is called recursively

   -  Change the value of a variable in the context of a routine call

  The Call Stack menu on the source view lists the names of the routines
  of your program that are currently active on the stack, up to the
  maximum number of lines that can be displayed on your screen.

  The numbers on the left side of the menu indicate the level of each
  routine on the stack relative to level 0, which denotes the routine in
  which execution is paused.

  To set the current scope to a particular routine on the stack, choose
  its name from the Call Stack menu.  This causes the following to occur:

   -  The Call Stack menu, when released, shows the name and relative
      level of the routine that is now the current scope.

   -  The source view shows that routine's source code.

   -  The instruction view (if displayed) shows that routine's decoded
      instructions.

   -  The register view (if displayed) shows the register values
      associated with that routine call.

   -  If the scope is set to a calling routine (call-stack level other
      than 0), the debugger clears the current-location pointer.

   -  The debugger sets the scope for symbol searches to the chosen
      routine, so that you can examine variables, and so on, in the
      context of that scope.

  When you set the scope to a calling routine, the current-location
  pointer (which is cleared) marks the source line to which execution
  will return in that routine.  Depending on the source language and
  coding style used, this might be the line that contains the call
  statement or some subsequent line.

136  –  symbol_search

  Symbol ambiguities can occur when a symbol (for example, a variable
  name X) is defined in more than one routine or other program unit.

  In most cases, the debugger resolves symbol ambiguities automatically.
  First, it uses the scope and visibility rules of the currently set
  language.  In addition, because the debugger permits you to specify
  symbols in arbitrary modules (to set breakpoints and so on), the
  debugger uses the ordering of routine calls on the call stack to
  resolve symbol ambiguities.

  In some cases, however, the debugger might respond as follows when you
  specify a symbol that is defined multiple times:

   -  It might issue a "symbol not unique" message because it is not able
      to determine the particular declaration of the symbol that you
      intended.

   -  It might reference the symbol declaration that is visible in the
      current scope, which is not the one you want.

  To resolve such problems, you must specify a scope where the debugger
  should search for the particular declaration of the symbol:

   -  If the different declarations of the symbol are within routines
      that are currently active on the call stack, use the Call Stack
      menu on the source window to reset the current scope.

   -  Otherwise, enter the appropriate command at the command-entry
      prompt (EXAMINE or MONITOR, for example), specifying a path-name
      prefix with the symbol.  For example, if the variable X is defined
      in two modules named COUNTER and SWAP, the following command uses
      the path name SWAP\X to specify the declaration of X that is in
      module SWAP:

         DBG> EXAMINE SWAP\X

137  –  starting_debugger

  To start the debugger, enter the following command from DCL level:

    $ DEBUG/KEEP

  This startup method enables you to rerun your program or run another
  program from the same debugging session without exiting the debugger.

  Additional options for starting the debugger are discussed in the
  manual provided with this debugger.  With some of these startup
  methods, you cannot rerun your program or run another program from the
  same debugging session.

138  –  custom

  You can customize the debugger's DECwindows Motif interface as follows:

   -  Define the startup configuration of the debugger windows and views

   -  Show or hide line numbers in the source view at debugger startup

   -  Modify, add, or remove push buttons and associated debugger
      commands

   -  Define the key sequence to display the dialog box for conditional
      and action breakpoints

   -  Define the key sequence to make text selection language-sensitive
      in the source view

   -  Define the character font for text displayed in specific windows
      and views

   -  Define or redefine the commands bound to individual keys on your
      computer's keypad.

  You can control the first three of these customizations interactively
  from the DECwindows Motif interface, as explained in the Additional
  Topics.  In each of these three cases, you can save the current
  settings by choosing Save Options from the Options menu on the main or
  optional view window.

  In addition, you can control all customizations by editing the debugger
  resource file (DECW$USER_DEFAULTS:VMSDEBUG.DAT).

139  –  custom_views

  To define the startup configuration of the debugger windows and views:

  1.  While using the debugger, set up the desired configuration of the
      windows and views.

  2.  Choose Save Options from the Options menu on the main or optional
      view window.  This creates a new version of the debugger resource
      file with the new settings.

  When you later start the debugger, the new configuration appears
  automatically.

  Note that adding views to the startup configuration increases the
  startup time accordingly.

  You can also define the startup window configuration by editing the
  current definition of the following resources in the VMSDEBUG.DAT
  resource file:

  DebugSource.width
  DebugSource.x
  DebugSource.height
  DebugSource.y
  DebugControl.width
  DebugControl.x
  DebugControl.height
  DebugControl.y

140  –  custom_lineno

  The source view displays source line numbers by default at debugger
  startup.  To hide (or display) line numbers at debugger startup:

  1.  While using the debugger, choose Show Line Numbers from the File
      menu on the main window.  Line numbers are displayed when a
      filled-in button appears next to that menu item, and vice versa.

  2.  Choose Save Options from the Options menu on the main or optional
      view window.  This creates a new version of the debugger resource
      file with the new settings.

  When you later start the debugger, line numbers are either displayed or
  hidden accordingly.

  You can also set the startup default for line numbers by setting the
  following resource to either True or False in the VMSDEBUG.DAT resource
  file.

  DebugSource.StartupShowSourceLineno

141  –  custom_button

  The push buttons on the push-button view are associated with debugger
  commands.  You can:

   -  Change a push button's label or the command associated with a push
      button

   -  Add a new push button and assign a command to that button

   -  Remove a push button

   -  Resequence a push button

  NOTE:  You cannot modify or remove the Stop push button.

  The Additional Topics explain how to customize push buttons
  interactively through the DECwindows Motif interface.

  To save these modifications for subsequent debugger sessions, choose
  Save Options from the Options menu on the main window or an optional
  view.  This creates a new version of the debugger resource file with
  the new definitions.

142  –  custom_button_move

  To resequence a push button:

  1.  Choose Customize Buttons...  from the Options menu on the main
      window or an optional view.  The Customize dialog box appears.

  2.  Click on the push button in the control panel of the Customize
      dialog box.

  3.  Click on Right Arrow or Left Arrow.  The push button is resequenced
      one place to the right or left in the dialog box control panel.

  4.  Click on OK.  The push button is resequenced one place to the right
      or left in the push-button view on the main window.

143  –  custom_button_mod

  To change a push button's label or the debugger command associated with
  a push button:

  1.  Choose Customize Buttons...  from the Options menu on the main
      window or an optional view.  The Customize dialog box appears.

  2.  Click on the push button in the control panel of the dialog box.

  3.  If changing the push button label, enter the new label in the Label
      field or choose a predefined icon from the Icon menu.  (If changing
      the push button label, verify that the Icon menu is set to None.)

  4.  If changing the command associated with the push button, enter the
      new command in the Command field.

      If the command is to operate on a name or language expression
      selected in a window, include %s in the command name.  For example,
      the following command displays the current value of the variable
      whose name is currently selected:

      EXAMINE %s

      If the command is to operate on a name that has a a percent sign
      (%) as the first character, specify two percent signs.

  5.  Click on Modify.  The push button is modified in the dialog box
      control panel.

  6.  Click on OK.  The push button is modified in the push-button view
      on the main window.

144  –  custom_button_add

  To add a new push button to the push-button view and assign a debugger
  command to that push button:

  1.  Choose Customize Buttons...  from the Options menu on the main
      window.  The Customize dialog box appears.

  2.  Enter the debugger command for that push button in the Command
      field.

  3.  Enter a label for that push button in the Label field or choose a
      predefined icon from the Icon menu.

  4.  Click on Add.  The push button is added to the control panel within
      the dialog box.

  5.  Click on OK.  The push button is added to the push-button view in
      the main window.

  If you are debugging programs written in C or C++, you may want to add
  a new push button to the push button view, one that monitors a
  dereferenced value.  If so, you enter the following command in the
  Command field of the Customize dialog box:

         monitor *%s

145  –  custom_button_remove

  To remove a push button:

  1.  Choose Customize Buttons...  from the Options menu on the main
      window.  The Customize dialog box appears

  2.  Click on the push button in the control panel of the Customize
      dialog box.

  3.  Click on Remove.  The push button is removed from the control panel
      within the dialog box.

  4.  Click on OK.  The push button is removed from the push button view
      in the main window.

146  –  custom_resource

  The debugger is installed on your system with a debugger resource file
  DECW$SYSTEM_DEFAULTS:VMSDEBUG.DAT that defines the startup default
  settings for the following debugger user-interface options:

   -  Configuration of windows and views

   -  Whether to show or hide line numbers in the source view

   -  Button names and associated debugger commands

   -  Key sequence to display the dialog box for conditional and action
      breakpoints

   -  Key sequence for language-sensitive text selection in the source
      view

   -  Character fonts for text in the windows and views

   -  Key bindings for commands associated with the computer keypad

   -  Colors for elements of the source and instruction views and Editor

   -  Command echo

   -  Title Bar label format

  A listing of the system default debugger resource file with explanatory
  comments is contained in the manual provided with this debugger.

  You can customize the following features from the DECwindows Motif
  interface:

   -  Configuration of windows and views

   -  Whether to show or hide line numbers in the source view

   -  Push button names and associated debugger commands

  You can redefine the rest of the customizable parameters by editing
  your local debugger resource file.

  See Additional Topics for information about changing and saving the
  debugger user-interface options, and restoring system default debugger
  user-interface options.

147  –  custom_key_breakdb

  By default, the key sequence for displaying the dialog box for
  conditional and action breakpoints is Ctrl/MB1.  To define another key
  sequence, edit the current definition of the following resource in the
  VMSDEBUG.DAT resource file:

  DebugSource.ModifyBreakpointToggleSequence

148  –  custom_key_select

  By default, the key sequence for language-sensitive text selection in
  the source view is Ctrl/MB1.  To define another key sequence, edit the
  current definition of the following resource in the VMSDEBUG.DAT
  resource file:

  DebugSource.IdentifierSelectionSequence

  To avoid conflict with standard DECwindows Motif word selection, do not
  use a double-click combination, such as Ctrl<Btn1Down>(2).

149  –  custom_font

  To define another font for the text displayed in various debugger
  windows and views, edit the current definition of the following
  resources in the VMSDEBUG.DAT resource file:
  DebugDefault.Font
  DebugSource.Font
  DebugInstruction.Font
  DebugMessage.Font
  DebugOptions.Font

150  –  custom_key_binding

  The following commands have been mapped to individual keys on your
  computer's keypad:

  Command                 Keypad Label            Key Designation
  --------                ------------            ---------------

  Step/Line                 KP0                    <Key>0xFFB0
  Examine                   KP1                    <Key>0xFFB1
  Go                        KPcomma                <Key>0xFFAC
  Step/Into                 GOLD-KP0               <Key>0xFF91,<Key>0xFFB0
  Step/Over                 BLUE-KP0               <Key>0xFF94,<Key>0xFFB0
  Examine^                  GOLD-KP1               <Key>0xFF91,<Key>0xFFB1
  Show Calls                KP5                    <Key>0xFFB5
  Show Calls 3              GOLD-KP5               <Key>0xFF91,<Key>0xFFB5
  Activate                  ENTER                  <Key>0xFF8D

  To bind a different command to a key that is already associated with a
  command, edit the current definition of the following resources in the
  VMSDEBUG.DAT resource file:
  DebugSource.*DXmCSText.translations:#override\n\
     <Key>0xFFB0: EnterCmdOnCmdLine("step\line") \n\
     <Key>0xFFB1: EnterCmdOnCmdLine("examine") \n\
     <Key>0xFFAC: EnterCmdOnCmdLine("go") \n\
     <Key>0xFF91,<Key>0xFFB0: EnterCmdOnCmdLine("step\into") \n\
     <Key>0xFF94,<Key>0xFFB0: EnterCmdOnCmdLine("step\over") \n\
     <Key>0xFF91,<Key>0xFFB1: EnterCmdOnCmdLine("examine^") \n\
     <Key>0xFFB5: EnterCmdOnCmdLine("show calls") \n\
     <Key>0xFF91,<Key>0xFFB5: EnterCmdOnCmdLine("show calls 3") \n\
     <Key>0xFF8D: activate()\n\

  To bind a command to a key that is not currently associated with a
  command, refer to the Keysym Encoding chapter of the "X and Motif Quick
  Reference Guide" for key designations.

151  –  decwindows_basics

  Information about using DECwindows Motif, such as how to use windows,
  dialog boxes, and scroll bars, is available from Session Manager help.
  To get Session Manager help:

  1.  Move the mouse pointer to the Session Manager icon (the icon that
      contains a small key in it) in the Icon Box.

  2.  Press mouse button 1 (MB1) twice to display the Session Manager
      window.

  3.  Move the mouse pointer to the Help menu; press and hold MB1 to pull
      down this menu.

  4.  Move the mouse pointer to the On Basics menu item and release MB1.
      The Session Manager displays a Help window, which includes a list
      of Additional Topics about using DECwindows Motif.

152  –  on_context

  Context-sensitive help is information about an area or object in a
  window or a dialog box.

  To display context-sensitive help:

  1.  Choose On Context from the Help menu in a debugger window.  The
      pointer shape changes to a question mark (?).

  2.  Place the question mark on an object or area in a debugger window
      or dialog box.

  3.  Click on MB1.  Information about that area or object is displayed
      in a Help window.  Additional Topics provide task-oriented
      discussions, where applicable.

  To display context-sensitive help for a dialog box, you can also click
  on the Help button in the dialog box.

153  –  on_window

  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.

154  –  on_help

  Choose On Help in the Help menu for instructions on how to use the help
  system.

155  –  on_version

  Choose On Version in the Help menu for version and copyright
  information about the OpenVMS Debugger.

156  –  on_command

  Choose On Commands in the Help menu for information about debugger
  commands.

  The debugger's DECwindows Motif interface is layered on the command
  interface.  You can enter debugger commands at the DBG> command-entry
  prompt in the command view.

157  –  context_sensitive_help

  Context-sensitive help is information about an area or object in a
  window or a dialog box.

  To display context-sensitive help:

  1.  Choose On Context from the Help menu in a debugger window.  The
      pointer shape changes to a question mark (?).

  2.  Place the question mark on an object or area in a debugger window
      or dialog box.

  3.  Click on MB1.  Help for that area or object is displayed in a Help
      window.  Additional Topics provide task-oriented discussions, where
      applicable.

  To display context-sensitive help for a dialog box, you can also click
  on the Help button in the dialog box.

158  –  overview_help

  The On Window help topic (Using the Main Window, Using the Optional
  View Window, Using the Editor Window, Using the Instruction Window) and
  their subtopics provide task-oriented information about the debugger
  and debugging.

  To display the On Window topics, use either of these techniques:

   -  Choose On Window from the Help menu in a debugger window.

   -  Choose Go To Overview from the View menu of a debugger help window.

  Then, to display information about a particular subject, choose a topic
  from the list of Additional Topics.

159  –  command_help

  You can enter debugger commands as follows:

   -  At the command-entry prompt in the command view.

   -  In certain debugger dialog boxes (for example, when assigning a new
      command to a push button on the push-button view).

  To display help on debugger commands and various topics:

   -  Choose On Commands from the Help menu of a debugger window.

   -  Choose the command name or other topic (for example,
      Language_Support) from the list of Additional Topics.

160  –  msg_help

  Debugger diagnostic messages are displayed in the command view.  To
  display help on a particular message:

  1.  Choose On Commands from the Help menu of a debugger window.

  2.  Choose Messages from the list of Additional Topics.

  3.  Choose the message identifier from the list of Additional Topics.

161  –  ha_map_pane_hlp

  The Memory Map, located at the upper left of the heap analyzer screen,
  displays a graphical representation of memory use in real time.

  Each memory allocation appears as a colored strip, or 'segment'.  By
  searching for segments that seem too large, too numerous, or in other
  ways anomalous, you can identify areas in your application where one of
  the following memory events may be occurring:

   -  Memory leaks

   -  Fragmentation

   -  Repetitive allocations

   -  Insufficient allocation

   -  Inefficient memory use

  For information on Memory Map context-sensitive pop-up menus and
  pull-down menus, see the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

162  –  ha_hist_pane_hlp

  The Type Histogram, located in the upper right of the heap analyzer
  screen, allows you to see statistical summaries on segments of the same
  segment type.

  Use the Type Histogram to:

   -  Check the percentage of total segments represented by a segment
      type.  The left histogram shows this percentage graphically.  Click
      on an individual segment type to see a numerical percentage.

   -  Check the percentage of the total bytes allocated to a segment
      type.  The right histogram shows this percentage graphically.
      Click on an individual segment type to see a numerical percentage.

  The total number of segments and the total number of bytes (recognized
  by the heap analyzer) appear at the top of the histogram window.

  For information on Type Histogram context-sensitive pop-up menus, see
  the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

163  –  ha_type_cs

  Most of the work you do in the heap analyzer is accomplished through
  context-sensitive pop-up menus.  The menu items available on the Type
  Histogram are as follows:

      Action             Function
      ------             --------

      Display Type       Displays the segment's type definition
                         in the Information Window.

      Go to Type         Moves the cursor to the segment's type
                         in the Views-and-Types Display.

      Do Not Use Type    Adds the segment's type to the
                         Do-not-use Type List.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

164  –  ha_msg_pane_hlp

  The Message Window, located beneath the Memory Map, displays output
  from the heap analyzer.

  Use the Message Window on the heap analyzer window to do the following:

   -  Read informational and error messages generated by the heap
      analyzer.

   -  Read one-line informational descriptions on individual segments.
      (Click on MB1 while your mouse pointer rests on the segments of
      interest.)

  For information on Message Window context-sensitive pop-up menus, see
  the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

165  –  ha_map_cs

  Most of the work you do in the heap analyzer is accomplished through
  context-sensitive pop-up menus.  The menu items available on the Memory
  Map are as follows:

      Action             Function
      ------             --------

      Traceback of Allocation
                         Displays a traceback, that is, the
                         sequence of routine calls on the
                         callstack, for the segment under
                         your mouse arrow.

      Display Segment    Displays the segment definition of
                         the segment under your mouse arrow
                         in the Information Window.

      Display Contents   Displays the contents of the segment
                         under your mouse arrow.

      Display Address    Displays the address under your mouse
                         arrow in the Information Window.

      Display Type       Displays the segment's type definition
                         in the Information Window.

      Go to Type         Moves the cursor to the segment's type
                         in the Views-and-Types Display.

      Do Not Use Type    Adds the segment's type to the
                         Do-not-use Type List.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

166  –  ha_interpret_trace

  The heap analyzer displays traceback information when you choose the
  Traceback of Allocation context-sensitive menu item from the Memory
  Map.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

167  –  ha_interpret_gototype

  The heap analyzer moves you to the Views-and-Types Display when you
  choose the Go to Type context-sensitive menu item from the Memory Map
  or the Type Histogram.

  Your mouse arrow rests on the segment type associated with the segment
  you selected in the Memory Map or Type Histogram.

  You can choose one of the following options for the display of this
  type in the Memory Map:

   -  Change the color of the type

   -  Show (or hide) the type

   -  Expand (or collapse) the type

   -  Save (or remove) the type

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

168  –  ha_color_type

  The heap analyzer allows you to change the color assigned to a segment
  type in the Memory Map by clicking MB3 on the color spectrum for a
  segment type or types.

  This feature can be useful if the colors of adjacent types are too
  similar to distinguish each type clearly.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

169  –  ha_show_type

  The heap analyzer allows you to hide (and then, show again) the display
  of a segment type in the Memory Map by doing one of the following:

   -  Toggling the Show toggle button and clicking the Apply button in
      the Views-and-Types Display.

   -  Selecting the Show or Hide menu item and clicking the Apply button
      in the Views-and-Types Display.

  This feature can be useful when you need to isolate a segment or
  segments in the Memory Map in order to see them better.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

170  –  ha_expand_type

  The heap analyzer allows you to expand (or collapse) the display of a
  segment type contained inside the display of other segment types in the
  Memory Map by doing one of the following:

   -  Toggling the Expand toggle button and clicking the Apply button in
      the Views-and-Types Display.

   -  Selecting the Expand or Collapse menu item and clicking the Apply
      button in the Views-and-Types Display.

  This feature can be useful when you need a more or less detailed
  picture of an area in the Memory Map.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

171  –  ha_save_type

  The heap analyzer allows you to save (or remove) the display of a
  segment type in the Memory Map by doing one of the following:

   -  Toggling the Save toggle button and clicking the Apply button in
      the Views-and-Types Display.

   -  Selecting the Save or Remove menu item and clicking the Apply
      button in the Views-and-Types display.

  This feature can be useful when you need to improve heap analyzer
  performance by discarding information on unimportant segments.  It is
  also useful when you need to discard all information before a point in
  time, so you can perform a series of actions and see the display
  resulting from them.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

172  –  ha_interpret_donotuse

  The heap analyzer adds a new segment type name to the Do-not-use Type
  List when you perform one of the following actions:

   -  Choose the Do Not Use Type context-sensitive menu item from the
      Memory Map or the Type Histogram.

      The segment type added is the one associated with the segment your
      mouse arrow is pointing to.

   -  Choose the Add to Do-not-use Type List pull-down menu item from the
      Options menu on the Memory Map.

      The segment type added is the one you type into the dialog box that
      appears for your input.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

173  –  ha_interpret_segdef

  The heap analyzer displays segment type definitions when:

   -  You click MB1 on a segment displayed in the Memory Map.

   -  You choose the Display Segment context-sensitive menu item from the
      Memory Map.

  A segment definition has the following form:

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

  which includes:

   -  0004ECA5:  The address underneath your cursor when you pressed MB1
      (This information does not appear when you choose from the
      context-sensitive menu)

   -  15:  The segment number in the Memory Map display

   -  00040000:  The initial address of the segment

   -  0001CA00:  The length in bytes of the segment

   -  005CA00:  The final address of the segment

   -  LIBRTL:  The segment name, or segment type

   -  Image:  The segment classification (image, block, region, or zone)

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

174  –  ha_interpret_typedef

  The heap analyzer displays type definitions when you choose the Display
  Type item in the context-sensitive menu for the Memory Map.

  A type definition has the following form:

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

  which includes:

   -  LIBRTL\LI$VM\LIB$GET_VM:  The segment type name

   -  (Block):  The type classification (image, block, region, or zone)

   -  39 segments:  Number of segments

   -  00002160 bytes:  Number of bytes

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

175  –  ha_interpret_adddef

  The heap analyzer displays segment address definitions when you choose
  the Display Address item in the context-sensitive menu for the Memory
  Map.

  An address definition has the following form:

  001C710B is read and write accessible by the user

  which includes:

   -  001C710B:  The address of the segment

   -  read and write accessible:  The access to the user

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

176  –  ha_interpret_contdef

  The heap analyzer displays segment contents definitions when you choose
  the Display Contents item in the context-sensitive menu for the Memory
  Map.

  A contents definition has the following form:

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

  00000000 00000000 00000000                001C7108
  00345000 00000000 00000000  ~#@           001C7118
  00000B10 00000000 06503000          <>    001C7128
  00C45000 00113000 00000000  *  +*,        001C7138
  00000000 000C4000 0000E000      ..   ?    001C7148

  which includes:

   -  15:  The segment number in the Memory Map display

   -  001C7000:  The initial address of the segment

   -  000000C0:  The length in bytes of the segment

   -  001C70C0:  The final address of the segment

   -  LIBRTL\LIB$VM\LIB$GET_VM:  The segment name, or segment type

   -  Block:  The segment classification (image, block, region, or zone)

   -  An ASCII representation of the contents of the segment

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

177  –  ha_info_pane_hlp

  The Information Window, located in the lower left of the heap analyzer
  screen, displays output from context-sensitive menu items in the Memory
  Map.  These items request the following information:

   -  Traceback entries for an allocation

   -  Segment definitions

   -  Contents definitions

   -  Address definitions

   -  Segment type definitions

  For information on Information Window context-sensitive pop-up menus,
  see the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

178  –  ha_info_cs

  Most of the work you do in the heap analyzer is accomplished through
  context-sensitive pop-up menus.  The menu item available on the
  Information Window is as follows:

      Action             Function
      ------             --------

      Go to Source       Displays the source code associated with
                         the traceback entry under your mouse arrow.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

179  –  ha_source_pane_hlp

  The Source Window, located between the Information Window and the
  Do-not-use Type List, displays the source code associated with a
  traceback entry.

  To display source code, perform the following steps:

  1.  Choose the Traceback of Allocation item in the context-sensitive
      menu on the Memory Map.

  2.  When traceback information appears in the Information Window, click
      on an individual traceback entry.

      The routine call associated with the traceback is highlighted when
      your source code appears.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

180  –  ha_hidelist_view_hlp

  The Do-not-use Type List, located between the Source Window and the
  Views-and-Types Display, lists the routines the heap analyzer does not
  use as "segment types," the names that characterize segments.

  For example, the display showing in the Memory Map may include many
  segments labeled with the names of low-level memory management
  routines.  If you include these names in the Do-not-use Type List, the
  heap analyzer will search further for names to characterize segments,
  and each segment's purpose will become clearer.

  For information on Do-not-use Type List context-sensitive pop-up menus,
  see the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

181  –  ha_hidelist_cs

  Most of the work you do in the heap analyzer is accomplished through
  context-sensitive pop-up menus.  The menu item available on the
  Do-not-use Type List is as follows:

      Action             Function
      ------             --------

      Use Type       Removes a segment type from the Do-not-use
                     Type List.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

182  –  ha_typelist_pane_hlp

  The Views-and-Types Display, located in the lower right of the heap
  analyzer screen, displays the segment types known to the heap analyzer
  and allows you to alter the display of these types.

  Since the type list is organized into images, blocks, regions, and
  zones, you can choose the scope of your change, as follows:

   -  All views (all segments)

   -  All blocks (or individual blocks)

   -  All images (or individual images)

   -  All regions (or individual regions)

   -  All zones (or individual zones)

  Then, move to the right side of the display to choose your display
  change:

   -  Change colors used in display

   -  Suppress (or restore) types in display

   -  Expand (or collapse) detail of types in display

   -  Remove (or save) information on types displayed in session

  <here>

  For information on View-and-Types Display context-sensitive pop-up
  menus, see the additional topics below.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

183  –  ha_typelist_cs

  Most of the work you do in the heap analyzer is accomplished through
  context-sensitive pop-up menus.  The menu items available from the left
  side of the Views-and-Types Display are as follows:

      Action             Function
      ------             --------

      Display Type       Displays the segment's type definition
                         in the Information Window.

      Go to Type         Moves the cursor to the segment's type
                         in the Views-and-Types Display.

      Do Not Use Type    Adds the segment's type to the
                         Do-not-use Type List.

  The menu items available from the right side of the Views-and-Types
  Display are as follows:

      Action             Function
      ------             --------

      Color Spectrum      Changes the color assigned to a segment type
                          or types in the Memory Map.

     --------

      Show                Restores full Memory Map display.

      Hide                Suppresses the display of one or more segment
                          types.

      Reset               Cancels the options chosen.

     ---------

      Expand              Includes the display of segment types occurring
                          within other segment types in the Memory Map.

      Collapse            Suppresses the display of segment types occurring
                          within other segment types in the Memory Map.

      Reset               Cancels the options chosen.

     ---------

      Save                Saves all subsequent information about a
                          segment type or types.

      Remove              Deletes absolutely all information about a
                          segment type or types.

      Reset               Cancels the options chosen.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

184  –  ha_source_db_hlp

  Use the Set Source Dialog Box to specify a source directory search
  list.

185  –  ha_add_hidetype_db_hlp

  Use the Add to Do-not-use Type List Dialog Box to add additional
  routines to the Do-not-use Type List.

186  –  ha_button_pane_hlp

  The push buttons on the control panel allow you to control the speed
  your application executes and the Memory Map displays.  Use the push
  buttons on the control panel to do the following:

  Button             Function
  --------           ---------

  Start/Step          Initially, the Start push button starts your
                      application.  Once your application is running,
                      this push button becomes the Step push button, which
                      you can use when your application is paused to
                      single-step through the Memory Map display.

  Pause               Stops the updating of the Memory Map.

  Slow                Slows the updating of the Memory Map.

  Sync                Off: A small histogram shows how far behind
                      your application's processing the Memory Map
                      displays events (a slight discrepancy improves
                      heap analyzer performance).

                      On: Directs the heap analyzer to update the Memory
                      Map at exactly the same time your application
                      executes the event.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

187  –  ha_file_menu_hlp

  Use the File menu on the heap analyzer window as follows:

  Action      Function
  ------      --------

  Exit        Exits the heap analyzer.

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

188  –  ha_display_menu_hlp

  Use the Display menu on the heap analyzer window as follows:

  Action           Function
  ------           --------

  Text Visible     (Default.)  Labels each segment in the Memory
                    Map with a segment name, provided that the
                    segment is large enough to carry a name label.

  Auto Scroll      (Default.) Automatically scrolls the Memory Map
                    to the highest memory addresses (lower right)
                    whenever memory is expanded.

  Reduce Scroll     When you request a limited or partial Memory
  Region            Map display, compresses the display so you can
                    see as many segments as possible without scrolling
                    to their location in the original display.

  Display All       Restores the complete Memory Map display after
  Segments          you have requested a limited or partial display.

  Clear             Clears text from the Information Window.
  Information
  Window

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

189  –  ha_zoom_menu_hlp

  Use the Zoom menu on the heap analyzer window to specify a closer or
  more distant view of the Memory Map by choosing from the following
  options:

             Extraordinarily Close
             Extremely Close
             Very Close
             Close
             Medium  (Default)
             Far
             Very Far

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

190  –  ha_options_menu_hlp

  Use the Options menu on the heap analyzer window as follows:

  Action           Function
  ------           --------

  Set Source...    Allows you to specify a search directory
                   when you display source code in the debugger
                   or in the source window.

  Add to           Allows you to specify additional segment types
  Do-not-use       to be included in the Do-not-use Type List.
  Type List...

  Save             Allows you to save the segment types listed in
  Do-not-use       your Do-not-use Type List between heap analyzer
  Type List        sessions.

  Restore          Deletes additions to the Do-not-use Type List
  Do-not-use       since the last heap analyzer session.
  Type List

  For information on other heap analyzer screen locations and pop-up
  menus, click the 'On Context' menu item in the heap analyzer Help menu,
  then click the location of interest.

  For information on using the heap analyzer, see the 'On Window' menu
  item in the heap analyzer Help menu.

191  –  ha_help_menu_hlp

  Use the Help menu on the heap analyzer window as follows:

  Action        Function
  ------        --------

  On Context    Provides context-sensitive help for the heap analyzer.

  On Window     Provides task-oriented information on heap analyzer windows.

  On Version    Provides copyright and version information
                on the heap analyzer.

  On Help       Provides task-oriented information on
                DECwindows Motif online help.

  Glossary      Defines terms associated with the heap analyzer.

192  –  on_context_ha

  Context-sensitive help is information about an area or object in a
  window or a dialog box.

  To display context-sensitive help:

  1.  Choose On Context from the Help menu in a debugger window.  The
      pointer shape changes to a question mark (?).

  2.  Place the question mark on an object or area in a debugger window
      or dialog box.

  3.  Click on MB1.  Information about that area or object is displayed
      in a Help window.  Additional Topics provide task-oriented
      discussions, where applicable.

  To display context-sensitive help for a dialog box, you can also click
  on the Help button in the dialog box.

193  –  on_window_ha

  Choose On Window in the Help menu for an overview of the heap analyzer
  along with information on how to do various tasks using the heap
  analyzer.

194  –  On help ha

  Choose On Help in the Help menu for instructions on how to use the help
  system.

195  –  on_version_ha

  Choose On Version in the Help menu for version and copyright
  information about the heap analyzer.

196  –  glossary_ha

  TBS:  This information will appear in a later version release.

197  –  ha_on_window_hlp

  The heap analyzer is a feature of the debugger that provides a
  graphical representation of memory use in real time.  By studying this
  representation, you can identify areas in your application where memory
  usage and performance can be improved.  For example, you might notice
  allocations that are made too often, memory blocks that are too large,
  evidence of fragmentation, or memory leaks.

  After you locate an area of interest, you can request an enlarged, more
  detailed, or altered view.  You can also request additional information
  on the size, contents, or address of the allocations shown.

  After you narrow your interest to an individual allocation, you can
  request traceback information.  The analyzer allows you to correlate
  the traceback entry for an allocation with source code in your
  application program.  By scrolling through the source-code display, you
  can then identify problematic code and decide how to correct it.

  The additional topics below, read in sequence, describe the steps
  involved in using the heap analyzer.

198  –  ha_window_start

  You can invoke the heap analyzer during a debugging session in one of
  the following ways:

   -  In the debugger main window, choose the Run Image or Rerun Same
      items from the File menu.  When a dialog box appears, select the
      program you wish to execute and click the heap analyzer toggle
      button.

   -  At the debugger command entry prompt, enter the RUN/HEAP_ANALYZER
      or RERUN/HEAP_ANALYZER command.

   -  On VAX and Alpha systems, at the DCL prompt ($) in a DECterm window
      outside the debugger, enter the following commands and then execute
      your program:
      $ DEFINE/USER LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED

   -  To display the Heap Analyzer graphical display on I64 systems, at
      the DCL prompt ($) enter the command
      START HEAP_ANALYZER

  You can also invoke the heap analyzer outside a debugging session by
  entering the DEFINE/USER command detailed above, and then the DCL
  command RUN/NODEBUG.

  After you successfully invoke the heap analyzer, the heap analyzer
  startup screen appears.

199  –  ha_window_windows

  The heap analyzer contains a main window, six subsidiary windows, and a
  control panel.

  The Memory Map, the most important window, displays a representation of
  your application's dynamic memory use.  At startup, the Memory Map
  shows the images that comprise your application.  As your application
  executes, you can see the relative location and size of individual
  memory blocks, images, program regions, memory zones, and dynamic
  strings as they are allocated and deallocated in memory space.

  The Message Window displays information on your heap analyzer session.
  At startup, the Message Window contains the message 'Heap Analyzer
  initialization complete.  Press Start button to begin program.' As your
  application executes, informational and error messages appear in this
  window.

  The Push Button Control Panel contains buttons that allow you to
  control the speed of the Memory Map display.  At startup, you click on
  the Start button to begin executing your application.  As your
  application executes, you can click on other buttons in the panel to
  pause, slow, or otherwise affect the continuous display.

  The Information Window displays information on Memory Map segments.  As
  your application executes, you can pause execution at any time to
  request specific information.

  The Source Window displays the application source code associated with
  a segment in the Memory Map.

  The Do-not-use Type List allows you to adjust the Memory Map display by
  redetermining a segment's type, or group name.

  The Views-and-Types Display allows you to adjust the Memory Map display
  by selectively viewing certain segment types.

  The Type Histogram displays summary and statistical information on
  segment types.

  As you use the heap analyzer, you may need to increase or decrease the
  size of the window in which you are working.  To do this, pull the
  window pane sashes between windows or resize the screen as a whole.

200  –  ha_window_sourcedir

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

  To set a source directory:

  1.  Choose the Set Source...  menu item from the Options menu on the
      heap analyzer screen.

      The Set Source dialog box appears.

  2.  Enter the directory specification for your source directory as you
      would for the OpenVMS Debugger SET SOURCE command.

      For more information on this command, see the debugger SET SOURCE
      command in online help.

  3.  Click on OK.

  The heap analyzer can now access your application.

201  –  ha_window_run

  If you invoked the heap analyzer from within a debugging session, start
  your application by performing the following steps:

  1.  Click on the Start button in the Push Button Control Panel.

      The Message Window displays an "application starting" message, and
      the Start button label changes to Step.  The OpenVMS Debbugger main
      window pops forward.

  2.  Click on the Go button in the OpenVMS Debugger's control panel, and
      iconize the OpenVMS Debugger window.

      Memory events associated with your application begin showing in the
      Memory Map.

  (If you invoked the heap analyzer outside a debugging session, start
  your application by performing only step 1 above.)

  After your application is running, the Memory Map (and other parts of
  the heap analyzer display) are continuously updated to reflect the
  state of your application.

  Unless you intervene (by clicking one of the push buttons in the heap
  analyzer control panel), this updating continues until an occurrence
  causes memory events to stop.  For example, your application might
  prompt for input, the debugger might prompt for input, or your
  application might finish execution.

202  –  ha_window_contbutton

  If you decide to examine events in the Memory Map as your application
  is executing, you can use the heap analyzer's push buttons to slow,
  pause, and otherwise affect the speed of the display.

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

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

  The Sync histogram to the right of the Sync button indicates how far
  behind your application the heap analyzer is running.  For performance
  reasons, the heap analyzer displays memory events a few seconds after
  their occurrence in your application.

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

203  –  ha_window_defwork

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

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

  In such cases, your heap analyzer session consists of the following
  steps:

  1.  Examine the Memory Map display.

  2.  Set display characteristics in the Memory Map (optional).

  3.  Request additional information on individual segments (optional).

  4.  Request traceback information on individual segments.

  5.  Correlate traceback entries with source code routines.

204  –  ha_window_def_mmdisp

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

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

205  –  ha_window_def_optmmdisp

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

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

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

206  –  ha_window_def_optinfo

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

  A segment definition has the following form:
  cursor-address   n:init-address + length = end-address  name ( view )

  cursor-address   The address beneath your cursor when you click MB3.

  n                The number of your segment within the sequence of
                   total segments.

  init-address     The initial address of your segment.

  length           The length (in bytes) of your segment.

  end-address      The last address of your segment.

  name             The segment type name of your segment.

  view             The view of your segment:
                   block, image, region, or zone.

                   (See the 'Altering the Views and Types Display' help
                   topic for more information on views.)

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

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

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

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

            [ASCII representation]

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

  001C710B is read and write accessible by the user

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

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

207  –  ha_window_def_trace

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

  Traceback information consists of a partial segment definition (a
  segment definition without a cursor address) and the list of elements
  on the callstack at the moment your segment was created.  The element
  naming convention is:

     image name\module name\routine name\line number

  For example:

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

208  –  ha_window_def_final

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

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

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

  If you double click MB1 on a traceback entry, and 'Source Not
  Available' messages appear in the Source Window, you may have forgotten
  to set a source directory at the beginning of your heap analyzer
  session.  See the 'Setting a Source Directory' help topic for
  information on setting a search directory.

209  –  ha_window_optwork

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

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

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

   -  Review the type summary in the Type Histogram (to see a summary, in
      total segments and total bytes, of each segment type's use) Buff

   -  Adjust the type determination in the Memory Map (directing the heap
      analyzer to select type names that are more meaningful to you)

   -  Adjust the type display in the Memory Map (directing the heap
      analyzer to suppress some types and highlight others)

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

210  –  ha_window_opt_info

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

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

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

211  –  ha_window_opt_type

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

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

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

  This default behavior can cause the following Memory Map problems:

   -  The same few type names appear repeatedly in the Memory Map
      display.

      This occurs when the first routines on the callstack are low-level
      memory management or utility routines.  Since most of the
      allocation events in your application use these routines, you see
      unrelated allocations grouped together with the same type name.

      To prevent this problem, add any application-specific memory
      management or utility routine names to the Do-not-use Type List
      before you run your application.

   -  The type names assigned provide a higher level of abstraction than
      you require.

      This can occur when the first routine on the callstack is less
      application-bound than your level of examination.  If you need to
      see type names that reflect application functions, it is not
      helpful to see type names derived from intermediary memory
      management routines instead.

      This can also occur when the first routine on the callstack focuses
      on a part of your application you are not interested in examining.
      If you need to see type names that reflect subsystem functions (for
      example, initialize_death_star), it is not helpful to see only one
      type name for all subsystem functions (for example,
      initialize_star).

      To correct this problem, add the current type name to the
      Do-not-use Type List until the Memory Map display reflects the
      level of abstraction you desire.

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

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

212  –  ha_window_opt_disp

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

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

213  –  ha_window_opt_scope

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

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

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

   -  Views (integrates all four views)

   -  Blocks (block view from LIB$VM memory manager)

   -  Images (image view from SYS$IMAGE memory manager)

   -  Regions (system services view from SYS$SERVICES memory manager)

   -  Zones (zone view from LIB$VM_ZONE memory manager)

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

  This hierarchy offers you the following choices in scope:

   -  To affect all segment types in all views:

      Click MB1 on the Views keyword

   -  To affect all segment types in one view:

      Click MB1 on the Blocks, Images, or Zones keywords.

   -  To affect individual segment types:

      Double click MB1 on the view of your choice, and click MB1 on one
      or more single segment types.

214  –  ha_window_opt_dispopt

  The right window of the Views-and-Types Display shows the display
  options available, as follows:

   -  Color

      To change the color of all segment types, all segment types in a
      particular view, or individual segment types, click MB3 on the
      color button in the display.  When the vertical color strip
      appears, click MB1 on the color of your choice.  Then, click the
      Apply button to apply your change.

   -  Show (or hide) status

      To suppress (or restore) the display of all segment types, all
      segment types in particular view, or individual segment types,
      toggle the Show button to the Hide (or Show) setting and click MB1.
      (Alternatively, you can choose the appropriate menu item from the
      Show pop-up menu.) Then, click the Apply button to apply your
      change.

      Use this option to clear the Memory Map of segments you are not
      examining.  You can also use this option to find all segments of a
      particular type (by hiding every other segment).

   -  Expand (or collapse) status

      To collapse (or expand) the display of segment types contained
      within all segment types, all segment types in a particular view,
      or individual segment types, toggle the Expand button to the
      Collapse (or Expand) setting and click MB1.  (Alternatively, you
      can choose the appropriate menu item from the Expand pop-up menu.)
      Then, click the Apply button to apply your change.

      Use this option to clear the Memory Map of nested segments you are
      not examining.  Depending on your application, heap analyzer
      performance may also improve.

   -  Save (or remove) status

      To destroy (or save) information on all segment types, all segment
      types in a particular view, or individual segment types, toggle the
      Save button to the Remove (or Save) setting and click MB1.
      (Alternatively, you can choose the appropriate menu item from the
      Save pop-up menu.) Then, click the Apply button to apply your
      change.

      Use this option to clear the Memory Map completely, and then resume
      Memory Map display.

  To cancel a choice, click the Reset button, or choose the Reset menu
  item from the Show, Expand, or Save pop-up menus.

215  –  ha_window_exit

  To exit the heap analyzer, choose the Exit item from the File menu on
  the heap analyzer screen.

216  –  ha_on_version_hlp

  The heap analyzer is a feature of the OpenVMS Debugger

  Software Version:    OpenVMS Debugger Version 8.2

  Copyright 2015, VMS Software, Inc.

  All rights reserved.

  For more information about the heap analyzer, double click on 'Using
  the Heap Analyzer' from the list of Additional Topics below.

217  –  ha_on_help_hlp

  Two kinds of online help about the debugger and debugging are available
  during a debugging session:
      Context-sensitive help, which is information about an area or
      object in a window or dialog box

   -  Task-oriented help, which consists of an introductory help topic
      named 'Using the Heap Analyzer' and several subtopics on specific
      debugging tasks

  Related context-sensitive and task-oriented topics are connected
  through the list of Additional Topics in the Help windows.

218  –  ha_context_sensitive_help

  Context-sensitive help is information about an area or object in a
  window or a dialog box.

  To display context-sensitive help:

  1.  Choose On Context from the Help menu in the heap analyzer screen.
      The pointer shape changes to a question mark (?).

  2.  Place the question mark on an object or area in a heap analyzer
      window or dialog box.

  3.  Click on MB1.  Help for that area or object is displayed in a Help
      window.  Additional Topics provide task-oriented discussions, where
      applicable.

  To display context-sensitive help for a dialog box, you can also click
  on the Help button in the dialog box.
Close Help