OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / REF102.ZIP / REF.DOC < prev next >

Wrap

Text File | 1991-09-24 | 69KB | 1,882 lines

REF 1.0 User's Guide Shareware Evaluation Version The Cove Software Group P.O. Box 1072 Columbia, MD 21044 (301) 992-9371 Version 1.02 September, 1991 Copyright (C) 1991 The Cove Software Group All Rights Reserved Table of Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 What is REF? . . . . . . . . . . . . . . . . . . . . 1 1.2 Registration . . . . . . . . . . . . . . . . . . . . 1 1.3 Getting started . . . . . . . . . . . . . . . . . . 2 1.3.1 System requirements . . . . . . . . . . . . . 2 1.3.2 Printing the User's Guide . . . . . . . . . . 2 1.3.3 Installing PWBRMAKE . . . . . . . . . . . . . 2 1.3.4 Installing REF . . . . . . . . . . . . . . . 4 2 Preparing for REF . . . . . . . . . . . . . . . . . . . . . 5 2.1 Manual preparation . . . . . . . . . . . . . . . . . 5 2.2 Using NMAKE . . . . . . . . . . . . . . . . . . . . 6 3 Using REF . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1 REF services . . . . . . . . . . . . . . . . . . . . 8 3.2 Symbol types, attributes, instances . . . . . . . . 9 3.3 Running REF . . . . . . . . . . . . . . . . . . . 10 3.3.1 Syntax . . . . . . . . . . . . . . . . . . 10 3.3.2 Specifying the input file . . . . . . . . . 11 3.3.3 Specifying options . . . . . . . . . . . . 11 3.3.3.1 File suppression (/Ex) . . . . . . . 11 3.3.3.2 Standard format (/S) . . . . . . . . 12 3.3.4 Specifying symbol names . . . . . . . . . . 12 3.3.5 Specifying actions . . . . . . . . . . . . 13 3.3.6 Specifying symbol-type filters . . . . . . 15 3.3.7 Specifying attribute filters . . . . . . . 15 4 Reports . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.1 Cross-reference (/X) . . . . . . . . . . . . . . . 18 4.1.1 REF format . . . . . . . . . . . . . . . . 18 4.1.2 Standard (/S) format . . . . . . . . . . . 20 4.2 Call trees (/T, /Tx) . . . . . . . . . . . . . . . 21 4.2.1 Forward call trees (/T) . . . . . . . . . . 21 4.2.2 Subtrees and levels . . . . . . . . . . . . 22 4.2.3 Recursion . . . . . . . . . . . . . . . . . 22 4.2.4 Indirect calls . . . . . . . . . . . . . . 23 4.2.5 Symbols required . . . . . . . . . . . . . 24 4.2.6 Reverse call trees . . . . . . . . . . . . 24 4.3 Calls, Called-by (/C, /Cx) . . . . . . . . . . . . 25 4.4 Uses, used-by (/U, /Ux) . . . . . . . . . . . . . 25 4.5 Modules (/M) . . . . . . . . . . . . . . . . . . . 26 4.6 Unreferenced symbols (/N) . . . . . . . . . . . . 27 4.7 Outline (/O) . . . . . . . . . . . . . . . . . . . 28 4.8 Dump (/D, /Dm, /Ds) . . . . . . . . . . . . . . . 29 Appendix A: Error Messages . . . . . . . . . . . . . . . . 31 1 Introduction 1.1 What is REF? REF is a utility that can provide considerable information about projects developed with the Microsoft (R) Professional Development System (PDS) running under DOS or OS/2. 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. REF is currently compatible with the following languages (all are Microsoft products): ∙ BASIC 7.10 ∙ C 6.0 ∙ COBOL 4.0 ∙ Fortran 5.1 ∙ Macro Assembler 6.0 REF will automatically be compatible with revisions of these products and with other languages (such as Pascal) if and when they are released in PDS versions. 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 typeset copy of the manual, a Microsoft QuickHelp-compatible help file, and a free upgrade to the next release of REF. The shareware evaluation package is not "crippled" in any way. No features are disabled, and the documentation file is complete. The registered version of REF.EXE is identical except that it does not display the shareware information. 1.2: Registration 2 Please see the REGISTER.DOC and LICENSE.DOC for registraion forms, licenses and warranty, etc. 1.3 Getting started 1.3.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 include the products listed section 1.1 and are the Microsoft products 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 mixed languages and not all of the languages are PWB-compatible (say, Microsoft C 6.0 with MASM 5.x or Borland's TASM), you can use REF on the PWB-compatible portion of the project. 1.3.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). 1.3.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. Before you start, decide where you are going to put 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 and LIB. Installing PWBRMAKE from SETUP First, locate the "SETUP" or "INSTALLATION" diskette for your Microsoft language product. Insert the disk in your diskette 1.3: Getting started 3 drive and make that drive the current drive; type SETUP and press Enter. Look for a menu option that reads something like: Copy a file from the distribution disk If there is no such option, exit SETUP and follow the alternate instructions below. Select the "copy" option and follow the prompts. In most versions of SETUP, the first prompt will request the name of the file to be copied ("PWBRMAKE.EXE") and the second prompt will ask the name of the directory to which you want the file copied. After you've responded to both prompts, SETUP will install the program for you; exit SETUP when you're done and put the SETUP diskette away. Alternate instructions If your version of SETUP does not include an option to install a single file, follow these instructions to install PWBRMAKE manually. Your SETUP disk should still be in the diskette drive, of course. 1. 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. 2. 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. b. Remove the setup diskette and insert the PWBRMAKE diskette. 3. Install the compressed file PWBRMAKE.EX$ from the diskette by running the DECOMP program. Just type DECOMP and, at the first DECOMP prompt, enter d:path\pwbrmake.ex$ where 'd:path' is the installation drive and directory that contains PWBRMAKE (usually A:\BINB). Note that the filename extension is EX$, not EXE. At the second DECOMP prompt, enter: 1.3: Getting started 4 d:path\pwbrmake.exe where d:path represents the drive and directory you have selected for permanent storage of PWBRMAKE. DECOMP will decompress PWBRMAKE and store it in the directory you specified. 4. 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. 1.3.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 REF.EXE The REF program (DOS version) REFP.EXE The REF program (OS/2 version) 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 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 REF.EXE (DOS) and/or REFP.EXE (OS/2) to appropriate working directories. We suggest that you keep REF in the same directory as the DOS or OS/2 versions of your compiler or assembler (or perhaps with CodeView and other language tools). For example: COPY REF.EXE C:\C\BINB COPY REFP.EXE C:\C\BINP NOTE: the DOS and OS/2 versions of REF 1.00 were released as REFDOS.EXE and REFOS2.EXE respectively. You may have renamed these as REF.EXE and REFP.EXE. Copy the remaining files to a convenient working directory for review (you do not need them to run REF). Please print and review REGISTER.DOC for registration information, LICENSE.DOC for 1.3: Getting started 5 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 Preparing for REF 2.1 Manual preparation 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. If you use the PWB, note that preparing the browser database is the same as preparing the REF database: preparing for the browser also prepares for REF, and vice versa. 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 file1.sbr file2.sbr This creates the database TEST.BSC from the two raw files created in the first example. Note that PWBRMAKE truncates the raw (.SBR) files to zero length. They are not needed after PWBRMAKE has been run, and you can erase them if you wish. However, if you do this, you will not be able to build the database incrementally you'll have to recompile every module every time. See the next section for one technique that allows incremental database building. You can use wildcards: PWBRMAKE /o test test?.sbr or 2.1: Preparing your projects 6 PWBRMAKE /o test *.sbr The latter command, of course, 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.2 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, deal with the problem of PWBRMAKE's desire to truncate the raw data files. 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": # ----------------------------------------- # Makefile for MYPROG # # Inference rules .c.obj: cl /c /FR $*.c .asm.obj: ml /c /Cx /FR $*.asm # Primary target--link and run PWBRMAKE, # creating the database MYPROG.BSC. myprog.exe: mod1.obj mod2.obj moda.obj link mod1+mod2+moda,myprog; copy *.sbr *.sbx pwbrmake /Iu /o myprog *.sbx erase *.sbx # Subsidiary targets mod1.obj: mod1.c mod2.obj: mod2.c moda.obj: moda.asm 2.2: Using NMAKE 7 2.1: Preparing your projects 7 Note how the make file handles PWBRMAKE's truncation of the SBR files: just before PWBRMAKE runs, we duplicate all of the SBR files, using the extension SBX. Then we run PWBRMAKE using the duplicate (SBX) files; these are truncated, and we erase them but the original files remain intact. The point of this is to maintain the raw data files so that we can build the database incrementally, i.e., to avoid have to recompile every module every time. See your documentation and online help for more information about NMAKE. 3.1: REF services 8 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. All REF output is sent to the screen. It can be redirected or piped, of course, if desired: REF > xref.txt REF | MORE 3.2: Symbol types, attributes, instances 9 3.2 Symbol types, attributes, 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 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 10 3.3 Running REF 3.3.1 Syntax The basic syntax for running REF is: REF [/?] [/HELP] [/Ifile] [options] [symbols] [/actions] [/Ffilters] [/Aattribute-filters] The syntax for REFP (the OS/2 version) is identical except that the name of the program is REFP rather than REF. Examples in this manual refer to "REF", but use "REFP" for OS/2. The /? option displays a brief help screen. All other options are ignored if /? is present. The /HELP option (which can be abbreviated /H) displays hypertext help for REF using Microsoft's QuickHelp program (QH.EXE). If REF cannot find QH.EXE or its own help file (REF.HLP), it displays the brief help screen. All other options are ignored if /HELP is present. This option is available only in the registered version. 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. All of the parameters are optional. If no parameters at all are specified, REF prepares a cross reference for all non-local 3.3: Running REF 11 functions, macros, and variables for the first .BSC file in the current directory. This is equivalent to: REF /X /Ffmv /Iname.bsc where NAME.BSC is the first .BSC file shown in an unsorted directory listing. 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 two options. 3.3.3.1 File suppression (/Ex) The /Ex option suppresses information from specified modules. The format is: /Ex[(extension[,extension])] 3.3: Running REF 12 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. 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.3.2 Standard format (/S) The standard (or "Microsoft") format affects only the cross reference report. When you use the /S option: REF /S /X REF's output is generated in "Microsoft standard" format. A cross reference might look like this: d:\c\include\stdio.h(199) : definition : printf (macro) This format is useful for interaction with other products, such as text editors, that "understand" how to parse the filename and line number. See section 4.1 for further information. 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: 3.3: Running REF 13 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 The example prepares cross reference information for the symbols main, myvar, mymacro, and MYCONST. The database is PROJECT.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 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 3.3: Running REF 14 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 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 Displays a list of all functions that func1 calls 3.3: Running REF 15 REF /Cx func1 func2 Displays a list of all functions that call func1 or func2 REF /C/Cx func1 Displays both lists for func1 REF /C/U Displays 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 /X /Fsutpc To obtain cross reference information about ALL symbols: REF /X /F* 3.3.7 Specifying attribute filters 3.3: Running REF 16 In the uses/used-by and cross-reference reports, REF normally suppresses references to symbols with either or both of the following attributes: 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'). 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 may not have and which is usually not included in the project database. If you wish to include symbols with local 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 (letter 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. 4: Reports 17 4 Reports This section describes all of the reports REF can generate. Many of the report samples use 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 first or only .BSC in the current directory, so we do not have to specify the /I (input file) argument. 4.1: Cross-reference (/X) 18 4.1 Cross-reference (/X) 4.1.1 REF format To obtain a cross-reference in REF's text format, 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 1 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 "()", 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. 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. 4.1: Cross-reference (/X) 19 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. As an example of filtering, let's produce a cross 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) 4.1: Cross-reference (/X) 20 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". 4.1.2 Standard (/S) format "Standard" format refers to the format Microsoft products use for error messages and other information where line numbers and file names are useful. A standard format report can be obtained by using the /S option: REF /S /X The standard format report for the demo project would look like this: demo2.c(1) : definition : inc (macro) demo2.c(7) : reference : inc (macro) demo1.c(1) : definition : j demo1.c(11) : reference : j demo2.c(3) : reference : j demo1.c(7) : definition : main() demo1.c(15) : definition : sub1() (static) demo1.c(4) : reference : sub1() (static) demo1.c(9) : reference : sub1() (static) demo2.c(6) : definition : sub2() demo1.c(2) : reference : sub2() demo1.c(18) : reference : sub2() For each definition and reference, REF prepares a line in this format: filename(line) : type : name (information) The filename (which may include a path if there is one in the database) is followed immediately by the line number in parentheses. After this is a space-delimited colon and the "type", which will always be either "definition" or "reference". Following the type is another space-delimited colon and the objects name followed, in some cases, by the qualifiers in parentheses. This format is readily amenable to automated processing and, in fact, many text editors already "understand" text in this format. Macros can often be easily written that will automatically run REF and deal with the results in a useful way. For example, a 4.1: Cross-reference (/X) 21 mouse click on a reference to an object could run REF and then lead to displays of the definition and additional references, in context. The standard format report does not show objects for which the module name is unknown. 4.2 Call trees (/T, /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 declaration- 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: Call trees (/T, /Tx) 22 4.2.2 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 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.3 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: 4.2: Call trees (/T, /Tx) 23 main └─sub1 └─sub2 └─sub1... The ellipsis ("...") shows that the call tree continues indefinitely from this point. 4.2.4 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. 4.2: Call trees (/T, /Tx) 24 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! 4.2.5 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.6 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 4.2: Call trees (/T, /Tx) 25 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. 4.3 Calls, Called-by (/C, /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() { 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 4.4: Uses, used-by (/U, /Ux) 26 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 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: Modules (/M) 27 4.5 Modules (/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: 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; } 4.6: Unreferenced symbols (/N) 28 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 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 4.7: Outline (/O) 29 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 /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's over 100 lines long for the simple demo program, 4.8: Dump (/D, /Dm, /Ds) 30 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 differs 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: 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 "<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: usually 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(). 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. Appendix A: Error Messages 31 Appendix A: Error Messages REF displays the following error messages. Messages with numbers RF1xxx are fatal; REF cannot continue and returns a nonzero errorlevel to the operating system. Messages with numbers RF2xxx are informational in nature; REF continues proessing normally. RF1001: too many symbols (max=40) Only forty symbols may be specified on the command line. RF1002: too many actions (max=20) Only twenty actions may be specified per REF run. RF1003: too many exclude types (max=10) Only ten exclude headers may be specified with /Ex. RF1004: 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. RF1005: 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. RF1006: can't open <filename> REF was unable to find or open a file with the specified name. RF1007: out of memory REF ran out of memory. RF2001: <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. RF2002: 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. RF2003: 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).