Page Numbers: Yes First Page: 23 X: 527 Y: 10.5"
Margins: Binding: 13
Odd Heading:
Binder
Even Heading: Not-on-first-page
Binder
Appendix C: Binder
The Mesa Binder combines modules and previously bound configurations to produce a new configuration. The configuration description language C/Mesa is used to describe desired configurations to the Binder. It is documented principally in section 7.7 of the Mesa Language Manual, Version 5.0; and in the Binder Change Summary. The output of the binder is a binary configuration description (Bcd) which may be loaded into a running system or processed by a later invocation of the Binder. This appendix discusses the operation of the Binder including its switches and error messages.
File Organization
In order to understand the Binder options described below, it is necessary to understand something about how configurations exist in files. The Bcd file produced by the Binder normally contains only the compiled description of the configuration; it does not contain any code or symbols. For each module instance in the configuration, the Bcd specifies the location of the code and symbols by file name (and version stamp), starting page, and number of pages. Thus the code and symbols for a configuration may be scattered over a large number of files. It is possible to put the Bcd, the code, and the symbols in the same file (this is the way Bcds are generated by the Mesa compiler).
While debugging, the "normal" mode of operation is not to copy code or symbol segments to another file (this is the default). Instead, they are left in the files generated by the compiler. This saves disk space and requires the least binding time.
For distribution, the code or symbols of the configuration’s modules can be copied to an output file. This is selected by switches and parameters on the Binder’s command line. Code is usually copied into the same file containing the Bcd. It is possible to copy code into a file other than the Bcd file, but this is not very useful. Symbols may be copied into the Bcd file, but they are usually written to a separate file.
It is a good idea to package the symbols of a released subsystem into a separate file, so that they will not take up disk space when they are not in use. This also makes it easier to keep track of a consistent set of symbols for all of the modules. Because the Binder and Loader deal only with interfaces, symbol tables are not required for binding or loading. Of course, they are required for meaningful debugging.
The Binder also has an option to compress symbol tables as they are copied. In this mode, just signals declared at the top level and all (public and private) procedures of modules are included. No other symbols are copied. This option allows limited but often adequate debugging, and will substantially reduce the size of the symbols file (typically by more than 50%).
Running the Binder
The Binder is a Bcd file, and Mesa.image must be used to run it. When compressing symbols, SymbolCompressor.bcd must be loaded first; see the description of the /x switch below.
User Interface
The Binder reads commands from the executive’s command line (through the file Com.cm). At the start of the first binding, the message "bind" is displayed in the cursor. If there are any warnings, "warning" is displayed, and if there are errors, "errors" is shown. At the end of binding, the message "Type Key" is displayed in a flashing cursor if there are errors and you have requested the Binder to pause. Typing Shift-Swat aborts the executive’s current command sequence; Control-Swat invokes the Mesa Debugger; any other character causes normal exit from the Binder.
A summary of the Binder’s commands is written on the file Binder.log. The error and warning messages from binding, say Foo.config are found on Foo.errlog.
Commands
The Binder accepts a sequence of one or more commands, each of which usually has one of the following forms:
inputFile/switches
outputFile ← inputFile/switches
[key1: file1, ... keym: filem] ← inputFile/switches
In the third form the valid names for keyi are code, symbols, and bcd. (It is also possible to control the association between file names and included modules or configurations; this is described below.)
The string inputFile names the file containing the source text of the configuration description, and its default extension is .config.
There is a principal output file, the name of which is determined as follows:
If you use the first command form, it is inputRoot.bcd, where inputRoot is the string obtained by deleting any extension from inputFile.
If you use the second form, it is outputFile, with default extension .bcd.
If you use the third form and keyi is bcd, it is filei, with default extension .bcd; otherwise, it is obtained as described for the first form.
If the Binder detects any errors, the principal output file is not written, and any existing file with the same name is deleted.
You may also request that the code or symbols of the constituent modules be copied to an output file, as follows:
You request copying of code by specifying the /c switch or by using the third command form with keyword code. Code is copied to the principal output file unless you use the third form and keyi is code, in which case the code is copied to a file named filei, with default extension .code.
You request copying of symbols by specifying the /s or /x switch or by using the third command form with keyword symbols. Symbols are copied to the file inputRoot.symbols unless you use the third form and keyi is symbols, in which case they are copied to a file named filei, with default extension .symbols. Compressed symbols will be copied if the /x switch is specified.
Any warning or error messages are written on the file outputRoot.errlog, where outputRoot is the string obtained by deleting any extension from the name of the principal output file. If there are no errors or warnings, any existing error log with the same name is deleted at the end of the bind.
When more than one Binder command is given on the command line, the commands must be separated by semicolons. However, you may omit a semicolon between any two successive identifiers (file names or switches), or between a ] and an identifier (but not between an identifier and a /). Note that any required semicolon in an Alto Executive command must be quoted.
Switches
The optional switches are a sequence of zero or more letters. Each letter is interpreted as a separate switch designator, and each may optionally be preceded by - or ~ to invert the sense of the switch.
The Binder recognizes the switches:
/c- copy code
/s- copy symbols
/p- pause after binding if there are errors or warnings
/r- run the specified .image or .run file
/x- copy compressed symbols
/g- (has no effect; retained for compatibility with Mesa 5)
By default, the binder will pause after completing all commands if any errors were reported. A /p switch can be specified on a command to cause the Binder to pause if there were any errors or warnings on that binding step.
The switch /r (run) is used to specify that the Binder should run some other program rather than returning to the Alto Executive. Use of this switch is described in the Context Switching section below.
In order to copy compressed symbols with the /x switch, SymbolCompressor.bcd must be loaded with the Binder. This may be done with a command line of the form
>Mesa.image SymbolCompressor.bcd Binder.bcd ...
Global switches are set by a command with an empty file name. Each of the switches listed above, except for /r, can be specified as a global switch. Note that unless a command to change the global switch settings comes first in the sequence of commands, it must be separated from the preceding command by an explicit semicolon.
Associating Files with Modules and Configurations
The Binder lets you control the association between file names and the modules or configurations included in a configuration when you call it. This is done by specifying a list of component identifier-file name pairs inside brackets after the input file name. Such a list can be thought of as augmenting or replacing a DIRECTORY clause in the configuration description. For example, the command line
>Binder.bcd MySystem[Test: UnpackedTest]
will bind MySystem.config using the previously bound configuration Test that is stored on the file UnpackedTest.bcd.
A command that includes one of these optional component-file name lists will have one of the forms:
inputFile[id1: file1, ... idn: filen]/switches
outputFile ← inputFile[id1: file1, ... idn: filen]/switches
[key1: file1, ... keym: filem] ← inputFile[id1: file1, ... idn: filen]/switches
The module or configuration named by idi in the configuration description will be read from the file filei. The extension .bcd is assumed for the file names.
Binder Command Line Examples
>Binder.bcd MySystem
Read MySystem.config and write the resulting Bcd on MySystem.bcd. This is the "normal" debugging mode since it is the fastest and requires the least disk space.
>Binder.bcd MySystem/c
Read MySystem.config, write MySystem.bcd. Copy all code segments into MySystem.bcd. Leave all symbol segments as they were in the input files. This is a possible "distribution" mode.
>Binder.bcd MySystem/cs
Read MySystem.config and write the resulting Bcd on MySystem.bcd. Copy all code segments into MySystem.bcd, and copy all symbol segments into MySystem.symbols. By packaging all of the symbols in a single file, you minimize the risk of getting an incorrect version of some symbol table. This is also a possible distribution mode, if debugging will be required.
>Mesa.image SymbolCompressor.bcd Binder.bcd MySystem/cx
Read MySystem.config, write MySystem.bcd. Copy all code segments into MySystem.bcd; compress all symbol segments into MySystem.symbols.
>Binder.bcd MySystem[SubSystem: ExperimentalSubSystem]
Read MySystem.config, write MySystem.bcd. Read the included subconfiguration SubSystem from the file ExperimentalSubSystem.bcd.
>Binder.bcd MySystem ← NewSystem.config/cs
Read NewSystem.config, write MySystem.bcd. Copy all code segments into MySystem.bcd and all symbol segments into MySystem.symbols. Commands with "left hand sides" allow renaming of the output (bcd, symbol, and code) files.
>Binder.bcd [bcd: MySystem.bcd, symbols: MySystem.bcd] ← NewSystem/c
Read NewSystem.config, write MySystem.bcd. Copy all code and all symbol segments into MySystem.bcd.
>Binder.bcd SubSys MySystem/cs
Read SubSystem.config, write SubSys.bcd. Then read MySystem.config, write MySystem.bcd; copy code into MySystem.bcd and symbols into MySystem.symbols.
>Binder.bcd /-p SubSystemA SubSystemB MySystem
Bind SubSystemA, SubSystemB, and MySystem and do not pause even if there are errors.
>Binder.bcd SubSystemA/p SubSystemB/p MySystem
Bind SubSystemA, SubSystemB, and MySystem as usual; in addition, stop after binding SubSystemA or SubSystemB if either contains errors.
Context Switching
The command line switch /r (run) is used to specify that the Binder should run some other program rather than returning to the Alto Executive. The program’s name is given by the filename before the /r. Both ".image" and ".run" files may be specified. If there is no explicit extension, ".image" is assumed. Any switches after the r and any other text remaining in the command line after the file with the /r switch will be passed to the new program.
Examples:
>Binder.bcd SomeConfig Mesa.image/r SomeConfig
will bind SomeConfig and then run Mesa.image as if you had typed Mesa SomeConfig.
>Binder.bcd SomeConfig Mesa/rd OtherConfig/-s SomeConfig
will bind SomeConfig and then run Mesa.image as if you had typed Mesa/d OtherConfig/-s SomeConfig.
>Binder.bcd SomeConfig/c Ftp.run/r Iris Store SomeConfig.bcd
will bind SomeConfig copying the code and then run Ftp.run as if you had typed Ftp.run Iris Store SomeConfig.bcd.
Fine point:
To detect the end of the command the Binder’s command line scanner reads a few characters beyond the /r. These characters must look like the beginning of a valid Binder command. This means that a semicolon must be placed after the command containing the /r if the next token is not an identifier (e.g., if the token is a global switch for the program being run).
Error Messages
If possible, the Binder will indicate the offending source line and configuration name with each error. Some of the common error messages are:
interface is undeclared
An attempt is being made to import the interface (or program) interface, but interface is neither imported from a higher lever configuration nor exported by any module or configuration at the same level.
id does not match the module or configuration name in the Bcd
The identifier used to name a module or configuration in a configuration description must exactly match (including capitalization) the name used inside that module or configuration.
item from interface is unbindable (imported by module)
(item nnn) from interface is unbindable (imported by module)
(Warning) An item from interface has no implementation. If symbols for the importer or the interface can be found, the item’s name is printed. Otherwise, the item’s interface number is printed, and you can count (from 0) the interface items in interface or use the Lister’s Interface command to get more information.
file is referenced in two versions: (version1) and (version2)
(Warning) Two different versions of the named file are referenced by the modules being bound. This will produce an error if you attempt to match the two versions as import and export.
interface1 (version1) is required for import, but only interface2 (version2) is available
interface2 is available for import (or being passed as a parameter), but the importer requires interface1. The source line shows the importer.
interface1 (version1) is being exported, but interface2 (version2) is required
The source line shows an exporter of interface1 who is trying to assign the interface (implicitly or explicitly) to interface2. This may be a version problem (if the interface names are the same) or an error in an assignment.
interface is not imported by any modules
interface is not exported by any modules
A configuration must tell the truth about what it IMPORTS and EXPORTS, i.e. everything imported or exported by a configuration must actually be imported or exported by a contained module or configuration.
file could not be opened to copy symbols
(Warning) When copying symbols, the file containing the symbol segments for a module could not be opened. The copied symbols file will still be produced, but will not contain symbols for the module; thus limited debugging will still possible using the symbols file.
The following modules were compiled for Alto (others were not)
An attempt has been made to bind modules compiled with the /A switch and modules compiled with /-A.
The following modules were compiled /L (others were not)
(Warning) An attempt has been made to bind modules compiled with the /L switch and modules compiled without it.
Code links will be added to the previously bound configuration name
Code links are requested for the previously bound configuration name
(Warning) It is usually a bad idea to impose code links on a configuration that did not specify them when it was originally bound. That is to say, LINKS: CODE should be specified only on the lowest level configuration that is bound. You should certainly never add code links to a configuration without careful consideration; it may contain a module with multiple instances bound differently (requiring frame links). The first message comes from the code copying routines (desire for code links is noted in the Bcd when a configuration is bound, but space for them is generated only when code is copied); the second message is generated if code is not being copied in this execution of the Binder.
Errors detected, Bcd not written
The Binder has produced no output.
Fatal Binder Error
Fatal errors are reported in a fashion similar to the Compiler; the signal and message are given in octal, and should be included in any change request reporting a fatal Binder error.
Current Limitations
The DIRECTORY clause in a configuration description should be used only when the name of a module or configuration differs from the name of its file. Do not make DIRECTORY entries for interface (DEFINITIONS) files.
The output Bcd file can be renamed; the symbols file cannot (since the Bcd contains the name of this file in its internal tables).
Multiple instantiations of nested configurations are not implemented. You can get around this by binding the nested configuration in a separate step.
Estimated running time: five seconds for initialization plus one-half second per included file (module or configuration). Add one second per module to copy code and one second per module to copy symbols.