wdbgstrt.gml

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

.chap *refid=vidstrt Starting Up the Debugger
.*
.np
The following topics are discussed:
.begbull
.bull
:HDREF refid='vidcmdl'.
.bull
:HDREF refid='comopt'.
.bull
:HDREF refid='dwopt'.
.bull
:HDREF refid='dosopt'.
.bull
:HDREF refid='winopt'.
.bull
:HDREF refid='linuxopt'.
.bull
:HDREF refid='qnxopt'.
.bull
:HDREF refid='videvar'.
.endbull
.*
.section *refid=vidcmdl &dbgname Command Line
.*
.np
There are several versions of the debugger.
.begnote
.note binw&pc.&dbgcmd..exe
This is the DOS character-mode debugger.
.note binw&pc.&dbgcmd.c.exe
This is the Windows 3.x character-mode debugger.
.note binw&pc.&dbgcmd.w.exe
This is the Windows 3.x windowed (GUI) debugger.
.note binnt&pc.&dbgcmd..exe
This is the Windows NT/9x character-mode debugger.
.note binnt&pc.&dbgcmd.w.exe
This is the Windows NT/9x windowed (GUI) debugger.
.note binp&pc.&dbgcmd..exe
This is the OS/2 character-mode debugger.
.note binp&pc.&dbgcmd.w.exe
This is the OS/2 windowed (GUI) debugger.
.note wd
This is the name of the debugger used on UNIX platforms.
.endnote
.np
See the sections entitled
:HDREF refid='vidoss'.
and
:HDREF refid='vidrem'.
for information on which version to select for your situation.
.np
On the debugger command line, you can specify options that you want to
use during your debugging session. Acceptable option short forms are
indicated in capital letters. For example, the
.us /TRap
option may be shortened to
.us /tr.
.*
.section *refid=comopt Common Switches
.*
.np
The following switches are applicable to all operating systems.
.begnote $break

.cw !
.note /TRap=trap_file[;trap_parm]
.cw ;
.ix 'options' 'TRap'
.ix 'TRap option'
.ix 'DOS extenders' 'trap option'
specifies an executable helper program that the debugger uses to
control the application being debugged, or to communicate across a
remote link.
It is called a "trap file" since the interrupts used
for debugging are sometimes called "traps".  The
.sy trap
option selects
the appropriate trap file to use.
.bi This option must be specified when remote debugging,
.bi debugging DOS extender applications
.bi or debugging OS/2 exception handlers.
.np
The remote trap files themselves have startup parameters.
This is specified following the semi-colon.
.refalso vidrem
.ix '32-bit debugging' 'trap file'
.ix 'trap file'
.ix 'extensions' '.TRP'
.ix 'TRP extension'
Normally you do not have to specify a trap file. If you do not specify
the
.sy trap
option, the default trap file that supports local debugging is loaded.
There are several exceptions.
.autopoint
.point
To debug a CauseWay 32-bit application, you must use
.us /TRAP=CW.
.point
To debug a Tenberry Software 32-bit DOS/4G(W) application, you must
use
.us /TRAP=RSI.
.point
To debug a Phar Lap 32-bit application, you must use
.us /TRAP=PLS.
.point
.ix 'exception handler' 'OS/2'
.ix 'OS/2 exception handler'
.ix 'debugging an OS/2 exception handler'
To debug an OS/2 exception handler, you must use
.us /TRAP=STD&semi.2
which tells the debugger to catch exceptions only on the second chance
(normally it would be the debugger that traps the exception).
.point
To debug an OS/2 16-bit application under Phar Lap's RUN286 DOS
extender, you must use
.us /TRAP=STD16.
.endpoint

.note /LInes=n
.ix 'display' 'changing lines'
.ix 'screen' 'number of lines'
.ix 'options' 'LInes'
.ix 'LInes option'
controls the number of lines used by a character mode debugger.  The number
of lines available depends on the operating system and your video card.
The values 25, 43 and 50 are often supported.

.note /COlumns=n
.ix 'display' 'changing columns'
.ix 'screen' 'number of columns'
.ix 'options' 'COlumns'
.ix 'COlumns option'
controls the number of columns used by a character mode debugger.  The number
of columns available depends on the operating system and your video card.
If your system does not support the requested number of columns,
this option is ignored

.note /Invoke=file
.ix 'options' 'Invoke'
.ix 'Invoke option'
may be used to specify an alternate name for the debugger configuration file
which is to be used at start-up time.
The default file name is "&dbgcmdup..&dbgsuffup".
Debugger configuration files are found in the current directory or one
of the directories in your
.ev PATH
.dot

.note /NOInvoke
.ix 'options' 'NOInvoke'
.ix 'NOInvoke option'
specifies that the default debugger configuration file is not to be invoked.

.note /NOMouse
.ix 'options' 'NOMouse'
.ix 'NOMouse option'
requests that the debugger ignore any attached mouse.
.ix 'mouse' 'sharing'
.ix 'mouse events' 'debugging'
.ix 'debugging' 'mouse events'
.bi This may be necessary if you are trying to debug mouse events
.bi received by your application.
This option ensures that the debugger
will not interfere with the mouse.

