$a invert=0; cap=0; capsh=0; und=0; undsh=0
$a line=80; page=0; top=0; bottom=0
$l
EDINBURGH COMPUTER SCIENCE DEPARTMENT            ADVANCED PERSONAL MACHINE
$b
!<INDIVIDUAL COMMANDS
$l4
!<L       Log on or off
          L <user>               eg  }L PDS
                                     Pass:......  [not echoed]
          L
$b
This command is used to log on to the Filestore.
The purpose of logging on is to establish the default directory
to be used in referencing files, and to demonstrate
authority to use those files by citing the appropriate password.
The user is prompted for the password (which is not echoed).
If the command file LOGIN.MOB exists, the commands in it are obeyed before
the system accepts further commands from the terminal.
If another user is already logged on at this machine, the previous user is
automatically logged off.
$b
Since this command always causes any existing user to be logged off,
it can be used without any parameter simply to log the current user off.
$l3
!>
!<T       Transfer files
          T <in1>,<in2>,<in3>/<out>     eg  }T ONE,TWO/BOTH
$b
The Transfer command is used to copy information from one or more
(up to three)
source streams to a destination stream. If more than one source stream
is specified, the data is concatenated in the order given.
The default for <in1> and <out> are the terminal.
$l3
!>
!<P       Print file(s)
          P <file>,<file>,...           eg  }P TEST.LIS
$b
The specified files are sent to the filestore printer. Any copying
operations this involves are done remotely and do not impose a load
on the local processor or on the network.
$l7
!>
!<E       Edit file
1         E <old>/<new>                 eg }E TEST1/TEST2
2         E .N/<new>                    eg }E .N/NUPROG
3         E <old>                       eg }E DATA
4         E <old>,<secondary>[/<new>]   eg }E DATA,EXTRA
5         E <old>/.N                    eg }E PROG.LIS/.N
$b
The Edit command is used to invoke the VECCE context editor.
Detailed information about this editor is available by giving
the system command HELP ECCE.
$b $l0
1. The first form of command is used to edit an existing file
   to a new file.
2. The second form is used to create a file from scratch.
3. The third form is used to edit an existing file.
   In this case, the new file is given the same name as the old,
   (but the original file is not deleted until the editing has
   been finished successfully).
4. The fourth form is used to specify a secondary input file.
5. The last form is used to examine a file without altering it.
$l6
!>
!<F       File enquiry
          F {<dir>:}<template>       eg  }F
                                         }F APM:
                                         }F NEW*
                                         }F APM:*.ASM
$b
The file enquiry command F provides the facility to list the names
of the files in a given directory.
If a directory is not specified, in the form <dir> followed by colon,
the current default directory is used.
If no template is specified, the names of all the accessible files in the
current directory are listed.
Accessible files are those to which the enquirer has some permitted
access.
$b
The purpose of specifying a template is to select a subset of
the complete list of names which have certain character sequences in common.
A template consists of a sequence of characters each of which
is a file-name character, or a question-mark, or an asterisk.
For a file-name to match the template, the characters of the
template must match those of the file-name in the order given,
with the question-mark acting as a wild-card matching any single
character and the asterisk as a wild-card matching any sequence
of characters.
$b
Note also the command FILES which provides fuller information about files,
including size, permissions and date of creation.
$l3
!>
!<D       Directory operations
          D <dir>             eg  }D LIB2  or just  }D
$b
This command displays the names of the files in the specified directory
and allows the user to ask for any of them to be Shown, Renamed,
Deleted, or Permitted.  It is self-documenting.  Type H within it for
assistance.
$b
The current default directory is used if <dir> is omitted.
$l3
!>
!<SET     Change Directory
          SET <dir>
$b
The SET command is used to change to another default directory, to be
used in subsequent file references. If <dir> is omitted, the default
reverts to that established at log-on.
$l4
!>
!<QUOTE   Quote Password
          QUOTE               eg  }QUOTE
                                  Pass: .....  [not echoed]
$b
The QUOTE command is used to quote a password in order to demonstrate
authority additional to that established at log-on, so that protected
files in directories owned by someone else may be accessed.
$l3
!>
!<DELETE  Delete file(s)
          DELETE <file>,<file>,..     eg  }DELETE TEST1,LIB:TEST2
