=title General Help Topics
 These are the conceptual and task-oriented help topics
 that supplement the context-sensitive help for
 individual objects in the debugger windows.

Additional information available:

Help Menu OverviewHelp Menu AboutHelp Menu Usingg DW basics
g relnotesg callframe labelg callframe buttons display srcg callframe buttons display inst
g resolve symb using callframeg pathnameg intro to addrexprg specifying data
g specifying codeg specifying linesg specifying labelsg specifying registers
g specifying byte offsetsg selecting codeg selecting variablesg specifying variables
g accessing uninitialized variablesg accessing nonstatic variablesg ast prog
g exit handlersg exdepg cmd modeg deb messagesg messages help
g messages severityg keypadg execg where execg watchg operations variables
g operations codeg operations addr regg deb wnd menusg create manipul debwnd
g display predwndsg display sourceg source notavailableg source control files
g display instructionsg display operandsg display pc contentsg invoke options
g end sessiong abortg cmd prcdrsg init fileg log fileg langexprg langexpr vrbl
g langexpr vrbl type convg langexpr addr compg radixg excepG Multilang
g builting builtin ssdebugg builtin logg builtin builting builtin operators
g builtin nextprev entityg builtin curvalueg builtin pageg builtin curnext wnds
g builtin nextprev scopeg builtin sourcinstg builtin exceptionsg builtin tasks
g builtin processesg builtin parcntg builtin identifiersg symb
g symb problemsg DST GST RSTg Symb complinkg Symb mod set
g symb symbolizeg resolve symbg symbol lookup convg using pathnames uniquely
g symb Shareg symb optg debug configg def configg multiproc config
g proc relg multiprocg multiproc activation optionsg ctrl visib proc
g multiproc statesg multiproc program executiong multiproc termination
g multiproc advanced conceptsg langg debugger interferenceg nondebug messages
Scopes Status L ButtonProcess Status L ButtonExamine Status L Button2Wind Dialog Box3g wkinds attribs acts
2Wind Dialog Box3g predwnds2Wind Dialog Box3g modify wnd2Wind Dialog Box3g create wnd
2Wind Dialog Box3g proc windows2Wind Dialog Box3g wkinds2Wind Dialog Box3g wind attrib
2Ex Vbl Dialog Box3g examine var2Dep Vbl Dialog Box3g deposit var2Show Vbl Dialog Box3g show var
2Ex Code Dialog Box3g display source2Ex Code Dialog Box3g display instructions
2Dep Code Dialog Box3g deposit code2Ex Addr Dialog Box3g examine addreg2Dep Addr Dialog Box3g deposit addreg
2Go Dialog Box3g go2Step Dialog Box3g step2Break Dialog Box3g breaktrace
2Proc Dialog Box3proc opt4show

=Title Overview of the Debugger
=include gen g_DW_basics
=include gen g_deb_wnd_menus
=include gen g_display_source
=include gen g_display_instructions
=include gen g_abort
=include gen g_deb_messages
=include gen g_exec
=include gen 2Go_Dialog_Box3g_go
=include gen 2Step_Dialog_Box3g_step
=include gen 2Break_Dialog_Box3g_breaktrace
=include gen g_watch
=include gen g_exdep
=include gen g_symb
=include gen g_intro_to_addrexpr
=include gen g_langexpr
=include gen g_lang
=include gen g_multilang
=include gen g_builtin
=include gen g_cmd_mode
=include gen g_cmd_prcdrs
=include gen g_init_file
=include gen g_log_file
=include gen g_symb_opt
=include gen g_excep
=include gen g_exit_handlers
=include gen g_symb_share
=include gen g_multiproc
=include gen g_ast_prog
=include gen g_keypad
=include gen g_debug_config
=include gen g_invoke_options
=include gen g_end_session
 The debugger is a tool that 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 enables you to do the following tasks:

  -  Control the program's execution (start the program,
     stop at points of interest, resume execution, and
     so on)

  -  Trace the execution path of the program

  -  Monitor changes in variables and other program
     entities

  -  Monitor exception conditions and language-specific
     events

  -  Examine and modify the values of variables, or
     force events to occur

  -  In some cases, test the effect of modifications
     without having to edit the source code, recompile,
     and relink

 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 online help, you will
 discover variations on the basic techniques.  You can
 also customize the debugger for 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
 use memory addresses or registers when referring to
 program locations, although you can, if you want.

 In addition, you can use symbols in the context that is
 appropriate for the program and its source language.
 The debugger supports the language conventions
 regarding data types, expressions, scope and visibility
 of entities, and so on.

 For more information about using the debugger, double
 click on an item from the list of additional topics
 below.

=Title About VAX DEBUG
=include gen Help_Menu_Overview
 VMS Debugger, DECwindows Interface

 Software Version:  VMS Version 5.2

 Copyright (c) 1989 by Digital Equipment Corporation.
 All rights reserved.

 For more information about the debugger, double click
 on Overview of the Debugger from the additional topics
 below.

=Title Using Debugger Help
=include gen Help_Menu_Overview
 Three kinds of online help about the debugger and
 debugging are available during a debugging session:

  -  Context sensitive help, which is available for any
     item in a debugger window, menu, or dialog box.

  -  Conceptual and task-oriented help, which consists
     of an introductory help topic named Overview and
     several subtopics on specific subjects.

  -  Help on the debugger's command interface, which is
     available through the COMMAND box.

Additional information available:

context sensitive helpoverview helpcommand help

=title Displaying Context-Sensitive Help
=include gen Help_Menu_Using
 Context sensitive help about the debugger is available
 for any item in a debugger window, menu, or dialog box.

 To display context-sensitive help:

 1.  Point to an item.

 2.  Press and hold the Help key.

 3.  Click on either MB1, MB2, or MB3.

 4.  Release the Help key.

 Context-sensitive help for dialog boxes is structured
 in the following way:

  -  The same help text is displayed for any location of
     the pointer cursor within a dialog box.

  -  The introductory help text describes how to use the
     dialog box for a typical operation.

  -  In most cases, a separate additional topic is
     devoted to each item in the dialog box (button,
     menu, and so on).  These topics are listed in the
     order that the items they describe appear in the
     dialog box, from top to bottom.

  -  Other topics provide task-oriented and conceptual
     discussions, where applicable.

 When using context-sensitive help, you should also
 display the Overview help topic and look for related
 information in the list of additional topics.

=title Displaying the Overview Help Topic and Subtopics
=include gen Help_Menu_Using
 The Overview help topic and subtopics provide
 conceptual and task-oriented help about the debugger
 and debugging.  These topics supplement the information
 that is available through context-sensitive help.

 To display the Overview topic, use any one of the
 following techniques:

  -  Choose Overview from the Help menu in the main
     window.

  -  Ensure that a debugger window has the input focus,
     then press and release the Help key.

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

 Then, to obtain information about a particular subject,
 choose a topic from the list of additional topics.

=title Displaying Help on the Debugger's Command Interface
=include gen Help_Menu_Using
 Help on the debugger's command interface is available
 through the COMMAND box.

  -  To open the COMMAND box, choose Show Command...
     from the Customize menu.

  -  To list the help topics, enter the command HELP at
     the DBG> prompt.

  -  For an explanation of the command-interface help
     system, enter the command HELP HELP.

=title DECwindows Basics
=include gen help_menu_overview
 Basic information about using DECwindows, such as how
 to manage windows, how to use dialog boxes, and how to
 use scroll bars, is available from Session Manager
 help.  Also, many DECwindows terms are explained in
 Session Manager help.

 To get Session Manager help, move the pointer to the
 icon box and press mouse button 1 (MB1) twice quickly
 on the session manager icon.  The session manager icon
 is the icon that contains your user name and the name
 of your system.  The Session Manager window is
 displayed on your screen.

 Move the pointer to the Help menu in the Session
 Manager window.  Press and hold MB1 to pull down the
 Help menu.  Move the pointer to the Overview menu item
 and release MB1.  Overview provides details about using
 DECwindows.

=Title Release Notes
 TBS

=title Explanation of Call Frame Field
=include gen g_pathname
=include gen g_symb
=include gen g_symb_mod_set
=include gen g_callframe_buttons_display_src
=include gen g_callframe_buttons_display_inst
=include gen g_resolve_symb_using_callframe
 The following text is displayed in the Call Frame
 field:

  -  A non-negative decimal integer that denotes the
     relative level of a call frame on the routine call
     stack.

     Call frame 0 (also known as scope 0 or the PC
     scope) denotes the routine at the top of the call
     stack, where execution is currently suspended.
     Call frame 1 (scope 1) denotes the calling routine,
     if any.  Call frame 2 denotes its caller, and so
     on.  The last routine down the call stack is the
     main program (the routine with the image transfer
     address).

  -  The name of the routine associated with the call
     frame indicated, including its path name prefix.
     The routine name is displayed only if the module
     associated with that call frame is set.

 By default, call frame 0 and its routine are identified
 in the Call Frame field.  By using the arrow buttons,
 you can reset the reference for symbol lookup and
 source and instruction display to another call frame on
 the stack.

=title Using Call Frame Arrow Buttons to Display Source Code
=include gen g_callframe_label
=include gen g_display_source
=include gen g_source_notavailable
=include gen g_callframe_buttons_display_inst
=include gen g_resolve_symb_using_callframe
=include gen Scopes_Status_L_Button
 By default, window SRC displays the source code for the
 routine in which execution is currently suspended.
 This is the routine associated with call frame 0, at
 the top of the call stack, as indicated in the Call
 Frame field of the main window.

 A convenient way to display the source code for
 routines on the call stack is to use the Call Frame
 arrow buttons in the main window:

  -  Clicking on the down-arrow button causes the source
     code of the calling routine (if any) to be
     displayed.

  -  Clicking on the up-arrow button causes the source
     code of the called routine (if any) to be
     displayed.

 If the debugger cannot locate source code for display,
 it tries to display source code in 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, it issues the following message:

    SOURCESCOPE, Source lines not available for .0\%PC.
      Displaying source in a caller of the current routine.

 In such cases, the boxed line in the source window
 identifies the line that contains code following the
 call statement in the calling routine.

=title Using Call Frame Arrow Buttons to Display Instructions
=include gen g_callframe_label
=include gen g_display_instructions
=include gen g_callframe_buttons_display_src
=include gen g_resolve_symb_using_callframe
=include gen Scopes_Status_L_Button
 By default, window INST displays the decoded VAX
 assembly-language instruction stream for the routine in
 which execution is currently suspended.  This is the
 routine associated with call frame 0, at the top of the
 call stack, as indicated in the Call Frame field of the
 main window.

 A convenient way to display the decoded instructions
 for routines on the call stack is to use the Call Frame
 arrow buttons in the main window:

  -  Clicking on the down-arrow button causes the
     instructions for the calling routine (if any) to be
     displayed.

  -  Clicking on the up-arrow button causes the
     instructions for the called routine (if any) to be
     displayed.

=title Using Call Frame Arrow Buttons to Resolve Symbols
=include gen g_resolve_symb
=include gen g_symbol_lookup_conv
=include gen g_callframe_buttons_display_src
=include gen g_callframe_buttons_display_inst
=include gen Scopes_Status_L_Button
 If a symbol is defined multiple times among routines
 that are active on the call stack, you can use the Call
 Frame arrow buttons in the main window to access a
 particular declaration of the symbol without having to
 use a path name prefix.

 The Call Frame field always shows the scope reference
 that the debugger uses for symbol searches.  By
 default, this is scope 0---the scope of the routine at
 the top of the call stack.

 The Call Frame arrow buttons enable you to change the
 scope reference for symbol searches as follows:
 Clicking once on the down-arrow button changes the
 search list from the default 0,1,2...N to 1,2,3...N.
 As a result, the Call Frame field shows scope 1.
 Clicking once more changes it to 2,3,4...N (the Call
 Frame field shows scope 2), and so on.  Conversely,
 clicking on the up-arrow button sets the reference to
 the next level up the call stack.

 The following examples show how you can use these
 buttons to change the convention for symbol lookup:

 Suppose a local variable X is defined twice in your
 program, within two routines that are currently on the
 stack.  One routine is associated with call frame 1,
 the other with frame 3.  When you specify X, the
 debugger by default searches down the call stack from
 frame 0 and uses the declaration of X in call frame 1.
 If you click on the down-arrow button to set the call
 frame to 2 or 3, the debugger then uses the declaration
 of X in call frame 3.

 In another example, suppose a routine has been called
 recursively several times, each time assigning a new
 value to variable X.  When the Call Frame field is set
 to 0, the debugger obtains the value of X in the
 current routine call.  When the Call Frame field is set
 to 1, the debugger obtains the value of X in the
 preceding call (in scope 1), and so on.

=title Understanding Symbol Path Names
=include gen g_resolve_symb
=include gen g_symb
 When displaying symbols that are defined or declared in
 your program (the names of variables, routines, program
 labels, and so on) the debugger always includes a path
 name prefix.

 A path name prefix uniquely identifies a symbol's
 location in terms of the lexical scope where that
 symbol is defined (module, nested routine, block, and
 so on).

 For example, if you were to examine an integer variable
 X declared in routine SWAP of module TEST, the debugger
 might display the following information in the output
 window (the value of X is 27 in this example):

    TEST\SWAP\X:  27

 In this example, TEST\SWAP is the path name prefix.
 The path name, which includes the symbol, is
 TEST\SWAP\X.

 The path name format is as follows.  The leftmost
 element of a path name is the module name.  Moving
 toward the right, the path name lists any successively
 nested routines and blocks that enclose the particular
 declaration of the symbol (which is the rightmost
 element).  A backslash character (\) is used to
 separate elements (except when the language is Ada,
 where a period is used, to parallel Ada syntax).

 By using a path name, you can specify a symbol
 uniquely.  Note, however, that the debugger can
 automatically resolve most symbol ambiguities, using
 the scoping rules of the currently set language and the
 ordering of routine calls on the call stack.
 Therefore, you need to use path names only under the
 following conditions:

  -  If the debugger issues a 'symbol not unique'
     message

  -  If you want to reference a symbol declaration other
     than the one you want

=title Specifying Address Expressions
=include gen g_langexpr_addr_comp
=include gen g_specifying_variables
=include gen g_selecting_variables
=include gen g_specifying_code
=include gen g_selecting_code
=include gen g_specifying_data
=include gen g_builtin_nextprev_entity
=include gen g_radix
=include gen g_operations_variables
=include gen g_operations_code
=include gen g_operations_addr_reg
=include gen g_symb_mod_set
=include gen g_resolve_symb
=include gen g_symb
Several dialog boxes and debugger commands require you
 to specify an address expression.  An address
 expression is an entity that denotes a memory address
 or a register.

 The debugger is a symbolic debugger.  Thereore, you can
 specify symbolic address expressions (symbolic names
 that are declared in, or associated with, your program)
 as well as numeric memory addresses or registers.

 Symbolic address expressions include routine names,
 variable names, program labels, and source line
 numbers.  The debugger associates a symbolic address
 expression with a unique address or register and also
 recognizes the compiler-generated type that is
 associated with a symbolic address expression.

 In addition to an address, register, or symbol, an
 address expression can include operators, numbers (byte
 offsets), and delimiters.  For example, the address
 expression TEMP+4 indicates the memory location that is
 4 bytes beyond the address of the symbol TEMP.  You can
 specify a byte offset from a symbolic location, numeric
 address, or register.

 You can use several debugger built-in symbols as
 address expressions for specific purposes.  For
 example, the period (.) refers to the entity (program
 location) last examined or deposited into, and %NEXTLOC
 refers to the next logical entity.  The next and
 previous logical entity symbols are useful when you are
 examining consecutive array elements or a stream of
 assembly-language instructions.

 Address expressions are associated with either code
 (VAX assembly-language instructions) or data.  The kind
 of address expression you need to specify in a dialog
 box depends on the action you are about to perform and
 is indicated in the help text for that dialog box.  For
 example, when setting a breakpoint, you specify an
 address expression that is associated with code.

 You can fill the Address Expression field or the
 Variable field of a dialog box automatically by
 selecting text in a window before opening the dialog
 box.  Note that the selection technique depends on
 whether the dialog box requires a code or data address
 expression.

 If the debugger cannot access a symbolic address
 expression that you have specified, first check that
 you have spelled the name correctly.  If you have, see
 Controlling Access to Symbols in Your Program for more
 information.

=title Specifying Data Address Expressions
=include gen g_specifying_variables
=include gen g_selecting_variables
=include gen g_specifying_registers
=include gen g_builtin_nextprev_entity
=include gen Examine_Status_L_Button
=include gen g_specifying_byte_offsets
=include gen g_radix
=include gen g_operations_variables
=include gen g_operations_addr_reg
=include gen g_symb_mod_set
=include gen g_resolve_symb
=include gen g_symb
=include gen g_intro_to_addrexpr
 When specifying address expressions that are associated
 with data, use any of the following forms:

  -  The name of a variable (for example, X) or of an
     element of a composite variable (for example,
     ARR[3]).  For high level languages, this is the
     most common way to specify an address expression
     that is associated with data.

  -  A memory address (for example, 1628).

  -  A VAX register (for example, %R1).

  -  A built-in symbol, such as the period (.) or
     %NEXTLOC.

  -  A byte offset (for example, TEMP+4).

  -  A combination of any of the above.

=title Specifying Code Address Expressions
=include gen g_selecting_code
=include gen g_specifying_lines
=include gen g_specifying_labels
=include gen g_display_pc_contents
=include gen g_specifying_registers
=include gen g_builtin_nextprev_entity
=include gen Examine_Status_L_Button
=include gen g_specifying_byte_offsets
=include gen g_radix
=include gen g_operations_code
=include gen g_operations_addr_reg
=include gen g_symb_mod_set
=include gen g_resolve_symb
=include gen g_symb
=include gen g_intro_to_addrexpr
 When specifying address expressions that are associated
 with code (VAX assembly-language instructions), use any
 of the following forms:

  -  A source line number (for example %LINE 53).

  -  A routine name (for example, SWAP).

  -  A label in the program (for example, %LABEL 30)

  -  A memory address (for example, 1628).

  -  A VAX register (for example, %PC).

  -  A built-in symbol, such as the period (.) or
     %NEXTLOC.

  -  A byte offset (for example, SWAP+4).

  -  A combination of any of the above.

=title Specifying Source Line Numbers (%LINE Symbol)
=include gen g_intro_to_addrexpr
=include gen g_symb
=include gen g_DST_GST_RST
=include gen g_display_source
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen g_radix
=include gen g_builtin_builtin
 Follow these rules when specifying a source line number
 as an address expression:

  -  Precede the number with the built-in symbol %LINE.
     Otherwise, the debugger interprets the number as a
     memory address.  For example:

     Address expression %LINE 342 specifies line 342
     Address expression 342 specifies memory address 342

  -  Specify a line number that is associated with
     executable code (VAX assembly-language
     instructions).  Otherwise, the debugger issues a
     diagnostic message identifying the previous or next
     executable line.  For example:

   LINEINFO, no line 6, previous line is 5, next line is 8
   NOSYMBOL, symbol '%LINE 6' is not in the symbol table

 Line numbers are handled by the debugger just like
 variable names, routine names, and other symbols that
 are declared in a program.  You can qualify a line
 number with a path name prefix that specifies the
 containing module.

 Compilers generate line-number symbol-table records
 only for those source lines that result in executable
 code.  For example:

  -  Line number records are generated for assignment
     statements, routine declarations, routine calls,
     and labels.

  -  Line number records are not generated for comment
     lines.

=title Specifying Program Labels (%LABEL Symbol)
=include gen g_intro_to_addrexpr
=include gen g_radix
=include gen g_builtin_builtin
 You specify a nonnumeric label (for example LOOP2) as
 an address expression exactly as it appears in the
 source code.

 Certain languages, like FORTRAN, have numeric labels.
 When specifying a numeric label (for example, 30) as an
 address expression, you must precede the number with
 the built-in symbol %LABEL (for example, %LABEL 30).
 Otherwise, the number is interpreted as a memory
 address.

 You can qualify the label with a path name prefix that
 specifies the containing module.

=title Specifying VAX Registers
=include gen g_intro_to_addrexpr
=include gen g_display_pc_contents
=include gen 2Wind_Dialog_Box3g_predwnds g_reg
=include gen g_builtin_builtin
 The debugger built-in symbol for a VAX register is the
 register name preceded by the percent sign (%).  The
 VAX register symbols are identified in the following
 list:

  Symbol        Description
  ------        -----------
  %R0 -> %R11   General purpose registers R0 - R11
  %AP or %R12   Argument pointer
  %FP or %R13   Frame pointer
  %SP or %R14   Stack pointer
  %PC or %R15   Program counter
  %PSL          Processor status longword

 For example, the following Examine command displays the
 contents of the PC (the address contained in the PC):

   Examine %PC
   MOD\%PC: 1553

 You can abbreviate registers by leaving out the percent
 character (for example, R0 instead of %R0).  However,
 if you do not use the percent character, the debugger
 might interpret these symbols as program variables you
 have defined, not as debugger built-in symbols.

 The debugger interprets these symbols as debugger
 built-in symbols only if your program does not contain
 variables of the same names.

=title Specifying Byte Offsets
=include gen g_intro_to_addrexpr
=include gen g_radix
 The following examples of address expressions show how
 to specify a byte offset from a particular location:

  -  The address expression TEMP + 4 indicates the
     memory location that is 4 bytes beyond the address
     denoted by the symbol TEMP.

  -  The address expression 1628 + 7 indicates the
     memory location that is 7 bytes beyond address
     1628.

=title Selecting Code Address Expressions from Windows
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen g_pathname
=include gen g_specifying_code
 Several dialog boxes require you to specify an address
 expression that is associated with code (that is, one
 or more VAX assembly-language instructions).  Examples
 are the Break, Call, and Examine Code dialog boxes.

 Symbolic address expressions that are associated with
 code include routine names, program labels, and line
 numbers for source lines that contain instructions (for
 example assignment statements, routine calls, and so
 on).

 You can fill the Address Expression field of these
 dialog boxes automatically by selecting text in a
 window before opening the dialog box.

 The following conventions apply:

  -  Select text in a debugger source or instruction
     window, or in a window of another application that
     provides the same source correlation context (for
     example, an LSEDIT editor window).

  -  When you open the dialog box, the Address
     Expression field (or equivalent field) displays a
     path name consisting of the module and line number
     where the text was selected, in the following
     format (n is the line number):

        module-name\%LINE n

  -  You can select any portion of a source line, but
     the line must result in executable code (VAX
     assembly-language instructions).  For example, a
     line that contains a routine declaration, routine
     call, assignment statement, or label results in
     executable code.

  -  If you select a source line that is not associated
     with code (for example, a comment line), the
     debugger issues a diagnostic message that
     identifies the previous or next executable line
     when you click on OK or Apply in the dialog box.

  -  If you select text in a window other than a source,
     instruction, or equivalent window (with source
     correlation context), the same selected text is
     displayed in the Address Expression field.

=title Selecting Variables from Windows
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen g_specifying_variables
 Several dialog boxes require you to specify a variable
 name in the Variable field or, in the case of the Watch
 dialog box, in the Address Expression field.

 You can fill the appropriate field of these dialog
 boxes automatically by selecting text in a window
 before opening the dialog box.

 The following conventions apply:

  -  You can select text in any window.

  -  To select a variable, double click on its name.

  -  To select an element or component of a composite or
     structured variable, press MB1 and drag the pointer
     cursor over the element or component, observing the
     syntax of the source language.

     For example, drag over the array element ARR[3] or
     over the record component EMPLOYEE.ADDRESS.

 When you open the dialog box, the same selected text is
 automatically inserted into the Variable field (or the
 Address Expression field of the Watch dialog box).

=title Specifying Variables
=include gen g_selecting_variables
=include gen g_specifying_registers
=include gen g_builtin_nextprev_entity
=include gen Examine_Status_L_Button
=include gen g_specifying_byte_offsets
=include gen g_radix
=include gen g_accessing_uninitialized_variables
=include gen g_accessing_nonstatic_variables
=include gen g_symb_opt
=include gen g_symb_mod_set
=include gen g_resolve_symb
=include gen g_symb
=include gen g_operations_variables
=include gen g_operations_addr_reg
=include gen g_intro_to_addrexpr
 You specify a variable exactly as you would in the
 source program.

 For example, to specify the variable X, enter X.

 If the variable is of a composite or structured data
 type, such as an array, record, or pointer (access
 type), use the syntax of the source language to specify
 the entire aggregate, individual components, or ranges
 of elements.  For example:

  -  If ARR is the name of an array variable, specifying
     ARR denotes the entire array aggregate in some
     languages.

  -  ARR[2] denotes element 2 of array ARR in some
     languages.

  -  ARR[3:7] denotes elements 3 through 7 of array ARR
     in some languages.  When specifying a range (an
     array slice), always start with the lowest-numbered
     element.  You can specify a list of ranges by
     separating ranges with commas.

  -  EMPLOYEE.ADDRESS denotes the ADDRESS component of
     the record variable EMPLOYEE in some languages.

 You can specify more than one variable or element of a
 variable.  In such cases, separate the individual
 entities to be examined with commas.  The following
 example obtains the value of X and of ARR[2]:

     X,ARR[2]

 If the debugger cannot access a variable that you
 specify, first check that you have spelled the name
 correctly (or selected the correct entity in a window).
 If you have, see the additional topics for more
 information.

 For example, if a symbol is not in the symbol table,
 you might need to set the module that contains the
 declaration of the variable.

 Or, if a symbol is not unique, you might need to add a
 path name prefix to the variable name to resolve the
 ambiguity.

=title Accessing Uninitialized Variables
=include gen g_specifying_variables
=include gen g_symb
 You can examine a static variable at any time during
 program execution, and you can examine a nonstatic
 (stack or register) variable as soon as execution
 reaches its defining routine.

 However, before you examine any variable, you should
 step or otherwise execute the program beyond the point
 where the variable is declared and initialized.  The
 value contained in any uninitialized variable should be
 considered invalid.

=title Accessing Nonstatic (Stack or Register) Variables
=include gen g_resolve_symb_using_callframe
=include gen g_specifying_variables
=include gen g_symb
 Storage for variables in your program is allocated
 either statically or nonstatically.  A static variable
 is associated with the same memory address throughout
 execution of the program.  A nonstatic variable is
 allocated on the stack or in a register and has a value
 only when its defining routine is active (on the call
 stack).

 Therefore, before you try to examine or deposit into a
 nonstatic variable, its defining routine must be active
 (on the call stack).  That is, program execution must
 be suspended somewhere within the defining routine.
 The debugger notifies you if you try to access a
 nonstatic variable when it is not active.

 A common technique for examining or depositing into a
 nonstatic variable is to first set a breakpoint on the
 defining routine and execute the program to the
 breakpoint.

 You can obtain information about the call stack by

  -  Choosing Call Stack...  from the Data menu

  -  Using the Call Frame Field and Buttons in the main
     window

=title Debugging AST-Driven Programs
A program can use asynchronous system traps (ASTs)
 either explicitly, or implicitly by calling VMS system
 services or run-time library routines that call
 user-defined AST routines.  The topic Disabling and
 Enabling ASTs explains how to facilitate debugging by
 disabling and enabling the delivery of ASTs originating
 with your program.  The topic AST Call Frames explains
 how delivery of an AST affects a call stack display, as
 obtained by choosing Call Stack...  from the Data menu.

Additional information available:

ast prog disableAST prog call

=title Disabling and Enabling ASTs
=include gen g_ast_prog
 Debugging AST-driven programs can be confusing because
 interrupts originating from the program can occur, but
 are not processed, while the debugger is running
 (processing commands, tracing execution, displaying
 information, and so on).

 The delivery of ASTs is always disabled while the
 debugger is running.

 By default, the delivery of ASTs is enabled while the
 program is running.

 You can control the delivery of ASTs while the program
 is running by choosing Other Attributes...  from the
 Customize menu and then turning the ASTs Enabled button
 on or off:

  -  If the ASTs Enabled button is on, the delivery of
     ASTs is enabled while the program is running.

  -  If the ASTs Enabled button is off, the delivery of
     ASTs is disabled while the program is running.

 Disabling the delivery of ASTs while the program is
 running causes any such potential interrupts to be
 queued.  Enabling the delivery of ASTs causes any
 pending ASTs to be delivered.

 You can control the delivery of ASTs during the
 execution of a routine called with the Call command.
 Choose Call...  from the Control menu to enter the Call
 command.  In the Call dialog box, turn the ASTs Enabled
 During Execution button on or off to enable or disable,
 respectively, the delivery of ASTs during the routine
 call.

=title AST Call Frames
=include gen g_ast_prog
 The delivery of an AST creates one or more special call
 frames that appear in a call stack display, as obtained
 by choosing Call Stack...  from the Data menu.  These
 call frames are not symbolized and might make the
 display confusing.  The following example illustrates
 what you might see in a call stack display when an AST
 routine is on the stack.

 Assume that a program calls the system service $SETIMR
 to set a timer that expires at a specified interval and
 then executes a user-defined AST routine, TIMER_ROUT,
 in the program.

 You set a breakpoint on routine TIMER_ROUT, start
 execution, which is then suspended on that routine, and
 then display the sequence of active calls at the
 breakpoint:

  [set breakpoint on TIMER_ROUT]
  [Go]
  ...
  break at routine MOD1\TIMER_ROUT
      14:     X = .X + 1;
  [Display call stack]
  module name  routine name  line   rel PC    abs PC
  *MOD1        TIMER_ROUT     14   00000002  0000040E
                                   00000000  80009E5E

 The last line is the call frame associated with the
 system AST dispatcher.  It shows the absolute PC value
 when the AST was delivered.

 Because the AST dispatcher is in system space, as
 indicated by the high absolute address, no symbolic
 information (module name, routine name, line number) is
 available.

 A call stack display associated with the delivery of an
 AST might also show some debugger call frames (module
 name SHARE$DEBUG) and diagnostic messages related to
 condition handling by the debugger.  You should ignore
 such messages and call frames.

=title Debugging Exit Handlers
Exit handlers are procedures that are called whenever an
 image requests the $EXIT system service or runs to
 completion.  An application program can declare one or
 more exit handlers.  The debugger always declares its
 own exit handler.

 At program termination, the debugger exit handler
 executes after all application-declared exit handlers
 have executed.

 To debug an application-declared exit handler:

 1.  Set a breakpoint in that exit handler.  (Choose
     Break...  from the Control menu to set a
     breakpoint.)

 2.  Cause that exit handler to execute, either by
     including in your program an instruction that
     invokes the exit handler (usually a call to $EXIT),
     or by allowing your program to terminate, or by
     choosing Exit on the File menu.

 Note that choosing Quit on the File provides the option
 of executing application-declared exit handlers.  A
 dialog box is displayed when you choose Quit with a
 program that has application-declared exit handlers.

 When the exit handler executes, the breakpoint is
 activated and control is then returned to the debugger.

 Choose Exit Handlers from the Data menu to identify any
 exit handlers that are declared in the program.  The
 exit handler routines are displayed in the order that
 they are called.  A routine name is displayed
 symbolically, if possible.  Otherwise its address is
 displayed.  The debugger's exit handlers are not
 displayed.

=title Examining and Manipulating Program Data
=include gen g_operations_variables
=include gen g_operations_code
=include gen g_operations_addr_reg
=include gen Examine_Status_L_Button
=include gen g_langexpr
=include gen g_symb
=include gen 2Ex_Vbl_Dialog_Box3g_examine_var
=include gen 2Dep_Vbl_Dialog_Box3g_deposit_var
=include gen 2Show_Vbl_Dialog_Box3g_show_var
=include gen g_specifying_variables
=include gen g_selecting_variables
=include gen 2Ex_Code_Dialog_Box3g_display_source
=include gen Ex_Code_Dialog_Box g_display_instructions
=include gen 2Dep_Code_Dialog_Box3g_deposit_code
=include gen g_specifying_code
=include gen g_selecting_code
=include gen 2Ex_Addr_Dialog_Box3g_examine_addreg
=include gen 2Dep_Addr_Dialog_Box3g_deposit_addreg
=include gen g_intro_to_addrexpr
The debugger enables you to manipulate variables, code
 locations (locations with VAX instructions), memory
 addresses and registers, and language expressions.

 The debugger supports all compiler-generated data types
 for the supported languages, such as integer, floating
 point, enumeration, record, array, and so on.  By
 default, it displays the values of program variables
 according to their declared type.

 In addition, the debugger supports a variety of data
 forms and types for entry and display.  By default, the
 source language of the program determines the format
 used for the entry and display of data.  You can also
 impose other formats.  For example, you can display the
 contents of a program location in ASCII, word-integer,
 or floating-point format.

=title The Debugger's Command Interface
=include gen g_cmd_prcdrs
=include gen g_init_file
=include gen g_log_file
=include gen g_invoke_options g_invoke_override_interf
=include gen 2Wind_Dialog_Box3g_wind_attrib g_inpwa
The debugger is available through two user interfaces:

  -  A DECwindows (direct manipulation) interface for
     workstations

  -  A command interface for terminals (and also for a
     few DECwindows operations that require you to enter
     commands)

 When using the DECwindows interface, you might need to
 specify debugger commands for the following purposes:

  -  To create debugger command procedures and
     initialization files.

  -  To specify actions in the Action field of some
     dialog boxes (for example, the Break or Windows
     dialog boxes).

 In addition, the debugger's DECwindows interface
 includes the COMMAND box, which enables you to enter
 debugger commands at the DBG> prompt---that is, to use
 the command interface from the DECwindows interface:

  -  To open the COMMAND box for just one command, press
     the DO key when a debugger window has the input
     focus.

  -  To open the COMMAND box indefinitely, choose Show
     Command...  from the Customize menu.  To close the
     COMMAND box, choose Hide Command...  from the
     Customize menu.

 In general, you can perform any DECwindows debugger
 action by means of a corresponding debugger command (or
 command/qualifier combination).  The output from a
 debugger command is displayed in the window that
 displays the output from the equivalent DECwindows
 action.

 The additional topics provide basic information about
 using debugger commands in the DECwindows environment.
 The topic Overriding the Debugger's Default Interface
 explains how you can invoke the command interface from
 a DECterm window.

 For complete information about the debugger's command
 interface, see the VMS Debugger Manual.

Additional information available:

cmd helpcmd format

=title Getting Online Help on the Command Interface
=include gen g_cmd_mode
 The online help system for the debugger's command
 interface provides information about each debugger
 command and on selected topics.  For an explanation of
 this help system, enter the command HELP HELP at the
 DBG> prompt in the COMMAND box.

 To open the COMMAND box, choose Show Command...  from
 the Customize menu.

=title Debugger Command Format
=include gen g_cmd_prcdrs create_cmd_proc
=include gen g_cmd_mode
 The topic General Command Format gives an overview of
 the debugger command format.  The other topics give the
 rules for entering commands in the following contexts:

  -  At the DBG> prompt in the COMMAND box

  -  In the Action field of a dialog box

  -  In a debbuger command procedure that you can later
     invoke with the @ (execute procedure) command

Additional information available:

General FormatEntering commands in action fieldEntering Commands At the Prompt

=TITLE General Command Format
=include gen g_cmd_mode cmd_format
=include gen g_cmd_mode
 A command string is the complete specification of a
 debugger command.  Although you can continue a command
 on more than one line, the term command string is used
 to define an entire command that is passed to the
 debugger.  A debugger command string consists of a verb
 and, possibly, parameters and qualifiers.

 The verb specifies the command to be executed.  Some
 debugger command strings consist of only a verb or a
 verb pair.  For example:

   DBG> GO
   DBG> SHOW IMAGE

 A parameter specifies what the verb acts on (for
 example, a file specification).  A qualifier describes
 or modifies the action taken by the verb.  Some command
 strings include one or more parameters or qualifiers.
 In the following examples, COUNT, I, J, and K, OUT2,
 and PROG4.COM are parameters (@ is the "execute
 procedure" command); /SCROLL and /OUTPUT are
 qualifiers.

   DBG> SET WATCH COUNT
   DBG> EXAMINE I,J,K
   DBG> SELECT/SCROLL/OUTPUT OUT2
   DBG> @PROG4.COM

 Some commands accept optional WHEN or DO clauses.  DO
 clauses are also used in some screen display
 definitions.

 A WHEN clause consists of the keyword WHEN followed by
 a conditional expression (within parentheses) that
 evaluates to true or FALSE in the current language.  A
 DO clause consists of the keyword DO followed by one or
 more command strings (within parentheses) that are to
 be executed in the order that they are listed.  You
 must separate multiple command strings with semicolons
 (;).  These points are illustrated in the next example.

 The following command string sets a breakpoint on
 routine SWAP that is triggered whenever the value of J
 equals 4 during execution.  When the breakpoint is
 triggered, the debugger executes the two command
 strings SHOW CALLS and EXAMINE I,K, in the order
 indicated.

 DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAM I,K)

 The debugger checks the syntax of the commands in a DO
 clause when it executes the DO clause.  You can nest
 commands within DO clauses.

=title Entering Commands in Action Fields of Dialog Boxes
=include gen g_cmd_mode cmd_format
=include gen g_cmd_mode
 When entering a debugger command in the Action field of
 a dialog box, you can abbreviate a keyword (verb,
 qualifier, parameter) to as few characters as are
 needed to make it unique within the set of all debugger
 keywords.

 You can enter more than one command string in the
 Action field by separating command strings with
 semicolons (;).

 You cannot continue a command string on another line in
 the Action field by typing a hyphen (-).

=TITLE Entering Commands in the COMMAND Box
=include gen g_cmd_mode cmd_format
=include gen g_cmd_mode
 When entering a debugger command at the DBG> prompt in
 the COMMAND box, you can abbreviate a keyword (verb,
 qualifier, parameter) to as few characters as are
 needed to make it unique within the set of all debugger
 keywords.

 However, some commonly used commands (for example,
 EXAMINE, DEPOSIT, GO, STEP) can be abbreviated to their
 first characters.  Also, in some cases, the debugger
 interprets nonunique abbreviations correctly on the
 basis of context.

 Pressing the RETURN key terminates the current line,
 causing the debugger to process it.  To continue a long
 command string on another line, type a hyphen (-)
 before pressing RETURN.  As a result, the debugger
 prompt is prefixed with an underline character (_DBG>),
 indicating that the command string is still being
 accepted.

 You can enter more than one command string on one line
 by separating command strings with semicolons (;).

 To enter a comment (explanatory text that is recorded
 in a debugger log file but is otherwise ignored by the
 debugger), precede the comment text with an exclamation
 point (!).  If the comment wraps to another line, start
 that line with an exclamation point.

 The command line editing functions that are available
 at the DCL prompt are also available at the debugger
 prompt, including command recall with the up arrow and
 down arrow keys.  For example, pressing the left arrow
 and right arrow keys moves the cursor one character to
 the left and right, respectively; pressing CTRL/H and
 CTRL/E moves the cursor to the start and the end of the
 line, respectively; pressing CTRL/U deletes all the
 characters to the left of the cursor, and so on.

 To abort a command that is being processed by the
 debugger, click on the Stop button in the main window.
 Clicking on the Stop button can also be used to
 interrupt program execution.  However, it does not
 interrupt or end the debugging session.

