\documentstyle[a4,12pt]{article}
\begin{document}
\author{APM Manual pages}
\title{APM Basic Commands}
\maketitle
\parskip .1 in
\setcounter{secnumdepth}{10}
\parindent 0in
\section{Preamble}
EDINBURGH COMPUTER SCIENCE DEPARTMENT \hspace{0.8 in} ADVANCED PERSONAL MACHINE

\section{INDIVIDUAL COMMANDS}
\subsection{L \hspace{0.5 in} Log on or off}
\small\tt \begin{verbatim}          L <user>               eg  }L PDS
                                     Pass:......  [not echoed]
          L
\end{verbatim}\rm  \normalsize 
This command is used to log on to a 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.COM 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.

\subsection{T \hspace{0.5 in} Transfer or Copy files}
\hspace*{0.7 in} T $<$in1$>$,$<$in2$>$,$<$in3$>$/$<$out$>$ \hspace{0.3 in} 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.

\subsection{P \hspace{0.5 in} Print file}
\hspace*{0.7 in} P $<$file$>$ -$<$printer$>$ -$<$optional params$>$ \hspace{0.7 in} eg \}P TEST.LIS

The specified file is sent to the nominated printer (Machine Halls printer by
default). Multiple files may be sent: format is $<$file$>$ -$<$params$>$, $<$file$>$ .. etc

Allowed printers are..

\small\tt \begin{verbatim}MH (Default):  North Machine Hall
OP          :  Block O/P
LJ          :  Laser-jet (Appleton Tower only).
\end{verbatim}\rm  \normalsize 
All print requests are routed via the VAX so if the VAX is especially busy
the print operation may time out. If this happens the print request should be
resubmitted.


Additional parameters:

\small\tt \begin{verbatim}-c     : Characters per inch across the page. This may take the values
         10, 12, 13 or 17 but will only be implemented for the -MH printer

-l     : Lines per inch down the page. This may take the values 3,4,6 or 8
         for the -MH printer only

-dp -lq: Document print or letter quality. The -MH printer can print NLQ
         (Near Letter Quality) documents but does so slowly.
\end{verbatim}\rm  \normalsize 
Defaults are -c12, -l6, -dp -mh.

\subsection{E \hspace{0.5 in} Edit file}
\small\tt \begin{verbatim}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
\end{verbatim}\rm  \normalsize 
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. Information about the alternative editor IE can be obtained from HELP IE.

\small\tt \begin{verbatim}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.
\end{verbatim}\rm  \normalsize 
\subsection{FILES \hspace{0.2 in} File enquiry (alias F)}
\small\tt \begin{verbatim}          F {<dir>:}<template>       eg  }F
                                         }F APM:
                                         }F NEW*
                                         }F APM:*.ASM
\end{verbatim}\rm  \normalsize 
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.

Additional parameters:

\small\tt \begin{verbatim}  -OUTPUT=<filename>  directs the output from F to the nominated file.
  -FULL               gives further information about the file, namely:
                      SOA     Date   Time   Blocks(Extents)
                      S,O = access permissions for Self and Others
                      A = Archive/No Archive
                      Date, Time: When file was created or last altered.
                      Blocks(Extents): Size of file in 512-byte blocks
                      and number of extents it is spread over.
                      For further information about files use the
                      ANALYSE command. (See HELP UTILITIES)
  -ALPHA              presents the files in alphabetical order.
  -TOTALS             gives only information about the directory (i.e.
                      the information normally given in the first line
                      of an F request).
  ??                  causes F to prompt for each parameter in turn.
\end{verbatim}\rm  \normalsize 
\subsection{D \hspace{0.5 in} Directory operations}
\small\tt \begin{verbatim}          D <dir>             eg  }D LIB2  or just  }D
\end{verbatim}\rm  \normalsize 
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 ? within it for assistance.

The current default directory is used if $<$dir$>$ is omitted.

\subsection{SET \hspace{0.3 in} Change Directory}
\small\tt \begin{verbatim}          SET <dir>
\end{verbatim}\rm  \normalsize 
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.

\subsection{QUOTE \hspace{0.2 in} Quote Password}
\small\tt \begin{verbatim}          QUOTE               eg  }QUOTE
                                  Pass: .....  [not echoed]
\end{verbatim}\rm  \normalsize 
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.

\subsection{DELETE Delete file(s)}
\small\tt \begin{verbatim}          DELETE <file>,<file>,..     eg  }DELETE TEST1,LIB:TEST2
\end{verbatim}\rm  \normalsize 
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 extensions other than
.MOB or .LIS is deleted. The response should be 'yes' or 'y' if the file is to
be deleted, 'no' or 'n' if not.

\subsection{PURGE \hspace{0.2 in} Purge unwanted files}
\small\tt \begin{verbatim}          PURGE
\end{verbatim}\rm  \normalsize 
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.

On the new-style filestores, PURGE works rather differently:
New-style filestore files may have version numbers. PURGE selectively deletes
old versions of specified files or "wild-card" lists of filenames.

