@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 3 - MUSS USER MANUAL
@G@RCHAPTER 3 - INPUT/OUTPUT STREAM MANAGEMENT@G
@V10 1 9 26
@S23.1 INTRODUCTION
@T% 10
@BThe input/output system was briefly introduced in Chapter
2. It was explained that physical input/output exists as
"documents", which may take a variety of forms: for example, a
deck of cards; a lineprinter listing; a file, or a
"conversation" at an interactive terminal. The input/output
facilities described in this Chapter and Chapter 4 provide
programs with a common interface to all kinds of input/output
documents, so that the programmer need not be aware of the
actual source or destination of a particular document.
They also provide a common interface between the
input/output facilities of all of the programming languages,
so that a file generated by a FORTRAN program may be read by a
COBOL program, and vice versa.
@BHigh-level language programs perform input and output
operations using the facilities of the language in which they
are written. These are described in the relevant programming
language manuals. However, all of the programming language
facilities in MUSS are implemented in terms of the basic
operations described in the next Chapter and some languages
use the basic operations directly. The exact relation of the
programming language facilities to the basic input/output
system is described separately for each language in the
appropriate Chapter of this Manual.
@BInput and output operations in MUSS are organised in terms
of logical input/output @5streams@0. Each process may have
several input and output streams in use at any one time, and
may switch between these at will.  There may be some variation
in the number of available streams in different implementations of
MUSS but the norm is 32 of each.
The most important functions
of the basic input/output system are to provide the means for
@
@
i)@IAssigning actual documents to input and output streams
(usually by job control commands).@
ii)@ISelecting the particular stream to be used for each
input/output operation.@
iii)@IPerforming actual input/output operations on a
stream.
@BThe basic operations provided are used by particular
compilers to build up the complete set of input/output
facilities for the corresponding programming languages. This
Chapter describes the stream assignment operations; the others are described
in Chapter 4.
@S23.2 CHARACTERISTICS OF INPUT AND OUTPUT STREAMS
@S33.2.1 Structure of an Input/Output Stream
@BThe information in an input/output stream is structured as a
series of records.  In its most simple form, where a document
is just a sequence of characters, this structure degenerates to a
single record.
@BAccess to a stream is normally sequential, although the basic system
supports facilities for positioning a stream at a particular point within a reco
rd
for processing the information sequentially from that point.
Thus random access can be implemented by forming an external index,
perhaps in another stream.
@S33.2.2 Sectioned Streams
@BThe actual document assigned to a stream may be either a file
or a message (or sequence of messages). Each
message, if there are more than one, is referred to as a @5section@0 of
the stream. The division into sections is
achieved by explicit calls of the Break Output command.
@S33.2.3 Message Streams - Messages and Synchronisation
@BA message stream consists of a sequence of messages from or to another
process. Streams which communicate with peripheral devices are of this
type, since the devices are controlled by special processes. Thus for
example input and output on an interactive terminal uses message
streams.
@BThe system distinguishes between two types of message, called @5long@0
and @5short@0 messages. Long messages are used for communicating with bulk
input/output devices (such as card readers and lineprinters), and
short messages for interactive devices. The user need not be aware of
the distinction in the case of input streams, as the system will
automatically read from whichever kind of message is received. For
output, however, the user must define which kind of message is to be
used on any message streams he creates. If short messages are
specified, the section size is determined by the size of the buffer
used - about 100 characters - and no section limit is imposed.
@BIn the case of message input streams, the user also has
to define what action the system should take when an attempt is
made to read beyond the last available message. There are two options:
to wait until further messages arrive, or to signal a fault. The
former is suitable for input from an interactive terminal, and such a
stream is referred to as an @5online@0 input stream. The latter is more
appropriate for batch input, which is normally all present
before the job is started; such a stream is called on @5offline@0 input
stream.
@BFor message output streams, the user may also wish to
indicate that the output is to be synchronised to the operations
of the receiving process. In interactive operation, for example,
it is undesirable for a large amount of output to be
generated by a job in advance of it being printed. Two
means of synchronisation are possible, one automatic and the
other explicit. In the automatic case, the job is
suspended when the message is sent, and can only be freed
by the receiving process. This is used to synchronise with an
output device, as the output device controllers will perform the
freeing operation, if necessary, on completing the output of a document. The
alternative method is to request the receiving process to send a
message in reply; this message must then be detected and read
explicitly. This option enables a job to request notification
when output is performed, without actually being halted.
@S33.2.4 IO Streams
@BAn IO stream is a stream on which both input
and output operations may be performed.
A @5single@0 @5pointer@0 is used for both input
and output. Thus, interleaved sequential input and output operations
will operate on consecutive elements of the stream.
Usually the strictly sequential access will be broken by the user
repositioning the pointer.
@BAn IO stream occupies both an input and an output
stream. Releasing or re-defining either the input or the
output associated with an IO stream causes both
to be discarded.
@S33.2.5 Stream Modes
@X%`
@BThere are four commands which provide for the creation
of streams@
@
@M1) DEFINE.INPUT
@N2) DEFINE.OUTPUT
@N3) DEFINE.IO
@N4) DEFINE.STRING.IO
@
@
Each of these has a mode parameter which allows options to be
selected as shown below.  Not all options apply to all commands,
and this is shown below by 'n' in the appropriate position of the
table headed 1,2,3.
There is no column allocated to the 4th function, which is
not normally used directly by the user, however the only lists
relevant to it are the last three.
@3
@U 26
@
@
   @O                    @O   @O    @O   @O       @O   @O       @O   @O       @O
      @O     @O
  |@O               |M...@O| |@OL...@O| |@O.|K|J|I@O| |@OH|G|F|E@O| |@OD|C|B|A@O
|    |@O1|2|3@O|
                     |      |      | | |   | | | |   | | | |     | | | |
 m) DEST CHANNEL ----       |      | | |   | | | |   | | | |     |n| | |
                            |      | | |   | | | |   | | | |     | | | |
  l SYNCHRONISATION -------        | | |   | | | |   | | | |     |n| | |
    %00 Unsynchronised             | | |   | | | |   | | | |     |n| | |
    %10 suspend                    | | |   | | | |   | | | |     |n| | |
    %08 reply to channel 0         | | |   | | | |   | | | |     |n| | |
    %09 reply to channel 1         | | |   | | | |   | | | |     |n| | |
           etc                     | | |   | | | |   | | | |     | | | |
 k) Discard on errors         -----  | |   | | | |   | | | |     |n| | |
 j) File on errors            -------  |   | | | |   | | | |     |n| | |
 i) Short messages only       ---------    | | | |   | | | |     |n| |n|
                                           | | | |   | | | |     | | | |
 h) Online stream             -------------  | | |   | | | |     | |n|n|
 g) Append access not required---------------  | |   | | | |     |n|n| |
 f) Exclusive access required -----------------  |   | | | |     | |n| |
 e) Document default          -------------------    | | | |     | | | |
                                                     | | | |     | | | |
 d) Trap on end of section    -----------------------  | | |     | |n| |
 c) Generate section separater-------------------------  | |     | |n| |
 b) Trap on end of record     ---------------------------  |     | |n| |
 a) Generate record separater -----------------------------      |@O |n| @O|
@0
@X%%
@SNotes:
@T% 10
@
@
a)@IIf this bit is set and the input is obtained a character
at a time using IN.CH or other procedures which themselves use IN.CH, then the
end of record character
@X%'
(RS = %1E)
@X%%
will be generated after the last actual character of each record.@
@
b)@IThe norm is that input composed of several records may be read as an
unstructured character string by means of IN.CH.  However, if
this bit is set and the input is obtained a character at a time using
IN.CH, then a trap will be entered if an attempt is made to read from
one record to the next.@
@
c)@IIf this is set and the input is read using IN.CH an attempt to read
beyond the last character in a section will generate
a 'section separator' character
@X%'
(FS = %12)@
@X%%
@
d)@INormally a message stream containing several messages may be read
as continuous uninterrupted input (providing no attempt is made to
reposition the input pointer in a different section).  If this bit is
set any attempt to read across a section boundary will result in a trap
entry.@
@
e)@IWhen a Nil or Zero document name is given the default is normally
to the current file, and in the case of input to the current stream if there
is no current file.  This bit causes output to default to the current
stream, and in the case of input it prevents the second default option
(current stream) from being used.  Thus, a trap will be entered if there
is no current file available when an input is defined as the nil
filename and this bit is set.@
@
f)@IIndicates that exclusive access to the file is required.  This
means that while the stream is defined, no other process may use the file.@
@
g)@IIndicates the action to be taken when the file
mentioned in DEFINEIO is an existing file.  The norm is for the
file to be opened and the pointer to be placed at the first record.
Several ways exist in which the pointer may be moved including
WIND to the open end of the file for appending purposes.  Intermediate
records may also be changed although normally only to other records
of the same size.  Also any record position at which the pointer has been
placed can be declared to be the new end of the file by 'END.POS'.
It may subsequently be appended to from this position but unless it is
an attempt to read beyond this position will be faulted.@
@
h)@IIndicates whether a message input stream is offline (0) or
online (1); for a file stream it has no meaning.@
@
i)@IIn the case of input this indicates that the input should always be from the
 header, even for a
long message - see section 3.2.4.
In the output case, output is in short messages.@
@
j, k)@INormally when a process ends its output streams are broken and the
accummulated output is sent to its destination.  If a process is
trapped the same thing normally happens to its message output but
new files will not be created since this could destroy existing files of the
same name.  However, this action can be overridden by bit j and k.
If bit j is set the file output will be filed even if a program traps.
If bit k is set no output will be dispatched if a process traps.@
@
l)@ISection 3.2.3 gives further information on the synchronisation and
conversational features of the message system.@
@
m)@IIs a 3-bit field which allows any channel of the destination process
to be specified as the destination of message output.
@S23.3 ASSIGNING DOCUMENTS TO STREAMS
@BThe input and output streams of a process are
identified to the basic I/O system by stream numbers.
Input and output stream 0 are normally used for the
"default" input and output stream associated with a job. For
example a job submitted on cards will automatically have input
stream 0 assigned to the card input document, and output 0 to
the lineprinter associated with the input station; for an
interactive job, input and output streams 0 are automatically
assigned to the terminal input and output respectively. The
remaining streams are assigned by the user to any
other documents which are needed during the course of the
job.
@BDocuments may be assigned to streams either explicitly by
the user, or automatically by the software he is using. In the
case of standard system software such as compilers and
editors, and of most applications packages, the assignment is
automatic - the user supplies a "document name" as a
parameter, and the corresponding document is assigned behind
the scenes to a stream. The main use for explicit assignments
arises in running a user's own programs. Here, the language
implementor will specify the correspondence between the stream
numbers of MUSS and the "logical channels",
"files", or whatever are operated on by the program. It is
then up to the user to assign documents to the appropriate
streams prior to entering his program. Sometimes it is
desirable to operate on an explicitly assigned stream using
system software, and special document names are available to
allow this to be done.
@S33.3.1 Procedures for Defining and Releasing Streams
@
@
1) @JINIT.IO()
@BThis procedure completely re-initialises all input and
output streams, abandoning any which are currently defined. It
is performed automatically at the start of a job and is not
normally used again, but it can be used as a drastic recovery
measure in the case of very serious errors.@
@
@
2) @J@OD@OEFINE.@OI@ONPUT(I,[C],I)I
@BThis procedure defines a new input stream, overriding any
existing definition of this input stream. If the stream
specified is defined already, any input being processed (i.e.
the current section) on the stream is discarded. If the
currently selected input stream is re-defined, it
automatically remains selected but with the new document
assigned to it.
@BP1 specifies the stream number to be defined and is normally 0-31 or -1. If P1
is negative a free stream number will be selected by the
system. The stream number actually used is always returned as
the integer result of the procedure.
@BP2 specifies the document which is to be assigned to the
stream, and may take any of the forms@
@
@T% 10
(a)@IA filename, indicating that the document is a file.
If the filename contains
the character ':', it will be interpreted as
username:filename, and the file belonging to the user
named will be accessed provided that permission has
been given. If no username is specified, the currently
selected directory is used.@
(b)@IZero, indicating that the current file is to be used.
The current file may
only be assigned to one input stream at a time. If no
current file is available, the currently selected
input stream will be assigned instead provided that
the mode (P3) allows this and that P1 was negative.@
(c)@IA message channel CH0* CH1* CH2* CH3* CH4* CH5* CH6* CH7*, indicating that
the document will
consist of messages addressed to
the specified message channel.@
(d)@IA stream name - STR0*, STR1*, etc. This enables an
already existing stream (already set up by a preceding
DEFINE.INPUT) to be specified as a parameter. If P1 is
negative, the stream number of the named stream is
returned; otherwise the document on the stream named
is re-assigned to stream P1 and the named stream
becomes undefined.
@BP3 gives the mode to be associated with the stream, and is
interpreted as indicated in 3.2.5.@
@
@
3) @J@OD@OEFINE.@OO@OUTPUT(I,[C],I,I)I
@BThis procedure defines a new output stream, overriding any
existing definition of this output stream. If the stream is defined
already, any output produced and not yet dispatched (i.e., the
current section) is discarded. If the currently-selected output
stream is re-defined, it automatically remains selected but with the
new document assigned to it.
@BP1 specifies the stream number to be defined. If P1 is negative a
free stream number will be selected by the system. The stream number
actually used is always returned as the integer result of the
procedure.
@BP2 specifies the document which is to be assigned to the stream,
and may take any of the forms@
@T% 10
@
(a)@IA filename, indicating that the document is to become a
file.
If the filename already exists, the existing
copy will be overwritten when the stream is broken. If the
filename contains the character ':', it will be interpreted
as username:filename and the file belonging to the user
named will be updated provided that permission has been
given. If no username is specified, the currently selected
directory is used.@
(b)@IZero, indicating that the document, on completion, is to
become the current file or output to the currently selected
stream, depending upon the mode setting.
The "current stream" option is
only valid for negative P1.@
(c)@IA process name followed by a '*', indicating that sections
of the document are to be sent as messages to the specified
process. This option is used for output to standard system
devices - for example LPT* for a lineprinter, PTP* for a
paper tape punch. If the process name contains the character
':', it will be interpreted as machine name:process name,
and the output will be sent to the machine named. Otherwise,
the current machine is assumed.@
(d)@IA stream name - STR0*, STR1*, etc. This enables an existing
stream (already set up in an earlier DEFINE.OUTPUT) to be
specified as a parameter. If P1 is negative, the stream
number of the named stream is returned; otherwise the
document on the stream named is re-assigned to stream P1 and
the named stream becomes undefined.@
(e)@IA reply name - REP0*, REP1*, etc. This indicates that any
output produced is to be sent as a reply to the last section
received on the specified input stream.@
(f)@IThe character '*' alone, meaning that any output produced on
the stream is to be discarded.
@BP3 gives the mode to be associated with this stream, and is
interpreted as indicated in 3.2.5.@
@BP4 gives the maximum section size in bytes of each section of output.
For short message streams this
parameter is not used. A zero gives an
installation dependant default which is normally the hardware segment size.
If a process exceeds the stated
size of any individual section it will be trapped.
@
@
@
4) @J@OD@OEFINE.@OIO@O(I,[C],I,I)I
@BThis procedure is used to define a stream which may be used both as input and
output.
If the specified stream exists already (either as an input stream, or
an output stream, or both) the existing definition is overridden
and any existing input/output is discarded.
@BP1 specifies the stream number to be defined. If P1 is negative,
a free stream (i.e. a stream number for which neither
input nor output is defined) will be selected by the system.
The actual stream number used is always returned as the
integer result of the procedure.
@BP2 specifies the output destination. This may take any of the
forms allowed for DEFINE.OUTPUT. If the stream name form
STR0*, STR1* etc., is used, the stream must already be an IO
stream.
The default to stream and P2 must specify the same stream name. The default to
the current stream is not allowed.
When the specified destination is the name of an existing
file, and the mode specifies append access, the stream will be initialised to co
ntain this file.  Otherwise a
scratch segment will be allocated,
which will normally be dispatched to the specified destination
when the stream is closed.
@BPrior to dispatch a scratch segment will have its size changed
down to the minimum which will accommodate all its records.  However,
there will be no size change to a file accessed in append mode.
@BP3 specifies the mode for the stream, and is interpreted as indicated in 3.2.5
.
@BP4 is the same as in DEFINE.OUTPUT.
@
@
@
5) @JCHANGE.DEST(I,[I])
@BThis procedure enables the destination process for an existing
message output stream to be changed, without otherwise redefining
the stream in any way. P1 gives the stream number whose destination
is to be changed. P2 is a vector of four single-length (I) elements,
containing the system process number (SPN), process identifier (PID)
and channel number for the new destination, and a sequence number.
This information may be found by calling IN.SOURCE - if the output
is to reply to some input already received - or LOOK.UP.PROCESS - if
the output is to an explicitly named process.@
@
@
6) @JDEFINE.STRING.IO(I,[C],I)I
@BThis procedure enables a vector of bytes specified by P2 to be
assigned to an IO stream P1, so that subsequent input and output operations
on this stream access the byte vector. If P1 is negative a free
stream number will be selected by the system. The stream number
actually used is always returned as the integer result of the
procedure. P3 gives the mode, as indicated in 3.2.5.
@
@
@
7) @J@OE@OND.@OI@ONPUT(I,I)
@BThis procedure is used to release an input stream which
is no longer required. P1 specifies the stream to be released.
@BNormally, programs which define input streams release them using
END.INPUT with P2 positive. This will release the stream, unless
it was last assigned using the STRO* or "current stream" form
of document name (see DEFINE.INPUT), in which case the stream continues
to exist. If P2 is negative, the stream will be released regardless.
(Negative P2 is used when the stream is being released abnormally,
as a result of an error).@
@
@
8) @J@OE@OND.@OO@OUTPUT(I,I)
@BThis procedure is used to release an output stream
or an IO stream which
is no longer required. P1 specifies the stream to be released.
@BIf P2 is positive, the final section of the output stream
is dispatched to its destination in the usual way, before being
released. For negative P2, the action depends upon the mode
associated with the stream, and the type of stream. For a message
output stream, the output will be dispatched unless the DISCARD bit
in the mode (see 3.2.5) is set. For other stream types,
the output will be discarded unless the SAVE bit in the mode is
set. (Negative P2 is used when the stream is being
released abnormally as a result of an error. By default, message
streams are dispatched in this case, while file streams are not. The
SAVE and DISCARD bits allow this default action to be overridden
if necessary).
@BAs with END.INPUT, the stream is not released for positive
P2 if it was last assigned using the STRO* or "current stream"
form of document name.@
@
@
9) @JPROCESS.NAME([C])[C]
@BThis procedure scans the document name P1 to identify the type of
document corresponding to it.  PW1 is set to the document type, as
follows:@
@3
@Q 8
@
@M0    Current file (or current stream)
@N1    File
@N2    Process
@N3    Reply stream (REPn*)
@N4    Stream number (STRn*)
@N5    Scratch output document (*)
@N6    Message input document (CHn*)
@0
@
@
Additional information is returned according to the type of document@
@T% 20
@
File            -@IPWW1 contains the directory name.  The result of the
procedure is a pointer to the filename (pathname).@
@
Process         -@IPWW1 contains the process name component and
PWW2 contains the machine name.@
@
Reply or stream -@IPW2 holds the stream number, i.e. the 'n' component
of REPn*, STRn* or CHn*.
@
@
Control characters appearing in the document name delimit the name so that,
for example, leading or trailing spaces or nulls are discarded.
@SExamples of Use of Stream Definition Commands
@BOf the commands described in this section, only DEFINE.INPUT and
DEFINE.OUTPUT are normally used as job control commands. INIT.IO
cannot sensibly be used as it leaves all streams undefined, and so
there is nowhere from which further commands could be read.
CHANGE.DEST cannot be used easily as the command interpreter does
not provide any facility for representing vectors. The following
examples show the use of DEFINE.INPUT and DEFINE.OUTPUT in some
common situations.@
@T% 30
@
i) DI 0 CH0*@IThis is the command used automatically at the
start of a batch job, to initialise its
default input stream. A message input
stream is defined, with all terminators
suppressed except the last. Any attempt
to read a new section with no message
present results in a trap.@
@X%~
ii) DI 0 CH0* %80
@X%%
@IThis is used automatically at the start of
an interactive job to initialise its
default input stream. The difference
between this and (i) is that in this
case, reading a new section with no
message present results in a prompt
being output on stream 0, and the
process being halted until a message
arrives.@
iii) DI 1 MFY @IThis assigns the file MFY to stream 1.
This is the kind of command normally
used to set up input streams prior to
entering a user program.@
@X%~
iv) DI 5 @IThis is similar to case (iii) above, but the
current file is assigned to
stream 5.@
v) DO 0 LPT* @IThis is the command used automatically
at the start of a batch job, to
initialise its default output stream.
A long message stream of one section,
with an installation-defined size
limit, and directed at the lineprinter
control process, is defined.@
@X%~
vi) DO 0 0 %180
@X%%
@IThis is the command used automatically
at the start of an interactive job,
to initialise its default output
stream. A short message stream is
defined, synchronised with the
output so that the process awaits
printing of each output section
before continuing. Each section of
output is sent as a reply to the
process from which the current section
of input stream 0 was received (i.e.
the interactive terminal).@
vii) DO 1 OFILE @IThis assigns the file OFILE to output
stream 1 - i.e. on a 'BREAK.OUTPUT',
the stream will be filed as OFILE.
Only one section, of an
installation-defined length
will be permitted.@
viii) DO 5 LPT* 0 10000 @IThis defines an output stream,
directed at the lineprinter,
consisting of one section
(actually, an installation defined
default which is normally one)
of at most 10 thousand bytes.
@SExamples of Automatic Stream Definition
@BMany of the examples given in Chapter 2 were in fact special
cases of this facility.@
@
@
i) NEW FILEX@IFILEX is an automatically assigned
output stream, directed at the file specified.@
@
ii) FORTRAN FILEX@IAn automatically assigned input
stream, causes the source program on
FILEX to be compiled.@
@
iii) EDIT FILEX FILEY@IAutomatically assigned input and output
streams, FILEX is edited to produce
FILEY.@
@
iv) FORTRAN@IThis causes the source program on the
current file to be compiled if one
exists, otherwise the source program
is taken from the currently selected
input stream.@
@
v) EDIT@IThe current file (if one exists) is edited,
to produce a new current file. In
this case, if no current file exists,
a fault is generated.@
@
vi) LF FILEX LPT*@IThe input stream is from the FILEX,
the output stream is set up, with
default parameters, to the
lineprinter.@
@
vii) LF FILEX STR1*@IIn this case, the output stream is
defined to be stream 1, which
must have been set up previously
by a DEFINE.OUTPUT command. This
is useful (a) if it is required
to use an output stream with
parameters other than the
defaults, for example one with
more than one section, and (b)
if it is required to append the
listing to the end of a stream
which has already some output on it.@
@
viii) LF@IThe current file is listed on the
currently-selected output stream
(c.f. v above). A fault is generated if no
current file exists.
@F
