HP OpenVMS Systems Documentation

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

/LONG_FLOAT

/S_FLOAT

/LONG_LONG_FLOAT

/T_FLOAT

/LONGWORD

/OCTAL

/OCTAWORD

/OPERANDS[=keyword]

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

/PS

/PSL

/PSW

/QUADWORD

/S_FLOAT

/SFPCR

/SOURCE

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

/TASK

/T_FLOAT

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

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

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)

/VARIANT=variant-selector address-expression

/VARIANT=(variant-selector,...) address-expression

In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid.

In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default.

You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C) or anonymous variant (PASCAL) to display.

/VMR

/WCHAR_T[:n]

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

/X_FLOAT

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.

The /VARIANT qualifier enables the debugger to display the correct item when it encounters an anonymous variant.

In a C program, a union contains members, only one of which is valid at any one time. When displaying a union, the debugger does not know which member is currently valid. In a PASCAL program, a record with a variant part contains variants, only one of which is valid at any one time. When displaying a record with an anonymous variant part, the debugger does not know which variant is currently valid, and displays all variants by default.

You can use the /VARIANT qualifier of the EXAMINE command to select which member of a union (C program) or anonymous variant (PASCAL program) to display. The format is as follows:

DBG> EXAMINE /VARIANT=variant-selector address-expression

DBG> EXAMINE /VARIANT=(variant-selector,...) address-expression

The variant selector variant-selector specifies a name, a discriminant (PASCAL only), or a position; that is, one of the following:

• NAME = name-string
• DISCRIMINANT = expression
• POSITION = expression

The /VARIANT qualifier takes a list of zero or more variant selectors. /VARIANT without any variant selectors is the default: the first variant of all anonymous variant lists will be displayed.

Each variant selector specifies either the name, the discriminant, or the position of the variant to be displayed.

The debugger uses the variant selector as follows:

1. If the debugger encounters an anonymous variable list while displaying address-expression, the debugger uses the variant selector to choose which variant to display.
2. Each time the debugger encounters an anonymous variant list, it attempts to use the next variant selector to choose which variant to display. If the variant selector matches one of the variants of the variant list (union), the debugger displays that variant.
3. The debugger walks the structure top-to-bottom, depth first, so that children are encountered before siblings.
4. If the debugger encounters an anonymous variant list and does not have a variant selector to match it with, the debugger displays the first variant.
5. If the variant selector does not match any of the variants of an anonymous variant list, the debugger displays a single line to indicate that. This is similar to what the debugger does if the discriminant value fails to match any of the variants in a discriminated variant list. . For example:

   [Variant Record omitted - null or illegal Tag Value: 3]

A name specifies a name string. A name matches a variant if that variant contains a field with the name specified by name.

A discriminant specifies a language expression that must be type compatible with the tag type of the variant part it is meant to match. The discriminant expression matches a variant if it evaluates to a value in the variant's case-label list. Discriminants apply only to Pascal programs, because C and C++ unions do not have discriminants.

A positional-selector specifies a language expression, which should evaluate to a integer between 1 and N, where N is the number of variants in a variant list. A positional-selector that evaluates to I specifies that the Ith variant is to be displayed.

You can use asterisk (*) as a wildcard, which matches all variants of an anonymous variant list.

Each of these variant selectors can be used to match all variants. In particular, each of the following variant selectors indicates that all of the variants of the first anonymous variant list are to be displayed.

/VAR=D=* /VAR=N=* /VAR=P=*

The variant selectors can themselves contain a list of selectors. For example, the following commands all mean the same thing.

EXAMINE /VARIANT=(DIS=3,DIS=1,DIS=54) x EXAMINE /VARIANT=(DIS=(3,1,54)) x EXAMINE /VARIANT=DIS=(3,1,54) x

You can specify a a single discriminant or position value without parentheses if the value is a simple decimal integer. To use a general expression to specify the value, you enclose the expression in parentheses. In the following list of commands, the first four are legal while the last three are not.

EXAMINE /VARIANT=POS=3 EXAMINE /VARIANT=POS=(3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=(3)) ! parentheses unnecessary EXAMINE /VARIANT=(POS=3) ! parentheses unnecessary EXAMINE /VARIANT=(POS=foo) ! parentheses necessary EXAMINE /VARIANT=POS=(foo) ! parentheses necessary EXAMINE /VARIANT=(POS=3-1) ! parentheses necessary

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.

DBG> EXAMINE /VARIANT=(NAME=m,DIS=4,POS=1) x
      

This command specifies that, for the first anonymous variant list encountered, display the variant part containing a field named "m", for the second anonymous variant list, display the part with the discriminant value 4, and, for the third anonymous variant list, display the first variant part.