DrWatson.TXT

This document contains information on:

   A. What is DrWatson?
   B. How to install DrWatson
   C. Using DrWatson
   D. Where to send information gathered by DrWatson
   E. Additional details on DrWatson


A. What is DrWatson?
--------------------
DrWatson is a diagnostic tool designed to provide developers 
with detailed information on the internal state of Windows 
when a system error such as an unrecoverable application 
error (UAE) occurs.  

DrWatson must be running at the time a UAE occurs in order 
to extract the required internal information from the system.
DrWatson takes very little memory and does not affect 
performance, so we encourage you to install DrWatson if a UAE 
has occurred before.  

After DrWatson is installed, if another UAE occurs, valuable 
information will be collected and written to a special file 
in the WINDOWS directory.  Microsoft can use this information 
to make the next version of Windows even better than 
Windows 3.0.  Application vendors can also use this 
information to improve their applications.


B. How to install DrWatson
--------------------------
DrWatson must be running at the time the system error occurs 
in order to collect the internal information from the system, 
so we recommend DrWatson be started automatically each time 
you start Windows.  

To start DrWatson automatically when you start Windows, do 
the following:

1) Copy DrWatson.EXE and toolhelp.DLL to the directory in 
   which Windows is installed.

2) Open the WIN.INI file by using a text editor, such 
   as NOTEPAD.

3) Add DrWatson to the LOAD= or RUN= line.  You will find 
   these lines located at the beginning of the WIN.INI file.

4) Save the WIN.INI file.

5) Restart Windows if you edited the WIN.INI file while 
   you were running Windows.

Alternatively, you can start DrWatson as you would start 
any other Windows application, by using the Program Manager 
or File Manager.  

Once started, DrWatson appears as an icon on your desktop.


C. Using DrWatson
-----------------
While DrWatson is running, if a UAE occurs, DrWatson will
automatically create a special file in your WINDOWS directory
named DrWatson.LOG. It will also prompt you for details regarding the
circumstances of how the UAE occured.  Please include enough
information to help our developers track the problem down.  Each time
a UAE occurs, DrWatson appends new data to this file.

The DrWatson.LOG file will contain a large amount of data, most of
which is not useful unless you are a developer and are familiar with
debugging applications.  This file is a standard text file so it can
be viewed with a text editor if you wish to look at it.

At this time, DrWatson does not detect all system errors, 
so don't be alarmed if DrWatson did not record information 
after a particular system error.

D. Where to send information gathered by DrWatson
-------------------------------------------------
The Microsoft Windows development team wants to gather as 
much DrWatson data as possible.  The data will be used to 
identify and correct problems in both Windows and Windows 
applications. There are a number of ways to send this data 
to us. (We prefer to receive this data in electronic form 
since that's easier to process.)  In all cases, please 
include the name and phone number of a person we can contact 
in the event we need additional data.


- Send a disk with the DrWatson.LOG file on it to Microsoft.  
  The mailing address is:
                               Microsoft Corporation.
			       Attn:  WINDOWS BETA PROGRAM 3/2
                               One Microsoft Way
                               Redmond, WA 98052-6399

- Post the data contained in DrWatson.LOG in the "Problem 
  Reports" forum in the Microsoft Windows section on 
  Compuserve. There's an online form there to use for 
  your convenience.  This form can only be used if you are
  using a Windows based product to connect to CompuServe. 

- Print DrWatson.LOG, then FAX it to Microsoft.  Mark it 
  "Attn WINDOWS BETA PROGRAM 3/2".  The Microsoft FAX number is
  (206) 883-8101.

- Print DrWatson.LOG, then sent it Microsoft, mark "Attn 
  WINDOWS BETA PROGRAM". The mailing address is listed above.


E. Additional Technical Details on DrWatson
--------------------------------------------
This section describes some technical details about 
DrWatson, including the form of the DrWatson report and 
the various options that can be turned on and off.  This 
section is probably not of interest to most users, but 
may be valuable to developers.

Changing the Log File
   By default, the log file report is called "DrWatson.LOG".
   You can change the name and location of this file by adding 
   a "logfile=" entry to the [DrWatson] section of WIN.INI.  
   You can also redirect output to a serial or parallel device.  
   For example, to send reports to a debugging terminal, add 
   this line:

   [DrWatson]
   logfile=com1

Report Format
   Each section of a DrWatson report can be disabled by adding 
   it to the "skipinfo=" entry of the [DrWatson] section of 
   WIN.INI.  For example, to disable the module list output of 
   a report, add this line:

   [DrWatson]
   skipinfo=module

DrWatson Report Header
   The first section of the report indicates the DrWatson 
   software version (0.72), time and date of event, the fault 
   type ('Invalid  Opcode'), selector:offset of the fault, and 
   segment number and file name of the current application.

   For example:
   
   Dr. Watson 0.73 Failure Report - Fri May 17 14:11:29 1991
   MEM had a 'Exceed Segment Bounds (Read)' fault at MEM 1:1157
   $tag$   MEM     Exceed Segment Bounds (Read)    MEM 1:1157\
         repne   scasb   Fri May 17 14:11:29 1991
   
   This part of the report is mandatory; it cannot be disabled.

CPU Registers
   The 16 bit CPU registers, segment registers linear base 
   address and limit, whether the selectors are Code, Data, or 
   NULL.  This section is important, but you can disable it by 
   adding "skipinfo=regs" to the [DrWatson] section of WIN.INI.

32 Bit CPU Registers
   If the CPU is a 386 or 486, the 32 bit register contents 
   will be displayed, unless "skipinfo=32bit" is added to WIN.INI.

Disassembly
   The instructions before and after the faulting instruction 
   are disassembled.  This section can be disabled with 
   "skipinfo=disasm".  The faulting instruction is marked with 
   the (module name:symbol+offset) of that address.  This last 
   feature requires the presence of a .SYM file with debugging 
   symbols in the same directory as the associated .EXE file.

Stack Dump/Trace
   The stack dump shows stack frames, letting you know the 
   calling sequence that produced the fault.   This section 
   can be disabled with the line "skipinfo=stack".

Task List
   System tasks are all active applications.  Disable with 
   "skipinfo=tasks".

Module List
   The module list is very large, and probably not vital.  
   We recommend disabling it with "skipinfo=modules".
   It is sometimes useful to deduce the version of a driver
   or application by looking at the time/date/size of the 
   file.

System Info
   System info is miscellaneous information available.  
   Disable it with "skipinfo=info".

Other Reports
   At this point, DrWatson's GP Fault decoding logic is 
   incomplete.  We detect many possible GP faults, but 
   not all.  Examples we detect are null pointer usage, 
   writing to code segments, segment limit violations. 
   Other faults may occur that display as "Unknown".  Let
   us know if that is a problem for you.