CREF.

DOC
(C) Copyright Microsoft Corporation, 1992
This file contains information on the purpose and use of the
Microsoft(R) Cross-Reference Utility (CREF) Version 6.00.

================================< Contents >================================

This file has 4 parts:
Part Contents
---- --------
1 Introduction
2 Using CREF
3 Reading Cross-Reference Listings
4 Difference from Previous Releases

==========================< Part 1: Introduction >==========================

The Microsoft Cross-Reference Utility (CREF) creates a cross-reference
listing of all symbols in an assembly-language program. A cross-reference
listing is an alphabetical list of symbols followed by references to
where a symbol appears in the source code.
CREF is intended for use as a debugging aid to speed up the search for
symbols encountered during a debugging session. The cross-reference
listing, together with the symbol table created by the assembler, can make
debugging and correcting a program easier.

============================< Part 2: Using CREF >==========================

CREF creates a cross-reference listing for a program by converting PWB
Source Browser database files (those ending with a BSC or an SBR
extension) into a readable ASCII file.
Command-Line Syntax
-------------------
CREF crossreferencefile [, crossreferencelisting] [;]
crossreferencefile Source Browser database file. Default
filename extension is BSC.
crossreferencelisting Readable ASCII cross-reference listing.
Default filename extension is REF. If
this filename is not supplied on the
command line, the base filename of the
database file is used and the REF
extension is added.
Using Prompts to Create a Cross-Reference Listing
-------------------------------------------------
You can direct CREF to prompt you for the files it needs by starting
CREF with just the command name (CREF). CREF prompts you for the
input it needs by displaying the following lines, one at a time:
Cross-Reference [.BSC]:
Listing [filename.REF]:
The prompts correspond to the fields of the CREF command lines. CREF
waits for you to respond to each prompt before printing the next one.
You must type a cross-reference filename (extension is optional) at
the first prompt. For the second prompt, you can either type a
filename or press the ENTER key to accept the default displayed in
brackets after the prompt.

Use of PWBRMAKE with CREF

-------------------------
Note that the CREF utility can create reports only from the final form
of the Source Browser database files. These files end in BSC (Browser
Source Cache), and are created by the utility PWBRMAKE. Because ML
creates an intermediate Source Browser file (with the filename extension
SBR), CREF will invoke PWBRMAKE to create a BSC file from a single SBR
file input. PWBRMAKE takes as input the SBR files created by ML,
merges them with other SBR files created from other assembly-language
source modules (if any exist), and creates a BSC file as the result.
The BSC file contains all of the information (across multiple modules,
if necessary) to provide a comprehensive cross-listing file for an entire
project.
CREF will invoke PWBRMAKE only when a single SBR file is given as input
to the utility; therefore, you must create a BSC database file from
the assembler-generated SBR files before invoking CREF. An example
of running PWBRMAKE is:
PWBRMAKE FILENAME.SBR FILE2.SBR FILE3.SBR ... FILEN.SBR
This example creates a BSC file using the base name of the first SBR
file on the command line. In this case, the resultant file would be
named FILENAME.BSC.
By using the BSC Source Browser database files, CREF is able to provide
cross-reference files for either a single assembly-language module or
for an entire multimodule assembly-language project. Below are the
steps necessary for both scenarios.
For more information on PWBRMAKE and its available switches, see the
"Tools" section of the Macro Assembler Reference manual, or type PWBRMAKE /?
at the command line to get a quick-reference screen.

Creating Single-Module Cross-Reference Listings

-----------------------------------------------
- Using ML with the /FR switch, create an SBR file for the
assembly-language module. An example is:
ML /c /FR filename.ASM
This creates a file FILENAME.SBR (as well as FILENAME.OBJ).
 - Invoke CREF using the database file created above (FILENAME.SBR)
as the input cross-reference file. An example of this is:
CREF FILENAME.SBR, FILENAME.REF
This creates the cross-reference listing FILENAME.REF.
Note that because CREF is capable only of reading Source Browser BSC
database files, the PWBRMAKE utility is automatically invoked to
convert the SBR on the command line into a BSC file.

Creating Multimodule Cross-Reference Listings

----------------------------------------------
- Using ML with the /FR switch, create an SBR file for each of the
assembly-language modules. An example is:
ML /c /FR *.ASM
This creates a file FILENAME.SBR (as well as FILENAME.OBJ).
- Invoke CREF using the database file created above (FILENAME.BSC)
as the input cross-reference file. An example of this is:
CREF FILENAME.BSC, FILENAME.REF
The cross-reference listing FILENAME.REF is created. This
particular example will have all of the symbols from all
of the modules in one cross-reference listing file.

=================< Part 3: Reading Cross-Reference Listings >==============

The cross-reference listing contains the name of each symbol defined in
your program. Each name is followed by a list of source filenames in
which the symbol appears. Each source name is then followed by a list of
line numbers representing the line or lines in the source file in which a
symbol is referenced.
Line numbers in which a symbol is defined are marked with the number sign (#).
Example
-------
Below is a sample assembly-language source-code module, followed by
the resulting cross-reference listing file.
.DOSSEG
.MODEL small, os_dos, pascal
.STACK 100h
.DATA
PUBLIC message, lmessage
message BYTE "Hello World!!!!"
lmessage EQU $-message
.CODE
.STARTUP
 EXTERN display:NEAR
call display
mov ax, 4C00h
int 21h
.EXIT
END

Example Reference Listing (Created from above source-code module)

-----------------------------------------------------------------
Microsoft Cross-Reference Version 6.00 Mon Nov 18 15:47:26 1991

Symbol Cross-Reference (# definition) Cref-1

@code
..\hello.asm . . . . . . . . 2#
@CodeSize
..\hello.asm . . . . . . . . 2#
@data
..\hello.asm . . . . . . . . 2#
@DataSize
..\hello.asm . . . . . . . . 2#
@fardata
..\hello.asm . . . . . . . . 2#
@fardata?
..\hello.asm . . . . . . . . 2#
@Interface
..\hello.asm . . . . . . . . 2#
@Model
..\hello.asm . . . . . . . . 2#
@stack
..\hello.asm . . . . . . . . 2#
@Startup
..\hello.asm . . . . . . . . 14#
_DATA
..\hello.asm . . . . . . . . 2#
_TEXT
..\hello.asm . . . . . . . . 2# 12
DGROUP
..\hello.asm . . . . . . . . 2# 2 14
display
..\hello.asm . . . . . . . . 16 17
<Unknown>. . . . . . . . . . 1#
 hello.asm
..\hello.asm . . . . . . . . 1#
lmessage
..\hello.asm . . . . . . . . 10# 7
message
..\hello.asm . . . . . . . . 9# 10 7
STACK
..\hello.asm . . . . . . . . 4#

=================< Part 4: Difference from Previous Releases >==============

Use Differences
---------------
- ML/MASM no longer generates a CRF assembler-specific binary file.
Instead, CREF 6.0 uses the generic Source Browser database file (BSC).
Because of this, CREF can actually be used with any source-code module
or project that is compiled/assembled by a Microsoft product that
creates SBR files.
Creating multimodule cross-reference listing files is another advantage
of using BSC Browser database files. Previous releases of CREF were
limited to single modules.

Listing Differences
-------------------
- All line numbers that are reported are relative to the actual source-
code module, not the assembler-generated listing file. This is a
direct result of using the Source Browser database files (BSC). These
files are not directly related to MASM listings and are generic
across Microsoft language products.