OpenVMS Debugger Manual
Previous Contents Index 


 
DBG> ex %fpsr 
LOOPER\main\%FPSR: 
        I U O Z D V TD RC PC WRE FTZ 
    SF3 0 0 0 0 0 0  1  0  3   0   0 
    SF2 0 0 0 0 0 0  1  0  3   0   0 
    SF1 0 0 0 0 0 0  1  0  3   1   0 
    SF0 0 0 0 0 0 0  0  0  3   0   0 
    TRAPS ID UD OD ZD DD VD 
           1  1  1  1  1  1 
DBG>

You can also force this formatting on any location (see EXAMINE/FPSR).

  • For information about Previous Function State (%PFS), Current Frame Maker (%CFM), Interrupt Function State (%IFS), and Next Previous Function State (%NEXT_PFS) registers, see Intel IA-64 Architecture Software Developer's Manual, Volume 1. Example: 


     
DBG> ex %pfs 
LOOPER\main\%PFS: 
    PPL PEC SOF SOL SOR RRB_GR RRB_FR RRB_PR 
      3   0  29  21   0      0      0      0 
DBG> ex %cfm 
LOOPER\main\%CFM: 
    SOF SOL SOR RRB_GR RRB_FR RRB_PR 
      6   5   0      0      0      0 
DBG> ex %ifs 
LOOPER\main\%IFS: 
    SOF SOL SOR RRB_GR RRB_FR RRB_PR 
      6   5   0      0      0      0 
DBG> ex %next_pfs 
LOOPER\main\%NEXT_PFS: 
    PPL PEC SOF SOL SOR RRB_GR RRB_FR RRB_PR 
      3   0   6   5   0      0      0      0 
DBG>

    Also see EXAMINE/PFS and EXAMINE/CFM.

  • For information about the Process Status Register (%PSR), see the Intel IA-64 Architecture Software Developer's Manual, Volume 2. Example: 


     
DBG> ex %psr 
LOOPER\main\%PSR: 
    IA BN ED RI SS DD DA ID IT MC IS CPL RT TB LP DB SI DI PP SP DFH DFL 
     0  1  0  0  0  0  0  0  1  0  0   3  1  0  0  0  0  1  0  0   0   0 
    DT PK  I IC MFH MFL AC UP BE 
     1  0  1  1   1   1  0  0  0 
DBG>

    Also see EXAMINE/PSR.

  • The debugger defaults to a bit vector format for the %GRNAT0, %GRANT1, and %PR registers. For example: 


     
DBG> ex %grnat0,%pr 
LOOPER\main\%GRNAT0: 
11111111 11111111 11111111 11000000 00000000 00000000 00000000 00000000 
LOOPER\main\%PR:     
00000000 00000000 00000000 00000000 11111111 01010110 10010110 10100011 
DBG>

  • The debugger defaults to single bits for registers %p0...%p63. For example: 


     
DBG> ex %p6,%p7 
LOOPER\main\%P6:        0 
LOOPER\main\%P7:        1 
DBG>

    4.5 Specifying a Type When Examining and Depositing

    The preceding sections explain how to use the EXAMINE and DEPOSIT commands with program locations that have a symbolic name and, therefore, are associated with a compiler-generated type.

    Section 4.5.1 describes how the debugger formats (types) data for program locations that do not have a symbolic name and explains how you can control the type for those locations.

    Section 4.5.2 explains how to override the type associated with any program location, including a location that has a symbolic name.

    4.5.1 Defining a Type for Locations Without a Symbolic Name

    Program locations that do not have a symbolic name and, therefore, are not associated with a compiler-generated type have the type longword integer by default. Section 4.1.5 explains how to examine and deposit into such locations using the default type.

    The SET TYPE command enables you to change the default type in order to examine and display the contents of a location in another type, or to deposit a value of one type into a location associated with another type. Table 4-3 lists the type keywords for the SET TYPE command.

    Table 4-3 SET TYPE Keywords
    ASCIC D_FLOAT   PACKED
    ASCID DATE_TIME INSTRUCTION QUADWORD
    ASCII: n EXTENDED_FLOAT 1 LONG_FLOAT 1 S_FLOAT 1
    ASCIW F_LOAT LONG_LONG_FLOAT 1 T_FLOAT 1
    ASCIZ FLOAT LONGWORD TYPE=( type-expression)
    BYTE G_FLOAT OCTAWORD WORD
          X_FLOAT 1

    1Integrity server and Alpha specific

    For example, the following commands set the type for locations without a symbolic name to, respectively, byte integer, G_floating, and ASCII with 6 bytes of ASCII data. Each successive SET TYPE command resets the type. 


     