$b
The DELETE command causes the specified file(s) to be destroyed.  The
user must have owner-authority over the directory involved in order to
delete files in it.
$b
As a precaution against accidental deletion of source files, confirmation
is requested before a file without an extension or with extension .ASM
is deleted. The response should be 'yes' or 'y' if the file is to be
deleted, 'no' or 'n' if not.
$l3
!>
!<PURGE   Purge unwanted files
          PURGE
$b
The PURGE command is used to get rid of transient files which may have
been created by an abandoned operation, such as a failed program.
It deletes all such files in the current directory.
$l3
!>
!<RENAME  Rename file
          RENAME <old1>/<new1>       eg  }RENAME CURDATA/OLDDATA
$b
The RENAME command is used to rename one or more files.  The user must
have owner authority with respect to the directory containing the file
in order to rename it.  Other attributes of the file, like date of
creation and permissions, are unaffected by renaming.
$b
It is not possible to alter the directory part of a file-specification.
The parameter <old1> may contain a directory name, as in LIB:TEST2,
but <new1> may not.
$l4
!>
!<PERMIT  Change file protection
          PERMIT <file>/<code>     eg  }PERMIT PROG/FF
          PERMIT <dir>:/<code>     eg  }PERMIT LIB:/FRA
$b
The first form changes the protection of <file> to <code>.
The second form changes the default protection associated with the
directory <dir>; this applies to all files subsequently created in that
directory.
$b
The interpretation of <code> on the 1976 Filestore is as follows:
$b
The first letter denotes the
permission given to anyone with owner-authority, the second letter
denotes permissions given to everyone else.
$b0
These letters may be:
$l0
          F : Free (i.e. Read/Write/Delete)
          R : Read-only
       or N : no access
$b
The third
letter, if present, affects the archive flag associated with the file
and may be:
$l0
          A : Archive (i.e. back this file up regularly)
       or V : Vulnerable (do not back this file up).
$l3
!>
!<PASS    Change password
           PASS
$b
This command is used to alter the user's password to something else.
First, the existing password is requested, as a safeguard, and then
the new password, which is requested twice to verify correct entry
(since passwords are not echoed).
$b
This permanently changes the password to the new choice.
$l4
!>
!<PAMSET  Set command separators
             eg      PAMSET
                     GroupSeparator then Keyflag:|\
$b
The command PAMSET is used to specify user preferences for the characters
used as punctuation symbols in the parameter part of a command line.
Choice is provided for two cases: the group separator used
to separate output file names from input file names and the flag character
used to introduce a keyword parameter.
$b
The standard system default for these is:
$l2
      Group separator: oblique stroke ('/')
      Keyword flag   : dash           ('-')
$b
The command PAMSET prompts for two characters, which must be typed in
the order indicated without intervening spaces.
The space character is a valid choice for group separator, though its
use imposes restrictions which do not apply to non-space choices.
Space is not valid for the keyword flag.
$b
The system defaults are restored whenever a user logs off.
$l4
!>
!<HELP    Obtain help
          HELP <topic>             eg  }HELP USERS  or just  }HELP
$b
The HELP command is used to obtain information aboy APM commands and
facilities. It provides access to on-line documentation for the
user to browse through.
$b
The single word HELP by itself provides
general information about the system and the command language.
$b
HELP followed by a topic-name like TERMINAL provides information
about a particular topic.
$b
This facility is similar to the EMAS VIEW facility, which provides
access to information using a Prestel-style tree-structured
approach.
Information is presented on a page-by-page basis, using RETURN to move
to the next page and the cursor keys to skip about.
$b
Type ? within HELP for a summary of the operations provided.
$l2
!>
!<USERS   List users
$b
The command USERS provides a list of the users currently logged on to
the central filestore.
$l3
!>
!<COMPARE Compare two files
          COMPARE <file1>,<file2>/<diff>   eg  }COMPARE TEST1,TEST2
$b
The program COMPARE compares two files and produces a list of the lines
which differ in each file.  The matching is done in such a way that
short insertions are recognised without generating a lot of false
mismatches.  The differing lines are printed out preceded by 1 or 2 to
indicate which file they are from.  The differing lines are followed by
the first line which matches in both files; preceded by an equals.
$l3
!>
!<LAYOUT  Layout document
          LAYOUT <file>/<doc>           eg  }LAYOUT PROJ.LAY/LP:
