wdbgexpr.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap *refid=videxpr &dbgname Expression Handling
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.ix 'expressions' 'handling of'
.np
The &dbgname is capable of handling a wide variety of expressions.
An expression is a combination of operators and operands selected from
application variables and names, debugger variables, and constants.
Expressions can be used in a large number of debugger commands and dialogs.
For example, the evaluated result of an expression may be displayed
by choosing
.popup New
in the Watches window or by using the print command.
.np
The appropriate syntax of an expression, i.e., the valid sequence of
operators and operands, depends on the grammar of the language that is
currently established.
The &dbgname supports the grammars of the C, C++, and FORTRAN 77
languages.
A grammar is selected automatically by the debugger when tracing the
execution of modules in an application.
For example, part of an application may be written in C, another part
in C++, and another part in FORTRAN 77.
The modules must have been compiled by one of the &company C, C++ or
FORTRAN 77 compilers.
When tracing into a module written in one of these languages, the debugger
will automatically select the appropriate grammar.
In addition to this automatic selection, a particular grammar may be
selected using the debugger
.kw Set LAnguage
command.
The language currently selected can be determined using the
.kw SHow Set LAnguage
command.
.*
.section General Rules of Expression Handling
.*
.np
.ix 'expressions' 'rules'
The debugger handles two types of expressions.
The difference between the two types of expressions is quite subtle.
One is called an "expression" and things operate as you would
normally expect.
This type of expression is used for all "higher" level operations such
as adding items to the Watches window.
The other type is called an "address expression".
It is used whenever the debugger prompts for an address and in
lower level commands such
.kw Examine
and
.kw Modify.
If the notation for a particular command argument is <address>,
it is an address expression.
If it ends in just "expr" then it is a normal expression.
The difference between the two forms lies in how they treat symbol
names.
In a normal expression the value of a symbol is its
.sy rvalue,
or contents.
In an address expression, the value of a symbol is (sometimes) its
.sy lvalue,
or address.
.np
Consider the following case.
You have a symbol
.id sam
at offset 100 and the word at that location contains the value 15.
If you enter
.id sam
into the watches window
you expect the value 15 to be printed and since
the Watches window
takes a normal expression that is what you get.
Now let us try it with the Breakpoint dialog. Enter
.id sam
in the address field. The Breakpoint dialog uses the result of
its expression as the address at which to set a breakpoint. The
Breakpoint dialog takes an address expression, and an implicit unary "&"
operator is placed in front of symbols.
The debugger has a set of heuristics that it applies to determine
whether it should use the rvalue or lvalue of a symbol.
.*
.section Language Independent Variables and Constants
.*
.np
The following sections describe conventions used in the debugger for
identifying modules, variables, line numbers, registers, etc.
.*
.beglevel
.*
.section *refid=exprsym Symbol Names
.*
.np
.ix 'expressions' 'symbol name'
Regardless of the programming language that was used to code the
modules of an application, the names of variables and routines will be
available to the debugger (provided that the appropriate symbolic
debugging information has been included with the application's
execution module).
The debugger does not restrict the way in which names are used in
expressions.
A name could represent a variable but it could also represent the
entry point into a routine.
.np
The syntax of a symbol name reference is quite complicated.
.ix 'expressions' 'module@routine_name'
.ix 'expressions' 'image@module@routine_name'
.ix '@routine_name'
.ix '@@routine_name'
.syntax
[[[image]@][module]@][routine_name.]symbol_name
.esyntax
.pc
Generally, an application will consist of many modules which were
compiled separately.
.ix 'expressions' 'current module'
.ix 'expressions' 'module'
The current image is the one containing the module which is currently
executing.
The current module is the one containing the source lines currently
under examination in the Source or Assembly window.
By default, the Source window's title line contains the current module
name.
.ix 'expressions' 'current routine'
.ix 'expressions' 'routine'
.ix 'expressions' 'function'
.ix 'expressions' 'procedure'
The current routine is the one containing the source line
at which execution is currently paused.
.np
The following are examples of references to symbol names.
.exam begin 7
symbol_name
main
WinMain
FMAIN
printf
LIB$G_OPEN
stdin
.exam end
.np
If the symbol does not exist in the current scope then it must be
qualified with its routine name.
Generally, these are variables that are local to a particular routine.
.exam begin 5
routine_name.symbol_name
main.curr_time
main.tyme
SUB1.X
SUB2.X
.exam end
.np
If the symbol is not externally defined and it does not exist in the
current module then it may be qualified with its module name.
In the C and C++ programming languages, we can define a variable that
is global to a module but known only to that module ("static" storage
class).
.exam begin 1
static char *NarrowTitle = { "Su Mo Tu We Th Fr Sa" };
.exam end
.pc
In the above example, "NarrowTitle" is global to the module
"calendar".
If the current module is not "calendar" then the module name can be
used to qualify the symbol as shown in the following example.
.exam begin 1
calendar@NarrowTitle
.exam end
.np
If the symbol is local to a routine that is not in the current module
then it must be qualified with its module name and routine name.
.exam begin 5
module_name@routine_name.symbol_name
[e-mail]_time
[e-mail]
subs@SUB1.X
subs@SUB2.X
.exam end
.np
If the symbol is local to an image that is not in the current executable
then it must be fully qualified with the image name.
.exam begin 7
prog_name@@routine_name
prog_name@module_name@routine_name
prog_name@module_name@routine_name.symbol_name
dll_name@[e-mail]_time
dll_name@[e-mail]
program@subs@SUB1.X
program@subs@SUB2.X
.exam end
.np
There is a special case for the primary executable image.  This is the
name of the program you specified when you started the debugger.
You can reference it by omitting the image name. The following examples
all refer to symbols in the primary executable image:
.exam begin 3
@@WinMain
@module@WinMain
@@routine.symbol
.exam end
.np
In the FORTRAN 77 programming language, all variables (arguments,
local variables, COMMON block variables) are available to the
subprogram in which they are defined or referenced.
The same symbol name can be used in more than one subprogram.
If it is a local variable, it represents a different variable in each
subprogram.
If it is an argument, it may represent a different variable in each
subprogram.
If it is a variable in a COMMON block, it represents the same variable
in each subprogram where the COMMON block is defined.
.cp 15
.exam begin 14
SUBROUTINE SUB1( X )
REAL Y
COMMON /BLK/ Z
    .
    .
    .
