home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / utils / asmutl / xref36.lbr / XREF36.DZC / XREF36.DOC
Encoding:
Text File  |  1987-08-25  |  6.0 KB  |  165 lines
  1. TOPIC:    XREF36
  2.  
  3. FROM:     LUCIEN L. PAN
  4.  
  5. DATE:     1983/10/18
  6.  
  7.  
  8. INTRODUCTION:
  9. ------------
  10.  
  11.      XREF  is  a cross-reference utility designed to  generate  a
  12. listing  file which contains valuable information that can be  of
  13. help to the assembly language programmer.
  14.  
  15.      It  uses  for input the '.PRN' file created by an  assembler
  16. and  writes  out a modified file which is identical to the  input
  17. except  for an identifying number and some  cosmetic  formatting,
  18. for each source line encountered.  At the end of input, XREF will
  19. output a report, listing each symbol and the line number(s) where
  20. the  symbol  was  referenced.  This  report can  be  used  as  an
  21. important  diagnostic tool facilitating the task of debugging  an
  22. assembly program.
  23.  
  24.  
  25. FEATURES:
  26. --------
  27.  
  28.      Due  to the (relatively) simple objectives of this  program,
  29. such  as  numbering each individual line and building a table  of
  30. symbols with references to where they are being used, most of the
  31. 'polishing'  is  aimed toward getting a nice-looking  listing  as
  32. output.
  33.  
  34.      Following  is  a short description of some of  the  features
  35. offered in this utility:
  36.  
  37.     -    Provides  a  filename  banner on the first page  of  the
  38.     listing,  which  when  folded  in half (on  the  proper  page
  39.     parity)  doubles as an excellent program  listing  separator,
  40.     allowing  easy indexing through a pile of printouts when they
  41.     are held together in a binder.
  42.  
  43.     -    The  line  identification  number  appears  between  the
  44.     object code expansion and the actual source code.  This in my
  45.     opinion,  gives  the the final listing a more attractive look
  46.     by  making  it less crowded.  It  definitively  improves  the
  47.     appearance  of  a '.PRN' file from MAC (tm),  as there is  no
  48.     blank  space  between  the  object  and  source  field  (when
  49.     defining  a  string greater than 5 characters  in  a  labeled
  50.     source line for example).
  51.  
  52.     -    Sadly,  most  assemblers that I've seen do not report  a
  53.     summary of errors, they just flag them. MAC (tm) reports them
  54.     to the console as they are encountered and fortunately,  CP/M
  55.     allows you to send it to the hard copy device.  However  that
  56.     still  doesn't  tell you where the errors are located in  the
  57.     listing  causing  much  time being  wasted  'eyeballing'  the
  58.     printout.  XREF will automatically execute a second pass when
  59.     error(s) were detected in the first pass,  this time  listing
  60.     only  the lines containing the error(s) along with their line
  61.     id.  numbers.  You  also have the option to list  only  error
  62.     lines, fast!
  63.  
  64.     -    A  listing to disk is implemented and is useful to those
  65.     who  use  disk spooling before  printing.  To  conserve  disk
  66.     space,  a tab compression/expansion driver is included. It is
  67.     a  desirable  feature since MAC (tm) only uses spaces in  the
  68.     object  field,  or  even worse,  MACROII  (tm)  expands  tabs
  69.     throughout  the entire file!  I've typically seen some  space
  70.     reduction in the order of 40%.
  71.  
  72.  
  73. INSTALLATION:
  74. ------------
  75.  
  76.      XREF36  is supplied in source code and compiled object.  The
  77. contents of the library are:
  78.  
  79.           XREF36.DOC
  80.           XREF36.AQM
  81.           XREFM.COM           (for MAC)
  82.           XREFT.COM           (for MACROII)
  83.  
  84.      Due  to  the incompatibility between MAC  (tm)  and  MACROII
  85. (tm),  the  compiled object can only handle one format at a  time
  86. and  is  specified  at assembly time by setting  the  TDL  symbol
  87. equate  to either true or false.  You can also specify the number
  88. of lines per page by changing the symbol PGLEN.
  89.  
  90.      For  those  using  MAC (or  ASM),  re-assembly  of  XREF  is
  91. straightfoward,  requiring  only  that the TDL symbol be  set  to
  92. false.
  93.  
  94.      For those using MACROII, a slight modification to the macro-
  95. assembler   object  module  (.COM)  itself  is   required.   Full
  96. explanations  are given in the source file.  Obviously,  the  TDL
  97. symbol must be set to true.
  98.  
  99.  
  100. OPERATION:
  101. ---------
  102.  
  103.      The  operation  of  XREF  is  very  simple  as  it  will  be
  104. illustrated in the following examples:
  105.  
  106.      A help display is available by entering:
  107.  
  108.           A0>XREF <CR>
  109.  
  110.      It will also appear if an error option is detected.
  111.  
  112.      To cross-reference a file to the printer, just type:
  113.  
  114.           A0>XREF MYFILE <CR>
  115.  
  116.      XREF  will assume an extension of '.PRN' if no file type  is
  117. specified. To enter a null filetype, just type a '.' (dot) as the
  118. only extension.
  119.  
  120.      To send the output to a disk file, just append the option:
  121.  
  122.           B0>XREF MYFILE /D
  123.  
  124.      The  listing  file will be created on the current drive  and
  125. will bear the same filename but will have a '.LST'  filetype.  In
  126. the  disk  mode,  tabs are always substitued for blanks  whenever
  127. possible (tab compression).
  128.  
  129.      The  drive  designators syntax follows the  one  defined  by
  130. CP/M:
  131.           A0>b:xref c:myfile d:/d
  132.  
  133.      Would  get XREF from drive B,  the PRN file from drive C and
  134. send the LST file to disk D.
  135.  
  136.      The rest of the available options are self-explanatory.
  137.  
  138.  
  139. LIMITATIONS:
  140. -----------
  141.  
  142.      For  the  TDL version of XREF (written  in  MAC  mnemonics),
  143. there are some non standard factors:
  144.  
  145.      XREF  cannot  detect that text between a .REMARK  should  be
  146. interpreted  as  a 'multi-line' comment so here is a way  to  get
  147. around  it;  just insert '*' at the beginning of each source line
  148. that is bracketed in a .REMARK pseudo-op. Actually, a whole frame
  149. of '*' can be put around the text and looks quite nice.
  150.  
  151.      It is also difficult to accept '.' as a legal global  symbol
  152. although  TDL's syntax allows it (but '.' doesn't show up in  the
  153. symbol table generated by MACROII).  This is due to the fact that
  154. '.' is also used as the base 10 specifier and also as the current
  155. program address counter key.
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163. * MAC and CP/M are trademarks of DIGITAL RESEARCH INC.
  164. * MACROII and TDL are trademarks of COMPUTER DESIGN LABS INC.
  165.