=title Debugger Diagnostic Messages
=include gen 2Wind_Dialog_Box3g_wind_attrib g_msgwa
=include gen g_messages_help
=include gen g_messages_severity
Debugger diagnostic messages include numerous
 informational messages (severity level I) that provide
 feedback during a debugging session.

 To reduce the time involved in acknowledging
 informational messages, only those debugger messages
 that have severity levels of W, E, or F are displayed
 in a message box.

 You can get context-sensitive help on any debugger
 message that is displayed in a message box.

 By default, all debugger messages, including those of
 severity level I, are displayed in the current message
 window (the window with the messages attribute).  By
 default, the predefined output window OUT has the
 messages attribute.

 Thus, debugger messages of severity level greater than
 I are displayed in two windows.  Messages displayed in
 a message box show only the message text.  Messages
 displayed in the current message window show the
 message text, identifier, severity, and facility.

=title Getting Help on Debugger Diagnostic Messages
=include gen g_messages_severity
=include gen help_menu_using
=include gen g_deb_messages
 When the debugger displays a diagnostic message in a
 message box, you can get context-sensitive help on that
 message.

 The help frame for a debugger diagnostic message
 consists of the following:

 1.  The identifier (IDENT), which is an abbreviation of
     the message text.

 2.  The message text, as displayed in the message box.
     In the help frame, a generic term is substituted
     for any specific entity (symbol, file name, and so
     on) that is indicated in the actual message.

 3.  The severity level:  Success, Informational,
     Warning, Error, or Fatal.

 4.  The explanation of the message and the action you
     need to take, if any.

 Note that online help might not be available for
 diagnostic messages that do not originate with the
 debugger.

 Diagnostic messages for all VMS components and
 utilities are explained in the VMS System Messages and
 Recovery Procedures Volume, where they are listed
 alphabetically by message identifier.

=title Explanation of Debugger-Message Severity Levels
=include gen g_deb_messages
 The significance of debugger severity levels is as
 follows:

 Success and Informational messages inform you that the
 debugger has performed your request.

 Warning messages indicate that the debugger might have
 performed some, but not all, of your request, and that
 you should verify the result.

 Error messages indicate that the debugger could not
 perform your request, but that the state of the
 debugging session was not changed.  The only exceptions
 are if the message identifier was DBGERR or INTERR.
 These identifiers signify an internal debugger error,
 and you should submit a Software Performance Report
 (SPR) in such cases.

 Fatal messages indicate that the debugger could not
 perform your request and that the debugging session is
 in an indeterminate state from which you cannot recover
 reliably.  Typically, the error ends the session.

=title Entering Debugger Commands from the Keypad
=include gen g_cmd_mode
When you invoke the debugger, a few commonly used
 debugger command sequences are automatically assigned
 to the keys on the numeric keypad.  Thus, you can
 perform certain functions either by choosing an item
 from a menu or by pressing a keypad key.

 Most keypad keys have three predefined
 functions---DEFAULT, GOLD, and BLUE.

  -  To enter a key's DEFAULT function, press the key.
     For example, pressing keypad key 0 issues the Step
     command (like clicking on the Step button in the
     main window).

  -  To enter its GOLD function, first press and release
     the PF1 (GOLD) key, and then press the key.  For
     example, pressing key PF1 and then keypad key 0
     enters the STEP/INTO command (like choosing Step
     Into Routine from the pop-up menu).

  -  To enter its BLUE function, first press and release
     the PF4 (BLUE) key, and then press the key.  For
     example, pressing key PF4 and then keypad key 0
     enters the STEP/OVER command (like choosing Step
     Over Routine from the pop-up menu).

 Some keys are bound to functions that manipulate
 debugger windows.  Some of these keys duplicate the
 functions of the Window Setups submenu and the
 Multiprocess Window Setups submenu of the Customize
 menu.

 You can also redefine key functions with the DEFINE/KEY
 command, entered in the COMMAND box.

 To determine the debugger command-sequence issued by a
 keypad key, enter the SHOW KEY command in the COMMAND
 box.

Additional information available:

g default keypadg gold keypadg blue keypadg keypad defs
g key designations

=title DEFAULT Key Definitions (Summary Keypad Diagram)
=include gen g_keypad g_keypad_defs
=include gen g_keypad g_gold_keypad
=include gen g_keypad g_blue_keypad
=include gen g_keypad g_key_designations
=include gen g_cmd_mode
=include gen g_keypad
 The following diagram summarizes the functions of the
 keypad keys when in the DEFAULT state---that is, when
 you press a key without first pressing the PF1 or PF4.

 +--------+--------+--------+--------+
 | (PF1)  |  Help  |  Set   | (PF4)  |
 | GOLD   | Keypad |  Mode  | BLUE   |
 | state  |Default | Screen | state  |
 +--------+--------+--------+--------+
 | Src LH1|        |        |  Disp  |
 |Inst RH1| Scroll |  Disp  |  next  |
 | Out S45|   Up   |  next  | S12345 |
 +--------+--------+--------+--------+
 |        |  Exam  |        |        |
 | Scroll | Source | Scroll |   Go   |
 |  Left  | .0\%PC | Right  |        |
 +--------+--------+--------+--------+
 |        |        | Select |        |
 |  Exam  | Scroll | Scroll |   E    |
 |        |  Down  |  next  |   N    |
 +--------+--------+--------+   T    |
 |                 |        |   E    |
 |      Step       | Reset  |   R    |
 |                 |        |        |
 +-----------------+--------+--------+

=title GOLD Key Definitions (Summary Keypad Diagram)
=include gen g_keypad g_keypad_defs
=include gen g_keypad g_default_keypad
=include gen g_keypad g_blue_keypad
=include gen g_keypad g_key_designations
=include gen g_cmd_mode
=include gen g_keypad
 The following diagram summarizes the functions of the
 keypad keys when in the GOLD state---that is, when you
 first press PF1 and then press a keypad key.

 The Reset key cancels the effect of pressing PF1 or
 PF4.

 +--------+--------+--------+--------+
 | (PF1)  |  Help  |Set Mode| (PF4)  |
 | GOLD   | Keypad |   No   | BLUE   |
 | state  |  Gold  | Screen | state  |
 +--------+--------+--------+--------+
 |Inst LH1|        |  Set   |        |
 | Reg RH1| Scroll | Process|        |
 | Out S45|  Top   |  next  |        |
 +--------+--------+--------+--------+
 | Scroll |        | Scroll | Select |
 |  Left  |  Show  | Right  | Source |
 |  255   |  Calls |  255   |  next  |
 +--------+--------+--------+--------+
 |  Exam  |        | Select |        |
 |  prev  | Scroll | Output |   E    |
 |        | Bottom |  next  |   N    |
 +--------+--------+--------+   T    |
 |                 |        |   E    |
 |    Step/Into    | Reset  |   R    |
 |                 |        |        |
 +-----------------+--------+--------+

=title BLUE Key Definitions (Summary Keypad Diagram)
=include gen g_keypad g_keypad_defs
=include gen g_keypad g_default_keypad
=include gen g_keypad g_gold_keypad
=include gen g_keypad g_key_designations
=include gen g_cmd_mode
=include gen g_keypad
 The following diagram summarizes the functions of the
 keypad keys when in the BLUE state---that is, when you
 first press PF4 and then press a keypad key.

 The Reset key cancels the effect of pressing PF1 or
 PF4.

 "..." means that you must specify a number (of lines or
 characters) before pressing the ENTER key.

 +--------+--------+--------+--------+
 | (PF1)  |  Help  |        | (PF4)  |
 | GOLD   | Keypad |  Disp  | BLUE   |
 | state  |  Blue  |  Gener | state  |
 +--------+--------+--------+--------+
 |2 SRC Qn| Scroll | 2 SRC  |  Disp  |
 | 2 INST |   Up   |   at   | Src H1 |
 | at RQn |  ...   | Q1,Q2  | Out S45|
 +--------+--------+--------+--------+
 | Scroll |  Show  | Scroll | Select |
 |  Left  |  Calls | Right  |  Inst  |
 |  ...   |   3    |  ...   |  next  |
 +--------+--------+--------+--------+
 |3 SRC Sn| Scroll | 3 SRC  |        |
 | 3 INST |  Down  |   at   |   E    |
 | at RSn |  ...   |S1,S2,S3|   N    |
 +--------+--------+--------+   T    |
 |                 |        |   E    |
 |    Step/Over    | Reset  |   R    |
 |                 |        |        |
 +-----------------+--------+--------+

=title Keypad-Key Definitions
=include gen g_keypad g_key_designations
=include gen g_keypad g_default_keypad
=include gen g_keypad g_gold_keypad
=include gen g_keypad g_blue_keypad
=include gen g_cmd_mode
=include gen g_builtin_builtin
=include gen g_keypad
 The following table summarizes all keypad key
 definitions.  To determine the debugger command
 sequence issued, use the SHOW KEY command in the
 COMMAND box.

 Key    State    Command Invoked or Function
 ---    -----    ---------------------------
 0      DEFAULT  STEP (like clicking on the Step button)
        GOLD     STEP/INTO (step into routine)
        BLUE     STEP/OVER (step over routine)

 1      DEFAULT  EXAMINE. Examines the logical successor
                 of the current entity, if one is
                 defined (the next location). (Like
                 clicking on the Current Entity down-
                 arrow button.)

        GOLD     EXAMINE ^. Examines the logical
                 predecessor of the current entity, if
                 one is defined (the previous location).
                 (Like clicking on the Current Entity
                 up-arrow button.)

        BLUE     Displays three sets of predefined
                 process-specific source and instruction
                 windows, SRC_n and INST_n: For the
                 previous, current (visible), and next
                 process on the process list.

 2      DEFAULT  SCROLL/DOWN
        GOLD     SCROLL/BOTTOM
        BLUE     SCROLL/DOWN (not terminated). To terminate
                 the command, supply the number of lines
                 to be scrolled (:n) or a window name.

 3      DEFAULT  SELECT/SCROLL %NEXTSCROLL. Selects as the
                 current scrolling window the next window
                 in the window list.

        GOLD     SELECT/OUTPUT %NEXTOUTPUT. Selects the
                 next output window in the window list as
                 the current output window.

        BLUE     Displays three predefined process-specific
                 source windows, SRC_n: for the previous,
                 current (visible), and next process on
                 the process list.

        BLUE     SELECT/SOURCE %NEXTSOURCE. Selects the
                 next source window in the window list as
                 the current source window.

 4      DEFAULT  SCROLL/LEFT
        GOLD     SCROLL/LEFT:255
        BLUE     SCROLL/LEFT (not terminated). To terminate
                 the command, supply the number of lines to
                 to be scrolled (:n) or a window name.

 5      DEFAULT  EXAM/SOURCE .%SOURCE_SCOPE\%PC; EXAM/INST
                 .%INST_SCOPE\%PC. Centers the current
                 source window on the next source line to
                 be executed, and the current instruction
                 window on the next instruction to be
                 executed. (Like choosing View Current
                 Location from the pop-up menu).

        GOLD     SHOW CALLS (Show Call Stack)
        BLUE     SHOW CALLS 3 (Show 3 levels)

 6      DEFAULT  SCROLL/RIGHT
        GOLD     SCROLL/RIGHT:255
        BLUE     SCROLL/RIGHT (not terminated). To
                 terminate the command, supply the number
                 of lines to be scrolled (:n) or a
                 window name.

 7      DEFAULT  Display SRC at left, INST at right, and
                 OUT below them, with the source,
                 instruction, and output attributes,
                 respectively. (Like choosing the second
                 layout from the Window Setups submenu.)

        GOLD     Display INST at left, REG at right, and
                 OUT below them, with the instruction,
                 and output attributes (INST and OUT).
                 (Like choosing the third layout from the
                 Window Setups submenu.)

        BLUE     Displays two sets of predefined process-
                 specific source and instruction windows,
                 SRC_n and INST_n: for the visible process
                 and for the next process on the process
                 list. (Like choosing the third layout on
                 the Multiprocess Window Setups submenu.)

 8      DEFAULT  SCROLL/UP
        GOLD     SCROLL/TOP
        BLUE     SCROLL/UP (not terminated). To terminate
                 the command, supply the number of lines
                 to be scrolled (:n) or a window name.

 9      DEFAULT  DISPLAY %NEXTDISP. Displays the next
                 window in the window list.

        GOLD     SET PROCESS/VISIBLE %NEXT_PROCESS. Makes
                 the next process in the process list the
                 visible process. (Like clicking on the
                 Visible Process right-arrow button.)

        BLUE     Displays two predefined process-specific
                 source windows, SRC_n: for the visible
                 process and for the next process on the
                 process list. (Like choosing the first
                 layout from the Multiprocess Window
                 Setups submenu.)

 PF1             Invokes the GOLD function of the next key
                 you press

 PF2    DEFAULT  Displays the DEFAULT key definitions.
        GOLD     Displays the GOLD key definitions.
        BLUE     Displays the BLUE key definitions.

 PF3    DEFAULT  Do not use in DECwindows interface
 PF3    GOLD     Do not use in DECwindows interface
 PF3    BLUE     DISPLAY/GENERATE. Regenerates the contents
                 of all automatically updated windows.

 PF4             Invokes the BLUE function of the next key
                 you press

 COMMA  DEFAULT  GO (like clicking on the Go button).

        GOLD     SELECT/SOURCE %NEXT_SOURCE. Selects the
                 next source window in the window list as
                 the current source window.

        BLUE     SELECT/INSTRUCTION %NEXTINST. Selects the
                 next instruction window in the window
                 list as the current instruction window.

 MINUS  DEFAULT  Displays the next window in the window
                 list with a larger window height.

        GOLD     Undefined

        BLUE     Displays SRC above OUT in the default
                 debugger startup configuration, with the
                 source and output attributes, respectively.
                 (Like choosing the first layout on the
                 Window Setups submenu.)

 ENTER           Enters (terminates) a command. Same
                 effect as RETURN.

 PERIOD          Cancels the effect of pressing the GOLD
                 or BLUE state keys.

 Next   DEFAULT  SCROLL/DOWN
 Screen
 (E6)

 Prev   DEFAULT  SCROLL/UP
 Screen
 (E5)

 Remove DEFAULT  DISPLAY/REMOVE %CURSCROLL. Removes the
 (E3)            current scrolling window from the
                 window list.

 Select DEFAULT  SELECT/SCROLL %NEXTSCROLL. Selects as the
 (E4)            current scrolling window the next window
                 in the window list after the current
                 scrolling window.

=title Key Designations
=include gen g_keypad g_keypad_defs
=include gen g_keypad g_default_keypad
=include gen g_keypad g_gold_keypad
=include gen g_keypad g_blue_keypad
=include gen g_cmd_mode
=include gen g_keypad
 Use the following key designations with the DEFINE/KEY
 and SHOW KEY commands:

 Key
 Designation:  Key Name:

   PF1         PF1
   PF2         PF2
   PF3         PF3
   PF4         PF4
   KP0-KP9     Keypad 0-9
   PERIOD      Keypad period (.)
   COMMA       Keypad comma (,)
   MINUS       Keypad minus (-)
   ENTER       ENTER
   E1          Find
   E2          Insert Here
   E3          Remove
   E4          Select
   E5          Prev Screen
   E6          Next Screen
   HELP        Help
   DO          Do
   F6-F20      F6-F20

=title Controlling Program Execution
=include gen g_where_exec
=include gen 2Go_Dialog_Box3g_go
=include gen 2Step_Dialog_Box3g_step
=include gen 2Break_Dialog_Box3g_breaktrace
=include gen g_watch
=include gen g_abort
=include gen g_multiproc_program_execution
The debugger enables you to perform the following tasks
 to control and monitor the execution of your program:

  -  Determine where execution is currently suspended

  -  Start or resume program execution, using the Go
     command

  -  Execute the program to the next source line,
     instruction, or other step unit, using the Step
     command

  -  Use breakpoints to suspend execution at points of
     interest

  -  Use tracepoints to trace the execution path of your
     program through specified locations

  -  Use watchpoints to monitor changes in the values of
     variables

=title Determining Where Execution is Currently Suspended
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen Scopes_Status_L_Button
=include gen g_callframe_buttons_display_src
=include gen g_callframe_buttons_display_inst
=include gen g_exec
 To determine where execution is currently suspended,
 use any of the following techniques:

  -  Look at the source window, SRC.  By default, the
     source line at which execution is suspended is
     displayed and boxed in the window, if source code
     is available for that routine.

  -  Look in the instruction window, INST, if it is
     displayed.  By default, the instruction at which
     execution is suspended is displayed and boxed in
     the window.

  -  If you have previously displayed another program
     location in the source or instruction window (so
     that it no longer shows the current location),
     choose View Current Location from the pop-up menu.
     The source line or instruction at which execution
     is suspended is displayed and boxed in the
     appropriate window.

  -  Look at the Call Frame field in the main window.
     By default, it identifies the routine in which
     execution is suspended.  The number 0 at the left
     of the routine name indicates that this is the
     routine at the top of the call stack (scope 0).

  -  Choose Call Stack...  from the Data menu to display
     the sequence of routine calls that are currently
     active on the call stack and to obtain detailed
     information about the call stack.

=title Using Watchpoints
=include gen g_exec
A watchpoint is a memory address, register, or
 (typically) a variable declared in the program whose
 value is monitored during program execution.  If the
 value changes, the debugger suspends execution and
 reports the old and new values.

 Note that you can set a watchpoint on a nonstatic
 (stack or register) variable only when program
 execution is currently suspended within the scope of
 its defining routine---that is, when the defining
 routine is active on the call stack.

 To set, identify, or cancel watchpoints, choose
 Watch...  from the Control menu.  As with breakpoints
 and tracepoints, you have several options for setting
 watchpoints.

=title Operations with Variables
=include gen 2Ex_Vbl_Dialog_Box3g_examine_var
=include gen 2Dep_Vbl_Dialog_Box3g_deposit_var
=include gen 2Show_Vbl_Dialog_Box3g_show_var
=include gen g_specifying_variables
=include gen g_selecting_variables
=include gen g_intro_to_addrexpr
=include gen g_symb
=include gen g_exdep
 The additional topics explain how to perform the
 following operations on variables and also provide
 related information:

  -  Examining (displaying the values of) variables

  -  Depositing (assigning values) into variables

  -  Obtaining information about variables and other
     symbolic address expressions (for example the path
     name or associated memory address)

=title Operations with Code Locations
=include gen 2Ex_Code_Dialog_Box3g_display_source
=include gen Ex_Code_Dialog_Box g_display_instructions
=include gen 2Dep_Code_Dialog_Box3g_deposit_code
=include gen 2Show_Vbl_Dialog_Box3g_show_var
=include gen g_specifying_code
=include gen g_selecting_code
=include gen g_intro_to_addrexpr
=include gen g_symb
=include gen g_exdep
 The additional topics explain how to perform the
 following operations on code locations (locations with
 VAX instructions) and also provide related information:

  -  Displaying the source line for a code location (for
     example, for a routine declaration)

  -  Displaying the VAX assembly-language instructions
     at a code location (for example, the instruction at
     the current PC value, where execution is suspended)

  -  Depositing VAX instructions at memory addresses or
     into registers

  -  Obtaining information about symbolic address
     expressions, such as routine names (for example the
     path name or associated memory address)

=title Operations with Addresses and Registers
=include gen 2Ex_Addr_Dialog_Box3g_examine_addreg
=include gen 2Dep_Addr_Dialog_Box3g_deposit_addreg
=include gen g_intro_to_addrexpr
=include gen g_symb
=include gen g_exdep
 The additional topics explain how to perform the
 following operations with memory addresses and
 registers and also provide related information:

  -  Examining the contents of addresses or registers

  -  Depositing values into addresses or registers

  -  Symbolizing an address or register (if a symbol is
     associated with that location)

=title Debugger Windows and Menus
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen g_create_manipul_debwnd
=include gen g_invoke_options g_invoke_startup
=include gen g_display_source
=include gen g_display_instructions
=include gen g_invoke_options
 The debugger windows consist of a main window and
 several predefined windows that capture and display
 different kinds of data.

 By default, the following windows are displayed at
 debugger startup:

   The main window
   The predefined source window SRC
   The predefined output window OUT

 Windows SRC and OUT are two examples of the kinds of
 debugger windows you can use to capture and display
 different types of data.

 Choosing Window Setups from the Customize menu in the
 main window enables you to quickly establish any of
 three useful window configurations by clicking on a
 layout.  The first layout is the default window
 configuration at debugger startup.

Additional information available:

main window

=title Debugger Main Window
=include gen Examine_Status_L_Button
=include gen Scopes_Status_L_Button
=include gen Process_Status_L_Button
=include gen g_deb_wnd_menus
 The debugger's main window includes:

  -  A menu bar.

  -  Four buttons that are labeled Go, Step, Examine,
     and Stop.

  -  Three sets of status fields and buttons that are
     labeled Current Entity, Call Frame, and Visible
     Process.

Additional information available:

Main Window Menu BarGo Step Examine Stop Buttons

=TITLE Debugger Main Window Menu Bar
=include gen g_deb_wnd_menus main_window
 The following table summarizes the functions available
 through the pull-down menus in the debugger main
 window.

  Menu      Description
  ----      -----------

  File      End the debugging session.

  Edit      Copy text to the clipboard, or paste text
            from the clipboard to a debugger dialog box
            or the COMMAND box.

  Control   Start, stop, and monitor the execution of
            your program under debugger control. For
            example: execute to the next line or to the
            next VAX assembly-language instruction; set
            breakpoints, tracepoints, and watchpoints;
            call a routine.

  Data      Display or manipulate data that is associated
            with your program. For example: examine
            variables and arbitrary program locations;
            assign new values to variables; evaluate
            language expressions; control access to
            variable names, routine names, and other
            symbols; manipulate multiprocess programs
            and Ada tasking programs. Note that the Tasks
            menu item is dimmed unless you are debugging
            a VAX Ada program.

  Customize Tailor your debugging environment and to
            establish default conditions. For example:
            create and manipulate debugger windows;
            change the programming language context;
            establish defaults for manipulating data and
            for accessing symbols; open the COMMAND box
            to access the debugger's command interface.

  Help      Obtain conceptual and task-oriented
            information about the debugger. This is an
            alternative to obtaining context-sensitive
            help on individual items that are displayed
            on the screen (menus, buttons, dialog boxes,
            and so on).

=TITLE Go, Step, Examine, and Stop Buttons in Main Window
=include gen g_deb_wnd_menus main_window
 The following table summarizes the functions of the Go,
 Step, Examine, and Stop buttons.

 Note that the functions of the Go, Step, and Examine
 buttons can also be performed through other means, such
 as the pop-up menu, Control menu, or Data menu.

  Button   Description
  ------   -----------

  Go       Start execution from the current program
           location.

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

  Examine  Display the value of a variable or other
           entity whose name is selected in a window,
           or the value of the entity last examined, if
           no text was selected.

  Stop     Interrupt program execution or a debugger
           operation.

=title Creating and Manipulating Debugger Windows
=include gen 2Wind_Dialog_Box3g_create_wnd
=include gen 2Wind_Dialog_Box3g_modify_wnd
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen g_deb_wnd_menus
=include gen g_display_source
=include gen g_display_instructions
 The debugger provides the following predefined windows
 to capture and display specific types of data:  SRC,
 OUT, AUTO, INST, and REG.

  -  SRC automatically displays the source code for the
     routine in which execution is currently suspended.

  -  OUT displays general debugger output, such as the
     value of a variable that you might be examining.
     AUTO is a special-purpose output window.

  -  INST displays the decoded VAX assembly-language
     instructions associated with your program

  -  REG displays the current register values for the
     routine in which execution is suspended.

 You can modify the predefined windows, create similar
 windows, or create automatic windows to capture and
 display specific data (for example, the current
 sequence of active routine calls).

 In addition, process-specific windows are available for
 multiprocess programs.

 To create or manipulate windows, choose Windows...
 from the Customize menu.

 The topic Overview of Window Kinds, Attributes, and
 Actions explains concepts and terminology related to
 creating and modifying windows.

=title Displaying the Predefined Windows INST, REG, and AUTO
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen 2Wind_Dialog_Box3g_predwnds g_reg
=include gen 2Wind_Dialog_Box3g_predwnds g_auto
To open windows INST or REG, choose Window Setups from
 the Customize menu.

 To open window AUTO, click on the Display button
 (instead of the OK or Apply button) in any of the
 following dialog boxes:

  -  Examine Variable (Choose Variables from the Data
     menu, then choose Examine Variable...  from the
     submenu.)

  -  Examine Address or Register (Choose Addresses or
     Registers from the Data menu, then choose Examine
     Address or Register...  from the submenu.)

  -  Language Expressions (Choose Language
     Expressions...  from the Data menu.)

 Window AUTO is displayed when you first click on the
 Display button in any one of these dialog boxes.
 Thereafter, it remains open until you close it.

 To modify these windows, choose Windows...  from the
 Customize menu.

=title Displaying Source Code
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen 2Wind_Dialog_Box3g_wind_attrib g_srcwa
=include gen g_callframe_buttons_display_src
=include gen 2Ex_Code_Dialog_Box3g_display_source
=include gen g_source_notavailable
=include gen g_source_control_files
=include gen g_symb_opt
=include gen g_display_instructions
By default, window SRC automatically displays the source
 code for the module that contains the routine in which
 execution is currently suspended.

 In addition, window SRC has the source attribute by
 default.  Therefore, you can also use SRC to display
 the source code for any part of your program---that is,
 SRC is updated by any command that you enter to display
 source code.  If no window has the source attribute,
 the output of such commands is directed at window OUT.

 You can display source code in window SRC as follows
 (if source code is available for display):

  -  You can display the source code for any routine on
     the call stack by clicking on the Call Frame arrow
     buttons in the main window.

  -  You can display arbitrary source lines in any
     module by choosing View Source...  from the
     Commands menu of window SRC.

  -  You can display the source line associated with a
     code location (for example, a routine declaration)
     by choosing Examine Code...  from the Code submenu
     of the Data menu.

 After manipulating the contents of window SRC, you can
 display the location at which execution is suspended by
 choosing View Current Location from the pop-up menu.

 If source code is not displayed or is not displayed as
 you might expect, see Making Source Code Available for
 Display for possible reasons and corrective action.

 If the program has been optimized by the compiler, the
 code that is executing as you debug might not always
 match your source code.  See Debugging Optimized Code.

=title Making Source Code Available for Display
=include gen g_display_source
=include gen g_symb_complink
=include gen g_source_control_files
=include gen g_symb_mod_set
=include gen g_specifying_code
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen g_callframe_buttons_display_src
=include gen g_symb_opt
 The topic Displaying Source Code lists the different
 ways you can display source code.

 If the debugger cannot locate source code for display,
 it issues a diagnostic message.  Source code might not
 be available for a variety of reasons.  For example:

  -  Execution is suspended within a module that was
     compiled or linked without the /DEBUG command
     qualifier.

  -  Execution is suspended within a system or shareable
     image routine for which no source code is
     available.

  -  The source file was moved to a different directory
     after it was compiled.  The location of source
     files is embedded in the object modules.

  -  The module might need to be set.

  -  You are trying to display the source code for a
     code location, but the address expression specified
     is not associated with code.  (To display the
     source code for a code location, choose Code from
     the Data menu, then choose Examine Code...  from
     the submenu).

 In the following cases, if the debugger cannot locate
 source code for display, it tries to display source
 code in the next routine down on the call stack for
 which source code is available:

  -  When window SRC is automatically displaying the
     location at which execution is suspended.

  -  When you use the Call Frame arrow buttons to
     display source code for a routine on the call
     stack.

  -  When you choose View Current Location from the
     pop-up menu.

 If the debugger can display source code for such a
 routine, it issues the following message:

    SOURCESCOPE, Source lines not available for .0\%PC.
      Displaying source in a caller of the current routine.

 In such cases, the boxed line in the source window
 identifies the line that contains code following the
 call statement in the calling routine.

 If your program has been optimized by the compiler, the
 code that is executing as you debug might not always
 match your source code.

=title Specifying the Location of Source Files
=include gen g_symb_complink
=include gen g_DST_GST_RST
=include gen g_symb_share
=include gen g_source_notavailable
=include gen g_display_source
 If a source file has been moved to a different
 directory since compile time, choose Source Files...
 from the Customize menu to specify a source directory
 search list.

 By default, the debugger expects a source file to be in
 the same directory it was in at compile time.

 The debugger displays source code only if you have
 specified the /DEBUG command with both the compile
 command and the LINK command.  Under these conditions,
 the symbol information created by the compiler and
 passed to the debug symbol table (DST) includes
 source-line correlation records.

 For a given module, source-line correlation records
 contain the full VMS file specification of each source
 file that contributes to that module.  In addition,
 they associate source records (symbols, types, and so
 on) with source files and line numbers in the module.

 When a source file is moved to another directory, the
 version number of the source file might change.  To
 locate the correct version of the source file in the
 event that a version number was not specified in the
 directory-spec parameter, the debugger inserts the
 asterisk wildcard character (*) in the version number
 field of the new file specification.  Therefore, all
 versions of the moved source file are searched until
 the correct version is located.

 The correct version of the source file is the version
 that has the same revision date and time, the same file
 size, the same record format, and the same file
 organization as the original compile-time source file.
 If the debugger does not find the correct version, it
 uses the file that has the closest revision date and
 time (if such a file exists in that directory) and
 issues a message such as the following when first
 displaying source code:

    original version of source file not found
    file used is WORK:[JONES.PROG3]PRG.FOR;14

 A full VMS file specification consists of the following
 fields:

 node::device:[directory]file-name.file-type;version-number

 If the full file specification of a source file exceeds
 231 characters, the debugger cannot locate the file.
 You can work around this problem by first defining a
 logical name "X" for your long file specification, and
 then specifying X in the Directory List field of the
 Source Files dialog box.

=title Displaying Decoded VAX Instructions
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_wind_attrib g_instwa
=include gen g_callframe_buttons_display_inst
=include gen 2Ex_Code_Dialog_Box3g_display_instructions
=include gen g_display_operands
=include gen Examine_Status_L_Button g_examine_inst_buttons
=include gen g_symb_opt
=include gen g_display_source
The predefined instruction window INST automatically
 displays the decoded VAX assembly-language instruction
 stream for the routine in which execution is currently
 suspended.

 Note that, by default, window INST is not displayed and
 does not have the instruction attribute.  See
 Displaying the Predefined Windows INST, REG, and AUTO.

 If window INST has the instruction attribute, you can
 also use it to display the instructions for any part of
 your program---that is, INST is also updated by any
 command that you enter to display instructions.  If no
 window has the instruction attribute, the output of
 such commands is directed at window OUT.

 You can display instructions in window INST as follows:

  -  You can display the instruction stream for any
     routine on the call stack by clicking on the Call
     Frame arrow buttons in the main window.

  -  You can display the instructions at a code location
     (for example, a routine declaration) by choosing
     View Instructions from the Commands menu of window
     INST, or by choosing Examine Code...  from the Code
     submenu of the Data menu.

  -  When you choose Examine Code..., you have the
     option of displaying detailed information about the
     instruction operands.

 After manipulating the contents of window INST, you can
 display the location at which execution is suspended by
 choosing View Current Location from the pop-up menu.

 The topic Examining Consecutive VAX Instructions
 explains how to use the Current Entity arrow buttons in
 the main window for that purpose.

 If the program has been optimized by the compiler, the
 code that is executing as you debug (and displayed in
 the instruction window) might not always match your
 source code.  See Debugging Optimized Code.

=title Displaying Decoded Instruction Operand Information
=include gen g_display_pc_contents
=include gen 2Ex_Code_Dialog_Box3g_display_instructions
=include gen Examine_Status_L_Button g_examine_inst_buttons
=include gen g_display_instructions
 You can display the decoded VAX assembly-language
 instructions associated with a code address expression
 (for example, a routine name) by choosing Code from the
 Data menu, then choosing Examine Code...  from the Code
 submenu.

 When using the Examine Code dialog box to display
 instructions, you can display different levels of
 information about the instruction operands.  To do so,
 use the With Operand Values button and the associated
 Full button, as explained in the next paragraphs.

 Note that you should use these buttons only when
 displaying the instruction at the current PC value.
 The information might not be reliable if you specify
 other locations.

 The PC (program counter) is the register that contains
 the address of the next instruction to be executed by
 your program.  To display the instruction at that
 address, enter .%PC in the Address Expression field of
 the Examine Code dialog box.

 The following example shows the use of the With Operand
 Values and Full buttons:

  -  By default (if the With Operand Values button is
     off), the debugger displays only the instruction
     and its operands.  For example:

      MOD3\%LINE 12:       MOVL    B^12(R11),R1

  -  To display brief operand information (address and
     contents), choose the With Operand Values option
     and turn off the Full button:

      MOD3\%LINE 12:       MOVL    B^12(R11),R1
           B^12(R11)  MOD3\K (address 1196) contains 1
           R1         R1 contains 8

  -  To display all the operand information, choose both
     the With Operand Values and the Full options:

      MOD3\%LINE 12:       MOVL    B^12(R11),R1
           B^12(R11)  R11 contains MOD3\N (address 1184),
                      B^12(1184) evaluates to MOD3\K
                      (address 1196), which contains 1
           R1         R1 contains 8

 You can establish a default level of operand
 information to be displayed whenever you examine
 instructions.  Choose Other Attributes...  from the
 Customize menu, then click on the appropriate button
 (None, Brief, or Full) under the Instruction Operand
 Information label.

 The settings of the operand-related buttons in the
 Examine Code dialog box reflect the default settings in
 the Other Attributes dialog box.

=title Specifying the Current PC Value
=include gen g_specifying_registers
=include gen g_specifying_code
=include gen g_intro_to_addrexpr
=include gen g_display_instructions
=include gen g_display_operands
 The program counter (PC) is the register that contains
 the address of the next instruction to be executed by
 the program.  The current PC value is that address.

 The current PC value is often used as an address
 expression in dialog boxes and debugger commands,
 typically Examine and Deposit.  When specifying the PC
 value as an address expression use the form .%PC.

 The period (.), when used directly in front of an
 address expression, denotes the "contents of"
 operator---that is, the contents of the location
 designated by the address expression.

 The following example illustrates the distinction
 between specifying %PC and .%PC as an address
 expression:

  -  Specifying %PC in the Address Expression field of
     the Examine Code dialog box displays the current PC
     value, namely the address of the next instruction
     to be executed.

  -  Specifying .%PC in the Address Expression field of
     the Examine Code dialog box displays the contents
     of that address, namely the next instruction to be
     executed by the program.

=title Options for Invoking the Debugger
=include gen g_end_session
=include gen g_abort
Perform the following steps before invoking the
 debugger:

 1.  Compile and link the modules of your program using
     the /DEBUG qualifier with the DCL compiler and LINK
     commands.

 2.  Make sure that the debugging configuration (default
     or multiprocess) is appropriate for the kind of
     program you are going to debug.

 You can then invoke the debugger as explained in the
 additional topics.

 Note:  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.

Additional information available:

g invoke compg invoke linkg invoke deb configg invoke invoke run
g invoke startupg invoke debugg invoke fileviewg invoke override interf

=title Compiling a Program to Prepare for Debugging
=include gen g_symb_complink
=include gen g_DST_GST_RST
=include gen g_symb_opt
=include gen g_invoke_options
 The usual way to compile a program for debugging is to
 specify the /DEBUG and /NOOPTIMIZE (or equivalent)
 qualifiers with the DCL compiler command.

 The following example shows how to compile a Pascal
 program consisting of two compilation units whose
 source code is in two separate files, FORMS.PAS and
 INVENTORY.PAS:

   $ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY

 Note:  The /DEBUG and /NOOPTIMIZE qualifiers are
 compiler command defaults for some languages.  These
 qualifiers are used in the example for emphasis.

 The /DEBUG qualifier on the compiler command (PASCAL in
 this case) directs the compiler to write the symbol
 information associated with each compilation unit into
 its object module (FORMS.OBJ and INVENTORY.OBJ, in this
 case), in addition to the code and data for the
 program.  This symbol information enables you to use
 the names of variables, routines, and other symbols
 declared in the program in debugger dialog boxes and
 commands.

 By specifying options with the /DEBUG qualifier, you
 can control the level of symbolic information provided
 (see Controlling Symbols When Compiling and Linking).
 This qualifier does not affect whether the debugger is
 invoked or how it is invoked.

 Most compilers optimize code to reduce the size of the
 program or to make it run faster.  For example,
 invariant expressions are removed from DO loops so that
 they are evaluated only once at run time; also, some
 memory locations might be allocated to different
 variables at different points in the program.

 In such cases you should compile the program with the
 /NOOPTIMIZE qualifier (or equivalent).  Otherwise, the
 contents of some program locations might be
 inconsistent with what you would expect from viewing
 the source code.  The topic Debugging Optimized Code
 describes some of the effects of optimization.

