@V7 54 2 -5
@L5 HIUK1047
0
85  85  85  85  85  85  85  85
85  85  85  85  85  85  85  85
85  85  85  85  85  85  85  85
85  85  85  85  85  85  85  85
85  58  78  85  85  127 90  60
85  85  90  85  85  85  85  85
85  85  85  85  85  85  85  85
85  85  85  85  85  85  85  85
100 91  99  107 109 93  90  109
111 50  82  93  78  127 112 109
90  109 100 89  90  115 95  127
86  83  87  55  72  55  80  91
60  84  87  82  87  84  50  87
83  46  46  74  46  125 83  85
87  87  61  76  45  83  65  100
63  65  65  55  50  55  85  127
@L3 COUK1247
80
@V9 0
@YCHAPTER 5 - MUSS USER MANUAL
@G@RCHAPTER 5 - FILES AND EDITING@G
@V10 1 9 54
@T% 10
@S25.1 GENERAL DESCRIPTION OF THE FILE SYSTEM
@T% 10
@BThe file system provides users with the means of retaining
information inside the system, and of accessing and altering this
information from within jobs.  Often, though not always, the files
are created by programs or system commands, using the input/output
facilities described in Chapters 3 and 4.
@BInitially each user of the system has a file directory, which lists the
files currently owned,
however, it is possible to create a hierarchy of directories, which
have a tree structure with the users original directory as the root.
As described in Section 2.4.1 the name of a directory or file is specified
to the system as a pathname and the terms @5filename@0, @5local@0 @5filename@0,
@5directory@0 @5name@0 and @5local@0 @5directory@0 @5name@0 were defined.
A single file may contain up to 256 K bytes of
information, but individual users are restricted both in the
number of files they may own and in the total amount of space
their files may occupy.  If a user exceeds either of these limits,
further attempts to access the files will be prevented until the
usage is brought back within the allocated limits - either by
deleting files or by increasing the user's allocation.
@BA user does not normally need to be aware of the exact location
of his files, as this is managed automatically by the system.
There is one aspect of this, however, which may concern the user.
The file system can extend across up to three levels of storage, and
files are automatically transferred by the system between the
three levels as necessary.  Files which are currently in use or have
recently been accessed reside in the @5local@0 filestore.  Files
which have not been used for some time may be automatically
offloaded to a large capacity file buffer, from which they may be
further removed to archive storage on removable storage media
(e.g. magnetic tapes).  The user need not be aware of this
movement, since files will be automatically retrieved into the
local filestore when they are accessed, but retrieving a file
from the archives may involve an appreciable delay.  Also,
commands are provided for the user explicitly to request file
offloading and onloading, for security reasons.
This mechanism is only provided on machines with a
suitable configuration.
@S25.2 SHARING FILES
@BA notation has been mentioned in 2.4.1 whereby users can
reference the files of other users.  This depends upon two mechanisms.
First, the users are organised in hierarchy which starts from the user
SYSTEM.  Any user may access the files of a subuser without the need for
special permission.
The second mechanism allows more selective sharing of files
across the hierarchy of users.
Any user may permit others selectively to share his files by
calling on the PERMIT command,
giving the access permission granted to
each user.
@S35.2.1 Network File Systems
      (not applicable to stand alone systems)
@BEach machine in the MUSS network has its own
independent file system.  However, the file commands are such
that users are able to open directories and retrieve copies
of files from other machines.  This involves passing messages
between the different file systems.  To specify the
necessary information about the required directory in another
machine, a command NAME.DIR is provided.  This
assigns a pseudo user name for the required directory,
which may subsequently be used as the user name parameter of file commands
to access the remote files.
@BIt is essential that users have been granted the
necessary permission to access the files in the
remote machines.
@S25.3 FILE SYSTEM COMMANDS
@BIn the following file system commands, whenever the user
whose file store is to be accessed is @5not@0 specified, the
local file/directory name will be assumed to be relative to the
currently selected directory of the current user.
@
@
1) @JOPEN.DIR([C])
@BThis command allows a user to select a subdirectory to be
used instead of his main directory, as the starting point of paths
in subsequent @5local@0 @5filenames@0 and @5local@0 @5directory@0 @5names@0.
The effect is the same as if the selected directory was the root directory,
except for path names which begin with '/' which always take the
user's main directory as their root.
P1 is the @5local@0 @5directory@0 @5name@0 of the required directory.
If P1 is the null string the main directory of the user is restored as the root.
@
@
2) @JOPEN.FILE([C],II,I,I)
@BThis command opens a file with the @5local@0 @5filename@0 P1 into the virtual
store of the
current process.  P2 is the username of the file's owner, with a
default of zero implying the current user.  P3 and P4
specify a segment and access permission for the file.  If the segment
number is negative, a free one will be allocated by the system.
The access permission is formed from the five segment
access bits (see Chapter 13) combined with the next most
significant bit, which if set indicates that exclusive access is required.  Any
access permission is allowed for files in the current directory, but
for files borrowed via the PERMIT facility, the calling process will
be faulted if the specified access exceeds that stated in the PERMIT
file.  PW1 returns the number of the segment holding the file, and
PW2 and PW3 the size and status of the segments respectively.@
@
@
3) @JFILE([C],II,I)
@BThis command preserves a segment (P3) as a file with @5local@0 @5filename@0 P1
.  P2 is
the name of the user who is to own the file, with a zero
default implying the current user.  The segment remains in the
process' virtual store after a file operation.@
@
@
4) @JDELETE.FILE([C],II)
@BThis command deletes the file with @5local@0 @5filename@0 P1 belonging to user
  P2.
