wguidrnt.gml

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

:set symbol="msg_list" value="event list"
:set symbol="mark_menu" value="File"
.*
.chap &drnt for Win32
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix 'debugger' 'post-mortem'
.ix '&drnt'
The 32-bit version of &drnt is a post-mortem debugger for Win32
applications.
When an exception occurs in a program, a post-mortem debugger allows
you, after the fact, to examine the state of both the program and the
system in order to determine the cause of the exception.
In addition to being a debugging tool, &drnt is a system utility that
enables you to examine and modify process information.
.begnote
.note Note:
Use the 32-bit version of &drnt to monitor native (Win32) applications
running under Windows 9x and NT based operating systems.
Use the 16-bit version of &drnt to monitor 16-bit Windows (Win16)
applications.
.endnote
.*
.section Using &drnt
.*
.np
This section discusses the following topics:
.begbull $compact
.bull
Starting &drnt
.bull
Quitting &drnt
.bull
The &drnt Menu Bar
.endbull
.np
&drnt is designed to be used effectively while minimized. You can
access some of &drnt's main functionality using the system menu while
the application is minimized. This includes the Log Current State, Log
Options, and Process Control menu items.
.*
.beglevel
.*
.section Starting &drnt
.*
.np
.ix 'start' '&drnt'
.ix '&drnt' 'start'
To start &drnt double click on the &drnt icon. This opens the &drnt
window.
.begnote
.note Note:
You can run only one instance of &drnt at a time.
.endnote
.*
.section Quitting &drnt
.*
.np
.ix '&drnt' 'leave'
.ix 'quit' '&drnt'
To exit &drnt, choose Exit from the File menu of the &drnt window.
.*
.section The &drnt Menu Bar
.*
.np
.ix 'Menu bar' '&drnt'
.ix '&drnt' 'Menu bar'
The Menu bar consists of the following four menus:
.begpoint
.point File
Save to a file and work with the event list
a file
.point Log
Work with the log file
.point Process
Work with processes currently running under Windows
.point Help
Access on-line help information
.endpoint
.*
.endlevel
.*
.section Using the &drnt Window
.*
.np
.ix 'event list' 'in &drnt'
.ix '&drnt' 'event list'
When you open &drnt, a window appears which contains the event list.
The event list records events generated by processes to which &drnt
is attached. To record these events you must first attach &drnt to the
desired processes. To perform this function, refer to the
section entitled :HDREF refid='drntat'..
Some examples of events are errors, the starting and ending of
threads, and the loading and unloading of DLLs.
.keep 16
.figure *depth='2.24' *scale=64 *file='DRW1' The &drnt window contains the event list where occurring events are recorded.
.np
The following sections describe functions that allow you to manipulate
the event list:
.begbull $compact
.bull
Saving the Event List
.bull
Clearing the Event List
.bull
Marking the Event List
.bull
Setting the Fonts
.endbull
.*
.beglevel
.*
.section &drnt.: Saving Event List Information to a File
.*
.np
.ix '&drnt' 'save'
The Save items in the File menu allow you to save the contents of the
event list to a text file. Saving information to a file enables you to
print the output later or annotate the text file on-line.
.np
.ix 'Save' 'in &drnt'
.ix '&drnt' 'save'
Choose Save from the File menu to save the event list information into
the current working directory. A message box appears indicating the
path to which &drnt saved the file.
.np
.ix 'Save As' 'in &drnt'
.ix '&drnt' 'Save As'
Choose Save As from the File menu to specify the file to which you
want to save the information currently in the window. This opens a
Save As dialog box where you select the desired file. Click on OK when
completed. A message box appears indicating the path to which &drnt
saved the event list.
.*
.section &drnt.: Clearing the Event List
.*
.np
.ix 'event list' 'clear'
.ix 'Clear List'
Choose Clear List from the File menu to delete all information from
the event list.
.*
.section &drnt.: Marking the Event List
.*
.ix '&drnt' 'marking event list'
.ix 'event list' 'marking in &drnt'
:INCLUDE file='wguimark.gml'
.*
.section &drnt.: Setting the Fonts
.*
.np
.ix 'fonts' 'setting in &drnt'
.ix '&drnt' 'set font'
The Set Font item in the File menu allows you to set the font, style,
and size for the text in the &drnt window. Choosing this item opens
the Font dialog box. Select the desired font details and click on OK
to close the dialog and apply the fonts.
.*
.endlevel
.*
.section Debugging Information Processors
.*
.np
Debugging Information Processors (DIP's) are Dynamic Link Libraries
that &drnt loads to read debugging information. Each DIP allows &drnt
to read a different type of debugging information.
.beglevel
.*
.section Using the Debugging Information Processor Status dialog
.*
.np
Choosing the Show DIP Status item from the File menu displays the
Debugging Information Processor Status dialog.
.keep 17
.figure *depth='2.5' *scale=80 *file='DRW4' The Debugging Information Processor Status dialog shows the DIP's &drnt has loaded.
.np
This dialog contains a list of all the DIP's that &drnt attempted to
load at startup and the results of those loads. If &drnt was unable to
load a particular DIP then the dialog will show the reason for the
failure. &drnt can only read a given type of debugging information if
it has successfully loaded the appropriate DIP.
.endlevel
.*
.section &drnt.: Exception Handling
.*
.np
.ix 'exception' 'handling in &drnt'
.ix '&drnt' 'exception handling'
.ix 'fatal error in &drnt'
When a fatal error, or exception, occurs in a process to which &drnt
is attached, &drnt intercepts the exception. By intercepting the
exception, &drnt halts the program's execution to prevent it from
terminating. When an exception occurs, a &drnt exception dialog box
appears on the screen indicating that a fatal error has occurred. This
dialog displays information about the error and gives you several
options.
.keep 24
.figure *depth='2.30' *scale=64 *file='DRW5' The exception dialog appears when a fatal error occurs in a program.
.np
The information displayed about the error includes:
.begpoint $break
.point Process Name
The name of the process in which the error occurred.
.point Process ID
The unique identifier associated with the process.
.point Fault Type
The type of fault that occurred.
.point Fault CS:EIP
The address of the instruction being executed when the fault occurred.
.point Source Info
The source line on which the error occurred. This only appears if the
program running contains debugging information and the exception
occurred on an assembly instruction that corresponds to a source line.
.endpoint
.np
There are four buttons on the exception dialog that you can use to
proceed.
.begnote
.note Act
.ix 'Act'
When the Act button is pressed &drnt.'s action is determined by the
option currently selected in the "action to take" section of the
dialog. The following describes the action taken for each option.
.begpoint $break
.point Terminate Task
When the Terminate Task radio button is selected choosing Act causes
the faulting process to be terminated immediately.
.*
.point Restart Instruction
When the Restart Instruction radio button is selected choosing Act
causes the faulting process to restart execution starting with the
instruction pointed to by its CS:EIP. This option is primarily used to
restart a process after you have changed its register values using the
Process Status dialog.
.*
.point Chain to Next Handler
A handler is a piece of code, a program, or a routine that gets called
when an exception occurs. A process can have several exception
handlers. When the Chain to Next Handler radio button is selected
choosing Act tells the operating system to continue searching for a
handler to deal with this exception. If no handler is found for the
exception then &drnt will redisplay the exception dialog to give you a
second chance to deal with the exception. During this second chance
notification the chain to next handler option is not available. This
option is useful for testing your own exception handling code.
.endpoint
.note Act and Log
.ix 'Act and Log'
Choosing the Act and Log button first creates a log file entry
recording information about this exception then takes the same action
that would result from choosing the Act button.
.note Registers
.ix 'Registers'
Select the Registers button to open the Process Status dialog. This
dialog gives you additional information on the state of the process
when the exception occurred. From this window you can change the
registers and flags and view the process's address space.
Refer to the section entitled :HDREF refid='drntex'.
for further information.
.note Options
.ix 'Options'
Select the Options button to choose the information you want to write
to the log file. This opens the Log Options dialog explained in the
section entitled :HDREF refid='drntcu'..
.endnote
.*
.beglevel
.*
.section Using External Exception Handlers
.*
.np
You can use the Continue Exceptions item in the file menu to tell
&drnt to only report on exceptions that are not handled by another
exception handler. When this item is checked &drnt only displays an
exception dialog if the system is unable to find a handler for an
exception. This behavior is the same as when Continue Exceptions is
not checked and chain to next handler is selected on the exception
dialog.
.*
.section *refid=drntex Examining the Process Status
.*
.np
.ix 'Process Status dialog'
.ix '&drnt' 'Process Status dialog'
The Process Status dialog appears when you choose the Registers button
in the exception dialog.
:CMT. .figure *depth='1.xx' *file='DRWx' The Process Status dialog provides additional information on the program state when the exception occurred.
.np
This dialog displays information in four sections:
.begbull $compact
.bull
Source Information
.bull
Registers
.bull
Flags
.bull
Instructions Around Fault
.endbull
.np
The Source Information section indicates the source file where the
error occurred and the line of that source file. In order to get
source information, your program must contain debugging information.
N/A appears in the Source Information section if the program does not
contain debugging information or the exception occurred on an assembly
instruction that does not correspond to a source file.
.np
The Registers and Flags sections display information in the CPU at the
time of the exception.
.np
The Instructions Around Fault section displays the assembly
instructions surrounding the instruction that was being executed when
the fault occurred. An asterisk marks the instruction to which the
CS:EIP is currently pointing.
.np
When the Show Symbols box is checked, &drnt tries to replace addresses
in the assembly code with symbolic names. &drnt can only replace
addresses if the faulting module contained debugging information. If
this box is not checked, addresses appear as numeric values.
.*
.beglevel
.*
.section &drnt.: Changing the Registers
.*
.np
.ix 'Process Status dialog' 'in &drnt'
.ix '&drnt' 'Process Status dialog'
In the Process Status dialog you can set up testing and debugging
situations by changing the values of the registers and flags. To
change a register value simply enter a new value in the edit field
that contains the current register value. To change the state of a
flag register just check or uncheck the check box associated with that
flag. A flag has a value of 1 when its check box is checked.
.np
The register and flag values will not take effect until you choose OK
on the Process Status dialog.
.*
.section &drnt.: Applying Registers
.*
.np
.ix 'Apply Registers'
.ix '&drnt' 'Apply Registers'
Selecting the Apply Registers button on the Process Status dialog
after making changes to the registers and flags updates the displayed
information based on your changes.
.*
.section *refid=drntvi &drnt.: Viewing Memory
.*
.np
.ix 'View Memory'
.ix '&drnt' 'View Memory'