/**********************************************************************************/
TURBO DEBUGGER
Turbo Debugger Readme file

This file discusses the following Turbo Debugger related topics:

1. New tools
2. Running TD32 and Windows NT
3. Corrupt session state files
4. Using TD.EXE in a Windows DOS box
5. Debugging multiple applications using TDW
6. Interrupting your program execution
7. TDW and TD32 icons
8. Network messages and TDW and TD32
9. TDW video support with resource intensive applications
10. Using TDW with Borland C++ and Delphi
11. TDW.INI
12. TDW hardware debugging
13. Running TDW under Windows for Workgroups
14. Running TDW under Windows 95
15. Video support
16. Debugging window messages
17. Debugging Delphi applications
18. WREMOTE under Windows NT
19. Debugging under Win32s
20. Answers to common questions


1. 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.


2. Running TD32 and Windows NT
-------------------------------
If you are running Windows NT 3.51 and are using TD32 to debug an application
that resides on a Novell network, you must have the Windows NT 3.51 ServicePack
3 (or higher) installed.


3. Corrupt session state files
------------------------------
If your machine locks up while you are debugging a Windows application,
your configuration files are likely to become corrupt. This can cause Turbo
Debugger to hang on startup. In this case, it is advisable to either start
the debugger with the -jn command-line option or delete the following files:

For TD: TDCONFIG.TD
***.TR

For TDW: TDCONFIG.TDW
***.TRW

For TD32: TDCONFIG.TD2
***.TR2

Where *** equals your application's name.

These files will most likely be found in either the working directory, the
\BorlandC\Bin directory or in the \Windows directory.


4. 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.


5. 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).


6. Interrupting your program execution
--------------------------------------
The system interrupt keystrokes no longer work in in Turbo Debugger versions
4.0 and later. In version 4.0, Turbo Debugger changed the debugging API from
WINDEBUG to TOOLHELP, as was recommended by Microsoft. Unfortunately, the
system interrupt keys are not documented in Microsoft's TOOLHELP API.

Here are several methods to interrupt Turbo Debugger while your application
runs:

1) If you have Turbo Debugger 3.1, you can use the TDDEBUG.386 that was
shipped with that version of the software. Set the driver in the [386 Enh]
section of your SYSTEM.INI, and use the TDWIN.DLL (shipped with BC++ 3.1)
as your DEBUGGERDLL in your TDW.INI.

2) Pick a certain key on your keyboard (for example, ~) to use as the
system interrupt key. In the message handler for WM_CHAR, trap the message
for that key being pressed and execute an "asm int 3" instruction. This
causes the keystroke to issue a "breakpoint," which pauses the execution of
your application.

While this method works for all versions of Turbo Debugger, it has the
disadvantage that you must modify your application. If you use this method,
make sure to remove the added keystroke handler before you distribute your
final application.

3) If you are using Windows NT to debug a 32-bit application with TD32,
press F12 to interrupt your program execution.

4) If you are using Windows 95 to debug a 32-bit application with TD32:
a) Place the debugger in asyncronous mode by setting Run|Wait For Child
to "No."
b) When your programis running, set a breakpoint on a line of code that
will execute.
c) When the Status Indicator on the Turbo Debugger menu bar reads
"PENDING," choose Run|Next Pending Status.
This places you back in the debugger where you can continue debugging.


7. TDW and TD32 icons
---------------------
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 ignore 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

causes the debugger to use the icon property's working directory, but
it will not be able to find the applications .DLL files.


8. 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.


9. 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 ) 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.


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

* 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).

* 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 you load only the latest version.
On disk, you may also want to rename or remove any earlier versions
of TDDEBUG.386 and TDWIN.DLL to avoid their accidental loading.
You must restart Windows after making changes to SYSTEM.INI.


11. TDW.INI
-----------
You must have a single copy of TDW.INI located on your system, and
it must be located in your main Windows directory (usually "\WINDOWS").
Be sure to delete any extra copies of TDW.INI that you might have on
your system.