=title Linking a Program to Prepare for Debugging
=include gen g_DST_GST_RST
=include gen g_Symb_complink
=include gen g_invoke_options
 The usual way to link a program for debugging is to
 specify the command LINK/DEBUG.

 For example, to link a program consisting of the two
 object modules INVENTORY.OBJ and FORMS.OBJ, enter the
 following command:

   $ LINK/DEBUG INVENTORY, FORMS

 The /DEBUG qualifier on the LINK command does the
 following:

  -  Copies the debugger symbol information from the
     object modules being linked into the debug symbol
     table (DST) and puts the DST in the executable
     image.

  -  Directs the image activator to pass control to the
     debugger when you subsequently execute the image
     with the RUN command.

 See Controlling Symbols When Compiling and Linking for
 more details on how the LINK command controls symbol
 information.

 Even if you have compiled and linked 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 INVENTORY

 This is convenient for checking your program after you
 think it is error free.  But the data required by the
 debugger still 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.

 The following table summarizes how to control debugger
 activation by means of LINK and RUN command qualifiers.
 Note that the LINK command qualifiers /[NO]DEBUG and
 /[NO]TRACEBACK affect not only debugger activation but
 also the level of symbolic information provided:

                                                Maximum
                Command To    Command To        Symbolic
  LINK Command  Run Program   Run Program       Information
  Qualifier     With Debugger Without Debugger  Available
  ------------  ------------- ----------------  -----------

  /DEBUG        RUN           RUN/NODEBUG       Full

  /TRACEBACK    RUN/DEBUG     RUN               Only
  or /NODEBUG                                   traceback

  /NOTRACEBACK  Cannot        RUN               None

=title Establishing the Debugging Configuration
=include gen g_multiproc
=include gen g_debug_config
=include gen g_builtin_log dbg_process
=include gen g_invoke_options
 Before invoking the debugger, check that the debugging
 configuration is appropriate for the kind of program
 you are going to debug.

 You can invoke the debugger in either the default
 configuration or the multiprocess configuration to
 debug programs that run in either one or several
 processes, respectively.  The configuration depends on
 the current definition of the logical name DBG$PROCESS.
 Thus, before invoking the debugger, enter the DCL
 command SHOW LOGICAL DBG$PROCESS to determine the
 definition of DBG$PROCESS.  (Or choose Logical Names...
 from the FileView Control menu).

 For programs that run in only one process, DBG$PROCESS
 either should be undefined, as in the following
 example, or should have the value DEFAULT:

   $ SHOW LOGICAL DBG$PROCESS
   NOTRAN, no translation for logical name DBG$PROCESS

 If DBG$PROCESS has the value MULTIPROCESS and you want
 to debug a program that runs in only one process, enter
 the following command:

   $ DEFINE DBG$PROCESS DEFAULT

=title Invoking the Debugger with the DCL RUN command
=include gen g_invoke_options g_invoke_comp
=include gen g_invoke_options g_invoke_link
=include gen g_invoke_options g_invoke_deb_config
=include gen g_invoke_options g_invoke_startup
=include gen g_invoke_options
 Before you can invoke the debugger, you must compile
 and link your program and establish the debugging
 configuration as explained in the additional topics.

 To invoke the debugger from a DECterm window, enter the
 DCL command RUN, specifying the executable image of
 your program as the parameter.

 For example, enter the following command to debug
 program INVENTORY:

   $ RUN INVENTORY

=title Debugger Startup Conditions
=include gen g_Multilang multilang_set_lang
=include gen g_invoke_options g_invoke_debug
=include gen g_init_file
=include gen g_source_notavailable
=include gen g_Deb_Wnd_Menus
=include gen g_invoke_options
When you invoke the debugger, it comes up in the
 following three windows, by default:

   The main window
   The predefined source window SRC
   The predefined output window OUT

 These and other debugger windows are described in
 detail in the topic Debugger Windows and Menus.

 Upon taking control of the program, the debugger
 performs the following steps:

 1.  Sets the language-dependent parameters to the
     source language of the main program (the module
     containing the image transfer address).  The topic
     Controlling the Current Debugger Language gives an
     overview of language-dependent parameters.

 2.  Issues a message in window OUT identifying the
     language to which the debugging session is
     initialized and the name of the main program.  For
     example:

     INITIAL, language is PASCAL, module set to INVENTORY

     Note:  When you invoke the debugger with the DCL
     DEBUG command, the current language is set to the
     source language of the routine in which execution
     is suspended upon interruption.

 3.  Executes the debugger initialization file, if any
     has been defined.

 4.  Suspends execution at the start of the main
     program.

 5.  Displays the source code for the main program in
     window SRC.  The boxed line in SRC indicates where
     execution is currently suspended.

 If the debugger cannot display source code, it issues a
 message.  See Making Source Code Available for Display.

 For Ada programs and certain other kinds of programs,
 the debugger suspends execution at the beginning of
 initialization code, before the main program, so that
 you can choose to execute that code under debugger
 control.  In such cases, the debugger displays the
 following message:

   NOTATMAIN, type GO to get to start of main program

 In such cases, click on the Go button in the main
 window to execute to the beginning of the main program.
 See your language documentation for more information.

=title Invoking the Debugger with the DCL DEBUG Command
=include gen g_invoke_options g_invoke_comp
=include gen g_invoke_options g_invoke_link
=include gen g_invoke_options g_invoke_deb_config
=include gen g_invoke_options g_invoke_startup
=include gen g_builtin_ssdebug
=include gen g_invoke_options
 Before you can invoke the debugger, you must compile
 and link your program and establish the debugging
 configuration as explained in the additional topics.

 You can invoke the debugger while your program is
 executing freely (for example, if you suspect that the
 program might be in an infinite loop or if you see
 erroneous output).

 To invoke the debugger in this manner, proceed as
 follows:

 1.  Enter the DCL command RUN/NODEBUG to execute the
     program without debugger control.

 2.  Press CTRL/Y to interrupt the executing program.
     Control then passes to the DCL command interpreter.

 3.  Enter the DCL command DEBUG to activate the
     debugger.  When the debugger comes up, it displays
     the main, source, and output windows, sets the
     current language to the source language of the
     routine where execution was interrupted, and
     executes any user-defined initialization file.

     To help you identify where execution was
     interrupted, look at the source window and choose
     Call Stack...  from the Data menu to identify the
     sequence of routine calls on the call stack.

     See Debugger Startup Conditions for information
     about the state of the debugging session at
     startup.

 For example:

   $ PASCAL/DEBUG/NOOPTIMIZE FORMS,INVENTORY
   $ LINK/DEBUG INVENTORY,FORMS
   $ RUN/NODEBUG INVENTORY
      .
      .
   <CTRL/Y>
   Interrupt
   $ DEBUG

 Interrupting a running program with CTRL/Y and then
 invoking the debugger with the DEBUG command is useful
 under the following conditions:

  -  Your program is in an infinite loop.

  -  After entering the RUN/NODEBUG command, you decide
     that you want debugger control.

  -  You have not specified the /DEBUG command qualifier
     at compile time, link time, or run time but want to
     debug your running program.  In this case,
     traceback information is the only symbolic
     information available for debugging.

=title Invoking the Debugger From a FileView Window
=include gen g_invoke_options g_invoke_comp
=include gen g_invoke_options g_invoke_link
=include gen g_invoke_options g_invoke_deb_config
=include gen g_invoke_options g_invoke_startup
=include gen g_invoke_options
 Before you can invoke the debugger, you must compile
 and link your program and establish the debugging
 configuration as explained in the additional topics.

 Then, to invoke the debugger from a FileView window,
 proceed as follows:

 1.  Choose Run from the FileView Files menu.  A dialog
     box is displayed.

 2.  Specify the executable image file to be debugged

 3.  Choose the Debug option

 4.  Click on OK

=title Overriding the Debugger's Default Interface
=include gen g_invoke_options g_invoke_comp
=include gen g_invoke_options g_invoke_link
=include gen g_invoke_options g_invoke_deb_config
=include gen g_builtin_log DBG_DECW_DISPLAY
=include gen g_cmd_mode
=include gen g_invoke_options g_invoke_startup
=include gen g_Deb_Wnd_Menus
=include gen g_invoke_options
 By default, if your workstation is running VMS
 DECwindows, the debugger comes up in the DECwindows
 interface on the workstation specified by the
 DECwindows application-wide logical name DECW$DISPLAY.

 The additional topics explain how to override the
 debugger's default DECwindows interface to achieve the
 following:

  -  Invoke the debugger's command interface from a
     DECterm window

  -  Display the debugger's DECwindows interface on
     another workstation

 In the same way that the logical names DBG$INPUT and
 DBG$OUTPUT enable you to override the device that the
 debugger uses for input and output, the logical name
 DBG$DECW$DISPLAY enables you to override the default
 interface of the debugger.  Note that, in most cases,
 there is no need to define DBG$DECW$DISPLAY, because
 the default implies the desired action.

 The topic Explanation of DBG$DECW$DISPLAY and
 DECW$DISPLAY provides more information about these
 logical names

 Before you can invoke the debugger, you must compile
 and link your program and establish the debugging
 configuration as explained in the additional topics.

Additional information available:

g invoke cmdg invoke dif workstationsg invoke decwdisplay

=title Invoking the Debugger's Command Interface
=include gen g_cmd_mode
=include gen g_invoke_options
=include gen g_builtin_log DBG_DECW_DISPLAY
=include gen g_invoke_options g_invoke_override_interf
 To invoke the debugger's command interface from a
 DECterm window, proceed as follows:

 1.  Enter the following definition in the DECterm
     window from which you plan to run the program:

       $ DEFINE/JOB DBG$DECW$DISPLAY " "

     You can specify one or more space characters
     between the quotation marks.  It is recommended
     that you use a job definition for the logical name.
     If you use a process definition, it must not have
     the CONFINE attribute.

 2.  Run the program from that DECterm window.  The
     debugger's command interface comes up in the same
     window.

 For example:

   $ DEFINE/JOB DBG$DECW$DISPLAY " "
   $ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY
   $ LINK/DEBUG INVENTORY, FORMS
   $ RUN INVENTORY

            VAX DEBUG Version 5.2

   INITIAL, language is PASCAL, module set to INVENTORY
   DBG>

=title Displaying Debugger Interface on Another Workstation
=include gen g_invoke_options
=include gen g_builtin_log DBG_DECW_DISPLAY
=include gen g_invoke_options g_invoke_override_interf
 If you are debugging a DECwindows application that uses
 most of the screen, you might find it useful to run the
 program on one workstation and display the debugger's
 DECwindows interface on another.  To do so, proceed as
 follows:

 1.  Enter a logical definition with the following
     syntax in the DECterm window from which you plan to
     run the program:

       DEFINE/JOB DBG$DECW$DISPLAY workstation_pathname

     where workstation_pathname is the path name for the
     workstation where the debugger's DECwindows
     interface is to come up.  See the description of
     the SET DISPLAY command in the VMS DCL Dictionary
     for the syntax of this path name.

     It is recommended that you use a job definition.
     If you use a process definition, it must not have
     the CONFINE attribute.

 2.  Run the program from that DECterm window.  The
     debugger's DECwindows interface comes up on the
     workstation specified by DBG$DECW$DISPLAY.  The
     application's windowing interface comes up on the
     workstation display where it normally does.

=title Explanation of DBG$DECW$DISPLAY and DECW$DISPLAY
=include gen g_builtin_log DBG_DECW_DISPLAY
=include gen g_invoke_options g_invoke_override_interf
 By default, if your workstation is running DECwindows,
 the debugger comes up in the DECwindows interface on
 the workstation specified by the DECwindows
 application-wide logical name DECW$DISPLAY.
 DECW$DISPLAY is defined in the job table by FileView or
 DECterm.  It points to the display device for the
 workstation.

 For information on DECW$DISPLAY, see the description of
 the DCL commands SET DISPLAY and SHOW DISPLAY in the
 VMS DCL Dictionary.

 The logical name DBG$DECW$DISPLAY is the
 debugger-specific equivalent of DECW$DISPLAY.
 DBG$DECW$DISPLAY is analogous to the debugger-specific
 logical names DBG$INPUT and DBG$OUTPUT.  These enable
 you to reassign SYS$INPUT and SYS$OUTPUT, respectively,
 to specify the device on which the debugger input and
 output are to appear.

 The default user interface of the debugger results when
 DBG$DECW$DISPLAY is undefined or has the same
 translation as DECW$DISPLAY.  By default,
 DBG$DECW$DISPLAY is undefined.

 The algorithm that the debugger follows when using the
 logical definitions of DECW$DISPLAY and
 DBG$DECW$DISPLAY is as follows:

 1.  If the logical name DBG$DECW$DISPLAY is defined,
     then use it.  Otherwise, use the logical name
     DECW$DISPLAY.

 2.  Translate the logical name.  If its value is not
     null (if the string contains characters other than
     space characters), then the DECwindows interface
     comes up on the specified workstation.  If the
     value is null (if the string consists only of space
     characters), then the command interface comes up in
     the DECterm window.

=title Ending a Debugging Session
=include gen g_exit_handlers
=include gen g_multiproc_termination
=include gen g_multiproc
=include gen g_invoke_options
=include gen g_abort
To end a debugging session, choose either Exit or Quit
 from the File menu in the main window.

 If your program has application-declared exit handlers,
 Exit executes these handlers.  Quit gives you the
 option of executing application-declared exit handlers
 (a dialog box is displayed in such cases).

 Unless you are debugging a multiprocess program, you
 can also end the debugging session by choosing Exit or
 Quit from any debugger window (not just the main
 window).

 For multiprocess programs, choosing Exit or Quit from a
 debugger window other than the main window has the
 following effect:

  -  If the window is not process specific, terminates
     the visible process

  -  If the window is process specific, terminates the
     process associated with that window

 You can also end a multiprocess debugging session or
 terminate individual processes by choosing the Exit
 option from the Processes dialog box (Data menu).

 The following message, displayed in the output window
 during a debugging session, indicates that your program
 has completed normally:

 EXITSTATUS, is '%SYSTEM-S-NORMAL, normal successful completion'

 If you want to continue debugging after seeing this
 message, it is usually best to end the session and
 start a new one.  You can restart execution from within
 the debugging session (by choosing Go...  from the
 Control menu and then specifying a location in the Go
 dialog box).  However, this technique can produce
 unexpected results if, for example, some variables have
 different values from when you first ran the program.

=title Interrupting Commands or Program Execution
=include gen g_where_exec
=include gen g_invoke_options
=include gen g_end_session
To interrupt program execution during a debugging
 session, click on the Stop button in the main window.
 This is useful if, for example, the program is in an
 infinite loop.

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

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

=title Using Debugger Command Procedures
=include gen g_Cmd_Mode
=include gen g_cmd_mode cmd_format
=include gen g_init_file
=include gen g_log_file
A debugger command procedure is a sequence of commands
 contained in a file.

 You can direct the debugger to execute a command
 procedure to recreate a debugging session, to continue
 a previous session, or to avoid typing the same
 debugger commands many times during a debugging
 session.  You can pass parameters to command
 procedures.

 Debugger command procedures are especially useful when
 you regularly perform a number of standard set-up
 debugger commands, as specified in a debugger
 initialization file.  You can also use a debugger log
 file as a command procedure.

Additional information available:

create cmd procexec cmd procPassing Parameters

=TITLE Entering Commands in Command Procedures
=include gen g_cmd_mode cmd_format
=include gen g_cmd_prcdrs exec_cmd_proc
=include gen g_cmd_prcdrs Passing_Parameters
=include gen g_cmd_prcdrs
=include gen g_cmd_mode
 The following is a sample debugger command procedure
 named BREAK7.COM:

   ! ***** Debugger Command Procedure BREAK7.COM *****
   !
   SET BREAK/AFTER:3 %LINE 120 DO (EXAMINE K,N,J,X(K); GO)
   SET BREAK/AFTER:3 %LINE 160 DO (EXAMINE K,N,J,X(K),S; GO)
   SET BREAK %LINE 90

 When you execute this command procedure with the
 execute procedure (@) command, the commands listed in
 the procedure are executed in the order they appear.

 The rules for entering commands in debugger command
 procedures are as follows:

 To maximize legibility, it is best not to abbreviate
 command keywords in a command procedure.  Do not
 abbreviate command keywords to fewer than four
 significant characters (not counting the negation
 /NO...), to avoid potential conflicts in future
 releases.

 Start a debugger command line at the left margin.  (Do
 not start a command line with a dollar sign ($) as you
 do when writing a DCL command procedure).

 The start of a new line ends the previous command line
 (the end-of-file character also ends the previous
 command line).  To continue a command string on another
 line, type a hyphen (-) before starting the new line.

 You can enter more than one command string on one line
 by separating command strings with semicolons (;).

 To enter a comment (explanatory text that does not
 affect the execution of the command procedure), precede
 the comment text with an exclamation point (!).  If the
 comment wraps to another line, start that line with an
 exclamation point.

=title Executing a Debugger Command Procedure
=include gen g_cmd_mode
=include gen g_init_file
=include gen g_log_file
=include gen g_cmd_prcdrs create_cmd_proc
=include gen g_cmd_prcdrs Passing_Parameters
=include gen g_cmd_prcdrs
 To execute a debugger command procedure:

  -  Choose Show Command...  from the Customize menu to
     open the COMMAND box.

  -  At the DBG> prompt in the COMMAND box, enter an at
     sign (@) followed by the file specification of the
     command procedure.


 If you do not supply a full file specification with the
 @ command, the debugger assumes SYS$DISK:[]DEBUG.COM as
 the default file specification for command procedures.

 For example, you would enter the following command line
 to execute command procedure BREAK7.COM, located in
 your current default directory:

   DBG> @BREAK7

 The SET ATSIGN command (entered in the COMMAND box)
 enables you to change any or all fields of the default
 file specification, SYS$DISK:[]DEBUG.COM.  The command
 SHOW ATSIGN identifies the default file specification
 for command procedures.

 By default, commands read from a command procedure are
 not echoed.  To echo commands in the current output
 window as they are read from a command procedure,
 proceed as follows:

 1.  Choose Logging...  from the Customize menu

 2.  Choose the Include I/O from Command Procedures
     option

 3.  Click on OK or Apply

 If the execution of a command in a command procedure
 results in a diagnostic of severity "warning" or
 greater, the command is aborted, but execution of the
 command procedure continues at the next command line.

=TITLE Passing Parameters to Command Procedures
=include gen g_builtin_parcnt
=include gen g_cmd_prcdrs create_cmd_proc
=include gen g_cmd_prcdrs exec_cmd_proc
=include gen g_cmd_prcdrs
 As with DCL command procedures, you can pass parameters
 to debugger command procedures.  However, the technique
 is different in several respects.

 Subject to the conventions described here, you can pass
 as many parameters as you want to a debugger command
 procedure.  The parameters can be address expressions,
 commands, or value expressions in the current language.
 You must surround command strings in quotation marks
 ("), and you must separate parameters by commas (,).

 A debugger command procedure to which you pass
 parameters must contain a DECLARE command line that
 binds each actual (passed) parameter to a formal
 parameter (a symbol) declared within the command
 procedure.

 The DECLARE command is valid only within a command
 procedure.  Its format is as follows:

   DECLARE p-name:p-kind [,p-name:p-kind [,...]]

 Each p-name:p-kind pair associates a formal parameter
 (p-name) with a parameter kind (p-kind).  The valid
 p-kind keywords are as follows:

  ADDRESS    The actual parameter is interpreted
             as an address expression.

  COMMAND    The actual parameter is interpreted
             as a command.

  VALUE      The actual parameter is interpreted
             as a value expression in the current
             language.

 The following example illustrates what happens when a
 parameter is passed to a command procedure.  The
 command DECLARE K:ADDRESS, within command procedure
 EXAM.COM, declares the formal parameter K.  The actual
 parameter passed to EXAM.COM is interpreted as an
 address expression.  The command EXAMINE K displays the
 value of that address expression.  The command SET
 OUTPUT VERIFY causes the commands to echo when they are
 read by the debugger.

   ! ***** Debugger Command Procedure EXAM.COM *****
   SET OUTPUT VERIFY
   DECLARE K:ADDRESS
   EXAMINE K

 The next command line executes EXAM.COM, passing the
 actual parameter ARR4.  Within EXAM.COM, ARR4 is
 interpreted as an address expression (an array
 variable, in this case).

   DBG> @EXAM ARR4
   %DEBUG-I-VERIFYIC, entering command procedure EXAM
   DECLARE K:ADDRESS
   EXAMINE K
   PROG_8\ARR4
       (1):        18
       (2):        1
       (3):        0
       (4):        1
   %DEBUG-I-VERIFYIC, exiting command procedure EXAM
   DBG>

 Each p-name:p-kind pair specified by a DECLARE command
 binds one parameter.  So, for instance, if you want to
 pass five parameters to a command procedure, you need
 five corresponding p-name:p-kind pairs.  The pairs are
 always processed in the order in which you specify
 them.

 For example, the next command procedure, EXAM_GO.COM
 accepts two parameters:  an address expression (L) and
 a command string (M).  The address expression is then
 examined and the command is executed:

   ! ***** Debugger Command Procedure EXAM_GO.COM *****
   DECLARE L:ADDRESS, M:COMMAND
   EXAMINE L; M

 The following example shows how you could execute
 EXAM_GO.COM, passing a variable X to be examined and a
 command @DUMP.COM to be executed:

   DBG> @EXAM_GO X, "@DUMP"

 The %PARCNT built-in symbol, which you can use only
 within a command procedure, enables you to pass a
 variable number of parameters to a command procedure.
 The value of %PARCNT is the number of actual parameters
 passed to the command procedure.

 The %PARCNT built-in symbol is illustrated in the
 following example.  The command procedure, VAR.DBG,
 contains the following lines:

   ! ***** Debugger Command Procedure VAR.DBG *****
   SET OUTPUT VERIFY
   ! Display the number of parameters passed:
   EVALUATE %PARCNT
   ! Loop as needed to bind all passed parameters
   ! and obtain their values:
   FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)

 The following command line executes VAR.DBG, passing
 the parameters 12, 37, and 45:

   DBG> @VAR.DBG 12,37,45
   %DEBUG-I-VERIFYIC, entering command procedure VAR.DBG
   ! Display the number of parameters passed:
   EVALUATE %PARCNT
   3
   ! Loop as needed to bind all passed parameters
   ! and obtain their values:
   FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
   12
   37
   45
   %DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
   DBG>

 When VAR.DBG is executed, %PARCNT has the value 3.
 Therefore, the FOR loop within VAR.DBG is repeated 3
 times.  The FOR loop causes the DECLARE command to bind
 each of the three actual parameters (starting with 12)
 to a new declaration of X.  Each actual parameter is
 interpreted as a value expression in the current
 language, and the command EVALUATE X displays that
 value.

=TITLE Using a Debugger Initialization File
=include gen g_cmd_mode cmd_format
=include gen g_cmd_prcdrs
=include gen g_builtin_log DBG_INIT
You can create an initialization file containing
 debugger commands to set your default debugging modes,
 debugger window characteristics, and so on.  When you
 invoke the debugger, those commands are executed
 automatically to tailor your debugging environment.

 A debugger initialization file is a command procedure,
 assigned the logical name DBG$INIT, that the debugger
 automatically invokes at debugger start up.

 For example, you might have a file DEBUG_START4.COM
 containing the following commands:

   ! *** Debugger Initialization File DEBUG_START4.COM ***
   ! Log debugging session into the
   ! default log file (SYS$DISK:[]DEBUG.LOG)
   SET OUTPUT LOG
   !
   ! Echo commands as they are read from command procedures:
   SET OUTPUT VERIFY
   !
   ! If source files are not in current default directory,
   ! use [SMITH.SHARE]
   SET SOURCE [],[SMITH.SHARE]
   !
   ! Set all modules:
   SET MODULE/ALL
   !
   ! Assign the command SHOW MODULE * to keypad key 7:
   DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *"

 To make this file a debugger initialization file, use
 the DCL command DEFINE.  For example:

 $ DEFINE DBG$INIT WORK:[JONES.DBGCOMFILES]DEBUG_START4.COM

=TITLE Logging a Debugging Session into a File
=include gen g_cmd_mode cmd_format
=include gen g_cmd_prcdrs
=include gen g_cmd_mode
You can record in a log file the debugger commands that
 result from your actions during a debugging session,
 and the debugger's responses to those commands.  You
 can use log files to keep track of your debugging
 efforts, or you can use them as command procedures in
 subsequent debugging sessions.

 To create a debugger log file, choose Logging...  from
 the Customize menu.  By default, the debugger writes
 the log to SYS$DISK:[]DEBUG.LOG.  You can specify
 another file specification for the log file.

 You might want to enter the command SET OUTPUT LOG in
 your debugger initialization file to automatically
 enable logging.

 When you use the debugger's DECwindows interface, each
 of your actions results in one or more debugger
 commands.  These commands are echoed in the COMMAND
 box, by default.

 You can record in a log file the debugger commands that
 you enter directly or indirectly during a debugging
 session and the debugger's responses to those commands.
 You can use log files to keep a record of your
 debugging sessions, or you can use them as command
 procedures in subsequent sessions.

 The following is an example of a debugger log file.

   SET STEP NOSOURCE
   SET TRACE %LINE 30
   SET BREAK %LINE 60
   SHOW TRACE
   !tracepoint at PROG4\%LINE 30
   GO
   !trace at PROG4\%LINE 30
   !break at PROG4\%LINE 60
      .
      .

 The debugger output is commented out with exclamation
 marks so you can use the file as a debugger command
 procedure without modification.  Thus, if a lengthy
 debugging session is interrupted, you can execute the
 log file as you would any other debugger command
 procedure.  Executing the log file restores the
 debugging session to the point at which it was
 previously terminated.

 If you plan to use a log file as a command procedure,
 you should first choose the option Include I/O from
 Command Procedures in the Logging dialog box, so that
 debugger commands are echoed as they are read.

=title Specifying and Evaluating Language Expressions
=include gen g_langexpr_addr_comp
=include gen g_langexpr_vrbl
=include gen g_langexpr_vrbl_type_conv
=include gen g_lang
=include gen g_multilang
=include gen g_builtin_curvalue
=include gen g_radix
A language expression consists of any combination of one
 or more symbols, literals, and operators that is
 evaluated to a single value in the syntax of the
 current language and in the current radix.

 To evaluate a language expression, choose Language
 Expressions...  from the Data menu, then specify the
 language expression in the Language Expression field of
 the dialog box.

 One use of the Language Expressions dialog box is as a
 calculator, to perform arithmetic calculations that
 might be unrelated to your program.  For example, if
 you specify (8+12)*6/4 in the Language Expression
 field, the debugger displays the calculated value, 30.

 The debugger recognizes the operators and expression
 syntax of the current language.  For example, if your
 program has an integer variable named WIDTH, the
 debugger evaluates the expression WIDTH+7 by adding 7
 to the current value of WIDTH.

 The debugger evaluates language expressions implicitly
 in the following contexts:

  -  When you assign (deposit) a value to a variable or
     other address expression.

  -  When the debugger processes a conditional
     breakpoint, tracepoint, or watchpoint.

  -  When you use debugger commands that evaluate
     language expressions (EVALUATE, DEPOSIT, IF,
     REPEAT, and so on).

 The debugger uses the rules of operator precedence of
 the current language when evaluating language
 expressions.

 If an expression contains symbols with different
 compiler-generated types, the debugger uses the
 type-conversion rules of the current language to
 evaluate the expression.  If the types are
 incompatible, a diagnostic message is issued.

=title Using Variables in Language Expressions
=include gen g_langexpr
 You can use variables in language expressions in much
 the same way that you use them in the source code of
 your program.

 Thus, the debugger generally interprets a variable used
 in a language expression as the current value of that
 variable, not the address of the variable.  For
 example, if X is an integer variable, the debugger
 evaluates X+4 by adding the value of X to 4.

 Note that the use of a variable in a language
 expression is generally limited to single-valued,
 nonstructured variables.  Typically, you can specify a
 multi-valued, structured variable (like an array or
 record) in a language expression only if the syntax
 indicates that you are referencing only a single value
 (a single element of the structure).  For example, if
 ARR is the name of an array of integers, then:

  -  You can specify ARR(2), or the expression 5+ARR(2),
     in the Language Expression field of a dialog box.

  -  You cannot specify ARR in the Language Expression
     field.

 Note also that, if the current language is BLISS, the
 debugger interprets a variable in a language expression
 as the address of that variable.  To denote the value
 stored in a variable, you must precede the variable
 name with the contents-of operator (period (.)).  For
 example, if Y is an integer variable and the language
 is set to BLISS, then:

  -  The debugger evaluates the language expression Y+4
     by adding 4 to the address of Y

  -  The debugger evaluates the language expression .Y+4
     by adding 4 to the value of Y

=title Numeric Type Conversion by the Debugger
=include gen g_langexpr
 When evaluating language expressions involving numeric
 types of different precision, the debugger first
 converts lower-precision types to higher-precision
 types before performing the evaluation.

 For example, when evaluating the expression 1.5+1, the
 debugger converts the integer 1 to the real 1.0 before
 doing the addition.  The result displayed is 2.5, in
 this case.

 The basic rules are as follows.  If integer and real
 types are mixed, the integer type is converted to the
 real type.  If integer types of different sizes are
 mixed (for example, byte-integer and word-integer), the
 one with the smaller size is converted to the larger
 size.  If real types of different sizes are mixed (for
 example, G_float and H_float), the one with the smaller
 size is converted to the larger size.

 In general, the debugger allows more numeric type
 conversion than the programming language.  In addition,
 the hardware type used for a debugger calculation
 (word, longword, G_float, and so on) might differ from
 that chosen by the compiler.  Because the debugger is
 not as strongly typed or as precise as some languages,
 the evaluation of an expression by the debugger might
 differ from the result that would be calculated by
 compiler-generated code and obtained by, for example,
 choosing Examine Variable from the Data menu.

=title Address Expressions Compared to Language Expressions
=include gen g_intro_to_addrexpr
=include gen g_langexpr
 An address expression denotes a memory address or a
 register.  A language expression specifies a value
 rather than a location in memory or a register.

 For example, assume X is an integer variable whose
 current value is 9 and whose memory address is 274903.
 Then:

  -  The language expression X+6 denotes the sum of the
     current value of X and 6 (that is 9+6, or 15).

  -  The address expression X+6 denotes the memory
     address that is 6 bytes beyond the address of X
     (that is, the address 274903+6)

=title Controlling the Radix for Integer Data
=include gen g_langexpr_addr_comp
 The debugger can interpret and display integer data in
 any one of four radixes:  decimal, hexadecimal, octal,
 and binary.  The default radix for both data entry and
 display is decimal for all languages except BLISS and
 MACRO.  It is hexadecimal for BLISS and MACRO.

 You can control the radix for the following kinds of
 integer data:

  -  Data that you specify in language expressions or
     address expressions.  The radix for data entry is
     called the input radix.

  -  Data that is displayed when you evaluate a language
     expression or examine a variable or other address
     expression.  The radix for data display is called
     the output radix.

 You cannot control the radix for other kinds of integer
 data.  For example, addresses are always displayed in
 hexadecimal radix in a call stack display (obtained by
 choosing Call Stack...  from the Data menu); and you
 must use decimal radix when specifying an integer in a
 context other than a language expression or an address
 expression (for example, in the After field of the
 Break dialog box).

 You can control the input radix independently of the
 output radix.

 The technique you use to control radix depends on your
 objective:

  -  To establish another input radix or output radix,
     choose Radix...  from the Customize menu.  The
     option menus of the Radix dialog box show the
     current settings for the input radix and output
     radix.

  -  The topic Entering Integer Data in Another Radix
     explains how to override the current input radix
     temporarily to enter data in another radix

  -  The topic Displaying Integer Data in Another Radix
     explains how to override the current output radix
     temporarily to display data in another radix

 Note:  When specifying a hexadecimal integer that
 starts with a letter rather than a number, precede the
 integer with a zero.  Otherwise, the debugger tries to
 interpret the integer as a symbol declared in your
 program.  For example specify the integer A34D as
 0A34D.

Additional information available:

g radix inputg radix output

=title Entering Integer Data in Another Radix
=include gen g_builtin_builtin
=include gen g_radix
 To enter one or more integer literals in another radix,
 temporarily overriding the current input radix, use one
 of the radix built-in symbols %BIN, %DEC, %HEX, or
 %OCT.

 A radix built-in symbol directs the debugger to treat
 an integer literal that follows (or all integer
 literals in a parenthesized expression that follows) as
 a binary, decimal, hexadecimal, or octal number,
 respectively.  These symbols do not affect the radix
 for data display.

 For example:

  -  %BIN 10 evaluates to the decimal value 2

  -  %HEX(10+10) evaluates to the decimal value 32

  -  %HEX 20 + 33 evaluates to the decimal value 65

=title Displaying Integer Data in Another Radix
=include gen g_radix
 To display the value of an integer language expression
 (for example, X+5 or 12*7) in another radix, proceed as
 follows:

 1.  Choose Language Expressions...  from the Data menu

 2.  Specify the integer expression to be evaluated in
     the Language Expression field

 3.  Choose the output radix from the Radix option menu

 4.  Click on OK or Apply

 To display the value of an integer variable in another
 radix, proceed as follows:

 1.  Choose Variables from the Data menu, then choose
     Examine Variable...  from the submenu

 2.  Specify the variable name in the Variable field

 3.  Choose the output radix from the Radix option menu

 4.  Click on OK or Apply

 To display an integer value at an address or register
 in another radix, proceed as follows:

 1.  Choose Addresses or Registers from the Data menu,
     then choose Examine Address or Register...  from
     the submenu

 2.  Specify the address or register in the Variable
     field

 3.  Choose the output radix from the Radix option menu

 4.  Click on OK or Apply

 The concept of radix applies strictly to integer data.
 However, note that you can also use the Radix option
 menus of the Language Expressions, Examine Variable,
 and Examine Address or Register dialog boxes to display
 noninteger data as integer data in a particular radix.
 This enables you to determine the contents of memory as
 integer data in that radix.

=title Debugging Exceptions and Condition Handlers
=include gen g_builtin_exceptions
A condition handler is a procedure that the VMS
 operating system executes when an exception condition
 (an exception) occurs.

 Exceptions include hardware exceptions (such as an
 arithmetic overflow or a memory access violation) or
 signaled software exceptions (for example, an exception
 signaled because a file could not be found).

 The following examples of exceptions could be generated
 by your program:  an arithmetic overflow or underflow,
 a memory access violation, an invalid operation code, a
 division by zero.

 VMS conventions specify how, and in what order, various
 condition handlers set up by the operating system, the
 debugger, or your own program are invoked---for
 example, the primary handler, call frame
 (application-declared) handlers, and so on.

 See the VMS Run-Time Library Routines Volume for
 additional information on condition handling.

 The debugger provides the following tools for debugging
 exceptions and condition handlers:

  -  You can set breakpoints or tracepoints on
     exceptions, and also on exception-related events in
     the case of Ada programs (choose Break...  from the
     Control menu).

  -  You can use several built-in symbols (such as
     %EXC_NAME) to qualify exception breakpoints and
     tracepoints.

Additional information available:

excep breakexcep resume execexcep cond handl

=title Setting Breakpoints or Tracepoints on Exceptions
=include gen 2Break_Dialog_Box3g_breaktrace
=include gen g_excep
 An exception breakpoint or tracepoint is one that was
 set using the 'every exception' option on the Target
 (upper-right) option menu of the Break dialog box.  To
 open the dialog box, choose Break...  from the Control
 menu.

 When you set an exception breakpoint or tracepoint, you
 direct the debugger to treat any exception generated by
 your program as a breakpoint (or tracepoint).  As a
 result, if your program generates an exception, the
 debugger suspends execution and reports the exception
 and the line at which execution is suspended.

 The following example illustrates the effect of setting
 an exception breakpoint:

   [Enter Go command]
    ...
   %SYSTEM-F-INTDIV, arithmetic trap, integer divide by
       zero at PC=0000066C, PSL=03C00022
   break on exception preceding TEST\%LINE 13
        6:         X := 3/Y;

 Note that an exception breakpoint (or tracepoint) is
 triggered even if your program has a condition handler
 to handle the exception.  An exception breakpoint
 causes a breakpoint to occur before any handler can
 execute (and thereby possibly dismiss the exception).
 Without the exception breakpoint, the handler would be
 executed, and the debugger would get control only if no
 handler dismissed the exception.

 An exception tracepoint is like an exception breakpoint
 followed by a Go command without an address expression
 specified.  An exception breakpoint cancels an
 exception tracepoint, and vice versa.

=title Resuming Execution at an Exception Breakpoint
=include gen 2Break_Dialog_Box3g_breaktrace
=include gen 2Go_Dialog_Box3g_go
=include gen 2Step_Dialog_Box3g_step
=include gen g_excep
 An exception breakpoint is one that was set using the
 'every exception' option on the Target (upper-right)
 option menu of the Break dialog box.  To open the Break
 dialog box, choose Break...  from the Control menu.

 When an exception breakpoint is triggered, execution is
 suspended before any application-declared condition
 handler is invoked.  When you resume execution from the
 breakpoint with the Go, Step, or Call commands (for
 example, from the Control menu), the behavior is as
 follows:

  -  Entering a Go or Step command to resume execution
     from the current location, causes the debugger to
     resignal the exception.  The Go command enables you
     to observe which application-declared handler, if
     any, next handles the exception.  The Step command
     causes you to step into that handler (see the next
     example).

  -  Entering a Go command to resume execution from a
     location other than the current location inhibits
     the execution of any application-declared handler
     for that exception.

  -  A common debugging technique at an exception
     breakpoint is to call a dump routine with the Call
     command.  When you enter the Call command at an
     exception breakpoint, no breakpoints, tracepoints,
     or watchpoints that were previously set within the
     called routine are active, so that the debugger
     does not lose the exception context.  Entering a Go
     or Step command after the routine has executed
     causes the debugger to resignal the exception, as
     for the first item in this list.

 The following FORTRAN example shows how to determine
 the presence of a condition handler at an exception
 breakpoint and how a Step command, entered at the
 breakpoint, enables you to step into the handler.

 First, an exception breakpoint is set and a Go command
 is then entered.  At the exception breakpoint, the call
 stack display (choose Call Stack...  from the Data
 menu) indicates that the exception was generated during
 a call to routine SYS$QIOW:

   %SYSTEM-F-SSFAIL, system service failure exception,
       status=0000013C, PC=7FFEDE06, PSL=03C00000
   break on exception preceding SYS$QIOW+6
   SHOW CALLS
    module name  routine name  line       rel PC    abs PC
                 SYS$QIOW                00000006  7FFEDE06
   *EXC$MAIN     EXC$MAIN        23      0000003B  0000063B

 The following call stack display indicates that no
 handler is declared in routine SYS$QIOW.  However, one
 level down the call stack, routine EXC$MAIN has
 declared a handler named SSHAND:

   stack frame 0 (2146296644)
       condition handler: 0
          SPA:            0
          S:              0
          mask:           ^M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11>
          PSW:            0020 (hexadecimal)
       saved AP:          2146296780
       saved FP:          2146296704
       saved PC:          EXC$MAIN\%LINE 25
   ...
   stack frame 1 (2146296704)
       condition handler: SSHAND
          SPA:            0
          S:              0
          mask:           ^M<R11>
          PSW:            0000 (hexadecimal)
       saved AP:          2146296780
       saved FP:          2146296760
       saved PC:          SHARE$DEBUG+2217
   ...

 At this exception breakpoint, entering a Step command
 enables you to step directly into condition handler
 SSHAND:

   stepped to routine SSHAND
        2:       INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS)
   SHOW CALLS
    module name  routine name  line       rel PC    abs PC
   *SSHAND       SSHAND           2      00000002  00000642
   ----- above condition handler called with exception 0000045C:
   %SYSTEM-F-SSFAIL, system service failure exception,
        status=0000013C, PC=7FFEDE06, PSL=03C00000
   ----- end of exception message
                 SYS$QIOW                00000006  7FFEDE06
   *EXC$MAIN     EXC$MAIN        23      0000003B  0000063B

 The debugger symbolizes the addresses of condition
 handlers into names if that is possible.  However, note
 that with some languages, exceptions are first handled
 by an RTL routine, before any application-declared
 condition handler is invoked.  In such cases, the
 address of the first condition handler might be
 symbolized to an offset from an RTL shareable image
 address.

