HOWTO: Debugging 32-bit Applications under Win32s

ID: Q102430

The information in this article applies to:

SUMMARY

Debugging Win32-based applications under Windows 3.1 with Win32s can be difficult because the debugging tools are complex to use and the process is not well documented. This article presents several strategies and choices for debugging Win32s applications. Note that you can not use any 16-bit debuggers to debug a Win32s application, even if the Win32s application is thunking down to the 16-bit side using Universal Thunks.

MORE INFORMATION

Before you start to debug a Win32-based application under Win32s, make sure that it runs correctly under Windows NT. Use either the WinDbg or NTSD debugger that ships with the Win32 Software Development Kit (SDK) or the Visual C++ debugger, to track down any problems.

Once you have debugged your application under Windows NT platform, you have several choices to debug under Windows 3.1 platform with Win32s. The following is a list, in increasing order of difficulty and complexity of debugging.

1. Use the Debugging Libraries for Windows 3.1 and Win32s

First install the debugging libraries for Windows 3.1 and run Windows. Note that the D2N.BAT and N2D.BAT files shipped with Windows 3.1 Software Development Kit (SDK) or Visual C++ 16-bit Edition version 1.5x compilers provide a way to switch between the retail and debug kernels of Windows. For more information on installing the Windows 3.1 debugging libraries, please refer to the following article in the Microsoft Knowledge Base:

   ARTICLE ID: Q86263
   TITLE: Redirecting Debugging Information Under Windows 3.0, 3.1

From a Windows MS-DOS box, install the debug version of Win32s by using the SWITCH.BAT file shipped with your Win32s product. Run the W32SDBWIN.EXE application that is shipped with Win32s, and choose the appropriate Win32sDebug trace flags carefully (or set the Win32sDebug flags appropriately in the WIN.INI file). Note that selecting too many will generate more information than you may care to see and selecting too few may cause you to miss important information and warnings. Run the DBWIN debug application to capture the diagnostic trace output from Windows and Win32s debugging libraries.

Run your Win32-based application and watch for any warnings or errors that are displayed in the DBWIN application window. Note that to indicate that you have installed the debug Win32s files, the string "Debug Win32s <version number>" will be displayed at the bottom-right corner of your monitor when your Win32s application is running.

2. Use CodeView for Win32s (if available)

If you have Microsoft Visual C++ 32-bit Edition version 1.0, CodeView for Win32s (CVW32S.EXE) is an additional option. CodeView for Win32s is a user-level debugger. Remote debugging is not necessary, therefore, CodeView for Win32s does not require a second machine. CVW32S does not come with Visual C++ 2.0 and later, it is available only with Visual C++ version 1.0. You can still use CVW32S.EXE with later versions of Visual C++, if you link with /PDB:none and /INCREMENTAL:no and if you do not use new features such as templates or C++ exception handling.

3. Remotely Debug the Win32s Application Using Remote WinDBG

If the debugging libraries described in option 1 above do not help you track down the problem in your Win32-based application, you will have to debug your application under a 32-bit debugger. Unfortunately, there is no 32-bit debugger that works under Win32s except for CodeView for Win32s described above.

One option is to remotely debug your application using the remote WinDbg (WDBG32S.EXE) tool (or use the kernel debugger described below). Remote debugging method requires two machines: a Win32s machine to run the Win32- based application and the remote debugger, WDBG32S.EXE and a Windows NT machine to run the WinDbg debugger.

Note that remote debugging with WinDBG only works on Windows NT versions 3.51 and earlier, not on Windows NT version 4.0. For more information on how to use the remote WinDBG component under Win32s, please refer to the following article in the Microsoft Knowledge Base:

   ARTICLE ID: Q133061
   TITLE: How to Remotely Debug a Win32s Application

4. Remotely Debug the Win32s Application Using the Visual C++ Debugger

You can also remotely debug your Win32-based application using the Remote Debug Monitor tool (MSVCMON.EXE) that only ships with the Win32s files that are included with Visual 32-bit Edition versions 2.x and 4.x. In this method, the MSVCMON.EXE runs on the target Win32s machine while communicating with the Visual C++ debugger running on the host Windows NT machine. The Visual C++ controls the execution of the Win32-based program you are debugging on your target machine.

Note that remote debugging with the Visual C++ debugger and MSVCMON tool will only work on Visual C++ 32-bit Edition version 4.1 and earlier, but not on Visual C++ version 4.2. For more information on this method, please refer to the following article in the Microsoft Knowledge Base:

   ARTICLE ID: Q131058
   TITLE: Tips for Remote Debugging with Visual C++ 2.x and 4.0

5. Use a Low-level Debugger like WDEB386 that Ships with Windows

WDEB386 is a powerful system-level debugger that can be used for debugging Win32-based applications, but the tool and the method are complicated to use. In general, use this method under Win32s only if you have to debug a Win32-based application that implements Universal Thunks. Application-level debuggers, such as the Microsoft Visual C++ debugger, CodeView for Windows, and WinDBG, cannot trace through thunks because they consist of both 32-bit and 16-bit code.

The major drawbacks to using a system-level debugger like WDEB386.EXE are that you need to know Intel x86 assembly language, know how Intel x86 microprocessors work, and remember many debugger commands. For more information on WDWB386, please refer to the documentation of the Win16 or Win32 SDK products. In addition, the Microsoft Knowledge Base contains several articles on how to use WDEB386 efficientlon. To find them, query on the following keywords:

   wdeb386 debug tips install

REFERENCES

You can use most of the information provided in this article for debugging Win32s applications that implement Universal Thunks. For additional information on thunks, refer to the following article in the Microsoft Knowledge Base:

   TITLE: Debugging Universal Thunks
   ARTICLE ID: Q105756

For general information on debugging under Win32s, please see the "Win32s Programmer's Reference" that is included with the Win32 SDK.
Keywords          : kbprg kbtool kbWin32s kbThunk 
Version           : 1.25 1.30 1.30a 1.30c
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: October 12, 1997