If you use a dual-boot system (for example, if you boot up into either
Windows 3.1 or Windows NT on a single system), you must reinstall the
correct video driver with TDWINI.EXE each time you change the operating
system you boot into; you cannot configure a different TDW.INI file
for each operating system you boot into.

By default, TDW.INI contains the following text:

[TurboDebugger]
VideoDll = \SVGA.DLL
debuggerDll = \TDWINTH.DLL

[VideoOptions]


12. TDW hardware debugging
--------------------------
In order to support hardware debugging in TDW, you need to load
the device driver TDDEBUG.386. Edit your SYSTEM.INI file in the \WINDOWS
directory and add the following statement to the [386enh] section:

device=\TDDEBUG.386

Make sure that you comment out the line that loads the Windows driver
WINDEBUG.386 with a semicolon. For example:

;c:\windows\windebug.386


13. Running TDW under Windows for Workgroups
--------------------------------------------
If you use Windows for Workgroups 3.11, you must use TDWINTH.DLL when
you debug with TDW. Be sure the DebuggerDll setting in your
TDW.INI file explicitly points to TDWINTH.DLL. For example:

debuggerDll=\TDWINTH.DLL


14. Running TDW under Windows 95
--------------------------------
Because TDW.EXE is a hard-mode debugger, it takes control of the WIN16 subsystem
on Windows 95. Pressing to attempt to change tasks under
Windows 95 can leave the debugger in an unstable state. To change tasks under
Windows 95, you must exit TDW.EXE.


15. Video support
-----------------
Turbo Debugger requires that you use the correct Windows video driver
for your video card. For example, if you have a TSENG card, make sure
that you are using the TSENG Windows video driver (the generic VGA
video driver does not work correctly with this video card).

To find out what type of video card you have installed in your
machine, type MSD at the DOS prompt. Use the TDWINI.EXE
utility to set up your video driver.

SVGA.DLL supports most video card configurations, provided that you
are using the correct Windows video drivers. Use the Turbo Debugger Video
Configuration utility (TDWINI.EXE) to determine the correct Video Support
for your adapter.

There are known conflicts between TDW's SVGA video DLL and some video drivers. To
solve the problem, reconfigure TDW to use TDWGUI.DLL or reconfigure Windows to use a standard VGA or SVGA driver.


Screen not being repainted
- - - - - - - - - - - - - -
Ensure that the "ForceRepaint" flag is set to "Yes" in the
VideoOptions section of TDW.INI:

[VideoOptions]
ForceRepaint=Yes

This can be done through the Turbo Debugger Video Configuration
utility (TDWINI.EXE).


16. Debugging window messages
-----------------------------
1) If you set up View|Windows Messages to display messages for
more than one procedure or handle or both, do not log all
messages. Instead, log specific messages for each procedure or
handle. If you log all messages, the system might hang, in
which case you will have to reboot to continue. This behavior
is due to the large number of messages being transferred
between Windows and Turbo Debugger.

2) When setting a break on the Mouse class of messages, note that
a "mouse down" message must be followed by a "mouse up" message
before the keyboard will become active again. When you return
to the application, you might have to press the mouse button
several times (or press the key) to get Windows to receive a
"mouse up" message. You'll know Windows has received the message
when you see it in the bottom pane of the Windows Message window
after the program breaks.


17. Debugging Delphi applications
---------------------------------
Stepping into Delphi's dynamic methods
- - - - - - - - - - - - - - - - - - - -
By default, single-stepping through a program skips over dynamic methods; Turbo
Debugger does not step into them. This is because TDW normally determines all the
single-step points when the program is first loaded, at which time dynamic methods
are not yet defined.

However, by following these steps, you can change the way TDW determines stop
points, which makes it possible to step into dynamic methods:
1) Choose View|Execution History.