$b
This command invokes the document production program LAYOUT to format
a file prepared in LAYOUT source.
$b
The program is described in a separate manual.
$l3
!>
!<VAX     Log on to VAX
          VAX
$b
The VAX command allows the APM user to access the ECSVAX/VMS system
over the ethernet, so that the terminal can be used as a VAX terminal.
$b
As this is a Network Terminal connection, rather than a direct one,
some facilities may not work in the customary way or may require
special action.
$b
This facility
should be used sparingly, because the mode of connection puts a heavier
load on Vax than ordinary terminals.
$b Throughout the Vax session, all commands and data are being directed
to the Vax system. A return is made to the APM system command level
when the VAX process to which the user
is connected stops (normally when the user logs off VAX).
$l3
!>
!<ASS     Assemble program
          ASS <file> <options>
$b
The ASS command invokes the M68000 assembler to assemble the program in
<file> (with assumed extension ASM).  The object code (in Motorola
format) goes into a file with extension MOB, the listing into a file
with extension LIS.  By default, production of object code is enabled,
of a listing disabled.
$b
The assembler accepts the full assembly language as defined by the
manufacturer (see Motorola Manual M68000 Assembly Language).
$l3
!>
!<IMP     Compile Imp program
          IMP <file> <options>
$b
This invokes the IMP compiler for the M68000.  The program in <file> (no
assumed extension) is compiled, with object code (in binary image form)
going to a file with extension MOB.  By default, production of object
code is enabled, but is suppressed if the program contains
compiler-detected errors.  By default, production of a listing is
disabled.  The main options are:
$l0

     -LIST        Produce a listing to file with same name as source
                  and extension .LIS
     -LFILE=LP:   Produce listing direct to network printer
     -NODIAG      Suppress line-number diagnostic
     -NOCHECK     Suppress run-time checks

For further information, exit from HELP and give the system command HELP IMP.

$l3
!>
!<C:CC    Compile C program
          C:CC <filename> [<pre-processor flags>]
$b
The C:CC command calls a version of the MIT portable compiler
for the C programming language.
$b
The filename specified is compiled to produce a relocatable machine code
file <basename>.REL where <basename> is formed by stripping any extension
from <filename>. .REL files can be linked together using the C:LINK command.
$b
For further information, give the command HELP C at system level.
$l3
!>
!<CR      Run C program
          CR <C-command-line>
$b
The CR command invokes the C linking loader.  The first thing on the
C-command-line is taken to be the name of a C-code file (assumed
extension CB) or, if it starts with '@', the name of a file (no assumed
extension) containing several C-code file names.  The code file(s) are
linked with the run-time support library, loaded, and entered.
$b
For further information, give the command HELP C at system level.
$l3
!>
!<SR      Run S-Algol program
          SR <SA-command-line>
