*line   1: Unknown output type = 
>$A invert=0; cap=0; capsh=0; und=0; undsh=0
EDINBURGH COMPUTER SCIENCE DEPARTMENT            ADVANCED PERSONAL MACHINE

!<INDIVIDUAL COMMANDS
!<L       Log on or off
          L <user>               eg  }L PDS
                                     Pass:......  [not echoed]
          L

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.

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.
!>
!<T       Transfer files
          T <in1>,<in2>,<in3>/<out>     eg  }T ONE,TWO/BOTH

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.
!>
!<P       Print file(s)
          P <file>,<file>,...           eg  }P TEST.LIS

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.
!>
!<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

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.

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.
!>
!<F       File enquiry
          F {<dir>:}<template>       eg  }F
                                         }F APM:
                                         }F NEW*
                                         }F APM:*.ASM

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.

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.

Note also the command FILES which provides fuller information about files,
including size, permissions and date of creation.
!>
!<D       Directory operations
          D <dir>             eg  }D LIB2  or just  }D

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.

The current default directory is used if <dir> is omitted.
!>
!<SET     Change Directory
          SET <dir>

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.
!>
!<QUOTE   Quote Password
          QUOTE               eg  }QUOTE
                                  Pass: .....  [not echoed]

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.
!>
!<DELETE  Delete file(s)
          DELETE <file>,<file>,..     eg  }DELETE TEST1,LIB:TEST2

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.

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.
!>
!<PURGE   Purge unwanted files
          PURGE

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.
!>
!<RENAME  Rename file
          RENAME <old1>/<new1>       eg  }RENAME CURDATA/OLDDATA

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.

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.
!>
!<PERMIT  Change file protection
          PERMIT <file>/<code>     eg  }PERMIT PROG/FF
          PERMIT <dir>:/<code>     eg  }PERMIT LIB:/FRA

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.

The interpretation of <code> on the 1976 Filestore is as follows:

The first letter denotes the permission given to anyone with owner-authority,
the second letter denotes permissions given to everyone else.
These letters may be:
          F : Free (i.e. Read/Write/Delete)
          R : Read-only
       or N : no access

The third letter, if present, affects the archive flag associated with the file
and may be:
          A : Archive (i.e. back this file up regularly)
       or V : Vulnerable (do not back this file up).
!>
!<PASS    Change password
           PASS

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).

This permanently changes the password to the new choice.
!>
!<PAMSET  Set command separators
             eg      PAMSET
                     GroupSeparator then Keyflag:|\

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.

The standard system default for these is:
      Group separator: oblique stroke ('/')
      Keyword flag   : dash           ('-')

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.

The system defaults are restored whenever a user logs off.
!>
!<HELP    Obtain help
          HELP <topic>             eg  }HELP USERS  or just  }HELP
*line 225: SPURIOUS DIRECTIVE B

$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.

The single word HELP by itself provides general information about the system and
the command language.

HELP followed by a topic-name like TERMINAL provides information about a
particular topic.

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.

Type ? within HELP for a summary of the operations provided.
!>
!<USERS   List users

The command USERS provides a list of the users currently logged on to the
central filestore.
!>
!<COMPARE Compare two files
          COMPARE <file1>,<file2>/<diff>   eg  }COMPARE TEST1,TEST2

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.
!>
!<LAYOUT  Layout document
          LAYOUT <file>/<doc>           eg  }LAYOUT PROJ.LAY/LP:

This command invokes the document production program LAYOUT to format a file
prepared in LAYOUT source.

The program is described in a separate manual.
!>
!<VAX     Log on to VAX
          VAX

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.

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.

This facility should be used sparingly, because the mode of connection puts a
heavier load on Vax than ordinary terminals.

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).
!>
!<ASS     Assemble program
          ASS <file> <options>

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.

The assembler accepts the full assembly language as defined by the manufacturer
(see Motorola Manual M68000 Assembly Language).
!>
!<IMP     Compile Imp program
          IMP <file> <options>

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:

     -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.