=title Effect of Debugger on Condition Handling
=include gen g_excep
 When you run your program with the debugger, at least
 one of the following condition handlers is invoked, in
 the order given, to handle any exceptions caused by the
 execution of your program:

 1.  Primary handler

 2.  Secondary handler

 3.  Call-frame handlers (application-declared).  Also
     known as stack handlers.

 4.  Final handler

 5.  Last-chance handler

 6.  Catchall handler

 A handler can return one of the following three status
 codes to the VAX Condition Handling Facility:

  -  SS$_RESIGNAL---The VMS operating system searches
     for the next handler.

  -  SS$_CONTINUE---The condition is assumed to be
     corrected, and execution continues.

  -  SS$_UNWIND---The call stack is unwound some number
     of call frames, if necessary, and the signal is
     dismissed.

 For more information about condition handling, see the
 VMS Run-Time Library Routines Volume.

Additional information available:

PRIMARY_HANDLERCALL-FRAME_HANDLERSFINAL_HANDLER
CATCHALL_HANDLER

=TITLE Primary and Secondary Handlers
=include gen g_excep excep_cond_handl
=include gen g_excep
 When you run your program with the debugger, the
 primary handler is the debugger.  Therefore, the
 debugger has the first opportunity to handle an
 exception, whether or not the exception is caused by
 the debugger.

 Thus, if you have set an exception breakpoint or
 tracepoint, the debugger breaks on (or traces) any
 exceptions caused by your program.  The break (or
 trace) action occurs before any application-declared
 handler is invoked.

 If you have not set an exception breakpoint or
 tracepoint, the primary handler resignals any
 exceptions caused by your program.

 The secondary handler is used for special purposes and
 does not apply to the types of programs covered by the
 debugger.

=TITLE Call-Frame Handlers (Application-Declared)
=include gen g_excep excep_cond_handl
=include gen g_excep
 Each routine of your program can establish a condition
 handler, also known as a call-frame handler.  The
 operating system searches for these handlers starting
 with the routine that is currently executing.  If no
 handler was established for that routine, the system
 searches for a handler established by the next routine
 down the call stack, and so on back to the main
 program, if necessary.

 After it is invoked, a handler might perform one of the
 following actions:

  -  It handles the exception, thus allowing the program
     to continue execution.

  -  It resignals the exception.  The operating system
     then searches for another handler down the call
     stack.

  -  It encounters a breakpoint or watchpoint, thereby
     suspending execution at the breakpoint or
     watchpoint.

  -  It generates its own exception.  In this case, the
     primary handler is invoked again.

  -  It exits, thus ending program execution.

=TITLE Final and Last-Chance Handlers
=include gen g_excep excep_cond_handl
=include gen g_excep
 These handlers are controlled by the debugger.  They
 enable the debugger to regain control if no
 application-declared handler has handled an exception.
 Otherwise, the debugging session would end.

 The final handler is the last call frame on the call
 stack and the first of these two handlers to be
 invoked.  The following example illustrates what
 happens when an unhandled exception is propagated from
 an exception breakpoint to the final handler:

   [Enter Go command]
   ...
   %SYSTEM-F-INTDIV, arithmetic trap, integer divide by
       zero at PC=0000066C, PSL=03C00022
   break on exception preceding TEST\%LINE 13
        6:         X := 3/Y;
   [Enter Go command]
   ...
   %SYSTEM-F-INTDIV, arithmetic trap, integer divide by
       zero at PC=0000066C, PSL=03C00022

 In this example, the first INTDIV message is issued by
 the primary handler, and the second is issued by the
 final handler, which then returns control to the
 debugger.

 The last-chance handler is invoked only if the final
 handler cannot gain control because the stack is
 corrupted.  For example:

   [Deposit the value 10 into register FP]
   [Enter Go command]
   ...
   %SYSTEM-F-ACCVIO, access violation, reason mask=00,
        virtual address=0000000A, PC=0000319C, PSL=03C00000
   %DEBUG-E-LASTCHANCE, stack exception handlers lost,
        re-initializing stack

=TITLE Catchall Handler
=include gen g_excep excep_cond_handl
=include gen g_excep
 The catchall handler, which is part of the VMS
 operating system, is invoked if the last-chance handler
 cannot gain control.  The catchall handler produces a
 register dump.  This should never occur if the debugger
 has control of your program.  But it can occur if your
 program encounters an error when running without the
 debugger.

 If, during a debugging session, you observe a register
 dump and exit the debugging session, submit a Software
 Performance Report (SPR) to Digital.

=title Debugging Multilanguage Programs
=include gen g_lang
=include gen g_langexpr
Within the same debugging session, you can debug modules
 whose source code is written in different languages.
 The additional topics explain how to set your debugging
 context to a particular language and also highlight
 some language-specific behavior that you should be
 aware of, to minimize possible confusion.

 When debugging in any language, be sure to consult the
 documentation supplied with that language.  The chapter
 devoted to debugging, in the user's guide, contains all
 language dependent information for that language.  See
 also Debugger Support for Languages, which lists the
 constructs and operators that are supported by the
 debugger for each language.

Additional information available:

multilang set langmultilang lang dif

=title Controlling the Current Debugger Language
=include gen g_lang
=include gen g_multilang
 Many programs include modules that are written in
 languages other than that of the main program (the
 routine that contains the image transfer address).  By
 default, the debugger language remains set to the
 language of the main program throughout a debugging
 session, even if execution is suspended within a module
 written in another language.

 To take full advantage of symbolic debugging with such
 modules, you can set the debugging context to that of
 another debugger-supported language as follows:

 1.  Choose Language from the Customize menu

 2.  Choose the language from the Language submenu

 For example, choosing COBOL from the Language submenu
 causes the debugger to interpret any symbols,
 expressions, and so on according to the rules of the
 COBOL language.

 The setting of the current language determines how the
 debugger parses and interprets the names, numbers,
 operators, and expressions you specify, including
 things like the typing of variables, array and record
 syntax, the default radix for integer data, case
 sensitivity, and so on.  The language setting also
 determines how the debugger displays data associated
 with your program.

 When debugging a program that is written in an
 unsupported language, you can choose Unknown from the
 Language submenu.  To maximize the usability of the
 debugger with unsupported languages, the Unknown menu
 item causes the debugger to accept a large set of data
 formats and operators, including some that might be
 specific to only a few supported languages.

 The operators and constructs that the debugger
 recognizes for each supported language, including the
 Unknown language setting, are identified in the topic
 Debugger Support for Languages.

=title Differences Among Languages
 The additional topics list some of the differences you
 should keep in mind when debugging in various
 languages.  Included are differences that are caused by
 setting the current language (through the Language
 submenu of the Customize menu) and other differences
 (for example, language-specific initialization code and
 predefined breakpoints).

 The differences described are not a complete list.
 Consult your language documentation for more
 information.

Additional information available:

multilang radixmultilang langexprmultilang arr recmultilang case
multilang initializmultilang ada break

=title Default Radix
=include gen g_radix
 The default radix for entering and displaying numeric
 data is hexadecimal for BLISS and MACRO; the default is
 decimal for all other languages.

=title Evaluating Language Expressions
=include gen g_langexpr
=include gen g_lang
 The debugger evaluates language expressions in several
 contexts (for example, when you assign a value to a
 variable or when the debugger is processing a
 conditional breakpoint).

 The debugger evaluates language expressions in the
 syntax of the current language and in the current
 radix.

 Note that operators vary widely among different
 languages (see Debugger Support for Languages).  For
 example, the following are equivalent expressions in
 Pascal and FORTRAN, respectively:

   Y < 5       ! Pascal
   Y .LT. 5    ! FORTRAN

 Assume that the language is set to Pascal and you have
 set a conditional watchpoint specifying Y < 5 in the
 Condition field of the Watch dialog box (to open the
 dialog box, choose Watch...  from the Control).  You
 now execute the program into a FORTRAN routine, set the
 language to FORTRAN, and resume execution.

 While the language is set to FORTRAN, the debugger is
 not able to evaluate the expression (Y < 5).  As a
 result, it sets an unconditional watchpoint and, when
 the watchpoint is triggered, returns a syntax error for
 the '<' operator.

 This type of discrepancy can also occur if you use
 commands that evaluate language expressions in debugger
 command procedures and initialization files.

 Note also that the debugger processes language
 expressions that contain variable names (or other
 address expressions) differently when the language is
 set to BLISS than when it is set to another language.

=title Arrays and Records
 The syntax for denoting array elements and record
 components (if applicable) varies among languages.

 For example, some languages use brackets, [], and
 others use parentheses, (), to delimit array elements.

 Some languages (like BASIC) have zero-based arrays.
 Some languages have one-based arrays, as in the
 following example:

   [Examine a variable named INTEGER_ARRAY]

   PROG2\INTEGER_ARRAY
      (1,1):       27
      (1,2):       31
      (1,3):       12
      (2,1):       15
      (2,2):       22
      (2,3):       18

 For some languages, like Pascal and Ada, the specific
 array declaration determines how the array is based.

=title Case Sensitivity
 Names and language expressions are case sensitive in C.
 You must specify them exactly as they appear in the
 source code.  For example, the names SWAP and swap are
 not equivalent when the language is set to C.

=title Initialization Code
 If you have a multilanguage program that includes an
 Ada package, or a FORTRAN main program that was
 compiled with the /CHECK=UNDERFLOW (or /CHECK=ALL)
 qualifier, a NOTATMAIN message is issued when you
 invoke the debugger.  For example:

  INITIAL, language is ADA, module set to 'MONITOR'
  NOTATMAIN, type GO to get to start of main program

 The NOTATMAIN message indicates that execution is
 suspended before the start of the main program.  This
 enables you to execute and check some initialization
 code under debugger control.

 The initialization code is created by the compiler and
 is placed in a special PSECT named LIB$INITIALIZE.  In
 the case of an Ada package, the initialization code
 belongs to the package body (which might contain
 statements to initialize variables, and so on).  In the
 case of a FORTRAN program, the initialization code
 declares the handler that is needed if you specify the
 /CHECK=UNDERFLOW or /CHECK=ALL qualifier.

 The NOTATMAIN message indicates that, if you do not
 want to debug the initialization code, you can execute
 immediately to the start of the main program by
 entering a Go command.  You are then at the same point
 as when you invoke the debugger with any other program.
 Entering the Go command again starts program execution.

=title Ada Predefined Breakpoints
 If your program is linked with a module that is written
 in Ada, two breakpoints that are associated with Ada
 tasking exception events are automatically established
 when you invoke the debugger.

 Note that these breakpoints are not affected by setting
 the current language through the Language submenu of
 the Customize menu.  They are established automatically
 during debugger initialization when the Ada run-time
 library is present.

 Under these conditions, when you choose Break...  from
 the Control menu, the following breakpoints are
 identified in the dialog box:

 Predefined breakpoint on ADA event "DEPENDENTS_EXCEPTION"
    for any value
 Predefined breakpoint on ADA event "EXCEPTION_TERMINATED"
    for any value

=title Debugger Built-in Symbols and Logical Names
=include gen g_builtin_ssdebug
=include gen g_builtin_log
=include gen g_builtin_builtin
The additional topics identify the debugger built-in
 symbols, logical names, and any other debugger-specific
 constructs.

=title Invoking the Debugger from a Program (SS$_DEBUG)
=include gen g_invoke_options g_invoke_debug
=include gen g_invoke_options
=include gen g_builtin_log
=include gen g_builtin_builtin
You can invoke the debugger from a program by signaling
 the condition SS$_DEBUG, which is defined in
 SYS$LIBRARY:STARLET.OLB.

 Signaling SS$_DEBUG from a program is equivalent to
 typing CTRL/Y followed by the DCL command DEBUG at that
 point during the execution of the program.

 You can pass commands to the debugger at the time you
 signal it with SS$_DEBUG:

  -  Specify the commands to be executed by the debugger
     as you would enter them at the DBG> prompt in the
     COMMAND box.

  -  Separate multiple commands by semicolons (;).

  -  Pass the commands by reference as an ASCIC string.
     See your language documentation for details on
     constructing an ASCIC string.

 For example, to invoke the debugger and enter a SHOW
 CALLS command at a given point in your program, you
 could insert the following code in your program (BLISS
 example):

 LIB$SIGNAL(SS$_DEBUG,1,UPLIT BYTE(%ASCIC 'SHOW CALLS'));

 You can obtain the definition of SS$_DEBUG at compile
 time from the appropriate STARLET or SYSDEF file for
 your language (for example STARLET.L32 for BLISS or
 FORSYSDEF.TLB for FORTRAN).

 You can also obtain the definition of SS$_DEBUG at link
 time in SYS$LIBRARY:STARLET.OLB (this method is less
 desirable).

=title Debugger Logical Names
=include gen g_builtin_builtin
=include gen g_builtin_ssdebug
The additional topics identify debugger-specific logical
 names.

Additional information available:

DBG_INITDBG_INOUTDBG_PROCESSDBG_DECW_DISPLAY

=title DBG$INIT Logical Name
=include gen g_init_file
=include gen g_builtin_log
 Use the logical name DBG$INIT to specify your debugger
 initialization file.  For example:

   $ DEFINE DBG$INIT DISK$:[JONES.COMFILES]DEBUGINIT.COM

 DBG$INIT accepts a full or partial VMS file
 specification as well as a search list.

 By default, DBG$INIT is undefined.

=title DBG$INPUT and DBG$OUTPUT Logical Names
=include gen g_builtin_log DBG_DECW_DISPLAY
=include gen g_invoke_options g_invoke_override_interf
=include gen g_builtin_log
 The logical names DBG$INPUT and DBG$OUTPUT apply only
 to the debugger's command interface.  They are ignored
 in the DECwindows interface.

 When using the debugger's DECwindows interface, use
 DBG$DECW$DISPLAY instead of DBG$INPUT and DBG$OUTPUT
 (see Overriding the Debugger's Default Interface).

 Use of DBG$INPUT and DBG$OUTPUT with the debugger's
 command interface is explained in the VMS Debugger
 Manual.

=title DBG$PROCESS Logical Name
=include gen g_def_config
=include gen g_multiproc_config
=include gen g_multiproc
=include gen g_debug_config
=include gen g_builtin_log
 Use the logical name DBG$PROCESS to specify the
 debugging configuration (default, or multiprocess)
 before invoking the debugger.

 By default, DBG$PROCESS is undefined.

=title DBG$DECW$DISPLAY Logical Name
=include gen g_invoke_options g_invoke_override_interf
=include gen g_cmd_mode
=include gen g_builtin_log DBG_INOUT
=include gen g_builtin_log
 Use the logical name DBG$DECW$DISPLAY in the DECwindows
 environment to specify the debugger interface
 (DECwindows or command) or the display device.  Use a
 job definition.

 For example, the following command causes the debugger
 to come up in the command interface when next invoked:

   $ DEFINE/JOB DBG$DECW$DISPLAY " "

 By default DBG$DECW$DISPLAY is either undefined or has
 the same definition as the application-wide logical
 name DECW$DISPLAY.

=title Debugger Built-in Symbols
=include gen g_specifying_registers
=include gen g_radix g_radix_input
=include gen g_specifying_lines
=include gen g_specifying_labels
=include gen g_builtin_identifiers
=include gen g_builtin_operators
=include gen g_builtin_nextprev_entity
=include gen g_builtin_curvalue
=include gen g_builtin_parcnt
=include gen g_builtin_exceptions
=include gen g_builtin_processes
=include gen g_builtin_tasks
=include gen g_builtin_page
=include gen g_builtin_nextprev_scope
=include gen g_builtin_sourcinst
=include gen g_builtin_curnext_wnds
=include gen g_builtin_log
=include gen g_builtin_ssdebug
The debugger's built-in symbols provide options for
 specifying program entities and values in dialog boxes
 or debugger commands.

 Most of the debugger built-in symbols have a percent
 sign (%) prefix.

 Descriptions of these symbols are organized as follows
 in the additional topics:

  -  Specifying VAX registers (%R0 through %R11, %AP,
     %FP, %SP, %PC, %PSL)

  -  Entering Integer Data in Another Radix (%BIN, %DEC,
     %HEX, %OCT)

  -  Specifying Source Line Numbers (%LINE)

  -  Specifying Program Labels (%LABEL)

  -  Constructing Identifiers (%NAME)

  -  Using Operators in Address Expressions (plus sign
     (+), minus sign (-), multiplication sign (*),
     division sign (/), at sign (@), period (.), bit
     field operator (<p,s,e>), backslash (\))

  -  Current, Next, and Previous Entity Built-In Symbols
     (period (.), RETURN key, circumflex (^), %CURLOC,
     %NEXTLOC, %PREVLOC)

  -  Current Value Built-In Symbol (%CURVAL,
     backslash(\))

  -  Counting Parameters Passed to Command Procedures
     (%PARCNT)

  -  Obtaining Information About Exceptions
     (%ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME,
     %EXC_NUMBER, %EXC_SEVERITY)

  -  Specifying Processes of a Multiprocess Program
     (%PROCESS_NAME, %PROCESS_PID, %PROCESS_NUMBER,
     %NEXT_ PROCESS, %PREVIOUS_PROCESS,
     %VISIBLE_PROCESS)

  -  Specifying Tasks of an Ada Tasking Program
     (%ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %TASK,
     %VISIBLE_TASK)

  -  Obtaining the Height and Width of the Screen
     (%PAGE, %WIDTH)

  -  Current, Next, and Previous Scope Built-In Symbols
     (%CURRENT_SCOPE_ENTRY, %NEXT_SCOPE_ENTRY,
     %PREVIOUS_SCOPE_ENTRY)

  -  Source and Instruction Display Built-In Symbols
     (%SOURCE_SCOPE, %INST_SCOPE)

  -  Specifying the Current or Next Debugger Window
     (%CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST,
     %NEXTOUTPUT, %NEXTSCROLL, %NEXTSOURCE)

=title Using Operators in Address Expressions
=include gen g_intro_to_addrexpr
=include gen g_cmd_mode
=include gen g_cmd_prcdrs
=include gen g_builtin_builtin
 The operators that you can use in address expressions
 are described in the additional topics.

 A unary operator has one operand.  A binary operator
 has two operands.

Additional information available:

pathname oparith opcontents opbitfield op

=title Path Name Operator (Backslash (\))
=include gen g_builtin_operators
 The backslash (\) is a path name operator in address
 expressions:

  \ (backslash)       When used within a path name,
                      delimits each element of the
                      path name. In this context, the
                      backslash cannot be the leftmost
                      element of the complete path name.

                      When used as the prefix to a
                      symbol, specifies that the symbol
                      is to be interpreted as a global
                      symbol. In this context, the
                      backslash must be the leftmost
                      element of the symbol's complete
                      path name.

 The following command displays the value of the
 variable COUNT that is declared in routine ROUT2 of
 module MOD4.  The backslash (\) path name delimiter
 separates the path name elements:

   Examine MOD4\ROUT2\COUNT
   MOD4\ROUT2\COUNT: 12

 The following command sets a breakpoint on line 26 of
 the module QUEUMAN:

   Set Break QUEUMAN\%LINE 26

 The following command displays the value of the global
 symbol X:

   Examine \X

=title Arithmetic Operators (+,-,*,/)
=include gen g_builtin_operators
 You can use the following arithmetic operators in
 address expressions:

  Plus sign (+)       Unary or binary operator. As a
                      unary operator, indicates the
                      unchanged value of its operand.
                      As a binary operator, adds the
                      preceding operand and succeeding
                      operand together.

  Minus sign (-)      Unary or binary operator. As a
                      unary operator, indicates the
                      negation of the value of its
                      operand. As a binary operator,
                      subtracts the succeeding operand
                      from the preceding operand.

  Multiplication      Binary operator. Multiplies the
  sign (*)            preceding operand by the succeeding
                      operand.

  Division sign (/)   Binary operator. Divides the
                      preceding operand by the succeeding
                      operand.

 The order in which the debugger evaluates the elements
 of an address expression is similar to that used by
 most programming languages.  The order is determined by
 the following three factors, listed in decreasing order
 of precedence (first listed have higher precedence):

 1.  The use of delimiters (usually parentheses or
     brackets) to group operands with particular
     operators

 2.  The assignment of relative priority to each
     operator

 3.  Left-to-right priority of operators

 The debugger operators are listed in decreasing order
 of precedence as follows:

 1.  Unary operators ((.), (@), (+), (-))

 2.  Multiplication and division operators ((*), (/))

 3.  Addition and subtraction operators ((+), (-))

 For example, when evaluating the following expression,
 the debugger first adds the operands within
 parentheses, then divides the result by 4, then
 subtracts the result from 5:

    5-(T+5)/4

 The following command displays the value contained in
 the memory location X+4 bytes:

   Examine X + 4

=title Contents-of Operator (At Sign (@) or Period (.))
=include gen g_builtin_operators
 In an address expression, the at sign (@) and period
 (.) each function as a "contents-of" operator.

 The "contents-of" operator is a unary operator.  It
 causes its operand to be interpreted as a memory
 address and thus requests the contents of (or value
 residing at) that address.

 The following examples illustrate use of the
 contents-of operator.  For brevity, debugger commands
 are used.

 In the next example, the instruction at the current PC
 value is obtained:

   EXAMINE .%PC
   MOD\%LINE 5: PUSHL   S^#8

 This is the instruction whose address is contained in
 the PC and which is about to execute.

 In the next example, the source line at the PC value
 one level down the call stack is obtained (at the call
 to routine SWAP):

   EXAMINE/SOURCE .1\%PC
      module MAIN
      MAIN\%LINE 134:     SWAP(X,Y);

 For the next example, assume that the value of pointer
 variable PTR is 7FF00000 hexadecimal, the address of an
 entity that you want to examine.  Assume further that
 the value of this entity is 3FF00000 hexadecimal.  The
 following command shows how to examine the entity:

   EXAMINE/LONG .PTR
   7FF00000: 3FF00000

 In the next example, the contents-of operator (at sign
 or period) is used with the current location operator
 (period) to examine a linked list of three
 quadword-integer pointer variables, L1, L2, and L3:

      +------+
   P: | 9B40 |--+      L1          L2          L3
      +------+  |   +------+    +------+    +------+
                +-->| 9BDA |--->| 9BF4 |--->| 0000 |
                    |------|    |------|    |------|
                    |  8   |    |  6   |    |  12  |
                    +------+    +------+    +------+

 P is a pointer to the start of the list.  The low
 longword of each pointer variable contains the address
 of the next variable; the high longword of each
 variable contains its integer value (8, 6, and 12
 respectively).

      SET TYPE QUADWORD; SET RADIX HEX
      EXAMINE .P              ! Examine the entity whose address
                              ! is contained in P.
 00009BC2: 00000008 00009BDA  ! High word has value 8, low word
                              ! has address of next entity (9BDA).
      EXAMINE @.              ! Examine the entity whose address
                              ! is contained in the current entity.
 00009BDA: 00000006 00009BF4  ! High word has value 6, low word
                              ! has address of next entity (9BF4).
      EXAMINE ..              ! Examine the entity whose address
                              ! is contained in the current entity.
 00009BF4: 0000000C 00000000  ! High word has value 12 (dec.), low word
                              ! has address 0 (end of list).

=title Bit-Field Operator <p,s,e>
=include gen g_builtin_operators
 You can apply bit field selection to an address-
 expression by means of the bit field operator, <p,s,e>.
 It is a unary operator.

 To select a bit field, you supply a bit offset (p), a
 bit length (s), and a sign extension bit (e), which is
 optional.

 The following example shows how to use the bit- field
 operator.  For example, to examine the address
 expression X_NAME starting at bit 3 with a length of 4
 bits and no sign extension, you would enter the
 following command:

   Examine X_NAME <3,4,0>

=title Current, Next, and Previous Entity Built-In Symbols
=include gen g_intro_to_addrexpr
=include gen Examine_Status_L_Button
=include gen g_builtin_builtin
 You can use the following debugger built-in symbols in
 address expressions to denote the current, next, and
 previous logical entities in various dialog boxes,
 command procedures, and other contexts:
   Symbol            Description
   ------            -----------
  %CURLOC        Current logical entity---the program
  . (period)     location last examined or deposited into.
                 This is the entity displayed in the
                 Current Entity field (symbolized and
                 with a path name prefix, if possible).

  %NEXTLOC       Logical successor of the current entity
                 ---the program location that logically
                 follows the current logical entity.

  %PREVLOC       Logical predecessor of current entity
  ^(circumflex)  ---the program location that logically
                 precedes the current logical entity.

 The debugger uses the type of the current entity to
 determine the logical successor and predecessor
 entities.

 These symbols are useful when you are examining or
 depositing consecutive array elements, a stream of
 assembly-language instructions, or consecutive memory
 addresses.

 Note that the concept of previous or next logical
 entity might not apply to some entities, such as
 noncomposite variables (integer, real, and so on).

 The debugger implicitly uses these built-in symbols
 with the Examine command in the following situations:

  -  If no text is currently selected when you click on
     the Examine button in the main window or choose
     Examine from the pop-up menu, the debugger issues
     the command Examine %CURLOC (or Examine .)

  -  When you click on the Current Entity down-arrow
     button in the main window, the debugger issues the
     command Examine %NEXTLOC

  -  When you click on the Current Entity up-arrow
     button in the main window, the debugger issues the
     command Examine %PREVLOC

=title Current Value Built-In Symbol
=include gen g_langexpr
=include gen g_builtin_nextprev_entity
=include gen g_builtin_builtin
 You can use the built-in symbol %CURVAL to denote the
 current value.  The current value is the value last
 displayed by an Evaluate or Examine command or last
 deposited.

 The backslash (\) also denotes the current value when
 used in that context.

 You can use these symbols with the Examine, Evaluate,
 and Deposit commands and the associated dialog boxes
 (Examine Variable, Language Expressions, Deposit into
 Variable, and so on).

 For example:

   Examine X
   MOD3\X:  23

   Evaluate %CURVAL
   23

   Deposit Y = 47
   Evaluate \
   47

=title Obtaining the Height and Width of the Screen
=include gen g_builtin_builtin
 The built-in symbols %PAGE and %WIDTH return the height
 and width in pixels, respectively, of the workstation
 screen.

 You can use these symbols in various language
 expressions.

=title Specifying the Current or Next Debugger Window
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_deb_wnd_menus
=include gen g_keypad
=include gen g_builtin_builtin
 The debugger maintains a list of the predefined and
 user-defined debugger windows, arranged in the order
 these windows were created.  The predefined windows are
 SRC, INST, OUT, AUTO, and REG.

 The following built-in symbols enable you to refer to
 debugger windows by their relative position on the
 window list instead of by their explicit names, such as
 SRC or INST.  These symbols are used mainly in keypad
 key definitions and command procedures.

 The window list is circular.  Therefore, you can use
 the built-in symbols to cycle through the window list
 until you reach the desired window.

 %CURDISP      The current window---the window most
               recently referenced with a DISPLAY
               command.

 %CURSCROLL    The current scrolling window---the
               default window for the SCROLL command
               and for the keypad keys that scroll
               windows (2, 4, 6, and 8).

 %NEXTDISP     The next window in the list after the
               current window.

 %NEXTINST     The next instruction window in the window
               list after the current instruction window.
               The current instruction window is the
               window that has the instruction attribute.
               It receives the output from
               EXAMINE/INSTRUCTION commands.

 %NEXTOUTPUT   The next output window in the window list
               after the current output window. An output
               window receives debugger output that is not
               already directed to another window.

 %NEXTSCROLL   The next window in the window list after
               the current scrolling window.

 %NEXTSOURCE   The next source window in the window list
               after the current source window. The
               current source window is the window that
               has the source attribute. It receives the
               output from TYPE and EXAMINE/SOURCE
               commands.

=title Current, Next, and Previous Scope Built-In Symbols
=include gen Scopes_Status_L_Button
=include gen g_builtin_sourcinst
=include gen g_builtin_builtin
 You can use the built-in symbols %CURRENT_SCOPE_ENTRY,
 %NEXT_SCOPE_ENTRY, and %PREVIOUS_SCOPE_ENTRY to obtain
 and manipulate the scope for symbol lookup and for
 source or instruction display relative to the routine
 call stack.

 These symbols return integer values that denote a call
 frame on the call stack.  Call frame 0 denotes the
 routine at the top of the stack, where execution is
 suspended.  Call frame 1 denotes the calling routine,
 and so on.

   Symbol                 Description

 %CURRENT_SCOPE_ENTRY  The call frame that the debugger
                       is currently using as reference
                       when displaying source code or
                       decoded VAX instructions, or when
                       searching for symbols. By default,
                       this is call frame 0.

 %NEXT_SCOPE_ENTRY     The next call frame down the call
                       stack from the call frame denoted
                       by %CURRENT_SCOPE_ENTRY.

 %PREVIOUS_SCOPE_ENTRY The next call frame up the call
                       stack from the call frame denoted
                       by %CURRENT_SCOPE_ENTRY.


 The symbols %NEXT_SCOPE_ENTRY and %PREVIOUS_SCOPE_ENTRY
 are used in the debugger commands that are bound to the
 Call Frame arrow buttons:

  -  Clicking on the down-arrow button issues the
     command SET SCOPE/CURRENT %NEXT_SCOPE_ENTRY

  -  Clicking on the up-arrow button issues the command
     SET SCOPE/CURRENT %PREVIOUS_SCOPE_ENTRY

 See Call Frame Field and Buttons in Main Window for an
 explanation of the effect of these buttons.

 See Source and Instruction Display Built-In Symbols for
 a description of how the symbols %SOURCE_SCOPE and
 %INST_SCOPE are related to the symbol
 %CURRENT_SCOPE_ENTRY.

=title Source and Instruction Display Built-In Symbols
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen Scopes_Status_L_Button
=include gen g_builtin_nextprev_scope
=include gen g_builtin_builtin
 The built-in symbols %SOURCE_SCOPE and %INST_SCOPE are
 used in the debugger commands that are bound to the
 predefined source and instruction windows SRC and INST,
 respectively.

 The command that automatically updates SRC is
 EXAMINE/SOURCE .%SOURCE_SCOPE\%PC.  This command causes
 SRC to display the source code for the routine that is
 identified in the Call Frame field in the main window,
 if source code is available for that routine.

 Similarly, the command that automatically updates INST
 is EXAMINE/INSTRUCTION .%INST_SCOPE\%PC.  This command
 causes INST to display the decoded instructions for the
 routine that is identified in the Call Frame field.

 Thus, by default %SOURCE_CODE and %INST_SCOPE both
 denote scope 0, which is the scope of the routine where
 execution is currently suspended.  Clicking on the Call
 Frame arrow buttons resets the reference scope and the
 values of %SOURCE_SCOPE and %INST_SCOPE, relative to
 the call stack.  See Current, Next, and Previous Scope
 Built-In Symbols.

 Instructions are always available for display for every
 routine on the call stack, because they are decoded
 from the executable image.  However, source code may
 not always be available for display.

 %SOURCE_SCOPE has the property that, if source code is
 not available for the current scope, %SOURCE_SCOPE
 signifies scope N, where N is the first level down the
 call stack for which source code is available.

 When displaying source lines that are not associated
 with the module where execution is suspended, the
 debugger issues the following message:

   SOURCESCOPE, Source lines not available for .0\%PC.
     Displaying source in a caller of the current routine.

=title Obtaining Information About Exceptions
=include gen g_excep
=include gen g_lang ada
=include gen g_builtin_builtin
 When an exception is signaled, the debugger sets the
 following exception-related built-in symbols:

      Symbol         Description

  %EXC_FACILITY  Name of facility that issued the current
                    exception
  %EXC_NAME      Name of current exception
  %ADAEXC_NAME   Ada exception name of current exception
                    (for Ada programs only)
  %EXC_NUMBER    Number of current exception
  %EXC_SEVERITY  Severity code of current exception

 You can use these symbols as follows:

  -  To obtain information about the fields of the VMS
     condition code of the current exception.  Choose
     Language Expressions...  from the Data menu to
     evaluate an exception-related symbol.

  -  To qualify exception breakpoints (or tracepoints)
     so that they trigger only on certain kinds of
     exceptions.  Use the Condition field of the Break
     dialog box to specify a conditional expression
     containing the exception-related symbol.  To open
     the dialog box, choose Break...  from the Control
     menu.

 The following examples illustrate the use of some of
 these symbols.  Where needed for clarity, debugger
 command syntax is used, followed by a summary
 description of the action [in brackets]:

   Evaluate %EXC_NAME
   'ACCVIO'

   SET TRACE/EXCEPTION WHEN (%EXC_NAME = "ACCVIO")
   [ Set conditional tracepoint on every exception ]

   Evaluate %EXC_FACILITY
   'SYSTEM'

   Evaluate %EXC_NUMBER
   12

   EVALUATE/CONDITION_VALUE %EXC_NUMBER
   [ Evaluate as a condition value ]
   %SYSTEM-F-ACCVIO, access violation, reason mask=01,
        virtual address=FFFFFF30, PC=00007552, PSL=03C00000

   SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12)
   SET BREAK/EXCEPTION WHEN (%EXC_SEVERITY .NE. "I" -
                       .AND. %EXC_SEVERITY .NE. "S")

=title Specifying Tasks of an Ada Tasking Program
=include gen g_lang ada
=include gen g_lang ada tasking_states
=include gen g_builtin_builtin
 You can use the following built-in symbols to specify
 the tasks of an Ada tasking program.  These built-in
 symbols apply only to Ada tasking programs.

  Symbol         Description

  %ACTIVE_TASK   The currently active task---the task
                 that executes when a GO or STEP command
                 is entered.

  %CALLER_TASK   The task that is the entry caller of the
                 active task during a task rendezvous.

  %NEXT_TASK     The next task on debugger's task list
                 after the task that is currently visible.

  %TASK n        Specifies a task by means of its task
                 identifier (n is a decimal integer
                 assigned by the VAX Ada run-time library
                 to each task as it is created).

  %VISIBLE_TASK  The currently visible task---the task
                 that is the context for an EXAMINE command,
                 for example.

 Two examples follow.  See the VAX Ada documentation for
 additional details.

   EXAMINE MONITOR_TASK
   MOD\MONITOR_TASK: %TASK 2

   WHILE %NEXT_TASK NEQ %ACTIVE
         DO (SET TASK %NEXT_TASK; SHOW CALLS)

=title Specifying Processes of a Multiprocess Program
=include gen Process_Status_L_Button
=include gen g_multiproc
=include gen g_builtin_builtin
 Use the following combinations of built-in symbols and
 process specifications to specify a process of a
 multiprocess program in debugger commands or in the
 Processes dialog box.  To open the dialog box, choose
 Processes...  from the Data menu.

 The brackets, [], surrounding a symbol indicate that it
 is optional.

 [%PROCESS_NAME] VMS-process-name
    Use this form if the VMS process name contains no
    space or lowercase characters.  The process name can
    include the asterisk wildcard character (*).

 [%PROCESS_NAME] "VMS-process-name"
    Use this form if the VMS process name contains space
    or lowercase characters.  Do not use the asterisk
    wildcard character (*).

 %PROCESS_PID process_id
    Use this form when specifying the VMS process
    identification number (PID, a hexadecimal number).

 %PROCESS_NUMBER process-number
    Use this form when specifying the process number
    assigned by the debugger, after the process comes
    under debugger control.  Process numbers appear in
    the list box of the Processes dialog box, along with
    the process name.  You can also use %PROC.

 %NEXT_PROCESS
    Specifies the next process after the visible process
    in the debugger's circular process list.

 %PREVIOUS_PROCESS
    Specifies the process previous to the visible
    process in the debugger's circular process list.

 %VISIBLE_PROCESS
    Specifies the process whose call stack, register
    set, and images are the current context for looking
    up symbols, register values, routine calls,
    breakpoints, and so on.  This is the process that is
    identified in the Visible Process field of the main
    window.

 When specifying processes in debugger commands or in
 the Processes dialog box (choose Processes...  from the
 Data menu), you must specify a process that is under
 debugger control.  The list box of the Processes dialog
 box identifies the processes that are under debugger
 control.

 The debugger implicitly uses %NEXT_PROCESS and
 %PREVIOUS_PROCESS with the SET PROCESS command when you
 click on the Visible Process arrow buttons in the main
 window:

  -  Clicking on the right-arrow button issues the
     command SET PROCESS %NEXT_PROCESS, setting the
     visible process to the next process on the process
     list.

  -  Clicking on the left-arrow button issues the
     command SET PROCESS %PREVIOUS_PROCESS, setting the
     visible process to the previous process on the
     process list.

=title Counting Parameters Passed to Command Procedures
=include gen g_cmd_prcdrs passing_parameters
=include gen g_builtin_builtin
 You can use the %PARCNT built-in symbol within a
 command procedure that accepts a variable number of
 actual parameters (%PARCNT is defined only within a
 debugger command procedure).

 %PARCNT specifies the number of actual parameters
 passed to the current command procedure.  In the
 following example, command procedure ABC.COM is invoked
 from the COMMAND box and three parameters are passed:

   DBG> @ABC 111,222,333

 Within ABC.COM, %PARCNT now has the value 3.  %PARCNT
 is then used as a loop counter to obtain the value of
 each parameter passed to ABC.COM:

   FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)

