/*************************************************************************/
                             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 <Ctrl><Alt><SysReq>
  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 <Enter>. 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 <Ctrl><Alt><SysReq>
------------------------------
When you're debugging with TDW, you can press <Ctrl><Alt><SysReq> 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 <Ctrl><Alt><SysReq> 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 <Option><Path to Source>
command includes the directory where the .DLL source is located.


14. PENDING activity indicator
------------------------------
The PENDING activity indicator was omitted from page 52 of the Turbo Debugger
User's Guide. It is documented in the section "Controlling Program Execution"
on page 28.


15. TDW Video Support with Resource intensive applications
----------------------------------------------------------
SVGA.DLL performs a mode switch using the Death & Resurrection DDK API calls.
In applications that use resources intensely ( e.g. BCW 4.5 ) the Death &
Resurrection calls fail inside certain Windows Display Drivers. This is a
problem with the Windows display driver. If you encounter such behavior,
change the TDW.INI settings using TDWINI.EXE for SVGA.DLL to:
    Use Documented Mode Switch
then restart the GDI when Turbo Debugger exits.

As an alternative, change your Video .DLL to TDWGUI.DLL.


16. TDW & The Integrated Debugger with PC Tools for Windows version 1.0.
------------------------------------------------------------------------
TDW & the Integrated Debugger are not 100% compatible with PC Tools for
Windows 1.0. The known problems inside TDW are resetting & reloading
applications causing random General Protection Faults.

When debugging an application with the Integrated Debugger, random General
Protection Faults occur which do not occur when you debug without PC Tools
for Windows loaded. Central Point has acknowledged this incompatibility.


17. Using TDW with Borland C++ and Borland Pascal
-------------------------------------------------
If you have both Borland C++ and Borland Pascal installed on your system:

  You cannot run both versions of TDW simultaneously. TDW 3.1 must be
  run to debug your Borland Pascal programs, and TDW 4.0 must be run
  to debug Borland C++ programs.

  Make sure that old copies of TDW.INI are removed from your system
  (run the TDWINI.EXE utility to clean up old TDW.INI files).

  If you wish to use TDWGUI.DLL with TDW version 3.1 you need to
  manually add UseTimer=Yes to the VideoOptions section of TDW.INI.
  Note that this option should not be set when using TDW version 4.0.
  This means that you would need to hand change your TDW.INI file each
  time you switched between versions of TDW. For this reason, we
  recommend the non-windowed video DLLs (such as SVGA.DLL) for
  customers who debug both BP and BC applications.

  Check the [386Enh] section in your Windows SYSTEM.INI file for
   multiple entries for the device TDDEBUG.386. Remove duplicate
  entries of TDDEBUG.386 so that only the version from Borland C++
  is loaded. On disk, you may also want to rename or remove the BP7
  versions of TDDEBUG.386 and TDWIN.DLL to avoid their accidental loading.
  You must restart Windows after making changes to system.ini.


 18. C++ exception handling
---------------------------
Turbo Debugger has the ability to step into the catch function after a
C++ exception is generated. If an exception is generated:

 1) Turbo Debugger notices the exception and pauses the program with the
    *cursor* (not the IP) placed on the throw that is responsible for
    the exception. In this way, Turbo Debugger notifies the user of the
    location where the exception was generated.

 2) Press <F8> to have the debugger step into the catch function, or
    press <F9> to continue running the program if you are not interested
    in this particular C++ exception.

/***************************** END OF FILE *******************************/

