@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 4 - MUSS USER MANUAL
@G@RCHAPTER 4 - BASIC INPUT/OUTPUT OPERATIONS@G
@V10 1 9 39
@T% 10
@BThe procedures in this Chapter are intended mainly for use in
programs, rather than as job control commands, and they enable a program
to perform the following functions@
@
i)@ISelect a particular stream to be used for subsequent input or
output operations until another stream is selected, and
to enquire about the currently selected streams.@
ii)@IExplicitly break an output stream into sections.@
iii)@IDiscover the mode, and other information, associated with a
stream.@
iv)@IPerform actual input/output operations.
@BThe user should be aware that all I/O documents in MUSS
consist of one or more records so that the notion of position,
in general, is two dimensional, namely@
@
@Mrecord number and
@Nposition within record.
@S24.1 PROCEDURES FOR STREAM SELECTION, ENQUIRY ETC
@BWhen it is known that a file contains only one record, which
may in fact be an arbitrary string of characters containing many lines
separated by newline characters, the record positioning commands can be
ignored.
@
@T% 50
@
1) @J@OS@OELECT.@OI@ONPUT(I)
@BThis procedure selects input stream P1 as the current input
stream. All subsequent input operations until the next call of
SELECT.INPUT will read from this stream. A fault is indicated if the
stream is not defined at the time of selection.
@BOn selecting a new input stream, the current position in the
currently selected stream is remembered, so that upon re-selection
input can resume from the present position.@
@
@
2) @JSELECT.HEADER()
@BIn the case of an input section which is a long message, this
procedure causes subsequent input on this section to be from the
header. For short messages, input re-commences from the start of the
section. On switching to a new section, the header or main document
is selected according to the mode of the input stream (see
3.2.5).@
@
@
3) @JSELECT.DOC()
@BThis procedure selects the main document of the current input stream. For a
short message, the action is identical to SELECT.HEADER. On
switching to a new section, the header or main document is selected
according to the mode of the input stream (see 3.2.5).@
@
@
4) @J@OB@OREAK.@OI@ONPUT(I)
@BThis procedure advances input stream P1 explicitly to the next
section. If P1 is negative, the current
stream is advanced.@
@
@
5) @JCURRENT.INPUT()I
@BThis procedure returns as its result the stream number of the
currently selected input stream.@
@
@
6) @JI.MODE()I
@BThis procedure returns the mode bits
for the current input stream,
with the most significant six bits encoded as follows@
@3
@Q 10
@
@M                 @O                                    @O
@N                |@OS|T|Q|P|O|N|    |20 BITS AS IN 3.2.5@O|
@N                 | | | | | |
@NSTREAM DEFINED --  | | | | |
@NSTREAM ASSIGNED----  | | | |
@NIO STREAM -----------  | | |
@NAVAILABLE FOR INPUT ---  | |
@NAVAILABLE FOR OUTPUT ----  |
@NSTRING IO -----------------
@0
@
@
7) @JI.SEG()I
@BThis procedure returns the segment number (if any) for the current
input stream.
A negative result implies there is
no segment - i.e. the current section is a short message.@
@
@
8) @JI.REC()I
@BThis procedure returns a 32-bit index into the current input
stream of the start of the current record.  This may be used
subsequently as a parameter to SET.I.REC and SET.O.REC.@
@
@
9) @JI.POS()I
@BThis procedure returns a 32-bit index to the current character of the current
input record. This may
be used subsequently as a parameter to SET.I.POS and SET.O.POS.@
@
@
10) @JI.SIZE()I
@BThis procedure return, as a 32-bit integer, the total size in
bytes of the document on the current input stream.@
@
@
11) @JR.SIZE()I
@BThis procedure normally returns, as a 32-bit integer, the number
of bytes in the current record.  If the stream is an IO stream,
which is selected for output, the number returned will be the maximum
size of the current output record.@
@
@
12) @JI.SOURCE([I])
@BThis procedure yields the identification of the process which
sent the current section of the current input stream, in a
vector of four I elements supplied as a parameter.
A trap is
entered if the input stream is not a message stream.@
@Q 6
@
@MP1[0] := system process number (SPN)
@NP1[1] := process identifier (PID)
@NP1[2] := channel to which replies are to be sent
@NP1[3] := message sequence number.@
@
This information is in a suitable form for use as a parameter to
CHANGE.DEST or SEND.MESSAGE.@
@
@
13) @JI.ENQ()I
@BThis procedure allows a process to enquire whether any input is
currently available at the current input stream.
The integer result is interpreted as follows:@
@3
@U 9
@
@
          @O                                             @O
          @O|                                   |D|C|B|A|@O
                (d)    END OF INPUT           -| | | |
                (c)    END OF AVAILABLE INPUT ---| | |
                (b)    END OF SECTION         -----| |
                (a)    END OF RECORD          -------|
