Updated: 11 December 1998

OpenVMS Debugger Manual

Displays the current value of a program variable. More generally, displays the value of the entity denoted by an address expression.

Format

EXAMINE [address-expression[:address-expression] [,...]]

Parameters

address-expression

Specifies an entity to be examined. With high-level languages, this is typically the name of a variable and can include a path name to specify the variable uniquely. More generally, an address expression can also be a memory address or a register and can be composed of numbers (offsets) and symbols, as well as one or more operators, operands, or delimiters. For information about the debugger symbols for the registers and about the operators you can use in address expressions, type Help Built_in_Symbols or Help Address_Expressions.

If you specify the name of an aggregate variable (a composite data structure such as an array or 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, follow the syntax of the current language.

If you specify a range of entities, the value of the address expression that denotes the first entity in the range must be less than the value of the address expression that denotes the last entity in the range. The debugger displays the entity specified by the first address expression, the logical successor of that address expression, the next logical successor, and so on, until it displays the entity specified by the last address expression. You can specify a list of ranges by separating ranges with a comma.

For information specific to vector registers and vector instructions, see /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers.

Qualifiers

/ASCIC

/AC

Interprets each examined entity as a counted ASCII string preceded by a 1-byte count field that gives the length of the string. The string is then displayed.

/ASCID

/AD

Interprets each examined entity as the address of a string descriptor pointing to an ASCII string. The CLASS and DTYPE fields of the descriptor are not checked, but the LENGTH and POINTER fields provide the character length and address of the ASCII string. The string is then displayed.

/ASCII:n

Interprets and displays each examined entity as an ASCII string of length n bytes (n characters). If you omit n, the debugger attempts to determine a length from the type of the address expression.

/ASCIW

/AW

Interprets each examined entity as a counted ASCII string preceded by a 2-byte count field that gives the length of the string. The string is then displayed.

/ASCIZ

/AZ

Interprets each examined entity as a zero-terminated ASCII string. The ending zero byte indicates the end of the string. The string is then displayed.

/BINARY

Displays each examined entity as a binary integer.

/BYTE

Displays each examined entity in the byte integer type (length 1 byte).

/CONDITION_VALUE

Interprets each examined entity as a condition-value return status and displays the message associated with that return status.

/D_FLOAT

Displays each examined entity in the D_floating type (length 8 bytes).

/DATE_TIME

Interprets each examined entity as a quadword integer (length 8 bytes) containing the internal representation of date and time. Displays the value in the format dd-mmm-yyyy hh:mm:ss.cc.

/DECIMAL

Displays each examined entity as a decimal integer.

/DEFAULT

Displays each examined entity in the default radix.

The minimum abbreviation is /DEFA.

/DEFINITIONS=n

(Alpha only) When the code is optimized, displays n definition points for a split-lifetime variable. A definition point is a location in the program where the variable could have received its value. By default, up to five definition points are displayed. If more than the given number of definitions (explicit or default) are available, then the number of additional definitions is reported as well. (For more information on split-lifetime variables, see Chapter 14.)

The minimum abbreviation is /DEFI.

/EXTENDED_FLOAT

/X_FLOAT

(Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes).

/FLOAT

On VAX processors, same as /F_FLOAT. Displays each examined entity in the F_floating type (length 4 bytes).

On Alpha processors, same as T_FLOAT. Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).

/F_FLOAT

(VAX only) Displays each examined entity in the F_floating type (length 4 bytes).

/FPCR

(Alpha only) Displays each examined entity in FPCR (floating-point control register) format.

/FMASK[=(mask-address-expression)]

Applies only to VAX vectorized programs. See the /TMASK qualifier.

/G_FLOAT

Displays each examined entity in the G_floating type (length 8 bytes).

/H_FLOAT

(VAX only) Displays each examined entity in the H_floating type (length 16 bytes).

/HEXADECIMAL

Displays each examined entity as a hexadecimal integer.

/INSTRUCTION

Displays each examined entity as an assembly-language instruction (variable length, depending on the number of instruction operands and the kind of addressing modes used). See also the /OPERANDS qualifier.

In screen mode, the output of an EXAMINE/INSTRUCTION command is directed at the current instruction display, if any, not at an output or DO display. The arrow in the instruction display points to the examined instruction.

On Alpha processors, the command EXAMINE/INSTRUCTION procedure-name displays the first instruction at the code address of a specified routine, entry point, or Ada package.

/LINE (default)

/NOLINE