$b
The SR command invokes the APM interpreter for the S-Algol language
as described by Cole and Morrison.
$b
The first thing on the
command line is taken to be the name of an S-code file, which is loaded
and interpreted.
$b
The command SR SA.SC <file> invokes the S-Algol interpreter to load and
interpret the S-Algol compiler.
$b
For further information, whistle.
$l3
!>
!>
$l1
!<BACKGROUND
The APM is constructed around a high-performance
memory bus, shareable by several processors and permitting
easy expansion of memory capability. The bus supports 32-bit
data operands and 32-bit (byte) addresses, with separate data and
address lines.
$b
The basic version of the system has a single processor board utilising
the Motorola 68000 microprocessor and one or more 1/2 megabyte
memory boards. The processor board interfaces to a standard video terminal
and to the Department's ethernet-type network.
There is no permanent local storage in the basic machine, all
files being held on remote file servers accessed over the network.
$b
Optionally, a system may incorporate either of two levels of
graphics capability. The lower level provides a passive frame-store
memory which allows direct access from the ordinary processor
to individual pixels; the second level puts the frame-store
under the control of a programmable graphics processor.
$b
The existing operating system supports a single-process environment.
The full operating system will consist of a nucleus
concerned with process creation and synchronisation, together
with an open-ended set of modules, selectable at will according
to configuration and user needs.
$l2
!>
!<LOADING THE SYSTEM
To load the system turn the power-on key clockwise to the first position.
If already switched on, the system may be reset and re-loaded at any time
by (gently!) pressing the small spring-loaded switch located on the boot
processor board.
This causes the operating system
software to be loaded over the network from the Filestore.
$b0
NB: The memory boards have similar-looking switches and should not be
confused with the boot processor board. The latter can be distinguished by the
ribbon cable connecting it to its neighbour.
After initial loading, the system announces
itself on the video screen and outputs a curly bracket, inviting
the user to enter a command at the keyboard.
$b
Usually the first command that a user will give in a session
will be the L command to log on to a remote filestore. However, it
is not essential to do so in order to use the system.
$l2
!>
!<COMMAND LANGUAGE
The simplest commands consist of a single word (a verb or
abbreviation for a verb); others consist of a number of words,
separated by prescribed punctuation symbols. Commands are
always terminated by typing RETURN, and until this is done,
they can be corrected or revoked at will.
$b
In general, the effect of typing a command is that the command verb
is used to locate a file which implements the command.
$b
Examples of some of the simple commands which require no
additional information beside the command verb itself are
HELP (to elicit help information) and TOD (to find out the
time of day).
$b
Examples of more elaborate commands (discussed below) are:
$l0
              COMPARE  OLDFILE , NEWFILE  / DUMPFILE
              T  TESTPROG / CURRPROG
$b $l1
!<Command verbs
The interpretation of a command verb proceeds along the following
lines:
$l0

  If the word is a defined symbol (see below), it is replaced
  by its definition and the resulting command is interpreted;

  A file with the same name as the command verb and extension MOB
  is searched for.
  If a directory is included in the name (for example, APM:PROG),
  the search is confined to the directory indicated.
  Otherwise, the search is made, first, in the user's selected
  directory and, failing that, in the system directory FMAC.
  If no such file can be found, an error report is made.

  The located file may be: a file of commands to be obeyed
                        or a Motorola 68000 object program to be executed.
$l2
!>
!<Parameters
In general it is necessary for the user to be able
to specify not only what operation is to be performed but
also what data is to be used, where the results are to go,
and what options are to be selected. This is done by
supplying additional parameter words following the command
verb.
$b
When a parameter is used to denote a data source or
destination, it is termed a stream-name.
A stream-name may take either of two forms: a file-name or a device-name.
$b
When parameters are present, they are separated from the
command word by at least one space.
Some conventions governing the use of punctuation symbols in the rest of the
command are illustrated in the following examples.
$b2 $l1
!<Examples
$b $l1
              T  TESTPROG / CURRPROG
Here the command word is T, indicating the Transfer
operation,which copies data from any file or device
to any other file or device. The source (TESTPROG)
is specified first and then the destination (CURRPROG)
following an oblique stroke.
$b $l1
              COMPARE  OLDFILE , NEWFILE  / DUMPFILE
In this case, the command word is COMPARE, indicating
file comparison. For this operation the two files to be
compared (OLDFILE and NEWFILE) have to be specified as
inputs; these file names are separated by a comma.
Then the output file to which a list of discrepancies is
to be sent (DUMPFILE) is specified after the oblique
stroke.
$b $l1
              COMPARE  OLDFILE , NEWFILE
In many cases, there are default parameters for a
command which are understood if the user does not supply
a parameter explicitly. In the case of COMPARE, the
default for output is the terminal.
$l1
!PAGE
$b $l1
              IMP  CURRPROG-NOASS-LIST
In this example invoking the IMP compiler, the source
program is specified as the first parameter and then two
options are selected:
-NOASS to suppress unassigned-variable checking and -LIST
to cause a listing to be produced.
The options are selected by means of a keyword preceded by a dash (minus-sign).
$b $l1
              IMP-NOASS-LIST  CURRPROG
This command is identical in effect to the previous one,
making the point that the placing of option specifiers
is open, unlike the placing of other parameters.
$l2
!>
!<Punctuation
General conventions governing the format of most
commands are as follows
$b
(a)  output stream-names are separated from input stream-names
by a group-separator character selectable by the user
(see the command PAMSET) -- the default
is the oblique stroke ('/');
$b
(b)  within a group of either input or output stream-names
the separator is a comma;
$b
(c)  keyword parameters are preceded by a keyword flag character
selectable by the user (see the command PAMSET)
 -- the default is the dash (minus);
