December 31, 1985 tdebug. Doc overview tdebug is a source code debugger for use in debugging Turbo Pascal (tm) Programs on the ibm-pc (tm). When used in conjunction with turbo. Com, it allows you to: 1
December 31, 1985 TDEBUG.DOC OVERVIEW TDEBUG is a source code debugger for use in debugging Turbo Pascal (tm) Programs on the IBM-PC (tm). When used in conjunction with TURBO.COM, it allows you to: 1. View your source code while debugging. 2. Trace the operation of your program statement by statement. 3. Insert breakpoints in your program by procedure/function name or by statement number. 4. Examine (and change) global or local variables in your program, including strings, array variables, and records. SYSTEM REQUIREMENTS 1. One of the following versions of Turbo Pascal for the IBM-PC: TURBO.COM v3.00b TURBO.COM v3.01a TURBO-87.COM v3.01a 2. Approximately 128k more memory than would normally be required to run your program in the Turbo memory mode. 3. A hard disk is desirable and may be a necessity when debugging large programs with the optional local symbols. OPERATION To use TDEBUG, include the file TDEBUG.COM on the disk (or in the directory) with TURBO.COM (or TURBO-87.COM), TURBO.MSG, and your program file. At the DOS prompt, call for TDEBUG. After a brief sign on message, TDEBUG will load TURBO.COM and transfer control to it. (The message 'Incorrect TURBO.COM version!' indicates that TDEBUG and your version of TURBO.COM are incompatible.) When calling for TDEBUG, the following optional parameters may be used: G Use global symbols only. Users with limited disk space may not be able to accommodate the local symbol disk file. T= The T option allows the name (and path) of the Turbo compiler 1 to be specified. '.COM' should be a part of this specification. The default is TURBO.COM. L= The L option allows specification of the local symbol file name. This option has been included mostly to allow a path to be specified. If enough space is available, a ramdisk drive is ideal with a hard disk being a second choice. The default filename is '@@LOCAL.SYM'. B=n For this option, n specifies the symbol table buffer size (decimal). This is important mainly when using local symbols because the local symbol file size will be approximately n times the number of procedures and functions in the program under test. Users with limited disk space will probably want to make n as small as possible. Unfortunately, the actual size required is not known until the program under test is compiled so some experimenting may be necessary. The default value is 6000 bytes. n may not be made less than 1000 bytes. Examples: TDEBUG T=TURBO-87.COM L=D:LOCAL B=5000 TDEBUG G Once TDEBUG has loaded and begun execution of TURBO.COM, all of the commands and features of Turbo Pascal should operate as they always have with the exception of the Run command. The only special requirement for programs to be debugged is that the {$U+} compiler directive not be used. When the Run command is executed, TDEBUG will regain control and the debugging screen will appear. The debugging screen is divided into two parts. The lower section is the command and data section. The '*' is a prompt for one of the commands described later. The top part of the screen displays the program source code text which at this point will be centered at the first executable statement of your program. Within the text part of the display, the current statement (the next one to be executed) will be highlighted. The left margin contains the statement number of the first statement occurring on that particular line. Statement numbers are consecutive numbers and are used to refer to individual statements in the commands described later. Since there may be more than one statement on a line, the statement number in the margin is that of the first statement on the line. The first character of each statement is highlighted. Note also that there may be no statements on a given line so those lines will have no numbers. 2 Dividing the two portions of the debugging screen is a line which at this point will probably display 'Memory'. This indicates that the text file being observed is in memory. Later, when viewing a portion of the program source code which is in an 'include' file, the name of the 'include' file will appear here. When the Run command is issued after a fresh compilation, TDEBUG will issue a report giving the symbol table buffer size actually required, the number of statements and include files found and any disk errors which might have occurred during compilation. In the event of any errors, it will not be possible to continue with the debugging session until the errors are corrected. Hit any key to return to TURBO to make the corrections. The most likely error is a symbol table buffer overflow which will require a change in the 'B' option at load time. SPECIAL KEYS FOR VIEWING TEXT The following keys may be used to change the text being displayed: Pg Up Pg Dn Move the display up or down one page. ^Pg Up ^Pg Dn Move to the start or end of the current file. Up arrow Down arrow Scroll up or down one line. F10 key Toggle between the debug screen and the screen of the program under test. In addition, the text being displayed may be changed using the View command described later. COMMAND EDITOR When entering commands, the following keys may used to edit the command: (They perform the same functions as they do in the Turbo Pascal editor.) ^A,^S,^D,^F,^G,^T,^H,LFARW,RTARW,^LFARW,^RTARW, Ins, Del, Backspace The Insert mode (default) is indicated by a slightly fatter cursor while the cursor is normal in the Overwrite mode. In addition, the F3 function key causes the last command entered (having more than three characters) to be redisplayed. This may 3 be used to make minor changes to a previous command or to correct a syntax error. Note that commands are not acted upon until the Enter key is hit. (The cursor does not have to be at the line end to enter the command.) COMMAND PARAMETERS Commands consist of one or two letters which may be followed by one or more parameters. A non alphabetic character must follow the command to delimit it from a following parameter. The parameters which may be used are: A Pascal source code symbol representing a procedure/function name, variable, or constant as appropriate. The special symbol 'RTN' may be used to refer to the return point of a procedure/function. The usage of global or local symbols is explained more fully in a later section. A statement number as displayed in the left margin of the text display. COMMANDS G (Go) Format: G [
[
key is hit. One or more breakpoints may be entered with the Go command. These breakpoints are called temporary breakpoints as they are in effect only until the first stopping point is reached. Any temporary breakpoint would then have to reentered with the next Go command if desired. The program under test may be interrupted using the key. Note that does not perform the same function but rather performs its normal Turbo Pascal function (as defined by the {$C } compiler directive. 4 Examples: G Start execution with no temporary breakpoints. (There might be some permanent breakpoints, however.) G 345 PROC1 RTN Start execution with temporary breakpoints at statement 345, at the start of procedure PROC1, and at the return point of the current procedure/function. In addition, there might be other permanent breakpoints in effect. T (Trace) Format: T Execute the current statement. Only one statement is executed. N (Next) Format: N Execute the current statement in its entirety. The difference between the Trace and the Next command is that if the current statement is a procedure or function call, Next will completely execute the procedure/function whereas Trace will Trace through the procedure/function. P (Permanent breakpoint) Format: [-]P [
] The P command is used to specify permanent breakpoints. Unlike temporary breakpoints, permanent breakpoints remain in effect until removed (using a '-' preceding the P command). If no parameter is entered, the breakpoints in effect are listed. Examples: P List all permanent breakpoints. -P Delete all permanent breakpoints. P 345 Install a breakpoints at statement 345. -P PROC1 Remove a breakpoint at procedure PROC1. 5 V (View text) Format: V [
] The View command may be used to change the text being observed in the text window. If no parameter is entered, the text will be centered around the current statement (the one to be executed next). Examples: V InitScreens View text at procedure InitScreens. V 545 View text around statement 545. V Rtn Find out where this procedure/function was called from. E (Examine/change variable or constant) Format: E The Examine/change command allows the the value of global and local variables and constants to be displayed. In addition, for variables, a new value may be entered. Note that Turbo Pascal 'typed constants' are actually initialized variables and these may also be changed. After a variable value has been output in response to the Examine/change command, a new value may be entered followed by the Enter key. For byte and integer types, a hex value may be specified by preceding it with a '$'. Hitting the Enter key only retains the old variable value. 8 bit variables (byte, char, boolean) are displayed in decimal, hex, and character (if printable). In the case of boolean, 0 is false, and 1 is true. Integer variables are displayed in both decimal and hex. Real variables are displayed in 'E' format and also decimal format if within a reasonable range. Pointer variables are displayed with the phrase 'Points to:' followed by an address and symbolic name if appropriate. If the pointer variable is followed by '^', the contents of the pointed to variable are displayed. To change a pointer variable, use either a symbolic name or a segment:offset numerical address with a colon separator such as $1234:$5678. 6 String variables are displayed as a string within quotes. When specifying a change to a string variable, the new string should be enclosed in quotes. A null string is specified by two quotes enclosing nothing. Individual characters of a string may be displayed and changed by treating the string as an array. Non numerical scaler variables are displayed numerically. For instance, a variable defined as Var Color :(red,green,blue,orange); would be be given a value of 2 if it contained blue. However, note that: E BLUE could be used to verify that blue was represented by 2. Sets cannot be examined. Examples: E RealArray[4,3] E InString E PersonRecord[12].ID.Lastname E PT^.Index1 E START^.NEXT^.NEXT^.NEXT^.VALUE[10][3] Q (Quit) Format: Q The Quit command when entered in TDEBUG returns control to Turbo Pascal without running the program under test to completion. X (Translate) Format: X
The translate command translates symbols and statements into segment-offset addresses. This is useful mainly when using an external assembly language debugger. Unlike the E (Examine) command, a variable need not be completely specified to get an address. 7 Examples: X PersonRecord ;yields the first address of PersonRecord X PersonRecord[12] ;yields the first address of PersonRecord[12] X PersonRecord[12].ID ;yields the first address of PersonRecord[12].ID DB (DeBug) Format: DB This command is used to enter an optional external assembly language debugger. Its use is explained in a later section. SYMBOLS TDEBUG makes use of two sets of symbols, the global symbols and (optionally) the local symbols. Global symbols are those which would be available in the main block of the Pascal program and include all non nested procedure/function names as well as variables and constants defined outside of procedure/functions. Local symbols are those defined within a procedure/function and are valid and only accessible within the block of that procedure/function. Local symbols include the formal parameters defined in the procedure heading and also function results. Note that the block boundaries are delimited by the BEGIN and END for any particular procedure. In particular, this means that local symbols cannot be accessed when the current instruction is a procedure/function heading. This should be kept in mind since breakpoints are frequently placed at procedure/function headings. Error messages such as 'Not a GLOBAL symbol' or 'Not a GLOBAL Variable' are meant to be a reminder that only the GLOBAL symbols are being searched. From a procedure/function heading it is only necessary to do one 'T' (Trace) command to be within procedure block where the local symbols can be accessed. TDEBUG searches local symbols before global symbols. This is of significance in cases where duplicate symbol names are used. HINTS It is possible to insert breakpoints in the source code using INLINE($CC). These breakpoints cannot be removed by TDEBUG but may be useful for conditional breaks. For instance: 8 IF I=49 THEN INLINE($CC); USING AN EXTERNAL ASSEMBLY LANGUAGE DEBUGGER It is possible to use an assembly language debugger in conjunction with TDEBUG. It is often desirable to examine the compiled code of a program to determine what the problems really are and this provides a convenient way to do this. The following instructions are for using DOS DEBUG although other debuggers may be used in a similar manner. Load DEBUG by: DEBUG TDEBUG.COM
where the
are the optional TDEBUG parameters. Once the load is completed and you are in DEBUG, issue the 'G' (Go) command. Operation of TDEBUG and TURBO will proceed in a normal fashion. At the appropriate time in the debugging session, use the X (Translate) command to find the machine addresses to be inspected. Then issue the DB (DeBug) command. You will find yourself back in DEBUG. At this point, the DEBUG U (Unassemble) or D (Display) commands can be used to inspect code or data. To reenter TDEBUG, it is necessary to jump over the INT 3 instruction which caused the break to DEBUG. Do this by using the G command: G=xxxx where xxxx is the contents of the IP register plus 1. No breakpoints should be installed with DEBUG as TDEBUG takes over the breakpoint vector when it is reentered. RESTRICTIONS, PROBLEMS, BUGS The following are current limits. Permanent and temporary breakpoints are limited to 6 each. Maximum number of include files = 20. Maximum include file size = 32k. Maximum number of statements = 4000. Maximum symbol length = 28. Maximum number of local symbol blocks = 250. Presently symbolic constants cannot be used as subscripts in the Examine/change command. For instance, if 9 Var Opcode :ARRAY[MOV..CMP] OF BYTE; it is presently necessary to specify OPCODE[0] rather than OPCODE[MOV] when using the Examine/change command. The program interrupt does not perform properly when the program under test is waiting for keyboard input. A simple screen switch is currently used. This limits debugging to text only programs. Function results should be accessible only within the block of the function whereas they can now be accessed from wherever the function may be called. Any results displayed outside of the function block are not valid. Use care not to alter a function result outside of its block as you will be altering an odd memory location. Variables defined as 'absolute' are sometimes stored as pointers. TDEBUG presently does not resolve these correctly. There is a problem when compiling to a disk COM file. Turbo often takes a short cut and transfers directly from memory to disk without recompiling. However, the memory file has been altered by TDEBUG and the resulting COM file is corrupted. It is best at this stage to compile to disk only without the debugger. IBM-PC is a trademark of International Business Machines Corporation. Turbo Pascal is a trademark of Borland International Inc. 10 #############################################################################################################################
