$a include=template_file

$n$lm
IMP Core Environment Standard
$b2$lm
Section 6: Basic I/O Procedures
$a sectno=6; pageno=1
$a indent=0

$a indent=1



$b4$v5$t0 * $t %routine ABANDON INPUT$b0
$b0   $t0 * $t %routine ABANDON OUTPUT$b0

$p These procedures close the route associated with the currently selected
input or output stream, at the same time notifying the accessor associated
with the route that an ABANDON operation has been performed on one of its
routes. If the route being closed is the last route to the accessor, the
accessor is also closed.

$p When an accessor is closed, it performs an overall ABANDON on its connection
to the associated object if any of the routes to the accessor were ABANDONed. 
Only if all routes were closed normally (using CLOSE procedures) will the
accessor perform a normal close on its connection to the object. On termination
of the program, any remaining routes are CLOSEd.

$p The effect of ABANDONing a connection to an object is implementation
defined for each stream facility.
Implementors would normally aim for an ABANDON to be interpreted as the
programmer specifying that he would rather not have performed the initial
OPEN on the object.
For input streams, ABANDON will thus usually be identical in effect to CLOSE.
For output streams, ABANDON should attempt to leave the environment in as
close to its original state as possible, for example by deleting new versions
of files leaving the originals in place.
On some systems, stream facilities may be unable to perform this kind of
operation and it is always permissable for ABANDON to be defined as equivalent
to CLOSE. Note that this implies that programmers cannot assume that,
for example, the environment will be unaffected by an OPEN-ABANDON pair.







$b4$v5$t0 * $t %routine CLOSE INPUT$b0
$b0   $t0 * $t %routine CLOSE OUTPUT$b0

$p These procedures close the route associated with the currently selected
input or output stream, at the same time notifying the accessor associated
with the route that an CLOSE operation has been performed on one of its
routes. If the route being closed is the last route to the accessor, the
accessor is also closed.

$p When an accessor is closed, it performs a normal close on its connection
to the associated object only if all previous routes to the accessor were
closed normally, i$.e$. with one of the CLOSE procedures. If any of the
routes were closed using an ABANDON procedure, the connection is ABANDONed
as described in the section on the ABANDON procedures above.

$p Note that, on normal termination of the program, any remaining routes
will be CLOSEd, causing the connections to their associated objects to be
closed normally unless an ABANDON call has closed some other route to the
accessor at an earlier point in the program. The effect on routes, accessors
and objects of abnormal termination of the program (for example through a
run-time error condition) is implementation dependent.




$b4$v5$t0 * $t %routine COMPLETE INPUT
$b0   $t0 * $t %routine COMPLETE OUTPUT
$p {informal & provisional}
These procedures 'kick' the accessor associated with the currently selected
input or output stream. The effect of these procedures is implementation defined
for each stream facility. COMPLETE$ OUTPUT can be likened to a transport service
'push' operation, that is it ensures that any data being held locally for
optimisation purposes is issued to the associated object. In some cases such as
on record-based file systems, this necessitates the output of a complete line of
text.




$b4$v5$t0 * $t _s_t_r_i_n_g(255) %function INPUT NAME$b0
$p This function returns a textual description of the object associated with the
currently selected input stream.




$b4$v5$t0 * $t _s_t_r_i_n_g(255) %function OUTPUT NAME$b0
$p This function returns a textual description of the object associated with the
currently selected output stream.




$b4$v5$t0 * $t %integer %function INPUT STREAM$b0
$p This function returns the stream number of the currently selected input
stream.




$b4$v5$t0 * $t %integer %function OUTPUT STREAM$b0
$p This function returns the stream number of the currently selected output
stream.




$b4$v5$t0 * $t %byte %function NEXT SYMBOL$b0
$p {informal & provisional}
This function returns the next symbol from the currectly selected input
stream. If the currently selected input stream is ended then an event (9,1,0)
will be signalled.



$b4$v5$t0 * $t %constant %integer NL$b0
$p This important constant represents the character which
terminates lines of text in streams opened by the standard text file stream
facility, i.e$. OPEN INPUT and OPEN OUTPUT.
It is defined according to the
ISO/ASCII code on which the IMP language is based as follows:
$b$v1$l0
            %constant %integer NL = 10
