home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
PROG_C
/
BSC32.ZIP
/
BSCTUT.TXT
< prev
next >
Wrap
Text File
|
1994-01-24
|
18KB
|
513 lines
______________________________________________________________________
Browser Library Tutorial - BSCTUT.TXT
Microsoft Visual C++ Browser Toolkit for Windows NT
(C) Copyright Microsoft Corporation, 1993
This tutorial illustrates the use of the browser
library (BSC.LIB) included in the Microsoft Visual C++
Browser Toolkit for Windows NT. Specifically, the
tutorial describes the Toolkit's sample application,
BSCDUMP, which calls many of the browser library's
functions. You may want to print a copy of BSCDUMP.C
for easy reference.
Contents
1 Overview of BSCDUMP
2 BSCDUMP Arguments
2.1 General List Commands
2.2 Symbol-specific List Commands
______________________________________________________________________
1 Overview of BSCDUMP
The sample application BSCDUMP included with the
Browser Toolkit demonstrates how you can use the
Toolkit's browser library to access the contents of
browser database files, which have the extension .BSC.
The database contains all symbols defined in the
program's source and include files, the location of
these symbols, references to each, and linkage
information. These symbols represent the names of all
functions, types (such as the names of all classes,
structures, enumerations, and their members), macros,
and variables in the files. Visual C++ stores a
program's function names as decorated names, which
indicate the class to which the function belongs,
parameter types, calling convention, and return type.
The database also contains such information as the
calltree of a function, the symbol table, the
definition table, and the reference table. You can
query each of these tables using the browser APIs to
obtain information about program symbols.
BSCDUMP is a program that displays the contents of .BSC
files. The program accomplishes most of its tasks by
calling browser library functions, which perform all
the information retrieval work. The include files,
BSCSUP.H and BSC.H, provide the necessary interface to
all the browser library's functions. The declarations
in each of these header files follow the specifications
explained in the BSCREF.TXT file. You should note the
special use of the browser library "callback"
functions since they can enhance environment
integration.
A callback function is one that performs a particular
system service required by the browser library (such as
memory allocation, file I/O, or error-handling).
Programs that use BSC.LIB can still use functions from
the C run-time library, however callback functions can
be used to provide an interface to any environment that
might not allow access to the C run-time library. See
BSCREF.TXT for a more detailed discussion of the
browser library's callback functions and their
specifications.
The Browser Toolkit includes the batch file MAKE.BAT
that instructs the Microsoft Visual C++ for Windows NT
compiler to create the BSCDUMP executable.
Some of the general operations BSCDUMP performs include
listing file references, redundant definitions, and
symbol definitions and references. The program also
displays symbol calltrees and classtrees, BSC file
summary and statistics, and raw symbols. The following
sections provide more specific information about these
operations and how they are accomplished.
______________________________________________________________________
2 BSCDUMP Arguments
BSCDUMP has the following usage syntax:
BSCDUMP [options] <file.bsc>
Table 1 lists the available options and their
respective actions. Note that if no option is selected,
BSCDUMP produces an ASCII dump of the .BSC file. The
table also indicates the function that is called to
produce the desired action. Function names preceded by
an asterisk refer to functions defined in the BSCDUMP.C
file itself. All other functions are defined in the
browser library. This tutorial describes each of these
options in the order listed in Table 1.
Table 1: BSCDUMP Options
Called
------------------------------------------------------------
Argument Action Function
------------------------------------------------------------
-l[FCVMT] List references ListRefs
-u[FCVMT] List unused definitions *ListUnused
-O <file> Outline functions with *DumpFunctio
source comments n-Comments
-s List BSC file StatsBSC
summary/statistics
-S List raw symbols *ListRawSyms
-o[FCVMT] List outline for given FOutlineModu
<symbol> symbol (module) leLsz
-i[FCVMT] List information about GenerateOver
<symbol> given symbol loads
-r <symbol> List references to *DumpDefRefL
symbol (case sensitive) sz
-d <symbol> List definitions of *DumpDefRefL
symbol (case sensitive) sz
-R <symbol> List references to *DumpDefRefL
symbol (case sz
insensitive)
-D <symbol> List definitions of *DumpDefRefL
symbol (case sz
insensitive)
-t <symbol> Provide GenerateOver
calltree/classtree loads
-b <symbol> Provide backward GenerateOver
calltree/classtree loads
no argument Dump entire BSC file DumpBSC
contents
The additional options [FCVMT] available for some
arguments narrow the inquiry to the following specific
symbols:
Argument Symbol Information
F Functions
C Classes
V Variables
M Macros
T Types
If none of these suboptions is selected explicitly,
then they are all selected by default. The following
sections describe each of the BSCDUMP options in more
detail.
______________________________________________________________________
2.1 General List Commands
For each of the options selected that also take
suboptions, BSCDUMP creates a filter mask (called an
MBF for historical reasons) representing these
suboptions. If no suboptions are selected, this mask is
set to all options.
Refer to BSCREF.TXT for a more detailed discussion of
browser library functions referred to in BSCDUMP.C.
-l[FCVMT] (List References)
The program simply passes the suboption filter mask to
the browser library function ListRefs, which
accomplishes the task of listing all symbol references.
-u[FCVMT] (List Unused Definitions)
BSCDUMP depends on the function ListUnused to list
unused definitions. This is not a browser library
function and therefore is a good example of one way to
extend the library's functionality. Here is the
function listing:
void ListUnused(MBF mbf)
{
ISYM isym, isymMac;
IINST iinst, iinstMac;
IUBY iubyFirst, iubyLast;
isymMac = IsymMac();
for (isym = 0 ; isym < isymMac ; isym++) {
InstRangeOfSym(isym, &iinst, &iinstMac);
for ( ; iinst < iinstMac ; iinst++) {
if (!FInstFilter(iinst, mbf))
continue;
UbyRangeOfInst(iinst, &iubyFirst, &iubyLast);
if (iubyFirst == iubyLast) {
DumpInst(iinst);
BSCPrintf("\n");
}
}
}
}
Initially, ListUnused calls a browser library function,
IsymMac, that returns the biggest symbol index in the
browser database. This number provides the upper bound
in a search for redundant symbol definitions. The
following for loop allows the remaining part of the
function to query each symbol individually with the
range of isym = 0 to isym = isymMac - 1. The function
then queries another library function, InstRangeofSym,
to determine the range of instances associated with
each symbol in the symbol table. This function stores
the lower and upper bounds in iinst and iinstMac,
respectively. A call to FInstFilter determines if the
current symbol matches the one requested. If it does
not, then the function proceeds with the next iteration
of the for loop.
Using the two bounds for the symbols, ListUnused calls
on the library function UbyRangeOfInst, which returns
the associated range called by the table. The function
then determines if the upper and lower bounds of this
range are identical. If the current symbol is
redundant, ListUnused calls the function DumpInst,
which sends the following information to the standard
output regardless of symbol instance type:
<ASCII instance name> <ASCII type name> <ASCII
attribute name>
Finally, another library function, BSCPrintf, produces
the new line on the standard output via the BSCOutput
callback function.
-O <file> (Outline functions with source comments)
The BSCDUMP function DumpFunctionComments displays a
list of all functions and associated comments in the
given source file(s). Wildcards can be used in the
filename given to this option.
To display the source file comments,
DumpFunctionComments calls another BSCDUMP.C function,
DumpComments. This function uses a heuristic rule to
search for comment blocks before functions in the
source. If no comments can be found, only the function
name is displayed.
The following is the output of bscdump -O bscdump.c
bscdump.bsc:
Browser Data Base: bscdump.bsc
[[[[[[[[[[[[[ c:\browser\bscdump.c ]]]]]]]]]]]]
## DumpBobInfo (function:public)
{
// dump the instance info from a BOB, the BOB must be
of clsInst
//
}
## DumpComments (function:public)
{
// having opened a particular file, we are now looking
for comments at
// or before the given line number
//
}
## DumpDefRef (function:public)
{
// dump definitions or references for a single BOB,
suitable for use
// in GenerateOverloads
//
}
## DumpDefRefLsz (function:public)
{
// dump definition or reference starting from possibly
overloaded symbol name
//
}
## DumpFunctionComments (function:public)
{
// show any comment headers that are associated with
functions
// in the given module. The module may include
wildcards.
//
}
## DumpFwdTree (function:public)
{
// dump a forward tree, either class tree or call tree
depending on
// the type of BOB that we get. The BOB must be an
instance BOB.
//
}
## DumpRevTree (function:public)
{
// dump a reverse tree, either class tree or call tree
depending on
// the type of BOB that we get. The BOB must be an
instance BOB.
//
}
## GenericError (function:public)
{
// non-specific error message about a given symbol
//
}
## ListRawSyms (function:public)
{
// list the raw text of all the symbols in the
database, useful
// for grepping. Note sorting order is subject to
change so
// use a comparison API to compare...
//
}
## ListUnused (function:public)
{
// list unused definitions, these are items which are
not used by some other
// symbol known to the browser. Note, entry points
like "main" should appear
// in the list. This output is helpful in locating
dead code.
//
}
## main (function:public)
{
// main entry point, parse args and dispatch workers...
//
}
## MbfFromLsz (function:public)
{
// get a mask of object types (nobody knows how this
ended up getting
// called an MBF) from a string...
//
}
## ParseArgs (function:public)
{
// parse arguments into global variables and open a
database
//
}
## Usage (function:public)
{
// emit usage information
//
}
-s (List Browser File Summary/Statistics)
The browser library function StatsBSC performs all the
necessary work required to list statistics and a
summary of a browser database. The statistics include
the table sizes for the following tables and lists:
- Module Table
- Symbols listed by module name
- Symbol list
- Properties list
- Definition table
- Reference table
- Call table
- Called by table
In addition, the StatsBSC function outputs each symbol
and the associated instance information counts.
-S (List Raw Symbols)
To list raw symbols in a browser database, BSCDUMP
calls its function ListRawSyms, shown below. This
function calls the library function IsymMac, which
returns the biggest symbol index in the database.
BSCDUMP then prints all symbols with index smaller than
this largest index.
void ListRawSyms()
{
ISYM isym, isymMac;
isymMac = IsymMac();
for (isym = 0 ; isym < isymMac ; isym++)
BSCPrintf("%s\n", LszNameFrSym(isym));
}
______________________________________________________________________
2.2 Symbol-Specific List Commands
-o[FCVMT] <symbol> (List Outlines)
The -o option produces a list of all symbols in the
module with attribute types indicated by the suboptions
(F, V, M, C, or T). With the exception of argument
parsing, all of the work required to produce this list
is done by the library function FOutlineModuleLsz.
Here is the actual call to this function:
FOutlineModuleLsz(psymbol, mbf)
-i [FCVMT] <symbol> (List Symbol Information)
This option causes BSCDUMP to call the
GenerateOverloads library function, which takes three
arguments: a symbol, a symbol mask, and a pointer to a
function. GenerateOverloads returns all possible
browser objects (BOBs) that match a given overloaded
name. GenerateOverloads then applies whatever function
it was given to each of the BOBs found, making
GenerateOverloads a very powerful library function. In
this case, the function passed to GenerateOverloads is
DumpBobInfo, which dumps a single instance of a browser
object.
void BSC_API DumpBobInfo(BOB bob)
{
if (ClsOfBob(bob) != clsInst)
return;
DumpInst(IinstFrBob(bob));
BSCPrintf("\n");
}
-r <symbol> and -d <symbol> (List References and
Definitions to Symbol; Case Sensitive)
The -r and -d options allow the user to list each
reference to and definition of, respectively, a given
symbol. Its implementation again demonstrates the power
of GenerateOverloads. BSCDUMP uses its DumpDefRef
function and GenerateOverloads, as shown below, to
generate references and definitions.
void DumpDefRefLsz(LSZ lszSym)
{
if (!GenerateOverloads(lszSym, mbfAll,
DumpDefRef))
GenericError(lszSym);
}
-R <symbol> and -D <symbol> (List References and
Definitions to Symbol; Case Insensitive)
These two options are identical to their respective -r
and -d counterparts, with the exception that the
database queries are case insensitive. In fact, they
both result in the same function, DumpDefRefLsz, being
called. BSCDUMP achieves this dual-case functionality
by calling the SetCaseBSC library function, which
overrides the browser database case sensitivity. The
argument to SetCaseBSC is a Boolean which determines if
sensitivity is on (TRUE) or off (FALSE).
-t <symbol> (Provide Calltree/Classtree)
This option provides the calltree or classtree from a
symbol name, which may be the name of either a function
or a module. BSCDUMP calls the GenerateOverloads
library function with a pointer to BSCDUMP's
DumpFwdTree function. Depending on the symbol mask
filter, the latter determines the type of tree
requested (call or class) and calls one of the two
library functions CallTreeInst or ClassTreeInst.
-b <symbol> (Provide Backward Calltree/Classtree)
For a backward calltree or classtree, BSCDUMP also
calls GenerateOverloads, but with a pointer to
BSCDUMP's DumpRevTree function instead. After
determining which type of tree is requested, BSCDUMP
calls one of two library functions, RevTreeInst or
RevClassTreeInst.