DBG> SET TYPE BYTE
DBG> SET TYPE G_FLOAT
DBG> SET TYPE ASCII:6

    Note that the SET TYPE command, when used without the /OVERRIDE qualifier, does not affect the type for program locations that have a symbolic name (locations associated with a compiler-generated type).

    The SHOW TYPE command identifies the current type for locations without a symbolic name. To restore the default type for such locations, enter the SET TYPE LONGWORD command.

    4.5.2 Overriding the Current Type

    The SET TYPE/OVERRIDE command enables you to change the type associated with any program location, including locations with compiler-generated types. For example, after the following command is executed, an unqualified EXAMINE command displays the contents of only the first byte of the location specified and interprets the contents as byte integer data. An unqualified DEPOSIT command modifies only the first byte of the location specified and formats the data deposited as byte integer data. 


     
DBG> SET TYPE/OVERRIDE BYTE

    See Table 4-3 for the valid type keywords for the SET TYPE/OVERRIDE command.

    To identify the current override type, enter the SHOW TYPE/OVERRIDE command. To cancel the current override type and restore the normal interpretation of locations that have a symbolic name, enter the CANCEL TYPE/OVERRIDE command.

    The EXAMINE and DEPOSIT commands have qualifiers that enable you to override the type currently associated with a program location for the duration of the EXAMINE or DEPOSIT command. These qualifiers override any previous SET TYPE or SET TYPE/OVERRIDE command as well as any compiler-generated type. See the DEPOSIT and EXAMINE commands for the type qualifiers available to each command.

    When used with a type qualifier, the EXAMINE command displays the entity specified by the address expression in that type. For example: 


     
DBG> EXAMINE/BYTE .           ! Type is byte integer.
MOD3\%LINE 15 :  -48
DBG> EXAMINE/WORD .           ! Type is word integer.
MOD3\%LINE 15 :  464
DBG> EXAMINE/LONG .           ! Type is longword integer.
MOD3\%LINE 15 :  749404624
DBG> EXAMINE/QUAD .           ! Type is quadword integer.
MOD3%LINE 15 :  +0130653502894178768
DBG> EXAMINE/FLOAT .          ! Type is F_floating.
MOD3%LINE 15 :   1.9117807E-38
DBG> EXAMINE/G_FLOAT .        ! Type is G_floating.
MOD3%LINE 15 :   1.509506018605227E-300
DBG> EXAMINE/ASCII .          ! Type is ASCII string.
MOD3\%LINE 15 :  ".."
DBG>

    When used with a type qualifier, the DEPOSIT command deposits a value of that type into the location specified by the address expression, which overrides the type associated with the address expression.

    The remaining sections provide examples of specifying integer, string, and user-declared types with type qualifiers and the SET TYPE command.

    4.5.2.1 Integer Types

    The following examples show the use of the EXAMINE and DEPOSIT commands with integer-type qualifiers (/BYTE, /WORD, /LONGWORD). These qualifiers enable you to deposit a value of a particular integer type into an arbitrary program location. 


     
DBG> SHOW TYPE           ! Show type for locations without
type:  long integer      ! a compiler-generated type.
DBG> EVALU/ADDR .        ! Current location is 724.
724
DBG> DEPO/BYTE . = 1     ! Deposit the value 1 into one byte 
                         ! of memory at address 724.
DBG> EXAM .              ! By default, 4 bytes are examined.
724:  1280461057
DBG> EXAM/BYTE .         ! Examine one byte only.
724:  1
DBG> DEPO/WORD . = 2     ! Deposit the value 2 into first two 
                         ! bytes (word) of current entity.
DBG> EXAM/WORD .         ! Examine a word of the current entity.
724:  2
DBG> DEPO/LONG 724 = 999 ! Deposit the value 999 into 4 bytes
                         !(a longword) beginning at address 724.
DBG> EXAM/LONG 724       ! Examine 4 bytes (longword)
724:  999                ! beginning at address 724.
DBG>

    4.5.2.2 ASCII String Type

    The following examples show the use of the EXAMINE and DEPOSIT commands with the /ASCII:n type qualifier.

    When used with the DEPOSIT command, this qualifier enables you to deposit an ASCII string of length n into an arbitrary program location. In the example, the location has a symbolic name (I) and, therefore, is associated with a compiler-generated integer type. The command syntax is as follows: 


     