$b
Many stream facilities regard this character value as being no different in
its properties to any others in the %byte character range. However,
the pre-defined "standard" text file stream facility defined by OPEN INPUT
and OPEN OUTPUT distinguishes NL from all other characters.
Any accessor created by OPEN OUTPUT recognises the character value NL as
indicating a line break and performs the appropriate system-dependent
operations to achieve this effect in the output file. Similarly, input accessors
created by OPEN INPUT perform the system-dependent operations required to
extract lines of text from the input file, and provide the program with a
NL character when that position in the file is reached.





$b4$v5$t0 * $t %routine OPEN INPUT$ $ ( %integer Stream, _s_t_r_i_n_g(255) S )
$b0   $t0 * $t %routine OPEN OUTPUT ( %integer Stream, _s_t_r_i_n_g(255) S )

$p These two procedures constitute the TEXT stream facility, which allows an
IMP program access to a class of external objects which contain lines
of textual data.
Note that the exact relationship between the TEXT stream facility and the
underlying filing system is implementation defined (DEF0009; TEXT stream
facility). Most implementors will choose to use a file organisation provided by
the operating system if that is possible, but no fixed relationship is
guaranteed. In particular, there is no guarantee that files created by this
stream facility can be interpreted by anything other than OPEN$ INPUT.
This applies as much to operating system commands and programs as it does to IMP
programs attempting to access the object using other stream facilities. However,
the TEXT stream facility should be arranged if at all possible to create files
processable by the host operating system's standard text manipulation tools,
for example editors, file listing commands and so forth.
To allow the IMP system to interface with the host operating system's
conventions, certain characteristics of the data are not guaranteed to be
preserved on re-reading the file:

$v5$a indent<=2

$b$v10$t1 1$. $t2 Line Length. Under some operating systems, the convention for
text files is that they are organised as a series of fixed-length records.
Variable-size text lines generated by an IMP program will usually have to
be padded with trailing blanks to fit into such a scheme. Conversely, trailing
blanks at the end of a text line (i.e$. immediately preceeding the newline) may
be stripped off before the contents of the line are presented to the IMP
program. Finally, the TEXT stream facility may be forced to break a very long
line generated by an IMP program into several smaller lines in order to fit
into the record size specified by the operating system.

$b$v5$t1 2$. $t2 Trailing NL Character. Operating systems on which text files
are organised as a sequence of records (whether of a fixed size as in item$ 1
above or of variable size) by their nature imply that any text file will have
some number of complete lines, i.e$. that it is impossible to have a file on
which the last line is not terminated in the same way as were previous lines.
This manifests itself in IMP programs on such systems when the last line in an
output file is not terminated by a NL character:
on re-reading the file, it will be found to have had the NL inserted anyway.

$b$v10$t1 3$. $t2 Exact Character Values. Internally, IMP programs use a full
8-bit extended ISO/ASCII character set, and any of these 256 values may be
presented to the TEXT stream facility for output into a text file. Each of these
values has a meaning to the IMP program in terms of its graphical
representation; for example, the value$ 65 represents the capital letter$ 'A'.
However, many operating systems use a different character code to the ISO/ASCII
one used by IMP. The most common example of this in
modern operating systems is IBM's Extended Binary Coded Decimal
Interchange Code (EBCDIC), an 8-bit binary code which contains most (but not
all) of the graphical characters used by the ISO/ASCII code as well as adding a
few of its own. On systems using a character code different from that used
internally by IMP, the TEXT stream facility is required to perform the
translation between the IMP character code and that of the host operating
system: on an EBCDIC system, this will usually mean a simple 1-1$ mapping from
one character code to the other.
However, where shortcomings are present in one code relative to the other then
some information will be lost: for example, certain regional variants of
EBCDIC lack such characters as '[' and ']'.
This problem of loss of information may be arbitrarily severe: as an extreme
example, many older operating systems use 6-bit character codes in which the
customary control characters and lower-case letters are omitted, which require
any lower-case characters to be converted to their upper-case equivalents on
output.

$b$v5$a indent>

$v5$p In summary, the purpose of the TEXT stream facility is to process and
generate files of textual data which are in a human-readable form. Examples of
this kind of file would be a high-level language source file and the
corresponding compiler listing file.

This stream facility is therefore required to interface to the host operating
system's text file facilities, which in turn implies that very little can be
guaranteed about the contents of files manipulated by the TEXT stream facility
other than that a "best effort" will be made to communicate textual data with
the (human) user of the file.

For all purposes which require reliable exchange of data between programs (i.e$.
excluding the human element) it is recommended that the BINARY stream facility
described below be used instead.






$b4$v5$t0 * $t %routine OPEN BINARY INPUT$ $ ( %integer Stream, _s_t_r_i_n_g(255) S )
$b0   $t0 * $t %routine OPEN BINARY OUTPUT ( %integer Stream, _s_t_r_i_n_g(255) S )