sometimes keywords may be followed by an equals-sign and a value;
$b
(d)  the complete command is terminated by RETURN;
$b
(e)  spaces are optional before and after the punctuation
symbols mentioned above, except that the keyword flag character must be
followed immediately by the keyword.
$l2
!>
!<File-names
File-names denote files held on a remote file server; file naming
conventions are those imposed by the file server. At present, the only
such server is the original central Departmental Filestore introduced in
1976.
$b0
Full information about the management of files is contained
in the Filestore manual.
$b
The naming conventions are as follows.
The full form of a file-name consists of an owner-name,
followed by a colon, followed by a file-identifier proper.
In many cases the owner-name is implicit, so that only
the file-identifier proper need be typed. The latter
consists of up to 12 characters, of which the first must
be a letter or a dollar-sign,
and the remainder may be any
combination of letters, digits and dots.
A file-identifier
starting with a dollar-sign denotes a temporary file, which
is automatically deleted when the user logs off.
$b0
Conventionally a dot is used to separate a file-name extension
(like LIS or OBJ) from the file-name proper.
$b
The special file name LP: (that is, owner-name LP followed
simply by a colon) is used to denote the line-printer connected
to the Filestore.
$l2
!>
!<Devices
Device-names are distinguished by starting
with a colon. On the basic machine, the only device is the video
terminal, which is denoted by :T (or simply a colon by itself).
Also reckoned as a device is the null data stream (denoted by :N),
which it is sometimes convenient to specify in place of a file-name;
for input, this implies no data and for output, results to
be discarded.
$l3
!>
!>
!<Executable files
Executable files are either object files or command files. Both types
have the extension MOB.
$b $l
Object files
These are files containing directly executable programs,
generated by one of the assemblers or
compilers available on the system.
$b $l
Command Files
A command file
consists of a sequence of commands and data exactly as they would be
typed at the terminal, except that the first character in the file must
be a left curly bracket ('{').  The commands are successively executed
until either the end of the file is reached or one of the commands
fails.  The command file is closed after the last (and possibly only)
command in the file is executed.  One command file may call another, but
presently only on a chained (not nested) basis.
$l2
!>
!<Symbol Dictionary
The system maintains a dictionary of names or 'symbols' which have
been defined to stand for other names or partial command sequences.
A number of system definitions are established when the system is first
loaded. The user may add others as required by means of symbol definition
commands.
The form of this type of command is:
$l1
                 <newname> = <oldname>
$b0
For example:
$l
                 GO = UTIL:TESTPROG1
$b $l
!<More about Symbols
$b
When a program is loaded for which there is an abbreviation in the
command dictionary, the system remembers where it has been loaded. The
space occupied by the binary image is not released when the program
finishes. This saves time when the same program is subsequently required
again, which is especially useful for large frequently used programs like
the compiler.
$b
When symbols are looked up in the command dictionary, approximate
(leading substring) matches are taken to be sufficient. For example,
given the abbreviation
ASSEM=FMAC:M68000
the command ASSEM, but also the commands ASS or just A may be used to refer
to FMAC:M68000, provided there has not been a more recent symbol definition
starting with A OR ASS.
$b
At present, it is not possible, as on VAX/VMS,
to include preferred default options in the symbol definition
(like IMP=I:C-DIAG-LIST).
It is, however, possible to include flag characters in
a definition (e.g$. COMPARE=FMAC:COMPARE!).
$l3
!>
!>
!<Flag Characters
A command verb may be terminated by one or more flag characters, which
cause the command to be interpreted slightly differently.
$b
Flag character '_' suppresses translation of the command verb via
the command dictionary.
$b
Flag character '!' instructs the command interpreter to read the rest of
the command line, and to interpret it as a set of input-output stream
definitions as noted above
(up to 3 input file names separated by commas, optionally
followed by a '/' and up to 3 output file names separated by commas).
$b
Flag character '?' causes the loaded program to be entered in trace-mode
for single
step execution under control of the Software Front Panel.
$l3
!>
!>
!<THE VIDEO TERMINAL
On the basic configuration, the VDU terminal is the interactive control
device for access to the system. In fact, it figures as two devices:
a keyboard for input, and a display screen  for output. Terminals
are always driven in full duplex mode, which means that
information typed at the keyboard does not automatically appear
on the screen; it does so only if the software dealing with keyboard input
(the terminal handler) echoes it. Most of the time, characters
are echoed as they are typed in, but in some cases echoing
is suppressed or other characters substituted.
$b
The general principle for text input is that keyboard
input is not acted on until the RETURN key (or other terminator
key) is pressed, although some highly interactive programs override
this provision. All the printing characters of the ASCII character
set may be entered in the normal way, but the control
characters are subject to special interpretation by the system,
as described below.
Control characters are generated by pressing a normal key while holding
down the CTRL key. For example, TAB (though usually provided as
a single key) can also be generated by CTRL together with I; this
is indicated below as ^I.
$b $l1
!<Prompts
Many programs issue a prompt message when input is required, as
a guide to the user.
$b
It is usually permitted to type ahead of
input requests, and it may be convenient to do so when a lengthy
operation is in progress.
Information typed ahead is
not echoed until the running program tries to read it.
It is discarded in the event of a total failure
in the execution of a previously issued command.
$l2
!>
!<Terminal Control Characters
$l0
DEL       Erase the last extant character typed on the current line.

