home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / w3_diag / drwatson.arj / DRWATSON.TXT < prev    next >
Encoding:
Text File  |  1991-06-07  |  7.6 KB  |  204 lines
  1. DrWatson.TXT
  2.  
  3. This document contains information on:
  4.  
  5.    A. What is DrWatson?
  6.    B. How to install DrWatson
  7.    C. Using DrWatson
  8.    D. Where to send information gathered by DrWatson
  9.    E. Additional details on DrWatson
  10.  
  11.  
  12. A. What is DrWatson?
  13. --------------------
  14. DrWatson is a diagnostic tool designed to provide developers 
  15. with detailed information on the internal state of Windows 
  16. when a system error such as an unrecoverable application 
  17. error (UAE) occurs.  
  18.  
  19. DrWatson must be running at the time a UAE occurs in order 
  20. to extract the required internal information from the system.
  21. DrWatson takes very little memory and does not affect 
  22. performance, so we encourage you to install DrWatson if a UAE 
  23. has occurred before.  
  24.  
  25. After DrWatson is installed, if another UAE occurs, valuable 
  26. information will be collected and written to a special file 
  27. in the WINDOWS directory.  Microsoft can use this information 
  28. to make the next version of Windows even better than 
  29. Windows 3.0.  Application vendors can also use this 
  30. information to improve their applications.
  31.  
  32.  
  33. B. How to install DrWatson
  34. --------------------------
  35. DrWatson must be running at the time the system error occurs 
  36. in order to collect the internal information from the system, 
  37. so we recommend DrWatson be started automatically each time 
  38. you start Windows.  
  39.  
  40. To start DrWatson automatically when you start Windows, do 
  41. the following:
  42.  
  43. 1) Copy DrWatson.EXE and toolhelp.DLL to the directory in 
  44.    which Windows is installed.
  45.  
  46. 2) Open the WIN.INI file by using a text editor, such 
  47.    as NOTEPAD.
  48.  
  49. 3) Add DrWatson to the LOAD= or RUN= line.  You will find 
  50.    these lines located at the beginning of the WIN.INI file.
  51.  
  52. 4) Save the WIN.INI file.
  53.  
  54. 5) Restart Windows if you edited the WIN.INI file while 
  55.    you were running Windows.
  56.  
  57. Alternatively, you can start DrWatson as you would start 
  58. any other Windows application, by using the Program Manager 
  59. or File Manager.  
  60.  
  61. Once started, DrWatson appears as an icon on your desktop.
  62.  
  63.  
  64. C. Using DrWatson
  65. -----------------
  66. While DrWatson is running, if a UAE occurs, DrWatson will
  67. automatically create a special file in your WINDOWS directory
  68. named DrWatson.LOG. It will also prompt you for details regarding the
  69. circumstances of how the UAE occured.  Please include enough
  70. information to help our developers track the problem down.  Each time
  71. a UAE occurs, DrWatson appends new data to this file.
  72.  
  73. The DrWatson.LOG file will contain a large amount of data, most of
  74. which is not useful unless you are a developer and are familiar with
  75. debugging applications.  This file is a standard text file so it can
  76. be viewed with a text editor if you wish to look at it.
  77.  
  78. At this time, DrWatson does not detect all system errors, 
  79. so don't be alarmed if DrWatson did not record information 
  80. after a particular system error.
  81.  
  82. D. Where to send information gathered by DrWatson
  83. -------------------------------------------------
  84. The Microsoft Windows development team wants to gather as 
  85. much DrWatson data as possible.  The data will be used to 
  86. identify and correct problems in both Windows and Windows 
  87. applications. There are a number of ways to send this data 
  88. to us. (We prefer to receive this data in electronic form 
  89. since that's easier to process.)  In all cases, please 
  90. include the name and phone number of a person we can contact 
  91. in the event we need additional data.
  92.  
  93. - Send the information contained in DrWatson.LOG via email 
  94.   to WINBETA at Microsoft. 
  95.  
  96. - Send a disk with the DrWatson.LOG file on it to Microsoft.  
  97.   The mailing address is:
  98.                                Microsoft Corporation.
  99.                    Attn:  WINDOWS BETA PROGRAM 3/2
  100.                                One Microsoft Way
  101.                                Redmond, WA 98052-6399
  102.  
  103. - Post the data contained in DrWatson.LOG in the "Microsoft
  104.   Suggestion/Problem Report" form in the main Microsoft Connection
  105.   area (MSCON) on Compuserve. There's an online form there to use for 
  106.   your convenience.  
  107.  
  108. - Print DrWatson.LOG, then FAX it to Microsoft.  Mark it 
  109.   "Attn WINDOWS BETA PROGRAM 3/2".  The Microsoft FAX number is
  110.   (206) 883-8101.
  111.  
  112. - Print DrWatson.LOG, then sent it Microsoft, mark "Attn 
  113.   WINDOWS BETA PROGRAM". The mailing address is listed above.
  114.  
  115.  
  116. E. Additional Technical Details on DrWatson
  117. --------------------------------------------
  118. This section describes some technical details about 
  119. DrWatson, including the form of the DrWatson report and 
  120. the various options that can be turned on and off.  This 
  121. section is probably not of interest to most users, but 
  122. may be valuable to developers.
  123.  
  124. Changing the Log File
  125.    By default, the log file report is called "DrWatson.LOG".
  126.    You can change the name and location of this file by adding 
  127.    a "logfile=" entry to the [DrWatson] section of WIN.INI.  
  128.    You can also redirect output to a serial or parallel device.  
  129.    For example, to send reports to a debugging terminal, add 
  130.    this line:
  131.  
  132.    [DrWatson]
  133.    logfile=com1
  134.  
  135. Report Format
  136.    Each section of a DrWatson report can be disabled by adding 
  137.    it to the "skipinfo=" entry of the [DrWatson] section of 
  138.    WIN.INI.  For example, to disable the module list output of 
  139.    a report, add this line:
  140.  
  141.    [DrWatson]
  142.    skipinfo=module
  143.  
  144. DrWatson Report Header
  145.    The first section of the report indicates the DrWatson 
  146.    software version (0.72), time and date of event, the fault 
  147.    type ('Invalid  Opcode'), selector:offset of the fault, and 
  148.    segment number and file name of the current application.
  149.  
  150.    For example:
  151.    
  152.    Dr. Watson 0.73 Failure Report - Fri May 17 14:11:29 1991
  153.    MEM had a 'Exceed Segment Bounds (Read)' fault at MEM 1:1157
  154.    $tag$   MEM     Exceed Segment Bounds (Read)    MEM 1:1157\
  155.          repne   scasb   Fri May 17 14:11:29 1991
  156.    
  157.    This part of the report is mandatory; it cannot be disabled.
  158.  
  159. CPU Registers
  160.    The 16 bit CPU registers, segment registers linear base 
  161.    address and limit, whether the selectors are Code, Data, or 
  162.    NULL.  This section is important, but you can disable it by 
  163.    adding "skipinfo=regs" to the [DrWatson] section of WIN.INI.
  164.  
  165. 32 Bit CPU Registers
  166.    If the CPU is a 386 or 486, the 32 bit register contents 
  167.    will be displayed, unless "skipinfo=32bit" is added to WIN.INI.
  168.  
  169. Disassembly
  170.    The instructions before and after the faulting instruction 
  171.    are disassembled.  This section can be disabled with 
  172.    "skipinfo=disasm".  The faulting instruction is marked with 
  173.    the (module name:symbol+offset) of that address.  This last 
  174.    feature requires the presence of a .SYM file with debugging 
  175.    symbols in the same directory as the associated .EXE file.
  176.  
  177. Stack Dump/Trace
  178.    The stack dump shows stack frames, letting you know the 
  179.    calling sequence that produced the fault.   This section 
  180.    can be disabled with the line "skipinfo=stack".
  181.  
  182. Task List
  183.    System tasks are all active applications.  Disable with 
  184.    "skipinfo=tasks".
  185.  
  186. Module List
  187.    The module list is very large, and probably not vital.  
  188.    We recommend disabling it with "skipinfo=modules".
  189.    It is sometimes useful to deduce the version of a driver
  190.    or application by looking at the time/date/size of the 
  191.    file.
  192.  
  193. System Info
  194.    System info is miscellaneous information available.  
  195.    Disable it with "skipinfo=info".
  196.  
  197. Other Reports
  198.    At this point, DrWatson's GP Fault decoding logic is 
  199.    incomplete.  We detect many possible GP faults, but 
  200.    not all.  Examples we detect are null pointer usage, 
  201.    writing to code segments, segment limit violations. 
  202.    Other faults may occur that display as "Unknown".  Let
  203.    us know if that is a problem for you.
  204.