2) Invoke the Execution History SpeedMenu, either by clicking the right mouse
button or by pressing Alt+F10.

3) Toggle the "Full history" option from No to Yes.

You should now be able to step into dynamic methods created by Delphi.


WREMOTE and Delphi exception handling
- - - - - - - - - - - - - - - - - - - - -
Exception handling in a Delphi application is not visible from WREMOTE. To debug
Delphi exception handling code, you must use Turbo Debugger locally.


18. WREMOTE under Windows NT
----------------------------
There is a new command line switch you can use with TDW and WREMOTE which
facilitates remote network debugging under NT. Use the -raX command-line switch to
tell TDW or WREMOTE which LAN adapter port is to be used by NetBios. The adapter
number must match the following registry key:

HKEY_LOCAL_MACHINE
Software
Microsoft
RPC
NetBios
ncacn_nb_nb0: xxx

For example, if the value of the ncacn_nb_nb key is 0x2, then you must use
command-line switch -ra2. The default value for the -ra switch is 0 (zero).

Remember: Network remote debugging is only supported if you have installed the
NetBios network protocol.


19. Debugging under Win32s
--------------------------
TD32 no longer supports Win32s debugging.


20. Answers to common questions
-------------------------------
Following is a list of the most commonly asked questions about Turbo debugger:

1) Are there any syntactic or parsing differences between Turbo
Debugger's C expression evaluation and Turbo C++ for Windows'?

You can't pass constant-string arguments when evaluating
functions.

OK: myfunc(123) myfunc(string_variable)

BAD: myfunc("constant")

2) What should I be aware of when I am debugging multilanguage
programs with Turbo Debugger?

Turbo Debugger's default source language is "Source," which
means it chooses the expression language based on the current
source module. This can cause some confusion if your program
has source modules written in different languages (like C
and assembler). Since you are actually entering a language
expression any time Turbo Debugger prompts you for a value
or an address, this can cause some unexpected results:

a. Even if you are in a CPU window or a Dump window, you
must still enter addresses in the source language,
despite the fact that the window is displaying in hex.
For example, to display the contents of memory address
1234:5678, you must type one of the following
expressions, depending on your current source language:

C 0x1234:0x5678
Pascal $1234:$5678
Assembler 1234H:5678H

b. When your current language is assembler, you must be
careful when entering hex numbers, since they are
interpreted EXACTLY as they would be in an assembler
source file. This means that if you want to enter a
number that starts with one of the hex digits A - F, you
must first precede the letter with a 0 so Turbo Debugger
knows you are entering a number. Likewise, if your number
ends in B or D (indicating a binary or decimal number), you
must add an H to indicate that you really want a hex number:

OK: 0aaaa 123dh 89abh

BAD: aaaa 123d 89ab

3) Why does the text "Cannot be changed" come up when I do an
assignment in the Data/Evaluate/Modify "New value" pane?

If you use the Data/Evaluate/Modify command (Ctrl-F4) to
change a variable by direct assignment, the "New value" pane
will say "Cannot be changed." This doesn't mean the
assignment didn't take effect. What it does mean is that the
assignment expression as a whole is not a memory-referencing
expression whose value you can change by moving to the
bottom pane. Here are some examples of direct assignment
expressions:

C x = 4
Pascal ratio := 1.234
Assembler wval = 4 shl 2

If you had typed just "x," "ratio," or "wval" into the top
pane, then you would be able to move to the bottom pane and
enter a new value. The direct assignment method using the
"=" or ":=" assignment operator is quicker and more
convenient if you don't care about examining the value of
the variable before modifying it.


4) What could happen when global breakpoints are set on local
variables?

When you set global breakpoints using local variables, make
sure the breakpoints are cleared before you exit the
procedure or function that the variables are defined in. The
best way to do this is to put a breakpoint on the last line
of the procedure or function. If you do not clear the
breakpoints, your program will break unexpectedly and may
even hang on some machines because the breakpoints are being
set in memory that is not currently being used by the
procedure or function.

