Mesa User's HandbookVersion 6.0October 1980This handbook contains documentation for using all of the standard Mesa services intended forMesa programmers as well as operational procedures for the Alto. In general, the sections are shortand to the point, serving as a how-to guide rather than a reference document containing all of thedetails. This handbook assumes prior familiarity with the Mesa language as well as the Alto.XEROXOFFICE PRODUCTS DIVISIONSystems Development Department3333 Coyote Hill Road / Palo Alto / California 94304 W;p P4qX NF Gb./ Et@$ CF A]-#Gr- sX-t-7uF4  =?AK ^i Table of ContentsPrefacev 1. Getting started 1.1. Setting up your Alto disk1 1.2. Installing the debugger1 1.3. Preparing your source file1 1.4. Compiling your program2 1.5. Binding your configuration2 1.6. Running your program2 1.7. Debugging your program2 1.8. Reporting problems3 2. Directories4 3. Resources5 Appendices A. Compiler8 B. Formatter17 C. Binder23 D. System30 E. Debugger33F. Utilities40G. RunMesa48iii%\pi WqH RHxP4HxMrHxJHxGHxE-HxBlHx?Hx<H 7H 2 H . x+E Hx( Hx% Hx# Hx ? Hx} Hx H, r h= U ^i PrefaceOctober 1980This handbook contains documentation for using all of the standard Mesa services intended forMesa programmers as well as operational procedures for the Alto. In general, the sections are shortand to the point, serving as a how-to guide rather than a reference document containing all of thedetails. This handbook assumes prior familiarity with the Mesa language as well as the Alto. Allsuggestions as to the form, correctness, and understandability of this document should be sent toyour support group.This documentation is divided into 4 parts. Section 1 describes the basics needed to get started,Section 2 lists the directories that are of interest to Mesa users, Section 3 lists various resources youshould be aware of, and Appendices A through G give further details on the Compiler, Formatter,Binder, System, Debugger, Utilities, and RunMesa. The style of this handbook is similar to that used in the Mesa Language Manual. All fine pointsare in this font, user input/debugger output and file names are in this font, and references toother documents are in this font. v)HI p(FqX A ./ ?d@$ =F <K :nA 8 5x-rq 3rqrq 2)r qrq1 02 -3:sq +t qu q )s q,J h=B ^i 1Section 1: Getting StartedThis section tells you all that you need to know for getting started and running a Mesa program.See the appendices for further details on the various subsystems and a sample debugging session.1.1. Setting up your Alto diskIf you are setting up an Alto disk from scratch, either copy the standard Mesa disk maintained byyour support group or obtain the command file MesaDisk.cm, which transfers the basic runtimefiles, as well as Bravo (and a Mesa User.cm file), to your Alto disk. You also need to install the AltoOperating System version 18, Executive 11, using erase option, before executing the command file; this should leave yourdisk with about 4000 free pages (for a single model 31 disk). If you just wish to get a new Mesa system on analready initialized disk, obtain the command file Mesa.cm. Mesa 6.0 requires Alto Operating Systemversion 18, Executive 11 (or newer versions) for proper operation.In either case, the basic Mesa runtime files that are transferred are: (1) RunMesa.run, a BCPLprogram which loads the ram with the Mesa emulator, loads main memory with the kernel Mesasystem, and starts execution, (2) Mesa.image, the Mesa system, (3) Compiler.image, thecompiler, and (4) Binder.bcd, the binder, (5) XDebug.image, the debugger, (6)MesaFont.strike, and (7) the system definitions files. Note that you need approximately 1800 pages forall of the Mesa files plus about 700 pages for Bravo and related files. These command files also install thedebugger (and Bravo).If the file MesaFont.al exists, Mesa will use it for the system display; otherwise SysFont.al isused.1.2. Installing the debuggerIn order to establish the communication link between the debugger and the Mesa system, you mustinstall the debugger. This installation is similar to installing the Swat debugger, for those familiar with thatoperation. Make sure your Alto disk contains the debugger, XDebug.image.The debugger is installed by typing XDebug to the Alto Executive. This saves the debugger's coreimage on the file MesaDebugger and exits to the Alto Executive. You must have a strike font onthe disk, either MesaFont.strike or SysFont.strike. These can be obtained from yourfavorite source of Alto fonts; there is a version of Gacha8, called MesaFont.strike on therelease directory. If you want to load some of your own programs into the debugger, see Appendix E.1.3. Preparing your source fileThe Mesa compiler accepts both unformatted ASCII and formatted Bravo text files. The debuggeruses source files for setting and displaying breakpoints. Since the debbugger ignores Bravo trailers,you are advised to indent programs with tabs and spaces. If the source files on your Alto disk arenot consistent with the object files, you will be restricted in your use of the debugger.Ifp"\qi Wr4, Up` PzpX M,rI K s r# I$srt! HYf F-r/ E-srt' CB @7r1s rt >rC <"s r s r ;As rs r 9sr't" 7Gr" 6K 2 s r&s r 1U ,_pX )rW 'iur t\ % r0trs r "s$sr4 s r+ %srs r" })sr t5 pX r+tr% !E C,ur" Y T>Y1Getting started21.4. Compiling your programThe compiler allows several options on the command line to control what is being compiled, andwhat interfaces are used; see the compiler section of this document for details. In the simplest case,type Compiler source1 source2 . . . directly to the Alto Executive, making use of its filenamecompleter if you wish. The compiler assumes a ".mesa" filename extension if one is not supplied,and produces object files with an extension of ".bcd". Compiled versions of all DEFINITIONSmodules that your program uses must be on your disk.If a syntax error occurs, the compiler attempts to recover by deleting and/or inserting text (not inthe file), logs the change(s), and tries to plow on. Semantic errors result in a symbolic print-out ofthe location of the error (in the form: procedure[character-position]) and an indication ofthe type of error. The semantic passes try very hard to muddle through with a complete diagnosis.The compiler puts all error messages in the file sourcename.errlog. When compiledsuccessfully, the resulting object file is found on sourcename.bcd. If the compilation is notsuccessful, any existing file named sourcename.bcd is deleted.1.5. Binding your configurationThe binder is available in ".bcd" form, so the file Mesa.image is needed on the disk in order torun it. The binder command syntax is similar to that of the compiler. In the simple case, typeBinder source1 source2 . . . directly to the Alto Executive, making use of its filenamecompleter if you wish. The binder assumes a ".config" filename extension if one is not supplied,and produces a object files with an extension of ".bcd".Compiled versions of all modules in your configuration must be on your disk. The binder goesthrough your configuration description, sourcename.config, and attempts to bind theIMPORTs/EXPORTs. All error messages are put in sourcename.errlog. When successfullybound, your sourcename.bcd file is ready to run. The binder puts a summary of the commandsit processes on the file Binder.log.1.6. Running your programType Mesa sourcename to the Alto Executive and your program will be loaded intoMesa.image and started. The process of loading your program includes binding your program'simports to the various interfaces exported by the system. At this point, you are well advised tobrowse through the Mesa System Documentation for complete details on what you can do. There isalso a conversational interface to the loader available as MesaExec.bcd. See Appendix D fordetails. Typing sourcename to the Alto Executive is the same as typing Mesa sourcename.bcd. See the AltoExecutive documentation and Appendix D for more details.1.7. Debugging your programIn order to set breakpoints in your program, trace program execution, display the runtime state, orinterpret simple Mesa statements, you must first invoke the Mesa debugger; there are several waysof doing this. The straightforward method is to append the switch "/d" to your sourcename onthe command line; this brings you into the debugger just before your program is started. If youwish to enter the debugger at any time (i.e., while your program is running), Control-Swatinterrupts your program. Once you are inside the debugger, typing "?" to the command processorgives you a list of the valid commands. The Mesa Debugger Documentation contains details onother ways of entering the debugger and complete documentation on all the available commands.#fpX b ^r*4 ](G [sur2 Ysr, X2srv Vr4 S<=' Q"E O sr NF02 Lsr J4s r IP$s r DZpX A rsrs r" ?dN =sur: <.sr :n2sr 7F 5x>(sr 3wrwrsr 2) s r" 0s w +pX (=r(sr; &s rC $B #Gur* !;s r  tw t,wt Q8 [pX  r21 eP 5sr s r !? o@ s r1sr "ur yI 2>]sGetting started31.8. Reporting problemsAny requests or problems with the Mesa system should be sent via the Adobe action requestsystem, using the Core Software option of ARSubmit.'fpXI b ^r&3 ](3 \= *%4Section 2: DirectoriesThese directories are maintained on [Iris]. Users without ready access to this file server shouldconsult their support group.Contains the .image and .bcd files of interest to users of the Mesa system. For files thatare not so generally used, look in the appropriate subdirectories described below.System>Contains the source and object files for the system definitions and program modules.Several packages constructed from standard Mesa system modules are also stored here.Compiler>Formatter>Binder>XDebug>Lister>Utilities>Ftp>Pup> (and FatPup>)Contains the source and object files for the compiler, formatter, binder, debugger, lister,utility programs, ftp, and pup respectively.Doc>Contains the documentation for the Mesa system; both .bravo and .press versions aremaintained here. In addition, a variety of sample programs, including Lexicon (describedin Chapter 7 of the Mesa Language Manual), can be found here.An informal directory containing packages and independent subsystems along withcorresponding documentation. The file Summary.Press contains a list of these packagesand a short description of each.This directory, on [Igor], contains the new version of the Mesa system during the alphatest period. When the system is ready to be released, the contents of the directorymoves to and the contents of moves to . fp \qi Wr$sr1 Up R"sNr srstr9M,R Is Fr$0DN As ? >J < : 9T 7 6 rsr2A1, -s *rr6srsr ()sr '#ur #s r)O's r"7 s rsr>+sr Ksrs r sr =U5Section 3: ResourcesThe following list enumerates resources that may be of interest to Mesa programmers. They can allbe obtained through the support group.DocumentsMesa Language ManualComplete reference on the language, syntax, and use of Mesa. See also the Compilerupdate memo for new language features in Mesa 6.Mesa System DocumentationDescribes configurations of the Mesa system software and the components which comprisethem.Mesa Debugger DocumentationDescribes the current release of the Mesa debugger.Mesa Ftp Functional SpecificationDescribes the procedural interface to the Mesa Ftp (file transfer) Package.Mesa Pup Package Functional SpecificationDescribes the procedural interface to the Pup Package. Pups (PARC Universal Packets)represent the lowest level interface to the Ethernet communications network.Debugger Extended FeaturesDescribes facilities for adding user generated facilities to the debugger.Integrated Mesa EnvironmentDescribes as a small executive for controlling the compilation, binding, and debugging ofapplications software This package greatly speeds up the compilebinddebug cyclewhen small changes are involved.Performance Mesaurement ToolControl Transfer Counting ToolDescribe facilities for measuring program performance.Change SummaryCompiler UpdateBinder UpdateIfp$\qi WrZ Up& Pzp M,sxIr/ srxH60 DsxAr>x? Mesa.signalsCompiler.signalsXDebug.signals*.signals contains a list of signal names, values, and global frame addresses for variousMesa components. These can be useful for interpreting signal values displayed by thedebugger when it has insufficient symbols to give the names symbolically.User.cmA User.cm file set up with the Mesa Bravo macros, Gacha10 for the editing font, andminimal printing fonts.MesaDisk.cmMesa.cmThe command files used for setting up a basic Mesa disk (as described in section 1.1).MesaFont.strikeA .strike version of Gacha10 suitable for use in the Mesa Debugger or Tajo.[Maxc1]MesaUsers.dl (or MesaUsers^ to Laurel).Distribution list for messages to the Mesa user community. If you wish to get on this list,talk to your secretary or .Other materialsThere have been a series of videotapes prepared which describe various features of the languageand runtime environment. See a member of your support group for further details on the tapesthat are currently available and where to get them.(fpI b ^t ]( [xX2r-#xV),xTI Qt xNFrtr(trxL IPt G xDZrIp r A tx=rtr tr/ :ntsrx7>x5xt r 0pX -3rR +E )3F )=>n8Appendix A: CompilerThe Mesa compiler translates Mesa source files into corresponding object files. An object filecontains the executable code for the module (if any), a binary configuration description (for use bythe binder or loader), and a symbol table (for inclusion by other programs or for use by thedebugger). By convention, an object file has a name with extension ".bcd".The Mesa Language Manual describes the syntax and semantics of the Mesa source language. Thisappendix describes the operation of the compiler, including the compile-time options and messages.Preparing Source FilesThe compiler accepts ASCII text files. In a source file, any sequence of characters that begins witha ^Z is skipped up to (but excluding) the next carriage return (or end of file). This conventionaccommodates Bravo formatting codes. You may use such formatting in your source files as yousee fit. Note, however, that Mesa does not interpret any information about fonts, position, etc.,attached to source text that it displays (e.g., in identifying the location of an error or breakpoint).The recommended extension for naming any Mesa source file is ".mesa".Standard Bravo macros useful during the editing and compilation cycle are described in the ContextSwitching section later.Running the CompilerThe compiler takes commands from the command line. The command line syntax is describedbelow in greater detail; the simplest form of command is a list of file names, such as>Compiler.image sourcefile1 sourcefile2 ... sourcefilenIf you supply the command sourcefile with no period and no extension, the compiler assumesyou mean sourcefile.mesa.During compilation, the display is turned off and a die is displayed in the cursor. The number onthe die identifies the pass of the compiler that is running. This allows you to check the progress ofthe compilation and also provides useful feedback to the maintainers of the compiler whensomething goes drastically wrong. The cursor moves down the screen to indicate progress through asequence of commands and to the right as errors are detected.Fine point:Don't confuse the compiler's cursor with DMT's.The compiler reports the result of each command on the file Compiler.log with a messagehaving one of the following forms (each * is replaced by an appropriate number; bracketed itemsappear only when relevant): fp \qi WrS Up sr sr Ss r R"Etr Nsr/ M,#? HYp E r32 CcZ AA @sr7 >mZ ;>tr 7V 6( 1Up .rX ,_V)t(u)t (u)t(v %rt r! $>tr X H33 T  T R= 'u / r"t r  G x 8 1=YCompiler9file.mesa -- source tokens: *, time: * [code bytes: *, links: *, frame size: *] [* warnings on file.errlog]Compilation was successful. The object file is file.bcd. For a DEFINITIONS module, themiddle line is not meaningful and is omitted. Otherwise, "links" is the number of itemsimported by the module, and "frame size" is the size of the global frame (in words),exclusive of the links. The third line appears only if warning messages were logged. Thecompiler issues warnings for certain constructs that are technically correct but nonsensical orlikely to be unintended. Warnings do not prevent writing a valid object file, but youshould usually investigate them.file.mesa -- aborted, * errors [and * warnings] on file.errlogCompilation was unsuccessful. You will find the error messages (and warning messages, ifany) in the indicated file. If the errors were detected during the early phases ofcompilation, no object file was written (and any existing object file with the same name wasdeleted).File errorThe compiler could not find the specified file.At the end of compilation, the message "Type Key" is displayed in a flashing cursor if there areerrors or warnings. (You can change this behavior by using switches, which are described below.)Typing any key will cause the compiler to exit.Fine point:Typing Shift-Swat aborts the Executive's current command sequence (i.e., causes any commands inREM.CM to be ignored); Ctrl-Swat invokes the Mesa Debugger; any other character causes normal exitfrom the compiler.Command Line ArgumentsThe Compiler allows you to control the association between modules and file names at the time youinvoke the compiler. The compiler accepts a series of commands, each of which has the formoutputFile _ inputFile[id1: file1, ..., idn: filen]/switchesOnly inputFile is mandatory; it names the file containing the source text of the module to becompiled, and its default extension is .mesa. Any warning or error messages are written on thefile outputRoot.errlog, where outputRoot is the string obtained by deleting any extensionfrom outputFile, if given, otherwise from inputFile. If there are no errors or warnings, anyexisting error log with the same name is deleted at the end of the compilation.If a list of keyword arguments appears between brackets, each item establishes a correspondencebetween the name idi of an included module, as it appears in the DIRECTORY of the sourceprogram, and a file with name filei; the default extension for such file names is .bcd. (If thename of an included module is not mentioned on the command line, its file name is computedfrom information in the DIRECTORY statement).The optional switches are a sequence of zero or more letters. Each letter is interpreted as aseparate switch designator, and each may optionally be preceded by - or ~ to invert its sense.)FfpIbstrtr`vtrtrt rt^rt stx[r0srtrw r xYtrxX2t r%xVUxTPxS<=xQNFstrt rt stxJrYxIPSxG9#xFBt x?dr/ <V :nK 8/ 5u x2pt u7x0wutu1x/D +EpX 'r U &ON #t#Gw#t#Gw#t#Gw#t#Gw#t rtr8 'tr3 Ztrt r1 t rtr*  O  S twr-wr KtwKrtr G wr trI Ctrtr ( >]omCompiler10If outputFile (and _) are omitted, the object code and symbol tables are written on the fileinputRoot.bcd, where inputRoot is inputFile with any extension deleted. Otherwise codeand symbols are written on outputFile, for which a default extension of .bcd is supplied. Ifthe compiler detects any errors, the output file is not written and any existing file with the samename is deleted.The compiler accepts a sequence of one or more commands from the Executive's command line(through the file Com.cm). Commands are separated by semicolons, but you may omit a semicolonbetween any two successive identifiers (file names or switches), or between a ] and an identifier (butnot between an identifier and a /). Note that any required semicolon in an Alto Executivecommand must be preceded by a single quote (').You can set global switches by a command with an empty file name. In the form /switches,each letter designates a different switch. Unless a command to change the global switch settingscomes first in the sequence of commands, you must separate it from the preceding command by anexplicit semicolon. Examples:>Compiler ReadOldFormat _ ReadData[DataFormat: OldFormat]Compile the program ReadData.mesa that has the included interface DataFormat in itsDIRECTORY statement. Use the file OldFormat.bcd (which contains the declarationDataFormat: DEFINITIONS = . . .) as the source of this interface. Put the object program inthe file ReadOldFormat.bcd.>Compiler /-aj SymStuff[Table: LongTable]/n SymExtra[Table: LongTable]Compile the files SymStuff.mesa and SymExtra.mesa, getting the definition of Tablefrom LongTable.bcd. Produce object files SymStuff.bcd and SymExtra.bcd.Don't produce code for the Alto, and cross jump both modules, generate NIL checks forSymStuff only (switches explained below).Compiler SwitchesSwitches allow you to modify command input. A command has the general formfile[/s]where [ ] indicates an optional part and s is a sequence of switch specifications. A switchspecification is a letter, identifying the switch, optionally preceded by a '-' or '~' to reverse thesense of that switch. The valid switches areaAlto instruction set (default)bbounds checkingfimplementation of floating point operations (default)jcross-jumping optimizationlimplementation of long pointer instructions in Alto emulationnNIL pointer checkingppause after compiling file if there are errorsrterminate compilation and run the program contained in filessort global variables and entry indices (default)uuninitialized variable checkingwlog warning messages (default)ywarning on runtime calls%fp  brt rtrH `vt rtrtr, ^ t r#tr ](30 [ X2: Vtr : TM S<tr9 Q/ NFHtr L"? JP IPu Fr Bt9@7rt rt r>wrt rr?x<\Hx:17ftx4rSx2p3&x05'x/!I&s rJs x-z r>x+'tr)x*+Fx(&s.x&9x$u n#$Qwtxr=xwr-x[&tr txrL x<xo*5x Lx sr -x y H ~ 2>]QCompiler12l[ong pointers]If specified, the compiler will generate code for a variation of the Alto instruction set thathas additional long pointer instructions and fewer alignment and minimal stack restrictions.Programs compiled /l will not run on an Alto, even if they contain no long pointers.n[il]If NIL checking is specified, the compiler inserts code to check for a null value prior to anyoperation that dereferences a pointer. Note that indexing operations using an arraydescriptor or a string also imply dereferencing and are checked. If the pointer value is NIL,the signal PointerFault from interface TrapDefs is raised. No compile-time checks for NILare performed.Fine Point: No NIL checks are provided in the dereferencing of relative pointers.Depending upon coding style, these runtime checks can increase the size of the compiledcode substantially.p[ause]This switch is unusual in that its meaning is slightly different depending on whether it is aglobal or local switch. As a global switch, it specifies pausing (p) or not pausing (-p) justbefore exiting from the compiler in the event of errors or warnings; the global default is topause. As a local switch, it specifies pausing just after compiling the specified file if thatfile or any preceding file contained errors; moreover, any remaining commands are ignored.The local default is not to pause but to continue with the next input file.r[un]This is described below under Context Switching.s[ort]Normally, the compiler sorts certain items by frequency of use before assigning addresses.This helps to keep the object code compact. If sorting is suppressed (-s), the assignmentsof global frame offsets and entry indices depend only upon order of declaration in thesource text. This switch was added in anticipation of tools allowing inexpensive correction and replacementof modules in a configuration. These tools are not yet available.u[ninitialized variables]If the /u switch is given, the compiler issues warning messages for uses of apparentlyuninitialized variables (but not fields of records). The algorithm used to detect suspicioususage is based upon the following assumptions:The entire body of a procedure is executed before the bodies of any proceduresdeclared within it.Within any procedure, the order of execution is equivalent to the order ofappearance of source text (for the purposes of variable initialization).The bodies of the contained procedures are executed in order of appearance.The algorithm works fairly well for detecting certain common errors, but it is obviously notfoolproof. There is no guarantee that all uses of potentially uninitialized variables are%fp  bt^r3+](N [sts@ X2tTrwr1'S<&.Q7#wrO s rsr(wNFr Kuwu?HrBG Ct@~r6'>Ctrtr=/H;_9sr@89K 4t1r0 .Mt*rO )W/tr'G& uN$aB !trtr:]u.?SG1H0 gX s C f y9]'Compiler13reported; conversely, properly initialized variables are sometimes flagged when theinitialization depends upon the order of execution of subprocedures. (Performance withrespect to global variables is improved by putting the initialization code for a module eitherin the main body or the lexically first procedure.)w[arnings]Log (w) or ignore (-w) certain legal but suspicious constructs that can be detected by thecompiler.y[ell about runtime calls]This switch is intended for use by programmers writing such things as bootstrap loaderswhere the standard Mesa runtime machinery is unavailable. It flags operations, such ascertain division, etc., that generate calls to system functions.Examples:>Compiler fooCompile foo using all the default switch settings.>Compiler foo/-wjAs above, but suppress warning messages and do cross-jumping.>Compiler /-p file1 file2 file3Use this form if you want the compiler to press on no matter what. If it is part of acommand file, the next (Executive) command will be executed whether or not there wereerrors.>Compiler file1 file2/p file3Use this form if you want the compiler to pause before compiling file3 if either file1or file2 does not compile successfully. If file3 depends upon the others (by includingthem), this can save a lot of wasted time and effort.>Compiler file1/p '; /-p file2 file3Use this form if you want the compiler to pause before compiling file2 if file1 doesnot compile successfully. Press on to the next Executive command even if file2 orfile3 does not compile.Context SwitchingIf you are a Bravo user, you might find the following macros useful for switching between Bravoand the Mesa compiler. They are included in User.cm.bravo/m filenameThis invokes Bravo with two windows, gets filename.errlog in a smaller, bottomwindow, and gets filename.mesa in the top window. (Be sure not to usefilename.mesa on the command line.))FfpI xbsr5Kx`vRx^P x](3Yt xVrtr tr2xTQtxNFr@xLTxJ@ GDZt wArtr'>tw<r=8tw6KrI w4 Hw2/tw-3r@tr tw+rtr$tr w)5&t$w$r-trtrw"s&$trw tr p rC -t rtxCrtrx>t r!?x t rt =[^Compiler14q[uit]/mThis Bravo command writes out the file in the selected window (say filename.mesa) andterminates Bravo. It then specifies the following sequence of (Executive) commands:>compile filename>bravo/m filenameThe command line switch "/r" (run) causes the compiler to terminate by running some otherprogram instead of returning to the Alto Executive. You may specify either a ".image" or a".run" file; if you omit the extension, ".image" is assumed. Any switches after the "r" and anyother text remaining in the command line after the command specifying this switch are copied tothe file Com.cm for inspection by the new program. This facility is primarily intended for use incommand files.Examples:>Compiler sourcefile Mesa/r sourcefileCompile sourcefile; then invoke Mesa.image to load and start sourcefile.bcd.Note that "Compiler sourcefile; Mesa sourcefile" has the same effect but isslower, because it returns to the Alto Executive before invoking Mesa. (There areoverheads of several seconds associated with both restarting the Executive and reestablishingthe Mesa environment.)>Compiler sourcefile Ftp.run/r Iris store sourcefile.bcdCompile sourcefile, then store the object file on Iris. Note that you must supply the".run" extension to invoke Ftp in this way.Fine point:You can run Bravo using the "/r" switch, but the current version (7.5) will not correctly find switches orarguments on the command line.Error MessagesThe compiler writes error and warning messages for sourcefile.mesa onsourcefile.errlog. Each pass detects certain classes of errors. Error messages are logged in(approximate) source order by each pass. Within a single pass, the compiler does its best tocomplete its analysis in spite of any errors. With the exception of "correctable" syntactic errors,detection of an error by one pass causes all following passes to be skipped. Thus you willsometimes get a new set of error messages after correcting all those reported by a previous run ofthe compiler. The compiler never writes a bindable or loadable object file if it detects any errors.The compiler also logs warning messages. These are advisory only and are intended to draw yourattention to suspicious usage. They do not abort compilation or invalidate the object file (but theyshould be checked).Here is a trivial and nonsensical program that illustrates the form of the compiler's error messages.%fp  bt^r 9t r](J YtX2 Trtr7 S<@tr Qtr$tr%tr OK NFtrL L IP Ft&Brt r t r t rA t r?d&,=]< 8t85xrt rD3tr& 0u .q@*- (=p $r 'tr #GtrM !";  X Q O )9 Y _  =( e :+ h =W<Compiler15Sample: PROGRAM = BEGIN i: INTEGER, i _ j+TRUE; END. i: INTEGER, ^ Syntax Error [46]Text deleted is: ,Text inserted is: ;j is undeclared, at Sample[52]: i _ j+TRUE;TRUE has incorrect type, at Sample[52]: i _ j+TRUE;The first message is generated by the first pass and shows how syntactic and lexical errors arereported. The arrow points to the first symbol that is necessarily invalid (or one symbol before it),and the decimal number is a character index in the source file. Of course, the compiler cannotknow what you intended, and the "real" error might have occurred quite a bit earlier. Thecompiler tries to fix these errors as best it can by local deletion and insertion of symbols. Thesesymbols are not written into the source file but are reported to help you interpret subsequentmessages. If the compiler cannot find a way to continue parsing, or if too many of these errorsaccumulate, it gives up.Fine Point:In order for the arrow to line up under the syntax error, you need to be viewing the file with a fixed pitchfont.If you are editing the program and its error log in the debugger, you can use the Position command onone of the menus of the source window to locate the errors, given the character indicies in the error log.The other error messages report "semantic" errors. Errors are located by displaying a line of sourcetext (the second line in each message) as well as the character index (a decimal number) and theenclosing procedure or program name (the identifier preceding the number). The text of the errormessage is intended to be reasonably self-explanatory. Sometimes it refers to an identifier orexpression. The compiler reconstructs these expressions from the parse tree; in later passes, thereconstruction often reflects rearrangement or constant folding so it may not exactly duplicate thesource code. As subexpressions, "?" indicates an undeclared identifier and "..." indicates eithera cutoff because of depth of nesting or an expression form the compiler cannot reconstruct from theparse tree.Compiler FailuresThe message reporting a compiler failure has the following form:FATAL COMPILER ERROR, at id[index]: (source text)Pass = n, signal = s, message = m)FfpI bt`v^ ]( [ X2 V T S< O NF J( IP DZrH Bf A _ ?d&4 ="B < sr7 :n8( 8 4u x2Px1x.Ltu x,(B )r^ 'E &O[ $_ #&< !YM #tr tr  [ c p Br@tststLs t st st s ^=ZCompiler16Such a message indicates that the compiler has noticed some internal inconsistency. The compilerwill skip the remainder of the command line if this happens. If you get such a message (orencounter other compiler problems), you should submit a change request as described in Section1.8. Be sure to preserve the relevant files and to mention the octal codes identifying the pass (n),signal (s) and message (m) in your change request.Current LimitationsThe following limits are built into the current implementation of Mesa and are enforced by thecompiler:The number of interface items declared in a single DEFINITIONS module cannot exceed 128.Neither the number of procedure bodies nor the number of signal codes defined in a singlePROGRAM module can exceed 128.The size of the frame or record required by a procedure or program cannot exceed 4096words.Procedure declarations cannot be nested more than five levels deep, counting catch phrasesas procedure levels.The compiler allocates its internal tables dynamically and tries to adjust their relative sizes toaccommodate the program being compiled. When it is unsuccessful, it reports failure with amessage of the form:Storage Overflow in Pass nUsually, the best thing to do is split your program into two or more smaller modules. If the Pass is5, you can sometimes get your program compiled by removing code from the main body (into aprocedure called by the main body), or reordering the procedures so that the largest ones come nearthe end. The reason that this works is that pass 5 reuses the parse tree space from earlier procedures to hold codegenerated for later procedures. If the main body (first processed) or one of the first procedure bodies is large, there isnot much space for the code.%fp  brD `v3( ^Fp ](r Usr [srsr Vp S_rJ QNi) w rK:IswrF$@D}A.=? <8Y :A 8 5ts 2Lr<) 0M .&= -V ug +C8 *r *O==17Appendix B: FormatterThe Formatter transforms Mesa source files into a standard format. It establishes the horizontaland vertical spacing of the program in a way which reflects its logical structure.This appendix describes the formatting rules and the operation of the formatter, including theruntime options and messages.Preparing Source FilesSee this section in Appendix A: Compiler. Since the formatter uses the scanner and parser of thecompiler in order to determine structure, only syntactically correct programs may be formatted.ExamplesThe formatter takes commands only from the command line: follow "Formatter" with a list offilenames, separated by spaces. For example, the command>Formatter ProgNamewill read the file ProgName.mesa, will copy its old contents to Formatter.scratch$, and willproduce a new, plain text, consistently formatted version of ProgName.mesa.The command>Formatter ProgName/-tkwill read the file ProgName.mesa and produce a two column landscape listing of the module inthe file ProgName.press. The program will be formatted using multiple fonts and faces.There are numerous other options described below.Command Line DescriptionThe simplest form of command is just the name of a source file to be formatted. If you supply thecommand sourcefile with no period and no extension, the formatter assumes you meansourcefile.mesa.During formatting, the display is turned off and the compiler's pass-one die is displayed in thecursor.The formatter reports the result of each command in Formatter.log with a message having oneof the following forms (each * is replaced by an appropriate number; bracketed items appear onlywhen relevant):file.mesa -- source tokens: *, time: *I fp#]qi YrF W^R T0. Rh Mp JGrpr# H.1 Cp @~r/sr >9x;s 89r s rsr 6=s r 3C x/s ,rs r8 *s r/ '1 "p r-5 s r- @sr 4, J 4s r TT  ^tsrsr =ZFormatter18Formatting was successful. The source file has been rewritten. The original can be foundin Formatter.scratch$. If several files are formatted in the same run, the original ofonly the last file will be in Formatter.scratch$.file.mesa -- aborted, * errors [and * warnings] on file.errlogFormatting was unsuccessful. The output of the formatter is undefined if syntax errors existin the input file. The original file is undisturbed.File errorThe formatter could not find the specified file.If any error or warning messages were issued, it brings this to your attention by putting "Type Key"into the cursor. The formatter will not return to the executive or run another subsystem until youacknowledge the message. (You can change this behavior by using switches, described below.)Formatting rulesGeneral RuleAs a general rule, the Formatter changes only the white space in the program. It does not insert ordelete any printing characters. On the other hand, it may insert white space where there previouslywas none. It does throw away any Bravo formatting in the input file, and only puts it into theoutput file if asked.SpacingIndentation is done by a combination of tabs and spaces in plain-text mode (assuming that a tabequals eight spaces), and by spaces alone in Bravo formatted mode.The decision as to where to break lines is made independently of the output mode: press file, plaintext, or Bravo looks.A logical unit will be placed on a single line if it fits.A simple carriage return in the input file is treated as a space. The occurrence of two consecutivecarriage returns (a blank line) is preserved in the output file. Three or more consecutive returns(two or more blank lines) result in two blank lines in the output file. Since all Bravo looks arediscarded by the scanner, paragraph leading done with looks is not preserved.For output files that contain fonts and faces (Press or Bravo) these additional rules apply:Comments are set in italics.The names of procedures are bold where they are defined.Reserved words and predeclared identifiers are in Font 1 (or 7).Font 1 should be smaller than font 0. The fonts Helvetica 10 and Helvetica 8 work well inBravo mode. For press files, the formatter choses Helvetica 10 and 8 for portrait listingsand Helvetica 8 and 6 for landscape listings.%cfp br;`vsr/^sr [tsrs rs tsX2rP Vsr! SrQ <\M :G 9  4:t 0r:% /DB +"K ){ %X: " -8 bO H M 4(v8@ M ^+0 -  p=\Formatter19In general there are no spaces before or after atoms containing only special characters. Exceptionsto this rule are as follows:A space or carriage return follows (but does not precede) a comma, semicolon, or colon.A space precedes a left square bracket when the bracket follows any of the keywordsRECORD, MACHINE CODE, PROCEDURE, RETURNS, SIGNAL, PORT, and PROGRAM.Spaces surround the left-arrow operator.The exclamation point (enabling) and equal-greater (chooses) operators are alwayssurrounded by spaces. This is also true for equal signs used in initialization and forasterisks used in place of variant record tags.Some arithmetic operators, depending on their precedence, are surrounded by spaces.The equivalent of two spaces is used for each level of indenting.StructureThe formatter determines the indenting structure of the program by the brackets that surround thebodies of compounds. The brackets include {}, (), [], BEGIN-END, DO-ENDLOOP, and FROM-ENDCASE.An attempt is made to maximize the amount of information on a page. For example, consider:Record: TYPE = RECORD [Record: TYPE = RECORDfield: Type,[field: Type];field: Type,field: Type,];In both cases, the structure is clear; it is indicated by the indenting, not the placement of thebrackets. The formatter generates the form on the left.The body of each compound, assuming it does not fit on a single line, is indented one nesting level.The placement of the brackets depends on the bracket and on its prefix and its suffix. Forexample, a loop statement has the following possible prefixes, brackets, and suffixes:PrefixesBracketsSuffixesFOR, WHILEDOOPENUNTIL, (empty)ENDLOOPENABLEThe following paragraphs contain a number of examples. They observe the following rules for theplacement of opening and closing brackets:The opening brackets {, [, FROM, and DO appear on the same line as their prefixes; BEGINstarts on a new line.If the remainder of the statement fits on a single line (with its closing bracket), it is placedthere, indented one level. Otherwise, all closing brackets except ] and } appear on lines bythemselves. If } is preceded by a semicolon, then it is also placed on a line by itself.The statement following a THEN or ELSE is indented one level, unless it fits on the same line. THENis on the same line as its matching IF and ELSE is indented the same amount as IF.(fpI  br(< `vw]Dw[5wYuru rurururururwW^(wT4J5wS<WwQ/wO9 JA F$t BrI A.+vrvrvwrurururururur ?8"w<8vuvuv2uvuk:v 3k8 3 37B 35 1yr&; /8 ,?% *K )4Vw%%$>%%2%%w$>uru$>u2uw"ur$>u2u Hr\ *w&vrvrurur uw~rw`w\4vrvrwvr$$ furur)u r$ururur D x>Y^Formatter20IF bool THENIF bool THEN statementBEGINELSE {body}bodyENDELSEIF bool THEN {BEGIN statement;body statement}ENDThe labels of a SELECT (and its terminating ENDCASE) are indented one level, and the statements asecond level, unless they fit on the same line with the label.SELECT tag FROMcase => statement;case => long statement;ENDCASEEach compound BEGIN-END, DO-ENDLOOP, or bracket pair is indented one level. When the rules forIF and SELECT call for indenting a statement, a BEGIN is not indented an extra level.These rules are not exhaustive, but are intended to give the flavor of the formatter output.Formatter SwitchesSwitches allow you to modify command input. A command has the general formfile[/s] {file2[/s] . . .}where [ ] indicates an optional part and s is a sequence of switch specifications. A switchspecification is a letter, identifying the switch, optionally preceded by a '-' or '~' to reverse its sense.The valid switches aregdon't close press file at end of input filehgenerate a press file (does not force ~t)kgenerate a two-column landscape press file (does not force ~t)ppause after formatting if there are errorsrterminate formatting and run the program contained in filetoverwrite input file with plain text formatted version (default)voverwrite input file with bravo looks using fonts 6 and 7zoverwrite input file with bravo looks using fonts 0 and 1Each switch has a default setting, The command sourcefile is equivalent tosourcefile/~g~h~k~p~rt~v~z if you use the standard defaults, i.e., the formatter onlygenerates a plain text file to replace the original source. Note that the "r" switch changes theinterpretation of file, which should name a subsystem.You can change the default setting of any switch by using a global switch. Switches given with nosourcefile establish the default setting. Unless overridden or reset, that default applies to allsubsequent commands. See, for example, the multiple program Press output example below.Some additional information about the options:%cfp burvru urvrurv`vu urv^v](u[u urvrurvYu rv X2 Vu SNFurvruLvrv JvrIPvGu DZr urururur. Burur#ur ?dM :p 7BrK4s 2Lr)wr) 0Ksrsr .+sr+*srtrsr(`sr1trsr&sr*%sr6s#jr@!sr9 sr9  %s r &sr6 ~1sr sr [ b :(1 . >ZgJFormatter21gIf a press file is being generated, it is not closed at the end of the current input file. It isexpected that another file in the command list will also be generating press file outputand a single press file will contain multiple input files. The name of the press file willbe that of the first to which press output is being generated. If the type of press file(landscape versus portrait) changes, the first will be closed and another press file will bestarted. Be careful not to generate a press file larger than will be accepted by yourprinter.v, z These switches cause the formatted version of the source file to contain Bravo looks.The "z" switch is intended to be used on a standard Mesa Programming disk that hasHelvetica 10 and Helvetica 8 as fonts 0 and 1. The "v" switch uses fonts 6 and 7 andproduces output that is more convenient for including in documentation. Indenting ishandled slightly differently for Bravo format output files. In plain text mode,indentation is done by a combination of tabs and spaces: the font is assumed to be fixedpitch and the tab is assumed to be 8 times the width of a space. The z switch causes allindentation to be done with spaces only. For v, each level of indentation is done with asingle tab.Examples:>Formatter fooFormat foo using all the default switch settings (standard or established by a globalswitch).>Formatter foo/-tkFormats foo into a two-column, landscape press file, leaving the original source unchanged.>Formatter /-tkg ProgA ProgB ProgC ProgD/-g Produces a two-column, landscape press file ProgA.press that contains listing of all fourprograms, each starting on a new page.The r (run) and p (pause) switches have identical semantics as in the compiler.Formatter FailuresThe message reporting a formatter failure has the following form:FATAL COMPILER ERROR, at id[index]: (source text)Pass = 1, signal = s, message = mSuch a message indicates that the formatter has noticed some internal inconsistency. Note that theabove message is not a typo, the message comes from a module shared with the compiler. The formatter will skipthe remainder of the command line if this happens. If you get such a message (or encounter otherformatter problems), you should submit a change request as described in Section 1.8. Be sure topreserve the relevant files and to mention the octal codes identifying the signal (s) and message (m)in your change request. If you were overwriting the input file (i.e. not saying /-t) you can findthe original contents of the file in Formatter.scratch$.(fpI bs+r)8+`v)/+^?+](#6+[(4+YB+X2tTsx+rA+S<%-+Q%0+OF+NFJ+L9+JE+IPY+G DZA s w>rsr&%w<9sw7rsrI3s,w1Ur s r"w/& ,_sr srrA ststsHt sr sts t Rr Hx Dr a \(p r Str tr  Qsr f%sr  =W3Formatter22Handling of Files by the FormatterIn the absence of fatal errors, 1. The file is copied to Formatter.scratch$,2. The original file is overwritten while parsing Formatter.scratch$,3. If no syntax errors, go on to next file, else copy Formatter.scratch$ back ontooriginal source file first.%cfp  b" ^r\TsrY2srW^sr U, Up8523Appendix C: BinderThe Mesa Binder combines modules and previously bound configurations to produce a newconfiguration. The configuration description language C/Mesa is used to describe desiredconfigurations to the Binder. It is documented principally in section 7.7 of the Mesa LanguageManual, Version 5.0; and in the Binder Change Summary. The output of the binder is a binaryconfiguration description (Bcd) which may be loaded into a running system or processed by a laterinvocation of the Binder. This appendix discusses the operation of the Binder including its switchesand error messages.File OrganizationIn order to understand the Binder options described below, it is necessary to understand somethingabout how configurations exist in files. The Bcd file produced by the Binder normally containsonly the compiled description of the configuration; it does not contain any code or symbols. Foreach module instance in the configuration, the Bcd specifies the location of the code and symbolsby file name (and version stamp), starting page, and number of pages. Thus the code and symbolsfor a configuration may be scattered over a large number of files. It is possible to put the Bcd, thecode, 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 toanother file (this is the default). Instead, they are left in the files generated by the compiler. Thissaves 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 copiedinto the same file containing the Bcd. It is possible to copy code into a file other than the Bcd file, but this isnot very useful. Symbols may be copied into the Bcd file, but they are usually written to a separatefile.It is a good idea to package the symbols of a released subsystem into a separate file, so that theywill not take up disk space when they are not in use. This also makes it easier to keep track of aconsistent set of symbols for all of the modules. Because the Binder and Loader deal only withinterfaces, symbol tables are not required for binding or loading. Of course, they are required formeaningful debugging. The Binder also has an option to compress symbol tables as they are copied. In this mode, justsignals 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 willsubstantially reduce the size of the symbols file (typically by more than 50%).Running the BinderThe 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. I fp%\qi Wr/& Up!"s"r# S/#s R"rsr!s Pzrtr 8 NT M, I-p Er=% D7(tr. BS @tr/ ?AX =^tr ;8tr 8V 663 5U5 2T 0_;& ."tru7vu -rtr" +i (-6 &sI $2- #$F !} .L K V 8O 9p rtr w ru Cwu2wu r >X0Binder24User InterfaceThe Binder reads commands from the executive's command line (through the file Com.cm). At thestart 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, themessage "Type Key" is displayed in a flashing cursor if there are errors and you have requested theBinder to pause. Typing Shift-Swat aborts the executive's current command sequence; Control-Swatinvokes 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 warningmessages from binding, say Foo.config are found on Foo.errlog.CommandsThe Binder accepts a sequence of one or more commands, each of which usually has one of thefollowing forms:inputFile/switchesoutputFile _ inputFile/switches[key1: file1, ... keym: filem] _ inputFile/switchesIn the third form the valid names for keyi are code, symbols, and bcd. (It is also possible tocontrol the association between file names and included modules or configurations; this is describedbelow.)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 stringobtained 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 withthe same name is deleted.You may also request that the code or symbols of the constituent modules be copied to an outputfile, as follows:You request copying of code by specifying the /c switch or by using the third command formwith keyword code. Code is copied to the principal output file unless you use the third formand keyi is code, in which case the code is copied to a file named filei, with defaultextension .code.You request copying of symbols by specifying the /s or /x switch or by using the thirdcommand form with keyword symbols. Symbols are copied to the fileinputRoot.symbols unless you use the third form and keyi is symbols, in which casethey are copied to a file named filei, with default extension .symbols. Compressedsymbols will be copied if the /x switch is specified.&kfp  bs ^r>wr ](f [A Y7, X2uw u2w VuQr S< .w vr Qw r w r NFs Jr6% IP Fw DZ AARuAwARuAwARuAwARuAw >r&w>&u>rwrwrwr <*: ;A 7 wr. 6Kwr 2 sr9 0)w rwr .(wr ,_"w rwr )w)Wu)rwrw)Wu)rwr (: $\ #$ B . -wrsr  wrG dwudrwr$wudr  wr 1wrwrsr wtr wr wCurwr wxurwr ;wr : =[Binder25Any warning or error messages are written on the file outputRoot.errlog, where outputRootis the string obtained by deleting any extension from the name of the principal output file. If thereare no errors or warnings, any existing error log with the same name is deleted at the end of thebind.When more than one Binder command is given on the command line, the commands must beseparated by semicolons. However, you may omit a semicolon between any two successiveidentifiers (file names or switches), or between a ] and an identifier (but not between an identifierand a /). Note that any required semicolon in an Alto Executive command must be quoted.SwitchesThe optional switches are a sequence of zero or more letters. Each letter is interpreted as aseparate switch designator, and each may optionally be preceded by - or ~ to invert the sense ofthe 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 /pswitch can be specified on a command to cause the Binder to pause if there were any errors orwarnings on that binding step.The switch /r (run) is used to specify that the Binder should run some other program rather thanreturning to the Alto Executive. Use of this switch is described in the Context Switching sectionbelow.In order to copy compressed symbols with the /x switch, SymbolCompressor.bcd must beloaded 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 globalswitch settings comes first in the sequence of commands, it must be separated from the precedingcommand by an explicit semicolon. Associating Files with Modules and ConfigurationsThe Binder lets you control the association between file names and the modules or configurationsincluded in a configuration when you call it. This is done by specifying a list of componentidentifier-file name pairs inside brackets after the input file name. Such a list can be thought of asaugmenting or replacing a DIRECTORY clause in the configuration description. For example, thecommand line>Binder.bcd MySystem[Test: UnpackedTest]will bind MySystem.config using the previously bound configuration Test that is stored on thefile UnpackedTest.bcd.*fpI  br, wrw `vr\ ^R ]( YK X2K V3wr& TwrQ Qs NFr tr7 LCwrtr  J G#wE-wkr wCwkr wAwkr5w@7wkrtrtrw>wkrwBinder.bcd MySystemRead 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/cRead MySystem.config, write MySystem.bcd. Copy all code segments intoMySystem.bcd. Leave all symbol segments as they were in the input files. This is apossible "distribution" mode.>Binder.bcd MySystem/csRead MySystem.config and write the resulting Bcd on MySystem.bcd. Copy all codesegments 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 anincorrect version of some symbol table. This is also a possible distribution mode, ifdebugging will be required.>Mesa.image SymbolCompressor.bcd Binder.bcd MySystem/cxRead MySystem.config, write MySystem.bcd. Copy all code segments intoMySystem.bcd; compress all symbol segments into MySystem.symbols.>Binder.bcd MySystem[SubSystem: ExperimentalSubSystem]Read MySystem.config, write MySystem.bcd. Read the included subconfigurationSubSystem from the file ExperimentalSubSystem.bcd.>Binder.bcd MySystem _ NewSystem.config/csRead NewSystem.config, write MySystem.bcd. Copy all code segments intoMySystem.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/cRead NewSystem.config, write MySystem.bcd. Copy all code and all symbolsegments into MySystem.bcd.>Binder.bcd SubSys MySystem/csRead SubSystem.config, write SubSys.bcd. Then read MySystem.config, writeMySystem.bcd; copy code into MySystem.bcd and symbols into MySystem.symbols.&kfp  brL `v ]w ]nu]w]nu]w]nu]w]nu]w [[u[w[u[w[u[w[u[w YLXuYLwXuYLwXuYLwXuYLwXuYLwXuYLwXuYLw WVuWw TVr%wSuTVr3 RwQuRrwr O`s LwIrwrtrw r GR DwB%rFwrGw r@~w r0> ;w9 rwrtrw r7f w r wr5$14S2p /!w7,rxtrw r*w r$wr 'w6%5rwrw r #wrwr ?w*r/wrw rw rwr u0wrwrwr 'wDr wrw r  w r w ;rwrw rwr w r w rwr L=\Binder27>Binder.bcd /-p SubSystemA SubSystemB MySystemBind SubSystemA, SubSystemB, and MySystem and do not pause even if there areerrors.>Binder.bcd SubSystemA/p SubSystemB/p MySystemBind SubSystemA, SubSystemB, and MySystem as usual; in addition, stop after bindingSubSystemA or SubSystemB if either contains errors.Context SwitchingThe command line switch /r (run) is used to specify that the Binder should run some otherprogram rather than returning to the Alto Executive. The program's name is given by the filenamebefore the /r. Both ".image" and ".run" files may be specified. If there is no explicitextension, ".image" is assumed. Any switches after the r and any other text remaining in thecommand line after the file with the /r switch will be passed to the new program.Examples:>Binder.bcd SomeConfig Mesa.image/r SomeConfigwill bind SomeConfig and then run Mesa.image as if you had typed MesaSomeConfig.>Binder.bcd SomeConfig Mesa/rd OtherConfig/-s SomeConfigwill bind SomeConfig and then run Mesa.image as if you had typed Mesa/dOtherConfig/-s SomeConfig.>Binder.bcd SomeConfig/c Ftp.run/r Iris Store SomeConfig.bcdwill bind SomeConfig copying the code and then run Ftp.run as if you had typedFtp.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 mustbe placed after the command containing the /r if the next token is not an identifier (e.g., if the token is aglobal switch for the program being run).Error MessagesIf possible, the Binder will indicate the offending source line and configuration name with eacherror. Some of the common error messages are:interface is undeclaredAn attempt is being made to import the interface (or program) interface, but interface isneither imported from a higher lever configuration nor exported by any module orconfiguration at the same level.*fpI  bw.w_rw rw rwr#w] Zw.wX2rw rw rwr*wVw rw tr Rhp Orwr 1 MrN K wrwrwr2 J# wr wr$ H|%wr* E- Aw.x?dr2 w r w r3wx= r :nw8x7r w r w r  wx6Kr 2w<x0rw rwrx.w!r +u x){Mvux(jx&vu@x%X) !Yp  r` c. xtw xr>xrxrxF xK =UBinder28id does not match the module or configuration name in the BcdThe identifier used to name a module or configuration in a configuration description mustexactly 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 orthe interface can be found, the item's name is printed. Otherwise, the item's interfacenumber is printed, and you can count (from 0) the interface items in interface or use theLister'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 beingbound. This will produce an error if you attempt to match the two versions as import andexport.interface1 (version1) is required for import, but only interface2 (version2) isavailableinterface2 is available for import (or being passed as a parameter), but the importerrequires interface1. The source line shows the importer.interface1 (version1) is being exported, but interface2 (version2) is requiredThe 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 interfacenames are the same) or an error in an assignment.interface is not imported by any modulesinterface is not exported by any modulesA configuration must tell the truth about what it IMPORTS and EXPORTS, i.e. everythingimported or exported by a configuration must actually be imported or exported by acontained module or configuration.file could not be opened to copy symbols(Warning) When copying symbols, the file containing the symbol segments for a modulecould not be opened. The copied symbols file will still be produced, but will not containsymbols 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 modulescompiled 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 andmodules compiled without it.&kfp  bxtw:_r8!]L Zxtwtxtwtxw YtxwxtwtxwVrxr7TN S<Exr Qtr! NFxtwxMyNFwxMyNFwKr2$JG4%H EQxDyEQtwxDyEQw txDyEQtwxDyEQw CA x@~yA r/?Ax>y?Ar& <x;y<twx;y<wx;y<twx;y<w 9rx90y9r&7 x7fy7r26(1 2xw 12xw.r2vrvrs -r9+i" (xtw#%r F#N "P9! w>rtr twtr w8r*tr n > '=TvBinder29Code links will be added to the previously bound configuration nameCode 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 notspecify them when it was originally bound. That is to say, LINKS: CODE should be specifiedonly on the lowest level configuration that is bound. You should certainly never add codelinks to a configuration without careful consideration; it may contain a module withmultiple instances bound differently (requiring frame links). The first message comes fromthe code copying routines (desire for code links is noted in the Bcd when a configuration isbound, but space for them is generated only when code is copied); the second message isgenerated if code is not being copied in this execution of the Binder.Errors detected, Bcd not writtenThe Binder has produced no output.Fatal Binder ErrorFatal errors are reported in a fashion similar to the Compiler; the signal and message aregiven in octal, and should be included in any change request reporting a fatal Binder error.Current LimitationsThe DIRECTORY clause in a configuration description should be used only when the name of amodule or configuration differs from the name of its file. Do not make DIRECTORY entries forinterface (DEFINITIONS) files.The output Bcd file can be renamed; the symbols file cannot (since the Bcd contains the name ofthis file in its internal tables).Multiple instantiations of nested configurations are not implemented. You can get around this bybinding 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 moduleto copy symbols.*fpI  bw>tx `vw?txx]rHx\TxW^[xU%trxTGxRhF OwxLr" IPwxFr?xE-4( A.p =rvr/sr <8> vr : v r 7B tr9tr 5" 2L4- 04 -VG +*2 * )=>J30Appendix D: SystemThe Mesa system is available as Mesa.image. Users without need of some of the runtimemachinery (BasicMesa users of earlier systems) can trim down the Mesa system via a commandline switch. Support for use of memory banks other than the first is part of the standard system(provided that the proper microcode is available on the machine running it). The standard userinterface is the command line; BCDs are loaded and started by specifying them on the commandline. It is also possible to load the Mesa Executive which serves as an interactive user interface.Command Line LoadingClient BCDs are loaded by specifying them on the command line. The general form of thecommand line is:>[Mesa[/d]] [/s] file1[/s] file2[/s] . . .The valid global switches are listed below. A '-' preceding the switch inverts its meaning./b -- convert the system to a "basic" one. Throw away the keyboard and display handlers,close Mesa.typescript./d -- go directly to the debugger (this is the only switch applicable to the image file)./k -- don't allocate the debugger bitmap in bank 1 (see Appendix E: Debugger)The valid local switches are listed below. A '-' preceding the switch inverts its meaning./d -- go to the debugger after loading this BCD but before starting it./s -- start the BCD (default if non-null control module)./l -- load the BCD with code links. The modules will only have code links if there is room for thelinks in the code and the modules specify that they want code links. See Appendix D of the Mesa LanguageManual for a discussion of code links.The default extension for file is ".bcd". The Alto Executive inserts Mesa.image (if it's on the disk) infront of files ending with the extension .bcd. Global switches are given by a slash with no preceding filename. Local switches apply only to the file to which they are attached. If Mesa runs out of thingsto load from the command line, it returns to the Alto Executive.Feedback of modules loaded and their global frame address is given on the screen and on the fileMesa.typescript unless the /b switch is invoked. fp!7\qi Wrs r Up sr> S3. R"? Pz= N't r/ IpX Fr8 D ARsusus >r0sr:sr(/9 sr5srQ2sr6pr /Dsr++srE(sr7%|sr v>#\w "sv %rsrsrvs v })svr; O /@ E 9sr sr0 =SSystem31Example:>Mesa DisplayPackage/l-s SomeConfig/dStart Mesa and load the DisplayPackage with code links but don't start it. Then loadSomeConfig and go to the debugger before starting it.RestrictionsThe default maximum number of processes is 75. The default number of modules is 384. If this istoo large, there is SmallMesa.image with 32 and 256 respectively. If this is too small, negotiatewith your support group to have a larger Mesa system made.Mesa ExecutiveAn interactive user interface can be obtained by loading the file MesaExec.bcd intoMesa.image. It provides commands for loading and starting modules, going to the debugger, andexiting to the Alto Executive. The commands are given as single letters, and are completed to fullwords by the program. The prompt is a ">". All characters typed on the screen are also writteninto the file Mesa.typescript.CommandsBelow is a listing of the commands with the characters typed by the user underlined.>New Filename: file[/l]CRLoad file into the system but don't start it. A file extension of .bcd isassumed. MesaExec then prints out the global frame address for the module (orcontrol module of a bound config). The optional /l instructs the loader to usecode links if space is provided for the configuration being loaded.>Start Global frame: numberCRStart the (or restart) module with the given global frame. Typing ESC to theprompt will insert the global frame address of the last file loaded via New.>Debug [Confirm]CRGo to the Debugger (if installed). Proceed from the Debugger to return toMesaExec.>Quit [Confirm]CRReturn to the Alto Executive.>-- any text CRInsert a comment into Mesa.typescript.)fpI  br ^s%x[rsr s rxYs r+ Tp Qr*7 Osr? NF: IPpX FrMesaFont.strike. Strike fonts can be found where altofonts are stored. (Strike fonts that include kerning are not supported.)Memory Bank ManagementWhen running on machines with more than 64K of memory, the client system supplies space to theDebugger for the Debugger's bitmap (unless all but one bank has been disabled; see below); theclient can disable this option by using the /k switch.It is also possible for the Debugger to be installed with more than one bank of memory availablefor code swapping; this is done by reducing the amount of memory available to the client using theRunMesa bank switches or the Alto Executive MesaBanks.~ command (in Executive version 11 orlater).MesaBanks.~This command establishes the default memory allocation available to client programs.Arguments can be in two forms: a sixteen bit octal mask (followed by an optional /bswitch) indicating the available banks; a one in bit position n of the mask (counting fromthe left) indicates that bank n is available. Form two is a series of decimal bank numberseach followed by the /x switch; each bank mentioned is excluded from use by the client.Note that a request to exclude bank zero will be ignored. If no argument is present, thecommand will display the current value of the bank mask.The MesaBanks.~ command establishes the available memory for each .image or .bcdprogram invoked directly by the Alto Executive. The default may be overridden byexplicitly using RunMesa to invoke the program and optionally specifying bank switches onits command line, before the .image file name. The bank switches have the same formatas the arguments to MesaBanks.~ (except that the /b switch is required in the case of abitmask). In the absense of any bank switches, RunMesa always assumes that all banks areavailable to the client.I fp$\qi Wr+6 UpK S,1 R" M,pX Ir-st HYY Fut:rtvrt E-vt%r$sr CN @7w xCsr,xs rsr x #sr"x M =]ADebugger34Using these facilities, it is possible to set up the defaults so that the Debugger has extra banks ofmemory at the expense of the client program. For example, on a three bank Alto, the followingcommands might be used to set the default and then install the Debugger:MesaBanks.~ 2/xRunMesa.run 1/x XDebug.imageUnder this arrangement, the client would use banks zero and one, and the Debugger would usebanks zero and two (because bank zero is swapped onto Swatee, it can be used by both).Actually, because the client (by default) is also allocating space for the Debugger's display bitmap,the client actually has only one-and-one-half banks, and the Debugger has two-and-one-half; thiscan be changed by running the client with the /k switch, resulting in two banks available to each.Note that the MesaBanks.~ command affects all Mesa programs invoked by the Alto Executive,including the Compiler and Binder. So the above example would run the Compiler in only twobanks, not three; this can be changed by saying RunMesa Compiler on the command line, which,because there are no bank switches specified, defaults to all banks available (not really necessary inthis case, since the Compiler runs almost as well in two banks as in three). On the next newsession, the Debugger is smart enough to notice that the Compiler (or whoever) has smashed what itthought was in bank two. (It is also smart enough not to use any memory that the client owns, sothat the 1/x switch on the command line above is actually unnecessary.)Since there are a lot of options here, some "standard" examples of client and Debuggerconfigurations might be helpful:Two Banks: Normally, do nothing; client and Debugger will each have one-and-one-halfbanks. For small clients and better Debugger performance, use RunMesa 1/xMesa.image Client.bcd, which will give the client one bank and the Debugger two.(If you were to use MesaBanks.~ 1/x in this case, the Compiler would also be restrictedto one bank).Three Banks: As in the three bank example above.Four Banks: Use MesaBanks.~ 3/x to give the client and the Debugger two-and-one-halfbanks each and the Compiler three; use MesaBanks.~ 2/x 3/x and Client/k toincrease the Debugger's allocation to three banks and restrict the client to two. Obviously,this can be adjusted based on the size of the client and the desired performance of theDebugger.FilesThe debugger itself is contained in the file XDebug.image. There are several other files that areused by the debugger and should not be edited or deleted from your disk. These are the swappingfiles used by the debugger: Swatee (to hold the user's core image), MesaDebugger (to hold thedebugger's core image), and Debug.log (used as a record of your debugging session). If you don'twant your swatee to be used, create the file MesaCore and the debugger will use that instead.Signals and errorsSee the Mesa Debugger Documentation for details on the common signal and error messages youmight receive and suggestions for recovery.%fp  brE `vB ^H\TsZ X2r7$ V6sr TF S<8( Q.sr* NF s rwr- L0+ J0sr IPc G@ FZ DZ2/ Bsr; ?d6 =;Aw r49;<"s 7r- 6Ksr4 2)w r$/w rsr5.'srsr,_ Q*<) $p rs r) %w !r }sr s r sr%t /-st( 9pX rwr8 C+ >XGDebugger35Sample programThe configuration we are going to use as an example is taken from the Mesa Language Manual(Chapter 7). The following files should be retrieved from Mesa>Doc: LexiconClient.mesa,Lexicon.mesa, LexiconDefs.mesa, LexiconClient.bcd, Lexicon.bcd,LexiconDefs.bcd, Lex.config, Lex.bcd, and Lex.ts (a sample typescript of the debugging sessionthat follows).The sample configuration Lex consists of two modules, Lexicon and LexiconClient. After themodules have been compiled and the configuration has been successfully bound, you are ready toload and debug the program.Entering the debuggerLet us assume that the configuration has been loaded and started (by typing Lex to the AltoExecutive), and you have interrupted the program and entered the debugger for the first time (byholding down Control-Swat after the program has started). You get a herald that indicateswhich version of the debugger you are using and when it was built, followed by the current dateand time, a message indicating why you entered the debugger (in this case, interrupting theprogram), and a prompt for the first command:Alto/Mesa Debugger 6.0m of 12-Sep-80 23:2112-Sep-80 23:41*** interrupt ***>Setting the contextIn order to get to a context from which you can set breakpoints in one of the modules in Lex, let'sfirst check to see which configurations have been loaded by saying:>List Configurations [confirm]which responds with:LexMesa NucleusIf we check the context at this point, you can see that the current module is NubControl in theMesa configuration,>CUrrent contextModule: DebugNub, G: 172764B, L: 166160B, PSB: 3700B Configuration: Mesa.We need to set the current configuration to be Lex,>SEt Root configuration: Lexand find out which modules are in this configuration,) fpI  bX ^r(w ](r+srsr [s r*sr+srs r Ysrs rsrsrt- X2 r Txrxrx r S<[ Q LpX IPr@ sr G` F s rA DZ;$ B&5 A -x=s*x<x:nx7 2)pX .r+.xr -3Cx)s &rx#Gsx!x r&(x r xrxsx 4xe r/xrx s yr5  2=]Debugger36>Display Configuration LexLexicon, G: 150404B~LexiconClient, G: 150424BNotice the ~ indicating that Lexicon hasn't been started yet. Now we can set the context to beLexicon, so that we can set some breakpoints>SEt Module context: LexiconSetting breakpoints by selectionsLet's load the source text for Lexicon into a window so we can set breakpoints by pointing at thetext. This may be done in one of two ways: either display the stack and ask to see the source (thisloads and positions the source file for the current module into the source window of the debugger),>Display StackLexicon, G: 150404B~ >s Cross jumped!--Lexicon.mesa >qor load the file into a source window by 1) selecting the file name Lexicon (the extension defaults to.mesa), 2) moving into a source window (there is always at least one around), and 3) choosing the Loadcommand from the menu. Note the message warning that Lexicon was compiled with the crossjumping switch turned on. Additional source windows can be created, destroyed, and movedaround as needed, using the appropriate menu commands.Now move into the window containing the source file, and put this window on top. This can bedone by either clicking the red mouse button in the left or right sections of the window header, orby selecting the window menu command Top.Suppose we want to set a breakpoint on the exit of the procedure NewNode. Scroll the windowuntil this procedure is visible, then select the word RETURN inside this procedure. Hold down themenu button (yellow button) and choose the SetBreak command. This sets a breakpoint on theexit of the procedure (similarly, selecting the word PROCEDURE or PROC sets a breakpoint on theentry to the procedure).Suppose you want to set a breakpoint in the end of one of the conditional IF-THEN-ELSE statementsin the procedure InsertString. This can be done by selecting any place in the statement ELSEn.llink _ NewNode[];. Confirmation of where the breakpoint has been set is given by themoving the selection to the first character of the statement: ELSE <>n.llink _ NewNode[]; (Notethat in all cases, the closest enclosing statement is the place at which the breakpoint is actually set).Setting breakpoints by type-inYou may also set entry and exit breakpoints in the program using keyboard commands. For anybreakpoint, you may specify a condition that must be satisfied in order for the breakpoint to betaken. If, for instance, you want to set a breakpoint on the entry to the procedure FindString,and enter the debugger only if root is not NIL, say:%fp bs`v^ [r sr9 Yxr%S<s NFpX! Jrxr IPN G30DZs B&A ?d <r%sxrt :nstrt%rs 8rI 7D 5x6 2)P 0X .%sr +2xr )6yr& (=&sr( & *yryr $ != y r x r;y QxrB  4yxr c  pX rI Q o=x r xryr  =Z+Debugger37>Break Entry procedure: FindString Breakpoint #3.>ATtach Condition #: 3, condition: root # NIL.Inserting commentsSaving some comments along with the commands is a good idea, so that it is easier to rememberwhat happened when looking back at the typescript file. For instance you might now say,>--This breakpoint was set to skip checking for a lexicon if we>--know the tree is empty.ProceedingIt is now time to proceed and run the program. This is done by executing the following command:>Proceed [confirm].If we try to add the lexeme "xxxxx" to the tree, we will then reach our breakpoints.Examine and change the stateYou next enter the debugger at the first breakpoint with the herald:>Break #1 at exit from NewNode, L: 165424B, PC: 274B (in Lexicon,G: 150404B)to indicate where you are. At this point you might display the stack and look at the variables,>Display StackNewNode, L: 165424B, PC: 274B (in Lexicon, G: 150404B) >v n = 147374B^ >qor look at the several levels of the stack,>Display StackNewNode, L: 165424B, PC: 274B (in Lexicon, G: 150404B) >nInsertString, L: 165434B, PC: 162B (in Lexicon, G: 150404B) >nAddString, L: 165444B, PC: 137B (in Lexicon, G: 150404B) >nCommandProc, L: 170420B, PC: 470B (in LexiconClient, G: 150424B)>nLexiconClient, L: 165464B, PC: 257B (in LexiconClient, G: 150424B)>nNo symbols for L: 172614B, PC: 702B (in MesaNub, G: 172670B) >qor ask to see what the node n (in NewNode) looks like (invoke the interpreter by typing SP),> n^[llink:NIL, rlink:NIL, string:(5,5)"xxxxx"].) fpI xbrs0x`v. [pX X2r#: VSxS n.llink _ n; n.rlink _ n; n; n^which responds with,147374B^[llink:147374B^, rlink:147374B^, string:(5,5)"xxxxx"].If at this point we want to see the value of the variable root in the module LexiconClient (avariable in the current configuration but not in the current module), this may be done by saying,>Find variable: rootwhich responds with the value of root, and where it was found:NIL (in Lexicon, G: 150404B).More breakpoint commandsThe following command lists all of the breakpoints that have been set:>LIst Breaks [Confirm]1 -- Break at exit from NewNode (in Lexicon, G: 150404B).2 -- Break in InsertString (in Lexicon, G: 150404B). Cross jumped! ELSE <>n.llink _ NewNode[];3 -- Break at entry to FindString (in Lexicon, G: 150404B). Condition:root # NIL;If you decide that you are no longer interested in any of these breakpoints you can>Clear All Breaks [confirm]which removes all breakpoints and restores the instructions.Look at the user worldIf you are interested in seeing the state of the user display, you can look at the user world by saying >Userscreen [confirm].When you want to return to the debugger, hit either the Swat key or FR5; this brings you backinto the debugger, ready to execute more commands.%fp  br@xr xr `v xr](s! YrVsT6 Qrxrx r O01Ls IPr!xrFs A pX =rF:ns89745x 342)%"0 -3rS)s &r< !pX Qr52s r0srsr  2 ~ =RFDebugger39Setting tracepointsSuppose next you want to set a trace on the entry to the procedure LexicalCompare so that youcan simply see the two strings being compared and go on. You may do so by saying,>Trace Entry procedure: LexicalCompare Breakpoint #4.Now we should proceed>Proceed [confirm]and try to add a new lexeme, say "yyy".When the tracepoint is reached, you get the herald indicating why you entered the debugger, whereyou are, and a dump of the input parameters of the procedure:Trace #4 at entry to LexicalCompare, L: 165750B, PC: 276B (in Lexicon,G: 150404B)>Display StackLexicalCompare, L: 165750B, PC: 276B (in Lexicon, G: 150404B) >P s1 = (3,80)"yyy" s2 = (5,5)"xxxxx" >leaving you in Display Stack. Type 'q' to terminate the Display Stack command, and thencontinue executing your program >Proceed [confirm].This represents a brief introduction to the use of most of the debugger's commands that you willcommonly need. See the Mesa Debugger Documentation for further details; the best teachers areexperienced Mesa programmers and lots of practice!!! ) fpI  bX ^rCx r ](RxYs4r VxSLister 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 commaor 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 thecommand name if a unique command exists. The Lister will prompt for arguments if the commandname is terminated with CR. Typing ? in keyboard mode will produce a list of available commandsand 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 singlefile, the parameter is the name of the file; if no extension is given, ".bcd" is assumed. Somecommands 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 primarilyinternally by the Mesa implementors. Quote marks are shown on command parameters that are ofstring type; it is usually not necessary to type them to the Lister.Commands Useful to General Mesa UsersCompressUsing["Filename"]Filename contains a list of compiler output Bcds. The using lists of the directorystatement are generated for each module in the list; they are then sorted to show for eachinterface, and for each item in the interface, which modules reference that item. The samecaveat about implicitly included symbols applies as for the Using command. The output iswritten to file.ul. fp! \qi WrG VDsr:s r T s r # Rs rs r/ Mp JrI I t uv t wr0 Gb"; EW D!@t5 =vC : h 907 6rFwr 4^D 2wr* 1 - &wr) ,W *r< tr (7t r '#xr #` "-V D s% tSr$xrtr*0F] 0tr tr o>XUtilities41Debug[]Invokes the Debugger.Image["Filename"]Makes an image file. If no extension is specified, .image is assumed. ImageMaker must be loaded beforeusing this command.Implementors["Filename"]Filename contains a list of compiler output Bcds (interfaces and program modules). Thiscommand creates a file, Filename.iml, showing for each interface exported by anyprogram in the list, where the various interface items are implemented. If the list alsoincludes the Bcd for a particular interface, the interface items not implemented by anyprogram are also shown. In order to run this command, one needs not only the Bcds inthe list, but also the Bcds for the interfaces exported by the programs therein. MissingBcds 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 theinterface items and numbers (on Filename.il). These numbers are the ones reported by theBinder for unbindable items.Load["Filename"]NEWs and STARTs the module Filename. An escape hatch allowing other programs to run in theLister 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 allimports 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 theexported interfaces and enumerates interface items in those interfaces that are not exportedby this module or configuration.Using["Filename"]Filename is a compiler output Bcd. This command generates a directory statement withits included identifier lists (on Filename.ul). Since there is not enough information in the Bcdto tell which symbols were implicitly included, the USING clauses may contain a superset of those itemsactually needed.)fpI  btx_r \txZfrv4w vxX UtxSr xr)xQt r xP4?xN xrCxL(&xrxK>xr?xIxr4 FHtxCrxrw r+xB%t rvx@~ =/tx:wrwr trv&x9  5tx3Cr 0tx.r9wr x,_v0 )tx'#rxrx%|t r<x#? !txrxr#x":xI tx rxr2xe"t rvxxv 'wv.x] B 9V&Utilities42UsingList["Filename"]Filename contains a list of compiler output Bcds. This command creates a ".ul" filefor each file named in the list.Version["Filename"]Filename is a compiler or binder output Bcd, or an IMAGE file. This command shows, onMesa.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 twoboolean 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 otherprocedures it calls. It does this by scanning the code for the modules. It does an imperfectjob in that it cannot tell who is being called via a procedure variable. However, if there areany 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 nestedwithin 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 toprocedure variables.Commands Useful to WizardsBcd["Filename"]Filename is a compiler or binder output Bcd. This command produces a listing of theinternal 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 itemsare included.BcdSegment["Filename",Base,Pages,Links]The most general form of the Bcd command allowing you to specify the location of theBcd 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 eachstatement 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 ofoperations will be the same). If one is making listings for low level octal debugging, be sure to make newlistings of code for packaged modules using the CodeInConfig command.%fp  bt_r$xrtr] [:tXrxrwrWtr= TVt7Qr$xrP4t r0N@ KtIPrxr'Gt r"$FQ DZJB5&A I?d IncludeChecker [outputfile][/switches] [filename1 filename2 ...])fpI  btx_r'(xrtrx]Btrx\T3 YtxVr tr'xT3yv6 Qt%xNr'(xrtrxL5tr xK>; GtxEtr)*xr2xCt r @~t$x>rtr'x<\$tr 9 A 7f$ 2ppX /!rB xr -zV +xrxr!xr *+[ (?tr & #DC ?Txrxr=T0xrCIT #xr&T PT0&TSxr#xr ? ]&xtA V =ZDBUtilities44whereoutputfile is the name of the file written. If no extension or switches are given, .listis 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 .bcdfiles to be checked. It is not necessary to give an extension, since the IncludeChecker willlook 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:>IncludeCheckerIt 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 ininteractive 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 thislisting./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 willattempt 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). Inaddition, list as comments any Bcds and source files not on the disk which areneeded to do the compilation./mUse multiple output files (-m is default). The compilation order is written onsource.outputfile. The includes and included by relations are written ontooutputfile.includes and outputfile.includedBy, respectively. Thisswitch 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. Thatis, a .mesa but no .bcd./pPlace a /p after every change of inclusion depth (see below) in the compilationcommand (-p is default). This will cause the Compiler to pause if errors arefound while compiling that or any previous module. /sSame as /c-i-o. This is used when only a consistent compilation command isneeded.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 offiles that you give should include, for example, any important system files upon which your files aredependent. %fp  br^t r7t](r4t r Ytr5tX2r?V trtr@Ttrtr Q2NFt JrJ IPMtr tr GU DZ!trtr+A tr=tr?d<tr88tr? tr7@ 3tr#trtr2) xr,0-3trtr2+tr:)trtr(=7$tr,'#Gtrtrtrtr+Qtr+4[trtr2  et r prsLr o [  h >ZIUtilities45It is also a good idea to inspect the consistent compilation command before executing it, since theIncludeChecker'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 thedisplay; in addition, it adds that file to the compilation command if /c is in effect. A warning isalso displayed if a Bcd is found that was created by an obsolete version of the Compiler; its sourcefile is also added to the compilation command. The IncludeChecker lists the file names of the compilation order and the consistent compilationcommand by inclusion depth, with the files that are the most deeply included first. Within thatconstraint, definitions modules are printed before program modules. In general, then, the "lowestlevel" 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 LexiconClientwill produce a consistent compilation command in Line.cm and the output shown below onIC.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 stringdefsIOPkg (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 windowdefsLexicon (28-May-80 9:30:29 60#203#) (compilation source: 28-Apr-8017: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 systemdefsLexiconClient (28-May-80 10:02:50 60#203#) (compilation source: 28-May-8010: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)fpI  brD `vQ ](xrB ['tr YxrM X2/ T!> S<*6 QD O;$ L;xIPtC Frtr DZtr A t' ?d# = <) :n 8 5x; 3 2) 0 -36 +% )$ (= & $ #G ( Q % $ [*   1  o% $ * y  2>]Utilities46LexiconDefs (14-May-80 10:48:49 60#205#) (compilation source: 18-Apr-7919:19:11) (source on disk: [same]) includes nothingIODefs is included by IOPkg Lexicon LexiconClientIOPkg is included by nothingLexicon is included by nothingLexiconClient is included by nothingLexiconDefs is included by Lexicon LexiconClientSignalListerSignalLister 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 onthe stack when there are no symbols on the disk or as an aid to repackaging code. To produce asignal 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, ifFoo.image was made by loading Foo.bcd on top of Mesa.image (along withImageMaker.bcd, of course), a complete signal listing for Foo.image will require thatMesa.symbols and all the symbols for Foo.bcd be on the disk. If Mesa.symbols is notpresent, only those modules from Foo.bcd will have their signals listed.Statistics PackageThis package gathers statistics about Mesa source and object files and writes them onMesa.typescript. It may be invoked either interactively or from the command line. To invokeit 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 thecommand line, Statistics enters the interactive mode. Type ? to get full documentation. Thefollowing switches are used:%fp  `vt ( ^ ](- X2 V T Q NF J$ G F% A p =r?.@) <t r; :nt r$+ 8? 7tr3t 0r-3trtrtr)trtr t r &V $trtr t r #Gt r(tr !t rtrt r !tr pX r95:  trE eCt% rtr' #: y R 2=]Utilities47/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/cAlto/Mesa Statistics Package 6.0Statistics 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 13DisplayControl 7694 255 912 6 1 35 2 18StreamIO 6376 216 924 7 1 5 2 11SystemDisplay 15524 492 1988 7 2 8 4 22 ------ ----- ------ ------ --- ------ ----- ----TOTAL: 35290 1138 4400 24 5 54 10 64Sometimes the program puts an asterisk after the number of code pages for a module. This means thatthe number of code bytes is very close to a page boundary, and the number of links is such that bindingwith code links will cause the code to "spill over" into another page.BcdSignalsBcdSignals is a program which will produce a signal listing from a .bcd file; it works much likethe 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 inthis Bcd. This will normally be the first free global frame index in thesystem into which the Bcd will be loaded./xtakes octalNumber to be the StartPilot loadmap form of a global frameindex. This is the number in brackets beside the module name in theloadmap. Use 200B times the octal number used with the /n switch./plists the name, byte PC, and length of each procedure in Foo onFoo.procs./slist the signals of Foo on Foo.signals (default).)fpI xbtrx_tr%x](trxZtrxX2trxUtrxSH !S =+? :! 90A 76 4m 3gL# 2[ .B) -Z +ie *S ( #p tU! HG@IH-! P Y  V(9  3>] RunMesa49header format (.bcd, .code, and .symbols files are compatible) and RunMesa will give you thecreation and creator of the file, but will refuse to run it.The following local switches are recognized:/BThe argument is a 16-bit octal number taken as a bitmask of which banks of memory the software isallowed to use. It will be ANDed with the actual memory configuration bitmask. The high orderbit is bank 0; the low order bit is bank 15D./CSame as /I (below) except the remainder of the command line is ignored./IThe argument is the name of the image file to be executed. A file name with no switches has thesame effect. Default name: Mesa; default extension: image./M[n]The argument is the name of a microcode file to be loaded into the RAM in packed ram format (cf.PackMu). This could be a different version of the Alto/Mesa microcode, or if you have Alto/Mesamicrocode in ROM, you can have RunMesa load any other microcode for you. The M may befollowed by a number (0-2) indicating which bank of RAM to load./XThe argument is a list of decimal memory bank numbers (separated by commas) which are to beexcluded from use by the software. Equivalent to supplying a bit mask to /B with zeros in theindicated bits.RunMesa rewrites Com.cm (if necessary) to remove itself and all other arguments and place the image file name first.An image file cannot tell whether it was invoked from the Executive or as an argument to RunMesa.FrontFront.run is the part of RunMesa.run that loads the microcode and Mesa code. Front can be added to the front of animage file to turn it into a self-contained run file (e.g. Laurel.run). None of the options listed above are available withFront. Here are the steps to make a self-contained file:1.Get Front.run from the same place you get RunMesa.run.2. Run it by saying "Front" to the Executive. Make sure that the microcode version it prints out is the sameas the one you usually get from RunMesa. This operation also insures that the image file will start at a pageboundary in the file.3.Concatenate Front.run and your image file by sayingCopy Foo.run _ Front.run Foo.imageto the Executive.Make sure you have enough disk space when you start. Front adds about 35 pages to an image file.Parameters passed via CallSubsysParameters can be passed to RunMesa and Front in the userParams parameter to the Alto OS CallSubsys operation (seeAlto Operating System Reference Manual). Both RunMesa and Front will accept a memory bank restriction bitmask (asin the local /B switch) in a parameter of type privateType+10D. RunMesa will also accept a parameter of typeopenStreams with a stream on the desired image file already open (all command line processing is bypassed in thiscase). The Alto Executive uses this feature to speedup the entry into Mesa programs.)fpI kbAt(4k`< ],xZkakYoDkX-xUkGxQkGkP;xMk>"kL5WkJ?kIs@xFkk[kE ^kC @d ?a :p 7tM& 6(| 49x1x6x.x^x-Vhx+x(3n'F"x% " a 7pX  tIu t )I J&ut/ u tf U e>S HELVETICA TIMESROMAN LOGO HELVETICA  HELVETICA  TIMESROMAN TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMANGACHA  TIMESROMAN  TIMESROMAN  TIMESROMAN GACHA  TIMESROMAN TIMESROMAN  HELVETICA HELVETICA TIMESROMAN  TIMESROMAN  TIMESROMAN GACHA  HELVETICA TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN GACHA  TIMESROMAN TIMESROMAN HELVETICA HELVETICA  TIMESROMAN  TIMESROMAN  TIMESROMAN GACHA  TIMESROMAN  HELVETICA HELVETICA  HELVETICA  TIMESROMAN TIMESROMAN  TIMESROMAN  TIMESROMAN  TIMESROMAN  HELVETICA  TIMESROMAN HELVETICAGACHA  HELVETICA   HELVETICA TIMESROMAN  TIMESROMAN  TIMESROMAN GACHA  TIMESROMAN  TIMESROMAN  TIMESROMAN TIMESROMAN HELVETICA GACHA   HELVETICA   TIMESROMAN   TIMESROMAN   TIMESROMAN  GACHA   TIMESROMAN  TIMESROMAN  HELVETICA  TIMESROMAN   HELVETICA   HELVETICA  TIMESROMAN   TIMESROMAN   TIMESROMAN   TIMESROMAN  GACHA   HELVETICA  TIMESROMAN  HELVETICA  HELVETICA   TIMESROMAN  TIMESROMAN   TIMESROMAN  GACHA   TIMESROMAN   TIMESROMAN  HELVETICAG {  "*&W*'.g28@NH QY^ek=p*u {~s6s>Gi %*08@J"PP*J":PPB"*iA":B: ;Z: ;Zj/H8F& Q muhb.pressSweet28-Oct-80 15:22:57 PSTF