Examples:
\small\tt \begin{verbatim}PURGE fred         means "purge all files called fred in the current directory"
PURGE *.mob        purges all old versions of .MOB files
PURGE jim:print.*  purges all deleteable .MOB files in directory jim:.
PURGE jim:         purges everything in directory jim:
\end{verbatim}\rm  \normalsize 
\subsection{RENAME Rename file}
\small\tt \begin{verbatim}          RENAME <old1>/<new1>       eg  }RENAME CURDATA/OLDDATA
\end{verbatim}\rm  \normalsize 
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.

\subsection{PERMIT Change file protection}
\small\tt \begin{verbatim}          PERMIT <file>/<code>     eg  }PERMIT PROG/FF
          PERMIT <dir>:/<code>     eg  }PERMIT LIB:/FRA
\end{verbatim}\rm  \normalsize 
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 current Filestores 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:

\small\tt \begin{verbatim}          F : Free (i.e. Read/Write/Delete)
          R : Read-only
       or N : no access
\end{verbatim}\rm  \normalsize 
The third letter, if present, affects the archive flag associated with the file
and may be:

\small\tt \begin{verbatim}          A : Archive (i.e. back this file up regularly)
       or V : Vulnerable (do not back this file up).
\end{verbatim}\rm  \normalsize 
\subsection{PASS \hspace{0.3 in} Change password}
\small\tt \begin{verbatim}           PASS
\end{verbatim}\rm  \normalsize 
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.

\subsection{PAMSET Set command separators}
\small\tt \begin{verbatim}             eg      PAMSET
                     GroupSeparator then Keyflag:|\
\end{verbatim}\rm  \normalsize 
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:

\small\tt \begin{verbatim}      Group separator: oblique stroke ('/')
      Keyword flag   : dash           ('-')
\end{verbatim}\rm  \normalsize 
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.
See also HELP PAM.

\subsection{HELP \hspace{0.3 in} Obtain help}
\small\tt \begin{verbatim}          HELP <topic>             eg  }HELP USERS  or just  }HELP
\end{verbatim}\rm  \normalsize 
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 displays a list of topics and invites the user to
select one. Typing $<$carriage-return$>$ gives the user general information about
the APM and its 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. HELP HELP provides
more detailed information about the HELP facility.

\subsection{USERS \hspace{0.2 in} List users}

The command USERS provides a list of the users currently logged on to the
same Filestore as the calling user.

\subsection{COMPARE Compare two files}
\small\tt \begin{verbatim}          COMPARE <file1>,<file2>/<diff>   eg  }COMPARE TEST1,TEST2
\end{verbatim}\rm  \normalsize 
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.

\subsection{VAX \hspace{0.3 in} Log on to VAX}
\small\tt \begin{verbatim}          VAX
\end{verbatim}\rm  \normalsize 
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).

\subsection{ASS \hspace{0.3 in} Assemble program}
\small\tt \begin{verbatim}          ASS <file> <options>
\end{verbatim}\rm  \normalsize 
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).

\subsection{IMP \hspace{0.3 in} Compile Imp program}
\small\tt \begin{verbatim}          IMP <file> <options>
\end{verbatim}\rm  \normalsize 
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:

\small\tt \begin{verbatim}     -LIST        Produce a listing to file with same name as source
                  and extension .LIS
     -NODIAG      Suppress line-number diagnostic
     -NOCHECK     Suppress run-time checks
\end{verbatim}\rm  \normalsize 
HELP IMP gives further information.


\subsection{C:CC \hspace{0.3 in} Compile C program}
\small\tt \begin{verbatim}          C:CC <filename> [<pre-processor flags>]
\end{verbatim}\rm  \normalsize 
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.

HELP C gives further information.

\subsection{CR \hspace{0.4 in} Run C program}
\small\tt \begin{verbatim}          CR <C-command-line>
\end{verbatim}\rm  \normalsize 
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.

HELP C gives further information.

\subsection{SR \hspace{0.4 in} Run S-Algol program}
\small\tt \begin{verbatim}          SR <SA-command-line>
\end{verbatim}\rm  \normalsize 
The command SETUP SA sets up the definitions required by S-Algol.

The SR command then invokes the APM interpreter for the S-Algol language as
described by Cole and Morrison. It takes no parameters.

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

The command SR
\\ \hspace*{0.8 in} SA:SC $<$file$>$ invokes the S-Algol interpreter to load and interpret
the S-Algol compiler.

A strictly limited amount of support for S-Algol is offered by Fred King, who
should be consulted for further information.


