/*************************************************************************/ TURBO DEBUGGER Turbo Debugger Readme file This file discusses the following Turbo Debugger related topics: 1. Just-In-Time debugging with TD32 2. New tools 3. Debugging throw calls 4. Debugging under Win32s 5. Corrupt session state files 6. Using TD.EXE in a Windows DOS box 7. Debugging multiple applications using TDW 8. TDW and 9. TDW and TD32s' Icons 10. Resetting an application that's running under TDW 11. Resetting a process that's attached to TD32 12. Network messages and TDW and TD32 13. Debugging DLL's via LoadLibrary under Windows 14. PENDING activity indicator 15. TDW Video Support with Resource intensive applications 16. TDW & The Integrated Debugger with PC Tools for Windows version 1.0. 17. Using TDW with Borland C++ and Borland Pascal 18. C++ exception handling 1. Just-In-Time debugging with TD32 ----------------------------------- Windows NT gives TD32 the ability to trap application exceptions, even when TD32 is not running. If your application encounters an exception, the Windows NT Program Registry can automatically launch TD32. TD32 then displays the source line where the exception occurred. To set up Just-In-Time debugging, you must specify a debugger in the Windows NT program registry. Once set up, Windows NT starts the registered debugger in the event of an application error. This mechanism lets you connect TD32 to any process that fails. Windows NT displays an Application Error dialog box when an unhandled exception occurs. The dialog box provides an OK button, which you can choose to terminate the application. However, if you register a debugger in the Windows NT program registry, the dialog box will also contain a CANCEL button. Choosing CANCEL invokes the registered debugger. To add TD32 to the program registry: 1) Run the program JITIME.EXE (located in your Borland C++ BIN directory) from Windows NT. 2) Check one of the following: TD32 -- Registers TD32.EXE as the default debugger Dr. Watson -- Registers WinSpector as the default debugger None -- Does not register any debugger Other -- Registers the debugger of your choice 3) Select Confirm Invocation if you want the Application Error dialog box to display a CANCEL button. If Confirm Invocation is not checked, Windows NT automatically starts the selected debugger when any application error occurs. 2. New tools ------------ The 16-bit linker now handles symbol tables larger than 64K in the debug information for an .EXE file. This change required a modification to the format of the debug information generated by the linker. As a result, the following tools have been updated to correspond to this TLINK modification: TDW, TDUMP, the IDE Debugger, the IDE Browser If you attempt to use any of the new tools with old executable files, they will output an error message and refuse to run. To work around this condition, relink your application using the new TLINK.EXE. However, if you use an old version of TDUMP it checks for version 4.0 and later. If TDUMP generates garbage when dumping an executable file, check the symbolic debug version number contained in the header. If it is version 4.01, make sure that you are using the correct version of TDUMP (TDUMP prints out "Version 4.1" in the banner when you run it). 3. Debugging throw calls ------------------------ If you step over or into a throw() call, the application will run until it reaches a breakpoint or program termination instead of stopping at the appropriate catch() function. To debug catch() functions, set breakpoints within the functions. 4. Debugging under Win32s ------------------------- a) To use TD32 under Windows 3.1, you must have Win32s installed. Win32s is usually installed at the same time you install BC45. If Win32s is not properly installed, TD32 will not run under Windows 3.1. To verify that Win32s is properly installed, run the Freecell application supplied with Win32s. b) Because Win32s does not run under Windows 3.0, TD32 is not compatible with Windows 3.0. c) TD32 can support dual monitor debugging under Win32s. Ensure that a monochrome adapter is installed in your machine and set the [VideoOptions] section of TDW.INI to the following setting: [VideoOptions] MONO=yes This operation can be performed automatically by using the TDWINI.EXE Video Configuration Utility and selecting the Mono option in the SVGA.DLL Settings Dialog. d) You cannot trace into Windows kernel code when you debug with TD32 under Win32s. TD32 steps over any call that steps into the kernel code. If you attempt to step into a statement that does not have debug information, and that statement calls the kernel code, TD32 will not perform a Screen Swap unless Display Options are set to Always or unless you are using the TDWGUI.DLL video driver. e) See the online text file TD_HELP.TXT for more information on using TD32 and TDW. 5. Corrupt session state files ------------------------------ If your machine locks up while you are debugging a Windows application, it is best to delete any session state files before restarting the debugger. This can be done by either deleting the session state files or by starting the debugger with the -jn command-line option. 6. Using TD.EXE in a Windows DOS box ------------------------------------ The TD.PIF file included with the BC45 installation insures the proper settings for running the DOS based Turbo Debugger (TD.EXE) in a Windows DOS box. If need be, you can create this .PIF file using Window's Pif editor, and setting the following values: Program Filename: TD.EXE Window Title: Turbo Debugger for DOS Video Memory: Text Memory Requirements: 128 -1 EMS: 0 -1 XMS Memory 0 3096 Execution: Background & Exclusive enabled ( required for Dual Monitor debugging ) Close Window on Exit. Advanced Options: Memory Options: Lock Application Memory. Display Options: Retain Video Memory. TD.EXE running in a DOS Box results in heavy use of the GDI resources. Running a high resolution video driver on some video adapters while running multiple applications can result in an inability to display High Resolution Graphics. If this is the case, close one or more of the Windows applications that are currently running. 7. Debugging multiple applications using TDW -------------------------------------------- You can debug multiple applications under TDW as follows: 1. Load the first program to be debugged into TDW. 2. Once the application is loaded, press the F3 key to display the Load Module Source or DLL Symbols dialog box. 3. In the DLL Name text entry box, enter the name of the .EXE or DLL to add. If the .EXE or DLL resides in another directory, you need to provide the full path. 4. Press . TDW adds the program name to the DLLs & Programs list box and puts the !! symbol after it. 5. Close the Load Module Source or DLL dialog box, return to the Module window, and set any necessary breakpoints in the first program. 6. Press F9 to run the first program. 7. Switch to the Windows Program Manager while the first program is running and run the second program in the usual way. 8. You see the display switch back to TDW with the CPU window showing the start-up information of the second application. Close the CPU window. 9. In the Module window, set any necessary breakpoints in the second application, then press the F9 key to run it. This method is useful for debugging DDE conversations or any other inter-program communication in the Windows environment (such as OLE 2 applications). 8. TDW and ------------------------------ When you're debugging with TDW, you can press to interrupt the application being debugged and to return control to TDW. However, the behavior in TDW 4.0 has changed slightly to accommodate the use of Microsoft's TOOLHELP.DLL. If your application is idle when you interrupt its execution, TDW posts a WM_NULL message to the application to "wake it up" so it can respond to the interrupt. Because of this, you may need to press a number of times before you get a response from the application being debugged. 9. TDW and TD32s' Icons ----------------------- The Working Directory settings in the Turbo Debugger icons have been slightly changed. To accommodate for DLLs in the working directory of the application being debugged, TDW & TD32 set the working directory to the directory used in the Command Line input box. Because of this, TDW and TD32 ignores any directories input into the Working Directory input box. You can work around this by using the -t command line option without supplying a path. For example TDW -t MYAPP.EXE In this case, the debugger uses the icon property's working directory, but it will not be able to find the applications .DLL files. 10. Resetting an application that's running under TDW ----------------------------------------------------- If you reset TDW before running the application you're debugged runs to completion, Windows will not free the applications resources. To prevent this from occurring, run the application being debugged to completion before restating it. Resources are freed by Windows only when an application has been terminated via a WM_QUIT message. 11. Resetting a process that's attached to TD32 ----------------------------------------------- TD32 cannot reset a process which you have attached to using the File|Attach command. If you reset or terminate a process that you attached to, you must start a new debugging session. 12. Network messages and TDW and TD32 ------------------------------------- Network message broadcasts must be disabled when you run either TDW or TD32. It is recommended that you disable message broadcasts from your Windows Network dialog in the Control Panel. 13. Debugging DLL's via LoadLibrary under Windows ------------------------------------------------- If you are debugging a .DLL inside TDW, and the source for the .DLL resides in a different directory, make sure that TDW's