Controls whether program locations are displayed in terms of line numbers (%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger symbolizes program locations in terms of line numbers.

/LONG_FLOAT

/S_FLOAT

(Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes).

/LONG_LONG_FLOAT

/T_FLOAT

(Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).

/LONGWORD

Displays each examined entity in the longword integer type (length 4 bytes). This is the default type for program locations that do not have a compiler-generated type.

/OCTAL

Displays each examined entity as an octal integer.

/OCTAWORD

Displays each examined entity in the octaword integer type (length 16 bytes).

/OPERANDS[=keyword]

(VAX only) Displays operand information associated with an examined instruction (displays each operand's address and its contents, using the operand's data type). The keywords BRIEF and FULL vary the amount of information displayed about any nonregister operands. The default is /OPERANDS=BRIEF.

Use /OPERANDS only when examining the instruction at the current PC value (for example, EXAMINE/OPERANDS .0\%PC). Examining the operands of an instruction that is not at the current PC value can give erroneous results, because the state of the machine (the contents of the registers) is not set up for that instruction.

In screen mode, operand information is directed at the current output display.

When you examine the operands of a vector instruction, any operand-element masking that might be associated with that instruction is performed by default. The /TMASK and /FMASK qualifiers enable you to specify some other mask. The current value of the vector length register (VLR) limits the highest element of a vector register that you can examine.

See also the SET MODE [NO]OPERANDS=keyword command, which lets you set a default level for the amount of operand information displayed when examining instructions.

/PACKED:n

Interprets each examined entity as a packed decimal number. The value of n is the number of decimal digits. Each digit occupies one nibble (4 bits).

/PS

(Alpha only) Displays each examined entity in PS (processor status register) format.

/PSL

(VAX only) Displays each examined entity in PSL (processor status longword) format.

/PSW

(VAX only) Displays each examined entity in PSW (processor status word) format. The /PSW qualifier is like /PSL except that only the low-order word (2 bytes) is displayed.

/QUADWORD

Displays each examined entity in the quadword integer type (length 8 bytes).

/S_FLOAT

(Alpha only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes).

/SFPCR

(Alpha only) Displays each examined entity in SFPCR (software floating-point control register) format.

/SOURCE

Note This qualifier is not available in the DECwindows Motif interface to the debugger.

Displays the source line corresponding to the location of each examined entity. The examined entity must be associated with a machine code instruction and, therefore, must be a line number, a label, a routine name, or the memory address of an instruction. The examined entity cannot be a variable name or any other address expression that is associated with data.

In screen mode, the output of an EXAMINE/SOURCE command is directed at the current source display, if any, not at an output or DO display. The arrow in the source display points to the source line associated with the last entity specified (or the last one specified in a list of entities).

On Alpha processors, the command EXAMINE/SOURCE procedure-name displays the source code at the code address of a specified routine, entry point, or Ada package.

/SYMBOLIC (default)

/NOSYMBOLIC

Controls whether symbolization occurs. By default (/SYMBOLIC), the debugger symbolizes all addresses, if possible; that is, it converts numeric addresses into their symbolic representation. If you specify /NOSYMBOLIC, the debugger suppresses symbolization of entities you specify as absolute addresses. If you specify entities as variable names, symbolization still occurs. The /NOSYMBOLIC qualifier is useful if you are interested in identifying numeric addresses rather than their symbolic names (if symbolic names exist for those addresses). Using /NOSYMBOLIC may speed up command processing because the debugger does not need to convert numbers to names.

/TASK

Applies to tasking (multithread) programs. Interprets each examined entity as a task (thread) object and displays the task value (the name or task ID) of that task object. When examining a task object, use /TASK only if the programming language does not have built-in tasking services.

/T_FLOAT

(Alpha only) Displays each examined entity in the IEEE T_floating type (double precision, length 8 bytes).

/TMASK[=(mask-address-expression)]

/FMASK[=(mask-address-expression)]

These qualifiers apply only to VAX vectorized programs. They enable you to specify a mask in order to display certain elements of a vector register (V0 to V15), or of an array in memory, while not displaying other elements.

For example, when you examine the operands of a vector instruction (by using the /OPERANDS qualifier), these qualifiers enable you to override any operand-element masking that might be associated with that instruction.

The /TMASK qualifier applies the EXAMINE command only to the elements of the register or array that correspond to the set bits (bit value: 1) of the mask. The /FMASK qualifier applies the EXAMINE command only to the elements that correspond to the clear bits (bit value: 0) of the mask. The current value of the vector length register (VLR) limits the highest register element that you can examine but not the highest array element.

By default, if you do not specify a mask address expression with /TMASK or /FMASK, the vector mask register (VMR) is used. That is, the EXAMINE command is applied only to the elements of the vector register or array that correspond to the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of VMR.

If you specify a mask address expression with /TMASK or /FMASK, the value at that address is used as the mask, subject to the following conventions:

• You must use parentheses around the address expression.
• The number of mask elements limits the number of register or array elements that you can examine.
• If the mask address expression denotes a Boolean array, its values are used as the mask, in the same basic way that VMR is used in the default case.
• If the mask address expression denotes a non-Boolean array, the least significant bit value of each array element is used as the mask for the corresponding element of the register or target array.
• If the mask address expression denotes a Boolean scalar type, its value is used as the mask for the first element of the register or target array. No other elements are examined.
• If the mask address expression denotes any other type, its least significant bit value is used as the mask for the first element of the register or target array. No other elements are examined.
• For a multi-element mask, the lowest specified element of the mask is applied to the lowest specified element of the register or target array.

/TYPE=(name)

Interprets and displays each examined entity according to the type specified by name (which must be the name of a variable or data type declared in the program). This enables you to specify a user-declared type. You must use parentheses around the type expression.

/VMR

(VAX only) Applies only to VAX vectorized programs. Displays the Vector Mask Register.

/WCHAR_T[:n]

Interprets and displays each examined entity as a multibyte file code sequence of length n longwords (n characters). The default is 1 longword.

When converting the examined string, the debugger uses the locale database of the process in which the debugger runs. The default is C locale.

/WORD

Displays each examined entity in the word integer type (length 2 bytes).

/X_FLOAT

(Alpha only) Displays each examined entity in the IEEE X_floating type (length 16 bytes).

Description

The EXAMINE command displays the entity at the location denoted by an address expression. You can use the command to display the contents of any memory location or register that is accessible in your program. For high-level languages, the command is used mostly to obtain the current value of a variable (an integer, real, string, array, record, and so on).

If you are debugging optimized code on Alpha systems, the EXAMINE command displays the definition points at which a split-lifetime variable could have received its value. Split-lifetime variables are discussed in Chapter 14. By default, the EXAMINE command displays up to five definition points. With the /DEFINITIONS qualifier, you can specify the number of definition points.

The debugger recognizes the compiler-generated types associated with symbolic address expressions (symbolic names declared in your program). Symbolic address expressions include the following entities:

• Variable names. When specifying a variable with the EXAMINE command, use the same syntax that is used in the source code.
• Routine names, labels, and line numbers. These are associated with instructions. You can examine instructions using the same techniques as when examining variables.

In general, when you enter an EXAMINE command, the debugger evaluates the address expression specified to yield a program location. The debugger then displays the value stored at that location as follows:

• If the location has a symbolic name, the debugger formats the value according to the compiler-generated type associated with that symbol (that is, as a variable of a particular type or as an instruction).
• If the location does not have a symbolic name (and, therefore, no associated compiler-generated type) the debugger formats the value in the type longword integer by default. This means that, by default, the EXAMINE command displays the contents of these locations as longword (4-byte) integer values.

For information specific to vector registers (VAX only) and vector instructions (VAX only), see the /TMASK, /FMASK, /VMR, and /OPERANDS qualifiers.

There are several ways of changing the type associated with a program location so that you can display the data at that location in another data format:

• To change the default type for all locations that do not have a symbolic name, you can specify a new type with the SET TYPE command.
• To change the default type for all locations (both those that do and do not have a symbolic name), you can specify a new type with the SET TYPE/OVERRIDE command.
• To override the type currently associated with a particular location for the duration of a single EXAMINE command, you can specify a new type by using a type qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). Most qualifiers for the EXAMINE command are type qualifiers.