P2 may be zero implying current user.@
@
@
5) @JRENAME.FILE([C],II,[C])
@BThis command is used to rename the file with @5local@0 @5filename@0 P1 belongi
ng to user P2.
P2 may be zero implying current user.  P3
gives the new file name
which must be a simple name not including ':' or '/'.@
@
@
6) @JSECURE.FILE([C],II)
@BThis command causes the named file to be copied to the offload
buffer, thus creating a secure copy of it.  The local copy of the
file is retained.  P1 is a @5local file name@0 and P2 the user
name.  Update permission is required to secure a file in another
user's directory.@
@
@
7) @JBACKUP.FILE([C],II)
@BThis command deletes the local copy of a file, so that on next
accessing the file, the most recently offloaded copy (if any) will
be obtained.  This may be the version last copied using the
SECURE.FILE command, or it may be a later version which has been
offloaded automatically by the system.  P1 is a @5local file name@0
and P2 the user name.  Update permission is required to back up a
file in another user's directory.@
@
@
8) @JCATALOGUE.FILES([C],II)
@BThis command creates a copy of the directory, specified by
the local directory name P1, in a newly created segment.  PW3
returns the segment number.  P2 is the user name of the directory
owner, with a zero default implying the current user.
@BIf P2 is zero or specifies the current user a list of
@5all subdirectories and files@0, held in the directory P1, is
returned, otherwise @5only files@0 permitted to current user (via
permit command) are returned.
Each entry in the segment is 40 bytes long and may take one of
two forms:@
@
@Q 8
@
@T% 35
@OSubdirectory Entry@O%@OFile Entry@O@
@
Dir Name (16 bytes)%File Name (16 bytes)@
Size in pages (32 bits)%Status (32 bits)@
Create time in seconds (32 bits)%Size in bytes (32 bits)@
Disc address (32 bits)%Update time in seconds (32 bits)@
%Create time in seconds (32 bits)@
%Disc address (32 bits)@
@BPW1 returns the number of subdirectory entries which occupy the
first PW1 entries of the segment.
@BPW2 returns the number of file entries which follow the subdirectory
entries.
@BPW4 holds the maximum number of files and PW6 gives the
maximum amount of file store allowed to the user.
@BPW5 returns the amount of file store used (in blocks) in
directory P1.
@BTotal number of files currently owned by the user and the total
file store used (in blocks) are returned in PWW1 and PWW2 respectively.
@
@
@
9) @JREAD.FILE.STATUS([C],II)
@BThis command reads the directory information associated with the
@5local@0 @5filename@0 P1 in the directory of user P2.  PW1 returns the status i
nformation in
the form:@
@3
@U 8
@
      @O                        @O
      @O|      |   |   |   |   |@O
               |   |   |   |
               |   |   |    ----- local copy exists
               |   |    ------offloaded copy exists
               |    ----- file open
                ----- file open with exclusive access
@0
@BPWW1 holds the size of the file in bytes, and PWW2 and PWW3 return the
update time and the
create time (in seconds) respectively.@
@
@
10) @JPERMIT([C],II,II,II)
@BThis command may be called by a user to
assign a set of access rights to one of his files for another user.
P1 specifies the @5local@0 @5filename@0 and P2 the name of the
user to be granted permission.  The option "ALL"
is available for both parameters, to allow a user
access to all the files in a directory, or allow
all users access to a file.
@BThe third parameter gives the permissions assigned,
and is specified as a combination of the letters:@
@T% 10 20
@Q 9
@
%X%meaning permission to open with execute access@
%W%meaning permission to open with write access@
%R%meaning permission to open with read access@
%E%meaning permission to open with exclusive access@
%C%meaning permission to change access when open@
%U%meaning permission to update the file@
%D%meaning permission to delete the file@
%N%meaning permission to rename the file.@
@
@
The letters may appear in any order.
@BTo remove access permission rights, the PERMIT
command should be called with P3 zero.
@BIf P4 is non-zero it should be a name previously
defined by a NAME.DIR command.  In that case the PERMIT
command will be handled by the appropriate file manager process.
@
@
@
11) @JCATALOGUE.PERMIT([C],II)
@BThis command creates a copy of the permissions
associated with the
directory specified by the @5local directory name@0 P1.
P2 is the user name of the directory owner,
with a zero default implying the current user.
If P2 is zero or specifies the current user a copy of
@5all@0 permissions associated with the directory P1 is
returned, otherwise only those permissions granted to the
current user are returned.
A segment is created for this purpose, and the
segment number is returned in PW2.  The permission entries are
of the form:@
@T% 10 20
@Q 5
@
%FILENAME%(16 bytes)@
%USERNAME%(8 bytes)@
%ACCESS%(1 byte)@
@
@
The access is bit significant, and has the format@
@3
@U 12
@
               @O                        @O
               @O|      | | | | | | | | |@O
                       | | | | | | | |
                       | | | | | | |  -- X
                       | | | | | |  ---- W
                       | | | | |  ------ R
                       | | | |  -------- E
                       | | |  ---------- C
                       | |  ------------ U
                       |  -------------- D
                        ---------------- N
@0
@
@
The number of entries in the segment is returned in PW1.@
@
@
12) @JNAME.DIR(II,II,II,[C])
@BThis command allows the normal file commands
to apply to other file systems controlled by file manager processes.  It
introduces the name P1 which may subsequently
be used instead of a user name in other file commands, and in @5filenames@0
and @5directory@0 @5names@0.
P2 names the file manager process required, and P3 names the
machine on which it runs.  If P2 is zero the default name "FILMAN" will be used.
  P4 is a string containing additional
