Executive User's Guide Executive, the Alto command processing subsystem, is the intermediary by which Alto users generally invoke other subsystems and ask simple questions about the state of the Alto file system. It is just the same as any other subsystem, except that its name is known by the Alto Operating System, and it is invoked by the Operating System whenever the Bcpl operator "finish" or equivalent is executed. This document describes version 11 of Executive. 1. What It Does The operation of Executive proceeds thus: 1. It reads any leftover unexecuted commands from a file called Rem.Cm into a main memory command queue. 2. It begins building up a command line (terminated by a CR). If the command queue empties before the command line is terminated, additional characters are read from the keyboard until a CR is read. Editing is done during this phase. If the command line has been empty for about twenty minutes, the user is assumed to be occupied elsewhere, and the diagnostic program Dmt.Boot is invoked either from the disk (if it can be found) or from the Ethernet. 3. The edited command is placed at the front of the command queue and the command queue is analyzed for *-, #-, and @-substitutions. If something of the form @filename@ is discovered in the first line in the command queue, it is replaced by the contents of the named file and analysis continues with the first character of the replacement. Executive makes no attempt to detect or recover from infinitely recursive replacements. If the characters * or # are encountered in a filename in the first line, the file directory is used to replicate that filename with appropriate substitutions. This step results in a completely edited command line. 4. The first atom (contiguous sequence of legal file name characters) in the command line is analyzed to see whether it is the name of a subsystem in the file directory or the name of a command internal to Executive or neither. If neither, then Executive attempts to extend the atom into the name of a subsystem or Executive command. (The subsystem lookup algortithm is described below.) Failing in this, it complains and resets itself. Otherwise the line is written on the file Com.Cm. Then if the first atom was or could be extended into a subsystem name, the rest of the command queue is written on Rem.Cm, and the subsystem is invoked with a CallSubSys Operating System call. If it is an internal Executive command, the appropriate subroutine is called. Executive passes the switches found on the subsystem name in the user parameters vector of CallSubSys. See the documentation of CallSubSys for more details. ------------ Copyright Xerox Corporation 1980 Executive User's Guide June 26, 1980 2 In parallel with these steps, Executive does a few housekeeping chores: a. It reads the entire file directory into memory, merges in the names of user-callable routines internal to Executive, and sorts the resulting list alphabetically. b. Having nothing else to do, it puts a line containing a continuously- updating digital clock and the number of free disk pages on the user's screen, and flashes a vertical bar cursor where the next typed character will go. A number of characters have special meaning during the editing step (2): Null: Ignored Carriage Return: Terminates the line, beginning step 3. Control-A: Backspace: Removes the last character from the line queue. Control-W: Removes the last item which looks like a file name from the line queue. UpArrow: Single quote: Causes itself and the next character both to be appended to the line queue, regardless of what the next character is. Control-U: Signals that at the conclusion of step 2 the line queue is to be written on the file Line.Cm and its contents replaced by the text "Bravo/n Line.Cm". If one has the proper Bravo and User.Cm, this will invoke Bravo on the command line. (This is also an easy way to build small command files. Just type the desired command followed by Control-U and CR. Then copy or rename Line.Cm.) Control-X: Performs step 3 on the line queue as it is, returns to step 2. In other words, it eXpands @, *, and #. Control-C: Delete: Empties out the line queue, starts over again. Escape: Interprets the last atom in the line queue as the prefix of a file name; continues that file name until it is complete or ambiguous. Flashes the screen if it is ambiguous. ?: Interprets the last atom of the line queue as the prefix of a file name; types out all file names which begin that way. Tab: Executive User's Guide June 26, 1980 3 Same as "?" except it deletes the atom from the line queue after typing the file names. This would be what one would normally use to interrogate the directory. * and # work as expected. LineFeed: If the file Line.Cm exists, its contents are appended to the line queue. Blank1: Blank2: Blank3: These are the three blank keys on the right side of the Microswitch keyboard, numbered from top to bottom. These keys behave like LineFeed except the files used are Key1.cm, Key2.cm and Key3.cm. These are called "macro keys" and make it convenient to have several frequently used command sequences available as single keystrokes. (The Control-U feature is a convenient way to generate the text for these files.) In step 3, several characters have special meaning: Semicolon: Carriage Return: Terminate the line; control goes to step 4. Up Arrow: If followed by a carriage return, do nothing. If followed by an up arrow, put one up arrow in the line queue. If followed by any other character, put both characters in the line queue (Ugh!). /: If followed by another "/", this begins a comment, so scan ahead until finding a carriage return or semicolon. If not, put the "/" in the line queue. @: Scan ahead until finding another @ (the second @ may be omitted if it comes at the end of the command). The atom in between is a file name. Replace the @atom@ by the contents of the named file. If the file doesn't exist exactly as specified, try extending the specification and forcing a .Cm suffix. *: #: Expand the atom using these characters by making a search through the file directory. * matches any sequence of file name characters. # matches any single character except a period. File names are defined to end with an infinite number of periods. The atom is replaced by all file names matching its pattern. Switches on the atom, if any, are replicated. There is one special character recognized during step 4. Control-C: Aborts the command and starts over again. Control-C is effective up until the time that Executive gives up control to the subsystem being invoked. If you realize a mistake in your Executive User's Guide June 26, 1980 4 command after typing CR, quickly typing Control-C will abort it. (When Executive's header line disappears, it is too late.) In step 4, one switch is taken to have special meaning on the subsystem name only. The switch /! will set the pause parameter in the call to CallSubSys to true causing you to enter Swat after your program is loaded, but before its first instruction is executed. This switch, if detected, is removed from the command line before Com.Cm is created. This feature is extremely useful if your program is hitting a bug before its first user interaction. 2. Executive Commands The Executive contains a number of subroutines which can be invoked from the command line. The commands corresponding to these subroutines can be identified by the extension character "~", which is illegal in a file name. Executive commands include the following: Type.~ FileName ... Display the contents of the named file(s) on the screen. After each page, it asks whether you want to see more of the current file. A Ctrl-C at this point terminates the entire Type command. You can type any files, even binary ones, but typing some files will give you more useful information than typing others. Delete.~ FileName ... Removes the named files from the directory and frees their disk space. Use this command very carefully. Its effect cannot be undone. Typing Ctrl-C will abort the command cleanly between deletions. Copy.~ DestFileName _ SourceFileName ... Copies a file. If there are several SourceFileNames then the copy will contain the concatenation of the information in the source files, in the order listed. In accordance with the Alto File Date Standard, copying a file preserves the creation date of the file; concatenating files generates a new creation date. Rename.~ OldFileName NewFileName (or NewFileName _ OldFileName) Changes the name of OldFileName. NewFileName must not already exist unless OldFileName and NewFileName are the same (use this feature to change the capitalization of a file name). BootFrom.~ FileName [...Sys.Boot] Initiates a software-simulated bootstrap sequence on the file named by FileName. Most probably the FileName should have the .Boot extension. Like the OS system call BootFrom (which it uses) this command does not actually do a hardware bootstrap operation, so it does not re-initialize any Alto hardware or microcode tasks. If you don't know what this implies, don't worry about it. Quit.~ Has the effect of BootFrom Dmt.Boot. This commences the running of the diagnostic program, which doesn't use the Executive User's Guide June 26, 1980 5 Operating System at all. This is done automatically after a machine has been idle in Executive for about 20 minutes. If Dmt.Boot is not on your disk or you turn the disk off, Dmt will be loaded from the Ethernet. Login.~ Places your user name and password in the system area of main memory for use by programs which interact with access- controlled resources (like timesharing or file systems, for example). SetTime.~ Sets the Alto's internal time-of-day clock. The time is obtained from the Ethernet if possible. Failing that you will be asked to supply the time (and possibly time zone) manually in the form 12-jan-78 14:45. Use SetTime/m to bypass the Ethernet and set time manually. Use /z to force setting of time zone in manual mode. (When Executive is started it examines the time-of-day clock. If the value is not reasonable Executive attempts to obtain the time from the Ethernet before proceeding. If the time cannot be obtained, the time-of-day displayed at the top of the screen will be "Date and Time Unknown" indicating that you should invoke the SetTime.~ command manually.) As a side effect of obtaining the time from the Ethernet, Executive learns the network number of the local Ethernet and displays it along with the Alto's host address in one of the header lines at the top of the screen. A network number of 0 means "I don't know.". Dump.~ DumpFileName SourceFileName ... Writes DumpFile as a structured file (in Dump format) containing the names and data of all the SourceFiles. This is a convenient way of packaging up a collection of related files into a single composite file that can later be decomposed into its constituent parts. See Appendix A for details of Dump format. The primary virtue of this particular format is that it is intended to be compatible with the Dump format of the Data General Nova DOS operating system, and it is compatible with the Tenex subsystem DUMP-LOAD.SAV and the Dump and Load commands in Ftp. Load.~ DumpFileName This reads through a Dump format file and creates individual files corresponding to its constituent parts. The /V switch causes Load to ask you about each constituent part, whether to copy it from the DumpFile to an individual file or not. Acceptable responses are Y, N, and C. The latter indicates that you would like it to be copied, but into a file with a different name than that indicated. You are then asked to supply the name you prefer. Release.~ Tells you the release number and date of Executive. The release number is also shown in the first Executive herald line, just after the slash following "Xerox Alto Executive." StandardRam.~ For any Trap except the Swat Trap (#774xx) the Alto microcode sends control of the emulator task to the microcode Ram for Executive User's Guide June 26, 1980 6 interpretation. StandardRam initializes the microcode Ram to send control of the emulator task back to the Rom Trap-handling microcode. If you don't initialize the microcode Ram before executing a program which 1) uses Traps, and 2) doesn't initialize the Ram itself, then when the first Trap happens your machine will probably do something bizarre, but it usually will not destroy disk data. Install.~ FileName [...Sys.Boot] Causes a customized version of the operating system on the file named by FileName to be written on the file Sys.Boot. For further details, please see the section on "Installing the operating system" in the Alto Operating System manual. BootKeys.~ FileName [...Sys.Boot] Did you know that by holding down various combinations of keys on the Alto keyboard while pressing the boot button it is possible to get the Alto to bootstrap load itself from any file on the disk? (This bootstrap will probably crash fairly quickly on any file except one in .Boot format.) Bootstrapping the Operating system is simply a special case of this: all keyboard keys up refers to disk address 0, which by convention is where a copy of the first data page of Sys.Boot is stored. To find out what keys to push in order to bootstrap load other files, you use the BootKeys command. Resume.~ FileName [...Swatee] The file named by FileName is patched so that its Swatee file pointer is the same as the current Swatee file pointer, and then it is loaded in and run. For best results, this file should be Swatee, or a copy of a Swatee. If you want to return to Swat with an old Swatee (for example, originally you didn't have the right .SYMS file) you can say Copy.~ Swatee _ OldSwatee (no need to do this if Swatee is already correct) Resume.~ Swat Chat.~ Ftp.~ Scavenger.~ NetExec.~ These commands load the corresponding programs from the Ethernet. If you have the .Run file for one of these, it will be found instead by the normal Executive lookup strategy. EtherBoot.~ octal number This command will boot any available Ethernet bootable file provided that you know its number. FileStat.~ FileName ... This command will tell you several things about a file: its length in bytes, size in pages, serial number and disk address, creation, read and write dates. If any FileName is of the form octal/s (or octal1,octal2/s) the file will be looked up by serial number rather than by name. This is useful if Scavenger or some other program gives you a serial number without telling you the name. The forms octal/v and octal/r tell you about the file that owns the specified virtual or real disk address. MesaBanks.~ bank specifiers Executive User's Guide June 26, 1980 7 This command sets the default memory configuration for Mesa programs. Uses and implications of this command are described in the Mesa documentation and will not be covered here. WriteDirectory.~ This command causes Executive to write the sorted version of your directory back onto SysDir on your disk. Keeping the directory approximately sorted on the disk greatly reduces the time required for Executive to sort it during initialization. Executive will periodically perform a WriteDirectory in an attempt to keep the directory reasonably sorted. WriteDirectory also will compact the directory collecting all the free space at the end and will report several statistics about directory useage. 3. Subsystem Lookup Executive recognizes and knows how to invoke several kinds of subsystems. In order to select a subsystem matching the name given in the command line Executive uses the following algorithm: 1. For each of the strings , ".run", ".image", ".bcd", ".~", "*.run", "*.image", "*.~" and "*.bcd" ask how many directory entries are matched by appending the string to the typed name. As soon as the answer is one the subsystem is found. Note that the question is asked separately for each extending string and that the questions are asked in the order specified. The order of the search means that the order of subsystem types is: Bcpl program, Mesa image file, Mesa bcd file, internal command (the order of Mesa bcd files and internal commands is reversed if the name is not completely specified). 2. If the subsystem name ends in ".image" it is assumed to be a Mesa image file and is invoked using the program RunMesa.run. 3. If the subsystem name ends in ".bcd" it is assumed to be a runnable Mesa configuration. "Mesa.image" is added to the front of the command and the lookup starts over. 4. Otherwise the subsystem is invoked directly (if internal) or via CallSubsys. (If the file does not look like a valid .Run file you will be asked to confirm that you want to try to run it.) 4. User.Cm Entries The Executive section of User.Cm may contain several commands to the Executive. Most of these are command lines to be executed if some event is noted (see the Operating System documentation for a description of events). In addition to standard events, any other event may be specified using the notation eventN where N is the event number (in decimal). Executive User's Guide June 26, 1980 8 The command in the line labeled eventAboutToDie: will be executed after the twenty minute timeout described above but before Dmt is loaded. If you use this feature you should include a Quit.~ as the final command. The number of text lines in the user command window can be set from User.Cm using the selector DisplayLines: followed by a number. You are advised not to set this number higher than its default value (currently 16), but you might want to reduce the number in order to leave more memory space for your directory if you have a large number of files (say, more than 500). The line "Screen: Black" in User.Cm directs Executive to use the display in white-on-black rather than the normal black-on-white mode. 5. Dump Format A dump file is a sequence of blocks of eight-bit bytes. The first byte of each block is the block type. A typical dump file might look like: ... . . ... Name Block - Type=#377 A name block contains two bytes of file attributes and then the file name. The file attributes are used by the Nova operating system; Alto Dump.~ sets these bytes to 0, and Alto Load.~ ignores them. The file name is a sequence of ASCII characters terminated by a 0 byte. Data Block - Type=#376 A data block contains two bytes of byte count (high-order byte first), two bytes of checksum (high-order byte first), and a sequence of data bytes. The byte count must be less than or equal to 256 for compatibility with Novas, and the count does not include the checksum or byte count; only the data bytes are counted. Novas do not handle data blocks with byte counts of 0 or 1 correctly. Alto Dump.~ will not produce such blocks unless forced to dump a file whose length is less than 2 bytes. The checksum is a 16-bit add ignoring carry, over the data and byte count. If the block has an odd number of bytes, the last byte is NOT included in the checksum computation. Error Block - Type=#375 Novas generate error blocks. Alto Dump.~ does not. Alto Load.~ terminates if it encounters one. End Block - Type=#374 An end block has no contents and terminates a Load.~. Date Block - Type=#373 Date blocks with six bytes of date are generated by Nova RDOS. Alto Executive User's Guide June 26, 1980 9 Dump.~ puts the four byte Alto creation date into the first four bytes and zeros the remaining two. For compatibility with older Alto implementations, date blocks are optional. N.B. This appendix is included thanks to David Boggs.