wguidrwc.gml

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

:set symbol="msg_list" value="event list"
:set symbol="mark_menu" value="File"
.*
.chap &drwc for Windows 3.1
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix '&drwc'
The 16-bit version of &drwc is a post-mortem debugger for Windows 3.1.
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, &drwc is a system utility that
enables you to examine task information.
.np
&drwc can be a useful tool when performing in-house testing on your
applications. By running &drwc while testing applications, all faults
are logged. This gives you important information to recreate the
errors so you can fix the problems.
.begnote
.note Note:
Use the 16-bit version of &drwc to monitor 16-bit Windows (Win16)
applications running under Windows 3.1 or Win32 based operating systems.
Use the 32-bit version of &drwc to monitor Win32 applications running
under Win32 based operating systems.
.endnote
.*
.section Using &drwc
.*
.np
This section discusses the following topics:
.begbull $compact
.bull
Starting &drwc
.bull
Quitting &drwc
.bull
The &drwc Menu Bar
.endbull
.np
&drwc is designed to be used effectively while minimized. You only
need to view the application window when an error or warning occurs.
When this happens the &drwc icon changes from stethoscope to an
explosion indicating that information is waiting for your attention in
the main window.
.np
Some of &drwc's main functionality can also be accessed using the
system menu while the application is minimized. This includes the log
options, task control, and log current state functions.
.np
&drwc is more useful with the Windows debug kernel. Under the debug
kernel, Windows checks for many common programming errors and
generates debugging messages when it finds them. &drwc catches the
debugging messages and displays them on the event list. Viewing these
messages helps you identify errors in your program that you might not
otherwise see.
.*
.beglevel
.*
.section Starting &drwc
.*
.ix '&drwc' 'start'
.ix 'start' '&drwc'
.np
To start &drwc, double click on the &drwc icon. This opens the &drwc
window.
.*
.section Quitting &drwc
.*
.ix '&drwc' 'leave'
.ix 'Exit' '&drwc'
.np
To exit &drwc, select Exit from the File menu. This is the only way to
quit the application. Unlike other applications, double clicking on
the system menu box or selecting close from the system menu only
minimizes the application.
.*
.section The &drwc Menu Bar
.*
.ix 'menu bar' '&drwc'
.ix '&drwc' 'menu bar'
.np
The menu bar consists of the following four menus:
.begpoint
.point File
Save to a file, work with the event list, and configure the session
.point Log
Work with the log file
.point Task
Work with tasks currently running under Windows
.point Help
Access on-line help information
.endpoint
.*
.endlevel
.*
.section Using the &drwc Window
.*
.np
.ix 'event list' 'in &drwc'
.ix '&drwc' 'event list'
When you open &drwc, a window appears which contains the event list.
The event list records the various events occurring under Windows.
Some examples of events are errors, debugging messages
(under the debug kernel of Windows only), the starting and ending of
programs, and the loading and unloading of DLLs.
.keep 16
.figure *depth='2.24' *scale=64 *file='DRW1' The &drwc window contains the event list which records and displays events occurring under Windows.
.np
When a debug message is issued, the &drwc icon alerts you that an
entry has been made on the event list. The &drwc icon changes from
stethoscope to an explosion. To reset the icon you must acknowledge
the alert in one of two ways:
.begstep
.step View the event list
by double clicking on the icon, or
.step Choose Clear Alert
.ix 'Clear Alert'
from the system menu.
.endstep
.np
&drwc intercepts all exceptions that occur in the system. An exception
is an error that causes your program to terminate. &drwc prevents your
program from terminating by halting the program's execution. The state
of the program remains intact.
.np
As with non-fatal errors, &drwc makes an entry on the event list when
an exception occurs. However, instead of alerting you to the entry by
changing the icon, &drwc reveals an exception dialog. This dialog
gives you several options. Refer to the
section entitled :HDREF refid='drwcexc'. for more information.
.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 &drwc.: Saving Event List Information to a File
.*
.np
.ix '&drwc' '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 &drwc'
.ix '&drwc' '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 &drwc saved the file.
.np
.ix 'Save As' 'in &drwc'
.ix '&drwc' '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 &drwc
saved the event list.
.*
.section &drwc.: Clearing the Event List
.*
.np
.ix 'event list' 'clear'
.ix 'Clear List'
Choose Clear from the File menu to delete all information from the
event list.
.*
.section &drwc.: Marking the Event List
.*
.ix '&drwc' 'marking event list'
.ix 'event list' 'marking in &drwc'
:INCLUDE file='wguimark.gml'
.*
.section &drwc.: Setting the Fonts
.*
.np
.ix 'fonts' 'setting in &drwc'
.ix '&drwc' 'set font'
The Set Font item in the File menu allows you to set the font, style,
and size for the text in the &drwc 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.
.*
.section Setting the Alert Feature
.*
.np
Each time &drwc logs a debug message, its icon changes from a
stethoscope to an explosion . This indicates that there is important
information waiting for you in the event list. Some debug messages
report only minor programming anomalies that may not be errors at all.
The text for these messages is prefixed by
.us wn,
for warning. Because these messages are not urgent, you may not want
the icon to signal the message. The Alert on Warnings menu item allows
you to configure &drwc so that its icon does not change for these
minor warning messages.
.np
.ix 'Alert on Warnings option'
.ix '&drwc' 'configure'
When the Alert on Warnings item in the File menu is not checked, the
icon does not change for minor warning messages. When this item is
checked, the &drwc icon alerts you when a warning or serious error
occurs.
.*
.section Showing the DIP status
.*
.np
DIP's (Debugging Information Processors) are Dynamic Link Libraries
that &drwc loads to read debugging information. Each DIP allows &drwc
to read a different type of debugging information. Choosing the Show
DIP Status item from the File menu displays the Debugging Information
Processor Status dialog.
.keep 17
.figure *depth='2.14' *scale=68 *file='DRW4' The Debugging Information Processor Status dialog shows the DIP's &drwc has loaded.
.np
This dialog contains a list of all the DIP's that &drwc attempted
to load at startup and the results of those loads. If &drwc was unable
to load a particular DIP then the dialog will show the reason for
the failure. &drwc can only read a given type of debugging information
if it has successfully loaded the appropriate DIP.
.*
.section Using the Clear Alert Function
.*
.ix 'Clear Alert function'
.ix '&drwc' 'Clear Alert'
.np
If you are running &drwc minimized then each time an error or
warning is logged, the icon changes from a stethoscope to an explosion.
Unless you reset the icon, you will not know when more events are
added to the event list.
.np
There are two ways to reset the &drwc icon:
.begstep
.step Double click on the icon
to view the event list, or
.step Choose Clear Alert
.ix 'Clear Alert'
from the system menu.
.endstep
.np
To clear the alert message, click on the &drwc icon to reveal
the system menu. Choose Clear Alert from the menu to change
the icon back to the stethoscope. &drwc still logs the event,
but you do not have to look at it immediately.
.*
.endlevel
.*
.section *refid=drwcexc &drwc.: Exception Handling
.*
.ix '&drwc' 'exception dialog'
.ix 'Exceptions' 'handling in &drwc'
.np
The &drwc exception dialog box appears on your screen when an
exception occurs in any program in the system. This indicates that a
fatal error has occurred.
.keep 24
.figure *depth='2.30' *scale=64 *file='DRW5' The exception dialog appears when a fatal error occurs in a program.
.np
Instead of terminating the program, &drwc suspends it and leaves its
state intact. Because the state is undisturbed you can view the
program's state information from the exception dialog, including
memory and register values. The exception dialog displays information
about error and gives you several options. The information displayed
about the error includes:
.begpoint $break
.point Task Name
The name of the module in which the error occurred.
.point Task Path
The full path of the file from which the offending module was loaded.
.point Fault Type
The type of fault that occurred.
.point Fault CS:EIP
The address of the instruction being executed when the fault occurred.