DEPOSIT/ASCII:n address-expression = "ASCII string of length n"

    The default value of n is 4 bytes. 


     
DBG> DEPOSIT I = "abcde"    ! I has compiler-generated integer type. 
%DEBUG-W-INVNUMBER, invalid numeric string 'abcde'
                            ! So, it cannot deposit string into I.
DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer 
                            ! type to deposit 5 bytes of
                            ! ASCII data.
DBG> EXAMINE .              ! Display value of I in compiler- 
MOD3\I:  1146048327         ! generated integer type.
DBG> EXAM/ASCII:5 .         ! Display value of I as 5-byte 
MOD3\I:  "abcde"            ! ASCII string. 
DBG>

    To enter several DEPOSIT/ASCII commands, you can establish an override ASCII type with the SET TYPE/OVERRIDE command. Subsequent EXAMINE and DEPOSIT commands then have the effect of specifying the /ASCII qualifier with these commands. For example: 


     
DBG> SET TYPE/OVER ASCII:5! Establish ASCII:5 as override type. 
DBG> DEPOSIT I = "abcde"  ! Can now deposit 5-byte string into I. 
DBG> EXAMINE I            ! Display value of I as 5-byte 
MOD3\I:  "abcde"          ! ASCII string. 
DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. 
DBG> EXAMINE I            ! Display I in compiler-generated type. 
MOD3\I:  1146048327
DBG>

    4.5.2.3 User-Declared Types

    The following examples show the use of the EXAMINE and DEPOSIT commands with the /TYPE=(name) qualifier. The qualifier enables you to specify a user-declared override type when examining or depositing.

    For example, assume that a Pascal program contains the following code, which declares the enumeration type COLOR with the three values RED, GREEN, and BLUE: 


       .
   .
   .
TYPE 
    COLOR = (RED,GREEN,BLUE); 
   .
   .
   .

    During the debugging session, the SHOW SYMBOL/TYPE command identifies the type COLOR as it is known to the debugger: 


     
DBG> SHOW SYMBOL/TYPE COLOR
data MOD3\COLOR 
    enumeration type (COLOR, 3 elements), size: 1 byte
DBG>

    The next example displays the value at address 1000, which is not associated with a symbolic name. Therefore, the value 0 is displayed in the type longword integer, by default. 


     
DBG> EXAMINE 1000
1000:   0
DBG>

    The next example displays the value at address 1000 in the type COLOR. The preceding SHOW SYMBOL/TYPE command indicates that each enumeration element is stored in 1 byte. Therefore, the debugger converts the first byte of the longword integer value 0 at address 1000 to the equivalent enumeration value, RED (the first of the three enumeration values): 


     
DBG> EXAMINE/TYPE=(COLOR) 1000
1000:   RED
DBG>

    The following DEPOSIT command deposits the value GREEN into address 1000 with the override type COLOR. The EXAMINE command displays the value at address 1000 in the default type, longword integer: 


     
DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN
DBG> EXAMINE 1000
1000:   1
DBG>

    The following SET TYPE command establishes the type COLOR for locations, such as address 1000, that do not have a symbolic name. The EXAMINE command now displays the value at 1000 in the type COLOR: 


     
DBG> SET TYPE TYPE=(COLOR)
DBG> EXAMINE 1000
1000:   GREEN
DBG>

    Chapter 5
    Controlling Access to Symbols in Your Program

    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.

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

    For example, when you try to set a breakpoint on a routine named COUNTER, the debugger might display the following diagnostic message: 


    DBG> SET BREAK COUNTER
%DEBUG-E-NOSYMBOL, symbol 'COUNTER' is not in the symbol table
DBG>

    You must then set the module where COUNTER is defined, as explained in Section 5.2.

    The debugger might display the following message if the same symbol X is defined (declared) in more than one module, routine, or other program unit: 


    DBG> EXAMINE X
