home *** CD-ROM | disk | FTP | other *** search
/ Programming Languages Suite / ProgramD2.iso / Languages / Masm V6.11 / BIN / CREF.DO$ / CREF
Encoding:
Text File  |  1992-01-27  |  9.9 KB  |  281 lines
  1.  
  2.                                  CREF.DOC
  3.  
  4.                   (C) Copyright Microsoft Corporation, 1992
  5.  
  6.      This file contains information on the purpose and use of the
  7.      Microsoft(R) Cross-Reference Utility (CREF) Version 6.00.
  8.  
  9.  
  10. ================================< Contents >================================
  11.  
  12.  This file has 4 parts:
  13.  
  14.                Part     Contents
  15.                ----     --------
  16.                1        Introduction
  17.  
  18.                2        Using CREF
  19.  
  20.                3        Reading Cross-Reference Listings
  21.  
  22.                4        Difference from Previous Releases
  23.  
  24.  
  25.  
  26. ==========================< Part 1: Introduction >==========================
  27.  
  28.  The Microsoft Cross-Reference Utility (CREF) creates a cross-reference
  29.  listing of all symbols in an assembly-language program.  A cross-reference
  30.  listing is an alphabetical list of symbols followed by references to
  31.  where a symbol appears in the source code.
  32.  
  33.  CREF is intended for use as a debugging aid to speed up the search for
  34.  symbols encountered during a debugging session.  The cross-reference
  35.  listing, together with the symbol table created by the assembler, can make
  36.  debugging and correcting a program easier.
  37.  
  38.  
  39. ============================< Part 2: Using CREF >==========================
  40.  
  41.  CREF creates a cross-reference listing for a program by converting PWB
  42.  Source Browser database files (those ending with a BSC or an SBR
  43.  extension) into a readable ASCII file.
  44.  
  45.     Command-Line Syntax
  46.     -------------------
  47.  
  48.         CREF crossreferencefile [, crossreferencelisting] [;]
  49.  
  50.             crossreferencefile      Source Browser database file. Default
  51.                                     filename extension is BSC.
  52.  
  53.             crossreferencelisting   Readable ASCII cross-reference listing.
  54.                                     Default filename extension is REF. If
  55.                                     this filename is not supplied on the
  56.                                     command line, the base filename of the
  57.                                     database file is used and the REF
  58.                                     extension is added.
  59.  
  60.     Using Prompts to Create a Cross-Reference Listing
  61.     -------------------------------------------------
  62.     You can direct CREF to prompt you for the files it needs by starting
  63.     CREF with just the command name (CREF).  CREF prompts you for the
  64.     input it needs by displaying the following lines, one at a time:
  65.  
  66.         Cross-Reference [.BSC]:
  67.         Listing [filename.REF]:
  68.  
  69.     The prompts correspond to the fields of the CREF command lines. CREF
  70.     waits for you to respond to each prompt before printing the next one.
  71.     You must type a cross-reference filename (extension is optional) at
  72.     the first prompt.  For the second prompt, you can either type a
  73.     filename or press the ENTER key to accept the default displayed in
  74.     brackets after the prompt.
  75.  
  76.  
  77.     Use of PWBRMAKE with CREF
  78.     -------------------------
  79.     Note that the CREF utility can create reports only from the final form
  80.     of the Source Browser database files.  These files end in BSC (Browser
  81.     Source Cache), and are created by the utility PWBRMAKE. Because ML
  82.     creates an intermediate Source Browser file (with the filename extension
  83.     SBR), CREF will invoke PWBRMAKE to create a BSC file from a single SBR
  84.     file input.  PWBRMAKE takes as input the SBR files created by ML,
  85.     merges them with other SBR files created from other assembly-language
  86.     source modules (if any exist), and creates a BSC file as the result.
  87.     The BSC file contains all of the information (across multiple modules,
  88.     if necessary) to provide a comprehensive cross-listing file for an entire
  89.     project.
  90.  
  91.     CREF will invoke PWBRMAKE only when a single SBR file is given as input
  92.     to the utility; therefore, you must create a BSC database file from
  93.     the assembler-generated SBR files before invoking CREF.  An example
  94.     of running PWBRMAKE is:
  95.  
  96.         PWBRMAKE FILENAME.SBR FILE2.SBR FILE3.SBR ... FILEN.SBR
  97.  
  98.     This example creates a BSC file using the base name of the first SBR
  99.     file on the command line.  In this case, the resultant file would be
  100.     named FILENAME.BSC.
  101.  
  102.     By using the BSC Source Browser database files, CREF is able to provide
  103.     cross-reference files for either a single assembly-language module or
  104.     for an entire multimodule assembly-language project.  Below are the
  105.     steps necessary for both scenarios.
  106.  
  107.     For more information on PWBRMAKE and its available switches, see the
  108.     "Tools" section of the Macro Assembler Reference manual, or type PWBRMAKE /?
  109.     at the command line to get a quick-reference screen.
  110.  
  111.  
  112.     Creating Single-Module Cross-Reference Listings
  113.     -----------------------------------------------
  114.        - Using ML with the /FR switch, create an SBR file for the
  115.          assembly-language module.  An example is:
  116.  
  117.             ML /c /FR filename.ASM
  118.  
  119.          This creates a file FILENAME.SBR (as well as FILENAME.OBJ).
  120.  
  121.        - Invoke CREF using the database file created above (FILENAME.SBR)
  122.          as the input cross-reference file.  An example of this is:
  123.  
  124.             CREF FILENAME.SBR, FILENAME.REF
  125.  
  126.          This creates the cross-reference listing FILENAME.REF.
  127.  
  128.          Note that because CREF is capable only of reading Source Browser BSC
  129.          database files, the PWBRMAKE utility is automatically invoked to 
  130.          convert the SBR on the command line into a BSC file.
  131.  
  132.  
  133.     Creating Multimodule Cross-Reference Listings
  134.     ----------------------------------------------
  135.        - Using ML with the /FR switch, create an SBR file for each of the
  136.          assembly-language modules.  An example is:
  137.  
  138.             ML /c /FR *.ASM
  139.  
  140.          This creates a file FILENAME.SBR (as well as FILENAME.OBJ).
  141.  
  142.        - Invoke CREF using the database file created above (FILENAME.BSC)
  143.          as the input cross-reference file.  An example of this is:
  144.  
  145.             CREF FILENAME.BSC, FILENAME.REF
  146.  
  147.          The cross-reference listing FILENAME.REF is created.  This
  148.          particular example will have all of the symbols from all
  149.          of the modules in one cross-reference listing file.
  150.  
  151.  
  152. =================< Part 3: Reading Cross-Reference Listings  >==============
  153.  
  154.  The cross-reference listing contains the name of each symbol defined in
  155.  your program.  Each name is followed by a list of source filenames in
  156.  which the symbol appears.  Each source name is then followed by a list of
  157.  line numbers representing the line or lines in the source file in which a
  158.  symbol is referenced.
  159.  
  160.  Line numbers in which a symbol is defined are marked with the number sign (#).
  161.  
  162.     Example
  163.     -------
  164.     Below is a sample assembly-language source-code module, followed by
  165.     the resulting cross-reference listing file.
  166.  
  167.                     .DOSSEG
  168.                     .MODEL small, os_dos, pascal
  169.  
  170.                     .STACK 100h
  171.  
  172.                     .DATA
  173.                     PUBLIC message, lmessage
  174.  
  175.         message     BYTE    "Hello World!!!!"
  176.         lmessage    EQU     $-message
  177.  
  178.                     .CODE
  179.  
  180.                     .STARTUP
  181.  
  182.                     EXTERN display:NEAR
  183.                     call   display
  184.                     mov    ax, 4C00h
  185.                     int    21h
  186.  
  187.                     .EXIT
  188.                     END
  189.  
  190.  
  191.     Example Reference Listing (Created from above source-code module)
  192.     -----------------------------------------------------------------
  193.  
  194.         Microsoft Cross-Reference  Version 6.00       Mon Nov 18 15:47:26 1991
  195.  
  196.  
  197.           Symbol Cross-Reference       (#  definition)  Cref-1
  198.  
  199.         @code
  200.             ..\hello.asm . . . . . . . .    2#
  201.  
  202.         @CodeSize
  203.             ..\hello.asm . . . . . . . .    2#
  204.  
  205.         @data
  206.             ..\hello.asm . . . . . . . .    2#
  207.  
  208.         @DataSize
  209.             ..\hello.asm . . . . . . . .    2#
  210.  
  211.         @fardata
  212.             ..\hello.asm . . . . . . . .    2#
  213.  
  214.         @fardata?
  215.             ..\hello.asm . . . . . . . .    2#
  216.  
  217.         @Interface
  218.             ..\hello.asm . . . . . . . .    2#
  219.  
  220.         @Model
  221.             ..\hello.asm . . . . . . . .    2#
  222.  
  223.         @stack
  224.             ..\hello.asm . . . . . . . .    2#
  225.  
  226.         @Startup
  227.             ..\hello.asm . . . . . . . .   14#
  228.  
  229.         _DATA
  230.             ..\hello.asm . . . . . . . .    2#
  231.  
  232.         _TEXT
  233.             ..\hello.asm . . . . . . . .    2#    12
  234.  
  235.         DGROUP
  236.             ..\hello.asm . . . . . . . .    2#     2     14
  237.  
  238.         display
  239.             ..\hello.asm . . . . . . . .   16     17
  240.             <Unknown>. . . . . . . . . .    1#
  241.  
  242.         hello.asm
  243.             ..\hello.asm . . . . . . . .    1#
  244.  
  245.         lmessage
  246.             ..\hello.asm . . . . . . . .   10#     7
  247.  
  248.         message
  249.             ..\hello.asm . . . . . . . .    9#    10      7
  250.  
  251.         STACK
  252.             ..\hello.asm . . . . . . . .    4#
  253.  
  254.  
  255. =================< Part 4: Difference from Previous Releases >==============
  256.  
  257.  
  258.    Use Differences
  259.    ---------------
  260.  
  261.     - ML/MASM no longer generates a CRF assembler-specific binary file.
  262.       Instead, CREF 6.0 uses the generic Source Browser database file (BSC).
  263.  
  264.       Because of this, CREF can actually be used with any source-code module
  265.       or project that is compiled/assembled by a Microsoft product that
  266.       creates SBR files.
  267.  
  268.       Creating multimodule cross-reference listing files is another advantage
  269.       of using BSC Browser database files.  Previous releases of CREF were
  270.       limited to single modules.
  271.  
  272.  
  273.    Listing Differences
  274.    -------------------
  275.  
  276.     - All line numbers that are reported are relative to the actual source-
  277.       code module, not the assembler-generated listing file.  This is a
  278.       direct result of using the Source Browser database files (BSC).  These
  279.       files are not directly related to MASM listings and are generic
  280.       across Microsoft language products.
  281.