BS or ^X  Erase all characters typed on the current line.

RETURN    Terminate the current line.

^S        Set auto-freeze mode.   When enabled, output to the terminal is
          halted every time the screen becomes full and remains in this frozen
          state until something is typed on the keyboard;
          LF 'unfreezes' the display for one line,
          RETURN or BS unfreeze the display for 1 page,
          and ^Q changes the mode to 'continuous scrolling'.

^Q        Quit auto-freeze mode.

^Y        Abandon the current activity, and return to command level.

^D or ^Z  Terminate input from the terminal, creating an 'end of file'
          condition.

^P        Pass the next character typed as data to the program
          currently running. For example,  ^P^Y allows ^Y to be input
          without stopping the program.

^T        Escape to trace-mode (See Software Front Panel).
$l3
!>
!>
!<DEMONSTRATION PROGRAMS
A number of demonstration programs are available in the directory ADEMO.
$b
The graphics demonstration programs must be run on a machine with the
appropriate graphics hardware.
$b
Many of the programs run continuously until abandoned by ^Y.
$b $l1
!<General
$l0
CALC:   Simple calculator.

PALIN:  A program for the Palindrome puzzle (cpu intensive).
        The program prompts for a starting number. Interesting cases
        are 98 (succeeds after 24 iterations) and 196 (unknown: this
        one will run and run).

INVADE: Space Invaders For Visual 200.
        Keys are {4 Move left}      {5 FIRE}      {6 Move Right}

MINSIM: Simulates logic as generated from MINIMO (PLA minimiser).
MS:     Calls MINSIM with demo file.  Type number of steps.
$l2
!>
!<Graphics - misc
$l0

TRIGTEST:   Evaluates software floating point SIN,COS,SQRT
    