=title Constructing Identifiers (%NAME Symbol)
=include gen g_builtin_builtin
 The %NAME built-in symbol enables you to construct
 identifiers that are not ordinarily legal in the
 current language.  The syntax is as follows:

   %NAME 'character-string'

 In the following example, the variable with the name
 '12' is examined:

   Examine %NAME '12'

 In the following example, the compiler-generated label
 P.AAA is examined:

   Examine %NAME 'P.AAA'

=title Controlling Access to Symbols in Your Program
=include gen g_symb_complink
=include gen g_symb_problems
=include gen g_DST_GST_RST
=include gen g_pathname
=include gen g_symb_mod_set
=include gen g_source_notavailable
=include gen g_symb_symbolize
=include gen g_resolve_symb
=include gen g_symbol_lookup_conv
=include gen g_symb_share
=include gen g_symb_opt
=include gen g_accessing_nonstatic_variables
=include gen g_cmd_mode
=include gen g_builtin_builtin
Symbolic debugging enables you to specify variable
 names, routine names, and so on, precisely as they
 appear in your source code.  You do not need to use
 numeric memory addresses or registers when referring to
 program locations, although you can, if you want.

 In addition, you can use symbols in the context that is
 appropriate for the program and its source language.
 The debugger supports the language conventions
 regarding data types, expressions, scope and visibility
 of entities, and so on.

 To have full access to the symbols that are associated
 with your program, you must compile and link the
 program using the /DEBUG DCL command qualifier.

 Under these conditions, the way in which symbol
 information is passed from your source program to the
 debugger and is processed by the debugger is
 transparent to you, in most cases.  However, certain
 situations might require some action.  Some are
 identified in the topic Possible Problems When
 Specifying Symbols.

 Note that the additional topics discuss only the
 symbols (typically address expressions) that are
 derived from your source program, for example:

  -  The names of various entities that you have
     declared in your source code, such as the names of
     variables, routines, program labels, array
     elements, or record components.

  -  The names of modules (compilation units) and
     shareable images that are linked with your program.

  -  Elements that the debugger uses to identify source
     code---for example, the specifications of source
     files, and source line numbers as they appear in a
     listing file or when the debugger displays source
     code.

 The following types of symbols are not included in
 these discussions:

  -  The symbols you might create during a debugging
     session with the DEFINE command, entered through
     the COMMAND box or a debugger command procedure.

  -  The debugger's built-in symbols, such as the period
     (.), %PC, and %SOURCE_SCOPE.

=title Possible Problems When Specifying Symbols
=include gen g_symb_complink
=include gen g_symb_mod_set
=include gen g_pathname
=include gen g_resolve_symb
=include gen g_symbol_lookup_conv
=include gen g_symb_opt
=include gen g_accessing_nonstatic_variables
=include gen g_source_notavailable
=include gen g_DST_GST_RST
=include gen g_symb_symbolize
=include gen g_symb_share
=include gen g_builtin_builtin
=include gen g_specifying_variables
=include gen g_specifying_code
=include gen g_specifying_data
=include gen g_intro_to_addrexpr
=include gen g_symb
 The following examples show some possible problems you
 might encounter when specifying a variable name or
 other symbolic address expression.

 It is assumed that you have compiled and linked all
 modules of your program using the /DEBUG qualifier with
 the DCL compile and LINK commands.

 Problem:

   When you try to set a breakpoint on a routine named
   COUNTER, the debugger displays the following
   diagnostic message:

   NOSYMBOL, symbol 'COUNTER' is not in the symbol table

 Corrective Action:

   Set the module in which COUNTER is declared by
   choosing Modules...  from the Data menu.

 Problem:

   The debugger displays the following message if a
   symbol X is defined (declared) in more than one
   module, routine, or other program unit:

   NOUNIQUE, symbol 'X' is not unique

 Corrective Action:

   Use a path name to resolve the symbol ambiguity.  Or
   use the Call Frame arrow buttons if the ambiguity is
   among symbols declared in routines that are currently
   on the call stack.

 Problem:

   The following message is displayed when you try to
   access a symbol J in a program that was optimized
   during compilation:

   UNALLOCATED, entity 'J' was not allocated in memory
      (was optimized away)

 Corrective Action:

   If available, use the /NOOPTIMIZE (or equivalent)
   compiler command qualifier to disable optimization.

 Problem:

   The following message is displayed when you try to
   access a variable K that was allocated on the stack
   or in a register (a nonstatic variable):

   SYMNOTACT, nonstatic variable 'MD1\SWAP\K' is not active

 Corrective Action:

   Execute the program and suspend execution within the
   routine in which variable K is defined.  You can then
   access K.

=title Symbol Tables Used by the Debugger (DST, GST, RST)
=include gen g_symb_complink
=include gen g_symb_mod_set
=include gen g_symbol_lookup_conv
=include gen g_symb_share
=include gen g_symb
 The debugger uses information stored in the following
 symbol tables:

  -  DST (Debug Symbol Table)

  -  GST (Global Symbol Table)

  -  RST (Run-Time Symbol Table)

 Each of these tables plays a role in the way symbol
 information is passed from your program's source code
 to the debugger.

 The DST and GST are built when you compile and link
 your program (that is, before you start a debugging
 session).  The RST is built by the debugger in several
 steps, as needed, in the course of a debugging session.

 The additional topics provide the context in which each
 of these symbol tables is built and used.

=title Controlling Symbols When Compiling and Linking
=include gen g_symb_opt
=include gen g_DST_GST_RST
=include gen g_symb_Share symb_share_complink
=include gen g_symb_Share
=include gen g_symb
 To take full advantage of symbolic debugging, you must
 compile and link your program with the /DEBUG
 qualifier.  The following example illustrates these
 steps with a simple Pascal program, INVENTORY, that
 consists of two compilation units whose source code is
 in two separate files, FORMS.PAS and INVENTORY.PAS.
 INVENTORY is the main program unit:

   $ PASCAL/NOOPTIMIZE/DEBUG FORMS, INVENTORY
   $ LINK/DEBUG INVENTORY, FORMS

 Note that the /NOOPTIMIZE qualifier is used with the
 compiler command (PASCAL, in this example).  If the
 compiler optimizes code by default, it is best to
 disable this feature by specifying /NOOPTIMIZE (or the
 equivalent qualifier, if any, for your compiler).
 Otherwise, the resulting code is optimized, possibly
 causing the contents of some program locations to be
 inconsistent with what you might expect from looking at
 the source code.

Additional information available:

Symb compSymb locl glblSymb linkSymb security

=title Controlling Symbols When Compiling
=include gen g_DST_GST_RST
=include gen g_Symb_complink
=include gen g_symb_Share symb_share_complink
=include gen g_symb_Share
=include gen g_symb
 When you compile a source file using the /DEBUG
 qualifier, the compiler creates symbol records for the
 debug symbol table (DST records) and includes them in
 the object module being generated (OBJ file type).

 DST records provide not only the names of symbols but
 also all relevant information about their use.  For
 example:

  -  Data types, ranges, constraints, and scopes
     associated with variables.

  -  Parameter names and parameter types associated with
     functions and procedures.

  -  Source line correlation records, which associate
     source lines with line numbers and source files.

 Most compilers allow you to vary the amount of DST
 information put in an object module by specifying
 different options with the /DEBUG qualifier.  The
 following table identifies the options for most
 compilers (refer to the documentation supplied with
 your language for complete information).

  Compiler
  Command Qualifier     DST Information
  -----------------     ---------------

  /DEBUG                Full

  /DEBUG=TRACEBACK      Traceback only (module names,
                        routine names, and line numbers)

  /NODEBUG              None

 Notes:

 1. /DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS,TRACEBACK)
    are equivalent.
 2. /DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS,TRACEBACK) are
    equivalent.
 3. /NODEBUG, /DEBUG=NONE, and
    /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent.

 The TRACEBACK option is a default for most compilers.
 That is, if you omit the /DEBUG qualifier, most
 compilers assume /DEBUG=TRACEBACK.  The TRACEBACK
 option enables the VMS traceback condition handler to
 translate memory addresses into routine names and line
 numbers so that it can give a symbolic traceback if a
 run-time error occurs.  For example:

   $ RUN INVENTORY
   ...
   %PAS-F-ERRACCFIL, error in accessing file PAS$OUTPUT
   %PAS-F-ERROPECRE, error opening/creating file
   %RMS-F-FNM, error in file name
   %TRACE-F-TRACEBACK, symbolic stack dump follows

   module name   routine name  line   rel PC    abs PC

   PAS$IO_BASIC  _PAS$CODE           00000192  00001CED
   PAS$IO_BASIC  _PAS$CODE           0000054D  000020A8
   PAS$IO_BASIC  _PAS$CODE           0000028B  00001DE6
   INVENTORY     INVENTORY      59   00000020  000005A1
 $

 The debugger displays traceback information when you
 choose Call Stack...  from the Data menu.

=title Local and Global Symbols
=include gen g_DST_GST_RST
=include gen g_symb_complink symb_link
=include gen g_symbol_lookup_conv
=include gen g_Symb_complink
=include gen g_symb_Share symb_share_complink
=include gen g_symb_share
=include gen g_symb
 DST records contain information about all symbols that
 are defined in your program.  These are either local or
 global symbols.

 Typically, local symbols are symbols that are
 referenced only within the module where they are
 defined; global symbols are symbols, such as routine
 names, procedure entry points, and global data names,
 that are defined in one module but referenced in other
 modules.

 Generally, the compiler resolves references to local
 symbols, and the linker resolves references to global
 symbols.

=title Controlling Symbols When Linking
=include gen g_DST_GST_RST
=include gen g_symbol_lookup_conv
=include gen g_Symb_complink
=include gen g_symb_Share symb_share_complink
=include gen g_symb_Share
=include gen g_symb
 When you enter the command LINK/DEBUG to link object
 modules and produce an executable image, the linker
 performs several functions that affect debugging:

  -  It builds a debug symbol table (DST) from the DST
     records contained in the object modules being
     linked.  The DST is the primary source of symbol
     information during a debugging session.

  -  It resolves references to global symbols and builds
     a global symbol table (GST).  The GST duplicates
     some of the global symbol information already
     contained in the DST, but the GST is used by the
     debugger for symbol lookup under certain
     circumstances.

  -  It puts the DST and GST in the executable image.

  -  It sets flags in the executable image that cause
     the image activator to pass control to the debugger
     when you enter the RUN command.

 The following table summarizes the level of DST and GST
 information passed to the debugger depending on the
 compiler or LINK command option.  The compiler command
 qualifier controls the level of DST and GST information
 passed to the linker.  The LINK command qualifier
 controls not only how much of that information is
 passed to the debugger but also how (or if) you can
 invoke the debugger.

           DST                         DST Data  GST Data
 Compiler  Data in   LINK    Command   Passed    Passed
 Command   Object    Command to Invoke to        to
 Qualifier Module    Qualif. Debugger  Debugger  Debugger

 /DEBUG    Full      /DEBUG  RUN       Full      Full

 /DEBUG=   Traceback /DEBUG  RUN       Traceback Full
   TRACE   only                        only

 /NODEBUG  None      /DEBUG  RUN       None      Full

 /DEBUG    Full      /TRACE  RUN/DEBUG Traceback Only
                                       only      universal
                                                 symbols

 /DEBUG=   Traceback /TRACE  RUN/DEBUG Traceback Only
   TRACE   only                        only      universal
                                                 symbols

 /NODEBUG  None      /TRACE  RUN/DEBUG None      Only
                                                 universal
                                                 symbols

 /DEBUG    Full     /NOTRACE Cannot    None      None

 LINK/TRACEBACK and LINK/NODEBUG are equivalent.  This
 is the default for the LINK command.

 A universal symbol is a symbol that is defined in one
 image and referenced in another.  A universal symbol
 must be defined as such at link time.  See Debugging
 Shareable Images for information about universal
 symbols and shareable images.

 If you specify /NODEBUG with the compiler command and
 subsequently link and execute the image, the debugger
 issues the following message when it is invoked:

   NOLOCALS, image does not contain local symbols

 The preceding message, which occurs whether you linked
 with the /TRACEBACK or /DEBUG qualifier, indicates that
 no DST has been created for that image.  Therefore, you
 have access only to global symbols contained in the
 GST.

 If you do not specify /DEBUG with the LINK command, the
 debugger issues the following message when it is
 invoked:

   NOGLOBALS, some or all global symbols not accessible

 The preceding message indicates that the only global
 symbol information available during the debugging
 session is the following:

  -  Information about global symbols that is stored in
     the DST

  -  Information about universal symbols that is stored
     in the GST

=title Controlling Symbols in Debugged Images
=include gen g_Symb_complink
=include gen g_symb
 Symbol records occupy space within the executable
 image.  After you have debugged your program, you might
 want to link it again without using the /DEBUG
 qualifier, to make the executable image smaller.  This
 creates an image with only traceback data in the DST.

 The command LINK/NOTRACEBACK enables you to secure the
 contents of an image from users after it has been
 debugged.  Use this command for images that are to be
 installed with privileges.

 When you enter LINK/NOTRACEBACK, no symbolic
 information (including traceback data) is passed to the
 image.  Moreover, the debugger cannot be invoked,
 either by the RUN/DEBUG command, or by a CTRL/Y --
 DEBUG sequence while the program is running.

=title Setting and Canceling Modules
=include gen g_symb_complink
=include gen g_DST_GST_RST
=include gen g_symb_share
=include gen g_symb_share symb_share_access
=include gen g_symb
 To set or cancel a module, choose Modules...  from the
 Data menu.  The Modules dialog box lists the modules of
 your program and identifies which modules are set.

 You need to set a module if the debugger is unable to
 locate a symbol that you have specified (for example, a
 variable name X) and issues a diagnostic message such
 as the following:

    NOSYMBOL, symbol 'X' is not in the symbol table

 The following paragraphs explain module setting and the
 conditions under which you might need to set or cancel
 modules.

 Complete symbol information is passed from your
 program's source code to the debugger when you compile
 and link the program using the /DEBUG command
 qualifier.

 When you invoke the debugger, symbol information is
 contained in the DST and GST, within the executable
 image.  The DST contains detailed information about
 local and global symbols.  The GST duplicates some of
 the global symbol information contained in the DST.

 To facilitate symbol searches, the debugger loads
 symbol information from the DST and GST into a run-time
 symbol table (RST), where that information can be
 accessed efficiently.  Unless symbol information is in
 the RST, the debugger does not recognize or properly
 interpret the associated symbols.

 Because the RST takes up memory, the debugger loads it
 dynamically, anticipating what symbols you might want
 to reference in the course of program execution.  The
 loading process is called module setting, because all
 symbol information for a given module is loaded into
 the RST at one time.

 At debugger startup, all GST records are loaded into
 the RST because global symbols must be accessible
 throughout the debugging session.  Also, the debugger
 sets the module that contains the main program (the
 routine specified by the image transfer address, where
 execution is suspended at the start of a debugging
 session).  You therefore have access to all global
 symbols and to any local symbols that should be visible
 within the main program.

 Subsequently, whenever execution of the program is
 interrupted, the debugger sets the module that contains
 the routine in which execution is suspended.  This
 enables you to reference the symbols that should be
 visible at the current PC value (in addition to the
 global symbols).

 If you try to reference a symbol that is defined in a
 module that has not been set, the debugger warns you
 that the symbol is not in the RST.  For example:

    Examine X
    NOSYMBOL, symbol 'X' is not in the symbol table

 You must then set the module containing that symbol
 explicitly by choosing Modules...  from the Data menu.

 When a module is set, the debugger automatically
 allocates memory as needed by the RST.  This can
 eventually slow down the debugger as more modules are
 set.  If performance becomes a problem, you can reduce
 the number of set modules, thereby automatically
 releasing memory, or you can disable dynamic module
 setting:

  -  Choose Modules...  from the Data menu to cancel a
     module (delete its symbol information from the
     RST).

  -  Choose Other Attributes...  from the Customize menu
     to disable or enable dynamic module setting.


 The topic Accessing Symbols in Shareable Images
 explains how to set images and modules when debugging
 shareable images.

=title Symbolizing Addresses and Registers
=include gen g_DST_GST_RST
=include gen g_symb
 The symbols that are declared in your program (the
 names or routines, variables, and so on) are symbolic
 address expressions that denote memory addresses or
 registers.

 If a memory address or register has a symbolic name,
 you can symbolize that address or register---that is,
 you can obtain the symbolic name that denotes the
 address or register.  To do so, choose Symbolize
 Address or Register...  from the Addresses and
 Registers submenu of the Data menu.

 If a memory address does not have a symbolic name, the
 debugger might partially symbolize the address as an
 offset, in bytes, from some symbolic address
 expression, such as the name of a routine or shareable
 image.

=title Resolving Symbol Ambiguities
=include gen g_symbol_lookup_conv
=include gen g_using_pathnames_uniquely
=include gen g_resolve_symb_using_callframe
=include gen g_symb
 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, using the scope and visibility rules of
 the currently set language and the ordering of routine
 calls on the call stack.

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

  -  It might not be able to determine the particular
     declaration of the symbol that you intended.  For
     example:

       Examine X
       %DEBUG-W-NOUNIQUE, symbol 'X' is not unique

  -  It might reference the declaration that is visible
     in the current scope, 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.  There are two techniques:

  -  Specify a path name prefix with the symbol.  For
     example, if the variable X is defined in two
     modules named COUNTER and SWAP, the path name
     SWAP\X uniquely specifies the declaration of X in
     module SWAP.  This technique can always be used to
     resolve symbol ambiguities.

  -  If the different declarations of the symbol are
     within routines that are currently active on the
     call stack, use the Call Frame arrow buttons in the
     main window to reset the reference for looking up
     symbols to the appropriate call frame.  With this
     technique, you do not need to specify a path name
     prefix.

=title Symbol Lookup Conventions
=include gen g_DST_GST_RST
=include gen g_resolve_symb
=include gen g_symb
 Symbol ambiguities can occur when a symbol (for
 example, a variable name X) is defined in more than one
 routine or other program unit.

 The following paragraphs explain how the debugger
 searches for symbols, resolving most potential symbol
 ambiguities using the scope and visibility rules of the
 programming language and also its own rules.  The topic
 Resolving Symbol Ambiguities describes supplementary
 techniques that you can use when necessary.

 You can specify symbolic address expressions in dialog
 boxes and debugger commands by using either a path name
 or the exact symbol.

 If you use a path name, the debugger looks for the
 symbol in the scope denoted by the path name prefix.
 For example, if you specify the path name MOD3\ROUT1\X,
 the debugger looks for symbol X in routine ROUT1 of
 module MOD3.

 If you do not specify a path name prefix, by default
 the debugger searches the run-time symbol table (RST)
 as explained in the following paragraphs.

 First, the debugger looks for symbols in the PC scope
 (also known as scope 0, or call frame 0), according to
 the scope and visibility rules of the currently set
 language.  This means that, typically, the debugger
 first looks within the block or routine surrounding the
 current PC value (where execution is currently
 suspended).  If the symbol is not found, the debugger
 searches the nesting program unit, then its nesting
 unit, and so on.  The precise manner, which depends on
 the language, guarantees that the correct declaration
 of a symbol that is defined multiple times is chosen.

 However, note that you can reference symbols throughout
 your program, not just those that are visible in the PC
 scope as defined by the language.  This is necessary so
 you can set breakpoints in arbitrary areas or examine
 arbitrary variables, and so on.  Therefore, if the
 symbol is not visible in the PC scope, the debugger
 continues searching as follows.

 After the PC scope, the debugger searches the scope of
 the calling routine (if any), then its caller, and so
 on.  The complete search list is denoted 0,1,2...N,
 where 0 denotes the PC scope and N is the number of
 calls in the call stack.  Within each scope (call
 frame), the debugger uses the visibility rules of the
 language to locate a symbol.

 This search list, based on the call stack, enables the
 debugger to resolve symbol ambiguities in a convenient,
 predictable way.

 If the symbol is still not found, the debugger searches
 the rest of the RST-that is, the other set modules and
 the global symbol table (GST).  At this point the
 debugger does not attempt to resolve symbol
 ambiguities.  Instead, if more than one occurrence of
 the symbol is found, the debugger issues a message such
 as the following:

    NOUNIQUE, symbol 'X' is not unique

 In such cases, use the techniques explained in the
 topic Resolving Symbol Ambiguities.

=title Using Path Names to Specify Symbols Uniquely
=include gen g_resolve_symb
=include gen g_symbol_lookup_conv
=include gen g_DST_GST_RST
=include gen g_symb
 If the debugger cannot resolve an ambiguity, you can
 add a path name prefix to the symbol to indicate the
 scope for that symbol.  For example, the address
 expression TEST\SWAP\X could specify the declaration of
 symbol X in routine SWAP of module TEST.

 To determine the path name prefix that you should use
 to resolve a symbol ambiguity, proceed as follows:

 1.  Choose Show Variable...  from the Variable submenu
     of the Data menu.

 2.  Specify the variable name (or other symbol) in the
     Variable field.

 3.  Click on OK or Apply.  The debugger displays all
     path names for the specified symbol (corresponding
     to all declarations of that symbol) that are
     currently loaded in the RST.

 4.  You can then use the appropriate path name prefix
     to specify the symbol uniquely.

 For example, the following Show Variable output
 identifies three separate declarations of symbol COUNT,
 in modules MOD7, MOD4, and MOD2:

    data MOD7\ROUT3\BLOCK1\COUNT
    data MOD4\ROUT2\COUNT
    routine MOD2\ROUT1\ROUT3\COUNT

 The first two declarations of COUNT are variables
 (data).  The last declaration listed is a routine.  The
 path name prefix for each declaration indicates the
 path (scope) that the debugger must follow to reach
 that particular declaration.  For example,
 MOD4\ROUT2\COUNT denotes the declaration of COUNT in
 routine ROUT2 of module MOD4.

 The path name format is as follows.  The leftmost
 element of a path name is the module name.  Moving
 toward the right, the path name lists any successively
 nested routines and blocks that enclose the particular
 declaration of the symbol (which is the rightmost
 element).  A backslash character (\) is used to
 separate elements (except when the language is Ada,
 where a period is used, to parallel Ada syntax).

 You can abbreviate a path name by deleting the names of
 nesting program units starting from the left, leaving
 enough of the path name to specify it uniquely.  For
 example, ROUT3\COUNT is a valid abbreviated path name
 for routine COUNT in the first Show Variable example.

 Note that the Show Variable output identifies global
 symbols twice, because global symbols are included both
 in the DST and in the GST.  For example:

    data ALPHA\X                ! global X
    data ALPHA\BETA\X           ! local X
    data X (global)             ! same as ALPHA\X

Additional information available:

symb scope linesymb scope path callssymb scope path routsymb scope path globl

=title Specifying Source Line Numbers in Arbitrary Modules
=include gen g_using_pathnames_uniquely
 The debugger looks up line numbers as it looks up any
 other symbols you specify.  By default, if first looks
 in the module in which execution is suspended.

 A common use of path names is for specifying a line
 number in an arbitrary module.  For example, you can
 set a tracepoint on line 26 of module TEST by
 specifying the address expression TEST\%LINE 26.

=title Specifying Symbols in Routines on the Call Stack
=include gen g_resolve_symb_using_callframe
=include gen g_using_pathnames_uniquely
 You can use a numeric path name to specify the scope
 for a routine on the call stack.  The path name prefix
 '0\' denotes the PC scope, the path name prefix '1\'
 denotes scope 1, and so on.

 For example, the path names 0\Y and 2\Y specify two
 declarations of Y, which are visible in scope 0 and
 scope 2, respectively.

 You can also use the Call Frame arrow buttons in the
 main window to reset the scope to another call frame on
 the call stack.

=title Specifying Routine Invocations
=include gen g_resolve_symb_using_callframe
=include gen g_using_pathnames_uniquely
 When a routine is called recursively, you might need to
 distinguish among several calls to the same routine,
 all of which generate new symbols with identical names.

 You can include an invocation number in a path name to
 indicate a particular call to a routine.  The number
 must be a nonnegative integer and must follow the name
 of the rightmost routine in the path name.  Zero
 denotes the most recent invocation; 1 denotes the
 previous invocation, and so on.  For example, if PROG
 calls COMPUTE and COMPUTE calls itself recursively, and
 each call creates a new variable SUM, the following
 path name specifies the variable SUM for the most
 recent call to COMPUTE:

    PROG\COMPUTE 0\SUM

 To refer to the variable SUM that was generated in the
 previous call to COMPUTE, you express the path name
 with a 1 in place of the 0.

 When you do not include an invocation number, the
 debugger assumes that the reference is to the most
 recent call to the routine (the default invocation
 number is 0).

 You can also use the Call Frame arrow buttons in the
 main window to reset the scope to another call frame on
 the call stack.

=title Specifying Global Symbols
=include gen g_using_pathnames_uniquely
 To specify a global symbol uniquely, use a backslash
 (\) as a prefix to the symbol.  For example, the path
 name \X specifies the global symbol X.

=title Debugging Shareable Images
=include gen g_symb
By default, your program might be linked with several
 Digital-supplied shareable images (for example, the
 run-time library image MTHRTL.EXE).  The additional
 topics explain how to control access to symbols when
 debugging user-defined shareable images.

 A shareable image is not intended to be directly
 executed.  A shareable image must first be included as
 input in the linking of an executable image, and then
 the shareable image is loaded at run time when the
 executable image is run.  You do not have to install a
 shareable image to debug it.  Instead, you can debug
 your own private copy by assigning a logical name to
 it.

 See the VMS Linker Utility Manual for more information
 about linking shareable images.

Additional information available:

symb share complinksymb share access

=title Compiling and Linking a Shareable Image for Debugging
=include gen g_symb_complink
=include gen g_DST_GST_RST
=include gen g_symb_share symb_share_access
=include gen g_symb_Share
=include gen g_symb
 The basic steps in compiling and linking a shareable
 image for debugging are as follows:

 1.  Compile the source files for the main image and for
     the shareable image, using the /DEBUG qualifier.

 2.  Link the shareable image with the /SHAREABLE and
     /DEBUG command qualifiers, declaring any universal
     symbols for that image using the UNIVERSAL linker
     option.  (A universal symbol is a symbol, for
     example a routine name, that is defined in a
     shareable image and referenced in another image.)

 3.  Link the shareable image against the main image,
     specifying the shareable image with the /SHAREABLE
     file qualifier as a linker option.  Also specify
     the /DEBUG command qualifier.

 4.  Define a logical name to point to the local copy of
     the shareable image.  You must specify the device
     and directory as well as the image name.
     Otherwise, the VMS image activator looks for an
     image of that name in the system default shareable
     image library (SYS$LIBRARY:IMAGELIB.OLB).

 5.  Execute the main image to invoke the debugger.  The
     shareable image is loaded at run time.

 These steps are illustrated next with a simple example.
 In the example, MAIN.FOR and SUB1.FOR are the source
 files for the main image (the executable image that you
 specify with the RUN command); SHR1.FOR and SHR2.FOR
 are the source files for the shareable image to be
 debugged.

 You compile the source files for each image as follows:

   $ FORTRAN/NOOPT/DEBUG MAIN,SUB1
   $ FORTRAN/NOOPT/DEBUG SHR1,SHR2

 You then use the LINK command to create the shareable
 image, also specifying any universal symbols:

   $ LINK/SHAREABLE/DEBUG SHR1,SHR2,SYS$INPUT:/OPTIONS
   UNIVERSAL=SHR_ROUT <CTRL/Z>
   $

 In the preceding example:

  -  The /SHAREABLE command qualifier creates the
     shareable image SHR1.EXE from the object files
     SHR1.OBJ and SHR2.OBJ.

  -  The /OPTIONS qualifier appended to SYS$INPUT:
     enables you to specify interactively the global
     symbol SHR_ROUT as a universal symbol.

  -  The /DEBUG command qualifier builds a DST and a GST
     for SHR1.EXE and puts them in that image.  The GST
     contains the universal symbol SHR_ROUT.  Note that
     the linker puts universal symbols in the GST unless
     you specify LINK/NOTRACEBACK, because universal
     symbols must be global symbols as well.

 You have now built the shareable image SHR1.EXE in your
 current default directory.  Because SHR1.EXE is a
 shareable image, you do not execute it directly with
 the RUN command.  Instead you link SHR1.EXE against the
 main (executable) image:

   $ LINK/DEBUG MAIN,SUB1,SYS$INPUT:/OPTION
   SHR1.EXE/SHAREABLE <CTRL/Z>
   $

 In the preceding example:

  -  The LINK command creates the executable image
     MAIN.EXE from MAIN.OBJ and SUB1.OBJ.

  -  The /DEBUG qualifier builds a DST and a GST for
     MAIN.EXE and puts them in that image.

  -  The /SHAREABLE qualifier appended to SHR1.EXE
     specifies that SHR1.EXE is to be linked against
     MAIN.EXE as a shareable image.

 When you execute the resulting main image, MAIN.EXE,
 any shareable images linked against it are loaded at
 run time.  However, by default the VMS image activator
 looks for shareable images in the system default
 shareable image library (SYS$LIBRARY:IMAGELIB.OLB).
 Therefore, you must define the logical name SHR1 to
 point to SHR1.EXE in your current default directory.
 Be sure to specify the device and directory:

   $ DEFINE SHR1 SYS$DISK:[]SHR1.EXE

 You can now invoke the debugger to debug both MAIN and
 SHR1 by entering the following command:

   $ RUN MAIN

=title Accessing Symbols in Shareable Images
=include gen g_symb_Share symb_share_complink
=include gen g_symb_complink
=include gen g_symb_mod_set
=include gen g_DST_GST_RST
=include gen g_symb_Share
=include gen g_symb
 By default, dynamic module and image setting is
 enabled.  Therefore, whenever the debugger interrupts
 execution, the debugger sets the image and module where
 execution is suspended, if they are not already set
 (unless the image was linked with the /NOTRACEBACK
 qualifier).

 Dynamic module and image setting gives you the
 following access to symbols automatically:

  -  You can reference symbols defined in all set
     modules in the image in which execution is
     suspended.

  -  You can reference symbols in the GST for that
     image, including any universal symbols defined for
     that image.

  -  By setting other modules in that image, you can
     reference any symbol defined in the image.

 After an image is set, it remains set until you cancel
 it (by choosing Images...  from the Data menu).

 If the debugger slows down as more images and modules
 are set, you can either cancel images or disable
 dynamic module and image setting.  To disable or enable
 dynamic module and image setting, Choose Other
 Attributes...  from the Customize menu.

 The last image that you or the debugger sets is the
 current image.  The current image is the debugging
 context for symbol lookup.  When performing any of the
 following operations, you can reference only the
 symbols that are defined in the current image:

  -  Setting or canceling modules

  -  Manipulating variables

  -  Evaluating language expressions

  -  Displaying source code

  -  Setting or canceling breakpoints, tracepoints, or
     watchpoints

 To reference a symbol in another image, proceed as
 follows:

 1.  Make that image the current image, by choosing
     Images...  from the Data menu.

 2.  Set the module where that symbol is defined, by
     choosing Modules...  from the Data menu.  (Setting
     an image does not set any modules).

 After you have set an image and set modules within that
 image, the image and modules remain set even if you
 establish a new current image.  However, you have
 access to symbols only in the current image at any one
 time.

 When you link shareable images for debugging, the
 linker builds a DST and a GST for each image.  To
 conserve memory, the debugger builds an RST for an
 image only when that image is set, either dynamically
 by the debugger or when you set it explicitly by
 choosing Images...  from the Data menu.

 The Images dialog box identifies all shareable images
 that are linked with your program, shows which images
 are set, and identifies the current image.  Only the
 main image is set initially when you invoke the
 debugger.

=title Debugging Optimized Code
=include gen g_invoke_options g_invoke_comp
=include gen g_display_source
=include gen g_display_instructions
=include gen 2Wind_Dialog_Box3g_predwnds g_src
=include gen 2Wind_Dialog_Box3g_predwnds g_inst
=include gen g_symb
By default, many compilers optimize the code they
 produce so that the program executes faster.  The net
 result is that the code that is executing as you debug
 might not match the source code displayed in the source
 window.  For example, some optimization techniques
 eliminate variables so that you no longer have access
 to them while debugging.

 To avoid the problems of debugging optimized code, many
 compilers allow you to specify the /NOOPTIMIZE (or
 equivalent) command qualifier at compile time.
 Specifying this qualifier inhibits most compiler
 optimization, thereby reducing discrepancies between
 the source code and executable code caused by
 optimization.

 If this option is not available to you, read the
 following paragraphs and the additional topics for
 information about how to debug optimized code.

 When debugging optimized code, use an instruction
 window, such as the predefined window INST, to display
 the decoded VAX assembly-language instruction stream of
 your program.  This is the exact code that is
 executing.

 You can display the source and instruction windows SRC
 and INST side by side by choosing Window Setups from
 the Customize menu and then clicking on the second
 window layout from the submenu.  This layout enables
 you to compare the source code and the decoded
 instructions for any part of your program.

 Another technique that is useful when debugging at the
 instruction level is to execute the program one
 instruction at a time.  To do so, choose Step by
 Instruction from the pop-up menu.

Additional information available:

symb opt Elim Vrblsymb opt Coding Ordersymb opt registerssymb opt cond codes

=title Optimization Resulting in Eliminated Variables
=include gen g_display_operands
=include gen g_symb_opt
 A compiler might optimize code by eliminating
 variables, either permanently or temporarily at various
 points during execution.  If you try to examine a
 variable X that no longer is accessible because of
 optimization, the debugger might display one of the
 following messages:

   UNALLOCATED, entity X was not allocated in memory
     (was optimized away)

   NOVALATPC, entity X does not have a value at the
     current PC (was optimized away)

 The following Pascal example shows how this could
 happen.

   PROGRAM DOC(OUTPUT);
      VAR
         X,Y: INTEGER;
      BEGIN
         X := 5;
         Y := 2;
         WRITELN(X*Y);
      END.

 If you compile this program with the /NOOPTIMIZE (or
 equivalent) qualifier, you obtain the following
 (normal) behavior when debugging:

   [Step]
   stepped to DOC\%LINE 5
        5:         X := 5;
   [Step]
   stepped to DOC\%LINE 6
        6:         Y := 2;
   [Step]
   stepped to DOC\%LINE 7
        7:         WRITELN(X*Y);
   [Examine X,Y]
   DOC\X:  5
   DOC\Y:  2

 If you compile the program with the /OPTIMIZE (or
 equivalent) qualifier, because the values of X and Y
 are not changed after the initial assignment, the
 compiler calculates X*Y, stores that value (10), and
 does not allocate storage for X or Y.  Therefore, after
 you invoke the debugger, a Step command takes you
 directly to line 7 rather than line 5.  Moreover, you
 cannot examine X or Y:

   [Examine X,Y]
   NOVALATPC, entity X does not have a value at the
      current PC (was optimized away)
   [Step]
   stepped to DOC\%LINE 7
        7:         WRITELN(X*Y);

 To see what values are being used in your optimized
 program, use the technique described in the topic
 Displaying Decoded Instruction Operand Information to
 display the instruction at the current PC value,
 including the values and symbolization of all of the
 operands.

 For example, the following lines show the optimized
 code when the PC value is at the WRITELN statement:

   [Step]
   stepped to DOC\%LINE 7
        7:         WRITELN(X*Y);
   [Examine .%PC]
   DOC\%LINE 7:    PUSHL   S^#10

 In contrast, the following lines show the unoptimized
 code at the WRITELN statement:

   [Step]
   stepped to DOC\%LINE 7
        7:         WRITELN(X*Y);
   [Examine .%PC]
   DOC\%LINE 7:    MOVL    S^#10,B^-4(FP)
        B^-4(FP)   2146279292 contains 62914576

=title Optimization Resulting in Changes in Coding Order
=include gen g_symb_opt
 Several methods of optimizing code consist of
 performing operations in a sequence different from the
 sequence specified in the source code.  Sometimes code
 is eliminated altogether.

 As a result, the source code displayed by the debugger
 does not correspond exactly to the actual code being
 executed.

 To illustrate, the following example depicts a segment
 of source code from a FORTRAN program as it might
 appear on a compiler listing or in a screen-mode source
 display.  This code segment sets the first ten elements
 of array A to the value 1/X.

   line          source code
   ----          -----------
     5            DO 100 I=1,10
     6            A(I) = 1/X
     7        100 CONTINUE

 As the compiler processes the source program, it
 determines that the reciprocal of X need only be
 computed once, not ten times as the source code
 specifies, because the value of X never changes in the
 DO loop.  The compiler thus generates optimized code
 equivalent to the following code segment:

   line          optimized code equivalent
   ----          ----------------------
     5            TEMP = 1/X
                  DO 100 I=1,10
     6            A(I) = TEMP
     7        100 CONTINUE

 In the optimized code, the value of 1/X is computed
 once, saved in a temporary location, and then assigned
 to each A(I).  The optimized code now executes faster,
 but it no longer corresponds exactly to the source
 code.

 In this example, if you execute to line 5 by entering a
 Step command, the debugger displays the source line as
 it appears in the source file, not the optimized code
 equivalent that it is actually executing:

   stepped to PROG_\%LINE 5
          5:       DO 100 I=1,10

 At this point, if you enter another Step command to
 execute line 5, the debugger executes line 5 of the
 optimized code, not line 5 of the displayed source
 code.  Thus, the program computes the reciprocal of X
 and sets up the DO loop, whereas the source display
 indicates only that the DO loop is set up.

 This discrepancy is not obvious from looking at the
 displayed source line.  Furthermore, if the computation
 of 1/X were to fail because X is zero, it would appear
 from inspecting the source display that a division by
 zero had occurred on a source line that contains no
 division at all.

 This kind of apparent mismatch between source code and
 executable code should be expected from time to time
 when debugging optimized programs.  It can be caused
 not only by code motions out of loops, as in the
 previous example, but by a number of other optimization
 methods as well.

=title Optimization Resulting in Use of Registers
=include gen g_accessing_nonstatic_variables
=include gen g_symb_opt
 A compiler might determine that the value of an
 expression does not change between two given
 occurrences and might save the value in a register.  In
 such cases, the compiler does not recompute the value
 for the next occurrence, but assumes the value saved in
 the register is valid.

 If, while debugging a program, you change the value of
 the variable in the expression, the corresponding value
 stored in the register might not be.  Thus, when
 execution continues, the value in the register might be
 used instead of the changed value in the expression,
 causing unexpected results.

 In addition, when the value of a nonstatic variable is
 held in a register, its value in memory is generally
 invalid; therefore, a spurious value might be displayed
 if you examine a variable under these circumstances.