The debugger can interpret and display integer data in any one of four radixes: binary, decimal, hexadecimal, and octal.

The default radix for both data entry and display is decimal for most languages. On VAX processors, the exceptions are BLISS and MACRO--32, which have a default radix of hexadecimal. On Alpha processors, the exceptions are BLISS, MACRO--32, and MACRO--64, which have a default radix of hexadecimal.

The EXAMINE command has four radix qualifiers (/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) that enable you to display data in another radix. You can also use the SET RADIX and SET RADIX/OVERRIDE commands to change the default radix.

In addition to the type and radix qualifiers, the EXAMINE command has qualifiers for other purposes:

• The /SOURCE qualifier enables you to identify the line of source code corresponding to a line number, routine name, label, or any other address expression that is associated with an instruction rather than data.
• The /[NO]LINE and /[NO]SYMBOLIC qualifiers enable you to control the symbolization of address expressions.

The EXAMINE command sets the current entity built-in symbols %CURLOC and period (.) to the location denoted by the address expression specified. Logical predecessors (%PREVLOC or the circumflex character (^)) and successors (%NEXTLOC) are based on the value of the current entity.

Related Commands:

• CANCEL TYPE/OVERRIDE
• DEPOSIT
• DUMP
• EVALUATE
• SET MODE [NO]OPERANDS
• SET MODE [NO]SYMBOLIC
• (SET,SHOW,CANCEL) RADIX
• (SET,SHOW) TYPE

