home *** CD-ROM | disk | FTP | other *** search
- /**********************************************************************************/
- 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 <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).
-
-
- 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 = <Your_Borland_Compiler_Bin_Directory>\SVGA.DLL
- debuggerDll = <Your_Borland_Compiler_Bin_Directory>\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=<Your_Borland_Compiler_Bin_Directory>\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=<Your_Borland_Compiler_Bin_Directory>\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 <Ctrl><Alt><Delete> 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 <Enter> 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 <ALT> 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 ************************************/
-
-