home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / USCX / BASUT-01.ZIP / BASICREF.DOC < prev    next >
Text File  |  1983-08-17  |  7KB  |  116 lines
  1.                CROSS-REFERENCE UTILITY FOR IBM PC BASIC PROGRAMS
  2.  
  3. To produce a cross-reference listing for BASIC programs running on the IBM 
  4. Personal Computer, I wrote a program that scans a BASIC program file and 
  5. builds a list of variable names and the locations where they occur.  The 
  6. program then sorts that list and writes it to a file. 
  7.  
  8. The program expects a standard BASIC program file, that is, one saved without 
  9. the special A (ASCII - American National Standard Code for Information 
  10. Interchange) or P (protect) options.  The standard save procedure stores the 
  11. program in a tokenized format in which all reserved BASIC words are 
  12. represented by tokens, 1 or 2-byte codes.  For instance, the RANDOMIZE 
  13. statement is represented by a single ASCII value of 185.  This tokenized 
  14. format saves space because multiple-character reserved words are represented 
  15. by only one or two characters.
  16.  
  17. All tokenized characters have a value of 128 or greater, outside the range of 
  18. ASCII values legal in variable names.  Only capital letters, numerals, and the 
  19. period are legal in variable names, and these have values between 46 and 90.  
  20. (Variables can be entered in lowercase, but BASIC converts them to capitals.)  
  21. The restrictions on legal variable names simplify the work of the cross 
  22. reference program because it can usually just skip tokens in its search for 
  23. valid variable names.  Two exceptions are the tokens for a remark (ASCII 143) 
  24. or data statement (ASCII 132).  In both these cases the program skips to the 
  25. end of the line so as not to confuse words in remarks, or literals in data 
  26. statements, with valid variable names.
  27.  
  28. All numbers used in a program - constants, initial values, line-number 
  29. references, and so on - are also encoded.  For instance, an ASCII 28 code 
  30. indicates that an integer value follows in the next 2 bytes in the file.  An 
  31. ASCII 29 indicates a single - precision number in the next 4 bytes.  Other 
  32. prefixes indicate various types of double - precision numbers, octal numbers, 
  33. or hexadecimal numbers.
  34.  
  35. The program skips over all coded numbers except those prefixed by an ASCII 14.  
  36. This code signifies a 2-byte number that is a program line number reference, 
  37. following a GOTO or GOSUB, for instance.  The cross-reference listing program 
  38. treats line number references as labels and lists all lines referenced by 
  39. other lines.  This can help you find all the places in a program that call a 
  40. certain subroutine.
  41.  
  42.                           H O W    I T    W O R K S
  43.  
  44. The format of the lines in a tokenized program file is shown in figure 1.  The 
  45. first 2 bytes are the BASIC offset address to the next program line.  Our only 
  46. interest in it is when it is 0 because a 0 offset signifies the end of the 
  47. program.  The next 2 bytes contain the line number, with the least significant 
  48. byte first.  These are followed by a series of bytes, including tokens, coded 
  49. numbers, and variable names, up to the end of the line, indicated by an ASCII 
  50. value of 0.
  51.  
  52. The approach of the cross reference utility, then, is very simple.  It makes a 
  53. note of the line number being scanned at the moment, then skips over tokens 
  54. and encoded numbers, looking for variable names and references to other 
  55. program lines.  When it finds the beginning of a variable name, it builds the 
  56. name, character by character, until it comes to an ASCII code that can't be 
  57. part of a variable name.  If the variable has been explicitly typed (marked by 
  58. a $, #, !, %), that character is added to the end of the name.  If the 
  59. variable is subscripted, then "(SUB)" is added.  Once complete, the variable 
  60. name is stored in an array; the line number where it appears is stored in a 
  61. parallel array of line numbers.
  62.  
  63. Once the entire program file has been scanned, the label and line number 
  64. arrays are sorted using a Shell sort. Then they are written to a disk file.
  65.  
  66. The only real problem is that all the scanning and sorting takes time.  The 
  67. program took nearly 7 minutes to process and sort labels for its own 145 lines 
  68. and 245 label references.  For a smaller program (123 references and 133 
  69. labels), it required 3 minutes 45 seconds.  You can get a modest increase in 
  70. speed of about 5 to 10 percent by eliminating comments and consolidating 
  71. statements in to one line where possible.  This will have the greatest effect 
  72. in the WHILE loop beginning at line 600 and the sort routine beginning at line 
  73. 800.
  74.  
  75.                                 B E    W A R Y
  76.  
  77. In order not to slow the program down further, I kept it as simple as 
  78. possible.  Because of this, a few bogus variables may creep into your listing.  
  79. These are words used as part of BASIC statements that are not tokenized.  They 
  80. include the following:  ALL in a CHAIN statement, BASE in an  OPTION BASE 
  81. statement, B or BF in a LINE statement, R in a LOAD statement, AS in APPEND, 
  82. or OUTPUT in an OPEN statement.  None of these is a reserved word, and they 
  83. are therefore not tokenized.  Thus, if you use them in a program, the cross 
  84. reference utility will treat them as variable names.  Note that both AS and 
  85. OUTPUT appear in listing 2.
  86.  
  87. The cross reference listing is written to a sequential disk file, which may be 
  88. read later.  The file name for the listing is the file name of the program 
  89. file with an extension of CRF.  If the original program file were MYPROG.BAS, 
  90. the listing would appear on file MYPROG.CRF.  To display the listing on your 
  91. monitor, you first need access to the DOS (disk operating system) - execute 
  92. SYSTEM from BASIC.  When in DOS, execute TYPE MYPROG.CRF.  If you want a hard 
  93. copy, press the Ctrl and PrtSc keys simultaneously prior to execution the TYPE 
  94. command; the listing on the monitor will then be output to the printer.
  95.  
  96.                           M O D I F I C A T I O N S
  97.  
  98. The output is formatted for an 80 - column screen or printer as the program 
  99. appears in listing 1.  To format for a 40 - column screen, change N>8 in line 
  100. 3070 to N>3.  To format for a 132 - column printer width, change it to N>16.  
  101. You may also want to redimension the arrays in statement 110.  They are large 
  102. enough for modest programs, but larger programs with more references will need 
  103. more space.
  104.  
  105.  
  106.  
  107.  
  108.         This disk copy was originally provided by "The Public Library",
  109.         the software library of the Houston Area League of PC Users.
  110.  
  111.         Programs are available from the Public Library at $2 per disk
  112.         on user-provided disks.  To get a listing of the disks in the
  113.         Public Library, send a self-addressed, stamped envelope to
  114.  
  115.              Nelson Ford,  P.O.Box 61565,  Houston, TX 77208.
  116.