IMP Core Environment Standard
Section 6: Basic I/O Procedures
* routine ABANDON INPUT
* routine ABANDON OUTPUT
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.
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.
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.
* routine CLOSE INPUT
* routine CLOSE OUTPUT
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.
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.
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.
* routine COMPLETE INPUT
* routine COMPLETE OUTPUT
{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.
* string(255) function INPUT NAME
This function returns a textual description of the object
associated with the currently selected input stream.
* string(255) function OUTPUT NAME
This function returns a textual description of the object
associated with the currently selected output stream.
* integer function INPUT STREAM
This function returns the stream number of the currently
selected input stream.
* integer function OUTPUT STREAM
This function returns the stream number of the currently
selected output stream.
* byte function NEXT SYMBOL
{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.
* constant integer NL
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:
constant integer NL = 10
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.
* routine OPEN INPUT ( integer Stream, string(255) S )
* routine OPEN OUTPUT ( integer Stream, string(255) S )
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:
1. 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.
2. 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.
3. 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.
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.
* routine OPEN BINARY INPUT ( integer Stream, string(255) S )
* routine OPEN BINARY OUTPUT ( integer Stream, string(255) S )
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.
* routine POSITION INPUT ( integer P )
* routine POSITION OUTPUT ( integer 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.
Position 0 is the position of the first character in the
stream, if any.
* integer function INPUT POSITION
* integer function OUTPUT POSITION
{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.
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.
* routine PRINT SYMBOL ( byte S )
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.
* routine PROMPT ( string(255) S )
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).
One some systems, the underlying system may have a prompt
facility sufficiently close to the IMP one for the
implementation to use it to
* routine READ SYMBOL ( name N )
* routine RESET INPUT
* routine RESET OUTPUT
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.
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.
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.
* routine SELECT INPUT ( integer S )
* routine SELECT OUTPUT ( integer S )
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).