home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
REF.ZIP
/
REF.DOC
< prev
next >
Wrap
Text File
|
1991-07-15
|
66KB
|
1,706 lines
REF 1.0
A Source Information System
for Microsoft (R) Languages
A Shareware Product
=================================
Copyright (C) 1991
All Rights Reserved
The Cove Software Group
Post Office Box 1072
Columbia, MD 21044
301/992-9371
CompuServe 76703,2002
REF Version 1.0
User's Guide Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . 1
1.1 What is REF? . . . . . . . . . . . . . . . . . . . 1
1.2 Registration . . . . . . . . . . . . . . . . . . . 1
2 Getting Started. . . . . . . . . . . . . . . . . . . . . 2
2.1 System requirements. . . . . . . . . . . . . . . . 2
2.2 Printing the User's Guide. . . . . . . . . . . . . 2
2.3 Installing PWBRMAKE. . . . . . . . . . . . . . . . 2
2.4 Installing REF . . . . . . . . . . . . . . . . . . 3
2.5 Preparing your projects. . . . . . . . . . . . . . 4
2.6 Using NMAKE. . . . . . . . . . . . . . . . . . . . 5
3 Using REF. . . . . . . . . . . . . . . . . . . . . . . . 6
3.1 REF services . . . . . . . . . . . . . . . . . . . 6
3.2 Symbol types, attributes, and instances. . . . . . 7
3.3 Running REF. . . . . . . . . . . . . . . . . . . . 8
3.3.1 Syntax . . . . . . . . . . . . . . . . . . . 8
3.3.2 Specifying the input file. . . . . . . . . . 9
3.3.3 Specifying options . . . . . . . . . . . . . 9
3.3.4 Specifying symbol names. . . . . . . . . . . 10
3.3.5 Specifying actions . . . . . . . . . . . . . 10
3.3.6 Specifying symbol-type filters . . . . . . . 12
3.3.7 Specifying attribute filters . . . . . . . . 13
4 Report contents. . . . . . . . . . . . . . . . . . . . . 14
4.1 Cross-reference (/X) . . . . . . . . . . . . . . . 15
4.2 Call trees (/T and /Tx). . . . . . . . . . . . . . 17
4.2.1 Forward call trees (/T). . . . . . . . . . . 17
4.2.1.1 Subtrees and levels. . . . . . . . . . 17
4.2.1.2 Recursion. . . . . . . . . . . . . . . 18
4.2.1.3 Indirect calls . . . . . . . . . . . . 19
4.2.1.4 Symbols required . . . . . . . . . . . 20
4.2.2 Reverse call trees . . . . . . . . . . . . . 20
4.3 Calls and Called-by (/C and /Cx) . . . . . . . . . 21
4.4 Uses/used-by (/U, /Ux) . . . . . . . . . . . . . . 21
4.5 Module list (/M) . . . . . . . . . . . . . . . . . 22
4.6 Unreferenced symbols (/N). . . . . . . . . . . . . 23
4.7 Outline (/O) . . . . . . . . . . . . . . . . . . . 24
4.8 Dump (/D, /Dm, /Ds). . . . . . . . . . . . . . . . 25
5 Messages . . . . . . . . . . . . . . . . . . . . . . . . 26
1 Introduction
1.1 What is REF?
REF is a utility that can provide considerable information
about projects developed under the Microsoft (R)
Professional Development System. REF provides information
about functions, variables, macros, and other symbols in a
variety of formats, including cross references, uses/used-by
tables, call trees, etc. It is especially useful for
projects developed using multiple languages (C and
assembler, for example) because it is language independent
and makes no attempt at source-parsing--parsing is handled
by the language processor itself.
Both DOS and OS/2 versions of REF are provided. To use REF,
you must have a Microsoft Programmer's Workbench ("PWB")
compatible language, but you do not have to actually use the
PWB.
1.2 Registration
After many years of providing free software for public use
(over seventy-five programs before we lost track), we are
bowing to reality and releasing REF as our first shareware
offering.
If you continue to use REF after a reasonable evaluation
period, you are required to register your use with us and
pay a modest license fee. There are two levels of
registration:
$20 - basic registration. You receive the current
version of REF without the shareware information
screen, and a paid invoice.
$35 - full registration. You receive the above plus
a printed copy of the manual, a Microsoft
QuickHelp compatible help file, and a free upgrade
to the next release of REF.
This package is not "crippled" in any way. No features are
disabled, and this document is complete. The registered
version of REF.EXE is identical except that it does not
display the shareware information.
Please see the REGISTER.DOC and LICENSE.DOC for registraion
forms, licenses and warranty, etc.
REF USER'S GUIDE - 1
2 Getting Started
2.1 System requirements
REF requires DOS 2.0 or later, or OS/2.
To use REF, you must develop your projects using Microsoft's
"Professional Development System" languages. These are the
MS products such as Microsoft C 6.x and Microsoft Macro
Assembler (MASM) 6.x with which are included the
Programmer's Workbench (PWB).
You do NOT have to install or use the PWB in order to make
full use of REF, but you must have a PWB-compatible version
of the language compiler or assembler.
If you develop a project in multiple languages and not all
of the languages are PWB-compatible (say, MSC 6.0 with MASM
5.x or TASM), you can use REF on the PWB-compatible portion
of the project.
2.2 Printing the User's Guide
To print the User's Guide, simply turn on your printer and
type
COPY [d:path]REF.DOC PRN
where d:path, of course, represents the drive and directory
that contains REF.DOC (this file).
2.3 Installing PWBRMAKE
Although REF does not require that the PWB be installed, it
does require one PWB-related program, namely, PWBRMAKE.EXE.
If you do not have PWBRMAKE.EXE on your fixed disk, you must
first install it as follows:
1. Locate the "SETUP" or "INSTALLATION" diskette for
your MS language product.
2. Find and view the file PACKING.LST on the setup
diskette. Locate the entry for PWBRMAKE.EXE; this will
tell you which diskette and directory contains the
PWBRMAKE program. Make a note of this information.
3. If PWBRMAKE is not located on the setup diskette:
a. Copy the program DECOMP.EXE from the setup
diskette to a working directory on your fixed disk.
REF USER'S GUIDE - 2
b. Remove the setup diskette and insert the PWBRMAKE
diskette.
4. Select a directory on your fixed disk where you will
keep PWBRMAKE. PWBRMAKE is a bound (family mode)
executable that will run under either DOS or OS/2, so it
will usually go into the BINB directory (\C\BINB,
\MASM\BINB, etc.) along with LINK, LIB, etc.
5. Install the compressed file PWBRMAKE.EX$ from the
diskette by running the DECOMP program. Just type
DECOMP
and, at the DECOMP first prompt, enter
d:path\pwbrmake.ex$
where 'd:path' is the installation drive and directory
that contains PWBRMAKE (usually A:\BINB).
At the second DECOMP prompt, enter:
d:path\pwbrmake.exe
where d:path represents the drive and directory you have
selected for permanent storage of PWBRMAKE.
6. Installation of PWBRMAKE is now complete. If you
copied DECOMP from the diskette to your fixed disk in
step 3, you can erase it if you wish.
2.4 Installing REF
If you're writing programs for DOS or OS/2, we're going to
assume that you know how to copy files, so this will be
simple.
You should have received all of the following files:
PACKING.LST A list of files that should be included
REGISTER.DOC Registration information
LICENSE.DOC License/redistribution information
WARRANTY.DOC Warranty information
REFDOS.EXE DOS version of the REF program
REFOS2.EXE OS/2 version of the REF program
REF.DOC This document
DEMO1.C First module of a simple demo "project"
DEMO2.C Second module of the demo
DEMO.MAK Make file for making the demo
DEMO.BSC Browser database for demo
If any of these files are missing, you have not received the
REF USER'S GUIDE - 3
complete package, which is a violation of our redistribution
agreement. Please contact your source and request that they
obtain the complete evaluation package before distributing
it.
Installation is simply a matter of copying the appropriate
version(s) of the REF program to your fixed disk.
REFDOS.EXE is the DOS version; REFOS2 is the OS/2 version.
Copy either one (or both) and rename to a more usable
name--we suggest REF.EXE for DOS and REFP.EXE for OS/2. We
suggest that you keep the REF program in the same directory
as your compiler or assembler executables.
For example:
COPY REFDOS.EXE C:\C\BIN\REF.EXE (DOS)
COPY REFOS2.EXE C:\C\BINP\REFP.EXE (OS/2)
Copy the remaining files to a convenient working directory
for review (they are not required to run REF). Please print
and review REGISTER.DOC for registration information,
LICENSE.DOC for license information, and WARRANTY.DOC for
warranty information. The DEMO*.* files contain a simple
demonstration program that is used for many of the report
samples in the User's Guide.
2.5 Preparing your projects
Before using REF, you must prepare a database containing
information about the project at hand. This is handled
entirely by the language processor (compiler and/or
assembler) and by PWBRMAKE. Two steps are involved:
First, compile or assemble source modules using the option
switch that prepares "source browser" information for the
PWB. Normally, this is the /FR option (you can use /Fr for
a more limited browser database). For example:
cl /FR file1.c file2.c
ml /FR filea.asm fileb.asm
This creates a raw browser information file for each module,
using the name module.SBR (e.g., FILE1.SBR and FILE2.SBR in
the first example).
Second, create a browser database from the raw files using
PWBRMAKE. The basic syntax you will use is:
PWBRMAKE /o output-name input-name(s)
For example:
PWBRMAKE /o test test1.sbr test2.sbr
REF USER'S GUIDE - 4
This creates the database TEST.BSC from the two raw files
created in the first example (you can erase the raw files
after running PWBRMAKE, by the way).
You can use wildcards:
PWBRMAKE /o test test?.sbr
or
PWBRMAKE /o test *.sbr
(the latter processes ALL of the .SBR files in the current
directory).
If you plan to search for unreferenced symbols (those which
are defined but never used), add the /Iu option:
PWBRMAKE /Iu /o test *.sbr
See your online help for more information about PWBRMAKE.
2.6 Using NMAKE
You may find it easier to use "make" files for maintaining
the REF/browser database. Essentially, all you have to do
is:
1. Add /FR to the compilation or assembly commands.
2. Run PWBRMAKE after linking.
3. Optionally, erase the .SBR files after PWBRMAKE.
Consider the following simple makefile that creates MYPROG
from MOD1.C, MOD2.C, and MODA.ASM. It manages compiling,
assembling, linking, and creating the database; all you have
to do is type "NMAKE":
# -----------------------------------------
# MYPROG MAKEFILE
#
# Primary target
myprog.exe: mod1.obj mod2.obj moda.obj
link mod1+mod2+moda,myprog;
pwbrmake /Iu /o myprog *.sbr
erase *.sbr
# Subsidiary targets
mod1.obj: mod1.c
cl /c /FR mod1.c
mod2.obj: mod2.c
cl /c /FR mod2.c
REF USER'S GUIDE - 5
moda.obj: moda.asm
ml /c /FR moda.asm
See your documentation and online help for more information
about NMAKE.
3 Using REF
3.1 REF services
REF provides the following information about a project that
has been prepared as described above. In the list below,
note that a "symbol" can be almost any symbolic name (a
function or procedure, constant, typedef, structure, union,
macro, whatever); REF can provide information about any
specific symbol(s) or about ALL symbols in the database.
Also note that the word "function" is used to mean a named
section of code, i.e., a subroutine. In some languages
these may be called procedures, PROCs, etc.; however, REF
always refers to these as "functions."
The available information is:
CALLS and CALLED-BY: all of the functions that a
function calls directly, and all of the functions that
call a function directly.
CALL TREE and REVERSE CALL TREE: complete call trees
showing how a function is called (e.g., main() calls
foo(), which calls fun1(), which calls fun2(), etc.).
CROSS-REFERENCES: cross-reference information for any
symbol(s) in the database. The cross reference lists
the source file name and line number where each symbol
is defined and where it is referenced.
DUMP: a comprehensive "dump" of all information
contained in the database (can be voluminous for larger
projects!).
OUTLINE: a listing of modules included in the database
and the symbols that are contained in each module.
UNREFERENCED SYMBOLS: all of the symbols that are
defined but not used anywhere.
MODULES: a simple list of the modules included in the
database.
USES and USED-BY: all of the symbols that a function
uses, and all of the functions that use a symbol.
REF USER'S GUIDE - 6
All REF output is sent to the screen. It can be redirected
or piped, of course, if desired:
REF /X > xref.txt
REF /X | MORE
3.2 Symbol types, attributes, and instances
Before we finally get into the mechanics of running REF, we
should briefly discuss "symbols". A symbol is the name of
some object in your program. It could belong to any of a
dozen or so different classes of symbols: functions,
variables, constants, structures and unions, parameters,
etc. These classes of symbols are called "symbol types".
Each symbol, in addition to belonging to one of the
supported types, has one or more "attributes": public,
local, static, etc.
A single combination of a name + type + attributes is called
an "instance". Examine the following code:
int intvar;
func1()
{
int intvar;
...
}
func2()
{
int intvar;
intvar = 1;
}
func3()
{
intvar = 1;
}
There are three definitions but only two instances of the
variable intvar. This is because the intvars in func1 and
func2 are identical: they are both of type VARIABLE, with
attribute LOCAL, and the name 'intvar'. These constitute
one instance of intvar. The global intvar is a second
instance--it is also a VARIABLE named 'intvar', but it has
the PUBLIC attribute rather than LOCAL.
Unfortunately, the browser database does not provide much
information to distinguish between multiple occurrences of
an instance. In the above example, REF does NOT know
whether the assignment to intvar in func2 is a reference to
REF USER'S GUIDE - 7
func1's intvar or to func2's intvar. It DOES know, however,
that the assignment in func3 is a reference to the global
intvar and not to either of the local ones.
3.3 Running REF
3.3.1 Syntax
Basic syntax for for the DOS version of REF is:
REF [/?] [/Ifile] [options] [symbols] [/actions]
[/Ffilters] [/Aattribute-filters]
The OS/2 version operates in the same manner as the DOS
version. The only difference is that the program is named
REFP rather than REF:
REFP [/?] [/Ifile] [options] [symbols] [/actions]
[/Ffilters] [/Aattribute-filters]
In the remainder of this document, all command examples will
show "REF"; simply substitute "REFP" for OS/2.
The /? option displays a brief help screen. All other
options are ignored if /? is present.
The "file" parameter specifies the name of the reference
database. If no file is specified, REF uses the first .BSC
database in the current directory.
The "options" are miscellaneous options that affect this run
of REF.
The "symbols" are the specific symbols in which you're
interested. If no symbols are listed, REF assumes you mean
"all qualifying symbols."
The "actions" specify the information that you want to see
(call tree, cross reference, etc.). You can specify as many
actions as you want per run. If no actions are specified,
REF assumes that you want a cross-reference.
The "filters" specify the kinds of symbols you are
interested in. In most cases, REF defaults to functions,
variables, and macros, but you can specify any kinds of
symbols you want.
The "attribute filters" allow you to include objects with
certain attributes (for example, local objects such as
variables declared within functions) that REF would normally
ignore. If no attribute filters are specified, REF
suppresses information on local symbols and on symbols that
are declared but not defined.
REF USER'S GUIDE - 8
All of the parameters are optional; if no parameters at all
are specified, REF prepares a cross reference for all
non-local functions, macros, and variables for the first
.BSC file in the current directory. This is equivalent to:
REF /X /Ffmv name.bsc
The REF command line is non-positional: arguments may be
specified in any order. Switches are not case-sensitive in
the current version; however, we reserve the right to make
them case-sensitive in future versions. We suggest that you
use the switches exactly as shown in the document. Switches
may be introduced by either '/' or '-' and may be
concatenated or listed separately; however, each switch must
have its own switch character (/ or -):
/C/T /C /T -C -T -C-T
Detailed information about each of the arguments follows.
3.3.2 Specifying the input file
Use the /I switch to specify the name of the input database
file. The name must follow the switch immediately, with no
intervening spaces. Include a drive and path if the
database is not in the current drive/directory. If no
extension is supplied, .BSC is assumed. Examples:
REF /Imyproj.bsc
REF /Id:\c\source\myproj.bsc
REF /Imyproj [assumes MYPROJ.BSC]
If no input filename is specified, REF assumes that you mean
the first file with a .BSC extension in the current
database.
REF always lists the database filename when it runs.
3.3.3 Specifying options
The current release of REF supports only one option. This
is the /Ex (Exlude eXtensions) option:
/Ex[(extension[,extension])]
This option affects only the /N (unreferenced symbols)
action; it suppresses information about unreferenced symbols
contained in files that match the specified extensions. /Ex
is intended primarily to suppress reports about unreferenced
symbols defined in header files.
REF USER'S GUIDE - 9
For example, the command
REF /N /Ex(H,INC)
would not display information about unreferenced symbols
that are defined in files with .H and .INC extensions.
No spaces may occur anywhere in the option. If no extension
is specified, the extension .H is assumed.
3.3.4 Specifying symbol names
REF assumes that any arguments that do not begin with a
switch character (/ or -) are the names of symbols about
which you want information. These can be the names of
symbols of any supported types, which are:
Functions or procedures (PROCs, in assembler)
Variables
Macros
Structure names
Union names
Function parameters
Named constants
Type definitions
Enumerated type names ("enumnam")
Enumerated type members ("enummem")
Segments
Groups
For the /O option only, the symbols should be module names
(i.e., the names of source files).
You can specify up to 40 symbol names, if you have room on
the command line.
Symbol names are case sensitive if the underlying module is
case sensitive (e.g., C symbols are case sensitive, but
assembler symbols may not be).
If no symbols are specified, REF assumes that you mean all
qualifying symbols, i.e., all symbols in the database that
meet the filter criteria (see below).
Example:
REF main myvar mymacro myconst /Iproject.bsc
3.3.5 Specifying actions
Actions specify the type(s) of information you want.
Further details about the format of each of these reports
REF USER'S GUIDE - 10
are given in separate secions below.
Valid action options are:
/C Calls: display all functions that the specified
symbols call. The symbols you specify should, of
course, also be functions. If no symbols are
specified, REF assumes "all functions", so you will
see a listing of all functions in the database along
with a list of the functions that each one calls.
/Cx Called by: display all functions that call the
specified symbols. The symbols you specify should,
of course, also be functions. If no symbols are
specified, REF assumes "all functions", so you will
see a listing of all functions in the database along
with a list of the functions that call each one.
/D Dump: a complete dump of all information in the
database. Any symbols given on the command line are
ignored.
/M Modules: display a list of the modules included in
the database.
/N Unreferenced symbols: display a list of symbols
that are defined/declared but never used. Any
symbols given on the command line are ignored.
/O Outline: display an outline of the modules
contained in the database, i.e., a list of all
symbols and their types for each module. Symbols on
the command line, if present, should be module
names.
/T Call tree: display a "tree" of calls descending
from each specified symbol. The symbols specified
should, of course, be functions.
/Tx Reverse call tree: display a "reverse tree" of
calls ascending from each specified symbol, i.e.,
all possible paths of execution to reach a
particular function.
/U Uses: display a list of all symbols that each of
the specified symbols uses, i.e., references. The
specified symbols should be functions.
/Ux Used by: display a list of all functions that use,
i.e., reference, each of the specified symbols.
/X Cross-reference: display a cross-reference for each
specified symbol, i.e., a list of each definition of
the symbol and each reference to the symbol.
Up to twenty actions can be specified per run (that's enough
REF USER'S GUIDE - 11
to use all of the possible actions, some more than once).
If no actions are specified, /X is assumed. If multiple
actions are requested, reports are displayed in the order
the action options appear on the command line.
Examples:
REF /C func1
Display a list of all functions that func1 calls
REF /Cx func1 func2
Display a list of all functions that call func1
or func2
REF /C/Cx func1
Display both lists for func1
REF /C/U
Display call lists and and "uses" information
for all symbols.
3.3.6 Specifying symbol-type filters
The browser database contains information about a dozen
different symbol types. By default, REF displays only
information about functions, variables, and macros when
generating the uses/used-by, cross-reference, and outline
reports.
If you want information about the other types, you can
obtain it by specifying a "filter" with the /F option. This
option is followed by a list of one or more type codes,
which are:
f Functions or procedures (PROCs, in assembler)
v Variables
m Macros
s Structure names
u Union names
p Function parameters
c Named constants
t Type definitions
e Enumerated type names ("enumnam")
n Enumerated type members ("enummem")
x Segments
g Groups
* All of the above
The default filter is /Fmvf (macros, variables, functions).
You can specify that you want information about as many
types as you wish. For example, the following command
requests cross-reference information about structures,
unions, typedefs, parameters, and constants:
REF USER'S GUIDE - 12
REF /X /Fsutpc
To obtain cross reference information about ALL symbols:
REF /X /F*
Remember that the filter setting does not affect the other
REF reports. Also note that many databases do not contain
information about all of the symbol types shown above.
3.3.7 Specifying attribute filters
In the uses/used-by and cross-reference reports, REF
normally suppresses references to symbols with either or
both of the following attributes:
1. Local: symbols that are defined within a local context
such as a function or procedure. It's usually not necessary
to see cross reference information, for example, for
strictly local variables; the filter eliminates such
information (otherwise most C programmers would see a large
volume of reference information on common "counting"
variables like 'i').
2. Declaration-only: symbols that are only declared, not
defined. The most common symbols with the "decl-only"
attribute are library functions and variables. They are
declared in a header file, but the definition is located in
the library source--which you probably don't have and which
is usually not included in the project database.
If you wish to include symbols with local and/or
declaration-only attributes in your uses/used-by and
cross-reference reports, use the "attribute filter" switch,
/A. This switch is followed by one or two characters, as
follows:
l Include Local symbols
d Include Declaration-only symbols
For example, this command includes local and decl-only
symbols with its cross-reference:
ref /X /Adl
Unlike the type filter (/F), which is EXCLUSIVE, the
attribute filter is INCLUSIVE. Symbols with the specified
attributes are added to the reports--but symbols with other
attributes are still included.
REF USER'S GUIDE - 13
4 Report contents
This section of the REF document describes all of the
reports REF can generate. Most of the report samples assume
the following do-nothing two-module C program. For the sake
of the brevity of the sample reports, we do not #include
stdio.h. Line numbers are shown in ():
MODULE DEMO1.C:
( 1) int j;
( 2) extern void sub2(int);
( 3) #define C 1
( 4) static int sub1(void);
( 5)
( 6) main ()
( 7) {
( 8) int i;
( 9) sub1();
(10) i = 1;
(11) j = 2;
(12) }
(13)
(14) static int sub1 ()
(15) {
(16) int i;
(17) i = 1;
(18) sub2(i);
(19) }
MODULE DEMO2.C:
(1) #define inc(k) (++k)
(2) extern void fputchar(int);
(3) extern int j;
(4)
(5) sub2(int i)
(6) {
(7) fputchar (inc(i) + '0');
(8) }
The reference database was created by NMAKEing this simple
makefile (DEMO.MAK; make via "NMAKE /F DEMO.MAK"):
# DEMO make
demo.exe:
cl /FR demo1.c demo2.c
\c\binb\pwbrmake /o demo demo?.sbr
erase demo?.sbr
The resulting database is DEMO.BSC; in the examples, we
assume that it is the only .BSC in the current directory, so
we do not have to specify the /I (input file) argument.
REF USER'S GUIDE - 14
4.1 Cross-reference (/X)
To obtain a cross-reference, run REF with the /X option:
REF /X
(Because /X is the default option, we could simply type
"REF" with no arguments.) The following report is produced:
Symbol cross-reference
----------------------
inc (macro)
Def: demo2.c(1)
Ref: demo2.c(7)
j
Def: demo1.c(1)
Ref: demo1.c(11)
Ref: demo2.c(3)
main()
Def: demo1.c(7)
sub1() (static)
Def: demo1.c(15)
Ref: demo1.c(4)
Ref: demo1.c(9)
sub2()
Def: demo2.c(6)
Ref: demo1.c(2)
Ref: demo1.c(18)
The report, which lists each instance in alphabetical order,
shows that 'inc' is a macro that is defined in line 2 of
DEMO2.C and referenced in line 7 of the same file.
Variable j is defined in line 1 of demo1.c. We know that j
is a variable because no type is shown for the symbol;
functions are shown with "()" (as in "main()"), and anything
else has a symbol type. Variable j is referenced twice:
once in line 12 of demo1.c and again in line 3 of demo2.c.
sub1() has the "static" attribute, as you can see from the
report.
Please remember that REF cannot distinguish between multiple
occurrences of an instance. Thus, if a symbol name is used
multiple times in the same way (say, two local variables
with the same name), there will be multiple DEF and possibly
multiple REF lines for the symbol, and there is no way to
determine which DEF each REF is referencing.
On the other hand, if the same name is used for symbols with
different types or attributes (say, a local variable and a
global variable with the same name), then each is a separate
instance and will have its own section of refs and defs.
Now, as an example of filtering, let's produce a cross
REF USER'S GUIDE - 15
reference that adds (1) constants and (2) symbols with the
local or decl-only attributes:
REF /X /Fmvfc /Ald
When specifying ANY type filter, you must specify ALL
desired types. Thus, we must use /Fmvfc to see macros,
variables, functions, and constants; if we used /Fc, we
would see ONLY constants.
The expanded report is as follows:
Symbol cross-reference
----------------------
C (constant)
Def: demo1.c(3)
Ref: demo1.c(10)
fputchar() (decl-only)
Def: <Unknown>(1)
Ref: demo2.c(2)
Ref: demo2.c(7)
i (local)
Def: demo1.c(8)
Def: demo1.c(16)
Ref: demo1.c(10)
Ref: demo1.c(17)
Ref: demo1.c(18)
inc (macro)
Def: demo2.c(1)
Ref: demo2.c(7)
j
Def: demo1.c(1)
Ref: demo1.c(11)
Ref: demo2.c(3)
main()
Def: demo1.c(7)
sub1() (static)
Def: demo1.c(15)
Ref: demo1.c(4)
Ref: demo1.c(9)
sub2()
Def: demo2.c(6)
Ref: demo1.c(2)
Ref: demo1.c(18)
Note that locals, constants, and declaration-only symbols
are now included (i, c, and fputchar(), for example). Also
note that i has two definitions and three references. The
browser database does not contain information about which
definitions each of the references "belongs to."
fputchar() is not defined in any of the database modules,
hence its module is "unknown".
REF USER'S GUIDE - 16
4.2 Call trees (/T and /Tx)
4.2.1 Forward call trees (/T)
Call trees specify the paths a program can take to reach a
specific function. Let's look at the call tree for main()
in the demo:
REF /T main
The report is as follows:
main
└─sub1
└─sub2
└─fputchar?
Function main() calls sub1(), which calls sub2(), which
calls fputchar(). fputchar() is undefined--remember, it's
decl-only--so the report adds a question mark, indicating
that it can't follow the call tree past fputchar().
If main() also called sub3() and sub4(), and sub3() in turn
called sub3a() and sub3b(), the report would look like this:
main
├─sub1
│ └─sub2
│ └─fputchar?
├─sub3
│ ├─sub3a
│ └─sub3b
└─sub4
If a function is called more than once from another
function, the number of such calls follows the name. For
example, if printf() were called three times by main(), it
would look like this:
main
└─printf? (3)
4.2.1.1 Subtrees and levels
The call tree for the main function of a large program can
be extensive. You can get subtrees by specifying lower
level functions (the following command assumes the sub3()
function, which is not in the "real" demo):
REF /T sub1 sub3
REF USER'S GUIDE - 17
sub1
└─sub2
└─fputchar?
sub3
├─sub3a
└─sub3b
You can limit the number of levels shown by adding a number
immediately following the /T (or /Tx) option. For example,
if you only want to see the functions directly called by
main():
REF /T1 main
If you want to see the functions called by main() and the
functions that those functions call (but no more):
REF /T2 main
The "2" indicates that you want to see the call tree to a
maximum depth of two call levels past main. REF supports
reports of call nesting up to 250 levels.
4.2.1.2 Recursion
Directly or indirectly recursive functions are shown with
"...". Consider the following skeleton program:
main()
{ sub1(); }
sub1()
{ sub2(); }
sub2()
{ sub1(); }
Note that sub1() is indirectly recursive: it calls sub2(),
which in turn calls sub1(). The call tree for main() would
show as follows:
main
└─sub1
└─sub2
└─sub1...
The ellipsis ("...") shows that the call tree continues
indefinitely from this point.
REF USER'S GUIDE - 18
4.2.1.3 Indirect calls
What happens when a function is called indirectly, e.g., by
address rather than by name? Let's look at an example;
we'll use assembler instead of C, since this is one case
where assembler may be easier to read.
proc1 proc
mov ax,offset proc3 ; Put proc3's address in AX
call proc2
...
proc2 proc
call ax ; Calls proc3 (indirectly)
...
proc3 proc
call foo
...
The call trees for proc1 and proc2 would look like this:
proc1
├─proc3
│ └─foo
└─proc2
proc2
proc2's tree is empty, indicating that it doesn't make any
calls at all--even though it actually does. This makes
sense, since the call is dynamic; the call target isn't
known until run time. The assembler knows that there is a
call, but it doesn't know what is being called and therefore
can't provide a name for the reference database.
But why is proc3's subtree shown under proc1, when proc1
never calls proc3? Because the database does not actually
distinguish between a REFERENCE to a function and a CALL to
a function. REF simply assumes that any reference to a
function is in fact a call, since that is by far the most
common case. Thus, the reference to proc3 is assumed to be
a call, and the proc3 call tree is displayed.
In practice, this is not really as bad a thing as might
appear. If proc3 didn't appear under proc1, it wouldn't
appear at all. At least we can tell that there is a path of
execution by which proc3 can be reached from proc1. proc2
is missing from the sequence, but this is better than
nothing!
REF USER'S GUIDE - 19
4.2.1.4 Symbols required
Unlike the other actions, call trees (and reverse call
trees) require you to specify at least one symbol (function)
name on the command line. Otherwise, REF would produce a
call tree for EVERY function in the program; for anything
larger than a trivial program, the volume of data produced
would be massive.
4.2.2 Reverse call trees
Reverse call trees are similar to call trees, but reversed:
the function(s) of interest are shown at the top of the tree
rather than at the bottom:
REF /Tx fputchar
fputchar
└─sub2
└─sub1
└─main
This report can be extremely useful because it clearly shows
the exact paths of execution by which a specific function
can be reached. In this case, fputchar() can only be
reached via
main() -> sub1() -> sub2() -> fputchar()
If sub3a() also called fputchar(), the reverse tree would
be:
fputchar
├─sub2
│ └─sub1
│ └─main
└─sub3a
└─sub3
└─main
Now note that there are two paths to fputchar():
main() -> sub1() -> sub2() -> fputchar()
main() -> sub3() -> sub3a() -> fputchar()
It is much easier to find all possible paths to a low level
function in this manner than to examine a forward tree from
main(). The forward tree would show many paths that end in
symbols that are of no interest, but the reverse tree shows
ONLY the paths of execution that lead to your function.
REF USER'S GUIDE - 20
4.3 Calls and Called-by (/C and /Cx)
The calls and called-by reports are simpler than the call
trees; they simply show lists of functions that directly
call or are called by the function(s) of interest. For
example, assuming this program:
main()
{
int a;
a = 1;
sub1(); sub3();
}
sub1()
{ sub2(); }
sub2()
{ }
sub3()
{ }
a call report for the whole program (REF /C) would be
Function Calls
-------- -----
main() sub1()
sub3()
sub1() sub2()
main() calls sub1() and sub3(); sub1() calls sub2().
The called-by report (REF /Cx) would be:
Function Called by
-------- ---------
main()
sub1() main()
sub2() sub1()
sub3() main()
4.4 Uses/used-by (/U, /Ux)
These reports show all symbols that a function uses, or all
functions that use a symbol. The "uses" report is a
superset of the "calls" report, and the "used-by" report is
a superset of the "called by" report. That is, a
uses/used-by report contains all of the information that
would be contained in the calls/called-by report for the
same set of symbols.
Running the "uses" report (REF /U) on the sample program
REF USER'S GUIDE - 21
produces the following report:
Symbol Uses
------ ----
main() sub1()
j
sub1() (static) sub2()
sub2() inc (macro)
Function main() uses function sub1() and variable j;
function sub1() uses function sub2(); and function sub2()
uses the macro 'inc'. We can get a more complete report by
requesting information on local objects as well as
additional symbol types:
REF /U /Al /Ffmvc
The new report adds constants and local variables:
Symbol Uses
------ ----
main() i (local)
sub1() (static)
C (constant)
j
sub1() (static) i (local)
sub2()
sub2() inc (macro)
The used-by report provides the "inverse" information:
which functions use each symbol (rather than which symbols
are used by each function). The full used-by report could
be obtained via:
REF /Ux /Al /Ffmvc
Symbol Used by
------ -------
C (constant) main()
i (local) main()
sub1() (static)
inc (macro) sub2()
j main()
sub1() (static) main()
sub2() sub1() (static)
4.5 Module list (/M)
The /M action simply displays a list of modules that are
included in the database. For our simple demo, the command
REF /M
produces this list:
REF USER'S GUIDE - 22
Modules
-------
1: demo1.c
2: demo2.c
4.6 Unreferenced symbols (/N)
This report shows any symbols that are defined but not
referenced. Consider this program:
main()
{
int var1, var2;
var1 = 1;
}
Running REF /N on the database for this program produces the
following report:
Unreferenced symbols
--------------------
test.c(3) : var2 (local)
The report shows that the local variable 'var2' is defined
on line 3 of TEST.C but is never referenced.
The unreferenced symbols report is not foolproof. Remember
that REF can't distinguish between multiple occurrences of
the same "instance" (a specific combination of name, type,
and attributes). If you do have multiple occurrences of an
instance, a reference to any one of them will prevent the
rest from appearing as unreferenced. Consider this program:
int var1;
main()
{
int var1;
}
sub1()
{
int var1;
var1 = 1;
}
There are three occurrences but only two instances of var1:
one global instance and one local instance. The local var1
in main() is unreferenced but will NOT appear in the reports
because its "cousin" instance in sub1() is not unreferenced.
On the other hand, the global instance of var1 WILL show as
unreferenced: it is a separate instance, and there are no
REF USER'S GUIDE - 23
references anywhere in the program to a global var1.
Of course, if you avoid duplicate names this will not
represent a problem.
Remember to include PWBRMAKE's /Iu option when you plan to
search for unreferenced symbols, and that you can exclude
information from header files using REF's /Ex option.
By the way, PWBRMAKE's /Es and /Ei options are supposed to
exclude from the database information that is derived from
certain types of included files; we have never been able to
get these to work reliably (PWBRMAKE version 1.10). Perhaps
you can.
4.7 Outline (/O)
The outline function displays an outline of the contents of
the database, i.e., a list of all qualifying symbols defined
in each module. The outline for the demo program (REF /O)
would be as follows:
demo1.c
j variable,public
main function,public
sub1 function,static
demo2.c
inc macro
sub2 function,public
All qualifying symbols (instances, really) are listed for
each module, along with the symbol type and attributes.
As usual, a more complete list can be obtained by changing
the filters. For example:
REF /Fmcvfp /Al /O
demo1.c
C constant
i variable,local
j variable,public
main function,public
sub1 function,static
demo2.c
i parameter,local
inc macro
sub2 function,public
You can also obtain outlines of specific modules by listing
them as "symbols" on the command line. To obtain an outline
of DEMO1.C:
REF USER'S GUIDE - 24
REF /O demo1.c
Some module names may include a drive and/or path in the
database (use /M to check). If you wish to name such a
module on the command line, you must use the exact
drive/path as listed by /M. For example, if a module is
listed by /M as "c:\c\include\heap.h", you must use the same
path with /O:
REF /O c:\c\include\heap.h
When specifying module names for /O, you can use the
standard DOS * and ? wildcards. To obtain both DEMO1.C and
DEMO2.C (as well as any other modules in the database that
match the filespec):
REF /O demo?.c
or
REF /O demo*.c
You can omit the drive/path if you use the * wildcard for
the entire root name of a file. For example, this command
would include an outline of a module listed as
"c:\c\include\heap.h"
REF /O *.h
If you DO specify a path with a wildcard, it must be
correct. This command would not work, because it's missing
the drive letter:
REF /O \c\include\*.h
4.8 Dump (/D, /Dm, /Ds)
The dump report simply dumps out most of the information in
the database. This report can be quite voluminous for large
programs; it' over 100 lines long for the simple demo
program,
The dump should be largely self-explanatory. It is in two
parts: a module list and a symbol list. The module list is
similar in contents to the /O (outline) report: it shows
the module name and all symbols that are contained in the
module. This list differes slightly in format and is not
affected by the filters (all modules and symbols are shown).
Here is the listing for the DEMO1.C module:
REF USER'S GUIDE - 25
Module 1 of 2: demo1.c
C (constant)
i (variable:local)
j (variable:public)
main (function:public)
sub1 (function:static)
One of the "modules" is usually a module named "<Library>".
This is actually a dummy module that is used to contain
objects that are declared but not defined anywhere that the
database knows about. For the most part, these will be
functions and variables that are declared in header files
but not defined within the program source--in other words,
library functions and variables.
The symbol list is a comprehensive, alphabetical list of all
symbols known to the database. For each symbol is shown:
Symbol name, type, and attribute(s)
Definitions (source file name and line number)
References (source file name and line number)
Uses information
Used-by information
Here is the symbol listing for the sub1() function:
sub1 (function:static)
def: demo1.c(14)
ref: demo1.c(3)
ref: demo1.c(8)
uses: i (variable:local) [3]
uses: sub2 (function:public)
used-by: main (function:public)
sub1() is a static function that is defined in line 14 of
DEMO1.C. It is referenced twice: once in line 3 of DEMO1.C
and again in line 8. sub1() uses the local variable 'i'
three times and calls the function sub2(). It is used by
(called by) the function main(). The [3] following the uses
information for variable 'i' indicates that 'i' is
referenced three times by sub1.
If you wish to see only one of the two lists, use /Dm to see
the module list or /Ds to see the symbol list.
5 Messages
Other than the messages and information displayed during
REF's regular reporting, REF produces the folloiwng
messages:
REF USER'S GUIDE - 26
<symbol name>: not found
No symbol was found in the database with the specified
name (which was given on the command line). Check case
and spelling.
Can't open <filename>
REF was unable to find or open a file with the specified
name.
Database in use: <filename>
Specifies the name of the database that REF is using
(not an error message).
Decl-only instance of <symbol name> found
When preparing a call tree, an instance of the named
symbol is "declaration only", i.e., it is declared
but not defined. Since the database has no information
about calls it might make, it is not possible to display
a call tree for this instance.
Filename not specified, no .BSC files found
You did not specify a filename on the command line, and
REF did not find any .BSC databases in the current
directory.
Must specify at least one symbol name for /T, /Tx
You must list at least one symbol (function) on the
command line when using /T or /Tx.
Non-function instance of <symbol name> found
When preparing a call tree, an instance of the named
symbol was found not to be a function (and thus has no
call tree).
Out of memory!
REF ran out of memory.
Too many actions (max=20)
Only twenty actions may be specified per REF run.
Too many exclude types (max=10)
Only ten exclude headers may be specified with /Ex.
Too many symbols (max = 40)
Only forty symbols may be specified on the command line.
-END OF USER'S GUIDE-
REF USER'S GUIDE - 27
