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 <null>, ".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><date block><data block 1>...<data block n>
      .
      .
      <name block><date block><data block 1>...<data block m>
      <end block>

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.