information required by the particular file manager.  Examples
can be found in Section 5.3.1 below.
@
@
@
13) @JRELEASE.DIR.NAME(II)
@BThis command cancels the effects of a previous NAME.DIR command.
P1 is a user name introduced by a NAME.DIR command.  After this
procedure is called this user name will no longer be recognised
as a reference to a file manager process.  Also a message will be
sent to the file manager process informing it that any resources
reserved by the NAME.DIR command can now be released.
@
@
@
14) @JCREATE.SUBDIR([C])
@BThis command creates a new subdirectory, with local directory name P1, within
the current directory.  It becomes part of the current tree of directories.
P1 must be a simple name not including ':' and '/'.
@
@
@
15) @JDELETE.SUBDIR([C])
@BThis command deletes an empty subdirectory of the current directory.
P1 is the local directory name of the subdirectory.  P1 must be
a simple name not including
':' and '/'.
@
@
@
16) @JCREATE.FILE.SEGMENT(I,I,[C],II)
@BThis command is equivalent in effect to the CREATE.SEGMENT command
described in Chapter 13.  It is used when a segment is created with the
intention of later filing it away as a particular named file.  By
giving the filename and username information at the point of creation
the system can optimise the allocation of resources to the segment.
The parameters P3 and P4 give the local filename and username of the
eventual file.  The parameters P1 and P2 and the result returned in PW
variables are exactly as described for CREATE.SEGMENT.
@
@
@
17) @JCREATE.FILE.X.SEGMENT(I,[C],II)
@BThis is identical to CREATE.FILE.SEGMENT except that the
command is equivalent to CREATE.X.SEGMENT not CREATE.SEGMENT.
@
@
@
18) @JCHANGE.ROOT.DIR(II,II)
@BThis procedure changes the main root directory is that of another
user.  P1 and P2 are the username and password of the new user.
After using this procedure all file operations will work as if the
current process was that of the new user.
@
@
@
19) @JCHANGE.FILE.SIZE([C],II,I)
@BThis procedure changes the size of a file.  P1 is the @5local filename@0
and P2 the user.  P3 is the required file size in pages.  The file must be
open when this command is used.  In changing the size the procedure may
convert the file into an X-segment.
@S35.3.1 File Manager Processes
@BAs mentioned in the description of NAME.DIR above, the
services provided by file manager processes can
be utilised through normal file commands.  Certain such processes
are commonly present in MUSS systems, and these are described
below.
The descriptions give the process name (P2 of NAME.DIR)
and then explain the use of the initial information (P4 of NAME.DIR).
@
@
@
1) @JFILMAN
@BThis process provides access to the standard file store
for other machines in the network.
It also allows additional flexibility in accessing files in the
same machine.  The information needed to access a file should be
passed in a string of form:-
@
@
@M(username/password)file name.
@BThis string can be arbitrarily split between the initial
information passed by NAME.DIR and the file name parameter of
subsequent file commands.
@BThe username and password should be valid ones for the machine
on which the FILMAN process is running.
@BThe "file name" is a full @5file name@0 optionally
containing another user name. If this second user name is present
access to files will be determined by the permissions granted to
the user identified by the "(username/password)".
@
@
@
2) @JFLOPPY
@BThis process is used to handle files on low capacity, easily
exchangeable media such as floppy discs.  The file store structure
is kept simple, with no division into users or directories.
Apart from this restriction all the normal file commands are
useable.  The initial information needs to identify the disc
and ensure that the user has access to it.  It is in the form:-@
@
@M[discname/password].
@BThe discname and password are the volume name and label,
as described in Chapter 17.
@BIf the discname is prefixed with "CLEAR:" it will
have its file store data structure initialised.
@BThe filenames used in the file operations with this file manager
should be a single name not a path name.
@
@
@
3) @JFILMAN10
@BThis process provides a limited set of file operations on
exchangeable discs with a file structure used in earlier issues
of MUSS.  Only the operations OPEN.FILE, CATALOGUE.FILES,
CATALOGUE.PERMITS and READ.FILE.STATUS are available.  The
initial information is in the form:-@
@
@M[discname](username/password)secondary user name.
@BThe discname identifies the exchangeable disc required.
@BThe username and password identify a user on the required disc.
@BThe secondary username is optional and is used when access is
required to the files of that user using permissions granted to
the first user identified.
@BFilenames in file operations using this file manager should be
single names with a maximum of eight characters.
@
@
@
4) @JEDMAN
@BThis process provides access to exchangeable discs with the
same file store structure as the system disc.
@S25.4 FILE EDITING
@BTwo editors are normally available in MUSS, a line editor
with limited screen editing capability and a full screen editor.
On some small machines the latter may not be available.
@S35.4.1 General Description of the Editor
@BThe editor is a program which enables users to make alterations
to files of text.  It is invoked by the command@
@
@
@T% 50
1) @J@OED@OIT([C],[C],I)
@BThe first two parameters of this command are filenames (or, more
accurately, document names - see Chapter 3).  The first is the input
file, and the second the output file, and the action of the editor
is to make an altered copy of the input file on the output file.
The two filenames may be the same, in which case the input file is
overwritten at the end of the edit by the output.  In general, the
two names may take any of the forms described for input and
output documents in Chapter 3, except that unbuffered (online)
documents may not be used.
@BThe third parameter is only relevant if the screen
editing command VIEW is to be used.  It specifies the type of terminal.
A value of zero always indicates a terminal which responds to the
ANSI standard sequences for cursor movement and line clearing.
The significance of other values is installation dependent.
@BThe use of the editor can be defined in terms of three operations,
namely@
@Q 6
@T% 30
@
1. @5Copying@0@Iinformation unchanged from the input file
output file.@
2. @5Skipping@0@Iover information in the input file, without
copying to the output file.@
3. @5Inserting@0@Inew information into the output file.@
@
It provides a variety
of commands for copying, skipping and inserting, allowing different
ways of specifying exactly what is to be copied, skipped or
inserted.
@S35.4.1.1 Online Operation
@BWhen the edit commands are from an online stream, the
editor is said to be in @5online mode@0.  In this mode, fault messages
and other monitoring will normally be returned to the online
console.  In the event of a fault the editor prints a fault message
and then ignores any further commands on the same line.  If the
command in which the fault occurred was an editing command (S, C, A,
B, D) then the input and output pointers are restored to their
values at the start of the command.
@S35.4.1.2 Offline Operation
@BIn offline mode, as soon as a fault occurs the editor returns
control to the calling program with the status word (PWO) set to -1.
This will normally have the effect of terminating the job.
No further editing commands are read, since there is a high
probability of interpreting inserted data etc. as commands.
@S35.4.1.3 Commands and Parameters
@BOperation of the editor is controlled by means of a sequence of
commands on the command input stream.  Each command is identified by
a single letter, which may be followed by a parameter.  Any number
of commands may be placed on a line; blank lines and spaces
occurring between commands are ignored.  Edit commands are accepted
in upper or lower case.
@BMost parameters are straightforward (e.g., an integer) and
require no special explanation.  However, a number of commands have
as their parameter a string.  A string is simply a sequence of
characters between a pair of string delimiters.  Any single
non-alphanumeric character which does not appear in the
sequence of characters may be used as a string delimiter.  Thus, any
of the following are legal strings:-@
@U 8
@
@
               'ABC DEF'
               /'BEGIN'/
               $'BEGIN'
                  'INTEGER' I, J, K;
               I := 1/2;
               $
