@Section(OVERVIEW)
The main objective of this first chapter is to provide general information
on the APM.  The following will be discribed here:
@Begin(Itemize)
The network. (See section @Ref(Network1)) 

Communicating with the system (load the system, reboot it, logging on or off,
ect,...).  (See section @Ref(LogOn1))

The main characteristics of the APM command language. (See section
@Ref(ComLanguage1))

The terminal.  (See section @Ref(Terminal1))

The software environment (in brief).  (See section @Ref(Soft1))

The control processor board and memory board.  (See sections @Ref(Control1)
and @Ref(Memory1))

All APM commands. (See section @Ref(Command1))
@End(Itemize)
The users that would only be interested in file editing, copying, transfering
files from one filestore to the other,...  will find the useful information in
the section @Ref(Command1) of this Chapter.  Text processing with ECCE, IE is
also discribed in chapter @ref(Editors).

@NewPage
@Section(THE NETWORK)@Label(Network1)

The Department has an ether-like local area network, which has
about 40 Advanced Personal Machines (APM's) and a number of filestore
attached.  There are two principal public filestore, referred to as
BRAVO and CHARLIE.  Users are normally accredited to only one of these,
and either of the workstations can be used with any of them.
@Begin(FileExample)
@B(Name         Hex Address)

BRAVO            15         This is mainly used by staff
                            and postgraduate students.

CHARLIE          1B         This is mainly used by MSc 
                            students and undergraduates.
@End(FileExample)
@Index(BRAVO)
@Index(CHARLIE)
@IndexSecondary(Primary="FileStores", Secondary="BRAVO")
@IndexSecondary(Primary="FileStores", Secondary="CHARLIE")

The workstations are modular computer systems based at present on the
Motorola 68000.  There are many different hardware configurations
possible, and some of these are described below.  Most software will run
on any of the systems unless it has any specific hardware requirements
(eg. Graphics).
@Begin(FileExample)

Basic system :      Motorola 68000, 2 Mb of memory, 
                    ether interface, Visual 200 
                    terminal.

Level 1 graphics:   Basic system, 4 plane frame-store, 
                    mouse interface,  Colour monitor.  
                    (Most systems have 1Mb of memory.)

Level 1.5 graphics: Basic system, 8 plane frame-store, 
                    mouse interface, Colour monitor, 
                    >= 1Mb of memory.

Level 2 graphics:   Basic system, bus arbiter, graphics 
                    processor, mouse interface, n frame-
                    store boards, Colour monitor.
@End(FileExample)

All of the public workstations are currently situated in the
machine halls.
 
@NewPage 
@Section(COMMUNICATING WITH THE SYSTEM)@Label(LogOn1)

  
@SubSection(Logging on)@Index(Log On)

Switch on the Visual 200 terminal (switch on the right hand side), and 
colour monitor (switch below the screen at the front) if one is present.

To load the system turn the Key switch on the front right of the APM cabinet.
The machine will now boot from the default filestore (Charlie).
As the machine boots various messages giving the versions of the system
components, and files being loaded are printed on the console.
 
@Index(Load the System)
@IndexSecondary(Primary="System", Secondary="Load")
 
If you wish to re-boot the system while it is running, you can press Ctrl+T,
followed by 'R' for Re-boot.  If the terminal does not respond, the machine
can be re-booted by pressing the reset switch on the processor board (the
one with two lights and a ribbon cable) which is inside the cabinet.
The memory boards have similar-looking switches and should not be confused
with the control processor board.  
@Index(Bootstrap) 

The bootstrap sequence may be interrupted in order to bootstrap from 
lternative 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.  You will then be prompted for a 
bootstrap file.  Respond <space> for the standard one or with the filename of
the required bootstrap file. 


When the machine finishes booting the cursor should be positioned to the
right of a curly bracket, which is the command prompt ('}').  The form of the
login command is

@Begin(FileExample)
 L Username     or     L Filestore::Username 
 password              password               
@End(FileExample)

 If the form on the left is used, the system will attempt to log you onto
 the same filestore as was used by the previous person (or the one it booted
 from if it has just been booted).  If the message 'No Authority' appears you
 have mis-typed the username or password.  If the message 'Owner XXX: not found'
 occurs then you may be trying to use the wrong filestore, and the form on the
 right should be used.

 Once you have logged on successfully, any system alert messages are printed,
 and your file LOGIN.COM (see section @Ref(LOGIN)), if you have one, will be obeyed.
 
@Paragraph(On your first log on)

Users are normally accredited with a null password.  If the user FG has just 
been accredited to filestore C, the following is a typical dialogue required to
"personalise" their number.

@Begin(FileExample) 
} L C::FG                                                         
  Pass:                          { Press return              
  You are using Filestore C [1b] { Welcome message and 
                                 { alerts 

} PASS                          { Set a non-null password     
  Current password:             { Press return                 
  New password: DALE            { The password (DALE) is 
                                { not echoed
  Confirm: DALE                 { You have to type your 
                                { password again otherwise 
                                { there will be no change
@Index(Password)
@IndexSecondary(Primary="Password", Secondary="Change")
@End(FileExample)

 
@SubSection(Logging off)@Index(Log Off)
 
The L command always logs you off before logging you on.  If you just want
to log off, the L command without a username parameter should be used.

@NewPage
@Section(COMMAND LANGUAGE)@Label(ComLanguage1)
@Index(Command)
@IndexSecondary(Primary="Command Language", Secondary="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).
 
The interpretation of a command verb proceeds along the following lines:

@Begin(Itemize)

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, 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.
@End(Itemize)
 
@SubSection(Parameters)
@IndexSecondary(Primary="Command Language", Secondary="Parameter")
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 will be illustrated in Section @Ref(Examples1).

@Paragraph(Devices)
@Index(Device)
 
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 
@Index(:T)
@IndexSecondary(Primary="Device", Secondary=":T")
by itself).  Also reckoned as a device is the null data stream (denoted by :N),
@Index(:N)
@IndexSecondary(Primary="Device", Secondary=":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.
 
 
@Paragraph(File-names)
@IndexSecondary(Primary="File", Secondary="FileName")
 
File-names denote files held on a remote filestore; file naming conventions
are those imposed by the filestore - except that in certain contexts a
server prefix is accepted, to select a particular filestore. FileStore prefixes
take the form ::<FileStore>: (or alternatively <FileStore>::).

The naming conventions for the current filestores 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 (letters, digits, dots, underlines and or dollars).  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.
@Index(File)
@IndexSecondary(Primary="File", Secondary="Temporary")
@SubSection(Punctuation)
 
General conventions governing the format of most commands are as follows

@Begin(Enumerate)
@IndexSecondary(Primary="Command Language", Secondary="Group Separator")
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 ('/');

Within a group of either input or output stream-names the separator is a
comma;

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;

The complete command is terminated by RETURN;

Spaces are optional before and after the punctuation symbols mentioned
above, except that the keyword flag character must be followed immediately by
the keyword. 

@End(Enumerate)
 
@SubSection(Flag Characters)
@IndexSecondary(Primary="Command Language", Secondary="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(Executable files)@Label(ExFile1)
 
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.

@IndexSecondary(primary="File", secondary="Command File")
@IndexSecondary(primary="File", secondary="Object File")
@IndexSecondary(primary="File", secondary="Executable File")
@Index(.MOB) @Index(.COM)

@b[Object files]

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

@b[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 i.e. any command line following the invocation of a command file will be
ignored.

@Label(LOGIN)
One of the useful command file you might want to include in your directory is
a LOGIN.COM file.  Any time that you will log on to the filestore, all the
commands in your LOGIN.COM file will automatically be executed.  The following
is a possible example of a LOGIN.COM file:
@Begin(FileExample)
become=set
heure=tod
h=help
f=files-alpha
lise=set ld
@End(FileExample)

 
@SubSection(Symbol Dictionary)
@Index(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:
@Begin(FileExample)
<newname> = <oldname>
@End(FileExample)
@Begin(FileExample, LeftMargin +0, Group)
For example:

    GO = UTIL:TESTPROG1
@End(FileExample)

It is possible to include preferred default options in symbol definitions
for example:
@example(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:
@example(SETALL = @@SETALL)

@SubSection(Examples)@Label(Examples1)

@b[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[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[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.

@b[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[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.
 
@NewPage
@Section(THE VIDEO TERMINAL)@Label(Terminal1)
@SeeAlso(Primary="Terminal",Other="VDU")
@Index(VDU)

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.


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) 
@Begin(Description)
@Index(DEL)@IndexSecondary(Primary="VDU", Secondary="DEL")
DEL
@\Erase the last extant character typed on the current line.

@IndexSecondary(Primary="VDU", Secondary="BS")@Index(BS)
@IndexSecondary(Primary="VDU", Secondary="^B")@Index(^X)
BS or ^X 
@\Erase all characters typed on the current line.

@IndexSecondary(Primary="VDU", Secondary="RETURN")@Index(RETURN)
RETURN
@\Terminate the current line.   

@IndexSecondary(Primary="VDU", Secondary="^S")@Index(^S)
^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'.

@IndexSecondary(Primary="VDU", Secondary="^Q")@Index(^Q)
^Q
@\Quit auto-freeze mode.  

@IndexSecondary(Primary="VDU", Secondary="^Y")@Index(^Y)
^Y
@\Abandon the current activity, and return to command level. 

@IndexSecondary(Primary="VDU", Secondary="^Z")@Index(^Z)
^Z
@\Terminate input from the terminal, creating an 'end of file' 
condition.

@IndexSecondary(Primary="VDU", Secondary="^P")@Index(^P)
^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.

@IndexSecondary(Primary="VDU", Secondary="^T")@Index(^T)
^T
@\Escape to trace-mode (See Software Front Panel).
@End(Description) 


@NewPage 
@Section(SOFTWARE ENVIRONMENT)@Label(Soft1)

 
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.

@SubSection(Initial System Loading)
 
@IndexSecondary(Primary="System", Secondary="Load")
After the system has been reset, 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 CLI.  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)

@Index(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.

@IndexSecondary(Primary="File", Secondary="MOB") 
@Paragraph(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.
 
@IndexSecondary(Primary="System", Secondary="Routines")
@Paragraph(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).

@b(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.