=title Optimization Resulting in Use of Condition Codes
=include gen g_symb_opt symb_opt_Elim_Vrbl
=include gen g_display_operands
=include gen g_symb_opt
 One optimization technique takes advantage of the way
 in which the VAX processor condition codes are set.
 For example, consider the following Pascal source code:

   X := X + 2.5;
   IF X < 0
   THEN
    .
    .

 Rather than test the new value of X to determine
 whether to branch, the optimized code bases its
 decision on the condition code setting after 2.5 is
 added to X.  Thus, if you attempt to set a breakpoint
 on the IF statement and deposit a different value into
 X, you do not achieve the intended result because the
 condition codes no longer reflect the value of X.  In
 other words, the decision to branch is being made
 without regard to the deposited value of the variable.

 You can determine the correct location for depositing a
 value so as to achieve the desired effect by using the
 technique described in the topic Displaying Decoded
 Instruction Operand Information.

 This technique enables you to display the instruction
 at the current PC value, including the values and
 symbolization of all of the operands.  See also
 Optimization Resulting in Eliminated Variables for an
 example.

=TITLE Debugging Configurations and Process Relationships
=include gen g_def_config
=include gen g_multiproc_config
=include gen g_proc_rel
=include gen g_multiproc
=include gen g_builtin_log DBG_PROCESS
=include gen g_invoke_options
You can invoke the debugger in either the default
 configuration or the multiprocess configuration to
 debug programs that run in either one or several
 processes, respectively.  The debugging configuration
 depends on the current definition of the logical name
 DBG$PROCESS, as indicated in the following table:

  Definition of Logical   Resulting Debugging
  Name DBG$PROCESS        Configuration
  ---------------------   -------------------

  Undefined or DEFAULT    Default (use this configuration
                          with a program that runs in one
                          process)

  MULTIPROCESS            Multiprocess (use this
                          configuration with a program
                          that runs in several processes)

 Note that the debugging configuration does not depend
 on whether the program runs in one or several
 processes.  Rather, the value of DBG$PROCESS determines
 whether or not debuggable images running in different
 processes can be controlled from the same debugging
 session.

 Before invoking the debugger, enter the DCL command
 SHOW LOGICAL DBG$PROCESS to determine the current
 definition of DBG$PROCESS and the resulting debugging
 configuration.

=TITLE Establishing the Default Debugging Configuration
=include gen g_multiproc_config
=include gen g_builtin_log DBG_PROCESS
=include gen g_debug_config
 Use the default debugging configuration to debug
 programs that run in only one process.

 The default debugging configuration is achieved when
 the logical name DBG$PROCESS is either undefined (the
 default) or has the value DEFAULT.

 The following command indicates that a default
 debugging configuration is in effect:

  $ SHOW LOGICAL DBG$PROCESS
  NOTRAN, no translation for logical name DBG$PROCESS

 If DBG$PROCESS has the value MULTIPROCESS and you want
 to debug a program that runs in only one process, enter
 the following command:

   $ DEFINE DBG$PROCESS DEFAULT

=title Establishing the Multiprocess Debugging Configuration
=include gen g_debug_config
=include gen g_def_config
=include gen g_invoke_options
=include gen g_multiproc
=include gen g_builtin_log DBG_PROCESS
 Use the multiprocess debugging configuration to debug a
 multiprocess program.  The multiprocess configuration
 enables you to interact with several processes from one
 debugging session.

 To establish a multiprocess debugging configuration,
 enter the following command before invoking the
 debugger:

   $ DEFINE/JOB DBG$PROCESS MULTIPROCESS

 As shown here, when defining DBG$PROCESS for a
 multiprocess configuration, use a job logical
 definition so that the definition applies to all
 processes in that job.  The reason is that an image can
 be connected to (and controlled by) an existing
 multiprocess debugging session only if the process
 running the image is in the same job as the process
 running the debugging session.

 In the typical multiprocess scenario, the program runs
 in one master parent process and several subprocesses.
 The debugger is invoked from the master process, then
 the program creates subprocesses during execution (a
 subprocess can also become the parent of another level
 of subprocesses).

 Another possible scenario is that the program runs in
 several peer processes.  There is no master process.
 This configuration would result if you invoked the
 debugger by running one debuggable image and then used
 the SPAWN/NOWAIT command repeatedly to spawn other
 processes and run a debuggable image in each spawned
 process.

=TITLE Process Relationships When Debugging
=include gen g_debug_config
 The debugger consists of two parts:  A relatively small
 kernel debugger image (DEBUG.EXE) and a larger main
 debugger image (DEBUGSHR.EXE) that contains most of the
 debugger code.  This separation reduces potential
 interference between the debugger and the program being
 debugged.  The separation also makes it possible to
 have two debugging configurations:  default and
 multiprocess.

 Regardless of the configuration, the presence of a main
 debugger running in a process establishes a unique
 debugging session.

 When you invoke the debugger in the default
 configuration, the program runs in its process along
 with the kernel debugger, and a new subprocess is
 created to run the main debugger.  A new main debugger
 (and, therefore, a new debugging session) is
 established every time you invoke the debugger.

 In the multiprocess configuration, the program being
 debugged runs in several processes.  Each process that
 is running one or more images under debugger control is
 also running a local copy of the kernel debugger.  The
 main debugger, running in a separate subprocess,
 communicates with the other processes through their
 kernel debuggers.

 Although all processes of a multiprocess configuration
 must be in the same job, they do not have to be related
 in a particular process/subprocess hierachy.  Moreover,
 the program images running in separate processes do not
 have to communicate with each other.

=title Debugging Multiprocess Programs
=include gen g_multiproc_config
=include gen Process_Status_L_Button
=include gen g_multiproc_activation_options
=include gen g_ctrl_visib_proc
=include gen 2Proc_Dialog_Box3proc_opt4show
=include gen g_multiproc_states
=include gen g_multiproc_program_execution
=include gen g_multiproc_termination
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen g_multiproc_advanced_concepts
To debug a multiprocess program (a program that runs in
 more than one process), you must establish a
 multiprocess debugging configuration before invoking
 the debugger.  That configuration enables you to
 interact with several processes from one debugging
 session.

 You can then invoke the debugger in the usual way.

 After invoking the debugger, you can control the
 execution of individual processes, examine data
 associated with specific processes, display information
 in process-specific windows, and so on.

 Choose Processes...  from the Data menu to manipulate
 processes.

=title Bringing a Process under Debugger Control
=include gen g_invoke_options
=include gen g_invoke_options g_invoke_debug
=include gen g_builtin_ssdebug
=include gen g_multiproc_states
=include gen g_multiproc
 You can bring a process under debugger control in any
 of the following ways:

  -  You execute the image with the DCL RUN[/DEBUG]
     command (or by choosing the equivalent FileView
     menu item).

  -  During a debugging session, if one or more
     processes in the same job as the session are
     waiting to be connected to the debugger, you enter
     a command that starts execution, such as Step.

  -  You enter a CTRL/Y -- DEBUG sequence from DCL level
     to interrupt an image that is running without
     debugger control.

  -  A program that is not under debugger control
     signals SS$_DEBUG.

 An image is debuggable if it was not linked with the
 /NOTRACEBACK qualifier.  In addition, full symbolic
 information is available only if the image's modules
 were compiled and linked with the /DEBUG qualifier.

 When a process comes under debugger control, it is
 initially in the "activated" state.  This condition is
 traced by default, as if you had set a tracepoint using
 the process activation option (choose Break...  from
 the Control menu to set a tracepoint).  You can
 optionally set a breakpoint on process activation.

 As with a one-process program, when the main process of
 a multiprocess program comes under debugger control,
 execution is suspended at the start of the main
 program.

 Within a given debugging session, the debugger assigns
 a process number sequentially, starting with process 1,
 to each process that comes under debugger control.  If
 a process is terminated by choosing Exit from the
 Processes option menu, its process number is not reused
 during that debugging session.

 To identify all processes that are currently under
 debugger control, choose Processes...  from the Data
 menu.  They are identified in the list box of the
 Processes dialog box.  Processes are listed
 sequentially by their debugger-assigned process number.

=title Controlling the Visible Process
=include gen Process_Status_L_Button
=include gen g_multiproc
 The visible process is the process that is currently
 the context for issuing process-specific commands.  It
 is identified in the Visible Process field of the main
 window.

 Process-specific commands are those that start
 execution (Step, Go, and so on) and those used for
 looking up symbols, setting breakpoints, looking at the
 call stack and registers, and so on.  For example,
 examine and deposit operations are directed at the
 visible process.

 Commands that are not process specific are those that
 do not depend on the mapping of virtual memory but,
 rather, affect the entire debugging environment ---for
 example, setting the default radix or disabling dynamic
 process setting through, respectively, the Radix and
 Other Attributes dialog boxes (Customize menu).

 When you invoke the debugger, the visible process is
 the first process that comes under debugger control,
 namely the process running the main program.  Within a
 given debugging session, the debugger assigns a process
 number sequentially, starting with process 1, to each
 process that comes under debugger control.

 You can reset the visible process to another process
 that is currently under debugger control in two
 possible ways:

  -  Click on the Visible Process arrow buttons in the
     main window.  This sets the visible process to the
     next or previous process on the debugger's list of
     processes.

  -  Choose Processes...  from the Data menu, then:

      -  Choose the option 'Set visible process' from
         the Processes dialog box.

      -  Specify a process in the Process field.

      -  Click on OK or Apply.

Additional information available:

g dynamic proc set

=title Dynamic Process Setting
=include gen g_multiproc
 By default, dynamic process setting is enabled.  As a
 result, whenever the debugger interrupts execution, the
 process in which execution is suspended becomes the
 visible process automatically.  (To enable or disable
 dynamic process setting, choose Other Attributes...
 from the Customize menu, then use the Dynamic Process
 Setting button).

 The visible process is always identified in the Visible
 Process field in the main window.

 Dynamic process setting occurs in the following
 situations:  when a breakpoint or watchpoint is
 triggered, at an exception, on the completion of a Step
 command, or when the last process performs an image
 exit.

 Dynamic process setting is disabled by turning off the
 Dynamic Process Setting button in the Other Attributes
 dialog box.  When dynamic process setting is disabled,
 the visible process remains unchanged until you specify
 another process explicity by means of either the
 Visible Process arrow buttons in the main window or the
 Processes dialog box (Data menu).

=title Debugging States for Multiprocess Programs
=include gen 2Proc_Dialog_Box3proc_opt4show
=include gen g_multiproc
 To determine the debugging state of one or more
 processes, choose Processes...  from the Data menu,
 then choose the Show brief or Show detailed option from
 the option menu of the Processes dialog box.

 The possible debugging states for a multiprocess
 program are as follows.  Entries from this list are
 shown in the State field when you use the Show brief or
 Show detailed option.

 Debugging State    Description
 ---------------    -----------
  Activated         The image and its process have just
                    been brought under debugger control,
                    either through a DCL RUN/DEBUG
                    command, a CTRL/Y -- DEBUG sequence,
                    or by the program signaling SS$_DEBUG
                    while it was not under debugger control.

  Break             A breakpoint was triggered.
  Break on branch
  Break on call
  Break on
  instruction
  Break on lines
  Break on modify of
  Break on return
  Exception break
  Exception break
    preceding

  Interrupted       Execution was interrupted in that
                    process, either because execution
                    was suspended in another process,
                    or because the user interrupted
                    program execution with the Stop
                    button in the main window.

  Step              A Step command has completed.
  Step on return

  Terminated        The image indicated has stopped
                    execution but the process is still
                    under debugger control. Therefore,
                    you can obtain information about the
                    image and its process. You can use
                    the Exit option (Processes dialog
                    box) to terminate the process.

  Trace             A tracepoint was triggered.
  Trace on branch
  Trace on call
  Trace on
  instruction
  Trace on lines
  Trace on modify of
  Trace on return
  Exception trace
  Exception trace
    preceding

  Unhandled         An unhandled exception was
  exception         encountered.

  Watch of          A watchpoint was triggered.

=title Controlling the Execution of a Multiprocess Program
=include gen g_multiproc
 When you enter a command that starts program execution,
 such as Step or Go, the command is executed in the
 context of the visible process.  However, images in any
 other processes that are not on hold can also execute.

 After execution is started, the way in which it
 continues depends on the state of the Interrupt
 Processes button in the Other Attributes dialog box (to
 open the dialog box, choose Other Attributes...  from
 the Customize menu).  By default, execution continues
 until it is suspended in any process.  At that point,
 execution is interrupted in any other processes that
 were executing images.

Additional information available:

g holding processes

=title Holding and Releasing Processes
=include gen g_multiproc
 A command that starts execution is executed in the
 context of the visible process, but it also causes
 execution to start in other processes.

 To inhibit execution in a process, put it on hold:

 1.  Choose Processes...  from the Data menu.

 2.  Choose the Hold option from the process option menu
     of the dialog box.

 3.  Specify the process to be put on hold in the
     Process field of the dialog box.

 4.  Click on OK or Apply.

 For example, suppose process 1 is the visible process
 and process 3 is put on hold.  Then, when execution is
 started with a Step command (in process 1), execution
 also starts in all other processes except process 2.

 The word "HOLD" next to a process name in the list box
 of the Processes dialog box indicates that a process is
 on hold.  The condition is also indicated in a Show
 brief or Show detailed display chosen from the dialog
 box.

 Note that a hold condition is ignored in the visible
 process.  Therefore, putting all processes on hold is a
 convenient way to confine execution to the visible
 process.  This feature is useful if, for example, you
 want to use the Call command (Control menu) to execute
 a dump routine that is not part of the execution stream
 of your program.

 To release a process from a hold condition, use the
 Release option from the Processes dialog box.

=title Controlling and Monitoring Process Termination
=include gen g_multiproc_states
=include gen g_end_session
=include gen g_multiproc
 When the main image of a process runs to completion,
 the process goes into the "terminated" debugging state
 (not to be confused with process termination in the VMS
 sense).  This condition is traced by default, as if you
 had set a tracepoint using the process termination
 option (Break dialog box, Control menu).  You can set a
 breakpoint on process termination.

 When a process is in the terminated debugging state, it
 is still known to the debugger.  You can display
 process information (choose Processes...  from the Data
 menu), examine variables, and so on.  When the last
 image of the program exits, the debugger gains control
 rather than ending the debugging session.

 To terminate individual processes (in the VMS sense)
 and remove them from debugger control, use the Exit
 option in the Processes dialog box, specifying one or
 more processes to be terminated.  After it is
 terminated with the Exit option, a process is no longer
 identified in the list box of the Processes dialog box.

 Terminating the last process ends the debugging
 session.

=title Advanced Concepts and Possible Errors
=include gen g_debug_config
=include gen g_builtin_log DBG_PROCESS
=include gen g_multiproc
 The debugging configuration (default or multiprocess)
 is controlled entirely by the definition of
 DBG$PROCESS.  If some of the processes in a job have
 different definitions of DBG$PROCESS, the resulting
 debugging configuration can be very confusing.

 The value of DBG$PROCESS is checked when the kernel
 debugger is first invoked.

 Consider the following scenario:

   $ DEFINE/JOB DBG$PROCESS MULTIPROCESS
   $ RUN TEST

   DBG_1> SET BREAK/ACTIVATING;GO
   break at program activation in %PROCESS_NUMBER 2
   DBG_2> SHOW PROCESS/ALL
    Number  Name     Hold  State         Current PC
        1 SMITH            interrupted   TEST\%LINE 50
   *    2 SMITH_1          activated     SUB1\%LINE 71
   DBG_2> SPAWN DEFINE DBG$PROCESS DEFAULT
   DBG_2> SET BREAK %LINE 100;GO !TEST creates a new process

   break at %LINE 100 in %PROCESS_NUMBER 2
   DBG> SHOW PROCESS/ALL
    Number  Name     Hold  State         Current PC
   *    3 SMITH_2          activated     MYPROG\%LINE 10
   DBG_2> SHOW PROCESS/ALL
    Number  Name     Hold  State         Current PC
        1 SMITH            interrupted   TEST\%LINE 50
   *    2 SMITH_1          break         SUB1\%LINE 100
   DBG>

 Because of the re-assigment of DBG$PROCESS, there are
 two different main debuggers (two debugging sessions)
 in the job.  Both of these debuggers are using the same
 terminal for input and output.  Therefore, the prompts
 and output lines from the two sessions are intermixed
 on the screen.

 This is generally not a desirable configuration.
 However, although potentially confusing, this
 configuration can be useful if you need to debug an
 experimental copy of a program without disturbing your
 primary debugging session which has several processes
 connected to it.

=title Debugger Support for Languages
=include gen g_langexpr
=include gen g_multilang
You can use the debugger with the following VAX
 languages:  Ada, BASIC, BLISS, C, COBOL, DIBOL,
 FORTRAN, MACRO-32, Pascal, PL/I, RPG II, and SCAN.  The
 debugger recognizes the syntax, data typing, and
 scoping rules of a given language.

 The debugger also recognizes the operators and
 expression syntax of a given language.  Therefore, you
 can compute the value of a source-language expression
 using the syntax of the currently set language.

 The additional topics provide the following information
 for each language:

  -  Supported operators in language expressions

  -  Supported constructs in language expressions and
     address expressions

  -  Supported data types

  -  Any other language-specific features (for example,
     event keywords in the case of Ada and SCAN)

 For further information about language-specific
 debugger support, refer to the documentation furnished
 with a particular language.

 If your program is written in more than one language,
 you can change the debugging context from one language
 to another during a debugging session.  To do so,
 choose Language from the Customize menu.

 In addition, when debugging a program that is written
 in an unsupported language, you can set the language to
 Unknown.  To maximize the usability of the debugger
 with unsupported languages, this setting causes the
 debugger to accept a large set of data formats and
 operators, including some that might be specific to
 only a few supported languages.  The operators and
 constructs that are recognized when the language is set
 to Unknown are identified in Debugger Support for an
 Unknown Language.

Additional information available:

ADABASICBLISSCCOBOLDIBOLFORTRAN
MACROPASCALPLIRPGSCAN

Unknown

=title Debugger Support for Ada
=include gen g_lang
 The additional topics provide information about
 debugger support for Ada.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data TypesPredefined AttributesTasking statesEvents

=title Operators in Language Expressions
=include gen g_lang ada
Supported Ada operators in language expressions follow:

  Kind     Symbol   Function

  Prefix   +        Unary plus (identity)

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    MOD      Modulus

  Infix    REM      Remainder

  Infix    **       Exponentiation

  Prefix   ABS      Absolute value

  Infix    &        Concatenation (only string types)

  Infix    =        Equality (only scalar and string
                    types)

  Infix    /=       Inequality (only scalar and string
                    types)

  Infix    >        Greater than (only scalar and string
                    types)

  Infix    >=       Greater than or equal (only scalar
                    and string types)

  Infix    <        Less than (only scalar and string
                    types)

  Infix    <=       Less than or equal (only scalar and
                    string types)

  Prefix   NOT      Logical NOT

  Infix    AND      Logical AND (not for bit arrays)

  Infix    OR       Logical OR (not for bit arrays)

  Infix    XOR      Logical exclusive OR (not for bit
                    arrays)

 Note:  The debugger does not support:

  -  Operations on entire arrays or records

  -  Short-circuit control forms:  and then, or else

  -  Membership tests:  in, not in

  -  User-defined operators

=title Constructs in Language and Address Expressions
=include gen g_lang ada
Supported constructs in language and address expressions
 for Ada follow:

  Symbol  Construct

  ( )     Subscripting

  .       Record component selection

  .ALL    Pointer dereferencing

=title Data Types
=include gen g_lang ada
Supported Ada data types follow:

  ADA Type                   VAX Type Name

  INTEGER                    Longword Integer (L)

  SHORT_INTEGER              Word Integer (W)

  SHORT_SHORT_INTEGER        Byte Integer (B)

  SYSTEM.UNSIGNED_QUADWORD   Quadword Unsigned (QU)

  SYSTEM.UNSIGNED_LONGWORD   Longword Unsigned (LU)

  SYSTEM.UNSIGNED_WORD       Word Unsigned (WU)

  SYSTEM.UNSIGNED_BYTE       Byte Unsigned (BU)

  FLOAT                      F_Floating (F)

  SYSTEM.F_FLOAT             F_Floating (F)

  SYSTEM.D_FLOAT             D_Floating (D)

  LONG_FLOAT                 D_Floating (D), if pragma
                             LONG_FLOAT(D_FLOAT) is in
                             effect. G_Floating (G), if
                             pragma LONG_FLOAT(G_FLOAT)
                             is in effect.

  SYSTEM.G_FLOAT             G_Floating (G)

  SYSTEM.H_FLOAT             H_Floating (H)

  LONG_LONG_FLOAT            H_Floating (H)

  Fixed                      (None)

  STRING                     ASCII Text (T)

  BOOLEAN                    Aligned Bit String (V)

  BOOLEAN                    Unaligned Bit String (VU)

  Enumeration                For any enumeration type
                             whose value fits into an
                             unsigned byte or word:
                             Byte Unsigned (BU) or Word
                             Unsigned (WU), respectively.
                             Otherwise: No corresponding
                             VAX data type.

  Arrays                     (None)

  Records                    (None)

  Access (pointers)          (None)

  Tasks                      (None)

=title Predefined Attributes
=include gen g_lang ada
Supported Ada predefined attributes follow:

  Attribute      Debugger Support

  P'CONSTRAINED  For a prefix P that denotes a record
                 object with discriminants. The value of
                 P'CONSTRAINED reflects the current state
                 of P (constrained or unconstrained).

  P'FIRST        For a prefix P that denotes an
                 enumeration type or a subtype of an
                 enumeration type. Yields the lower bound
                 of P.

  P'FIRST        For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 lower bound of the first index range.

  P'FIRST(N)     For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 lower bound of the Nth index range.

  P'LAST         For a prefix P that denotes an
                 enumeration type, or a subtype of an
                 enumeration type. Yields the upper bound
                 of P.

  P'LAST         For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 upper bound of the first index range.

  P'LAST(N)      For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 upper bound of the Nth index range.

  P'LENGTH       For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 number of values of the first index
                 range (zero for a null range).

  P'LENGTH(N)    For a prefix P that is appropriate
                 for an array type, or that denotes a
                 constrained array subtype. Yields the
                 number of values of the Nth index range
                 (zero for a null range).

  P'POS(X)       For a prefix P that denotes an
                 enumeration type or a subtype of an
                 enumeration type. Yields the position
                 number of the value X. The first
                 position is 0.

  P'PRED(X)      For a prefix P that denotes an
                 enumeration type or a subtype of an
                 enumeration type. Yields the value of
                 type P which has a position number one
                 less than that of X.

  P'SIZE         For a prefix P that denotes an object.
                 Yields the number of bits allocated to
                 hold the object.

  P'SUCC(X)      For a prefix P that denotes an
                 enumeration type or a subtype of an
                 enumeration type. Yields the value of
                 type P which has a position number one
                 more than that of X.

  P'VAL(N)       For a prefix P that denotes an
                 enumeration type or a subtype of an
                 enumeration type. Yields the value of
                 type P which has the position number N.
                 The first position is 0.

=title Ada Task States and Substates
=include gen g_builtin_tasks
=include gen g_lang ada
Debugger support for Ada task states and substates is as
 shown in the additional topics.

 The task state and substate keywords indicated can
 appear in a Show Task display.  This is the output
 resulting from either a SHOW TASK command or choosing
 'Show brief' or 'Show detailed' on the Tasks dialog box
 in the DECwindows interface.  To open the dialog box,
 choose Tasks...  from the Data menu.

Additional information available:

Task statesTask substates

=title Task States
=include gen g_lang ada tasking_states
The following task-state keywords can appear in a Show
 Task display and can also be used with the SHOW
 TASK/STATE= command.

  Task State  Description

  RUNNING     Currently running on the processor. This is
              the active task.

  READY       Eligible to execute and waiting for the
              processor to be made available.

  SUSPENDED   Waiting for an event rather than for the
              availability of the processor. For
              example, when a task is created, it
              remains in the suspended state until it
              is activated.

  TERMINATED  Terminated.

=title Task Substates
=include gen g_lang ada tasking_states
The following task-substate keywords can appear in a
 Show Task display:

  Task Substate     Description

  Abnormal          Task has been aborted.

  Accept            Task is waiting at an accept
                    statement that is not inside a select
                    statement.

  Activating        Task is elaborating its declarative
                    part.

  Activating tasks  Task is waiting for tasks it has
                    created to finish activating.

  Completed [abn]   Task is completed due to an abort
                    statement, but is not yet terminated.
                    In Ada, a task waiting for dependent
                    tasks at its "end" is called
                    "completed". After the dependent
                    tasks are terminated, the state
                    changes to terminated.

  Completed [exc]   Task is completed due to an unhandled
                    exception, but is not yet terminated.

  Completed         Task is completed. No abort statement
                    was issued, and no unhandled
                    exception occurred.

  Delay             Task is waiting at a delay statement.

  Dependents        Task is waiting for dependent tasks
                    to terminate.

  Dependents [exc]  Task is waiting for dependent tasks
                    to allow an unhandled exception to
                    propagate.

  Entry call        Task is waiting for its entry call to
                    be accepted.

  Invalid state     There is a bug in the VAX Ada run-
                    time library. Please submit a
                    Software Performance Report (SPR).

  I/O or AST        Task is waiting for I/O completion or
                    an AST.

  Not yet           Task is waiting to be activated by
  activated         the task that created it.

  Select or delay   Task is waiting at a select statement
                    with a delay alternative.

  Select or term.   Task is waiting at a select statement
                    with a terminate alternative.

  Select            Task is waiting at a select statement
                    with neither an else, delay, or
                    terminate alternative.

  Shared resource   Task is waiting for an internal
                    shared resource.

  Terminated [abn]  Task was terminated by an abort.

  Terminated [exc]  Task was terminated because of an
                    unhandled exception.

  Terminated        Task terminated normally.

  Timed entry call  Task is waiting in a timed entry
                    call.

=title Ada Events
=include gen g_builtin_exceptions
=include gen g_lang ada
You can use the following Ada event keywords with the
 'on the specified event' option when setting
 breakpoints or tracepoints (choose Break...  from the
 Control menu).

  Exception-Related Events
  ------------------------
  Event Keyword         Description

  HANDLED               Triggers when an exception is
                        about to be handled in an Ada
                        exception handler, including an
                        others handler.

  HANDLED_OTHERS        Triggers only when an exception
                        is about to be handled in an
                        others Ada exception handler.

  Task Exception-Related Events
  -----------------------------
  Event Keyword         Description

  RENDEZVOUS_EXCEPTION  Triggers when an exception begins
                        to propagate out of a rendezvous.

  DEPENDENTS_EXCEPTION  Triggers when an unhandled
                        exception causes a task to wait
                        for dependent tasks in some scope
                        (includes unhandled exceptions,
                        such as task rundown signals,
                        that are internal to the VAX
                        Ada run-time library). Often
                        immediately precedes a deadlock.

  Task Termination Events
  -----------------------
  Event Keyword         Description

  TERMINATED            Triggers when a task is
                        terminating, whether normally,
                        by abort, or by exception.

  EXCEPTION_TERMINATED  Triggers when a task is
                        terminating due to an unhandled
                        exception.

  ABORT_TERMINATED      Triggers when a task is
                        terminating due to an abort.

  Low-Level Task Scheduling Events
  --------------------------------
  Event Keyword         Description

  RUN                   Triggers when a task is about to
                        run.

  PREEMPTED             Triggers when a task is being
                        preempted from the RUN state, and
                        its state changes to READY.

  ACTIVATING            Triggers when a task is about to
                        begin its activation (that is, at
                        the beginning of the elaboration
                        of the declarative part of its
                        task body).

  SUSPENDED             Triggers when a task is about to
                        be suspended.

=title Debugger Support for BASIC
=include gen g_lang
 The additional topics provide information about
 debugger support for BASIC.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang basic
Supported BASIC operators in language expressions
 follow:

  Kind     Symbol  Function

  Prefix   +       Unary plus

  Prefix   -       Unary minus (negation)

  Infix    +       Addition, String concatenation

  Infix    -       Subtraction

  Infix    *       Multiplication

  Infix    /       Division

  Infix    **      Exponentiation

  Infix    ^       Exponentiation

  Infix    =       Equal to

  Infix    <>      Not equal to

  Infix    ><      Not equal to

  Infix    >       Greater than

  Infix    >=      Greater than or equal to

  Infix    =>      Greater than or equal to

  Infix    <       Less than

  Infix    <=      Less than or equal to

  Infix    =<      Less than or equal to

  Prefix   NOT     Bit-wise NOT

  Infix    AND     Bit-wise AND

  Infix    OR      Bit-wise OR

  Infix    XOR     Bit-wise exclusive OR

  Infix    IMP     Bit-wise implication

  Infix    EQV     Bit-wise equivalence

=title Constructs in Language and Address Expressions
=include gen g_lang basic
Supported constructs in language and address expressions
 for BASIC follow:

  Symbol  Construct

  ( )     Subscripting

  ::      Record component selection

=title Data Types
=include gen g_lang basic
Supported BASIC data types follow:

  BASIC Type   VAX Type Name

  BYTE         Byte Integer (B)

  WORD         Word Integer (W)

  LONG         Longword Integer (L)

  SINGLE       F_Floating (F)

  DOUBLE       D_Floating (D)

  GFLOAT       G_Floating (G)

  HFLOAT       H_Floating (H)

  DECIMAL      Packed Decimal (P)

  STRING       ASCII Text (T)

  RFA          (None)

  Arrays       (None)

  Records      (None)

 Note:

  -  Expressions that overflow in the BASIC language do
     not necessarily overflow when evaluated by the
     debugger.  The debugger tries to compute a
     numerically correct result, even when the BASIC
     rules call for overflows.  This difference is
     particularly likely to affect DECIMAL computations.

  -  BASIC constants of the forms
     [radix]"numeric-string"[type] (such as
     "12.34"GFLOAT) or n% (such as 25% for integer 25)
     are not supported in debugger expressions.

=title Debugger Support for BLISS
=include gen g_lang
 The additional topics provide information about
 debugger support for BLISS.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang bliss
Supported BLISS operators in language expressions
 follow:

  Kind    Symbol  Function

  Prefix  .       Indirection

  Prefix  +       Unary plus

  Prefix  -       Unary minus (negation)

  Infix   +       Addition

  Infix   -       Subtraction

  Infix   *       Multiplication

  Infix   /       Division

  Infix   MOD     Remainder

  Infix   ^       Left shift

  Infix   EQL     Equal to

  Infix   EQLU    Equal to

  Infix   EQLA    Equal to

  Infix   NEQ     Not equal to

  Infix   NEQU    Not equal to

  Infix   NEQA    Not equal to

  Infix   GTR     Greater than

  Infix   GTRU    Greater than unsigned

  Infix   GTRA    Greater than unsigned

  Infix   GEQ     Greater than or equal to

  Infix   GEQU    Greater than or equal to unsigned

  Infix   GEQA    Greater than or equal to unsigned

  Infix   LSS     Less than

  Infix   LSSU    Less than unsigned

  Infix   LSSA    Less than unsigned

  Infix   LEQ     Less than or equal to

  Infix   LEQU    Less than or equal to unsigned

  Infix   LEQA    Less than or equal to unsigned

  Prefix  NOT     Bit-wise NOT

  Infix   AND     Bit-wise AND

  Infix   OR      Bit-wise OR

  Infix   XOR     Bit-wise exclusive OR

  Infix   EQV     Bit-wise equivalence

=title Constructs in Language and Address Expressions
=include gen g_lang bliss
Supported constructs in language and address expressions
 for BLISS follow:

  Symbol     Construct

  [ ]        Subscripting

  [fldname]  Field selection

  <p,s,e>    Bit field selection

=title Data Types
=include gen g_lang bliss
Supported BLISS data types follow:

  BLISS Type         VAX Type Name

  BYTE               Byte Integer (B)

  WORD               Word Integer (W)

  LONG               Longword Integer (L)

  BYTE UNSIGNED      Byte Unsigned (BU)

  WORD UNSIGNED      Word Unsigned (WU)

  LONG UNSIGNED      Longword Unsigned (LU)

  VECTOR             (None)

  BITVECTOR          (None)

  BLOCK              (None)

  BLOCKVECTOR        (None)

  REF VECTOR         (None)

  REF BITVECTOR      (None)

  REF BLOCK          (None)

  REF BLOCKVECTOR    (None)

=title Debugger Support for C
=include gen g_lang
 The additional topics provide information about
 debugger support for C.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang c
Supported C operators in language expressions follow:

  Kind    Symbol    Function

  Prefix  *         Indirection

  Prefix  &         Address of

  Prefix  SIZEOF    Size of

  Prefix  -         Unary minus (negation)

  Infix   +         Addition

  Infix   -         Subtraction

  Infix   *         Multiplication

  Infix   /         Division

  Infix   %         Remainder

  Infix   <<        Left shift

  Infix   >>        Right shift

  Infix   ==        Equal to

  Infix   !=        Not equal to

  Infix   >         Greater than

  Infix   >=        Greater than or equal to

  Infix   <         Less than

  Infix   <=        Less than or equal to

  Prefix  (tilde)   Bit-wise NOT

  Infix   &         Bit-wise AND

  Infix   |         Bit-wise OR

  Infix   ^         Bit-wise exclusive OR

  Prefix  !         Logical NOT

  Infix   &&        Logical AND

  Infix   ||        Logical OR

=title Constructs in Language and Address Expressions
=include gen g_lang c
Supported constructs in language and address expressions
 for C follow:

  Symbol  Construct

  [ ]     Subscripting

  .       Structure component selection

  ->      Pointer dereferencing

=title Data Types
=include gen g_lang c
Supported C data types follow:

  Supported C data types follow:
  C Type                VAX Type Name

  INT                   Longword Integer (L)

  UNSIGNED INT          Longword Unsigned (LU)

  SHORT INT             Word Integer (W)

  UNSIGNED SHORT INT    Word Unsigned (WU)

  CHAR                  Byte Integer (B)

  UNSIGNED CHAR         Byte Unsigned (BU)

  FLOAT                 F_Floating (F)

  DOUBLE                D_Floating (D)

  ENUM                  (None)

  STRUCT                (None)

  UNION                 (None)

  Pointers              (None)

  Arrays                (None)

 Note:

  -  Symbol names are case sensitive for C, meaning that
     uppercase and lowercase letters are treated as
     different characters.

  -  Because the exclamation point (!) is an operator in
     C, it cannot be used as the comment delimiter.
     When the language is set to C, the debugger instead
     accepts /* as the comment delimiter.  The comment
     continues to the end of the current line.  (A
     matching */ at the end of the comment is neither
     needed nor recognized.) To permit debugger log
     files to be used as debugger input, the debugger
     recognizes !  as a comment delimiter if it is the
     first nonspace character on a line.

  -  The debugger accepts the prefix asterisk (*) as an
     indirection operator in both C language expressions
     and debugger address expressions.  In address
     expressions, prefix "*" is synonymous to prefix "."
     or "@" when the language is set to C.

  -  The debugger does not support any of the assignment
     operators in C (or any other language) in order to
     prevent unintended modifications to the program
     being debugged.  Hence such operators as =, +=, -=,
     ++, and - are not recognized.  To alter the
     contents of a memory location, use an explicit
     DEPOSIT command.

=title Debugger Support for COBOL
=include gen g_lang
 The additional topics provide information about
 debugger support for COBOL.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang cobol
Supported COBOL operators in language expressions
 follow:

  Kind     Symbol   Function

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    **       Exponentiation

  Infix    =        Equal to

  Infix    NOT =    Not equal to

  Infix    >        Greater than

  Infix    NOT <    Greater than or equal to

  Infix    <        Less than

  Infix    NOT >    Less than or equal to

  Infix    NOT      Logical NOT

  Infix    AND      Logical AND

  Infix    OR       Logical OR

=title Constructs in Language and Address Expressions
=include gen g_lang cobol
Supported constructs in language and address expressions
 for COBOL follow:

  Symbol  Construct

  ( )     Subscripting

  OF      Record component selection

  IN      Record component selection

=title Data Types
=include gen g_lang cobol
Supported COBOL data types follow:

  COBOL Type            VAX Type Name

  COMP                  Longword Integer (L,LU)

  COMP                  Word Integer (W,WU)

  COMP                  Quadword Integer (Q,QU)

  COMP-1                F_Floating (F)

  COMP-2                D_Floating (D)

  COMP-3                Packed Decimal (P)

  INDEX                 Longword Integer (L)

  Alphanumeric          ASCII Text (T)

  Records               (None)

  Numeric Unsigned      Numeric string, unsigned (NU)

  Leading Separate      Numeric string, left separate
  Sign                  sign (NL)

  Leading Overpunched   Numeric string, left overpunched
  Sign                  sign (NLO)

  Trailing Separate     Numeric string, right separate
  Sign                  sign (NR)

  Trailing Overpunched  Numeric string, right overpunched
  Sign                  sign (NRO)

 Note:

  -  The debugger can show source text included in a
     program with the COPY or COPY REPLACING verb.
     However, when COPY REPLACING is used, the debugger
     always shows the original source text as it
     appeared before text replacement.  In other words,
     the original source file is shown instead of the
     modified source text generated by the COPY
     REPLACING verb.

  -  The debugger cannot show the original source lines
     associated with the code for a REPORT section.  You
     can see the DATA SECTION source lines associated
     with a REPORT section, but no source lines are
     associated with the compiled code that generates
     the report.

=title Debugger Support for DIBOL
=include gen g_lang
 The additional topics provide information about
 debugger support for DIBOL.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang dibol
Supported DIBOL operators in language expressions
 follow:

  Kind     Symbol   Function

  Prefix   #        Round

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    //       Division with fractional result

  Infix    .EQ.     Equal to

  Infix    .NE.     Not equal to

  Infix    .GT.     Greater than

  Infix    .GE.     Greater than or equal to

  Infix    .LT.     Less than

  Infix    .LE.     Less than or equal to

  Infix    .NOT.    Logical NOT

  Infix    .AND.    Logical AND

  Infix    .OR.     Logical OR

  Infix    .XOR.    Exclusive OR