!>
!<C:CC    Compile C program
          C:CC <filename> [<pre-processor flags>]

The C:CC command calls a version of the MIT portable compiler for the C
programming language.

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.

For further information, give the command HELP C at system level.
!>
!<CR      Run C program
          CR <C-command-line>

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.

For further information, give the command HELP C at system level.
!>
!<SR      Run S-Algol program
          SR <SA-command-line>

The SR command invokes the APM interpreter for the S-Algol language as described
by Cole and Morrison.

The first thing on the command line is taken to be the name of an S-code file,
which is loaded and interpreted.

The command SR SA.SC <file> invokes the S-Algol interpreter to load and
interpret the S-Algol compiler.

For further information, whistle.
!>
!>
*line 365: SPURIOUS DIRECTIVE L
$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.

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.

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.

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.
!>
!<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.
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.

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.
!>
!<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.

In general, the effect of typing a command is that the command verb is used to
locate a file which implements the command.

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).

Examples of more elaborate commands (discussed below) are:
              COMPARE  OLDFILE , NEWFILE  / DUMPFILE
              T  TESTPROG / CURRPROG

!<Command verbs
The interpretation of a command verb proceeds along the following lines:

  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.
!>
!<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.

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.

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.


!<Examples

              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.

              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.

              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.
!PAGE

              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).

              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.
!>
!<Punctuation
General conventions governing the format of most commands are as follows

(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) within a group of either input or output stream-names the separator is a
comma;

(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;

(d) the complete command is terminated by RETURN;

(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.
!>
!<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.
Full information about the management of files is contained in the Filestore
manual.

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.
Conventionally a dot is used to separate a file-name extension (like LIS or OBJ)
from the file-name proper.

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.
!>
!<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.
!>
!>
!<Executable files
Executable files are either object files or command files.  Both types have the
extension MOB.

Object files
These are files containing directly executable programs, generated by one of the
assemblers or compilers available on the system.

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.
!>
!<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:
                 <newname> = <oldname>
For example:
                 GO = UTIL:TESTPROG1

!<More about Symbols

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.

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.

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!).
!>
!>
!<Flag Characters
A command verb may be terminated by one or more flag characters, which cause the
command to be interpreted slightly differently.

Flag character '_' suppresses translation of the command verb via the command
dictionary.

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).

Flag character '?' causes the loaded program to be entered in trace-mode for
single step execution under control of the Software Front Panel.
!>
!>
!<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.

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.

!<Prompts
Many programs issue a prompt message when input is required, as a guide to the
user.

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.
!>
!<Terminal Control Characters
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).
!>
!>
!<DEMONSTRATION PROGRAMS
A number of demonstration programs are available in the directory ADEMO.

The graphics demonstration programs must be run on a machine with the
appropriate graphics hardware.

Many of the programs run continuously until abandoned by ^Y.

!<General
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.
!>
!<Graphics - misc

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

!>
!<Graphics - CAD

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.
!>
!<Graphics - animation
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.
!>
!>
!<LOW-LEVEL OPERATIONS
!<BOOT    Load New System
          BOOT <file>

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.
!>
!<TOBIN   Convert to Binary
          TOBIN <infile>/<outfile>

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.
!>
!<HEX     Convert to hex
          HEX! <in>/<out>

The stream (usually a file) <in> is output to <out> one byte at a time, in
hexadecimal.
!>
!<DISASS  Dis-asssemble machine-code
          DISASS <codefile> / <listing>

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.

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.

The following options may be specified:
     -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


!>
!<DIS     Dis-assemble machine-code in store
          DIS <from> <to> [/<out>]

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.
!>
!>
!<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.

The information in this section is highly provisional and liable to change.

!<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.

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.
!>
!<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.

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.
!>
!<MOB files
If the first character in an executable (MOB) file is the character '{', it is
treated as a command file.
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.
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)].

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.
!>
!<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].

List of Entry-points
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.

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.

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.
!>
!>
!<THE SOFTWARE FRONT PANEL

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.
!PAGE
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).
!>
!>
!>
End of input file
Program stopped
