THE CEDAR LISTER (by Ed Satterthwaite)

The file Lister.df can be used to access a collection of programs that can be used to
extract information from Cedar object files.  The programs exported by Lister.df are

	Lister.bcd
	BL.bcd
	CL.bcd
	GL.bcd
	SL.bcd

Lister.bcd is a recompilation of SDD's lister and is documented in the Mesa User's
Handbook.  It uses a number of packages that are no longer being maintained, and
the Cedar version of this program will be withdrawn when its continued maintenance
becomes a burden.  The other programs collectively implement a subset of the
commands of the original lister.  Most are of interest only to wizards, but the
program GL is generally useful and the others are available to the curious.


SUMMARY

Function		Program		Switches

 global frame lister	GL		t	(output to typescript)
 
 code  lister		CL		h	(hexadecimal + mnemonics)
 					o	(octal + mnemonics)

 symbol lister		SL		t	(trees also)			

 bcd lister		BL		f	(file/version information only)
					l	(display link values)
					o	(sorted RT bcd tables)
					r	(RT bcd extension)
					v	(version info to typescript)

For each, the basic command line syntax is

  xL  file1/switches file2/switches ...

where xL is the program name (x = C, G, S or B), the extension .bcd is assumed for
each input file, the switches are optional, and the output is written to file1.xl,
file2.xl, etc.  For example,

  CL Foo Baz/o

produces a code listing for Foo.bcd on Foo.cl, and a code listing augmented with
octal addresses and opcodes for Baz.bcd on Baz.cl.  Execptions and extensions to 
this scheme are noted below.  Global switches are also allowed; for example,

  BL /v <pattern>.bcd

is often useful for determining versions of local files.  (Note that output appears
in the executive's window, not in .bl files.)

Each of these programs registers itself with the executive under two names, as follows:

	GL		GlobalLister
	CL		CodeLister
	SL		SymbolLister
	BL		BcdLister

Thus if you dislike short names you can rename the bcd on your disk to one of
the above names.


GLOBAL FRAME LISTER (GL)

GL provides information about global frame usage.  Its purpose is to help you
discover global frames that could easily be made smaller and/or to discover global
state that should be protected by monitors.  You should find the output more helpful
and less intimidating than that produced by BL and SL.

Usage:

  GL file1 file2 ...

where file1, file2, etc. are names of object files (extension .bcd assumed)
produced by the compiler (for a module) or the binder (for a configuration). 
The output is written to files file1.gl, file2.gl, etc.  There is one switch (/t)
which specifies that the output is to go to the typescript of the invoking
executive instead.  This switch may be used locally or globally.  For example,

  GL /t <pattern>.bcd

is useful for looking at a small collection of modules, while

  GL SomeConfig.bcd

might be more appropriate for examining a large config.  Note the symbol tables
for the component modules must be available on your local disk to get useful
information about a config.

For each module, the following information appears in the output:

 (1) the module name
 (2) the global frame size (in words)
 (3) the number of global frame index slots (gfi's) required (if > 1)
 (4) a list of variables in the global frame, with the size of each (in words)
 (5) a message if the module contains any STRING literals or StringBody's
      in the global frame (sorry, there's no more detail than this in symbol tables)
 (6) the number of words in the global frame not attributable to the variables
      listed in (4) or to frame overhead.

Notes:

 (a) Global frames have 3 words of overhead; however, a stateless global frame
      requires 4 words because of the way start traps are handled.
 (b) If a module is a (vanilla) monitor, the first variable is LOCK, an
      implicitly declared monitor lock.
 (c) If a module uses rope literals or atoms, a variable &refs will be listed; its
      size will be twice the sum of the numbers of rope literals and atoms.
 (d) If a module provides or uses runtime type information, a variable &types
      will be listed; its size will be equal to the number of type codes required.
 (e) Removing the items causing message (5) is a good idea even in non-Cedar 
      modules; the strings occupy MDS space, and module replacement will never
      be supported for such modules.
 (f) The number of words reported in (6) is approximately the number of words
      used for the bodies of global STRING literals and STRING variables.


CODE LISTER (CL)

The program CL can list the object code for a single procedure within a module
as well as the code for an entire module.  In addition, it is (currently) the only
lister program that allows you to redirect the output.

Usage:

The command

    CL output _ input

where "input" is a single identifier, produces a code listing for the module
input.bcd on the file output.cl (which defaults to input.cl if "output _" is omitted).
The command

    CL output _ input.proc

where "input" and "proc" are single identifiers, produces a listing of all procedures
with name "proc" in the module input.bcd.   Capitalization with the procedure
identifier must be correct.  Output goes to output.cl (proc.cl by default).  Note
that you should not specify the extension ".bcd" explicitly; the command

    CL output _ input.bcd

is not correct (unless "bcd" is the name of a proc you want listed).