@BSometimes it may be necessary to include as part of a string a
character which cannot be typed on the input device, (for example a
newpage character).  This may be achieved by typing the code for the
required character as two hexadecimal digits enclosed between two
string delimiters.  Thus, for example using the ISO character
codes:-@
@T% 10
@V2 10
@Q 9
@
@
1.@I!'BEGIN'!09!'INTEGER' I,J,;! means 'BEGIN' followed
by a tab followed by 'INTEGER' I,J;,@
@
2.@I!!OC!TITLE! represents a newpage character
followed by TITLE.@
@
3.@I//OA//OA// represents two consecutive newline symbols.
@V2 0
@B@GNote@G that this will only work for characters with codes in the
range 00 - 9F.  Certain characters are required so frequently that a
special representation exists within strings for them.  This
consists of a single letter enclosed between a pair of string
delimiters.  The characters for which a special representation
exists are:-@
@Q 5
@T% 10 30
@
@
%Newpage%(P)  e.g.,  //P/TITLES/@
@
%Newline%(L)  e.g.,  //L//L//@
@
@
N.B.  Users should be very careful in using the hexadecimal
representations, particularly in insertions, as it is possible to
introduce non-standard non-printing characters into the output file.
Also there may be unexpected effects when using line-editing
commands (see later).
@S35.4.1.4 Brief Summary of Available Commands
@BA brief description of the available commands is given below.
They will then be described individually in greater detail.  There
are 9 commands altogether, and they are grouped for ease of
description into 3 categories.  Commands from all 3 categories may,
however, be freely interspersed.@
@V2 10
@
@Q 6
@
A. Line-editing Commands@
@
1.@IS (SKIP) Skips to the start of a specified line.@
2.@IC (COPY) Copies to the start of a specified line.@
3.@II (INSERT) Inserts a string into the output stream.@
@
@Q 11
B. Context-editing Commands@
@
1.@IB (BEFORE) Copies up to the start of the next
occurrence of a specified string.@
2. @IA (AFTER) Copies up to the end of the next
occurrence of a specified string.@
3.@ID (DELETE) Copies up to the start of the next
occurrence of a specified string, then skips
to the end of the string (thus deleting it).@
4.@II (INSERT) Inserts a string into the output stream
(exactly as for line-editing).@
@
@Q 13
C. Other Commands@
@
1.@IW (WINDOW) Causes a section of the file being edited
to be listed on the monitor stream.@
2.@IR (RESTORE) Causes the input and output pointers
to be restored to the values they had before
the previous line or context editing command.@
3.@IE (EXIT) Copies all remaining characters from
the input stream to the output stream, and returns
control from the editor.@
4.@IM (MERGE) Alters the editors input file.@
5.@IQ (QUIT) Abandons the edit and returns from the
editor without updating the output file.@
6.@IV (VIEW)  This gives a simple screen edit facility
to text at the current position, as described in 5.4.1.7.
@V2 0
@S35.4.1.5 Line Editing Commands (S, C, I)
@BThese commands are used when whole lines are to be deleted,
inserted or replaced.  The two positioning commands (SKIP, COPY)
always position the input pointer INP at the start of some specified
line.  As explained in Section 1, SKIP merely advances the input
pointer without copying any information to the output stream.  COPY
advances the input pointer, copying all characters it passes into
the output stream.  The INSERT command is not specifically a
line-editing command, as the same command is used in both line and
context editing.  It is described separately in this section as the
method of use for line editing is slightly different.
@BThe SKIP and COPY commands enable the line required to be
specified in a number of ways, as follows, (NOTE all
positions are positions in the input stream, the output stream
position being specified implicitly).@
@
1.@IAs a relative page number, e.g., S + 5., meaning skip to the
top (i.e., line 1) of page i + 5 where i is
the current page.  Thus S + 1., means 'skip to top of
next page'.@
@
2.@IAs a relative line number, e.g., S + 20 meaning skip to
the start of line j + 20 where j is the current
line.  (Effectively, skip over 20 lines).@
@
3.@IAs an absolute page.line position e.g. C5.4 means copy
to the start of line 4 on page 5.@
@
4.@IAs a string, e.g., S'BEGIN' meaning skip to the start of
the next line which contains the string BEGIN.@
@
5.@IThe letter 'F', (e.g. CF) meaning copy (or skip) to the end
of the file.
Because this is a
dangerous command, the editor will always request
verification before proceeding, by printing 'REALLY?'.  If
the response to this is 'Y', the editor proceeds; otherwise
the command is abandoned as faulty.  Thus in offline mode,
to skip to the end of the input, the sequence 'SFY' is
necessary.
@BNote that use of control characters such as newline in strings in
the SKIP and COPY commands can have rather unexpected results.  For
example, consider:-@
@V4 0
@U 2
@
                          C//L/BEGIN/
@B(or, for that matter
@U 3
@
                          C/
                          BEGIN/  ).
@Bmeans copy to the start of the line containing the string 'linefeed'
BEGIN.  Thus if the file contained:-@
@U 3
@
                          END OF PROCEDURE;
                          BEGIN