5) Why is execution slower when tracing (F7) than when stepping
(F8) through my programs?

TDW can do reverse execution, which means that when you are
tracing through your program, Turbo Debugger could be saving all
the information about each source line you trace over. TD only
saves this information in the Module window if you have chosen
View|Execution History and toggled the Full History local menu
command to 'Yes'.

If you want faster execution you can step over (F8) the instruction
or toggle the Full History option to 'No' in the Execution History
window. (Although reverse execution is always available in the
CPU view, you must toggle this option to 'Yes' for it to work
in the Module view. The default setting in the Module view is 'No'.)

6) What are some of the syntactic and parsing differences between
Turbo Debugger's built-in assembler and the standalone Turbo Assembler?

A discussion follows this short example assembler program:

.model small
.data

abc struc
mem1 dd ?
mem2 db ?
mem3 db " "
abc ends

align 16
a abc <1,2,"xyz">

msg1 db "testing 1 2 3", 0
msg2 db "hello world", 0
nmptr dw msg1
fmptr dd msg1,msg2
nfmptr dw fmptr
xx dw seg a

.code

push cs
pop ds
mov bx,offset a
mov bx,nmptr
les si,fmptr
mov ah,4ch
int 21h
end

Because the assembler expression parser does not accept all legal
TASM instruction operands, Turbo Debugger assembler expressions
can be more general than those of TASM and can use multiple levels
of memory-referencing, much like C and Pascal. However, there are
a few constructs that you may be used to that you'll have to
specify differently for the Turbo Debugger assembler expression
parser to accept them:

a. Size overrides should always appear inside the
brackets; PTR is optional after the size. Also, when
referring to a structure, you must use the name of the
structure, not the name of the variable:

OK: [byte ptr bx] [dword si] [abc bx]

BAD: byte ptr[bx] [struc abc bx] [a bx]

b. You must specify a structure name when accessing the
members of a structure with a register pointer.

OK: [abc ptr bx].mem1 [abc bx].mem3 + 1

BAD: [bx].mem1

c. You can't use multiple instances of brackets ([]) unless they
are adjacent, and you can only follow a bracketed expression
with a dot and a structure member name or another bracketed
expression:

OK: 4[bx][si] [abc bx].mem2

BAD: [bx]4[si] [bx]+4

d. If you use a register as part of a memory expression
and you don't specify a size, WORD is assumed:

[bx] is the same as [word bx]

e. You can use any register you want between brackets ([]),
not just the combinations of BX, BP, SI, and DI allowed in
instruction operands. For example,

[ax+bx]
[bx+sp]

f. You can use multiple levels of brackets to follow chains of
pointers. For example,

[byte [[nfmptr]+4]]

g. Be careful with using registers to access memory locations.
You might get unexpected results if your segment
registers are not set up properly. If you don't
explicitly specify a segment register, Turbo Debugger
uses the DS register to reference memory.

h. When you do specify a segment register, make sure you
follow the same rule for size overrides: put it
INSIDE the brackets, as follows:

OK: [byte es:di] [es:fmptr]

BAD: es:[byte di]

i. Use the OFFSET operator to get the address of a
variable or structure. Turbo Debugger automatically
supplies the brackets around a variable name if you just type
the variable name alone.

a contents of structure a
[a] contents of structure a
offset a address of structure a

j. You can use the type overrides and the format control
count to examine any area of memory displayed as you wish.

[byte es:bx],10 10 bytes pointed to by es:bx
[dword ds:si],4 4 dwords pointed to by ds:si

This is very useful when specifying watch expressions.

k. Sometimes you use a word memory location or register to
point to a paragraph in memory that contains a data
structure. Access the structure with expressions like

[abc [xx]:0].mem1
[abc es:0].mem3

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