.note /DYnamic=number
.ix 'options' 'DYnamic'
.ix 'DYnamic option'
specifies the amount of dynamic storage that the debugger is to
set aside for its own use on startup.  The default amount that is
set aside is 500K bytes.  The larger the amount, the less memory
will be available for the application to be debugged.
.bi You only
.bi need to use this option if the debugger runs out of memory, or is
.bi causing your application to run out of memory.
If you are using the remote debugging feature, the debugger will use
as much available memory as available.

.note /NOExports
.ix 'options' 'NOExports'
.ix 'NOExports option'
specifies that no exports (system symbols) should be loaded.
It helps to speed up load time when debugging remotely and marginally
so when debugging locally.

.note /LOcalinfo=local_file
.ix 'options' 'LOcalinfo'
.ix 'LOcalinfo option'
is used primarily, but not exclusively, in conjunction with the remote
debugging capabilities of the debugger. It causes the debugger to use one or
more local files as sources of debugging information if the right
conditions are met. When the debugger observes that an executable file
or Dynamic Link Library (DLL) is being loaded with the same name
(i.e., the path and extension have been stripped) as one of the
.sy /localinfo
files, then the named local file is used as a source of debugging
information. The named file can be an executable file, a DLL file
(.dll), a symbolic information file (.sym), or any other file with
debugging information attached.
.tinyexam begin
wd /local=c:\dlls\mydll.sym /local=c:\exes\myexe.exe /tr=par myexe
.tinyexam end
.np
In the above example, the debugger would obtain debugging information
for any executable or DLL called
.mono myexe
or
.mono mydll
from
.fi c:\exes\myexe.exe
or
.fi c:\dlls\mydll.sym
respectively.
Note that no path searching is done for local files.
The debugger tries to open the file exactly as specified in the
.sy localinfo
option.
.np
See the section entitled :HDREF refid='vidrem'. for an explanation of
remote debugging.

.note /DOwnload
.ix 'options' 'DOwnload'
.ix 'DOwnload option'
specifies that executable file to be debugged is to be downloaded to
the task machine from the debugger machine.
The debugger searches for the executable file in the local path, and
downloads it to the debug server's current working directory on the
remote machine before starting to debug.
Debugging information is not downloaded, but is obtained locally, as
in the
.sy localinfo
option.
Note: Only the executable is downloaded; any required DLLs must be
present on the remote machine.
Downloading is relatively fast if you are using one of the TCP/IP
(TCP) or Netware (NOV) remote links.
Be sure to specify the file extension if it is not ".exe".
.exam begin
wd /tr=nov;john /download sample.exe
wd /tr=nov;john /download sample.nlm
.exam end
.np
The debugger does not erase the file when the debugging session ends.
So if you debug the application again, it will check the timestamp,
and if the file is up-to-date, it doesn't bother re-downloading it.
.np
See the section entitled :HDREF refid='vidrem'. for an explanation of
remote debugging.

.note /REMotefiles
.ix 'options' 'REMotefiles'
.ix 'REMotefiles option'
is used in conjunction with the remote debugging capabilities of the
debugger.  It causes the debugger to look for all source files
and debugger files on the remote machine.
When
.sy remotefiles
is specified, all debugger files (except "trap" files) and application
source files are opened on the task machine rather than the debugger
machine.
The trap file must be located on the debugger machine.
.np
The
.ev PATH
environment variable on the task machine is always used in locating
executable image files.
When
.sy remotefiles
is specified, the debugger also uses the task machine's
.ev PATH
environment variable to locate debugger command files.
See the section entitled :HDREF refid='vidrem'. for an explanation of
remote debugging.
See the section entitled :HDREF refid='rfxfile'. for an explanation of
remote and local file names.

.note /NOFpu
.ix 'options' 'NOFpu'
.ix 'NOFpu option'
requests that the debugger ignore the presence of a math coprocessor.

.note /NOSYmbols
.ix 'options' 'NOSYmbols'
.ix 'NOSYmbols option'
requests that the debugger omit all debugging information when loading
an executable image.
.bi This option is useful if the debugger detects and
.bi tries to load debugging information which is not valid.

.note /DIp=dipname
.ix 'options' 'DIp'
.ix 'DIp option'
used to load a non-default Debug Information Processor (DIP).  This option
is generally not needed since the debugger loads all DIPs that it finds
by default.
.refalso wndimg

.endnote
.*
.section *refid=dwopt DOS and Windows Options
.*
.np
The following switches apply to the DOS (binw&pc.&dbgcmd)
and Windows 3.x character-mode (binw&pc.&dbgcmd.c)
debuggers.
Refer to the sections called :HDREF refid='dosopt'. and
:HDREF refid='winopt'. for more switches relating to these
environments.
.begnote $break

.note /Monochrome
.ix 'options' 'Monochrome'
.ix 'Monochrome option'
When two display devices are present in the system, this option
indicates that the Monochrome display is to be used as the debugger's
output device, leaving the Color display for the application to use.
Use this option in conjunction with the
.sy Two
option described below.

.note /Color, /Colour
.ix 'options' 'Color'
.ix 'Color option'
.ix 'options' 'Colour'
.ix 'Colour option'
When two display devices are present in the system, this option
indicates that the Colour display is to be used as the debugger's
output device.
This option is used in conjunction with the