Examples

DBG> EXAMINE COUNT
SUB2\COUNT:  27
DBG>
      

This command displays the value of the integer variable COUNT in module SUB2.

DBG> EXAMINE PART_NUMBER
INVENTORY\PART_NUMBER:  "LP-3592.6-84"
DBG>
      

This command displays the value of the string variable PART_NUMBER.

DBG> EXAMINE SUB1\ARR3
SUB1\ARR3 
   (1,1):     27.01000 
   (1,2):     31.01000 
   (1,3):     12.48000 
   (2,1):     15.08000 
   (2,2):     22.30000 
   (2,3):     18.73000
DBG>
      

This command displays the value of all elements in array ARR3 in module SUB1. ARR3 is a 2 by 3 element array of real numbers.

DBG> EXAMINE SUB1\ARR3(2,1:3)
SUB1\ARR3 
   (2,1):     15.08000 
   (2,2):     22.30000 
   (2,3):     18.73000
DBG>
      

This command displays the value of the elements in a slice of array SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2.

DBG> EXAMINE VALVES.INTAKE.STATUS
MONITOR\VALVES.INTAKE.STATUS:  OFF
DBG>
      

This command displays the value of the nested record component VALVES.INTAKE.STATUS in module MONITOR.

DBG> EXAMINE/SOURCE SWAP
module MAIN 
    47:  procedure SWAP(X,Y: in out INTEGER) is
DBG>
      

This command displays the source line in which routine SWAP is declared (the location of routine SWAP).

DBG> DEPOSIT/ASCII:7 WORK+20 = 'abcdefg'
DBG> EXAMINE/ASCII:7 WORK+20
DETAT\WORK+20:  "abcdefg"
DBG> EXAMINE/ASCII:5 WORK+20
DETAT\WORK+20:  "abcde"
DBG>
      

In this example, the DEPOSIT command deposits the entity 'abcdefg' as an ASCII string of length 7 bytes into the location that is 20 bytes beyond the location denoted by the symbol WORK. The first EXAMINE command displays the value of the entity at that location as an ASCII string of length 7 bytes (abcdefg). The second EXAMINE command displays the value of the entity at that location as an ASCII string of length 5 bytes (abcde).

DBG> EXAMINE/OPERANDS=FULL .0\%PC
X\X$START+0C:   MOVL    B^04(R4),R7 
     B^04(R4)   R4 contains X\X$START\M (address 00001054), 
                B^04(00001054) evaluates to X\X$START\K 
                (address 00001058), which contains 00000016 
     R7         R7 contains 00000000
DBG>
      

On VAX systems, this command displays the instruction (MOVL) at the current PC value. Using /OPERANDS=FULL displays the maximum level of operand information.

DBG> SET RADIX HEXADECIMAL
DBG> EVALUATE/ADDRESS WORKDATA
0000086F
DBG> EXAMINE/SYMBOLIC 0000086F
MOD3\WORKDATA:  03020100
DBG> EXAMINE/NOSYMBOLIC 0000086F
0000086F:  03020100
DBG>
      

In this example, the EVALUATE/ADDRESS command indicates that the memory address of variable WORKDATA is 0000086F, hexadecimal. The two EXAMINE commands display the value contained at that address using /[NO]SYMBOL to control whether the address is symbolized to WORKDATA.

DBG> EXAMINE/HEX FIDBLK
FDEX1$MAIN\FIDBLK 
    (1):        00000008 
    (2):        00000100 
    (3):        000000AB
DBG>
      

This command displays the value of the array variable FIDBLK in hexadecimal radix.

DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6
SUB2\NEWDATA:  256 
SUB2\NEWDATA+2:  770 
SUB2\NEWDATA+4:  1284 
SUB2\NEWDATA+6:  1798
DBG>
      

This command displays, in decimal radix, the values of word integer entities (2-byte entities) that are in the range of locations denoted by NEWDATA to NEWDATA + 6 bytes.

DBG> EXAMINE/TASK SORT_INPUT
MOD3\SORT_INPUT:  %TASK 12
DBG>
      

This command displays the task ID of a task object named SORT_INPUT.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_047.HTML