DOCUMENT:Q75252 06-NOV-1999 [win16sdk] TITLE :Tips on Installing WDEB386 PRODUCT :Microsoft Windows Software Development Kit PROD/VER:WINDOWS:3.0,3.1 OPER/SYS: KEYWORDS:kb16bitonly ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1 ------------------------------------------------------------------------------- SUMMARY ======= The Microsoft Windows 80386 debugger, WDEB386, provided with the Microsoft Windows Software Development Kit (SDK) is automatically made available by the installation process; however, additional procedures may be needed to take full advantage of the features it provides. This article describes the procedures necessary to fully configure this protected-mode debugger. MORE INFORMATION ================ Hardware -------- A terminal connected to a COM port is required to use WDEB386. Unlike Microsoft CodeView for Windows (CVW), WDEB386 does not support running the debugger on a secondary monitor. Optionally, attach a second computer to a COM port on the primary computer. Running the Windows Terminal application on the second machine allows you to save and print portions of debug traces and memory dumps. Use the /C:n option (where n is 1 or 2) to specify which COM port to use with WDEB386. WDEB386 sends all output to the specified COM port. However, if the debugging version of WIN386.EXE (explained below) is run without running WDEB386, output is directed by default to COM1. Related Files ------------- Because of the similarity of the names of a number of files, there is some confusion as to what the debugger is and how to install and use it. The following list describes some files that have similar names, but completely different functions. WDEB386.EXE - This file is the actual WDEB386 debugger. The debugger is described in more detail in Chapter 5 of the "Programming Tools" manual distributed with the Windows SDK version 3.1 and in Chapter 9 of the "Tools" manual distributed with the Windows SDK version 3.0. WIN386.EXE - This executable file comprises the core of the Windows enhanced-mode operating system layer. It includes the VMM (virtual machine manager), and various standard VxDs (virtual devices). WINDEBUG.386 - This VxD may be installed in Windows running in enhanced mode (it is not included in WIN386.EXE). It provides a number of low-level services for debuggers, the most well-known being the ability to use the key combination CTRL+ALT+SYS RQ as a break request. This VxD is not necessary for WDEB386 to function properly. By default, the WDEB386.EXE file is installed in the C:\WINDEV directory, which makes it available in the MS-DOS PATH environment variable. The WINDEBUG.386 file is also installed during the SDK installation process. The file itself is copied to the Windows system directory (by default, C:\WINDEV\SYSTEM), and the line "DEVICE=WINDEBUG.386" is added to the [386enh] section in the SYSTEM.INI file. Therefore, these modules should require no special attention regarding their installation. WIN386.EXE ---------- Special care may be required concerning WIN386.EXE. The retail version of this file is part of Windows, and Windows does not run in enhanced mode without it. To take advantage of some of the more advanced and extremely useful features of WDEB386, however, the debugging version of WIN386.EXE must first be installed. This step is optional, but without it, a significant number of WDEB386 commands are not available. Most programmers are aware of the procedure to install "the debugging version of Windows." This procedure is not sufficient to install the debugging version of WIN386.EXE. The difference is that the debugging version of Windows consists of the debugging versions of the kernel, user, and GDI modules, along with their corresponding symbol files. These files are all available as part of the SDK. In contrast, the debugging version of WIN386.EXE is available only as part of the Microsoft Windows Device Driver Kit (DDK) in the 386\TOOLS\DEBUG directory. (Under Windows 3.0, the file is in the DDK VXD\TOOLS\DEBUG directory.) Therefore, even after installing the debugging version of Windows, an additional action is required to install the debugging version of WIN386.EXE. Installing WIN386.EXE is easy. Copy the retail version of WIN386.EXE to a different filename and copy the debugging version from the DDK disks into the Windows system directory. The retail version has a file size of around 500K bytes, whereas the debugging version is significantly larger. NOTE: The SYM file for the debugging version of WIN386.EXE is not available. There is a WIN386.SYM file supplied on the DDK in the same directory as the debugging version of WIN386.EXE, but this file contains the symbols for the retail version, and does not contain symbol information that matches the accompanying EXE file. Attempting to use this SYM file is worse than not using one at all because it assigns labels to addresses incorrectly. The Grabber ----------- Once the debugging version of WIN386.EXE is installed, it may also be necessary to install the debugging version of the "grabber" file. To determine if the debugging grabber is required, start the debugging Windows system in enhanced mode and attempt to start an MS-DOS session. If the attempt fails with the message "Incorrect System Version," then it is necessary to build and install the debugging version of the 386 grabber. This should be in the \386\GRABBER directory in the DDK (under Windows 3.0, this file is in the \VXD\GRABBER directory). Set the DEBUG flag in the makefile, build the grabber with the MAKE utility, and copy the grabber to the Windows system directory. You can change the name of the file, however, the "386grabber=" line in the SYSTEM.INI file must reflect the correct name. If it is possible to start an MS-DOS session on the Windows debugging system while running in enhanced mode, then this step has been completed successfully. Starting the Debugger --------------------- During the process of testing the grabber, you should see a number of messages written to the COM1 terminal by Windows. These messages indicate that the debugging version of WIN386.EXE has been correctly installed, and that the system is ready for the debugger. At this point, refer to Chapter 5 of the "Programming Tools" manual (or Chapter 9 of the "Tools" manual) for instructions on starting and using the debugger. For some tips on using the WDEB386 debugger, query on the words: wdeb386 Additional query words: 3.00 3.10 ====================================================================== Keywords : kb16bitonly Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK300 kbWinSDK310 Version : WINDOWS:3.0,3.1 ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 1999.