home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c480 / 18.ddi / SAMPLES / DBWIN / DBAPI.TX_ / DBAPI.TX
Encoding:
Text File  |  1993-02-08  |  9.1 KB  |  270 lines
  1.         Debug System Features
  2.         ---------------------
  3.  
  4. This document describes some APIs and WIN.INI options that can be used with
  5. the debugging version of the Windows system.  None of the features are
  6. available in the retail version of the system: the APIs exist, but they have
  7. no effect.
  8.  
  9. The debug system has features that provide some control over the various
  10. debugging messages output by the system, and to provide some assistance for
  11. debugging out-of-memory handling in applications.
  12.  
  13.  
  14.         System debug output messages
  15.         ----------------------------
  16.  
  17. All debugging output messages and RIPs in the debugging versions of USER,
  18. GDI, and KERNEL are categorized into four types:
  19.  
  20.     DBF_TRACE   Informational message.  No error has occured, but information
  21.                 may be useful during debugging.  Example: "KERNEL: Loading
  22.                 FOO.DLL"
  23.  
  24.     DBF_WARNING A situation that may or may not be an error, depending on the
  25.                 circumstances.  Example: "KERNEL: LoadString failed"
  26.  
  27.     DBF_ERROR   An error resulting in a failed API call.  Application
  28.                 continues running.  Example: "KERNEL: Invalid local heap"
  29.  
  30.     DBF_FATAL   An error that will result in terminating the application.
  31.                 Example: "USER: Obsolete function SetDeskWallpaper called"
  32.  
  33.  
  34.         WINDEBUGINFO structure
  35.         ----------------------
  36.  
  37. The debugging system debug information is provided in a WINDEBUGINFO structure:
  38.  
  39.     typedef struct tagWINDEBUGINFO
  40.     {
  41.         UINT    flags;
  42.         DWORD   dwOptions;
  43.         DWORD   dwFilter;
  44.         char    achAllocModule[8];
  45.         DWORD   dwAllocBreak;
  46.         DWORD   dwAllocCount;
  47.     } WINDEBUGINFO;
  48.  
  49. The flags field contains a combination of the following WDI_* values that
  50. indicates which of the remaining fields in the WINDEBUGINFO structure are
  51. valid:
  52.  
  53.     WDI_OPTIONS
  54.  
  55.         dwOptions   contains a combination of DBO_* debug options (see below)
  56.                     (win.ini [Windows] DebugOptions value)
  57.  
  58.     WDI_FILTER
  59.  
  60.         dwFilter    contains a combination of DBF_* trace filter flags (see below)
  61.                     (win.ini [Windows] DebugFilter value)
  62.  
  63.     WDI_ALLOCBREAK
  64.  
  65.         achAllocModule  Alloc break module name
  66.         dwAllocBreak    Alloc break count
  67.         dwAllocCount    Current count of allocations (GetWinDebugInfo only)
  68.  
  69.  
  70.         GetWinDebugInfo API
  71.         -------------------
  72.  
  73.     BOOL WINAPI GetWinDebugInfo(WINDEBUGINFO FAR* lpwdi, UINT flags);
  74.  
  75. Queries current debugging system debug information.  lpwdi is a pointer to a
  76. WINDEBUGINFO structure to be filled in, and flags contains a combination of
  77. WDI_* values indicating which fields of the WINDEBUGINFO to fill in.
  78.  
  79. The flags field of the returned WINDEBUGINFO structure is set to the
  80. supplied flags parameter.
  81.  
  82. Returns TRUE if successful, FALSE if lpwdi is invalid, or if running under
  83. the retail version of Windows.
  84.  
  85.  
  86.         SetWinDebugInfo API
  87.         -------------------
  88.  
  89.     BOOL WINAPI SetWinDebugInfo(const WINDEBUGINFO FAR* lpwdi);
  90.  
  91. Sets current debug system information. lpwdi is a pointer to the new
  92. WINDEBUGINFO data.  The flags field of the pointed-to WINDEBUGINFO structure
  93. must contain a combination of one or more WDI_* flags indicating which debug
  94. information is to be set.
  95.  
  96. You need only initialize those fields of the WINDEBUGINFO structure that
  97. correspond to the WDI_* flags you've set in lpwdi->flags.
  98.  
  99. Debug info changes made with this API apply only until you exit the system or
  100. reboot your machine.
  101.  
  102. Returns TRUE if successful, FALSE if lpwdi or lpwdi->flags is invalid, or if
  103. running under the retail version of Windows.
  104.  
  105.  
  106.         DebugOptions/dwOptions values
  107.         -----------------------------
  108.  
  109. DBO_CHECKHEAP       0x0001
  110.  
  111.     Perform local heap checking after all LocalXXX() calls.  Replaces old
  112.     win.ini [Kernel] EnableHeapChecking=1.
  113.  
  114. DBO_CHECKFREE       0x0020
  115.  
  116.     All freed local memory will be filled with 0xFB.  All newly allocated
  117.     memory is checked to ensure it still contains 0xFBs, to ensure that
  118.     someone hasn't written into a freed memory block.  Has no effect if
  119.     DBO_CHECKHEAP is not specified.  Replaces old win.ini [Kernel] EnableFreeChecking=1
  120.  
  121. DBO_BUFFERFILL      0x0004
  122.  
  123.     Fill buffers passed to APIs with 0xF9.  Ensures that all of supplied
  124.     buffer is writeable.  Helps detect overwrite problems when supplied
  125.     buffer size is not large enough (e.g., GetWindowText).
  126.  
  127. DBO_DISABLEGPTRAPPING 0x0010
  128.  
  129.     Disable hooking of the various fault interrupt vectors.  Generally not
  130.     useful for normal app development (since you can get lots of spurious
  131.     traps related to parameter validation that aren't errors). Same as old
  132.     [Kernel] DisableGPTrapping=1
  133.  
  134. DBO_SILENT          0x8000
  135.  
  136.     No warning, error, or fatal messages are printed out unless a stack
  137.     trace and "abort, break, ignore" prompt would occur.  NOTE: We don't
  138.     recommend the use of this flag -- it can cause you to miss or
  139.     ignore many warnings that are in fact bugs that should be fixed.
  140.  
  141. DBO_TRACEBREAK      0x2000
  142.  
  143.     Break with "abort, break, ignore" on any DBF_TRACE message, but only if
  144.     it matches the DebugFilter.
  145.  
  146. DBO_WARNINGBREAK    0x1000
  147.  
  148.     Break with "abort, break, ignore" prompt if a DBF_WARNING message
  149.     occurs. (normally, DBF_WARNING messages are printed but no break
  150.     occurs).  Also applies to invalid parameter warnings.
  151.  
  152. DBO_NOERRORBREAK    0x0800
  153.  
  154.     Don't break with "abort, break, ignore" prompt if a DBF_ERROR error
  155.     occurs.  Also applies to invalid parameter errors.
  156.  
  157. DBO_NOFATALBREAK    0x0400
  158.  
  159.     Don't break with "abort, break, ignore" prompt if a DBF_FATAL error
  160.     occurs.
  161.  
  162. DBO_INT3BREAK       0x0100
  163.  
  164.     Break to debugger with simple INT 3 rather than a call to FatalExit().
  165.     Does not generate a stack backtrace.
  166.  
  167.  
  168.  
  169.         DebugFilter/dwFilter options
  170.         ----------------------------
  171.  
  172. The DebugFilter option controls the output of DBF_TRACE messages. Normally,
  173. trace messages are not output to the debug terminal.  By setting the
  174. DebugFilter win.ini variable (or by calling SetWinDebugInfo), you can enable
  175. the output of various categories of trace messages:
  176.  
  177. DBF_KERNEL          0x1000
  178.  
  179.     Enable any trace message originating from KERNEL (DBF_KRN_*).
  180.  
  181. DBF_KRN_MEMMAN      0x0001
  182.  
  183.     Enable local and global memory management related messages from KERNEL
  184.  
  185. DBF_KRN_LOADMODULE  0x0002
  186.  
  187.     Enable module loading related messages from KERNEL
  188.  
  189. DBF_KRN_SEGMENTLOAD 0x0004
  190.  
  191.     Enable segment loading related messages from KERNEL
  192.  
  193. DBF_USER            0x0800
  194.  
  195.     Enable trace messages originating from USER
  196.  
  197. DBF_GDI             0x0400
  198.  
  199.     Enable trace messages originating from GDI
  200.  
  201. DBF_MMSYSTEM        0x0040
  202.  
  203.     Enable trace messages originating from MMSYSTEM
  204.  
  205. DBF_PENWIN          0x0020
  206.  
  207.     Enable trace messages originating from PENWIN
  208.  
  209. DBF_DRIVER          0x0010
  210.  
  211.     Enable trace messages originating from device drivers
  212.  
  213. DBF_APPLICATION     0x0008
  214.  
  215.     Enable trace messages originating from an application.
  216.  
  217.  
  218.         WIN.INI Debug Options
  219.         ---------------------
  220.  
  221. You can control whether or not messages are printed, and whether you get a
  222. RIP stack backtrace and "Abort, Break, Ignore?" prompt with two special
  223. WIN.INI variables:
  224.  
  225. [Windows]
  226.     DebugOptions =<hex constant>
  227.     DebugFilter  =<hex constant>
  228.  
  229. The Get/SetWinDebugInfo APIs may also be used to set or examine the options
  230. or filter values at runtime.
  231.  
  232. Both can be set to a C style hex constant preceded by "0x".  You can't use
  233. the OR operator to combine hex constants, nor can you use symbolic names for
  234. the constants: for example, to specify DBO_CHECKHEAP and DBO_FREEFILL, you'd
  235. use "DebugOptions=0x0021" in the [Windows] section of win.ini.
  236.  
  237.  
  238.         DebugOutput() API
  239.         -----------------
  240.  
  241.     void FAR _cdecl DebugOutput(UINT flags, LPCSTR lpszFmt, ...);
  242.  
  243. The DebugOutput API is used to generate messages to the debug terminal that
  244. are affected by the system debug options and trace filter flags.
  245.  
  246. What happens with the output message depends on the value of flags and the
  247. value of the system debug options (DBO_* values).
  248.  
  249. Possible values for flags are:
  250.  
  251.     DBF_TRACE   Informational message.  No error has occured, but information
  252.                 may be useful during debugging.  Example: "KERNEL: Loading
  253.                 FOO.DLL"
  254.  
  255.     DBF_WARNING A situation that may or may not be an error, depending on the
  256.                 circumstances.  Example: "KERNEL: LoadString failed"
  257.  
  258.     DBF_ERROR   An error resulting in a failed API call.  Application
  259.                 continues running.  Example: "KERNEL: Invalid local heap"
  260.  
  261.     DBF_FATAL   An error that will result in terminating the application.
  262.                 Example: "USER: Obsolete function SetDeskWallpaper called"
  263.  
  264. The only other bit that may be used by applications is DBF_APPLICATION.
  265. Device driver DLLs may use DBF_DRIVER as well.
  266.  
  267. lpszFmt is a formatting string identical to that for the wsprintf() API.  It
  268. must be less than 160 characters long.  Additional parameters for any '%'
  269. formatting to be done may be supplied to DebugOutput() after lpszFmt.
  270.