home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / TURBOPAS / DBG23.ZIP / DBG23.DOC < prev   
Encoding:
Text File  |  1985-11-19  |  13.9 KB  |  247 lines
  1.     3.  Insert breakpoints in your program by procedure/function 
  2.                    name or by statement number.
  3.                4.  Examine (and change) global variables in your program, 
  4.                    including strings, array variables, and records.
  5.           SYSTEM REQUIREMENTS
  6.                1.  Turbo Pascal IBM-PC Version 3.00B.
  7.                2.  Approximately 64k or so more memory than would normally 
  8.                    be required to run your program in the Turbo memory 
  9.                    mode.
  10.           OPERATION
  11.           To use TURBODBG, include the file DBG??.COM (the ?? is a two 
  12.           digit revision number) on the disk (or in the directory) with 
  13.           TURBO.COM, TURBO.MSG, and your program file.  At the DOS prompt, 
  14.           call for DBG??.  After a brief sign on message, TURBODBG will 
  15.           load TURBO.COM and transfer control to it.  (The message 
  16.           'Incorrect TURBO.COM version!' indicates that TURBODBG and your 
  17.           version of TURBO.COM are incompatible.)
  18.           At this point, all of the commands and features of Turbo Pascal 
  19.           should operate as they always have with the exception of the Run 
  20.           command.  The only special requirement for programs to be 
  21.           debugged is that the {$U+} compiler directive not be used.  When 
  22.           the Run command is executed, TURBODBG will regain control and the 
  23.           debugging screen will appear.
  24.           The debugging screen is divided into two parts.  The lower 
  25.           section is the command and data section.  The '*' is a prompt for 
  26.           one of the commands described later.  The top part of the screen 
  27.           displays the program source code text which at this point will be 
  28.           centered at the first executable statement of your program.
  29.           Within the text part of the display, the current statement (the 
  30.           next one to be executed) will be highlighted.  The left margin 
  31.                                      1
  32.           contains the statement number of the first statement occurring on 
  33.           that particular line.  Statement numbers are consecutive numbers 
  34.           and are used to refer to individual statements in the commands 
  35.           described later.  Since there may be more than one statement on a 
  36.           line, the statement number in the margin is that of the first 
  37.           statement on the line.  The first character of each statement is 
  38.           highlighted.  Note also that there may be no statements on a 
  39.           given line so those lines will have no numbers.
  40.           Dividing the two portions of the debugging screen is a line which 
  41.           at this point will probably display 'Memory'.  This indicates 
  42.           that the text file being observed is in memory.  Later, when 
  43.           viewing a portion of the program source code which is in an 
  44.           'include' file, the name of the 'include' file will appear here.
  45.           SPECIAL KEYS FOR VIEWING TEXT
  46.           The following keys may be used to change the text being 
  47.           displayed:
  48.                Pg Up
  49.                Pg Dn  Move the display up or down one page.
  50.                ^Pg Up
  51.                ^Pg Dn Move to the start or end of the current file.
  52.                Up arrow
  53.                Down arrow  Scroll up or down one line.
  54.                F10 key  Toggle between the debug screen and the screen
  55.                         of the program under test.
  56.           In addition, the text being displayed may be changed using the 
  57.           View command described later.
  58.           COMMAND EDITOR
  59.           When entering commands, the following keys may used to edit the 
  60.           command:  (They perform the same functions as they do in the 
  61.           Turbo Pascal editor.)
  62.                ^A,^S,^D,^F,^G,^T,^H,LFARW,RTARW,^LFARW,^RTARW,
  63.                Ins, Del, Backspace
  64.           The Insert mode (default) is indicated by a slightly fatter 
  65.           cursor while the cursor is normal in the Overwrite mode.
  66.           In addition, the F3 function key causes the last command entered 
  67.           (having more than three characters) to be redisplayed.  This may 
  68.                                      2
  69.           be used to make minor changes to a previous command or to correct 
  70.           a syntax error.
  71.           Note that commands are not acted upon until the Enter key is hit.  
  72.           (The cursor does not have to be at the line end to enter the 
  73.           command.)
  74.           COMMAND PARAMETERS
  75.           Commands consist of one or two letters (only one letter commands 
  76.           presently exist) which may be followed by one or more parameters.  
  77.           A non alphabetic character must follow the command to delimit it 
  78.           from a following parameter.  The parameters which may be used 
  79.           are:
  80.             <Symbol>
  81.                A Pascal source code symbol representing a 
  82.                procedure/function name, variable, or constant as 
  83.                appropriate.  The special symbol 'RTN' may be used to refer 
  84.                to the return point of a procedure/function.
  85.             <Statement>
  86.                A statement number as displayed in the left margin of the 
  87.                text display.
  88.           COMMANDS
  89.           G    (Go)
  90.             Format:
  91.                G [<parameter> [<parameter..]]
  92.             The Go command starts execution of the program under test.  
  93.             Execution will continue until a breakpoint is reached, the 
  94.             program terminates, or the <control Break> key is hit.
  95.             One or more breakpoints may be entered with the Go command.  
  96.             These breakpoints are called temporary breakpoints as they are 
  97.             in effect only until the first stopping point is reached.  Any 
  98.             temporary breakpoint would then have to reentered with the next 
  99.             Go command if desired.
  100.             The program under test may be interrupted using the <control 
  101.             Break> key.  Note that <control C> does not perform the same 
  102.             function but rather performs its normal Turbo Pascal function 
  103.             (as defined by the {$C } compiler directive.
  104.                                      3
  105.             Examples:
  106.                G   Start execution with no temporary breakpoints. (There 
  107.                    might be some permanent breakpoints, however.)
  108.                G 345 PROC1 RTN
  109.                    Start execution with temporary breakpoints at statement 
  110.                    345, at the start of procedure PROC1, and at the return 
  111.                    point of the current procedure/function.  In addition, 
  112.                    there might be other permanent breakpoints in effect.
  113.           T    (Trace)
  114.             Format:
  115.                T
  116.             Execute the current statement.  Only one statement is executed.
  117.           N    (Next)
  118.             Format:
  119.                N
  120.             Execute the current statement in its entirety.
  121.             The difference between the Trace and the Next command is that 
  122.             if the current statement is a procedure or function call, Next 
  123.             will completely execute the procedure/function whereas Trace 
  124.             will Trace through the procedure/function.
  125.           P    (Permanent breakpoint)
  126.             Format:
  127.                [-]P [<parameter>]
  128.             The P command is used to specify permanent breakpoints.  Unlike 
  129.             temporary breakpoints, permanent breakpoints remain in effect 
  130.             until removed (using a '-' preceding the P command).  
  131.             If no parameter is entered, the breakpoints in effect are 
  132.             listed.
  133.             Examples:
  134.                P        List all permanent breakpoints.
  135.               -P        Delete all permanent breakpoints.
  136.                P 345    Install a breakpoints at statement 345.
  137.               -P PROC1  Remove a breakpoint at procedure PROC1.
  138.                                      4
  139.           V    (View text)
  140.             Format:
  141.                V [<parameter>]
  142.             The View command may be used to change the text being observed 
  143.             in the text window.  If no parameter is entered, the text will 
  144.             be centered around the current statement (the one to be 
  145.             executed next).
  146.             Examples:
  147.                V InitScreens   View text at procedure InitScreens.
  148.                V 545           View text around statement 545.
  149.                V Rtn           Find out where this procedure/function was
  150.                                called from.
  151.           E    (Examine/change variable or constant)
  152.             Format:
  153.                E <symbol>
  154.             The Examine/change command allows the the value of global 
  155.             variables and constants to be displayed.  In addition, for 
  156.             variables, a new value may be entered.  Note that Turbo Pascal 
  157.             'typed constants' are actually initialized variables and these 
  158.             may also be changed.  
  159.             After a variable value has been output in response to the 
  160.             Examine/change command, a new value may be entered followed by 
  161.             the Enter key.  For byte and integer types, a hex value may be 
  162.             specified by preceding it with a '$'.  Hitting the Enter key 
  163.             only retains the old variable value.  
  164.             8 bit variables (byte, char, boolean) are displayed in decimal, 
  165.             hex, and character (if printable).  In the case of boolean, 0 
  166.             is false, and 1 is true.
  167.             Integer variables are displayed as both decimal and hex.
  168.             Real variables are displayed in 'E' format and also decimal 
  169.             format if within a reasonable range.
  170.             Pointer variables are displayed with the phrase 'Points to:' 
  171.             followed by an address and symbolic name if appropriate.  If 
  172.             the pointer variable is followed by '^', the contents of the 
  173.             pointed to variable are displayed.
  174.             String variables are displayed as a string within quotes.  When 
  175.             specifying a change to a string variable, enclose the new 
  176.             string in quotes.  A null string is specified by two quotes 
  177.                                      5
  178.             enclosing nothing.  Individual characters of a string may be 
  179.             displayed and changed by treating the string as an array.
  180.             Non numerical scaler variables are displayed numerically.  For 
  181.             instance, a variable defined as
  182.               Var   Color   :(red,green,blue,orange);
  183.             would be be given a value of 2 if it contained blue.  However, 
  184.             note that:
  185.                E BLUE
  186.             could be used to verify that blue was represented by 2.
  187.             Sets cannot be examined.
  188.             Examples:
  189.                E RealArray[4,3]
  190.                E InString
  191.                E PersonRecord[12].ID.Lastname
  192.                E PT^.Index1
  193.                E START^.NEXT^.NEXT^.NEXT^.VALUE[10][3]
  194.           Q    (Quit)
  195.             Format:
  196.                Q
  197.             The Quit command when entered in TURBODBG returns control to 
  198.             Turbo Pascal without running the program under test to 
  199.             completion.
  200.           HINTS
  201.           It is possible to insert breakpoints in the source code using 
  202.           INLINE($CC).  These breakpoints cannot be removed by TURBODBG 
  203.           but may be useful for conditional breaks.  For instance:
  204.             IF I=49 THEN INLINE($CC);
  205.           To get around the fact that local variables are not visible, the 
  206.           CONST's and VAR's may be moved temporarily to a global area.  
  207.           Turbo Pascal allows them to be moved just above the 
  208.           procedure/function definition.  Of course this only works if the 
  209.           procedure/function is not used recursively and if there is no 
  210.           symbol name conflict.
  211.                                      6
  212.           RESTRICTIONS, PROBLEMS, BUGS
  213.           The following are current limits.  These may be easily changed by 
  214.           changing a constant and recompiling.
  215.             Permanent and temporary breakpoints are limited to 3 each.
  216.             Maximum number of include files = 6.
  217.             Maximum include file size = 32k.
  218.             Maximum number of statements = 2000.
  219.             Maximum allowable symbol table size = 5k.
  220.             Maximum symbol length = 28.
  221.           When changing a string using Examine/change, there currently is 
  222.           no protection against entering one that is too long.  Use care.
  223.           Only global procedure/functions, variables, and constants are 
  224.           known to TURBODBG currently.  Procedure/function dummy variables 
  225.           and function values may be added in the future.  It may not be 
  226.           practical to make local variables and procedure/function symbols 
  227.           accessible.
  228.           Presently symbolic constants cannot be used as subscripts in the 
  229.           Examine/change command.  For instance, if
  230.            Var   Opcode  :ARRAY[MOV..CMP] OF BYTE;
  231.           it is presently necessary to specify OPCODE[0] rather than 
  232.           OPCODE[MOV] when using the Examine/change command.
  233.           The <control Break> program interrupt does not perform properly 
  234.           when the program under test is waiting for keyboard input.
  235.           A simple screen switch is currently used.  This limits debugging 
  236.           to text only programs.
  237.           There is a problem when compiling to a disk COM file.  Turbo 
  238.           often takes a short cut and transfers directly from memory to 
  239.           disk without recompiling.  However, the memory file has been 
  240.           altered by TURBODBG and the resulting COM file is corrupted.  It 
  241.           is best at this stage to compile to disk only without the 
  242.           debugger.
  243.                IBM-PC is a trademark of International Business Machines 
  244.                Corporation.
  245.                Turbo Pascal is a trademark of Borland International Inc.
  246. Capture buffer closed.
  247. DL 1 :