@Bthe pointer would finish at the start of the END line.  If you
don't understand this, never use control characters in S or C
commands!!
@V4 3
@SInsertion
@BThe Insert command has a string as its parameter, and inserts all
characters between the string delimiters into the output stream.
Since the SKIP and COPY commands always stop at the start of a line,
this means that to insert a single line into the output the insert
command should normally be used as follows:-@
@Q 3
@
@MI/NEW LINE TO BE INSERTED
@N/
@BThe following alternative:@
@
@
@NI/
@NNEW LINE TO BE INSERTED
@N/
@
@
would insert the new line with an extra blank line before it and@
@Q 3
@
@NI/
@NWRONG WAY OF DOING IT/
@
@
would insert an extra blank line and then simply insert the new
string at the start of the existing line.  This may of course be
useful in some cases, e.g.,@
@Q 3
@
@NS/INTEGER /I/
@NBEGIN/
@
@
will result in:@
@V4 3
@
@NBEGIN INTEGER
@
@
NOTE.  That when inserting new pages, the newpage character should
always be placed on a new line.  Thus:-@
@
(a)@ITo split an existing page into 2 pages such that the second
starts 50 lines from the current position@
@
@IC+50I//P//@
@Ihas the desired effect.@
@
(b)@ITo insert a completely new page after the current page@
@
@IC+1.I@
@I/FIRST LINE OF NEW PAGE@
@ILAST LINE OF NEW PAGE@
@I/P//@
@
@
@Q 27
@T% 10 25
Summary of Line-editing Syntax (by examples)
@
@
1.%S3.1%skip to top of page 3.@
2.%S + 10%skip over next 10 lines of input.@
3.%C'XYZ'%copy to start of next line containing XYZ.@
4.%CF%copy to end of input file.@
5.%SFY%skip to end of input file.@
6.%I%normal single line insertion.@
%/LINE TO INSERT@
%/@
7.%I%multiple line insertion.@
%/LINE 1@
%LINE 2@
%ETC@
%/@
8.%I%page insertion (if initially positioned at@
%/LINE 1%start of page).@
%LINE 2@
%ETC@
%/P//@
9.%I//P/LINE1%page insertion (if initially positioned at@
%LINE 2%end of page).@
%ETC@
%/@
@S35.4.1.6 Context-Editing Commands (B, D, A, I)
@BThese commands may be used to edit individual characters, or
strings of characters, within a line.  All four commands have a
single string parameter.  The Insert command is actually the same
command as the one used for line editing.
@SThe 'BEFORE' command  (B)
@BThe 'BEFORE' command is basically a copy operation, copying
characters from input to output until the input pointer arrives at
the start of the next occurrence of a specified string.  Unlike the
line-editing copy operation (C), however, the input pointer is left
immediately before the start of the string, not at the start of the
line.  For example, to correct:-@
@V4 0
@U 2
@
                          BEGIN INTER I,J,K;
@Bthe commands
@U 2
@
                          B/ER/I/EG/
@Bwould be used to copy to immediately before the string ER and then
insert EG.  In making corrections of this type, of course, it is
important to ensure that the string being searched for is unique.
For example, B/E/I/EG/ would have resulted in:-@
@U 2
@
                          BEGEGIN INTER I,J,K;
@V4 3
@SThe 'AFTER' command  (A)
@BThis is also a copying operation, leaving the input pointer
immediately after the next occurrence of the string.  Thus for
example, to correct:-@
@V4 0
@U 2
@
                          BEGIN INTE I,J,K;
@Bthe commands
@U 2
@
                          A/INTE/I/GER/
@Bcould be used.
@V4 3
@SThe 'DELETE' command  (D)
@BThe delete command is a combined copy and skip operation.  Its
action is to copy to the start of the specified string, and then
skip to the end of the string, thus effectively deleting it from the
output.  This operation is especially useful for correcting spelling
or typing errors, for example:-@
@V4 0
@U 6
@
                          BEGONE INTEGER I,J,K;
@
can be corrected by
@
                          D/BEGONE/I/BEGIN/
@Bor, provided that the string ONE does not occur before the spelling
mistake, by@
@V4 3
@U 2
@
                          D/ONE/I/IN/
@SThe 'INSERT' command  (I)
@BExamples of the use of the insert command have already been given
in the preceding section.  Its action, as in the case of line
editing, is simply to insert all the characters in the string into
the output stream.
@BStrings used in context-editing commands may, of course, contain
newline and newpage symbols as in the line editing commands.  The
most common use of the context editing commands, however, is to
correct small errors within a line.  Care should be taken in context
editing to avoid deleting the final newline character of a page or
file.
@SSummary of Context Editing Syntax (by example)
@T% 6 18
@
@
1.%B'CONTEXT'%Copy to immediately before the string CONTEXT.@
2.%A!END!%Copy to immediately after the string END.@
3.%D/XYZ/%Delete the next occurrence of the string XYZ,@
%%by copying to its start and skipping to its end.@
4.%I/CHARS/%Insert the string CHARS into the output.@
@S35.4.1.7 Other Commands
@BThe following commands are not actually editing commands, but
perform other useful functions.
@SThe 'WINDOW' command  (W)
@BThe window command allows sections of the edited output to be
printed on the monitor stream.
It may have either of the forms:-@
@Q 3
@
@MW  integer e.g., W3
@NW
@BWhen used with no parameter the W command prints the current
line on the monitor output stream.  If the input pointer is at the
start of the line, (i.e., the last character output was newline or
newpage), the line is printed from the input stream.  If on the
other hand the input pointer is not at the start of the line, then
the first part of the line is printed from the output stream,
followed by the characters ~^~ indicating the current position of
the pointer, followed by the rest of the line from the input stream.
Thus for example, if a line contained:-@
@U 10
@
                         BEGIN INTEGR I,J,K;
@
then the commands
@
                         D/INTEGR/I/INTEGER/W
@
would cause the following to be printed
@
                         BEGIN INTEGER~^~ I,J,K;