=title Constructs in Language and Address Expressions
=include gen g_lang dibol
Supported constructs in language and address expressions
 for DIBOL follow:

  Symbol  Construct

  ( )     Substring

  [ ]     Subscripting

  .       Record component selection

=title Data Types
=include gen g_lang dibol
Supported DIBOL data types follow:

  DIBOL Type          VAX Type Name

  I1                  Byte Integer (B)

  I2                  Word Integer (W)

  I4                  Longword Integer (L)

  Pn                  Packed Decimal String (P)

  Pn.m                Packed Decimal String (P)

  Dn                  Numeric String, Zoned Sign (NZ)

  Dn.m                Numeric String, Zoned Sign (NZ)

  An                  ASCII Text (T)

  Arrays              (None)

  Records             (None)

=title Debugger Support for FORTRAN
=include gen g_lang
 The additional topics provide information about
 debugger support for FORTRAN.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Predefined SymbolsData Types

=title Operators in Language Expressions
=include gen g_lang fortran
Supported FORTRAN operators in language expressions
 follow:

  Kind     Symbol    Function

  Prefix   +         Unary plus

  Prefix   -         Unary minus (negation)

  Infix    +         Addition

  Infix    -         Subtraction

  Infix    *         Multiplication

  Infix    /         Division

  Infix    **        Exponentiation

  Infix    //        Concatenation

  Infix    .EQ.      Equal to

  Infix    .NE.      Not equal to

  Infix    .GT.      Greater than

  Infix    .GE.      Greater than or equal to

  Infix    .LT.      Less than

  Infix    .LE.      Less than or equal to

  Prefix   .NOT.     Logical NOT

  Infix    .AND.     Logical AND

  Infix    .OR.      Logical OR

  Infix    .XOR.     Exclusive OR

  Infix    .EQV.     Equivalence

  Infix    .NEQV.    Exclusive OR

=title Constructs in Language and Address Expressions
=include gen g_lang fortran
Supported constructs in language and address expressions
 for FORTRAN follow:

  Symbol   Construct

  ( )      Subscripting

  .        Record component selection

=title Predefined Symbols
=include gen g_lang fortran
Supported FORTRAN predefined symbols follow:

  Symbol     Description

  .TRUE.     Logical True

  .FALSE.    Logical False

=title Data Types
=include gen g_lang fortran
Supported FORTRAN data types follow:

  FORTRAN Type    VAX Type Name

  LOGICAL*1       Byte Unsigned (BU)

  LOGICAL*2       Word Unsigned (WU)

  LOGICAL*4       Longword Unsigned (LU)

  INTEGER*2       Word Integer (W)

  INTEGER*4       Longword Integer (L)

  REAL*4          F_Floating (F)

  REAL*8          D_Floating (D)

  REAL*8          G_Floating (G)

  REAL*16         H_Floating (H)

  COMPLEX*8       F_Complex (FC)

  COMPLEX*16      D_Complex (DC)

  COMPLEX*16      G_Complex (GC)

  CHARACTER       ASCII Text (T)

  Arrays          (None)

  Records         (None)

 Note:

  -  Even though the VAX type codes for unsigned
     integers (BU, WU, LU) are used internally to
     describe the LOGICAL data types, the debugger (like
     the compiler) treats LOGICAL variables and values
     as being signed when used in language expressions.

  -  The debugger prints the numeric values of LOGICAL
     variables or expressions instead of TRUE or FALSE.
     Normally, only the low-order bit of a LOGICAL
     variable or value is significant (0 is FALSE and 1
     is TRUE).  However, VAX FORTRAN does allow all bits
     in a LOGICAL value to be manipulated and LOGICAL
     values can be used in integer expressions.  For
     this reason, it is at times necessary to see the
     entire integer value of a LOGICAL variable or
     expression, and that is what the debugger shows.

  -  COMPLEX constants such as (1.0,2.0) are not
     supported in debugger expressions.

=title Debugger Support for MACRO
=include gen g_lang
 The additional topics provide information about
 debugger support for MACRO.

Additional information available:

OperatorsConstructsData Types

=title Operators in Language Expressions
=include gen g_lang macro Constructs
=include gen g_lang macro Data_Types
=include gen g_lang macro
Language MACRO does not have expressions in the same
 sense as high-level languages.  Only assembly-time
 expressions and only a limited set of operators are
 accepted.

 To enable you to use expressions at debug-time as
 freely as in other languages, the debugger accepts a
 number of operators in MACRO language expressions that
 are not found in MACRO itself.

 In particular, the debugger accepts a complete set of
 comparison and Boolean operators modeled after BLISS.
 It also accepts the indirection operator and the normal
 arithmetic operators.

  Kind     Symbol   Function

  Prefix   @        Indirection

  Prefix   .        Indirection

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    MOD      Remainder

  Infix    @        Left shift

  Infix    EQL      Equal to

  Infix    EQLU     Equal to

  Infix    NEQ      Not equal to

  Infix    NEQU     Not equal to

  Infix    GTR      Greater than

  Infix    GTRU     Greater than unsigned

  Infix    GEQ      Greater than or equal to

  Infix    GEQU     Greater than or equal to unsigned

  Infix    LSS      Less than

  Infix    LSSU     Less than unsigned

  Infix    LEQ      Less than or equal to

  Infix    LEQU     Less than or equal to unsigned

  Prefix   NOT      Bit-wise NOT

  Infix    AND      Bit-wise AND

  Infix    OR       Bit-wise OR

  Infix    XOR      Bit-wise exclusive OR

  Infix    EQV      Bit-wise equivalence

=title Constructs in Language and Address Expressions
=include gen g_lang macro Operators
=include gen g_lang macro data_types
=include gen g_lang macro
Supported constructs in language and address expressions
 for MACRO follow:

  Symbol   Construct

  [ ]      Subscripting

  <p,s,e>  Bitfield selection as in BLISS

 Note:

 The DST information generated by the MACRO assembler
 treats a label that is followed by an assembler
 directive for storage allocation as an array variable
 whose name is the label.  This enables you to use the
 array syntax of a high-level language when examining or
 manipulating such data.

 In the following example of MACRO source code, the
 label LAB4 designates hexadecimal data stored in four
 words:

     LAB4:    .WORD    ^X3F,5[2],^X3C

 The debugger treats LAB4 as an array variable.  For
 example, the next command displays the value stored in
 each element (word):

     DBG> EXAMINE LAB4
     .MAIN.\MAIN\LAB4
         [0]:        003F
         [1]:        0005
         [2]:        0005
         [3]:        003C
     DBG>

 The next command displays the value stored in the
 fourth word (the first word is indexed as element "0"):

     DBG> EXAMINE LAB4[3]
     .MAIN.\MAIN\LAB4[3]:    03C
     DBG>

=title Data Types
=include gen g_lang macro Operators
=include gen g_lang macro constructs
=include gen g_lang macro
Supported MACRO data types follow:

  MACRO Type        VAX Type Name

  (Not applicable)  Byte Unsigned (BU)

  (Not applicable)  Word Unsigned (WU)

  (Not applicable)  Longword Unsigned (LU)

  (Not applicable)  Byte Integer (B)

  (Not applicable)  Word Integer (W)

  (Not applicable)  Longword Integer (L)

  (Not applicable)  F_Floating (F)

  (Not applicable)  D_Floating (D)

  (Not applicable)  G_Floating (G)

  (Not applicable)  H_Floating (H)

  (Not applicable)  Packed decimal (P)

=title Debugger Support for Pascal
=include gen g_lang
 The additional topics provide information about
 debugger support for Pascal.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Predefined SymbolsBuilt-in FunctionsData Types

=title Operators in Language Expressions
=include gen g_lang pascal
Supported Pascal operators in language expressions
 follow:

  Kind     Symbol   Function

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition, concatenation

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Real division

  Infix    DIV      Integer division

  Infix    MOD      Modulus

  Infix    REM      Remainder

  Infix    **       Exponentiation

  Infix    IN       Set membership

  Infix    =        Equal to

  Infix    <>       Not equal to

  Infix    >        Greater than

  Infix    >=       Greater than or equal to

  Infix    <        Less than

  Infix    <=       Less than or equal to

  Prefix   NOT      Logical NOT

  Infix    AND      Logical AND

  Infix    OR       Logical OR

=title Constructs in Language and Address Expressions
=include gen g_lang pascal
Supported constructs in language and address expressions
 for Pascal follow:

  Symbol  Construct

  [ ]     Subscripting

  .       Record component selection

  ^       Pointer dereferencing

=title Predefined Symbols
=include gen g_lang pascal
Supported Pascal predefined symbols follow:

  Symbol   Meaning

  TRUE     Boolean True

  FALSE    Boolean False

  NIL      Nil pointer

=title Built-In Functions
=include gen g_lang pascal
Supported Pascal built-in functions follow:

  Symbol  Meaning

  SUCC    Logical successor

  PRED    Logical predecessor

=title Data Types
=include gen g_lang pascal
Supported Pascal data types follow:

  PASCAL Type       VAX Type Name

  INTEGER           Longword Integer (L)

  INTEGER           Word Integer (W,WU)

  INTEGER           Byte Integer (B,BU)

  UNSIGNED          Longword Unsigned (LU)

  UNSIGNED          Word Unsigned (WU)

  UNSIGNED          Byte Unsigned (BU)

  SINGLE            F_Floating (F)

  DOUBLE            D_Floating (D)

  DOUBLE            G_Floating (G)

  QUADRUPLE         H_Floating (H)

  BOOLEAN           (None)

  CHAR              ASCII Text (T)

  VARYING OF CHAR   Varying Text (VT)

  SET               (None)

  FILE              (None)

  Enumerations      (None)

  Subranges         (None)

  Typed Pointers    (None)

  Arrays            (None)

  Records           (None)

  Variant records   (None)

 Note:

 The debugger accepts Pascal set constants such as
 [1,2,5,8..10] and [RED, BLUE] in Pascal language
 expressions.

=title Debugger Support for PL/I
=include gen g_lang
 The additional topics provide information about
 debugger support for PL/I.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang pli
Supported PL/I operators in language expressions follow:

  Kind     Symbol   Function

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    **       Exponentiation

  Infix    ||       Concatenation

  Infix    =        Equal to

  Infix    ^=       Not equal to

  Infix    >        Greater than

  Infix    >=       Greater than or equal to

  Infix    ^<       Greater than or equal to

  Infix    <        Less than

  Infix    <=       Less than or equal to

  Infix    ^>       Less than or equal to

  Prefix   ^        Bit-wise NOT

  Infix    &        Bit-wise AND

  Infix    |        Bit-wise OR

=title Constructs in Language and Address Expressions
=include gen g_lang pli
Supported constructs in language and address expressions
 for PL/I follow:

  Symbol  Construct

  ( )     Subscripting

  .       Structure component selection

  ->      Pointer dereferencing

=title Data Types
=include gen g_lang pli
Supported PL/I data types follow:

  PL/I Type            VAX Type Name

  FIXED BINARY         Longword Integer (L)

  FIXED DECIMAL        Packed Decimal (P)

  FLOAT BINARY         F_Floating (F)

  FLOAT DECIMAL        F_Floating (F)

  FLOAT BIN/DEC        D_Floating (D)

  FLOAT BIN/DEC        G_Floating (G)

  FLOAT BIN/DEC        H_Floating (H)

  BIT                  Bit (V)

  BIT                  Bit Unaligned (VU)

  CHARACTER            ASCII Text (T)

  CHARACTER VARYING    Varying Text (VT)

  FILE                 (None)

  Labels               (None)

  Pointers             (None)

  Arrays               (None)

  Structures           (None)

 Note:

 The debugger treats all numeric constants of the form n
 or n.n in PL/I language expressions as packed decimal
 constants, not integer or floating-point constants, in
 order to conform to PL/I language rules.  The internal
 representation of 10 is therefore 0C01 hexadecimal, not
 0A hexadecimal.  You can enter floating-point constants
 using the syntax nEn or n.nEn.

 There is no PL/I syntax for entering constants whose
 internal representation is Longword Integer.  This
 limitation is not normally significant when debugging,
 since the debugger supports the PL/I type conversion
 rules.  However, it is possible to enter integer
 constants by using the debugger's %HEX, %OCT, and %BIN
 operators.

=title Debugger Support for RPG
=include gen g_lang
 The additional topics provide information about
 debugger support for RPG.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang rpg
Supported RPG operators in language expressions follow:

  Kind     Symbol   Function

  Prefix   +        Unary plus

  Prefix   -        Unary minus (negation)

  Infix    +        Addition

  Infix    -        Subtraction

  Infix    *        Multiplication

  Infix    /        Division

  Infix    =        Equal to

  Infix    NOT =    Not equal to

  Infix    >        Greater than

  Infix    NOT <    Greater than or equal to

  Infix    <        Less than

  Infix    NOT >    Less than or equal to

  Prefix   NOT      Logical NOT

  Infix    AND      Logical AND

  Infix    OR       Logical OR

=title Constructs in Language and Address Expressions
=include gen g_lang rpg
Supported constructs in language and address expressions
 for RPG follow:

  Symbol   Construct

  ( )      Subscripting

=title Data Types
=include gen g_lang rpg
Supported RPG data types follow:

  RPG Type              VAX Type Name

  Longword              Longword Integer (L)

  Word                  Word Integer (W)

  Packed Decimal        Packed Decimal (P)

  Character             ASCII Text (T)

  Overpunched Decimal   Right Overpunched Sign (NRO)

  Arrays                (None)

  Tables                (None)

 Note:

 The debugger supports access to all RPG indicators and
 labels used in the current program.  You can thus
 examine labels such as *DETL and indicators such as
 *INLR and *IN01 through *IN99.

=title Debugger Support for SCAN
=include gen g_lang
 The additional topics provide information about
 debugger support for SCAN.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data TypesEvents

=title Operators in Language Expressions
=include gen g_lang scan
Supported SCAN operators in language expressions follow:

  Kind     Symbol  Function

  Prefix   +       Unary plus

  Prefix   -       Unary minus (negation)

  Infix    +       Addition

  Infix    -       Subtraction

  Infix    *       Multiplication

  Infix    /       Division

  Infix    &       Concatenation

  Infix    =       Equal to

  Infix    <>      Not equal to

  Infix    >       Greater than

  Infix    >=      Greater than or equal to

  Infix    <       Less than

  Infix    <=      Less than or equal to

  Prefix   NOT     Complement

  Infix    AND     Intersection

  Infix    OR      Union

  Infix    XOR     Exclusive OR

=title Constructs in Language and Address Expressions
=include gen g_lang scan
Supported constructs in language and address expressions
 for SCAN follow:

  Symbol  Construct

  ( )     Subscripting

  .       Record component selection

  ->      Pointer dereferencing

=title Data Types
=include gen g_lang scan
Supported SCAN data types follow:

  SCAN Type           VAX Type Name

  BOOLEAN             (None)

  INTEGER             Longword Integer (L)

  POINTER             (None)

  FIXED STRING (n)    TEXT with CLASS=S

  VARYING STRING      TEXT with CLASS=VS
  (n)

  DYNAMIC STRING      TEXT with CLASS=D

  TREE                (None)

  TREEPTR             (None)

  RECORD              (None)

  OVERLAY             (None)

 Note:

  -  There is no specific support for the following
     datatypes:  FILE, TOKEN, GROUP, SET.  Examining a
     FILL variable displays the contents of the
     specified variable as a string by default, and so
     might have little meaning.  If the characteristics
     of the fill are known, then the appropriate
     qualifier (/HEX, and so on) applied to the command
     produces a more meaningful display.

  -  The following examples show how to examine SCAN
     TREE and TREEPTR variables.  To dump an entire SCAN
     tree or subtree:

       Examine tree_variable([subscript], . . .  )

     To dump the contents of a SCAN subtree:

       Examine treeptr_variable

     To dump an entire SCAN subtree:

       Examine treeptr_variable->

  -  DEPOSIT is not supported for SCAN TREE variables.
     You can set breakpoints on any SCAN label, line
     number, MACRO, or PROCEDURE.

=title Events
=include gen g_lang scan
You can use the following SCAN event keywords with the
 /EVENT qualifier of the SET BREAK, SET TRACE, CANCEL
 BREAK, and CANCEL TRACE commands.  You can also display
 these event keywords with the SHOW EVENT_FACILITY
 command.

  Event       Description

  TOKEN       A token is built.

  PICTURE     An operand in a picture is being matched.

  INPUT       A new line of the input stream is read.

  OUTPUT      A new line of the output stream is written.

  TRIGGER     A trigger macro is starting or terminating.

  SYNTAX      A syntax macro is starting or terminating.

  ERROR       Picture matching error recovery is starting
              or terminating.

=title Debugger Support for an Unknown Language
=include gen g_lang
 When debugging a program that is written in an
 unsupported language, you can set the language to
 Unknown.  To maximize the usability of the debugger
 with unsupported languages, this setting causes the
 debugger to accept a large set of data formats and
 operators, including some that might be specific to
 only a few supported languages.  The operators and
 constructs that are recognized when the language is set
 to Unknown are identified in the additional topics.

Additional information available:

Operators in Language ExpressionsConstructs in Language and Address Expressions
Data Types

=title Operators in Language Expressions
=include gen g_lang unknown
Supported operators in language expressions when the
 language is set to Unknown follow:

  Kind     Symbol  Function

  Prefix   +       Unary plus

  Prefix   -       Unary minus (negation)

  Infix    +       Addition

  Infix    -       Subtraction

  Infix    *       Multiplication

  Infix    /       Division

  Infix    **      Exponentiation

  Infix    &       Concatenation

  Infix    //      Concatenation

  Infix    =       Equal to

  Infix    <>      Not equal to

  Infix    /=      Not equal to

  Infix    >       Greater than

  Infix    >=      Greater than or equal to

  Infix    <       Less than

  Infix    <=      Less than or equal to

  Infix    EQL     Equal to

  Infix    NEQ     Not equal to

  Infix    GTR     Greater than

  Infix    GEQ     Greater than or equal to

  Infix    LSS     Less than

  Infix    LEQ     Less than or equal to

  Prefix   NOT     Logical NOT

  Infix    AND     Logical AND

  Infix    OR      Logical OR

  Infix    XOR     Exclusive OR

  Infix    EQV     Equivalence

=title Constructs in Language and Address Expressions
=include gen g_lang unknown
Supported constructs in language and address expressions
 when the language is set to Unknown follow:

  Symbol  Construct

  [ ]     Subscripting

  ( )     Subscripting

  .       Record component selection

  ^       Pointer dereferencing

=title Data Types
=include gen g_lang unknown
When the language is set to Unknown, the debugger
 understands all data types accepted by other languages
 except a few very language-specific types, such as
 picture types and file types.  In Unknown language
 expressions, the debugger accepts most scalar VAX
 Standard data types.

 Note:

  -  When the language is set to Unknown, the debugger
     accepts the dot-notation for record component
     selection.  If C is a component of a record B which
     in turn is a component of a record A, C can be
     referenced as "A.B.C".  Subscripts can be attached
     to any array components; if B is an array, for
     instance, C can be referenced as "A.B[2,3].C".

  -  When the language is set to Unknown, the debugger
     accepts both round and square subscript
     parentheses.  Hence, A[2,3] and A(2,3) are
     equivalent.

=title Effect of Debugger on Program Execution
Because the debugger acts as an exception handler, it
 uses the stack.  This can cause uninitialized variables
 saved on the stack to be modified by the debugger.

 If your program references an uninitialized variable
 that is in this state, the execution of the program can
 be affected.

 Another source of possible interference between the
 debugger and your program is that they share memory.
 If your program is sensitive to changes in memory
 usage, the execution of the program can be affected.

=title Getting Help on NonDebugger Diagnostic Messages
=include gen g_deb_messages
 The following help text is displayed if you try to get
 context-sensitive help on a nondebugger diagnostic
 message (for example, ACCVIO):

   No online help is available for this diagnostic message.

 Diagnostic messages for all VMS components and
 utilities are explained in the VMS System Messages and
 Recovery Procedures Volume, where they are listed
 alphabetically by message identifier.

=title Call Frame Field and Buttons in Main Window
=include gen g_callframe_label
=include gen g_callframe_buttons_display_src
=include gen g_callframe_buttons_display_inst
=include gen g_resolve_symb_using_callframe
=include gen g_symbol_lookup_conv
=include gen g_resolve_symb
=include gen g_builtin_nextprev_scope
=include gen g_display_source
=include gen g_display_instructions
=include gen g_symb_mod_set
=include gen g_symb
The Call Frame field in the main window identifies the
 routine that the debugger uses as reference for the
 following purposes:

  -  When displaying source code in the current source
     window (window SRC, by default)

  -  When displaying decoded VAX instructions in the
     current instruction window (window INST, by
     default, if that window is displayed)

  -  When searching for symbols (variable names, routine
     names, and so on) that you specify

 The number displayed in the Call Frame field, to the
 left of the routine name, denotes the associated call
 frame on the routine call stack.

 By default, the routine identified is the one in which
 execution is currently suspended (the routine
 associated with call frame 0, at the top of the stack).

 The Call Frame arrow buttons enable you to reset the
 reference for source and instruction display and for
 symbol lookup to another call frame, which is then
 identified in the Call Frame field.

 A Call Frame arrow button that is dimmed indicates that
 the scope reference is at the end of the call stack.

 Note that the arrow buttons do not affect the execution
 of your program.

 To obtain detailed information about the call stack,
 Choose Call Stack...  from the Data menu.

=title Visible Process Field and Buttons in Main Window
=include gen g_multiproc
The Visible Process field and buttons in the main window
 are used when debugging multiprocess programs (programs
 that run in more than one process).  For programs that
 run in one process, the Visible Process field
 identifies the name of the process that is running the
 program being debugged.

 For a multiprocess program, the Visible Process field
 identifies the process that is currently the context
 for issuing process-specific commands.
 Process-specific commands are those that start
 execution (Step, Go, and so on) and those used for
 looking up symbols, setting breakpoints, looking at the
 call stack and registers, and so on.

 Commands that are not process specific are those that
 do not depend on the mapping of virtual memory but,
 rather, affect the entire debugging environment.

Additional information available:

set visible process

=title Using the Visible Process Arrow Buttons
=include gen g_builtin_processes
=include gen Process_Status_L_Button
=include gen g_multiproc
 Use the Visible Process arrow buttons to set the
 visible process to another process that is currently
 under debugger control:

  -  Click on the right-arrow button to set the visible
     process to the process with the next higher process
     number.

  -  Click on the left-arrow button to set the visible
     process to the process with the next lower process
     number.

 The process list is circular.  For example, the next
 process after the highest-numbered process is the
 lowest-numbered process.

=title Current Entity Field and Buttons in Main Window
=include gen g_builtin_nextprev_entity
=include gen g_pathname
=include gen g_symb
The Current Entity field in the main window identifies
 the last entity that was examined or deposited into
 (for example, a variable or a code location).  It is
 also the entity currently defined by the built-in
 symbol %CURLOC.

 If symbolization is available, the entity might be
 displayed as a symbol with a path name prefix or
 perhaps as a byte offset from a symbolic address
 expression (for example, TEST\X+4).  Symbolic address
 expressions include variable names, routine names,
 labels, and line numbers.

 No entity is displayed unless you have previously
 specified one in an examine or deposit operation.  See
 Operations that Can Update the Current Entity Field.

 When a current entity is defined, you can use the
 Current Entity arrow buttons to examine consecutive
 logical entities.  Otherwise, the buttons are dimmed.

 The debugger uses the type of the current entity to
 determine the logical successor and predecessor
 entities.  The current entity is reset with each click
 of one of the arrow buttons.

 Thus, when the current entity is an array variable, you
 can use the arrow buttons to examine consecutive array
 elements.  When the current entity is a code location,
 you can use the arrow buttons to examine consecutive
 VAX assembly-language instructions.

 By default, the debugger assigns the type longword
 integer to addresses or registers that are not
 associated with a symbolic name and, therefore, are not
 associated with a compiler-generated type.  See
 Examining Consecutive Memory Addresses.

 The topic Current, Next, and Previous Entity Built-In
 Symbols identifies built-in symbols that, when used
 with the Examine command (and related dialog boxes),
 achieve the same effect as the Current Entity arrow
 buttons.

 Note that the concept of previous or next logical
 entity might not apply to some entities, such as
 noncomposite variables (integer, real, and so on).

Additional information available:

g update curloc operationsg examine arr buttonsg examine inst buttonsg examine memory buttons

=title Operations that Can Update the Current Entity Field
=include gen g_intro_to_addrexpr
=include gen g_builtin_nextprev_entity
=include gen g_specifying_code
=include gen Examine_Status_L_Button
 The Current Entity field in the main window identifies
 the last entity that was examined or deposited into
 (for example, a variable or a code location).

 The following operations can update the Current Entity
 Field:

  -  Clicking on the Examine button in the main window
     or choosing Examine from the pop-up menu.

  -  Using the following dialog boxes (which are
     accessible from the Data menu):

       Examine Variable, Deposit into Variable
       Examine Code, Deposit Code
       Examine (Deposit into) Address or Register

  -  Clicking on the Current Entity arrow buttons.

  -  Specifying any of the built-in symbols that denote
     an address expression when examining or depositing.
     See Current, Next, and Previous Entity Built-In
     Symbols.

  -  Using an Examine or Deposit command, for example in
     an Action field of a dialog box or in a command
     procedure.

 When you are examining code address expressions, the
 Current Entity field duplicates some of the information
 in the current source or instruction window.  The
 entity is shown as a pathname consisting of a module
 name, line number, possibly a byte offset, and so on.

=title Examining Consecutive Array Elements
=include gen g_specifying_variables
=include gen g_builtin_nextprev_entity
=include gen Examine_Status_L_Button
=include gen g_intro_to_addrexpr
 You can use the Current Entity arrow buttons in the
 main window to examine consecutive indexed components
 of an array variable.

 For example, assume that you have examined or deposited
 into the third element of array ARR.  That element,
 which is expressed as ARR[3] in some languages, is now
 the current entity and is displayed in the Current
 Entity field.

 To display the value of the next array element, ARR[4],
 click on the down-arrow button.  Or, to display the
 value of the previous array element, ARR[2], click on
 the up-arrow button.

 Each time you click on an arrow button, the current
 entity is reset to the array element that is being
 examined.  That element is then identified in the
 Current Entity field, and its value is displayed in the
 current output window (window OUT, by default).

 The topic Current, Next, and Previous Entity Built-In
 Symbols identifies built-in symbols that, when used
 with the Examine command (and related dialog boxes),
 achieve the same effect as the Current Entity arrow
 buttons.

=title Examining Consecutive VAX Instructions
=include gen 2Ex_Code_Dialog_Box3g_display_instructions
=include gen Examine_Status_L_Button
=include gen g_specifying_code
=include gen g_builtin_nextprev_entity
=include gen g_intro_to_addrexpr
=include gen g_display_predwnds
=include gen g_display_instructions
You can use the Current Entity arrow buttons in the main
 window to examine consecutive assembly-language
 instructions that are associated with a code address
 expression (for example, a routine name).

 When you specify a code address expression in the
 following contexts, the current entity is set to the
 first instruction at that code location:

  -  When you choose Examine Code...  or Deposit into
     Code from the Code submenu of the Data menu

  -  When you choose View Instructions...  from the
     Commands menu of an instruction window

  -  When you choose Examine from the pop-up menu, or
     click on the Examine button in the main window

 For example, suppose you have specified line 12 in the
 Examine Code dialog box:

   Examine %LINE 12
     MOD3\%LINE 12:   MOVL  (R11),B^16(R11)

 The instruction displayed is the first instruction
 associated with line 12, and it is now the current
 entity.

 To display the next instruction associated with line
 12, click on the down-arrow button.  To display the
 previous instruction, click on the up-arrow button.
 Each time you click on an arrow button, the current
 entity is reset to the instruction that is being
 examined.

 For example:

   Examine next instruction (click on down-arrow):
     MOD3\%LINE 12+4: MOVL  S^#1,B^4(R11)

   Examine next instruction (click on down-arrow):
     MOD3\%LINE 12+8: TSTL  B^16(R11)

   Examine previous instruction (click on up-arrow):
     MOD3\%LINE 12+4: MOVL  S^#1,B^4(R11)

 If an instruction window with the instruction attribute
 is displayed, the examined instruction is centered and
 boxed in the window.  If no instruction window has the
 instruction attribute, the instruction is displayed in
 the current output window (window OUT, by default).

 The topic Current, Next, and Previous Entity Built-In
 Symbols identifies built-in symbols that, when used
 with the Examine command (and related dialog boxes),
 achieve the same effect as the Current Entity arrow
 buttons.

 A useful technique when debugging at the instruction
 level is to execute the program one instruction at a
 time.  To do so, choose Step by Instruction from the
 pop-up menu.  You can also establish a default
 instruction-based step unit (step to next instruction,
 step to next CALL instruction, and so on).  To
 establish a default step unit, choose Step...  from the
 Control menu.

 Note that, when you examine consecutive instructions in
 a MACRO program, the debugger might misinterpret data
 as instructions if storage for the data is allocated in
 the middle of a stream of instructions.

 The following example shows some MACRO code with two
 longwords of data storage allocated directly after the
 BRB instruction at line 7 (line numbers have been added
 to the example for clarity):

   module TEST
        1:         .TITLE  TEST
        2:
        3: START::
        4:         .WORD   0
        5:
        6:         MOVL    #2,R2
        7:         BRB     LABEL_2
        8:
        9:         .LONG   ^X12345
       10:         .LONG   ^X14465
       11:
       12: LABEL_2:
       13:         MOVL    #5,R5
       14:
       15:         .END    TEST$START

 Examining the code address expression %LINE 6 displays
 the instruction at the start of line 6:

   Examine %LINE 6
     TEST\START\%LINE 6:  MOVL   S^#02,R2

 Clicking on the down-arrow button causes the debugger
 to correctly interpret and display the logical
 successor entity as an instruction, at line 7:

   Examine next instruction (click on down-arrow):
     TEST\START\%LINE 7: BRB TEST\TEST$START\LABEL_2

 However, the following three clicks on the down-arrow
 button cause the debugger to interpret the three
 logical successors incorrectly as instructions:

   Examine next instruction:
     TEST\START\%LINE 7+2: MULF3  S^#11.00000,S^#0.5625000,S^#0.5000000

   Examine next instruction:
     ADDRESSMODE, instruction uses illegal or undefined addressing modes
     TEST\START\%LINE 7+6: MULD3  S^#0.5625000[R4],S^#0.5000000,@W^5505(R0)

   Examine next instruction:
     START+12:   HALT

=title Examining Consecutive Memory Addresses
=include gen g_specifying_code
=include gen 2Ex_Code_Dialog_Box3g_display_instructions
=include gen g_specifying_variables
=include gen g_builtin_nextprev_entity
=include gen Examine_Status_L_Button
=include gen g_intro_to_addrexpr
 You can use the Current Entity arrow buttons in the
 main window to examine consecutive memory addresses.
 The behavior of the arrow buttons depends on the type
 that is associated with the current entity.

 If the current entity denotes a location that is
 associated with a compiler-generated type (and,
 therefore, a symbolic name), the debugger determines
 the next or previous logical entity according to that
 type.

 Thus, for an array variable, the down-arrow button sets
 the current entity to the next higher-numbered array
 element.  For a code location, the down-arrow button
 sets the current entity to the next instruction.

 By default, the debugger assigns the type longword
 integer to locations that are not associated with a
 symbolic name.  You can establish another default type
 by choosing Default Datatype...  from the Customize
 menu.  For such locations, the debugger determines the
 next or previous logical entity according to the
 default type.

 Thus, by default, for a location that does not have a
 compiler-generated type, the arrow buttons reset the
 start address of the current entity in increments of
 one longword (4 bytes).

 The topic Current, Next, and Previous Entity Built-In
 Symbols identifies built-in symbols that, when used
 with the Examine command (and related dialog boxes),
 achieve the same effect as the Current Entity arrow
 buttons.

=title Overview of Window Kinds, Attributes, and Actions
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_modify_wnd
=include gen 2Wind_Dialog_Box3g_create_wnd
=include gen g_cmd_mode
=include gen g_display_source
=include gen g_display_instructions
By choosing Windows...  from the Customize menu, you can
 create or modify debugger windows of the following
 kinds.

   Source windows, such as the predefined window SRC

   Output windows, such as the predefined window OUT

   Automatic windows, such as the predefined window AUTO

   Instruction windows, such as the predefined window INST

   Register windows, such as the predefined window REG

 The window kind determines what type of information the
 window can capture and display:

  -  A source window displays the source code of your
     program.

  -  An instruction window displays the decoded VAX
     assembly-language instructions for the code that is
     actually executing.  If your program has been
     optimized during compilation, the instruction
     stream might not correspond to the source code
     displayed in the source window.  Thus, one use for
     instruction windows is to verify the path of
     execution when debugging optimized code.

  -  An output window is a general-purpose window that
     can display any debugger output that is not already
     directed to another, special purpose, window (such
     as a source or instruction window).

  -  An automatic window is a window whose definition
     includes one or more commands, as specified in the
     Action field of the Windows dialog box.  Whenever
     the debugger suspends execution, the commands are
     executed automatically, and the window is updated
     with the output of the commands.  For example, you
     can use an automatic window to display the current
     values of some variables during the course of a
     debugging session.

  -  A register window displays the contents of the VAX
     registers and related information.

 The window kind can also determine how the contents of
 the window are generated.  There are two possibilities:

  -  Some windows are automatically updated.  Their
     definition includes one or more debugger commands
     that are executed whenever the debugger gains
     control from the program.  The output of the
     commands forms the contents of those windows.

     Window SRC belongs to this category:  it is
     automatically updated so that an arrow centered in
     the window shows the source line at which execution
     is currently suspended.

     When you create this kind of window, you specify
     the debugger commands in the Action field of the
     Windows dialog box.

     You can determine the built-in commands for an
     existing window (for example, SRC or INST) by
     selecting its name from the Windows dialog box list
     box and looking at the Action field.

  -  Other windows, for example, the predefined window
     OUT, derive their contents from commands you enter
     interactively.  If you create a window of this
     general category, you must first assign one or more
     attributes to that window before anything can be
     written to it.  The attribute defines the type of
     information that is written to the window (source,
     instruction, output, echo input, messages).  The
     attributes you can assign to a window depend on the
     window kind.

     You can determine the attributes that are currently
     assigned to a window (if any) by selecting its name
     from the Windows dialog box list box and looking at
     the state of the Window Attributes buttons.

     When a window has a particular attribute, XXX, it
     is referred to as the current XXX window.  For
     example, the window that has the instruction
     attribute is the current instruction window.

 By default, attributes are assigned as follows to the
 debugger predefined windows:

    Attribute:     Window:
     Source         SRC
     Output         OUT
     Instruction    none
     Echo input     none
     Messages       OUT

 Although SRC is automatically updated by its own
 built-in command, it can also receive the output of
 certain interactive commands because it has the source
 attribute by default.  For example, if you choose View
 Source from the Commands menu of window SRC and specify
 a line number in the View Source dialog box, that
 source line is then centered and boxed in window SRC.

=title Debugger Predefined Windows (SRC, OUT, AUTO, INST, REG)
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_display_source
=include gen g_display_instructions
=include gen 2Wind_Dialog_Box3g_modify_wnd
=include gen 2Wind_Dialog_Box3g_create_wnd
The debugger provides the following predefined windows
 that you can use to capture and display different kinds
 of data:

  -  SRC, the predefined source window

  -  OUT, the predefined output window

  -  AUTO, the predefined automatic window (a special
     output window)

  -  INST, the predefined instruction window

  -  REG, the predefined register window

 Of these windows, only SRC and OUT are displayed, by
 default, at debugger startup.  See Displaying the
 Predefined Windows INST, REG, and AUTO.

 The basic features of the predefined windows are
 described in the additional topics.  You can change
 certain characteristics of these windows, such as
 buffer size or window attributes, by choosing
 Windows...  from the Customize menu in the main window.
 You can also create additional windows similar to the
 predefined windows from the Windows...  dialog box.

 Choosing Window Setups from the Customize menu enables
 you to quickly establish any of three useful window
 configurations by clicking on a layout.  The first
 layout is the default window configuration at debugger
 startup.

Additional information available:

g srcg outg autog instg reg

=title Predefined Source Window (SRC)
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_display_source
=include gen g_source_notavailable
=include gen g_builtin_sourcinst
=include gen g_symb_opt
=include gen Wind_Dialog_Box
 Window SRC, which is displayed by default at debugger
 startup, is an automatically updated source window.

 You can use SRC to display source code in two basic
 ways:

  -  By default, SRC automatically displays the source
     code for the module that contains the routine in
     which execution is currently suspended.  This
     enables you to quickly determine your current
     debugging context.

  -  In addition, because SRC has the source attribute
     by default, you can use it to display the source
     code for any part of your program.

 The name of the module whose source code is displayed
 is shown at the right of the window name, SRC.  The
 numbers displayed at the left of the source code are
 the compiler-generated line numbers, as they might
 appear in a compiler-generated listing file.

 As you execute the program under debugger control, SRC
 is updated automatically whenever execution is
 suspended.  The boxed line is the line to be executed
 next.  Specifically, execution is suspended at the
 first instruction associated with the boxed line.
 Thus, the boxed line corresponds to the current PC
 value.  The PC (program counter) is a VAX register that
 contains the memory address of the next instruction to
 be executed.

 If the debugger cannot locate source code for the
 routine in which execution is suspended (because, for
 example, the routine is a run-time library routine), it
 tries to display source code in 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, it issues the following message:

  SOURCESCOPE, Source lines not available for .0\%PC.
    Displaying source in a caller of the current routine.

 In such cases, the boxed line in the source window
 identifies the line that contains code following the
 call statement in the calling routine.  See Making
 Source Code Available for Display for more information.

 The built-in command that automatically updates SRC is
 EXAMINE/SOURCE .%SOURCE_SCOPE\%PC.  This command causes
 SRC to display the source code for the routine that is
 identified in the Call Frame field in the main window,
 if source code is available for that routine.  By
 default, this is the routine in which execution is
 currently suspended (the routine at the top of the call
 stack).

 If your program was optimized during compilation, the
 source code displayed in SRC might not always represent
 the code that is actually executing.  See Debugging
 Optimized Code.

