[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP OpenVMS Debugger Manual

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 and I64 only) Displays each examined entity in the IEEE S_floating type (single precision, length 4 bytes).

/LONG_LONG_FLOAT

/T_FLOAT

(Alpha and I64 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.

/PSR

(I64 only) Displays each examined entity in PSR (processor status register) 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.

/PSR

(I64 only) Displays each examined entity in PSR (processor status register) format.

/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 HP DECwindows Motif for OpenVMS user 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.

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

/VARIANT=variant-selector address-expression

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

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) or anonymous variant (PASCAL) to display.

/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 and I64 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.

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. The exceptions are BLISS and MACRO, 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:
If the debugger encounters an anonymous variable list while displaying address-expression, the debugger uses the variant selector to choose which variant to display.
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.
The debugger walks the structure top-to-bottom, depth first, so that children are encountered before siblings.
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.
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

#1
DBG> EXAMINE COUNT SUB2\COUNT: 27 DBG>

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

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

This command displays the value of the string variable PART_NUMBER.

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

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

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

#6
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).

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

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

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

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

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

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

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

Contents

Index