@0
@
Notes:@
@T% 10
@
(a)@Iis set when the last byte in the
current record has been read
and the end of record character returned (if required).@
(b)@Iis set when the last byte
of a section has been read
and the end of file character has been returned (if required).@
(c)@Iis set when the end of a section has been
reached and no further sections are available. For an
online message stream (see 3.2.3), subsequent attempts to input an item
sequentially from the stream will cause the process to be halted.
In all other cases, attempts to perform further
input will be faulted.@
(d)@Iis set when the last byte
of a stream has been read. A subsequent
attempt to input an item sequentially from the stream will generate a
fault.
@
@
@
14) @JI.DOC()[C]
@BThis procedure returns the name and type of the current input
document.  Additional information about the document type is also
returned in the PWW's.  PW1 is set to the type of document, as
follows:@
@3
@T% 10 30 37 57
@
%%PW1%Procedure result%PWW1@
%Current file% 0%Nil%0@
%File% 1%Pointer to filename%Directory name@
%Message channel% 5%Nil%CHn@
@0
@
@
@
15) @J@OS@OELECT.@OO@OUTPUT(I)
@BThis procedure selects output stream P1 as the current output
stream. All subsequent output operations until the next call of
SELECT.OUTPUT will output to this stream. A fault is indicated if
the stream is not defined at the time of selection.
@BOn selecting a new output stream, the current position in the
currently selected stream is remembered, so that upon re-selection
output can resume from the present position.@
@
@
16) @JCURRENT.OUTPUT()I
@BThis procedure returns as its result the stream number of the
currently selected output stream.@
@
@
17) @JO.MODE()I
@BThis procedure returns the mode bits
for the stream encoded as in I.MODE.@
@
@
18) @JO.SEG()I
@BThis procedure returns the segment number associated with the
current output stream.
A negative result implies
that there is no segment - i.e. the stream is a short message
or string stream.@
@
@
19) @JO.REC()I
@BThis procedure returns a 32-bit index to the current record
of the current output stream.  It may subsequently be used as the
parameter of SET.O.REC (or SET.I.REC in an IO stream).@
@
@
20) @JO.POS()I
@BThis procedure returns a 32-bit index to the current character of the current
output record. This may be used subsequently as a parameter
to SET.O.POS.@
@
@
21) @JO.SIZE()I
@BThis procedure returns, as a 32-bit integer, the current total
size in bytes of the current output stream.@
@
@
22) @JO.DOC()[C]
@BThis procedure returns the name and type of the current output
document.  Additional information about the document type is
returned in the PWWs.  PW1 is set to the type of document, as
follows:@
@3
@T% 17 22 44 60
@
%PW1%Procedure result%PWW1%PWW2@
Current file% 0%Nil%0%0@
File% 1%Pointer to filename%Directory name%0@
Process% 2%Nil%Process name%Machine name@
Reply stream% 3%Nil%REPn%0@
Scratch document% 5%Nil%0%0@
@0
@
@
@
23) @J@OB@OREAK.@OO@OUTPUT(I)
@BThis procedure terminates the current section of the specified
output stream, and dispatches it to its destination. P1 specifies the
output stream to be broken, where -1 indicates that the currently
selected stream is to be broken. In the case of breaking output on
the last section of a stream (as determined by its section count),
further attempts to output to
it will generate a trap (OUTPUT EXCEEDED). BREAK.OUTPUT has no
effect on an undefined stream.@
@
@
24) @JEND.POS()
@BThis procedure defines the current record position in the
current output stream to be its end.  Its normal use is in
truncating an IO stream.@
@
@
25) @JOUT.HDR([C])
@BThis procedure replaces the header of the current output
stream by the vector given by P1.  The character string is @5not@0
copied, so having called OUT.HDR, subsequent changes to the vector
P1 will result in corresponding changes when the output is printed.
@S24.2 BASIC INPUT/OUTPUT OPERATIONS
@BThe procedures described in this section provide the basic
input/output operations, in terms of which all other higher level
input/output is implemented.
@BAs explained in Chapter 3, both sequential and random input/output
operations are available.  Sequential input/output operations always
advance to the next position, while random operations are achieved by
first moving the pointer to a specified position and then performing
the corresponding sequential operations.
@BThree types of positioning operations are available, namely for
positioning at the start of a specified record, for positioning within
a record, and at the end of the last written record in an IO stream.
These are as follows@
@
@
1) @JSET.I.REC(I)
@BThis sets the starting position for a record within the current
input stream.  The parameter P1 is interpreted as a byte position,
as returned by I.REC and O.REC.  It is intended for higher level library
organisations in implementing more complex file organisations.@
@
@
2) @JSET.O.REC(I)
@BThis sets the starting position for a record within the current
output stream.  The parameter P1 is interpreted as a byte position,
as returned by O.REC and I.REC.  It is intended for higher level library organis
ations
in implementing more complex file organisations.@
@
@
3) @JWIND()
@BThis command should only be used when the current output stream is
a IO stream.  It positions the output pointer after the last record
in the output so that further records may be written or the last record extended
.@
@
@
4) @JSET.I.POS(I)
@BThis sets the current position within the input record. The parameter P1
is interpreted as a byte position, as returned by
I.POS and O.POS.@
@
@
5) @JSET.O.POS(I)
@BThis sets the current position in the output record. The parameter P1 is
interpreted as a byte position, as returned by
O.POS and I.POS.
@S34.2.1 Character Input/Output Procedures
@BThe main operations for accessing a stream are IN.CH and OUT.CH. Two
additional procedures are NEXT.CH, which inspects the next character
on the stream without actually advancing the pointer, and
IN.BACKSPACE which provides limited facilities for backspacing in
the input stream. There are also procedures to enable
larger quantities of data, such as complete lines, to be processed at a time.@
@
@
1) @JIN.CH()I
@BThis procedure yields as its integer result the next
character on the currently selected input stream. An error
is generated if the stream is undefined, or the last character
of the stream (or of the current record)
has already been read.
@
@
@
2) @JNEXT.CH()I
@BThis procedure has the same effect as IN.CH, except
that the input pointer is not advanced. Thus many consecutive
calls to NEXT.CH will yield the same result. The next call to
IN.CH will also yield the same result.@
@
@
3) @JIN.BACKSPACE(I)
@BThis procedure backspaces the input pointer by an amount
specified by P1. If P1 is negative, the pointer is moved
to the start of the current line.
This can still be used even after a linefeed or formfeed has been read.
For positive P1,
the pointer is moved back P1 characters, or to the start
of the current section, whichever is nearer.
@
@
@
4) @JIN.BIN(I)I
@BThis procedure reads the number of bytes specified by P1, yielding
a right justified logical 32 result.@
@
@
5) @JSKIP.LINE()
@BThis procedure advances the current input stream
to the start of the next line.
@BIf the pointer for the stream is currently positioned at the
end of a line - i.e. a linefeed or formfeed has been read
the input pointer will not be advanced.@
@
@
6) @JIN.LINE([C])I
@BThis procedure copies a line of input from the current input
stream into the buffer specified
by P1, and returns as its result the number of characters in the
line.
The linefeed or formfeed which terminates the line is copied
into the buffer, but is not included in the character count.
@BIf the pointer for the stream is currently positioned in
the middle of a line - i.e. the linefeed or formfeed has not
yet been read - the @Gremaining@G characters (if any) in the
line are copied.@
@
@
7) @JOUT.CH(I)
@BThis procedure outputs its parameter as the next character of
the currently selected output stream. If the current section buffer
is full, BREAK.OUTPUT is called first.@
@
@
8) @JOUT.BACKSPACE(I)
@BThis procedure backspaces the output pointer by an amount
specified by P1. If P1 is negative, the pointer is moved to
the start of the current line. For positive P1 the pointer is
moved back P1 characters, or to the start of the current section,
whichever is nearer.@
@
@
9) @JOUT.BIN(I,I)
@BThis procedure outputs the number of bytes of P1 specified by P2.@
@
@
10) @JOUT.LINE([C],I)
@BThis procedure outputs a line, contained in the character
string P1, to the currently selected output stream.
@BP2 specifies the carriage control to be used, and is to
be interpreted as follows:@
@
@Q 13
@T% 10 21
@
%     0  -%overprint previous line (i.e. output@
%%carriage return before printing).@
%     1  -%print on next line ( i.e. output one@
%%linefeed before printing).@
% 2-63  -%leave specified number (1-62) of blank@
%%lines before printing (i.e. output@
%%2-63 linefeeds first).@
%    64  -%print at start of next page (i.e. output@
%%one formfeed first.@
%    65  -%output one linefeed @Gafter@G printing.@
%66-127  -%output 2-63 linefeeds after printing.@
%   128  -%output formfeed after printing.@
@S34.2.2 Record Input/Output Procedures
@
@
@
1) @JIN.REC()I
@BThis procedure selects the next record in the currently
selected input stream, returning as a 32-bit result the size of the record, or -
1 if there are no more records. Subsequent sequential character
or binary operations will operate within this record.@
@
@
2) @JOUT.REC()
@BThis procedure completes the current record on the currently
selected stream, and starts a new record.
@S24.3 OTHER (CHARACTER STREAM) INPUT/OUTPUT PROCEDURES
@BFor the majority of user's, the input/output interface is defined
by the programming languages they use, and is implemented in terms
of the basic procedures described in section 4.2. However, there are
some further procedures available in the library for doing common
character input/output operations (such as reading and printing
decimal integers). These are used in the implementation of the basic
system, and in effect form the input/output interface of the system
programming languages, but they may also be used by programs written
in other languages.
@S34.3.1 Character Stream Input Procedures
@
@
1) @JIN.I()I
@BThis procedure reads a (possibly signed) decimal integer from the
currently selected input stream, returning the value as its result.
A trap is forced if the next nonblank character is not a decimal
digit, +, or -.@
@
@
2) @JIN.OCT()I
@BThis procedure reads an octal integer from the currently selected
input stream, returning the value as its result. A trap is forced if
the next nonblank character is not an octal digit.@
@
@
3) @JIN.HEX()II
@BThis procedure reads a hexadecimal number from the currently
selected input stream, returning a double length value as its
result. A trap is forced if the next nonblank character is not a
decimal digit, A, B, C, D, E or F.@
@
@
4) @JIN.C.LIT()II
@BThis procedure reads a string of characters enclosed in double
quote symbols from the currently selected input stream, returning
the string as a packed, right-justified II value. If too many
characters are given, the required number are taken from the end of
the string. Non-printing characters can be represented by using
their ISO character codes written as two hexadecimal digits and
enclosed between exclamation marks, e.g. "ABC", "A VERY LONG STRING",
"!OC!PAGE3". A trap is forced if the next character is not ".@
@
@
5) @JIN.NAME()II
@BThis procedure is similar to IN.C.LIT except that the string
should not be enclosed in quotes, preceding blank lines and spaces
are ignored, and the string terminates on reading either a space
or a newline. (This procedure is
commonly used in the system for reading filenames, etc.).@
@
@
6) @JIN.C.STR([C])I
@BThis procedure reads a character string enclosed in double quotes
from the currently selected input stream, in the same format as for
IN.C.LIT above. The string is placed in the byte vector described by
P1, and its size (number of characters) is returned as an integer
result. If the size of the byte vector is too small to accommodate
all the characters given, any remaining characters are ignored up to
the end of the string.@
@
@
7) @JIN.STR([C])I
@BThis procedure is similar to IN.C.STR except that the string
should not be in quotes, preceding blank lines and spaces are
ignored, and the string terminates on reading either a space or a newline.
(This procedure is used by the job
control interpreter to read string parameters). Notice that spaces
within the string must be represented by their hexadecimal character
codes, e.g.@
@
@MA!20!STRING!20!WITH!20!SPACES.@
@S34.3.2 Character Stream Output Procedures
@
@
@T% 50
1) @J@OSP@OACES(I)
@BThis procedure outputs the number of spaces specified by P1 to
the currently selected output stream.@
@
@
2) @J@ON@OEW.@OL@OINES(I)
@BThis procedure outputs the number of newlines specified by P1 to
the currently selected output stream. If P1 is zero, and the
previous character on this stream is newline, nothing is output;
otherwise a single newline is output.
@BFor short message streams (e.g. online output), BREAK.OUTPUT is
called to end the current section on each call to NEW.LINES.@
@
@
3) @J@OCAP@OTION([C])
@BThis copies the string of characters in the byte vector P1 to the
currently selected output stream.@
@
@
4) @JOUT.I(I,I)
@BThis procedure prints the integer P1 as a decimal integer on the
currently selected output stream. P2 specifies the required field
width. If P2 = 0, the number is printed left-justified. Otherwise,
it is printed (if possible) in a field width of P2 characters,
preceded by a space for positive numbers, a minus sign for negative
numbers (P2+1 characters in total). If the number requires more than
P2 digits, it will overflow the specified field width.@
@
@
5) @JOUT.OCT(I)
@BThis procedure prints the parameter P1 as an 11-digit octal
number on the currently selected output stream.@
@
@
6) @JOUT.HEX(I,I)
@BThis procedure prints the parameter P1
(which is a LOGICAL32) as a P2-digit hexadecimal
number on the currently selected output stream.
P2 may be in the range 1 to 8.
@
@
@
7) @JOUT.TIME()
@BThis procedure prints the time, in the format HH:MM:SS (hours,
minutes, seconds) on the currently selected output stream.@
@
@
8) @JOUT.DATE()
@BThis procedure prints the date, in the format DD:MM:YY (day,
month, year) on the currently selected output stream.@
@
@
9) @JOUT.TD(II,I)
@BThis procedure prints the time or date, extracted from its
parameter P1. This parameter is assumed to be a 32 bit integer,
as returned by the system procedure TIME.AND.DATE (Chapter 22).
If P2 is zero, the time is printed in the form HRS HRS:MINS MINS:SECS SECS.
If P2 is non zero, the date is printed in the form DAY DAY:MONTH MONTH:YEAR YEAR
.@
@
@
10) @JOUT.LINE.NO(I)
@BThis procedure prints the packed page/line number specified by P1
on the current output stream. The page and line numbers are printed
in decimal, separated by '.', with a total field width of 10
characters.  The most significant 16 bit of
P1 should give page numbers and the rest give line numbers.@
@
@
11) @JOUT.NAME(II)
@BThis procedure outputs its parameter as 8 characters, left
justified, with spaces to the right replacing any leading null
characters.@
@
@
12) @JOUT.FN([C])
@BThis procedure is used by compilers etc., to print out 'filename
time date' at the head of compilations, file listings, etc. P1 is
the filename to be printed. If it is zero, the filename <CFILE> will
be printed.@
@
@
13) @J@OO@OUT.@OS@OTACK(I,I)
@BThis produces a hexadecimal dump on the currently selected output
stream of the area between byte addresses P1 and P2. Any number of
consecutive identical lines are replaced by one copy of the line
followed by a single blank line.@
@
@
14) @JECHO.LINE()
@BThis causes the current line of input to be printed on the
current output stream if the output stream is offline. Otherwise, it
has no effect.@
@
@
15) @JPROMPT([C])
@BThis procedure resets the system prompt message, so that the
specified string (P1) is used the next time the system prompts an
online user for input. The prompt string will be reset to '**' by
the job control interpreter next time it regains control.
If the parameter is zero, prompting is suppressed completely.
@BThe prompt message is @5not@0 copied, so subsequent changes to
the prompt string P1 will result in corresponding changes to the output
when the prompt message is printed.@
@
@
16) @JPROMPT.CH(I)
@BTo allow the interception and recognition of prompt messages,
a prompt warning character is output immediately preceeding
the prompt message.  This warning character is set using the
PROMPT.CH command.  If the prompt warning character P1 is zero,
the warning character is omitted from prompt messages.
@F