@BThe parameter N indicates that after printing the current line,
the next N-1 lines of the input stream should also be printed.
@SThe VIEW command (V)
@BThe VIEW command causes a specified number of lines from the
current position onwards in the input stream to be made available
for screen editing.  Up to
23 of these will be displayed initially
with a cursor positioned at the top lefthand corner.  In the
case where the View command specifies more than 23 lines, the
remainder will roll on to the screen if an attempt is made to
move the cursor beyond the end of the screen.  The
V command has the same form as the Window command.
@
@
@Mi.e. V  integer  e.g. V30@
@BIn certain circumstances the amount of text made
available for editing will be less than requested and a
warning message will be given indicating where it has been
curtailed.  The reasons for this are:@
@T%10
@
1)@IThe occurrence of a line in the input that
is too wide to display across the screen.  In
this case the text for editing will stop at the
start of the long line and the input pointer
will point to the first character of the long line.@
@
2)@IThe occurrence of a newpage character.  The text
will be allocated up to the newpage character.  It will
not be sent with the text but on exit from view it will be
transmitted to the output stream.@
@
3)@IThe requested text being larger than the
buffer space available to the editor.  The text
allocated will stop at the end of the last complete line
prior to the buffer becoming full.
@BAfter the text has been displayed editing is achieved by the
set of commands described under VEDIT in section 5.5.
@BThe normal exit from View is achieved by the
Control 'E' command which arranges that the edited
output is sent to the output file with the input
pointer at the end of the string of input just viewed.
@BAn alternative form of exit allows the output to
be discarded and the input pointer to be restored
to its value prior to the View.  This is achieved by Control 'W'.
@BTwo other forms of exit are provided, mainly for
clerical use.  One of these Control 'Z', is to allow a
file to be searched a section at a time until
a specific feature is seen.  It allows the output
to be discarded but the input to be stepped on past the
section requested for viewing.  The final form of exit is
Control 'A' which allows a template document to be
successively output with different alterations each time.
This is achieved by sending the edited output to the
output stream while leaving the input pointer where it
was prior to viewing.  This allows the same section of
input to be viewed and edited any number of times.
@SThe RESTORE command  (R)
@BThis command simply restores the
values of the input and output pointers to their values before the
last positioning command, (i.e., S, C, A, B, D).  This is useful if a
command has been accidentally typed wrongly.  For the purpose of this
operation, the I command is not considered as an editing command.
@SThe EXIT command  (E)
@BThis command copies the remaining characters in the input stream
to the output stream and returns control to the program which called
the editor (usually the job control interpreter).@
@BIf it is required to delete the end of a file, this must be done
by using the command SF.
@SThe MERGE command  (M)
@BThis command has a filename as its parameter, and causes the
editor to switch its input to the start of the named file.  Note
that there is no way of returning to the previously selected file
other than by a further Merge command, which will return to the
@Gstart@G of the file.
@SThe QUIT command  (Q)
@BThis command may be used to abandon an edit without updating the
output file.  It is useful as an emergency exit in the case of
disastrous errors.
@S35.4.1.8 Repetition of Commands
@BAny sequence of commands may be repeated a specified number of
times by enclosing the sequence in brackets () with a repetition
count, e.g.,@
@
@T% 30
(10 S + 1 I/'COMMENT'/)@Iwill insert the string 'COMMENT' at the
start of each of the next 10 lines.@
(8 D/INTER/I/INTEGER/)@Iwill correct a mis-spelling which has
been made 8 times.
@BInstead of the repetition count, any of the following may be used:-@
@Q 7
@T% 10 20
@
%L%Meaning repeat until a newline is encountered in@
%%the input stream.@
%P%Meaning repeat until a newpage is encountered in@
%%the input stream.@
%F%Meaning repeat until the end of the input stream@
%%is encountered.@
@BWhen using the L and P repetition options, the pointers are left
at the start of the next line or page.  Thus for example:-@
@U 3
@
                         C+1. (P D 'E' I 'X')