DISPLAY:    Displays text
            Parameters:  filename{,fontfilename}{<space>paper<space>}
            Default fontfile FMACS:FONT.VISUAL
            Other font files are FMACS:FONT.{BANTAM,IGOR,RVISUAL,RIGOR}
            There is also a program RDISPLAY for a screen rotated through 90`.
            The Default font is FMACS:FONT.BANTAM

$l2
!>
!<Graphics - CAD
$l0
  
CHARLES:    Emulates the Charles graphics terminal
            Cursor keys move the picture around.
            A null filename re-draws previous file
            without going back to filestore.
CH:         Calls CHARLES with demo file.

SKETCH:     Displays a PCB layout.
SK:         Calls SKETCH with demo file.
$l2
!>
!<Graphics - animation
$l0
CLOCK:     Time-of-day clock

ROAD:      Rolling road with APM logo

GRAPHAN:   Tower of Hanoi.  Prompts for number of disks.
HA:        Calls GRAPHAN with the number 6.
  
TETRA:     Draws rotating tetrahedron -- prompts for centre, etc.
TE:        Calls TETRA with pre-defined sequence.
     
RUBIK:     Manipulates Rubik cube according to typed instructions.
RU:        Calls RUBIK with pre-set sequence
   
TWINKLE:   Draws a multitude of stars.
$l3
!>
!>
!<LOW-LEVEL OPERATIONS
$l2
!<BOOT    Load New System
          BOOT <file>
$b
The BOOT command loads the file specified starting at location 16_1000,
logs the current user off the Filestore, and jumps to the start-address
specified by the pseudo-reset vector contained in the loaded file.  It
is used to load trial versions of new operating systems.

If <file> is omitted, the effect is to inform the file server that local
information relevant to file server transactions has been lost.
$l3
!>
!<TOBIN   Convert to Binary
          TOBIN <infile>/<outfile>
$b
The standard Motorola M68000 assembler produces a form of output which,
aside from being space-inefficient, is incompatible with the ROM
bootstrap loader, which only loads straight binary images.  TOBIN
converts from Motorola format to binary image form.
$l3
!>
!<HEX     Convert to hex
          HEX! <in>/<out>
$b
The stream (usually a file) <in> is output to <out> one byte at a time,
in hexadecimal.
$l3
!>
!<DISASS  Dis-asssemble machine-code
          DISASS <codefile> / <listing>
$b
This program takes as input a file containing binary M68000 machine-code
instructions and translates these back to Motorola assembly language
statements. The input file is typically a standard
.MOB file produced by one of the compilers, but it does not have
to be. Hence the .MOB must be specified explicitly.
$b
A problem for the process of decoding is the presence in object files
of constant data in among the instructions.
Such data may correspond to valid machine instructions,
and will be printed as such. Because the M68000 has a variable
instruction length, it may also cause parts of following instructions
to be treated wrongly. This is usually confined to a single instruction
following a section of data.
$b
The following options may be specified:
$l0
     -FROM=.....    the byte displacement at which to start (default: 0)
     -TO=  .....    the byte displacement at which to stop (default: infinity)
     -HEX           input is in hex form rather than binary
     -BRIEF         suppress location numbering in output
$b2
$l3
!>
!<DIS     Dis-assemble machine-code in store
          DIS <from> <to> [/<out>]
$b
Code in the machine address space, between the specified addresses
<from> and <to> (both in hex), is decoded and output to stream <out> in
M68000 assembler notation.  If /<out> is omitted, output goes to the
terminal.
$l4
!>
!>
!<SOFTWARE ENVIRONMENT
The software environment as seen by the programmer is a composite of
facilities provided by the system and facilities provided by the
run-time support package for the particular language. At present
these boundaries have been drawn rather arbitrarily as circumstances
dictated. In particular, a number of utility routines have been
built into the operating system, which will, at a later stage, be
detached into library packages.
$b
The information in this section is highly provisional and liable
to change.
$b $l1
!<Initial System Loading
After the system has been reset (as a result of pressing the reset
button, of typing 'R' to the Software Front Panel, or of first switching
on), the ROM bootstrap fetches the operating system from the filestore.
The file FMAC:SYS on the 1976 filestore is read, and assumed to contain
a binary image of an operating system suitable for loading into memory
starting at address 16_1000.  Because in the M68000 the interrupt table
occupies the 256 longwords (1024 bytes) of store starting at address 0,
and this area is actually ROM, the ROM bootstrap contains code to
re-direct all interrupts through a corresponding table of pseudo-vectors
starting at address 16_1000.  The first two interrupt "vectors"
represent initial values for the stack pointer and program counter and,
consequently, the ROM bootstrap will use the corresponding values (at
16_1000 and 16_1004) to enter the loaded operating system.
$b
Once the basic system is loaded, it will load the command interpreter.
If by this time any key on the keyboard has been struck, the system will
ask for the name of an image file to load instead of the command
interpreter.  Otherwise it proceeds to load file FMAC:EXEC.MOB.  Once
this is loaded, it obeys command file FMAC:STARTUP.MOB, which contains
symbol definitions for some of the utility commands detailed above.
$l2
!>
!<Streams
The system supports 4 input streams (input 0-3) and 4 output streams
(output 0-3) for use for byte stream transput. Input 0 has the
significance of the command or control stream and Output 0 has
the significance of the report stream.
$b
When a program is loaded, the rest of the command line typed by the user
is not normally read by the command interpreter, but remains unread
on stream 0.
The loaded program can therefore read the parameter string from stream 0,
and is free to interpret it in whichever way it chooses.
$l2
!>
!<MOB files
If the first character in an executable (MOB) file is the character
'{', it is treated as a command file.
$b0
If the first character is the letter 'S', it is assumed to be an
object file in Motorola format.
The code is loaded
into free memory, with location counter addresses interpreted as
relative to the start of free memory.
$b0
If the first character of the file is neither '{' nor 'S',
the file is assumed to be a binary executable image, i.e. a contiguous
chunk of position-independant code. [At present the first character
should be binary 254 (16_FE)].
$b
Binary and Motorola format code files, once loaded, are entered by means
of a JSR to the last longword of the file.
The last longword is usually a jump with word displacement to
the actual start of the program. The area of free store available for
use by the program as stack or heap or general work space is
contiguous and is delimited at the low-address end by D6-256, and at the
high-address end by SP. The contents of all other registers on entry to the
program are undefined. Normally (except for programs which remain resident
because they have symbolic abbreviations) this contiguous area of free
store will be adjacent to the area into which the code was loaded.
$l2
!>
!<System routines
System routines are called indirectly
through a fixed-site table of entry points [The M68000 does not have indirect
addressing, so indirect calls are done as calls into a branch table].
$b
List of Entry-points
$b0
The file FMACS:SPECS.ASM contains a list of definitions for the routines
which are built-in to the system in a form suitable for inclusion
in an assembly language program. Most of the routines are also accessible
through the high-level language run-time support packages; see
the description of the individual languages.
$b
All these routines follow the convention that parameters are passed in
registers (values in D0 to D3, addresses in A0 to A3), results (if any) come
back in D0 or A0, all registers not conveying results retain the values they
had when the procedure was called.
Strings are held as length-prefixed sequences, and are always passed by
address -- of the first (length) byte.
$b
CAUTION: Many of the routines are provided within the system simply for
convenience of general availability and will eventually be phased
out in favour of external library packages.
$l3
!>
!>
!<THE SOFTWARE FRONT PANEL
$b
This debugging tool is invoked by appending the flag-character '?' to a
command verb, or by pressing ^T at the keyboard.  When invoked, the SFP
displays (near the top of the screen) the contents of processor
registers D0 to D7, A0 to A6, the current stack pointer A7, the status
register and program counter SR and PC, the line number (if an IMP
program compiled with the -DIAG or -TRACE qualifiers is running), and
the previous PC (if known).  In response to the "Now what?" prompt,
single-character commands are accepted, which are not subject to normal
line-editing conventions.  Unknown command characters (such as H for
help) cause a list of valid commands to be displayed.  These are shown
below.
$l1
!PAGE
$l0
S           Execute one single instruction of the running
            by setting the T bit in SR).

C           Resume normal execution of the running program.

Bx          Set breakpoint at x.  Execute instructions until PC=x.
            x is an absolute PC value and should be entered in
            hexadecimal immediately after the B (no leading spaces);
            the first non-hex character terminates the number,
            sets the breakpoint and resumes execution of
            the running program (implemented by replacing the
            instructions at the target PC by a TRAP #0 instruction,
            not by setting the T bit in SR).

R           Reset and reload the system.

N           Execute next statement or line.
            Only relevant to programs compiled with the -TRACE
            qualifier.

Ln          Execute statements until line n is reached
            (n is in decimal and should come immediately after
            the L). Only relevant to programs compiled
            with the TRACE qualifier

X           Examine store (Spy).  This issues a prompt for
            TWO hex numbers (no leading spaces, separated by
            one non-hex character).  The first is an address,
            the second a byte count (in the range 0 -- meaning
            256 -- to 255).
            The specified number of bytes (say k) are displayed
            on the screen. Three actions are then valid:
            Press RETURN: The next k bytes are displayed
            Press '=': The last byte displayed is
            overwritten  with a hex value, typed immediately following
            the '='.
            Press any of the above commands (including X to
            examine a different area of store).
$l3
!>
!>
!>