Page Numbers: Yes First Page: 40 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading: Not-on-first-page
Utilities
Even Heading:
Utilities
Appendix F: Utilities
Described below are several utility packages that have proved useful in building Mesa systems. The Lister produces symbolic listings of various Mesa file formats. The IncludeChecker checks for object file consistency. The Statistics package generates source and object statistics. The SignalLister and BcdSignals produce mappings of signals and signal values.
Lister
The Lister produces listings of bcds, interfaces, etc. from object files. To use it, retrieve Lister.bcd (running it requires Mesa.image). The Lister operates in either command line or keyboard mode. Commands look like procedure calls with constant (string, numeric, character, boolean) arguments. Arguments are type checked by the command interpreter. In command line mode, type to the Alto Executive:
>Lister command1[arg1, arg2, ...] command2[arg1, ...]
You actually type the square brackets, as in a Mesa procedure call.
For parameters of string type, the quote marks are optional; the scanner will take any characters up to the next comma or right bracket if the first character is not a quote.
In keyboard mode you just type the command with arguments. Typing the ESC key will extend the command name if a unique command exists. The Lister will prompt for arguments if the command name is terminated with CR. Typing ? in keyboard mode will produce a list of available commands and their arguments.
Almost all of the lister commands read one or more BCD files and extract information from them. They can be either the output of the Compiler or the output of the Binder. In the case of a single file, the parameter is the name of the file; if no extension is given, ".bcd" is assumed. Some commands take a list of files. In this case, the parameter specifies a file (such as object.defs) that contains a list of Bcds, separated by blanks.
The commands are divided into two sections below: those of general use, and those used primarily internally by the Mesa implementors. Quote marks are shown on command parameters that are of string type; it is usually not necessary to type them to the Lister.
Commands Useful to General Mesa Users
CompressUsing["Filename"]
Filename contains a list of compiler output Bcds. The using lists of the directory statement are generated for each module in the list; they are then sorted to show for each interface, and for each item in the interface, which modules reference that item. The same caveat about implicitly included symbols applies as for the Using command. The output is written to file.ul.
Debug[]
Invokes the Debugger.
Image["Filename"]
Makes an image file. If no extension is specified, .image is assumed. ImageMaker must be loaded before using this command.
Implementors["Filename"]
Filename contains a list of compiler output Bcds (interfaces and program modules). This command creates a file, Filename.iml, showing for each interface exported by any program in the list, where the various interface items are implemented. If the list also includes the Bcd for a particular interface, the interface items not implemented by any program are also shown. In order to run this command, one needs not only the Bcds in the list, but also the Bcds for the interfaces exported by the programs therein. Missing Bcds are reported and the command attempts to forge on.
Interface["Filename"]
Given the Bcd file for an interface (DEFINITIONS file), this command produces a list of the interface items and numbers (on Filename.il). These numbers are the ones reported by the Binder for unbindable items.
Load["Filename"]
NEWs and STARTs the module Filename. An escape hatch allowing other programs to run in the Lister environment.
Quit[]
Returns to the Alto Executive.
Run["Filename"]
Invokes another image file (if extension is .image) or a BCPL program (if extension is .run). If no extension is specified, .image is assumed.
Stamps["Filename"]
Filename is a compiler or binder output Bcd. This command generates a file, Filename.bl, that shows the version stamps of any modules bound in the file, and of all imports and exports of the top level configuration in the file.
UnboundExports["Filename"]
Filename is a compiler or binder output Bcd. This command examines all of the exported interfaces and enumerates interface items in those interfaces that are not exported by this module or configuration.
Using["Filename"]
Filename is a compiler output Bcd. This command generates a directory statement with its included identifier lists (on Filename.ul). Since there is not enough information in the Bcd to tell which symbols were implicitly included, the USING clauses may contain a superset of those items actually needed.
UsingList["Filename"]
Filename contains a list of compiler output Bcds. This command creates a ".ul" file for each file named in the list.
Version["Filename"]
Filename is a compiler or binder output Bcd, or an IMAGE file. This command shows, on Mesa.typescript, the object, source, and creator version stamps of the file.
Xref["Filename", IncludePrivateSymbols, ProceduresOnly]
Filename contains a list of compiler output Bcds. This command creates a file, Filename.xref, that contains a sorted list of all declarations (subject to setting of the two boolean parameters) in the collection of modules and interfaces.
XrefByCaller["Filename"]
Filename contains a list of compiler output Bcds. This command creates a single file, Filename.xlr, that shows for each procedure of each module in the list, what other procedures it calls. It does this by scanning the code for the modules. It does an imperfect job in that it cannot tell who is being called via a procedure variable. However, if there are any procedure variables called, it makes an entry for "*" in the list of called procedures. The user can check these procedures by hand. It does not report calls to procedures nested within the given procedure.
XrefByCallee["Filename"]
This is similar to XRefByCaller, except that the results are shown sorted by callee. Thus, the entry for "*" is the set of procedures in the list of modules that contain calls to procedure variables.
Commands Useful to Wizards
Bcd["Filename"]
Filename is a compiler or binder output Bcd. This command produces a listing of the internal tables of the binary configuration description (on Filename.bl).
BcdLinks["Filename"]
Same as the Bcd command, except that the control links of imported and exported items are included.
BcdSegment["Filename",Base,Pages,Links]
The most general form of the Bcd command allowing you to specify the location of the Bcd by filename, starting page number, number of pages, and whether you want the links (specify TRUE or FALSE).
Code["Filename"]
Filename is a compiler output Bcd. This command produces a listing of the object code (on Filename.cl). If the source file is available on your disk, the source for each statement is listed just before the object code.
Warning: This command produces a large amount of output.
Warning: If the module is subsequently packaged, the code offsets will change (although the sequence of operations will be the same). If one is making listings for low level octal debugging, be sure to make new listings of code for packaged modules using the CodeInConfig command.
CodeInConfig["Config", "Module"]
Config is a binder or packager output Bcd; Module is a module within that configuration. A code listing is produced for the module (see the Code command). This is of particular interest for packaged configurations.
OctalCode["Filename"]
Same as the Code command, except that opcodes are given in octal as well as by name.
Warning: This command produces a very large amount of output.
OctalCodeInConfig["Config", "Module"]
Config is a binder or packager output Bcd; Module is a module within that configuration. A code listing is produced for the module (see the OctalCode command). This is of particular interest for packaged configurations.
Symbols["Filename"]
Given a compiler output Bcd, this command lists the internal symbol table (on Filename.sl).
SymbolSegment["Filename",Base,Pages]
A more general form of the Symbols command allowing complete specification of the location of the symbols (e.g., in a .symbols file).
There are several other commands that are either self documenting or uninteresting to all but the most hardcore compiler debuggers.
Include Checker
The IncludeChecker is a program that examines a collection of Mesa source and Bcd files for consistency. It produces an output listing that gives a compilation order for the files, and for each Bcd, a list of all the Bcds that it includes, and a list of the Bcds which include it. Any inconsistencies (which are described below) are flagged in this listing by an asterisk. As an option, the IncludeChecker will also generate a compilation command on Line.cm that can be executed to make the files consistent.
The IncludeChecker determines that an inconsistency exists among the input files if either:
1.A Bcd includes another Bcd with a version different from the one currently on the disk. This might happen, for example, if the included Bcd had been recompiled.
2.A source file is "newer" than the corresponding Bcd. This could happen if the source had been edited, or if the source had been retrieved from a remote file server. The IncludeChecker compares the creation date of the source file against the creation date recorded in the Bcd of the source file from which the Bcd was derived.
The IncludeChecker operates in either command line or interactive mode. To use it in command line mode, type to the Alto executive:
>IncludeChecker [outputfile][/switches] [filename1 filename2 ...]
where
outputfile is the name of the file written. If no extension or switches are given, .list is assumed. If no file name is specified, the file Includes.list is assumed.
filename1 filename2 . . . is the list of file names specifying the source and .bcd files to be checked. It is not necessary to give an extension, since the IncludeChecker will look for any .mesa or .bcd file with the specified name. If no input files are specified, all .mesa and .bcd files on the disk are examined.
To use the IncludeChecker interactively just type:
>IncludeChecker
It will then prompt for the output file name and switches, and then a list of the files to check. These are typed one at a time, and the list of file names is terminated by a CR. Typing ? CR in interactive mode displays a short summary of the IncludeChecker’s parameters and use.
Each switch can be preceded by a - or ~ to reverse its meaning. The switches are:
/oPrint a compilation order in the output file (this is the default); -o suppresses this listing.
/iPrint both the includes and included by relationships in the output file (default).
/tObtain the creation date of source files from their leader page (default); -t will attempt to get the creation date from the first few lines of the source text.
/cWrite a consistent compilation command in Line.cm (-c is the default). In addition, list as comments any Bcds and source files not on the disk which are needed to do the compilation.
/mUse multiple output files (-m is default). The compilation order is written on source.outputfile. The includes and included by relations are written onto outputfile.includes and outputfile.includedBy, respectively. This switch is useful if the output would otherwise be too large to fit into Bravo.
/nDon’t list for compilation modules having no current object file on the disk. That is, a .mesa but no .bcd.
/pPlace a /p after every change of inclusion depth (see below) in the compilation command (-p is default). This will cause the Compiler to pause if errors are found while compiling that or any previous module.
/sSame as /c-i-o. This is used when only a consistent compilation command is needed.
The default switches are /oit-c-m-p-s.
Note: The IncludeChecker only checks for consistency of the files that you specify. Thus, the list of files that you give should include, for example, any important system files upon which your files are dependent.
It is also a good idea to inspect the consistent compilation command before executing it, since the IncludeChecker’s idea of what should be recompiled may not be the same as yours.
If a source file but no Bcd is found on the disk, the IncludeChecker outputs a warning on the display; in addition, it adds that file to the compilation command if /c is in effect. A warning is also displayed if a Bcd is found that was created by an obsolete version of the Compiler; its source file is also added to the compilation command.
The IncludeChecker lists the file names of the compilation order and the consistent compilation command by inclusion depth, with the files that are the most deeply included first. Within that constraint, definitions modules are printed before program modules. In general, then, the "lowest level" definitions modules appear first, while the "highest level" program modules appear last.
As an example of the IncludeChecker’s use, the command line
>IncludeChecker IC/c IODefs IOPkg LexiconDefs Lexicon LexiconClient
will produce a consistent compilation command in Line.cm and the output shown below on IC.list.
Compilation Order (by inclusion depth):
LexiconDefs streamdefs stringdefs
IODefs
oldstringdefs systemdefs tty windowdefs
IOPkg Lexicon LexiconClient
IODefs (4-May-80 16:20:37 60#203#) (compilation source: 14-Apr-80 17:37:16) includes
streamdefs
stringdefs
IOPkg (28-May-80 9:30:01 60#203#) (compilation source: 28-May-80 9:08:43)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
oldstringdefs
streamdefs
tty
windowdefs
Lexicon (28-May-80 9:30:29 60#203#) (compilation source: 28-Apr-80 17:02:20)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
LexiconDefs (14-May-80 10:48:49 60#205#)
oldstringdefs
systemdefs
LexiconClient (28-May-80 10:02:50 60#203#) (compilation source: 28-May-80 10:02:14)
(source on disk: [same]) includes
IODefs (4-May-80 16:20:37 60#203#)
LexiconDefs (14-May-80 10:48:49 60#205#)
oldstringdefs
LexiconDefs (14-May-80 10:48:49 60#205#) (compilation source: 18-Apr-79 19:19:11)
(source on disk: [same]) includes nothing
IODefs is included by
IOPkg Lexicon
LexiconClient
IOPkg is included by nothing
Lexicon is included by nothing
LexiconClient is included by nothing
LexiconDefs is included by
Lexicon LexiconClient
SignalLister
SignalLister is a program which will produce a signal listing for an image file, (e.g., Mesa.signals). It can also list the starting PC and length of procedures within an image file, (e.g., Mesa.procs). This information is particularly useful to determine what procedures are on the stack when there are no symbols on the disk or as an aid to repackaging code. To produce a signal listing for Foo.image, type to the Alto Executive:
>SignalLister Foo[/switches]
where
/plists byte PC, length, and names of the procedures in Foo on Foo.procs.
/slist signals of Foo (default) on Foo.signals.
If the symbols for a module are not available, no signals for that module are listed. For example, if Foo.image was made by loading Foo.bcd on top of Mesa.image (along with ImageMaker.bcd, of course), a complete signal listing for Foo.image will require that Mesa.symbols and all the symbols for Foo.bcd be on the disk. If Mesa.symbols is not present, only those modules from Foo.bcd will have their signals listed.
Statistics Package
This package gathers statistics about Mesa source and object files and writes them on Mesa.typescript. It may be invoked either interactively or from the command line. To invoke it from the command line, type the following to the Alto Executive:
>Statistics filename[/switches] . . .
Output is to the display and to Mesa.typescript. If no filenames are specified on the command line, Statistics enters the interactive mode. Type ? to get full documentation. The following switches are used:
/b -- bcd statistics (default).
/c -- command: use filename as switch.
/d -- invoke debugger.
/h -- print heading (default).
/m -- source statistics (default).
/s -- print subtotal.
/t -- print total.
/x -- "Management" statistics (i.e. chars, lines, code bytes, and frame sizes).
The following command line will generate the output shown below:
>Statistics AlFont DisplayControl StreamIO SystemDisplay t/c
Alto/Mesa Statistics Package 6.0
Statistics as of 22-Oct-80 4:37:48
chars lines code frame ngfi nlinks code symbol
bytes size pages pages
------ ----- ------ ------ --- ------ ----- ----
AlFont 5696 175 576 4 1 6 2 13
DisplayControl 7694 255 912 6 1 35 2 18
StreamIO 6376 216 924 7 1 5 2 11
SystemDisplay 15524 492 1988 7 2 8 4 22
------ ----- ------ ------ --- ------ ----- ----
TOTAL: 35290 1138 4400 24 5 54 10 64
Sometimes the program puts an asterisk after the number of code pages for a module. This means that the number of code bytes is very close to a page boundary, and the number of links is such that binding with code links will cause the code to "spill over" into another page.
BcdSignals
BcdSignals is a program which will produce a signal listing from a .bcd file; it works much like the SignalLister. To produce Foo.signals from Foo.bcd, type to the Alto Executive:
>BcdSignals [octalNumber/switch] Foo[/switches]
where
/ntakes octalNumber to be the global frame index of the first frame in this Bcd. This will normally be the first free global frame index in the system into which the Bcd will be loaded.
/xtakes octalNumber to be the StartPilot loadmap form of a global frame index. This is the number in brackets beside the module name in the loadmap. Use 200B times the octal number used with the /n switch.
/plists the name, byte PC, and length of each procedure in Foo on Foo.procs.
/slist the signals of Foo on Foo.signals (default).