%DEBUG-E-NOUNIQUE, symbol 'X' is not unique
DBG>

    You must then resolve the symbol ambiguity, perhaps by specifying a path name for the symbol, as explained in Section 5.3.

    This chapter explains how to handle these and other situations related to accessing symbols in your program.

    The chapter discusses only the symbols (typically address expressions) that are derived from your source program:

    The following types of symbols are discussed in other chapters:

    Also, see Section 4.1.11 for information about how to obtain the memory addresses and register names associated with symbolic address expressions and how to symbolize program locations.

    Note
    If your program was optimized during compilation, certain variables in the program might be removed by the compiler. If you then try to reference such a variable, the debugger issues a warning (see Section 1.2 and Section 14.1).

    Before you try to reference a nonstatic (stack-local or register) variable, its defining routine must be active on the call stack. That is, program execution must be paused somewhere within the defining routine (see Section 3.4.3).

    5.1 Controlling Symbol Information When Compiling and Linking

    To take full advantage of symbolic debugging, you must compile and link your program with the /DEBUG qualifier as explained in Section 1.2.

    The following sections describe how symbol information is created and passed to the debugger when compiling and linking.

    5.1.1 Compiling

    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 created.

    DST records provide not only the names of symbols but also all relevant information about their use. For example:

    Most compilers allow you to vary the amount of DST information put in an object module by specifying different options with the /DEBUG qualifier. Table 5-1 identifies the options for most compilers (see the documentation supplied with your compiler for complete information).

    Table 5-1 Compiler Options for DST Symbol Information
    Compiler Command Qualifier DST Information in Object Module
    /DEBUG 1 Full
    /DEBUG=TRACEBACK 2 Traceback only (module names, routine names, and line numbers)
    /NODEBUG 3 None

    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 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 has occurred. For example: 


    $ RUN FORMS
   .
   .
   .
%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 
FORMS           FORMS             59      00000020    000005A1
$

    Traceback information is also used by the debugger's SHOW CALLS command.

    5.1.2 Local and Global Symbols

    DST records contain information about all of the symbols that are defined in your program. These are either local or global symbols.

    Typically, a local symbol is a symbol that is referenced only within the module where it is defined; a global symbol is a symbol such as a routine name, procedure entry point, or a global data name, that is defined in one module but referenced in other modules.

    A global symbol that is defined in a shareable image and is referenced in another image (for example the main, executable image of a program) is called a universal symbol. When creating a shareable image, you must explicitly define any universal symbols as such at link time. See Section 5.4 for information about universal symbols and shareable images.

    Generally, the compiler resolves references to local symbols, and the linker resolves references to global symbols.

    The distinction between local and global symbols is discussed in various parts of this chapter in connection with symbol lookup and with shareable images and universal symbols.

    5.1.3 Linking

    When you enter the LINK/DEBUG command to link object modules and produce an executable image, the linker performs several functions that affect debugging:

    Section 5.4 explains how to link shareable images for debugging, including how to define universal symbols (global symbols that are defined within a shareable image and referenced from another image).

    Table 5-2 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 information passed to the linker. The LINK command qualifier controls not only how much DST and GST information is passed to the debugger but also whether the program can be brought under debugger control (see Section 1.2).

    Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information
    Compiler Command
    Qualifier1     		DST Data in
    Object Module     		LINK Command
    Qualifier2     		DST Data
    Passed
    to Debugger     		GST Data
    Passed
    to Debugger3
    /DEBUG Full /DEBUG Full Full
    /DEBUG=TRACE Traceback only /DEBUG Traceback only Full
    /NODEBUG None /DEBUG None Full
             
    /DEBUG Full /DSF 4 Full Full 5
    /DEBUG=TRACE Traceback only /DSF 4 Traceback only Full 5
    /NODEBUG None /DSF 4 None Full 5
             
    /DEBUG Full /TRACE 6 Traceback only Full
    /DEBUG=TRACE Traceback only /TRACE Traceback only Full
    /NODEBUG None /TRACE None Full
             
    /DEBUG Full /NOTRACE 7    

    1 See Table 5-1 for additional information.
    2 You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 5.4).
    3 GST data includes global symbol information that is resolved at link time. GST data for an executable image includes the names and values of global routines and global constants. GST data for a shareable image includes universal symbols (see Section 5.1.2 and Section 5.4).
    4Alpha only.
    5DBG$IMAGE_DSF_PATH must point to the directory in which the .DSF file resides.
    6 LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command.
    7 The RUN/DEBUG command allows you to run the debugger, but if you entered the LINK/NOTRACEBACK command you will be unable to do symbolic debugging.

    Previous Next Contents Index