wdbgcmd.gml

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

.chap *refid=vidcmd Debugger Commands
.*
.np
This section describes the syntax of debugger commands as well as
a description of each of the debugger commands.
.*
.section Syntax Definitions
.*
.np
.ix 'command' 'syntax'
.ix 'syntax' 'for commands'
A debugger command may contain any of the following syntax elements:
.begbull
.bull
A word in angle brackets, like <anything> is a defined term. Its
definition will appear after the syntax description of the command.
.bull
[x] indicates that "x" is an optional item. It may or may not be
included in the command.
.bull
[x|y|z] indicates that on of x, y or z should be included in the
command.
.bull
[x [x [...]]] indicates that x may be repeated zero or more times in
the command.
.bull
CApital indicates that ca,cap,capi,... are accepted short forms for
the command "capital".
.bull
(GUI only) indicates that this command is only available in a GUI
debugger.
.bull
(character-based) indicates that this command is only available in a
character mode debugger.
.bull
<expr> indicates an expression. These may include any of the
variables, etc in the program being debugged, and are evaluated in the
current program context.
.refalso videxpr
.bull
<integer> is an integer constant
.bull
<intexpr> is an an expression which evaluates to an integral value.
.refalso videxpr
.bull
<command> is any debugger command or group of debugger commands.
.np
You can group debugger commands with braces and separate them with
semi-colons. The resulting compound command may be considered as an
atomic command.
.code begin
{<command>;<command>;<command>}
.code end
.bull
<address> is any expression which evaluates to an address.
.refalso videxpr
.bull
<string> is a string of text, optionally enclosed in braces. For
example,
.code begin
this_is_a_string
{so is this}
.code end
.bull
<wndname> is the name of a window. Valid window names (with acceptable
short forms indicated in capitals) are:
.begbull $compact
.bull
ASsembly
.bull
ALl
.bull
BReak
.bull
Calls
.bull
Watch
.bull
FIle
.bull
FPu
.bull
FUnctions
.bull
FILEScope
.bull
LOCals
.bull
LOG
.bull
MEmory
.bull
MOdules
.bull
Register
.bull
SOurce
.bull
STack
.bull
Thread
.bull
IO
.bull
Globals
.bull
Variable
.bull
BInary
.bull
IMage
.bull
GLobalfunctions
.bull
Accelerators
.bull
TMPFile
.bull
REPlay
.bull
CUrrent
.endbull
.np
.bull
<file> represents any valid operating system file name. For example,
.code begin
c:\autoexec.bat
.code end
.bull
<path> represents
any valid operating system directory path. For example,
.code begin
c:\dir1\dir2
.code end
.endbull
.*
.section Command Summary
.*
.np
.ix 'command' 'summary'
A summary of each command follows.
.beglevel
.cmddef Accelerate
.np
This command behaves as if a menu item from the main menu was selected:
.code begin
Accelerate main <menu> {<menu_string>}
.code end
.np
This command behaves as if the named menu item in the
floating pop-up menu for the current window was selected:
.code begin
Accelerate {<menu_string>}
.code end
.begnote $break
.note <menu>
the string appearing on the main menu bar (File, Run, Break, Code, etc)
.note <menu_string>
is enough of the text appearing in a menu to uniquely identify it.
.endnote
.np
For example:
.code begin
accelerate main run {until return}
.code end
.pc
behaves as if "Until return" is selected from the run menu
.code begin
accelerate {Home}
.code end
.pc
behaves as if "home" were picked from the floating pop-up menu of the
current window.

.cmddef Break
.np
This command prints a list of all breakpoints into the log window:
.code begin
Break
.code end
.np
This command sets a break point.  See the section entitled
:HDREF refid='vidbrk'. for details about breakpoint operation.
.code begin
Break [|/Set|/Byte|/Word|/DWord|/Modify]
          <address> [ {<do_command>} [ { <condition> } [ <countdown> ]]]
.code end
.np
This command deactivates a breakpoint:
.code begin
Break/Deactivate <brkid>
.code end
.np
This command enables a breakpoint:
.code begin
Break/Activate <brkid>
.code end
.np
This command clears a breakpoint:
.code begin
Break/Clear <brkid>
.code end
.np
This command toggles a breakpoint through the active/inactive/deleted
states:
.code begin
Break/Toggle <brkid>
.code end
.np
This command turns on the resume option in the breakpoint:
.code begin
Break/Resume <brkid>
.code end
.np
This command turns off the resume option in the breakpoint:
.code begin
Break/UnResume <brkid>
.code end
.np
The Break options are:
.begnote $break $compact
.note /Set (default)
the breakpoint triggers when <address> is executed
.note /Byte
the breakpoint triggers when the byte at <address> is modified
.note /Word
the breakpoint triggers when the word at <address> is modified
.note /DWord
the breakpoint triggers when the double word at <address> is modified
.note /Modify
the breakpoint triggers when integer at <address> is modified
.note <condition>
an expression that must be true (non-zero value)
before the breakpoint stops program execution
.note <countdown>
an integer.  The breakpoint will not stop program
execution until <countdown> is decremented to zero.
.begnote
.note Note:
If you specify both <condition> and <countdown>, <countdown>
decrements only when <condition> evaluates to true.
.endnote
.note <do_command>
a command that is executed each time the breakpoint stops
program execution
.note <brkid>
option can be three possible values:
.begnote
.note <address>
Perform the operation on breakpoint with the given address.
.note *
Perform the operation on all breakpoints.
.note #<integer>
Names a breakpoint by its index.  This index can be discovered on
the title line of the Breakpoint dialog.
.endnote
.endnote
.np
Some examples of the break command and a description follow:
.np
This command sets a breakpoint at "foo" the 20th time that i equals 10.
When this occurs 'do j7' is executed:
.code begin
Break /Set foo {do j7} {i10} 20
.code end
.np
This command clears the breakpoint at foo:
.code begin
Break /Clear foo
.code end
.np
This command activates breakpoint #1:
.code begin
Break /Activate #1
.code end
.np
This command deactivates all breakpoints:
.code begin
Break /Deactivate *
.code end