END
SUBROUTINE SUB2( X )
REAL Y
COMMON /BLK/ Z
    .
    .
    .
END
.exam end
.pc
In the above example, "X" is an argument and need not refer to the
same variable in the calling subprogram.
.exam begin 2
CALL SUB1( A )
CALL SUB2( B )
.exam end
.pc
The variable "Y" is a different variable in each of "SUB1" and "SUB2".
The COMMON block variable "Z" refers to the same variable in each of
"SUB1" and "SUB2" (different names for "Z" could have been used).
To refer to "X", "Y", or "Z" in the subprogram "SUB2", you would
specify "SUB2.X", "SUB2.Y", or "SUB2.Z".
If "SUB2" was in the module "MOD" and it is not the current module,
you would specify "MOD@SUB2.X", "MOD@SUB2.Y", or "MOD@SUB2.Z".
.begnote
.note Note:
Global and local symbol name debugging information is included in an
executable image if you request it of the linker.
However, local symbol information must be present in your object
files.
The &company C, C++ and FORTRAN 77 compilers can include local symbol
debugging information in object files by specifying the appropriate
compiler option.
.refalso vidprep
.endnote
.*
.section Line Numbers
.*
.np
.ix 'expressions' 'line numbers'
Regardless of the programming language that was used to code the
modules of an application, line number information identifying the
start of executable statements will be available to the debugger
(provided that the appropriate symbolic debugging information has
been included with the application's execution module).  The
debugger does not restrict the way in which line number references
are used in expressions.  A line number represents the code
address of an executable statement in a routine.  Not all line
numbers represent executable statements; thus some line numbers
may not be valid in an expression.  For example, source lines
consisting of comments do not represent executable statements.
.np
The general format for a line number reference is:
.syntax
[ [image]@ ] [module_name] @ decimal_digits
.esyntax
.np
The following are examples of references to executable statements.
.exam begin 11
@36
@@45
@51
@125
hello@9
@hello@9
prog@hello@9
otherprg@goodbye@9
puzzle@50
calendar@20
SUB1@30
.exam end
.np
If the line number does not exist in the current module, it must be
qualified with its module name.  If it does not exist in the current
image, it must be qualified with the image name.
Line numbers are not necessarily unique.
For example, an executable statement could occur at line number 20 in
several modules.
The module name can always be used to uniquely identify the line 20
in which we are interested.
In the above examples, we explicitly refer to line 20 in the module
"calendar".
When the module name is omitted, the current module is assumed.
.begnote
.note Note:
Line number debugging information is included in an executable image
if you request it of the linker.
However, line number information must be present in your object files.
The &company C, C++ and FORTRAN 77 compilers can include line number
debugging information in object files by specifying the appropriate
compiler option.
.refalso vidprep
You can request line number debugging information when assembling
assembly language source files using &asmname. The "d1" option must
be specified on the command line.
.endnote
.*
.section Constants
.*
.np
A
.us constant
can be arithmetic or character.  Each constant has a data type
associated with it.  Arithmetic constants consist of those
constants whose data type is one of integer, real, or complex
(FORTRAN only).  C treats character constants like arithmetic
constants so they can be used in arithmetic expressions.  FORTRAN
treats character constants as constants of type CHARACTER so they
cannot be used in arithmetic expressions.
.beglevel
.*
.section Integer Constants
.*
.np
.ix 'expressions' 'integer constant'
An
.us integer constant
is formed by a non-empty string of digits preceded by an optional
radix specifier.
The digits are taken from the set of digits valid for the current
radix.
If the current radix is 10 then the digits are '0' through '9'.
If the current radix is 16 then the digits are '0' through '9' and 'A'
through 'F' or 'a' through 'f'.
.refalso dlgopt
.np
The following are examples of integer constants.
.exam begin 5
123
57DE
1423
345
34565788
.exam end
.np
Radix specifiers may be defined by the user, but two are predefined
by the debugger.
.us 0x
may be defined to be a radix specifier for
hexadecimal (base 16) numbers.
.us 0n
may be defined to be a radix specifier for decimal (base 10)
numbers
.exam begin 7
0x1234      hexadecimal
0n1234      decimal
255         decimal
0xff        hexadecimal
0x1ADB      hexadecimal
0n200       decimal
0x12fc0     hexadecimal
.exam end
.*
.section Real Constants
.*
.np
.ix 'expressions' 'real constant'
We first define a
.us simple real constant
as follows: an optional sign followed by an integer part followed by a
decimal point followed by a fractional part.
The integer and fractional parts are non-empty strings of digits.
The fractional part can be omitted.
.np
.ix 'expressions' 'real constant'
A
.us real constant
has one of the following forms.
.begpoint
.point (1)
A simple real constant.
.point (2)
A simple real constant followed by an
.id E
or
.id e
followed by an optionally signed integer constant.
.endpoint
.pc
The optionally signed integer constant that follows the
.id E
is called the
.us exponent.
The value of a real constant that contains an exponent is the value of
the constant preceding the
.id E
multiplied by the power of ten determined by the exponent.
.np
The following are examples of real constants.
.millust begin
123.764
0.4352344
1423.34E12
+345.E-4
-0.4565788E3
2.E6
1234.
.millust end
.begnote
.note Note:
The accepted forms of floating-point constants are a subset of
that supported by the FORTRAN 77 programming language.  The
debugger does not support floating-point constants that begin with
a decimal point (e.g., .4352344) or have no decimal point (e.g., 2E6).
However, both forms would be acceptable to a FORTRAN
compiler.  Also, the debugger does not support double precision
floating-point constants where "D" is used instead of "E" for the
exponent part (e.g., 2D6, 2.4352344D6).  All floating-point
constants are stored internally by the debugger in double
precision format.
.endnote
.*
.section Complex Constant (FORTRAN Only)
.*
.np