$p These two procedures constitute the BINARY stream facility, which allows an
IMP program access to a class of external objects through which %byte values are
guaranteed to be transmitted unchanged.
In addition, the number of %byte values placed into the stream must match the
number read out before end-of-file.
This is in contrast to the TEXT facility described above, where only certain
values are guaranteed to be stored unchanged and
certain other characteristics of the data (such as preserving the length of
files and lines) are not guaranteed to be preserved.
Note that the exact relationship between the BINARY stream facility and the
underlying filing system is implementation defined (DEF0006; BINARY stream
facility). Most implementors will choose to use a file organisation provided by
the operating system if that is possible, but no fixed relationship is
guaranteed. In particular, there is no guarantee that files created by this
stream facility can be interpreted by anything other than OPEN$ BINARY$ INPUT.
This applies as much to operating system commands and programs as it does to IMP
programs attempting to access the object using other stream facilities.





$b4$v5$t0 * $t %routine POSITION INPUT$ $ ( %integer P )$b0
$b0   $t0 * $t %routine POSITION OUTPUT ( %integer P )$b0

$p {informal & provisional}
Guaranteed to be applicable to the (as yet not defined) positionable file
stream facility, although some systems may permit these to be applied to
other stream facilities if convenient to the implementor without sacrificing
efficiency.
Positioning operations are ignored by stream facilities to which they are
inapplicable.

$p Position 0 is the position of the first character in the stream, if any.





$b4$v5$t0 * $t %integer %function INPUT$ $ POSITION$b0
$b0   $t0 * $t %integer %function OUTPUT POSITION$b0

$p {informal & provisional}
Guaranteed to be applicable to the (as yet undefined) positionable file
stream facility, although some systems may permit these to be applied to
other stream facilities if convenient to the implementor without sacrificing
efficiency.

$p Position 0 is the position of the first character in the stream, if any.
INPUT POSITION will always return 0 on a newly-opened file even if it is
empty. The value 0 will also be returned by stream facilities which are not
positionable.




$b4$v5$t0 * $t %routine PRINT SYMBOL ( %byte S )$b0
$p Presents the 8-bit value S to the currently selected output stream for
handling. The precise effect of PRINT SYMBOL will depend on the 
stream facility associated with the currently selected output stream.
For example, the BINARY stream facility treats all
values in the 8-bit range identically, while OPEN OUTPUT
treats the NL characters specially as a text line terminator.




$b4$v5$t0 * $t %routine PROMPT ( _s_t_r_i_n_g(255) S )$b0
$p Indicates a message which should be
communicated to an interactive terminal user on future occasions when 
input is requested from the interactive terminal, if such a device exists.
This message remains
in effect until the end of program execution or until it is replaced through
another call on PROMPT.
The initial PROMPT string is implementation defined (DEF0007; initial prompt
string).
The method of presentation of the PROMPT string to the user, and the precise
times at which the PROMPT string is communicated, are both implementation
defined (DEF0014; operation of PROMPT facility).

$v5$p One some systems, the underlying system may have a prompt facility
sufficiently close to the IMP one for the implementation to use it to





$b4$v5$t0 * $t %routine READ SYMBOL ( %name N )$b0



$b4$v5$t0 * $t %routine RESET INPUT$b0
$b0   $t0 * $t %routine RESET OUTPUT$b0
$p Reset the accessor associated with the currently selected input or output
stream to a state as close as possible to that in effect immediately after
the initial OPEN call which created the accessor.

$v5$p For input streams, this means rewinding the stream to its start so that
the first character in the stream will be the next to be read.
For streams associated with terminals or other non-rewindable objects,
this operation is typically ignored.

$v5$p For output streams, a RESET operation should attempt to discard any
output which has already been generated. Note that in this respect it differs
from POSITION$ OUTPUT(0) which merely resets the writing pointer to the
beginning of the stream without discarding the already generated data.
For streams associated with terminals or other non-rewindable objects,
this operation is typically ignored.




$b4$v5$t0 * $t %routine SELECT INPUT$ $ ( %integer S )$b0
$b0   $t0 * $t %routine SELECT OUTPUT ( %integer S )$b0

$p Make the input or output stream numbered S the currently selected input
or output stream, as appropriate. It is an error (ERR0006; illegal stream
number) if the value of S is less than
0 or greater than the implementation defined maximum stream number (DEF0001;
maximum stream number).