.cmddef Call
.np
Use the Call command to call a routine. The Call command options are:
.code begin
Call [/Far|/Interrupt|/Near]
         <address>
         [([<parm>[,<parm>[...]]])] [/|<printlist>]
.code end
.np
This command calls the routine at <address> with parameters.
.begnote
.note /Far
Use a far call instruction.
.note /Near
Use a near call instruction.
.note /Interrupt
Call the routine as if it were an interrupt handler.
.note <parm>
is [/<location>] <expr>
.note <location>
is [/|<regset>]
.begnote
.note /
means to put the parm on the stack.
.note /<regset>
means to put the parm into the named registers.
.note <regset> is a register aggregate.
.refalso videxpr
.endnote
.note <printlist>
See the print command for details.
.endnote
.np
Some examples of the Call command follow:
This command calls the function foo:
.code begin
call foo
.code end
.np
This command calls the function bar passing the parameters 1, 2, and 3:
.code begin
call bar( 1,2,3 )
.code end
.np
This command calls foo putting 1 on the stack, 2 in AX and 3 in CX:BX
printing out the value of AX and DX in decimal and hexadecimal
respectively on return:
.code begin
call /near foo( // 1, /ax 2, /[cx bx] 3 ) {%d %x} ax,dx
.code end
.np
The Call command only uses very basic symbolic information - it's
designed that way so that it can work even when no symbolic
information is available.
This has a number of implications.
The first is that the debugger pays no attention to any information on
where parameters are stored.
For example, in 32-bit applications, unless explictly instructed
otherwise, the first parm is placed in EAX, the second in EDX, and so
on (as defined by the "set call" command).
That means that you have to do something like:
.code begin
call foo( // &a, // &b )
.code end
.pc
to get things on to the stack.
This leads to a second, very important consideration.
.np
The debugger has no idea of the memory model that the program is
compiled in (recall that the 32-bit compiler does support large memory
models and far pointers, even if we don't supply versions of
the libraries for it).
That means that the debugger has no idea on whether the address of a
symbol should be far or near.
It always assumes far, since that never loses information.
A far pointer would be truncated to a near pointer when moved into a
32-bit register like EAX but not so when pushed onto the stack.
In this case,
.id // &a
and
.id // &b
cause 48-bit far pointers to be pushed onto the stack (they are
actually pushed as 64 bits for alignment reasons).
Thus the pointer to
.id b
is in the wrong place for the routine to access it (assuming it is
expecting near pointers) and this will likely cause a task exception.
To avoid this problem and properly pass arguments to the routine, you
need to do the following:
.code begin
call foo( // (void near *)&a, // (void near *)&b )
.code end
.pc
This forces the debugger to push near pointers onto the stack.
.np
Similar considerations apply for the 16-bit case.

.cmddef CAPture
.np
Use the Capture command to execute a command and put the resulting
program output into a window. The format of the command follows:
.code begin
CAPture <command>
.code end
.np
For example, this command calls a routine, foo, and puts its output
into a debugger window.
.code begin
capture call foo
.code end

.cmddef COnfigfile
.code begin
COnfigfile
.code end
.np
Used by the debugger to save and restore the configuration. When
"configfile" appears in a command file, it identifies that file as the
default configuration file. The debugger will overwrite the command
file when autosaving the current configuration. Also, the name of this
file is displayed in the filename field when the "Save Setup" dialog
initially appears.
.np
If more than one file is encountered containing the "configfile"
command, the last one seen is used to establish the configuration
file name.

.cmddef Display
.np
The display command allows you to open any window.
The general Display command is:
.code begin
Display <wndname> [/Open|/Close|/New|/MInimize|/MAximize|/Restore] [<ord>,<ord>,<ord>,<ord>]
.code end
.np
This command causes the debugger screen to repaint:
.code begin
Display
.code end
.np
This command displays the toolbar as either fixed (default) or floating:
.code begin
Display TOolbar [/Open] [/FLoating/Fixed] [<ord>]
.code end
.np
This command closes the toolbar:
.code begin
Display TOolbar [/Close]
.code end
.np
This command opens the status line:
.code begin
Display Status [/Open]
.code end
.np
This command closes the status line:
.code begin
Display Status /Close
.code end
.np
This command brings a window to the front:
.code begin
Display <wndname>
.code end
.np
The options for the Display command follow:
.begnote $break
.note <ord>
The height to be used for toolbar buttons.
.note <ord>,<ord>,<ord>,<ord>