\section{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.

\section{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 one of the Filestores.

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.

The bootstrap sequence may be interrupted in order to bootstrap from alternative
Filestores or files. To do this, hit any key while the first couple of lines
are being printed by the bootstrap. You will then be prompted for a Filestore
address, to which you reply with $<$space$>$ for the normal default or the hex
address of the required Filestore. \hspace{0.2 in} You will then be prompted for a bootstrap
file. Respond $<$space$>$ for the standard one or with the filename of the required
bootstrap file. \hspace{0.3 in} See HELP NEW O/S for details of how to use this mechanism to
bootstrap the new (multi-process) operating system.

\section{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:

\small\tt \begin{verbatim}              COMPARE  OLDFILE , NEWFILE  / DUMPFILE
              T  TESTPROG / CURRPROG
\end{verbatim}\rm  \normalsize 
\subsection{Command verbs}
The interpretation of a command verb proceeds along the following lines:

 If the word is preceded by an at-sign ('@'), a file with the name
 given and extension .COM is searched for and the commands in that
 file are obeyed;

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

 Otherwise a file with the same name as the command verb and
 extension MOB is searched for, and the program in that file
 is executed.
 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 system directory FMAC
 and failing that, in the current default directory.
 If no such file can be found, an error report is made.


\subsection{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.


\subsubsection{Examples}

\hspace*{0.9 in} 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.

\hspace*{0.9 in} 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.

\hspace*{0.9 in} 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.


\hspace*{0.9 in} 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).

\hspace*{0.9 in} 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.

\subsubsection{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.

\subsubsection{File-names}
File-names denote files held on a remote file server; file naming conventions
are those imposed by the file server - except that in certain contexts a
server prefix is accepted, to select a particular server. Server prefixes
take the form ::$<$server$>$: (or alternatively $<$server$>$::).

The naming conventions for the current file servers are as follows.
A full 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.


\subsubsection{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.


\subsection{Executable files}
Executable files are either object files or command files.
Object files have file-name extension .MOB (for Motorola object) and
command files have extension .COM.

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 each command should be introduced by a
left curly bracket, to distinguish commands from data.
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.

\subsection{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:

\hspace*{1.1 in} $<$newname$>$ = $<$oldname$>$

For example:

\hspace*{1.1 in} GO = UTIL:TESTPROG1

It is possible to include preferred default options in symbol definitions
for example:

\hspace*{1.1 in} OPT = PASCAL-NOCHECK-NODIAG-NOSTACK

A symbol may also be introduced to avoid having to type the at-sign to
indicate a command file rather than an object file, for example:

\hspace*{1.1 in} SETALL = @SETALL

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

\subsection{Parameter Aquisition - PAM}
PAM is a set of procedures which may be called by programs to acquire parameters

The module is available for IMP and Pascal programs on APM and VAX/VMS.

The relevant specifications are in the file INC:UTIL.IMP (for IMP)
or INC:UTIL.PAS (for Pascal).

Further information is available via HELP LIB

See also HELP PAMSET.



\section{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 $\hat{ }${}I.

\subsection{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.

\subsection{Terminal Control Characters}
\small\tt \begin{verbatim}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.

^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).
\end{verbatim}\rm  \normalsize 

\section{DEMONSTRATION PROGRAMS}
A number of demonstration programs are available in the directory ADEMO.
A menu is presented when you log on to this directory (null password).

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

Many of the programs run continuously until abandoned by $\hat{ }${}Y.


\section{LOW-LEVEL OPERATIONS}
\subsection{BOOT \hspace{0.3 in} Load New System}
\small\tt \begin{verbatim}          BOOT <file>
\end{verbatim}\rm  \normalsize 
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. Note that $<$file$>$ must be the complete filename,
including directory name and extension (if present).

\subsection{TOBIN \hspace{0.2 in} Convert to Binary}
\small\tt \begin{verbatim}          TOBIN <infile>/<outfile>
\end{verbatim}\rm  \normalsize 
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.

\subsection{HEX \hspace{0.3 in} Convert to hex}
\small\tt \begin{verbatim}          HEX! <in>/<out>
\end{verbatim}\rm  \normalsize 
The stream (usually a file) $<$in$>$ is output to $<$out$>$ one byte at a time, in
hexadecimal.

\subsection{DISASS Dis-asssemble machine-code}
\small\tt \begin{verbatim}          DISASS <codefile> / <listing>
\end{verbatim}\rm  \normalsize 
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.
If no parameters are specified, the program prompts for store addresses.

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.

The following options may be specified:

\small\tt \begin{verbatim}     -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
\end{verbatim}\rm  \normalsize 

\section{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.

\subsection{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
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.

\subsection{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.


\subsection{MOB files}
The first character in a MOB file must be the object module character 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 been REMEMBERed) this contiguous area of free store
will be adjacent to the area into which the code was loaded.

\subsection{System routines}
Basic 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. Some preserve working registers not used as parameters; others do not.
Strings are held as length-prefixed sequences, and are always passed by address
-- of the first (length) byte.



\section{THE SOFTWARE FRONT PANEL}

This debugging tool is invoked by appending the flag-character '?' to a command
verb, or by pressing $\hat{ }${}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.


\small\tt \begin{verbatim}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{verbatim}\rm  \normalsize 
\vspace{.75in} view:apm printed on 17/02/89 at 10.03

\newpage
\tableofcontents
\end{document}