Redirecting Debugging Information Under Windows 3.0, 3.1

• Microsoft Windows Software Development Kit (SDK) for Windows versions 3.1 and 3.0

SUMMARY

Each new application for the Microsoft Windows environment should be tested under the Windows debugging kernel. When an application performs an illegal or potentially harmful operation, the debugging kernel traps the error and provides a descriptive message about the source of the problem. By default, the debugging kernel sends its messages to the AUX device (which maps to the COM1 port). This article describes how to redirect output from the debugging kernel under Windows versions 3.0 and 3.1.

MORE INFORMATION

As noted above, in the Windows 3.0 and 3.1 environments, the debugging kernel sends its data to the AUX device, which (in general) maps to the COM1 port. One method to display this debugging information is to connect a serial communications terminal or another computer running a terminal emulation program to the COM1 port. Before running Windows, set the port's parameters appropriately through the MS-DOS MODE command. Placing the MODE command in the AUTOEXEC.BAT file automatically sets the port's parameters.

When the debugging kernel starts, if no device is connected to COM1, the kernel displays a "Cannot write to device AUX" message box. If the COM1 port is dedicated to another use and cannot be connected to a serial terminal, you can configure the debug kernel to send its messages elsewhere. The remainder of this article explains the procedures required.

Moreover, if you do not have a serial terminal connected to the COM1 port, then before starting the debug version of Windows, ensure that the following lines are added to the [Windows] section of the WIN.INI file:

   DebugOptions=0x0000
   DebugFilter=0x0000
   DebugTaskFilter=       ;leave it blank

   [Debug]
   OutputTo=NUL

The setting for the DebugOptions entry corresponds to the values for the dwOptions member of the WINDEBUGINFO structure in the Windows SDK. The setting for the DebugFilter entry corresponds to the values for the dwFilter member of WINDEBUGINFO. To determine the proper hexadecimal value for a setting, add the values of the options to be set. For example, to specify DBO_CHECKHEAP and DBO_FREEFILL, the setting for the DebugOptions entry would be 0x0021 (0x0001 + 0x0020). For information about the possible values for these options and a full description of the WINDEBUGINFO structure, see the Microsoft Windows Programmers Reference, Volume 3.

Windows 3.1

In the Windows 3.1 environment, the debugging terminal is not required. The Windows 3.1 debugging kernel provides two methods to redirect debugging information:

1. Redirect the debugging information from COM1 into a file by specifying the following in the [Debug] section of the SYSTEM.INI file:

         OutputTo = <filename>
   

   To disable sending debug messages to AUX, specify the following in the SYSTEM.INI file:

         OutputTo = NUL
   

2. Version 3.1 of the Microsoft Windows Software Development Kit (SDK) includes the DBWIN sample program in the advanced samples directory (by default, C:\WINDEV\SAMPLES). DBWIN provides a good interface and some useful features to debug an application in the Windows environment. DBWIN can disable sending debugging messages to AUX or redirect the debugging messages to any of the following:

       - The COM1 port
       - The COM2 port
       - A window on the primary display
       - A secondary monochrome monitor
   

   These redirection options are listed on the Options menu. When using DBWIN, choose Settings from the Options menu and verify that the Break On Traces option is not selected. For more information on DBWIN, see the DBAPI.TXT and DBWIN.TXT files in the DBWIN directory, Appendix C of the "Microsoft Windows Software Development Kit: Programming Tools" version 3.1 manual, and the online help files.

Windows 3.0

Windows 3.0 does not provide a built-in method to redirect debugging output; external measures are required.

This article outlines two methods to redirect output under Windows 3.0. The first is through the WINAUX.SYS device driver that redirects debugging output into a window on the main display, similar to the DBWIN application discussed above. The second is through the OX.SYS device driver that redirects debugging output to a secondary monochrome adapter connected to the system.

The WINAUX.SYS device driver is the method of choice.

Download WINAUX.EXE, a self-extracting file, from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download WINAUX.EXE (size: 29822 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the \SOFTLIB\MSLFILES directory
        Get WINAUX.EXE (size: 29822 bytes) 
  

   DEVICE=WINAUX.SYS

The OX.SYS file and its source code is available in the Software Library. If necessary, you can modify the OX source code to direct debugging output to another device such as LPT1, COM2, and so on.

Download OX.EXE, a self-extracting file, from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download OX.EXE (size: 19411 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the \SOFTLIB\MSLFILES directory
        Get OX.EXE (size: 19411 bytes) 
  

   DEVICE=OX.SYS