HOWTO: Remotely Debug a Win32s Application using WinDBG

• Microsoft Win32s, versions 1.25, 1.3, 1.30a, 1.3c

SUMMARY

Debugging Win32-based applications under Windows 3.1 with Win32s can be difficult because the debugging tools are complex and the procedure is not well documented. There are several choices in debugging a Win32s application that are listed in the following Knowledge Base article:

   ARTICLE ID: Q102430
   TITLE     : HOWTO: Debug 32-bit Applications under Win32s

Note that this method (remote debugging a Win32s application using WinDBG) only works with WinDBG that is included in the Win32 Software Development Kit (SDK) shipped with Windows NT version 3.51. The Win32 SDK that is shipped with Windows NT version 4.0 does not support remote debugging a Win32s application using WinDBG. This version of the SDK does not include the required Win32s components of WinDBG for remote debugging. In addition, future versions of the Win32 SDK will also not contain these components required for remotely debugging a Win32s application.

You can also remotely debug your Win32s application using the Remote Debug Monitor tool (Msvcmon.exe) that is only shipped with the Win32s files that are included with Visual 32-bit Edition versions 2.x, 4.0, and 4.1. For more information on this method, please refer to the following Knowledge Base article:

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

MORE INFORMATION

Preliminary Issues

First, before you start to remotely debug a Win32-based application under Win32s, make sure that it runs correctly under Windows NT and track down any problems using either the WinDbg or NTSD debugger that ships with the Win32 Software Development Kit (SDK) or the Visual C++ debugger. In addition, explore some of the other choices of debugging the Win32s application as described in the article referenced above. If none of these methods work for you, then you should remotely debug your application using the method described here.

Second, you must use a null modem (3-wire) cable to create a valid connection between the two machines (the host Windows NT machine and the target or remote Win32s machine) and make sure that the cable is set up exactly as specified in the Win32s Programmer's Reference.

Third, you must make sure you have a valid connection between the two machines you are using. One way you can test this functionality is by using the terminal emulator found in the Accessories group. If you can send text over the serial line then you have a valid connection. If you do not have a valid connection, make sure the correct COM ports are selected, and verify that the baud speed is the same on both machines.

Finally, for debugging with WinDBG, your Win32-based application and/or DLL must be built with certain compiler and linker switches so that debugging information is included. These switches can be found in the $(cdebug) and $(ldebug) macros, respectively, which are defined in Ntwin32.mak. It is also important to disable optimization with -Od or locals will not be available in the locals window and line numbers may not match the source. For more information on debugging with WinDBG, please refer to the following Knowledge Base article:

   ARTICLE ID: Q97908
   TITLE: Debugging DLLs Using WinDbg

Procedure for Remote Debugging

Note that remote debugging with WinDBG only works for serial transports. The following steps outline the procedure:

1. Make sure Win32s is installed correctly on the Windows 3.x machine.

2. Make sure you have the following files in your Window 3.x System subdirectory:

         Wdbg32s.exe
         Dm32s.dll
         Tlser32s.dll
   

   You can copy these files from the Microsoft Win32 Software Development Kit (SDK) or from your Windows NT machine if you have installed Windbg.exe from the Win32 SDK. Note the "s" in Tlser32s.dll and Dm32s.dll indicating that these files are for Win32s only (as opposed to Tlser32.dll and Dm32.dll which are for Windows NT only).

3. Place your Win32 executable with the debug information in a suitable directory on the Windows 3.x machine. Note the path to the executable because this information is used in step 4.

4. On your Windows NT machine, start the WinDBG debugger and click Open on the Program menu. Click New in the dialog box, and DO NOT BROWSE FOR THE FILE. In the Edit box, type the path that you noted in step 3. Windbg.exe needs the path of your remote executable because Windbg.exe looks for a remote executable.

5. Select the appropriate serial connection (for example, ser96 means use COM1 at 9600 baud). You can modify these parameters by clicking the Change button located at the bottom right of the dialog box. Refer to the documentation on Windbg debugger for more information on modifying the default COM port and baud rates.

6. Change the default transport DLL for WinDBG (typically, Tlser.dll) to Tlser32.dll since you are remotely debugging a Win32s application. To do this, click Change with the Transport Layer edit box highlighted. An edit box labeled PATH with the name of the DLL is displayed. Verify that this box contains Tlser32.dll.

7. WinDbg on Windows NT supports XON/XOFF (software) flow control. To enable XON/XOFF, you must specify the XON flag in the serial transport parameters on both WinDbg and remote WinDbg. Make sure to add XON to the end of the Parameters line: "COM1:19200 XON" in the Change dialog box above.

8. On the Windows 3.11 machine, start the remote WinDBG tool, Wdbg32s.exe and make sure the connection settings are the same as on the Windows NT side. Select Options to bring up the Transport dynamic-link library (DLL) dialog box and make sure that the transport DLL is Tlser32s.dll. Then choose the serial transport and other parameters. Also, make sure to place the XON flag at the end of the Parameters box ("COM1:19200 XON") similar to WinDBG on the Windows NT machine.

9. Click Connect on the remote WinDBG tool on the Widows 3.11 machine. The Connect option should be dimmed and the Disconnect menu option should be highlighted.

10. On your Windows NT machine, click Go on the Run menu. You can now start remotely debugging your Win32s application.