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] [, . . . ]]
1 – 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.
2 – Qualifiers
2.1 /ASCIC
/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.
2.2 /ASCID
/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.
2.3 /ASCII
/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.
2.4 /ASCIW
/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.
2.5 /ASCIZ
/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.
2.6 /BINARY
Displays each examined entity as a binary integer.
2.7 /BYTE
Displays each examined entity in the byte integer type (length 1
byte).
2.8 /CONDITION_VALUE
Interprets each examined entity as a condition-value return
status and displays the message associated with that return
status.
2.9 /D_FLOAT
Displays each examined entity in the D_floating type (length 8
bytes).
2.10 /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.
2.11 /DECIMAL
Displays each examined entity as a decimal integer.
2.12 /DEFAULT
Displays each examined entity in the default radix.
The minimum abbreviation is /DEFA.
2.13 /DEFINITIONS
/DEFINITIONS=n
(Alpha only, Integrity servers when optimized code is supported)
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
the VSI OpenVMS Debugger Manual.
The minimum abbreviation is /DEFI.
2.14 /EXPAND
Helps to expand complex unions or structures which have an
embedded structure containing a pointer to the top level structure.
2.15 /EXTENDED_FLOAT
/EXTENDED_FLOAT
/X_FLOAT
(Alpha and Integrity servers only) Displays each examined entity
in the IEEE X_floating type (length 16 bytes).
2.16 /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).
2.17 /FPCR
(Alpha only) Displays each examined entity in FPCR (floating-
point control register) format.
2.18 /G_FLOAT
Displays each examined entity in the G_floating type (length 8
bytes).
2.19 /HEXADECIMAL
Displays each examined entity as a hexadecimal integer.
2.20 /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.
2.21 /LINE
/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.
2.22 /LONG_FLOAT
/LONG_FLOAT
/S_FLOAT
(Alpha and Integrity servers only) Displays each examined entity
in the IEEE S_floating type (single precision, length 4 bytes).
2.23 /LONG_LONG_FLOAT
/LONG_LONG_FLOAT
/T_FLOAT
(Alpha and Integrity servers only) Displays each examined entity
in the IEEE T_floating type (double precision, length 8 bytes).
2.24 /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.
2.25 /OCTAL
Displays each examined entity as an octal integer.
2.26 /OCTAWORD
Displays each examined entity in the octaword integer type
(length 16 bytes).
2.27 /PACKED
/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).
2.28 /PS
(Alpha only) Displays each examined entity in PS (processor
status register) format.
2.29 /PSR
(Integrity servers only) Displays each examined entity in PSR
(processor status register) format.
2.30 /PSR
(Integrity servers only) Displays each examined entity in PSR
(processor status register) format.
2.31 /QUADWORD
Displays each examined entity in the quadword integer type
(length 8 bytes).
2.32 /S_FLOAT
(Alpha only) Displays each examined entity in the IEEE S_floating
type (single precision, length 4 bytes).
2.33 /SFPCR
(Alpha only) Displays each examined entity in SFPCR (software
floating-point control register) format.
2.34 /SOURCE
NOTE
This qualifier is not available in the VSI 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.
2.35 /SYMBOLIC
/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.
2.36 /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.
2.37 /TYPE
/TYPE=(name)
/TYPE:(name)
/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.
2.38 /VARIANT
/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.
2.39 /WCHAR_T
/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.
2.40 /WORD
Displays each examined entity in the word integer type (length 2
bytes).
2.41 /X_FLOAT
(Alpha and Integrity servers only) Displays each examined entity
in the IEEE X_floating type (length 16 bytes).
3 – 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 the VSI OpenVMS Debugger Manual. 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:
o Variable names. When specifying a variable with the EXAMINE
command, use the same syntax that is used in the source code.
o 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:
o 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).
o 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.
4 – Description, Continued...
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:
o 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.
o 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.
o 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:
o 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.
o 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:
o NAME = name-string
o DISCRIMINANT = expression
o 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
5 – 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> 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.
8.DBG> ex %r9:%r12
TEST\%R9: 0000000000000000
TEST\%R10: 0000000000000000
TEST\%R11: 0000000000000000
TEST\%SP: 000000007AC8FB70
DBG> ex/bin grnat0 <9,4,0>
TEST\%GRNAT0+1: 0110
DBG>
Debugger displays the string "NaT" when the integer register's
NaT bit is set.
9.Use /EXPAND to EXAMINE certain complex structures as below:
typedef struct _A{
int i;
struct {
int j;
int k;
struct _A *p;
} ST;
}A;
void main()
{
A a1,a2;
a1.i = 10;
a1.ST.j=11;
a1.ST.k=12;
a1.ST.p=0;
a2.i = 210;
a2.ST.j=211;
a2.ST.k=212;
a2.ST.p=&a1;
}
The EXAMINE command displays the following output for the above
example.
DBG> EXAMINE a2
TEST\main\a2
i: 210
ST
j: 211
k: 212
p: 2060327712
DBG> EXAMINE *a2.ST.p
*TEST\main\a2.ST.p
i: 10
ST: 51539607563 [cycle found in type definitions]
EXAMINE command does not expand the pointer ST.
Similar behavior happens for unions too.
The EXAMINE/EXPAND command displays the following output:
DBG> EXAMINE/EXPAND *a2.ST.p
%DEBUG-I-EXAMEXPAND, Use examine/expand with caution
*TEST\main\a2.ST.p
i: 10
ST
j: 11
k: 12
p: 0
DBG>
Note: In case of genuine loops in the structure, the EXAMINE/EXPAND
behavior is undefined. The debugger can go into an infinite loop and
in such cases, the use of EXAMINE/EXPAND must be avoided. An example for
this case is given below.
$ type a.cxx
struct B;
struct A {
B &x;
A( B &x );
};
struct B {
A y;
B();
};
A::A( B &xx ) : x(xx) {}
B::B( ) : y( *this ) {}
B b;
void main() {
B b1;
A a1(b1);
}
The EXAMINE/EXPAND command displays the following output:
DBG> EXAMINE/EXPAND *a2.ST.p
%DEBUG-I-EXAMEXPAND, Use examine/expand with caution
*TEST\main\a2.ST.p
i: 10
ST
j: 11
k: 12
p: 0
DBG>
Note: In case of genuine loops in the structure, the EXAMINE/EXPAND
behavior is undefined. The debugger can go into an infinite loop and
in such cases, the use of EXAMINE/EXPAND must be avoided. An example for
this case is given below.
$ type a.cxx
struct B;
struct A {
B &x;
A( B &x );
};
struct B {
A y;
B();
};
A::A( B &xx ) : x(xx) {}
B::B( ) : y( *this ) {}
B b;
void main() {
B b1;
A a1(b1);
}