@
will replace all 'E's on the next page by 'X's leaving the input and output
pointers at the top of page after that.
@BNote that the only effect of the (L, (P options is to restrict
the range of @5context@0 searches to the current line or page
respectively.  Thus they may not operate correctly if
searches for explicit line numbers are used within the repetition.@
@
@
Examples
@B(L D/A/I/*/) Replaces all 'A's on the current line by '*'s.
@B(P D/AREA/I/AREA1/) Replaces all occurrences of the name AREA
on the current page by AREA1.
@B(FA/MOD1/W) Searches for all occurrences of the name MOD1
in the file, and lists each line containing such an occurrence.@
@T% 10
@
@
NOTE.@IIn online mode the sequence of commands to be repeated is
limited to a single line.  There is no such restriction in offline
mode.  Brackets may be nested to a maximum depth of 5 though this
should rarely be necessary.@
@
@
Example
@B(5 (P D/A/I/B/)  ) Replaces all occurrences of the letter A
by B on the next 5 pages.
@S25.5 A BASIC SCREEN EDITOR
@
@
@T% 50
@JVEDIT([C],I,I,I)I%VED
@BThis is the limited screen editor used by the
View command above and some other system utilities.  The first parameter describ
es
the vector containing the text for screen editing.  The
second parameter gives
the size of the text for editing which is planted at the
start of the vector leaving a space at the end.  This is required
for insertions of new data.
The third parameter
describes
the device interface type (0-ANSI, 1-Installation dependent).
The fourth parameter is a stream number.  This is
the overflow output stream, which is used when too
many characters have been inserted and the text buffer is full.
When this occurs the buffer is flushed sending all
characters prior to the current cursor position to
the output stream.  This action is not evident to the
user as the screen remains unaltered but from then on
the cursor cannot be moved prior to this point.
VEDIT returns
the effective size of the vector after editing
when all the edited text appears from
the start of the specified vector.
This is followed immediately by the exit command type,
which provides the opportunity for the calling process
to take special action on the edited text.
@S35.5.1 Commands
@BUsers of ANSI standard terminals may use the special
keys associated with the following actions or the control alternatives.
Other users must use the control alternatives.@
@Q 11
@T% 10 40
@
%%@OControl Code@O@
@
%Cursor Up%Control U@
%Cursor Down%Control Y@
%Cursor Right%Control P@
%Cursor Left%Control O@
%Delete Character%Control D@
%Delete Remainder of Line%Control X@
%Command Exit%Control E,A,W,Z@
%Insert Space%Control R@
@
@
Any other characters are assumed to be replacements.
They will not only obliterate those already there on the
screen but will also delete them from the text.
Space for an insertion is made available by use of the
Control R command.
@S25.6 THE SCREEN EDITOR
@
@
@T% 50
1) @J@OSED@OIT([C],[C],I)
@T% 10
@BThis command invokes a general
purpose screen editor with a large set of
screen editing facilities.
@BThe first two parameters are filenames.  P1 is the input file and
P2 the output file.  If P1 is zero, the current file is used as
input.  However, if current file is not available
the editor assumes that the user has asked
for a new file to be created and consequently allows the user
to insert data (and edit it).
@BP2 is the destination file which can be any filename or the
current file (0) and will contain the edited (or newly input
and edited) data.
P3 is the terminal type.
@BThe display editor divides the screen into two areas, the
biggest area (at the top) is the one in which the
text appears and editing is done.  The bottom few
lines are reserved for displaying commands or any
other informative messages.
@BAll the editing operations are performed on programs
and English texts which are displayed on the screen.  The
editor has short and simple commands which show their
effects in the display as soon as they are typed in.  Text
(printing and formatting characters) is inserted just by
typing it; there is no "insert" command.
@BGenerally, each screen line contains a separate line of data.  However,
if a dataline is too long it will be displayed on several screen
lines.  Most edit functions (e.g. delete line) are restricted
to within the screen line and not the actual line.
@BThe editor provides seven different types of operations:
cursor control, insertion, deletion, screen control, mark and region,
kill/unkill and miscellaneous.  The form of these commands and
their characteristics are described in the following sections.
@S35.6.1 Form of Commands
@BMost of the frequently used commands are
entered using a single key
This is either in the form of a control character or
in the case of an ANSI standard terminal
the corresponding specially provided key.  The main commands
for which special keys are normally provided are given
below with the control character equivalents.  Some additional commands
only have control character representations and these are
introduced in the sections where they are described.
@Q 14
@
@
@X%`
@T` 30 40
@OOPERATION@O`@OANSI@O`@OALTERNATIVE CONTROLS@O@
@
cursor up`ESC[A`CTRL-U  %15@
cursor down`ESC[B`CTRL-Y  %19@
cursor forward`ESC[C`CTRL-P  %10@
cursor backward`ESC[D`CTRL-O  %F@
delete line`ESC[M`CTRL-X  %18@
delete next character`ESC[P`CTRL-D  %4@
scroll up`ESC[S`CTRL-A  %1@
scroll down`ESC[T`CTRL-Z  %1A@
previous page`ESC[V`CTRL-B  %2@
next page`ESC[U`CTRL-V  %6@
@X%%
@BThere are also some commands such as mark and region operations which are doub
le characters.  That is, two
characters must be typed consecutively with the CTRL held down.  After entering
the
first one users can still change their minds and start insertion or type
any non-existing command to cancel the effect of the double command.
@S35.6.1.1 Summary of Commands
@BThere are seven categories of operations each with a set of commands
which are outlined here and will be described individually in greater
detail later.
@BFor the rest of this section, commands are only
referred to by their control character identifier.  Users
may use ANSI commands whenever provided instead of these
controls (see 5.6).@
@T% 30
@
(C - means, CTRL key held down).
@SA. Cursor Control Commands
@
1. C-W@IMove cursor to the beginning of a line.@
2. C-E@IMove cursor to the end of a line.@
3. C-P@IMove cursor forward by one or more character positions.@
4. C-O@IMove cursor backward by one or more character positions.@
5. C-Y@IMove cursor down by one or more lines.@
6. C-U@IMove cursor up by one or more lines.
@SB. Insertion
@
@INo special command, just type in.
Receipt of commands will cause the line/screen to be refreshed.
@SC. Deletion Commands
@
1. C-D@IDelete one or more following characters.@
2. C-T@IDelete one or more preceding characters.@
3. C-X@IKill all or part of the current line.
@SD. Screen Control Commands
@
1. C-Z@IScroll down by two or more lines.@
2. C-A@IScroll up by two or more lines.@
3. C-V@IScroll up one or more pages.@
4. C-U@IScroll down one or more pages.
@SE. Mark and Region Commands
@
1. C-G C-B@ISet mark.@
2. C-G C-V@IInterchange mark and cursor.
@SF. Kill/Unkill Commands
@
1. C-G C-Z@ISave region.@
2. C-G C-X@IKill region.@
3. C-G C-A@IGet back (unkill).
@SG. Other Commands
@
1. C-R@IThe following integer is the repeat counter.@
2. C-G C-R@IDisplay repeat counter.@
3. C-G C-W@IQuit (abort) edit.@
4. C-G C-E@IExit (update and write).
@S35.6.1.2 Numeric Arguments
@BMany screen editing commands can be given a numeric argument.
Some commands interpret the argument as a repetition count.  In
all cases, @5no@0 @5argument@0 @5is@0 @5equivalent@0 @5to@0 @5an@0 @5argument@0
@5of@0 @5one@0.
@BAn argument can be entered by typing C-R followed by an unsigned
integer.  The next non-digit is assumed to be the
command for which the argument was intended.  However, if the
following non-digit is not a command, the argument will be reset.
@BTo cancel or change an argument another C-R <digits> may be typed.
@BThe effect of a numeric argument (n) on each command is described
in the following sections.
@S35.6.1.3 Cursor Control Commands
@BThe real position of the cursor on the screen is between the
position at which it resides and the one before it and hence 'next'
and 'previous' positions are identified.
@BThe line within which the cursor resides at any time is called the
'current line'.
@BCursor control commands only operate
within the text area and will not move to
positions outside the displayed text.
@
@
1) Beginning of the Line (C-W).
@BThis command positions the cursor at the first character position
of the line.
@
@
2) End of the Line (C-E).
@BThis command moves the cursor to the end of the current line and positions
it over (i.e., before) the last character on a screen line.
@
@
3) Cursor Forward (C-P).
@BThis command moves the cursor forward by (n) character positions.
If the cursor is at the end of a line, it will be moved to the beginning
of the next line.
scrolled up first so that the required line is within the screen.
@
@
4) Cursor Backward (C-O).
@BThis command moves the cursor backward by (n) character positions.
If the cursor is at the beginning of a line, it will be moved to the end
of the previous line.
@
@
5) Cursor Down (C-Y).
@BThis command moves the cursor to a similar position within the n-th
following line from current line.
@BOperation stops as soon as the required line is reached or end
of the file is encountered in which case the cursor will
be positioned within the last line.
@BIf the new position is beyond the end of line (EOL) marker, the cursor will be
repositioned at the EOL marker.
@
@
6) Cursor Up (C-U).
@BThis command moves the cursor to a similar position within the
n-th preceding line from current line.
@BIf the new position is beyond the EOL marker, the cursor will
be repositioned at the EOL marker.
@S35.6.1.4 Insertion
@BTo insert printing characters into the text, just type them in at an
appropriate position.  This causes any non-control character to be
echoed on the screen while all characters are buffered for transfer to
the editor.  Upon receipt of any non-insertable character (e.g. editing
commands), all or part of the screen will be refreshed by the editor.
This will cause newly inserted control characters (e.g.  VT) to be
displayed as well.  As a result users may type in as much data as they
wish (even past the text area of the screen).  However, receipt of any
command or non-insertable character will initiate the refreshing of the
screen before the command itself is serviced.
@BSometimes it may be necessary to clear the screen and refresh it,
this can be done by issuing a screen control command (5.6.1.6).
Format effectors such as linefeed, formfeed, carriage-return,
vertical tab, horizontal tab and backspace can be inserted using their
corresponding key (or CTRL + key).  When displayed, they will be shown
as c.
@BIf too many characters are added to one line without breaking it
with a carriage return (CTRL-M), linefeed (CTRL-J) or formfeed
(CTRL-L), the line will grow to occupy two (or more) lines on the
screen.
@BIf the new position of the cursor after insertion falls outside the
text area scope, the whole of the text will be scrolled up in order to
show the line which contains the cursor at the centre.
@S35.6.1.5 Deletion Commands
@BAll deletion operations are strictly limited to the
data being displayed at any time.
Only kill (delete) line saves the data being
removed, which may be restored using GET BACK command (5.6.1.8).
@
@
7) Delete Following Character(s) (C-D).
@BThis command deletes the next character
and all remaining characters are shifted to the left by one
character position.  Position of the cursor is not affected by
this command.
@
@
8) Delete Previous Character(s) (C-T).
@BThis command deletes the preceding character
and moves the cursor and the following characters
backward by one character position.
@
@
9) Kill/Delete Line (C-X).
@BOperation of this command depends on the value of the numeric
argument.
@BIf n is zero, all characters of the current line before the
cursor are deleted and the cursor and rest of the line are
shifted to the left.
@BIf n is non-zero, only the current line is affected.  In this case
all characters following the cursor up to but excluding the EOL
marker (if any are removed).  If there is no EOL, only contents
of the current line on the screen are removed.  With the cursor
positioned at the EOL, the EOL itself is removed.  Consequently,
in order to delete one line the C-X has to be used twice.
@S35.6.1.5.1 Deleting Long Lines
@BLong lines may be deleted by positioning the cursor at the beginning
of each portion of the line on the screen and using C-X.
@BIf all but the first screen line of a long line are deleted the line
still continues to be a long line until a separator (eg.,LF) is inserted
at the end of the line.
@S35.6.1.6 Screen Control Commands
@BThe text or edit area of the screen always
shows a limited amount of text and data, starting
from a certain point within the editor's buffer.  This
area, therefore acts like a 'window' to the buffer.
The window may be moved up and down in order
to change the active area (on which editing is done).
Notice that because of the automatic wrapping which is
performed on long lines, there is no need to move the
window sideways.
@
@
10) Scroll Down (C-Z).
@BThis command moves start of the window down by n(2 or more) lines, unless end
of the text is reached before that.
@BPosition of the cursor at the end of the operation depends on
the n.  Generally the cursor moves up with the text until it reaches the top of
the screen.  At this point any further scroll causes it to be
positioned at the top left hand corner of the screen.
@BTo read a long file sequentially this command can be used without
any parameter.  It takes the last two lines at the bottom of the text
area and puts them at the top, followed by many more lines not visible
before.
@BIf n = 0, it clears the screen before refreshing again.
@
@
11) Scroll Up (C-A).
@BThis command moves start of the window up by n lines,
unless beginning of the file is reached before that.
@BPosition of the cursor at the end of the operation depends on n.
Generally the cursor moves down with the text until it reaches the bottom of the
text area.  At this point an further scroll causes it to be positioned at the
beginning of the last line.
@BThis command with no parameter can be used for going back through the file
sequentially.  It takes the top two lines and puts them at the bottom of
the text area.  The rest is filled with the preceding lines in the file.
@BIf n = 0, it clears the screen before refreshing again.
@
@
12) Page Up (C-B)
@BThis command repositions start of the window at the beginning of the
n preceding pages and displays.
@BIf n = 0, it moves to the beginning of the file.
@
@
13) Page Down (C-V)
@BThis command positions start of the window at the beginning of the
n following pages and displays.
@BIf n = 0, it moves to the end of the file.
@S35.6.1.7 Mark and Region Commands
@BIn general, a command which processes part of the input text must be able
to be told where to start and where to stop.  Here, such commands (see 5.6.1.8)
start at the cursor position and end at a place called the "mark".  This
range of text is called the "region".
@BFor example, to remove part of a text, user could first set go to the
beginning of the text to be removed, put the mark there, move to the end
and then issue the KILL command.  Or set the mark at the end of the text,
move to the beginning, and then issue the command.
@BThe maximum gap size between mark and cursor is
machine-dependent.  On most
machines this will be about the same size as the segment
size.  If the mark becomes undefined, any
operations related to it will cause an appropriate
message to be displayed.
@
@
17) Set Mark (C-G C-B).
@BThis command places a mark where the cursor is currently positioned.
In fact the mark is invisible and only its position within the file
is remembered.
@
@
18) Interchange Mark and Cursor (C-G C-V).
@BThis command puts the mark where the cursor was and cursor where mark was.
Thus, the previous location of the mark is shown, but the region is not changed.
@BUsers in order to reassure themselves that the mark is where they think it is,
can use this command.
@S35.6.1.8 Kill/Unkill Commands
@BThis editor has several commands that erase variously sized blocks
of text without saving the erased text.  These are known as "delete"
commands.  There are also a number of commands which could be used to
erase and/or save text so that it can be restored if the user changes
his/her mind, or moved or copied to other parts of the file.
@BThe killed or saved text is pushed onto a "kill buffer".  Each
new kill/save command starts from the beginning of the buffer.  However,
a saved text may be re-inserted (unkilled) many times.
@
@
19) Save Region (C-G C-Z).
@BThis command copies the region onto the "kill buffer" without removing
it from the file.  The saved text may subsequently be inserted at other
places in the file.
@
@
20) Kill Region (C-G C-X).
@BThis command removes everything between cursor and the mark.  The killed
text is at the same time saved in the "kill buffer", and may be used
to restore to the condition before the kill command was issued, or to
copy the text to another place.
@
@
21) Get Back (C-G C-A).
@BThis command inserts into the file the contents of the "kill buffer"
and leaves the cursor at the end of the newly inserted text.
@S35.6.1.9 Other Commands (Miscellaneous)
@
@
22) Repeat Counter (C-R).
@BThe following unsigned integer is a repeat counter.
@
@
23) Display Repeat Counter (C-G C-R).
@BDisplays the repeat counter value in the second portion of the screen.
@
@
24) Quit (C-G C-W).
@BThis command causes the edit to be aborted.
@
@
25) Exit (C-G C-E).
@BThis command causes the edit to be finished and a new updated
file to be created.
@F