=title Predefined Output Window (OUT)
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_pathname
=include gen g_symb
=include gen Wind_Dialog_Box
 Window OUT is a general purpose output window.

 By default, OUT has the output and messages attributes.
 Therefore, it displays the following information:

  -  Any debugger output that is not directed to windows
     SRC, INST, or AUTO.  For example, if window INST is
     not displayed or does not have the instruction
     attribute, any output that would otherwise update
     window INST is displayed in window OUT.

  -  Debugger diagnostic messages.  Messages with a
     severity level greater than I (informational) are
     also displayed in a message box.

 Note that, when displaying variable names, routine
 names, and other symbolic address expressions, the
 debugger adds a path name prefix to the name.  The path
 name prefix identifies the nesting program elements in
 which the entity was declared in the program.  For
 example, if you examined a variable K, whose value was
 26, in routine SWAP of module SWAP_PACK, the debugger
 might display the following output:

      SWAP_PACK\SWAP\K: 26

 In this case, SWAP_PACK\SWAP\ is the path name prefix.

 In most cases, you do not need to include a path name
 prefix when specifying symbolic address expressions.
 See Understanding Symbol Path Names.

=title Predefined Automatic Window (AUTO)
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen Wind_Dialog_Box
 Note:  By default, the predefined automatic window AUTO
 is not displayed.  See Displaying the Predefined
 Windows INST, REG, and AUTO.

 Window AUTO is an automatic window.

 You can use AUTO instead of window OUT to display the
 output from the following dialog boxes (which are
 accessible from the Data menu):

    Examine Variable
    Examine Address or Register
    Language Expressions

 Window AUTO is created when you first click on the
 Display button in any one of these dialog boxes.
 Thereafter, AUTO remains open until you close it.

 AUTO includes a debugger command list in its
 definition.  Every time the debugger gains control,
 AUTO is updated with the output of that command list.

 When AUTO is created, its command list consists of the
 Examine or Evaluate command that was generated when you
 clicked on the Display button, and it displays the
 output of that command.

 Subsequently, every time you click on the Display
 button in any of the three dialog boxes listed, the
 debugger appends the new command generated to the
 current command list and updates AUTO to display the
 output from the entire command list.

 The usual way to add or delete a command from the
 definition of a window such as AUTO is to choose
 Windows...  from the Customize menu and then update the
 command list in the Action field for that window.  As
 an alternative, the Commands menu on window AUTO
 enables you to quickly add or delete an Examine command
 from the command list for that window by selecting
 text, without having to open the Windows dialog box.

=title Predefined Instruction Window (INST)
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_display_instructions
=include gen g_builtin_sourcinst
=include gen g_symb_opt
=include gen Wind_Dialog_Box
 Note:  By default, the predefined instruction window
 INST is not displayed and does not have the instruction
 attribute.  See Displaying the Predefined Windows INST,
 REG, and AUTO.

 Window INST is an automatically updated instruction
 window.

 INST displays the decoded VAX assembly-language
 instruction stream of your program.  This is the exact
 code that is executing, including the effects of any
 compiler optimization.  The topic Debugging Optimized
 Code explains how to use INST with the source window
 SRC when debugging optimized code.

 You can use INST in two basic ways:

  -  By default, INST automatically displays the decoded
     instructions for the routine in which execution is
     currently suspended.  This enables you to quickly
     determine your current debugging context.

  -  In addition, if INST has the instruction attribute,
     you can use it to display the decoded instructions
     for any part of your program.

 The name of the routine whose instructions are
 displayed is shown at the right of the window name,
 INST.  The numbers displayed at the left of the
 instructions are the compiler-generated source line
 numbers.

 As you execute the program under debugger control, INST
 is updated automatically whenever execution is
 suspended.  The instruction at which execution is
 suspended (the instruction at the current PC value) is
 boxed.

 The built-in command that automatically updates INST is
 EXAMINE/INSTRUCTION .%INSTRUCTION_SCOPE\%PC.  This
 command causes INST to display the instructions for the
 routine that is identified in the Call Frame field in
 the main window.  By default, this is the routine in
 which execution is currently suspended (the routine at
 the top of the call stack).

=title Predefined Register Window (REG)
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen g_specifying_registers
=include gen Wind_Dialog_Box
 Note:  By default, the predefined register window REG
 is not displayed.  See Displaying the Predefined
 Windows INST, REG, and AUTO.

 Window REG is an automatically updated window that
 displays the current values, in hexadecimal format, of
 the VAX general registers (R0 through R11, AP, FP, SP,
 and PC), the four condition code bits (C,V, Z, and N)
 of the processor status longword (PSL), and as many of
 the top stack values as can be displayed in the window.

 The register values displayed are for the routine in
 which execution is currently suspended.

 The register values are updated whenever the debugger
 takes control.

=title Modifying Debugger Windows
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_create_wnd
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_cmd_mode
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen g_display_source
=include gen g_display_instructions
To modify an existing window, proceed as follows:

 1.  Choose Windows...  from the Customize menu.

 2.  Click on the window name in the list box of the
     Windows dialog box.  This updates the dialog box
     with the selected window's name and its current
     parameters (window name, kind, attributes, action,
     position, dimension, and so on).

 3.  Modify the window parameters as desired.

 4.  Click on OK or Apply.

=title Creating Debugger Windows
=include gen 2Wind_Dialog_Box3g_wkinds g_srcwk src
=include gen 2Wind_Dialog_Box3g_wkinds g_outwk out
=include gen 2Wind_Dialog_Box3g_wkinds g_autowk auto
=include gen 2Wind_Dialog_Box3g_wkinds g_instwk inst
=include gen 2Wind_Dialog_Box3g_wkinds g_regwk reg
=include gen 2Wind_Dialog_Box3g_proc_windows create_wnd
=include gen 2Wind_Dialog_Box3g_modify_wnd
The additional topics explain how to create debugger
 windows to capture and display specific data.

=title Using Process-Specific Windows
=include gen g_debug_config
=include gen g_multiproc
=include gen Process_Status_L_Button
=include gen g_keypad
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
 Note:  Process-specific windows are used to debug
 multiprocess programs.

 In a multiprocess debugging configuration, the
 predefined windows SRC, INST, OUT, and REG are
 associated with the visible process.  For example,
 window SRC shows the source code where execution is
 suspended in the visible process, window OUT shows the
 output of commands executed in the context of the
 visible process, and so on.

 Similarly, any windows you create with the Windows
 dialog box are associated with the visible process,
 unless you specify a process in the Process field.

 In a multiprocess configuration, the predefined
 tracepoint on process activation automatically creates
 a new source window and a new instruction window for
 each new process that comes under debugger control.
 The windows have the names SRC_n and INST_n,
 respectively, where n is the process number.

 These predefined process-specific source and
 instruction windows are not displayed, by default.
 However you can open them by choosing Multiprocess
 Window Setups from the Customize menu.

 You can also use several predefined keypad-key
 sequences to manipulate these process-specific windows
 (see Entering Debugger Commands from the Keypad).

 The contents of a process-specific window are generated
 and modified in the context of that process.

 Any process-specific source and instruction windows
 that are created by the debugger on process activation
 are automatically canceled by the predefined tracepoint
 on process termination.

Additional information available:

create wnd

=title Creating Process-Specific Windows
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_create_wnd
=include gen g_multiproc
=include gen Wind_Dialog_Box
 In a multiprocess configuration, the predefined
 tracepoint on process activation automatically creates
 a new source window and a new instruction window for
 each new process that comes under debugger control.
 The windows have the names SRC_n and INST_n,
 respectively, where n is the process number.

 In addition to using these windows, you can create your
 own process-specific windows and make existing windows
 process specific.  You can make windows of any window
 kind process specific (source, instruction, output,
 automatic, or register).

 To create a process-specific window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.

 3.  Specify the window kind, attributes, and action, as
     applicable.  You assign attributes to
     process-specific windows in the same way that you
     assign them to windows that are not process
     specific.

 4.  Specify the process-specification to be associated
     with that window in the Process field.

 5.  Specify any other options.

 6.  Click on OK or Apply.

 The following example shows how to create an
 automatically updated source window named 3SOURCE that
 is specific to process 3.  The window thus created
 displays the source code where execution is suspended
 in process 3.

 1.  Specify 3SOURCE in the Window field.

 2.  Specify the Source Window Kind (and Window
     Attribute, if desired).

 3.  Specify the command EXAM/SOURCE .%SOURCE_SCOPE\%PC
     in the Action field.  This command shows the source
     code where execution is suspended (or the source
     code for the caller routine, if no source code is
     available for display).

 4.  Specify %PROC 3 in the Process field.

 5.  Specify None under the Window Name Suffix label.

 The Window Name Suffix label and buttons are another
 multiprocess-debugging feature of the Windows dialog
 box.  Use these buttons to automatically append a
 process-specific suffix to the window name specified in
 the Window field.

 The suffix denotes the visible process at the time that
 the window is created or modified.  The suffix can be
 either the debugger assigned process number, the VMS
 process name, or the VMS process identifier number
 (PID).  Note that the process number and name of the
 visible process are displayed in the Visible Process
 field of the main window.

=title Window Kinds (Source, Output, Automatic, Instr, Reg)
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
You can create and modify the following kinds of windows
 by choosing Windows...  from the Customize menu:

   Source windows, such as the predefined window SRC

   Output windows, such as the predefined window OUT

   Automatic windows, such as the predefined window AUTO

   Instruction windows, such as the predefined window INST

   Register windows, such as the predefined window REG

 The window kind determines what type of information a
 window can capture and display and how that information
 is generated.

 To specify the window kind, click on the appropriate
 button under the Window Kind label in the Windows
 dialog box.

 You can modify the window kind of an existing window.

Additional information available:

g srcwkg outwkg autowkg instwkg regwk

=title Source Windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_source
=include gen g_cmd_mode
=include gen g_symb_opt
=include gen Wind_Dialog_Box
 The source window kind specifies a window that displays
 source code as it might appear in a compiler-generated
 listing.

 The predefined window SRC is an example of a source
 window.

 If your program has been optimized during compilation,
 the source code displayed in a source window might not
 always reflect the code that is actually executing.
 See Debugging Optimized Code.

 In a source window, the numbers to the left of the
 source code are line numbers, as in a compiler listing.
 The box around a source line can indicate any of the
 following, depending on the command that last updated
 the displayed information:

  -  The source line at which execution is currently
     suspended (the line to be executed next)

  -  The source line that follows a routine call
     statement, if source code for a calling routine is
     being displayed

  -  The source line corresponding to an address
     expression that was specified through the Examine
     Code or View Instructions dialog box

Additional information available:

src

=title Creating a Source Window
=include gen Wind_Dialog_Box
=include gen 2Wind_Dialog_Box3g_wkinds g_srcwk
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_source
=include gen g_cmd_mode
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_create_wnd
 To create a source window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.

 3.  Choose the Source option under the Window Kind
     label.

 4.  If you want the source window to be updated
     whenever you enter commands to display source code,
     choose the Source attribute.  This makes the window
     the current source window.

 5.  If you want the source window to be updated
     automatically by a built-in TYPE or EXAMINE/SOURCE
     command whenever the debugger takes control,
     specify that command in the Action field.

     Window SRC is an automatically updated source
     window.  You can determine its built-in command by
     selecting the name SRC from the Windows dialog box
     list box and looking at the Action field.  See The
     Debugger's Command Interface for details on command
     syntax.

 6.  Specify any other options.

 7.  Click on OK or Apply.

=title Output Windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_cmd_mode
=include gen Wind_Dialog_Box
 The output window kind specifies a general purpose
 window that can capture and display any debugger output
 that is not directed to another window (according to
 the attributes assigned to various windows).

 The predefined window OUT is an example of an output
 window.  By default, OUT has the output and messages
 attributes.

 If no source window has the source attribute, the
 current output window displays source code that results
 from the following actions (and would otherwise update
 the current source window):

  -  Clicking on View Current Location from the pop-up
     menu.

  -  Using the View Source dialog box (from the Commands
     menu of a source window).

  -  Using the Examine Code dialog box with the Source
     Code option (from the Data menu).

  -  Entering a TYPE or EXAMINE/SOURCE command in the
     COMMAND box.

 If no instruction window has the instruction attribute,
 the current output window displays instructions that
 result from the following actions (and would otherwise
 update the current instruction window):

  -  Clicking on View Current Location from the pop-up
     menu.

  -  Using the View Instructions dialog box (from the
     Commands menu of an instruction window).

  -  Using the Examine Code dialog box with the
     Instructions option (from the Data menu).

  -  Entering an EXAMINE/INSTRUCTION command in the
     COMMAND box.

Additional information available:

out

=title Creating an Output Window
=include gen Wind_Dialog_Box
=include gen 2Wind_Dialog_Box3g_wkinds g_outwk
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_create_wnd
 To create an output window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.

 3.  Choose the Output option under the Window Kind
     label.

 4.  Assign any number of the following three attributes
     by choosing the appropriate option under the Window
     Attribute label:

       Output attribute
       Echo input attribute
       Messages attribute


 5.  Specify any other options.

 6.  Click on OK or Apply.

=title Automatic Windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen Wind_Dialog_Box g_action
=include gen g_cmd_mode
=include gen Wind_Dialog_Box
 The automatic window kind specifies an automatically
 updated window that displays the output from one or
 more debugger commands (specified in the Action field
 of the Windows dialog box).  The commands are executed
 in the order listed whenever the debugger takes
 control.

 The predefined window AUTO that is optionally invoked
 from the Examine Variable, Examine Address or Register,
 and Language Expressions dialog boxes is an example of
 an automatic window.

 The Commands menu on an automatic window enables you to
 quickly add or delete an Examine command from the
 command list for that window without having to open the
 Windows dialog box.

Additional information available:

auto

=title Creating an Automatic Window
=include gen Wind_Dialog_Box
=include gen 2Wind_Dialog_Box3g_wkinds g_autowk
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_cmd_mode
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_create_wnd
 To create an automatic window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.

 3.  Choose the Automatic option under the Window Kind
     label.

 4.  Specify one or more commands in the Action field.
     Separate multiple commands with semicolons (;).

 5.  Specify any other options.

 6.  Click on OK or Apply.

=title Instruction Windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen g_display_instructions
=include gen g_cmd_mode
=include gen g_symb_opt
=include gen Wind_Dialog_Box
 The instruction window kind specifies a window that
 displays the decoded VAX assembly-language instruction
 stream for the image that is being debugged.

 Because an instruction window shows the exact code that
 is executing, it is particularly useful in helping you
 debug optimized code.  See Debugging Optimized Code.

 The predefined window INST is an example of an
 instruction window.  By default, INST is not displayed
 and does not have the instruction attribute.  See
 Displaying the Predefined Windows INST, REG, and AUTO.

 In an instruction window, the numbers to the left of
 the instructions are compiler-generated line numbers.
 The box around an instruction can indicate any of the
 following, depending on the command that last updated
 the displayed information:

  -  The instruction at which execution is currently
     suspended (the next instruction to be executed)

  -  The instruction that called a routine, if
     instructions for a calling routine are being
     displayed

  -  The instruction corresponding to an address
     expression that was specified through the Examine
     Code or View Instructions dialog boxes

Additional information available:

inst

=title Creating an Instruction Window
=include gen Wind_Dialog_Box
=include gen 2Wind_Dialog_Box3g_wkinds g_instwk
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_instructions
=include gen g_cmd_mode
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_create_wnd
 To create an instruction window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.

 3.  Choose the Instruction option under the Window Kind
     label.

 4.  If you want the instruction window to be updated
     whenever you enter commands to display
     instructions, choose the Instruction attribute.
     This makes the window the current instruction
     window.

 5.  If you want the instruction window to be updated
     automatically by a built-in EXAMINE/INSTRUCTION
     command whenever the debugger takes control,
     specify that command in the Action field.

     Window INST is an automatically updated instruction
     window.  You can determine its built-in command by
     selecting the name INST from the Windows dialog box
     list box and looking at the Action field.  See The
     Debugger's Command Interface for details on command
     syntax.

 6.  Specify any other options.

 7.  Click on OK or Apply.

=title Register Windows
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen g_display_predwnds
=include gen g_specifying_registers
=include gen Wind_Dialog_Box
 The register window kind specifies an automatically
 updated window that shows the contents of the VAX
 registers and related information.

 A register window displays the current values (in
 hexadecimal format) of the VAX general registers (R0
 through R11, AP, FP, SP, PC), the four condition code
 bits (C,V, Z, and N) of the processor status longword
 (PSL), and as many of the top stack values as can be
 displayed through the window.

 The register values displayed are for the routine in
 which execution is currently suspended.

 The predefined window REG is an example of a register
 window.  By default, window REG is not displayed.  See
 Displaying the Predefined Windows INST, REG, and AUTO.

 The values contained in the registers are updated
 whenever the debugger takes control.

Additional information available:

reg

=title Creating a Register Window
=include gen Wind_Dialog_Box
=include gen 2Wind_Dialog_Box3g_wkinds g_regwk
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
=include gen 2Wind_Dialog_Box3g_proc_windows
=include gen 2Wind_Dialog_Box3g_create_wnd
 To create a register window:

 1.  Choose Windows...  from the Customize menu.

 2.  Specify the window name in the Window field of the
     Windows dialog box.  To create a register window:

 3.  Choose the Register option under the Window Kind
     label.

 4.  Specify any other options.

 5.  Click on OK or Apply.

=title Window Attributes
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wkinds_attribs_acts
=include gen 2Wind_Dialog_Box3g_predwnds
To assign one or more attributes to a debugger window,
 choose Windows...  from the Customize menu.

 The attributes that can be assigned to windows are as
 follows:

   Source
   Output
   Instruction
   Echo input
   Messages

 Each attribute represents some type of data (source
 code, input commands, diagnostic messages, and so on).
 Assigning an attribute to a window causes that window
 to receive and display that type of data.

 The attributes you can assign to a window depend on the
 window kind.

 To assign attributes to a window, proceed as follows:

 1.  Choose Windows...  from the Customize menu.

 2.  Enter the window name in the Window field of the
     Windows dialog box.

 3.  Click on the appropriate window kind button
     (source, instruction, output, automatic, or
     register).

 4.  Choose one or more window attributes, if applicable
     to that window kind.

 5.  Click on OK or Apply.

 By default, attributes are assigned as follows to the
 debugger predefined windows:

    Attribute:     Window:
     Source         SRC
     Output         OUT
     Instruction    none
     Echo input     none
     Messages       OUT

Additional information available:

g srcwag outwag instwag inpwag msgwa

=title Source Attribute
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_callframe_buttons_display_src
=include gen g_display_source
=include gen g_cmd_mode
=include gen Wind_Dialog_Box
 Assigning the source attribute establishes the
 specified window as the current source window.  The
 current source window is updated whenever you display
 source code through the following means:

  -  Click on View Current Location from the pop-up
     menu.

  -  Click on the Call Frame arrow buttons in the main
     window.

  -  Use the View Source dialog box (from the Commands
     menu of a source window).

  -  Use the Examine Code dialog box with the Source
     Code option (from the Data menu).

  -  Enter a TYPE or EXAMINE/SOURCE command in the
     COMMAND box or in an Action field of a dialog box.

 The source attribute can be assigned only to a source
 window.

 The predefined source window SRC has the source
 attribute by default.

 If no window has the source attribute, the output of
 these commands is directed at the current output
 window.

=title Output Attribute
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen Wind_Dialog_Box
 Assigning the output attribute establishes the
 specified window as the current output window.  The
 current output window displays any debugger output that
 is not otherwise directed to another window.

 The output attribute can be assigned only to an output
 window.

 The predefined output window OUT has the output
 attribute, by default.

 If no window has the output attribute, debugger output
 that would otherwise be directed at the current output
 window is suppressed.

=title Instruction Attribute
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_callframe_buttons_display_inst
=include gen g_display_instructions
=include gen g_cmd_mode
=include gen Wind_Dialog_Box
 Assigning the instruction attribute establishes the
 specified window as the current instruction window.
 The current instruction window is updated whenever you
 display instructions through the following means:

  -  Click on View Current Location from the pop-up
     menu.

  -  Click on the Call Frame arrow buttons in the main
     window.

  -  Use the View Instructions dialog box (from the
     Commands menu of an instruction window).

  -  Use the Examine Code dialog box with the
     Instructions option (from the Data menu).

  -  Enter an EXAMINE/INSTRUCTION command in the COMMAND
     box or in an Action field of a dialog box.

 The instruction attribute can be assigned only to an
 instruction window.

 No window has the instruction attribute by default.

 If no window has the instruction attribute, the output
 of these commands is directed at the current output
 window.

 You can assign the instruction attribute to the
 predefined instruction window INST in any of the
 following ways:

  -  Use the Windows dialog box.

  -  Choose Window Setups from the Customize menu, then
     click on one of the two setups that include INST.
     This action automatically assigns the instruction
     attribute to INST.

=title Echo Input Attribute
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_cmd_mode
=include gen g_log_file
=include gen Wind_Dialog_Box
 An action that you direct at the debugger through the
 DECwindows interface (for example, by clicking on OK in
 a dialog box) is translated into a debugger command
 before it is processed by the debugger.

 You can determine the command that is issued in the
 following ways:

  -  Assign the echo input attribute to an output
     window.  This establishes the specified window as
     the current echo input window.  The current echo
     input window echoes the commands that are issued to
     the debugger.

     The current echo input window also echoes any
     commands that you enter directly in the COMMAND
     box.

  -  Open the COMMAND box by choosing Show Command...
     from the Customize menu.  Commands are echoed at
     the debugger prompt, DBG>.

 The echo input attribute can be assigned only to an
 output window.

 No window has the echo input attribute by default.

 If no window has the echo input attribute, commands are
 echoed only in the COMMAND box.

 You can assign the echo input attribute to the
 predefined output window OUT by using the Windows
 dialog box.

 Note that a debugger log file contains a record of the
 commands issued during a debugging session and the
 corresponding debugger output.

=title Messages Attribute
=include gen 2Wind_Dialog_Box3g_wkinds
=include gen 2Wind_Dialog_Box3g_wind_attrib
=include gen g_messages_help
=include gen Wind_Dialog_Box
 Assigning the messages attribute establishes the
 specified window as the current message window.  Under
 those conditions, debugger diagnostic messages (of all
 severity levels) are displayed in both a normal message
 window and the current message window.

 The messages attribute can be assigned only to an
 output window.

 The predefined output window OUT has the messages
 attribute, by default.

 If no window has the messages attribute, debugger
 diagnostic messages are displayed in both a normal
 message window and the COMMAND box, if the latter is
 displayed.  To open the COMMAND box, choose Show
 Command...  from the Customize menu.

 Messages displayed in a message box show only the
 message text.  Also, only those messages whose severity
 level is greater than I (informational) are displayed
 in a message box.

 Messages displayed in the COMMAND box or in the current
 message window show the message text, ident, severity,
 and facility (DEBUG).

 You can assign the messages attribute to the predefined
 output window OUT by using the Windows dialog box.

=title Examining (Displaying the Values of) Variables
=include gen g_specifying_variables
=include gen g_radix
=include gen Examine_Status_L_Button
=include gen g_exdep
To examine (display the value of) a variable, choose
 Variables from the Data menu, then choose Examine
 Variable...  from the Variables submenu.  A dialog box
 is displayed.

 Note:  You can also examine a variable that is selected
 in a window by clicking on the Examine button in the
 main window or by choosing Examine from the pop-up
 menu.  Many of the concepts discussed in the next
 paragraphs also apply to these uses of the Examine
 command.

 When you examine a variable, the debugger associates
 the name specified with a memory address or register
 and with the compiler-generated type for that variable
 (integer, real, string, array, record, and so on).  By
 default, it then interprets and displays the value at
 that location according to the variable's type.

 If you specify the name of an aggregate variable (a
 composite data structure such as an array or a record
 structure), the debugger displays the values of all
 elements.  For an array, the display shows the
 subscript (index) and value of each array element.  For
 a record, the display shows the name and value of each
 record component.

 To specify an individual array element, array slice, or
 record component, use the syntax of the source
 language.  For example, ARR[4] could denote element 4
 of array ARR in some languages.

 You can interpret and display the value at the location
 denoted by a variable name in another type.  To do so,
 choose that type on the Target Datatype option menu of
 the Examine Variable dialog box.

 Use the Radix option menu to display data in a radix
 other than the default radix.

 The Current Entity field in the main window is updated
 whenever you examine a variable or any other address
 expression.

=title Depositing (Assigning Values) Into Variables
=include gen g_langexpr
=include gen g_specifying_variables
=include gen g_radix
=include gen Examine_Status_L_Button
=include gen g_exdep
To deposit (assign) a value into a variable, choose
 Variables from the Data menu, then choose Deposit into
 Variable...  from the Variables submenu.  A dialog box
 is displayed.

 When you deposit a value into a variable, the debugger
 takes the following action:

 1.  Associates the name specified in the Variable field
     of the dialog box with a memory address or register
     and with the compiler-generated type for that
     variable (integer, real, string, array, record, and
     so on).

 2.  Evaluates the language expression specified in the
     Language Expression field in the syntax of the
     current language and in the current radix to yield
     a value.

 3.  Checks that the value and type of the language
     expression is consistent with the type of the
     variable.  If you try to deposit a value that is
     incompatible with the type of the variable, the
     debugger issues a diagnostic message.  If the value
     is compatible, the debugger deposits the value into
     the location denoted by the variable name.  This
     updates the Current Entity field in the main
     window.

 The debugger might do type conversion during a deposit
 operation if the language rules allow it.  For example,
 a real value that is specified in the Language
 Expression field might be converted to an integer value
 if it is being assigned to a variable with an integer
 type.  In general, the debugger tries to follow the
 assignment rules for the current language.

 You cannot deposit a value into an entire aggregate
 variable (a composite data structure such as an array
 or record).  To specify an individual array element or
 a record component, use the syntax of the source
 language.  For example, ARR[4] could denote element 4
 of array ARR in some languages.

 You can override the compiler-generated type of a
 variable and deposit a value of another type at the
 location denoted by a variable name.  To do so, choose
 the type on the Target Datatype option menu.

=title Obtaining Information about Variables and Other Symbols
=include gen g_symb_mod_set
=include gen g_DST_GST_RST
=include gen g_pathname
=include gen g_resolve_symb
=include gen g_symb
=include gen g_symb_share
To display information that the debugger has about a
 given variable or other symbol in the current image,
 choose Variables from the Data menu, then choose Show
 Variable...  from the Variables submenu.  A dialog box
 is displayed.

 Note:  The current image is either the main image, by
 default, or the image established as the current image
 through the Images dialog box (Data menu).

 The information that the debugger displays about a
 symbol might not be the same as what the compiler had
 or even what you see in your source code.  Nonetheless,
 it is useful for understanding why the debugger might
 act as it does when handling symbols.

 Symbols are displayed with their path names.  The Show
 Variable dialog box enables you to list all possible
 declarations or definitions of a specified symbol that
 exist in the RST for the current image---that is, in
 all set modules and in the GST for that image.

 Use the Scope field to indicate that the debugger
 should identify only the specified symbols that are
 declared in a particular scope rather than the entire
 run-time symbol table (RST).

=title Displaying Source Code for a Code Location
=include gen g_source_notavailable
=include gen Examine_Status_L_Button
=include gen g_display_source
=include gen g_exdep
 To display the line of source code for a code location
 (an address expression associated with VAX
 instructions), proceed as follows:

 1.  Choose Code from the Data menu in the main window,
     then choose Examine Code...  from the Code submenu.
     A dialog box is displayed.

 2.  Enter a code address expression in the Address
     Expression field of the dialog box.  Routine names,
     program labels, and line numbers are symbolic
     address expressions that are associated with code.

 3.  Click on the Source Code button

 4.  Click on OK or Apply.

 The output is displayed as follows:

  -  The source line for the specified address
     expression is displayed in the current source
     window (the source window with the source
     attribute).  This is the predefined window SRC, by
     default.  The source line is centered and boxed in
     the window.

     For example, if the address expression is a routine
     name, the source line that contains the routine
     declaration is displayed and boxed.

  -  If no source window has the source attribute, the
     source line is displayed in the output window.

 The Current Entity field in the main window is updated
 whenever you examine a code location or any other
 address expression.

=title Displaying VAX Instructions at a Code Location
=include gen g_display_predwnds
=include gen Examine_Status_L_Button g_examine_inst_buttons
=include gen g_display_operands
=include gen g_display_pc_contents
=include gen Examine_Status_L_Button
=include gen g_display_instructions
=include gen g_exdep
To display the VAX assembly-language instructions at a
 code location (an address expression associated with
 instructions), proceed as follows:

 1.  Choose Code from the Data menu in the main window,
     then choose Examine Code...  from the Code submenu.
     A dialog box is displayed.

 2.  Enter a code address expression in the Address
     Expression field of the dialog box.  Routine names,
     program labels, and line numbers are symbolic
     address expressions that are associated with code.

     Or, to determine the instructions associated with a
     source line, you can first select that line from a
     source window and then open the dialog box.  The
     module name and line number are automatically
     inserted in the Address Expression field.

 3.  Click on the Instructions button.

 4.  To also display information about the instruction
     operands, choose the With Operand Values option
     (and the Full option for even more detailed
     information).

 5.  Click on OK or Apply.

 The output is displayed as follows:

  -  If an instruction window with the instruction
     attribute is displayed, the first instruction for
     the specified address expression is centered and
     boxed in the window.

  -  If no instruction window has the instruction
     attribute, the first instruction for the specified
     address expression is displayed in the current
     output window (window OUT, by default).

  -  If the With Operand Values button is on, operand
     information is displayed in the current output
     window.

 Note:  By default, the predefined instruction window
 INST is not displayed and does not have the instruction
 attribute.  See Displaying the Predefined Windows INST,
 REG, and AUTO.

 The Current Entity field in the main window is updated
 whenever you examine a code location or any other
 address expression.

=title Depositing VAX Assembly-Language Instructions
=include gen Examine_Status_L_Button
=include gen g_selecting_code
=include gen g_specifying_code
=include gen g_exdep
To deposit an instruction at a memory address or into a
 register, choose Code from the data menu, then choose
 Deposit Code...  from the Code submenu.  A dialog box
 is displayed.

 When you deposit an instruction, the debugger takes the
 following action:

 1.  Checks that the entity specified in the Instruction
     field of the dialog box is a valid VAX
     assembly-language instruction.

 2.  If you try to deposit an invalid instruction, the
     debugger issues a diagnostic message.  If the
     entity specified is a valid instruction, the
     debugger deposits the instruction starting at the
     address or register denoted by the specified
     address expression.  This updates the Current
     Entity field in the main window.

 VAX instructions occupy different numbers of bytes,
 depending on their operands.  When depositing
 instructions of arbitrary lengths into successive
 memory locations, use the Current Entity arrow keys to
 establish the next unoccupied location where an
 instruction can be deposited.

 When you replace an instruction, be sure that the new
 instruction, including operands, is the same length in
 bytes as the old instruction.  If the new instruction
 is longer, you cannot deposit it without overwriting,
 and thereby destroying, the next instruction.  If the
 new instruction occupies fewer bytes of memory than the
 old one, you must deposit NOP instructions
 (instructions that cause "no operation") in bytes of
 memory left unoccupied after the replacement.

 The debugger does not warn you if an instruction you
 are depositing overwrites a subsequent instruction, nor
 does it remind you to fill in vacant bytes of memory
 with NOPs.

=title Examining the Contents of Addresses or Registers
=include gen g_radix
=include gen Examine_Status_L_Button
=include gen g_exdep
To examine the contents of a memory address or register,
 choose Addresses or Registers from the Data menu, then
 choose Examine Address or Register...  from the
 submenu.  A dialog box is displayed.

 When you examine an arbitrary address or register and
 the Target Datatype option menu is set to the Compiler
 Generated option, the debugger formats and displays the
 value at the specified location as follows:

  -  If the location has a symbolic name, the debugger
     formats and displays the value according to the
     compiler-generated type associated with that
     symbol---that is, as a variable of a particular
     type (if the symbol defines a data location) or as
     a VAX assembly-language instruction (if the symbol
     defines a code location).

  -  If the location does not have a symbolic name (and,
     therefore, no associated compiler-generated type),
     the debugger formats and displays the value in the
     type longword (4-byte) integer.  See Target
     Datatype Option Menu for details.

 You can interpret and display the value at the
 specified location in another type.  To do so, choose
 that type on the Target Datatype option menu.

 Use the Radix option menu to display data in a radix
 other than the default radix.

 The Current Entity field in the main window is updated
 whenever you examine an address, register, or symbolic
 address expression.

=title Depositing Values into Addresses and Registers
=include gen g_langexpr
=include gen g_radix
=include gen Examine_Status_L_Button
=include gen g_exdep
To deposit a value at a memory address or into a
 register, choose Addresses or Registers from the Data
 menu, then choose Deposit into Address or Register...
 from the submenu.  A dialog box is displayed.

 When you deposit a value at an address or register, the
 debugger takes the following action:

 1.  Evaluates the language expression specified in the
     Language Expression field of the dialog box in the
     syntax of the current language and in the current
     radix to yield a value.

 2.  Checks that the value and type of the language
     expression is consistent with the type specified on
     the Target Datatype menu.  If you try to deposit a
     value that is incompatible, the debugger issues a
     diagnostic message.  If the value is compatible,
     the debugger deposits the value at the location
     specified in the Address or Register field.  This
     updates the Current Entity field in the main
     window.

 The debugger might do type conversion during a deposit
 operation if the language rules allow it.  For example
 a real value that is specified in the Language
 Expression field might be converted to an integer value
 if an integer type was chosen on the Target Datatype
 option menu.  In general, the debugger tries to follow
 the assignment rules for the current language.

=title Starting and Resuming Execution (Go Command)
=include gen g_excep excep_resume_exec
=include gen g_multiproc_program_execution
=include gen g_exec
To start or resume program execution from the current
 location, click on the Go button in the main window.

 To start execution from another location, choose Go...
 from the Control menu and specify the location in the
 Go dialog box.

 After it is started with the Go command, program
 execution continues until one of the following events
 occurs:

  -  The program completes execution

  -  A breakpoint is reached

  -  A watchpoint is activated

  -  An exception is signaled

  -  You click on the Stop button in the main window

 Note that starting execution from a location other than
 the current location can produce unexpected results,
 because it alters the normal control flow of your
 program.  For example, during a debugging session you
 can restart execution from the beginning of the
 program.  However, because the program has executed,
 the values of some variables might now be different
 from when you first ran the program.

 Go is one of the four debugger commands that you can
 use to execute your program.  The others are:

  -  Step (on the Control or pop-up menu, or the Step
     button in the main window)

  -  Call (on the Control menu)

  -  Exit (on the File menu of the debugger windows)

=title Executing the Program by Step Unit (Step Command)
=include gen g_excep excep_resume_exec
=include gen g_multiproc_program_execution
=include gen g_exec
To execute one step unit of your program, click on the
 Step button in the main window.

 By default, a step unit is one line of source code;
 and, by default, the debugger notifies you of the
 completion of a Step command by displaying a "stepped
 to..." message and the source line where execution is
 suspended.

 To specify other options for the Step command, choose
 Step...  from the Control menu.  For example, you can
 make the default step unit signify "execute one
 instruction".

 Note the following additional points about the Step
 command:

  -  When used to execute the program in units of one or
     more source lines, the Step command executes one or
     more executable lines at a time, skipping over any
     other lines.

     Executable lines are those for which instructions
     were generated by the compiler (for example, lines
     with routine calls or assignment statements).
     Examples of nonexecutable lines are comment lines
     or lines with variable declarations without value
     assignments.

  -  When execution is suspended at a routine call,
     clicking on the Step button executes the call in
     one step, by default, suspending execution at the
     next source line in the calling routine.

     You can override this behavior to execute the
     routine in steps by choosing Step Into Routine from
     the pop-up menu, and then clicking on the Step
     button after execution is within the routine.

 Step is one of the four debugger commands that you can
 use to execute your program.  The others are:

  -  Go (on the Control or pop-up menu, or the Go button
     in the main window)

  -  Call (on the Control menu)

  -  Exit (on the File menu of the debugger windows)

=title Using Breakpoints and Tracepoints
=include gen g_excep excep_resume_exec
=include gen g_exec
To set a breakpoint or tracepoint in your program,
 choose Break...  from the Control menu.

 A breakpoint is a location in your program at which
 execution is to be suspended.  Typical locations are
 routine declarations, program labels, and specific
 lines of source code.  At a breakpoint, you can step
 into a routine, check the current value of a variable,
 and so on.

 In addition to specifying unique locations, you can set
 breakpoints on every source line or on certain classes
 of VAX assembly-language instructions.  You can also
 set breakpoints on certain kinds of events, such as
 exceptions and Ada tasking events.  And you can set
 conditional breakpoints that trigger only when a
 specified expression is evaluated to be true.

 A tracepoint is like a breakpoint, except that
 execution continues after the debugger reports that the
 tracepoint has been reached.  Tracepoints enable you to
 monitor the path of execution of your program through
 specified locations (for example, through routine
 calls).  As with breakpoints, you can trace through
 classes of instructions, monitor events, and set
 conditional tracepoints.

=title Displaying Process Information
=include gen g_multiproc_states
=include gen g_multiproc
 To display information about one or more processes and
 any images running in those processes, choose
 Processes...  from the Data menu, then use the Show
 brief or Show detailed options from the Processes
 dialog box.

 You must specify a process that is currently under
 debugger control (a process that is identified in the
 list box of the Processes dialog box).

 The brief display provides one line of information for
 each specified process.  For example:

   Number  Name      Hold  State    Current PC
  *    2 JONES_TWA3  HOLD  break    SCREEN\%LINE 47

 The detailed display provides several lines of
 information.

 The following information is provided in a brief
 display, starting from the left:

  -  The asterisk character (*), if displayed as in the
     previous example, marks the visible process.

  -  The Number field shows the process number assigned
     by the debugger (process 2, in the example).  A
     process number is assigned sequentially, starting
     with process 1, to each process that comes under
     debugger control.  If a process is terminated by
     choosing Exit from the Processes option menu, its
     process number is not reused during that debugging
     session.

  -  The Name field shows the VMS process name
     (JONES_TWA3, in the example).

  -  The Hold field shows the word "HOLD" if the process
     is on hold, as in the example.

  -  The State field shows the current debugging state
     for that process.  In the example, the image's
     execution is suspended at a breakpoint (break
     state).  See Debugging States for Multiprocess
     Programs.

  -  The Current PC field shows the location, symbolized
     if possible, at which execution is suspended.  It
     is suspended at line 47 of module SCREEN in the
     example.