home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TPUTIL1.ZIP / TURBODBG.DOC < prev   
Encoding:
Text File  |  1985-12-21  |  12.6 KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                              December 14, 1985
  9.  
  10.                           TURBODBG.DOC
  11.  
  12. OVERVIEW
  13.  
  14. TURBODBG is a source code debugger for use in debugging Turbo 
  15. Pascal (tm) Programs on the IBM-PC (tm).  When used in 
  16. conjunction with TURBO.COM, it allows you to:
  17.  
  18.      1.  View your source code while debugging.
  19.      2.  Trace the operation of your program statement by 
  20.          statement.
  21.      3.  Insert breakpoints in your program by procedure/function 
  22.          name or by statement number.
  23.      4.  Examine (and change) global variables in your program, 
  24.          including strings, array variables, and records.
  25.  
  26.  
  27. SYSTEM REQUIREMENTS
  28.  
  29.      1.  Turbo Pascal IBM-PC Version 3.00B or 3.01A.
  30.      2.  Approximately 64k or so more memory than would normally 
  31.          be required to run your program in the Turbo memory 
  32.          mode.
  33.  
  34.  
  35. OPERATION
  36.  
  37. To use TURBODBG, include the file DBG??.COM (the ?? is a two 
  38. digit revision number) on the disk (or in the directory) with 
  39. TURBO.COM, TURBO.MSG, and your program file.  At the DOS prompt, 
  40. call for DBG??.  After a brief sign on message, TURBODBG will 
  41. load TURBO.COM and transfer control to it.  (The message 
  42. 'Incorrect TURBO.COM version!' indicates that TURBODBG and your 
  43. version of TURBO.COM are incompatible.)
  44.  
  45. At this point, all of the commands and features of Turbo Pascal 
  46. should operate as they always have with the exception of the Run 
  47. command.  The only special requirement for programs to be 
  48. debugged is that the {$U+} compiler directive not be used.  When 
  49. the Run command is executed, TURBODBG will regain control and the 
  50. debugging screen will appear.
  51.  
  52. The debugging screen is divided into two parts.  The lower 
  53. section is the command and data section.  The '*' is a prompt for 
  54. one of the commands described later.  The top part of the screen 
  55. displays the program source code text which at this point will be 
  56. centered at the first executable statement of your program.
  57.  
  58. Within the text part of the display, the current statement (the 
  59. next one to be executed) will be highlighted.  The left margin 
  60.  
  61.  
  62.                            1
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74. contains the statement number of the first statement occurring on 
  75. that particular line.  Statement numbers are consecutive numbers 
  76. and are used to refer to individual statements in the commands 
  77. described later.  Since there may be more than one statement on a 
  78. line, the statement number in the margin is that of the first 
  79. statement on the line.  The first character of each statement is 
  80. highlighted.  Note also that there may be no statements on a 
  81. given line so those lines will have no numbers.
  82.  
  83. Dividing the two portions of the debugging screen is a line which 
  84. at this point will probably display 'Memory'.  This indicates 
  85. that the text file being observed is in memory.  Later, when 
  86. viewing a portion of the program source code which is in an 
  87. 'include' file, the name of the 'include' file will appear here.
  88.  
  89.  
  90. SPECIAL KEYS FOR VIEWING TEXT
  91.  
  92. The following keys may be used to change the text being 
  93. displayed:
  94.  
  95.      Pg Up
  96.      Pg Dn  Move the display up or down one page.
  97.  
  98.      ^Pg Up
  99.      ^Pg Dn Move to the start or end of the current file.
  100.  
  101.      Up arrow
  102.      Down arrow  Scroll up or down one line.
  103.  
  104.      F10 key  Toggle between the debug screen and the screen
  105.               of the program under test.
  106.  
  107. In addition, the text being displayed may be changed using the 
  108. View command described later.
  109.  
  110.  
  111. COMMAND EDITOR
  112.  
  113. When entering commands, the following keys may used to edit the 
  114. command:  (They perform the same functions as they do in the 
  115. Turbo Pascal editor.)
  116.  
  117.      ^A,^S,^D,^F,^G,^T,^H,LFARW,RTARW,^LFARW,^RTARW,
  118.      Ins, Del, Backspace
  119.  
  120. The Insert mode (default) is indicated by a slightly fatter 
  121. cursor while the cursor is normal in the Overwrite mode.
  122.  
  123. In addition, the F3 function key causes the last command entered 
  124. (having more than three characters) to be redisplayed.  This may 
  125.  
  126.  
  127.  
  128.                            2
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140. be used to make minor changes to a previous command or to correct 
  141. a syntax error.
  142.  
  143. Note that commands are not acted upon until the Enter key is hit.  
  144. (The cursor does not have to be at the line end to enter the 
  145. command.)
  146.  
  147.  
  148. COMMAND PARAMETERS
  149.  
  150. Commands consist of one or two letters (only one letter commands 
  151. presently exist) which may be followed by one or more parameters.  
  152. A non alphabetic character must follow the command to delimit it 
  153. from a following parameter.  The parameters which may be used 
  154. are:
  155.  
  156.   <Symbol>
  157.      A Pascal source code symbol representing a 
  158.      procedure/function name, variable, or constant as 
  159.      appropriate.  The special symbol 'RTN' may be used to refer 
  160.      to the return point of a procedure/function.
  161.  
  162.   <Statement>
  163.      A statement number as displayed in the left margin of the 
  164.      text display.
  165.  
  166.  
  167. COMMANDS
  168.  
  169. G    (Go)
  170.  
  171.   Format:
  172.      G [<parameter> [<parameter..]]
  173.  
  174.   The Go command starts execution of the program under test.  
  175.   Execution will continue until a breakpoint is reached, the 
  176.   program terminates, or the <control Break> key is hit.
  177.  
  178.   One or more breakpoints may be entered with the Go command.  
  179.   These breakpoints are called temporary breakpoints as they are 
  180.   in effect only until the first stopping point is reached.  Any 
  181.   temporary breakpoint would then have to reentered with the next 
  182.   Go command if desired.
  183.  
  184.   The program under test may be interrupted using the <control 
  185.   Break> key.  Note that <control C> does not perform the same 
  186.   function but rather performs its normal Turbo Pascal function 
  187.   (as defined by the {$C } compiler directive.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                            3
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.   Examples:
  207.  
  208.      G   Start execution with no temporary breakpoints. (There 
  209.          might be some permanent breakpoints, however.)
  210.  
  211.      G 345 PROC1 RTN
  212.          Start execution with temporary breakpoints at statement 
  213.          345, at the start of procedure PROC1, and at the return 
  214.          point of the current procedure/function.  In addition, 
  215.          there might be other permanent breakpoints in effect.
  216.  
  217. T    (Trace)
  218.  
  219.   Format:
  220.      T
  221.  
  222.   Execute the current statement.  Only one statement is executed.
  223.  
  224.  
  225. N    (Next)
  226.  
  227.   Format:
  228.      N
  229.  
  230.   Execute the current statement in its entirety.
  231.  
  232.   The difference between the Trace and the Next command is that 
  233.   if the current statement is a procedure or function call, Next 
  234.   will completely execute the procedure/function whereas Trace 
  235.   will Trace through the procedure/function.
  236.  
  237.  
  238. P    (Permanent breakpoint)
  239.  
  240.   Format:
  241.      [-]P [<parameter>]
  242.  
  243.   The P command is used to specify permanent breakpoints.  Unlike 
  244.   temporary breakpoints, permanent breakpoints remain in effect 
  245.   until removed (using a '-' preceding the P command).  
  246.  
  247.   If no parameter is entered, the breakpoints in effect are 
  248.   listed.
  249.  
  250.   Examples:
  251.  
  252.      P        List all permanent breakpoints.
  253.     -P        Delete all permanent breakpoints.
  254.      P 345    Install a breakpoints at statement 345.
  255.     -P PROC1  Remove a breakpoint at procedure PROC1.
  256.  
  257.  
  258.  
  259.  
  260.                            4
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272. V    (View text)
  273.  
  274.   Format:
  275.      V [<parameter>]
  276.  
  277.   The View command may be used to change the text being observed 
  278.   in the text window.  If no parameter is entered, the text will 
  279.   be centered around the current statement (the one to be 
  280.   executed next).
  281.  
  282.   Examples:
  283.  
  284.      V InitScreens   View text at procedure InitScreens.
  285.      V 545           View text around statement 545.
  286.      V Rtn           Find out where this procedure/function was
  287.                      called from.
  288.  
  289.  
  290. E    (Examine/change variable or constant)
  291.  
  292.   Format:
  293.      E <symbol>
  294.  
  295.   The Examine/change command allows the the value of global 
  296.   variables and constants to be displayed.  In addition, for 
  297.   variables, a new value may be entered.  Note that Turbo Pascal 
  298.   'typed constants' are actually initialized variables and these 
  299.   may also be changed.  
  300.  
  301.   After a variable value has been output in response to the 
  302.   Examine/change command, a new value may be entered followed by 
  303.   the Enter key.  For byte and integer types, a hex value may be 
  304.   specified by preceding it with a '$'.  Hitting the Enter key 
  305.   only retains the old variable value.  
  306.  
  307.   8 bit variables (byte, char, boolean) are displayed in decimal, 
  308.   hex, and character (if printable).  In the case of boolean, 0 
  309.   is false, and 1 is true.
  310.  
  311.   Integer variables are displayed as both decimal and hex.
  312.  
  313.   Real variables are displayed in 'E' format and also decimal 
  314.   format if within a reasonable range.
  315.  
  316.   Pointer variables are displayed with the phrase 'Points to:' 
  317.   followed by an address and symbolic name if appropriate.  If 
  318.   the pointer variable is followed by '^', the contents of the 
  319.   pointed to variable are displayed.
  320.  
  321.   String variables are displayed as a string within quotes.  When 
  322.   specifying a change to a string variable, enclose the new 
  323.   string in quotes.  A null string is specified by two quotes 
  324.  
  325.  
  326.                            5
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.   enclosing nothing.  Individual characters of a string may be 
  339.   displayed and changed by treating the string as an array.
  340.  
  341.   Non numerical scaler variables are displayed numerically.  For 
  342.   instance, a variable defined as
  343.  
  344.     Var   Color   :(red,green,blue,orange);
  345.  
  346.   would be be given a value of 2 if it contained blue.  However, 
  347.   note that:
  348.  
  349.      E BLUE
  350.  
  351.   could be used to verify that blue was represented by 2.
  352.  
  353.   Sets cannot be examined.
  354.  
  355.   Examples:
  356.  
  357.      E RealArray[4,3]
  358.      E InString
  359.      E PersonRecord[12].ID.Lastname
  360.      E PT^.Index1
  361.      E START^.NEXT^.NEXT^.NEXT^.VALUE[10][3]
  362.  
  363.  
  364. Q    (Quit)
  365.  
  366.   Format:
  367.      Q
  368.  
  369.   The Quit command when entered in TURBODBG returns control to 
  370.   Turbo Pascal without running the program under test to 
  371.   completion.
  372.  
  373.  
  374. HINTS
  375.  
  376. It is possible to insert breakpoints in the source code using 
  377. INLINE($CC).  These breakpoints cannot be removed by TURBODBG 
  378. but may be useful for conditional breaks.  For instance:
  379.  
  380.   IF I=49 THEN INLINE($CC);
  381.  
  382. To get around the fact that local variables are not visible, the 
  383. CONST's and VAR's may be moved temporarily to a global area.  
  384. Turbo Pascal allows them to be moved just above the 
  385. procedure/function definition.  Of course this only works if the 
  386. procedure/function is not used recursively and if there is no 
  387. symbol name conflict.
  388.  
  389.  
  390.  
  391.  
  392.                            6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404. RESTRICTIONS, PROBLEMS, BUGS
  405.  
  406. The following are current limits.  These may be easily changed by 
  407. changing a constant and recompiling.
  408.  
  409.   Permanent and temporary breakpoints are limited to 3 each.
  410.   Maximum number of include files = 6.
  411.   Maximum include file size = 32k.
  412.   Maximum number of statements = 2000.
  413.   Maximum allowable symbol table size = 5k.
  414.   Maximum symbol length = 28.
  415.  
  416. When changing a string using Examine/change, there currently is 
  417. no protection against entering one that is too long.  Use care.
  418.  
  419. Only global procedure/functions, variables, and constants are 
  420. known to TURBODBG currently.  Procedure/function dummy variables 
  421. and function values may be added in the future.  It may not be 
  422. practical to make local variables and procedure/function symbols 
  423. accessible.
  424.  
  425. Presently symbolic constants cannot be used as subscripts in the 
  426. Examine/change command.  For instance, if
  427.  
  428.  Var   Opcode  :ARRAY[MOV..CMP] OF BYTE;
  429.  
  430. it is presently necessary to specify OPCODE[0] rather than 
  431. OPCODE[MOV] when using the Examine/change command.
  432.  
  433. The <control Break> program interrupt does not perform properly 
  434. when the program under test is waiting for keyboard input.
  435.  
  436. A simple screen switch is currently used.  This limits debugging 
  437. to text only programs.
  438.  
  439. There is a problem when compiling to a disk COM file.  Turbo 
  440. often takes a short cut and transfers directly from memory to 
  441. disk without recompiling.  However, the memory file has been 
  442. altered by TURBODBG and the resulting COM file is corrupted.  It 
  443. is best at this stage to compile to disk only without the 
  444. debugger.
  445.  
  446. At this stage, TURBODBG is experimental.  Please report any 
  447. problems, comments, suggestions, and especially if it doesn't 
  448. work with your IBM-PC version 3.00B or 3.01A TURBO.COM to me at 
  449. Compuserve ID 76327,53.
  450.                                              
  451.                                         Dave Baldwin
  452.  
  453.      IBM-PC is a trademark of International Business Machines 
  454.      Corporation.
  455.      Turbo Pascal is a trademark of Borland International Inc.
  456.  
  457.  
  458.                            7
  459.  
  460.  
  461.  
  462.  
  463.