home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c081_11 / 6.ddi / MANUAL.ZIP / TCREF.DOC < prev   
Encoding:
Text File  |  1991-02-13  |  4.8 KB  |  137 lines
  1.  
  2.           TCREF: The source module cross-reference utility
  3.           ------------------------------------------------
  4.  
  5. TABLE OF CONTENTS
  6. -----------------
  7. 1. What is TCREF?
  8. 2. How to Use TCREF
  9. 3. Compatibility with TLINK
  10. 4. TCREF Options
  11. 5. TCREF Reports
  12.  
  13.  
  14. 1. WHAT IS TCREF?
  15. -----------------
  16.  
  17.   TCREF is designed to produce two reports: a cross-reference list of where 
  18.   all global symbols are used and defined, and a list of individual modules 
  19.   and the symbols used within them.
  20.  
  21.  
  22. 2. HOW TO USE TCREF
  23. -------------------
  24.  
  25.   TCREF accepts as input a group of .XRF files produced by TASM. These files 
  26.   contain cross-reference information for individual modules. From these input 
  27.   files, a single .REF file is produced that contains one or more reports in 
  28.   ASCII text. The command format follows:
  29.  
  30.     TCREF <XRF files separated by '+' characters> ','
  31.        <REF filename> <switches>
  32.  
  33.   For example, the following would take the FOO1.XRF, FOO2.XRF, and FOO3.XRF 
  34.   as input files and produce FOO.REF:
  35.  
  36.     TCREF foo1+foo2+foo3,foo
  37.  
  38.   Response files
  39.   ---------------
  40.   TCREF also accepts ASCII files as command strings. Simply precede the file 
  41.   name with an @ sign to include a file in the command string. For example,
  42.  
  43.     TCREF @dofoo
  44.  
  45.   where DOFOO contains
  46.  
  47.     foo1+foo2+foo3,foo
  48.  
  49.   will do the same thing as the previous example.
  50.  
  51.  
  52. 3. COMPATIBILITY WITH TLINK
  53. ---------------------------
  54.  
  55.   TCREF accepts command strings that TLINK accepts. TCREF ignores any 
  56.   irrelevant switches and fields, such as any libraries or MAP files, or
  57.   switches that pertain only to the linker function. Similarly, if an .XRF 
  58.   file cannot be located, TCREF will simply ignore it.
  59.  
  60.   Beware! When using a TLINK response file, don't explicitly specify file 
  61.   extensions, since doing so will override TCREF's internal defaults and 
  62.   possibly result in disaster. For example, if the response file reads aS
  63.  
  64.     foo1+foo2+foo3,foo.exe
  65.  
  66.   you should not use this file without modification with TCREF because the 
  67.   .REF file it creates will be named FOO.EXE, presumably overwriting your 
  68.   program.
  69.  
  70.  
  71. 4. TCREF OPTIONS
  72. ----------------
  73.  
  74.   TCREF accepts all the switches present in TLINK, but most of them are 
  75.   discarded. TCREF only uses these options:
  76.  
  77.     /c makes GLOBAL report case-sensitive.
  78.  
  79.     /r generates LOCAL reports for all the specified modules.
  80.  
  81.     /p# sets report page length to # lines.
  82.  
  83.     /w# sets report page width to # columns.
  84.  
  85.  
  86. 5. TCREF REPORTS
  87. ----------------
  88.  
  89.   TCREF takes great care to make semantic sense of symbols. Cross-reference
  90.   information is useless when symbols with the same name but different
  91.   meanings are lumped together. TCREF therefore takes into account the
  92.   SCOPE of a symbol when producing its reports. Cross-reference information
  93.   is always listed for the source file and source line number.
  94.  
  95.   Global (or linker-scope) report
  96.   -------------------------------
  97.  
  98.   TCREF's global report lists cross-reference information for global symbols 
  99.   as they appear to the linker. Use the /c switch if you want to produce 
  100.   case-sensitive reports.
  101.  
  102.   In this report, global symbols appear alphabetically in the left column.
  103.   References, organized by source file, are listed in the right column.
  104.   Wherever #'s appear indicates that definition occurs at that line.
  105.  
  106.   Here's an example symbol printout:
  107.  
  108.     Global Symbols       Cref  #  = definition
  109.     BAR                  TEST.ASM:  1  3  6  9  12  15  18 +
  110.                                                 21  23  29
  111.                                           #  TEST2.ASM:  2  4  6  #8
  112.  
  113.   What does this tell you? The leading # sign before the TEST2.ASM indicates 
  114.   that BAR was defined somewhere in that module. For each source file, the 
  115.   source line at which the reference occurred is listed. This list can occupy
  116.   more than one line, as in the case of the lines for TEST.ASM. The + 
  117.   character indicates that wrap has occurred. Finally, the # sign before the 
  118.   8 indicates that a definition of BAR occurred in TEST2.ASM on line 8.
  119.  
  120.   The local (or module-scope) report
  121.   ----------------------------------
  122.  
  123.   If you specify /r on the command line, a local report will be made for
  124.   each module. It will contain all the symbols used in that module, listed 
  125.   in alphabetical order. The /c switch will have no effect on these reports, 
  126.   since the appropriate case-sensitivity has already been determined at 
  127.   assembly time.
  128.  
  129.   Like global reports, references are organized by source file in the right 
  130.   column. A sample printout looks like this:
  131.  
  132.     Module TEST.ASM Symbols        Cref  # = definition
  133.     UGH                            TEST.ASM:  1  3  6  9  12  15  18 +
  134.                                                           21  23  29
  135.                                                    #  UGH.INC:  #2
  136.  
  137.