3.3.2 Using the System Debugging Log Application

The System Debugging Log Application (DBWIN.EXE) allows you to display messages produced by the debugging version of Windows even if you are not running a debugger and do not have a debugging terminal. DBWIN.EXE allows you to control the output of specific types of messages. It also includes a feature that forces memory-allocation errors when testing the robustness of an application.

Note:

DBWIN.EXE can provide useful debugging messages with the retail ver-sion of Windows as well. When you run DBWIN.EXE with the retail version of Windows, the Settings and Alloc Break commands are disabled in the Options menu, and you will only see a limited subset of debugging messages.

3.3.2.1 System Debugging Output

The default system debugging output goes to AUX. DBWIN.EXE can also send debugging messages to COM1 or COM2. Sending debugging output to COM1 or COM2 improves the performance of your debugging system when you have redirected system debugging output to NUL, or if DBWIN.EXE is not running.

To disable AUX as the default, add the following setting to the [Debug] section of SYSTEM.INI:

OutputTo=NUL

To disable the default kernel output and to send output to COM1 or COM2, set the MS-DOS COM port baud rates to match the baud rates of your debugging terminal by using the MS-DOS mode command. To ensure that the settings are always correct, use the mode command in your AUTOEXEC.BAT file.

You can log messages to the system debugging window, to a monochrome screen, or to the COM1 or COM2 devices. The default destination for messages is to a window.

You can choose different destinations for debugging messages from the Options menu. These settings stay in effect the next time you run DBWIN.EXE.

3.3.2.2 System Debug Options Dialog Box

When you choose the Settings command on the Options menu, a System Debug Options dialog box appears. This dialog box allows you to control the output of debugging messages produced by the debugging version of Windows.

The System Debug Options dialog box works only when you are running the debugging version of Windows. There are three groups of check boxes, described as follows:

Break Options

Control whether and how a message will cause a break and stack trace to the debugger.

Debug Options

Control the kind of debugging features that are enabled in the system.

Trace Options

Control whether or not certain kinds of informational messages are produced.

The check boxes for Break Options and Trace Options are self-explanatory. The following list explains the check boxes for the Debug Options:

Option Description

Validate Heap Checks the consistency of global and local heaps before every call to a memory-management function. This option affects the global heap only when it is one of the default startup settings (that is, when it is saved by choosing the Save Settings command on the File menu). This option affects local heaps only if it is set before the application is started.
Check Free Blocks Ensures that freed local blocks are not written into. The value 0xFB is written into free blocks, and when the heap is validated, a check is performed to ensure that the blocks are still filled with this value. This option works only with local heaps. This option must be used with the Validate Heap option.
Buffer Fill Fills buffers that are passed to Windows functions with the value 0xF9. This option ensures that all of the supplied buffer is writable and helps detect overwrite problems that can occur when the buffer is too small.
Break with INT 3 Breaks to the debugger with an int 3 instruction, instead of a fatal exit. This option does not display a stack trace.
Don't trap faults Prevents the system from hooking GP and stack overflow faults. (Many faults that result from choosing this option would normally be handled by the system. Choosing this option results in faults that would not occur otherwise.)

3.3.2.3 Alloc Break Command

The Alloc Break command on the Options menu ensures that an application deals properly with out-of-memory conditions. This command displays a dialog box into which you can enter the module name of your application and the number of memory allocations you want to succeed before subsequent allocations fail.

The system counts each global or local memory allocation performed by your application. When the number of allocations reaches the allocation break count, that allocation and all subsequent allocations fail. Because memory allocations made by the system fail once the break count is reached, calls to certain functions (such as CreateWindow, CreateBrush, and SelectObject) fail as well. Only allocations made within the context of the application you specify are affected by the allocation break count.

The module name is limited to 8 characters. In some cases the module name may be different from the filename; the module name is specified in the module-definition (.DEF) file for the application. You cannot specify the module name of a DLL.

If you set the break count to zero, no allocation break is set, but the system counts allocations made by the specified application. You can choose the Show Count button to display the current allocation count.

You can set an allocation break before an application is run. The allocation count is then set to zero and allocations are counted as soon as the application starts. If you run more than one instance of an application, the allocation break applies only to the most recent instance.

The allocation count is also reset to zero when you choose the Set button or the Inc & Set button. You can set an allocation break before performing an operation to ensure that your application handles the problem effectively. Then you can choose Inc & Set and repeat the operation to ensure that the next allocation failure is also handled properly.