If you are unclear about the working of Algol 68 transput, consult chapter 9. The function of this section is to document all the transput declarations so that you can use it as a reference manual.
The declarations will be covered in the following order:-
In the sequel, transput errors are mentioned using identifiers whose values appear in the following table:-
Only five modes are available:-
The mode NUMBER
is used as a parameter of the
procedures whole
, fixed
and
float
, but because it is the union of all number modes,
it is unnecessary to specify it and so has not been made available for
general use.
For each channel in this section, the general properties are first given, followed by a table giving the properties of books opened on the channel and then a list of specific properties for the following procedures where applicable:-
establish |
open |
create |
close |
lock |
scratch |
set |
logical end |
reidf |
stand in channel
. Books on this channel have the following
properties:-
stand in channel | |
---|---|
bin possible | TRUE |
put possible | FALSE |
get possible | TRUE |
set possible | TRUE |
reidf possible | FALSE |
The stand out channel
is the standard buffered output channel.
Books on this channel have the following properties:-
stand out channel | |
---|---|
bin possible | TRUE |
put possible | TRUE |
get possible | FALSE |
set possible | TRUE |
reidf possible | FALSE |
and are available as the stand out book.
The stand back channel
is the standard buffered input/output
channel. Books on this channel have the following properties:-
stand back channel | |
---|---|
bin possible | TRUE |
put possible | TRUE |
get possible | TRUE |
set possible | TRUE |
reidf possible | TRUE |
and are available as the stand back book.
The channels have the following properties:-
8r644
. If the file cannot be established, the routine will return
the value errno
(the system error name) refers to.
8r444
.
If the file cannot be opened, the routine will return the value
errno
refers to.
8r644
.
REF FILE
opened with this channel
has blank as the string terminator. The
arguments, as a book, have the following properties:-
arg channel | |
---|---|
bin possible | FALSE |
put possible | FALSE |
get possible | TRUE |
set possible | TRUE |
reidf possible | FALSE |
open
.no program args
.open
.make term
can be used to set the string
delimiter to any required value to facilitate searching for
quote-delimited or otherwise delimited arguments.env channel | |
---|---|
bin possible | FALSE |
put possible | FALSE |
get possible | TRUE |
set possible | TRUE |
reidf possible | FALSE |
open
yields an error of valuestty saneThe keyboard is made available as a book having the following properties:-
kbd channel | |
---|---|
bin possible | TRUE |
put possible | FALSE |
get possible | TRUE |
set possible | FALSE |
reidf possible | FALSE |
get bin
rather than get
. The channel has the
following properties:-
open
.""
for the
identification. The routine checks to see whether stand in has been
redirected and yields the error stand in redirected
if so. Otherwise, the characteristics of stand
in
are changed to wait for a single character with no minimum
waiting time and with no echo of the input.open
.close
.close
.associate
except that binary transput is also allowed. The buffer behaves as a
book with the following properties:-
mem channel | |
---|---|
bin possible | TRUE |
put possible | TRUE |
get possible | TRUE |
set possible | TRUE |
reidf possible | FALSE |
p
and l
are both
1
and the value of c
is a positive integer then
c
is taken to be the size of the buffer. Otherwise, the
routine yields estab invalid parameters
as error value. The identification should be ""
.RVC
(see section 2b). The
identification will be used as the memory buffer.client/server socket channel | |
---|---|
bin possible | TRUE |
put possible | TRUE |
get possible | TRUE |
set possible | FALSE |
reidf possible | FALSE |
p
should be the family of socket (either
af unix or af inet).
If the latter, the l
should
be the port. The c
should be the MTU (maximum transport unit).
This governs the size of the buffer associated with the socket. No
checks are performed on its value. If p
is neither af
unix
nor af inet
, the routine returns
estab invalid parameters
as error value. The server socket should be established before the
client socket.open invalid parameters
for both
channels.PROC accept = (REF FILE socket)REF FILE:and is used by the server to accept a client socket, thereby yielding a
REF FILE
name which can be used to communicate with
the client.
The example programs client1
, server1
, client2
and server2
(whose source can be found in the examples
directory) demonstrate simple use of sockets.Four standard files are provided:-
stdin
. Books connected via
stand in
differ from those connected via the channel
stand in channel: set possible
returns FALSE
. Thus
this file must be regarded as a simple stream of bytes. When the
kbd channel is being used, stand in is unavailable.stdout
. Books connected
via
stand out
differ from those connected via the channel
stand out channel:
set possible
returns FALSE
. Thus this file must be regarded as a
simple stream of bytes.stderr
and behaves like
the file stand out
.Three procedures are available for opening files:-
(REF FILE f,STRING idf,
CHANNEL chann,INT p,l,c)INT:
p
pages, each page containing l
lines, each line containing
c
characters. In the QAD standard prelude, the
mem channel (see section 5)
takes notice of
p
, l
and c
and both p
and l
must
be 1
. The socket channels (see section
6) use p
for the socket family, l
for
the port if the family is af inet
and c
for the
size of
the MTU. For other channels, the values of p
, l
and
c
are ignored. The procedure yields zero on success, otherwise
an integer denoting an error (see section 13.7.2).
UNION(CHAR,STRING,RVC) idf,
CHANNEL chann)INT
STRING
. The above union ensures that an RVC
parameter can
be used to open an existing memory buffer with the memory channel. This
is particularly useful for performing transput on buffers obtained from
C library routines. The procedure yields zero on success, otherwise
an
integer denoting an error (see section 13.7.2).
PROC create=(REF FILE f,CHANNEL chann)INT:
/tmp
using the given channel.
Three procedures are provided:-
PROC close=(REF FILE f)VOID:
reidf
procedure has been
called, after closing the file, the procedure renames the file to the
identification given in the reidf
field.
PROC lock=(REF FILE f)VOID:
chmod
.
PROC scratch=(REF FILE f)VOID:
The procedures in this section are responsible for the transput of
actual values. Firstly, formatless transput is covered and then binary
transput. The a68toc compiler does not support formatted
transput. In each section, the shorthand L
is used for the
various precisions of numbers and bits values.
The term straightening is used in Algol 68 to mean the process whereby a complex mode is separated into its constituent modes. For example, the mode
MODE X=STRUCT(INT a, CHAR b, UNION(REAL,VOID) u)
would be straightened into values of the following modes:-
INT
CHAR
UNION(REAL,VOID)
The mode REF[]X
would be straightened into a number of values
each having the mode REF X
, and then each such value would be
further straightened into values having the modes
REF INT
REF CHAR
REF UNION(REAL,VOID)
However, a value of mode COMPL
is not straightened into two
values both of mode REAL
. Instead, the real part is transput,
then an "I"
read or written followed by the imaginary part.
Formatless transput converts internal values into strings of characters or strings of characters into internal values.
PROC(REF FILE)VOID) x)VOID:
put(stand out,x)
(synonym print).
[]UNION(SIMPLOUT,
PROC(REF FILE)VOID) x)VOID:
x
is straightened and the resulting values are
output. Each plain mode is output as follows:-
[]CHAR
, output all the characters on the current
line.
flip
or flop
for TRUE
or
FALSE
respectively. For []BOOL
, output flip
or
flop
for each BOOL
.
flip
for each bit equal to one and
flop
for each bit equal to zero. l bits width
characters are output in all. No newline or newpage is output. For
[]L BITS
, each BITS
value is output as above with
no
intervening spaces.
whole(i,1+l int width)which will right-justify the integer in
1+l int widthpositions with a preceding sign. For
[]L INT
, each integer is
output as described above, preceded by a space if it is not at the
beginning of the line. No newlines or newpages are output.
l real width+l exp width+3positions in floating-point format and preceded by a sign. For a value of mode
[]L REAL
, each REAL
value is output
as
described above.
i
. For []L COMPL
,
each complex value is output as described above.
lf
character is output if the routine is newline
and an ff
character if the routine is newpage.
User-defined routines with this mode can be used.
PROC(REF FILE)VOID) x)VOID:
get(stand in,
...)
.
[]UNION(SIMPLIN,
PROC(REF FILE)VOID x)VOID:
REF STRING
.
In
each case, if the end of the file is detected while reading characters,
the logical file end procedure is called:-
c
where c < blank
are
skipped and the next character is assigned to the name.
If a REF[]CHAR
is given, then the above action occurs for each
of the required characters of the multiple.
string term
field of f
is read. The file
is then
backspaced so that the string terminator will be available for the next
get
.
flip
nor flop
, the char error procedure
is
called with flop
as the suggestion. For REF[]BOOL
,
each
\texttt{REF BOOL}
name is assigned a value as described above.
REF BOOL
is repeated for each bit in the name.
For REF[]L BITS
, each REF L BITS name is assigned a
value as described above.
"0"
as the
suggestion. Reading of decimal digits continues until a character
which is not a decimal digit is encountered when the file is
backspaced. If during the reading of decimal digits, the value of
l max int
would be exceeded, reading continues, but the input
value is not increased. For REF[]L INT
, each integer is read
as described above.
"."
followed by any number of control characters (such
as newline or tab characters) and the fractional part
"Ee\"
. The exponent may have a sign. Absence of a sign is
taken to mean a positive exponent
REF[]L REAL
, each REAL
value is read
as
described above.
"i"
are read
from the file. Newlines or newpages or other control characters can
precede each real. The first number is regarded as the real part and
the second the imaginary part. For REF[]L COMPL
, each
REF L COMPL
is read as described above.
Binary transput performs no conversion on internal values, thus providing a means of storing internal values in a compact form in books or reading such values into a program.
put bin(stand back,x)
.
[]SIMPLOUT x)VOID:
get bin(stand back,x)
In all the above procedures, the transput is direct with no code
conversion. It should also be noted that the procedure
make term,
although usually used with formatless transput, can
also be used with binary transput in the QAD standard prelude for
inputting a STRING
terminated by any of a number of
characters. You should note that if set possible for
the channel
concerned, then the terminator (which will always
include
the lf
character) will not have been read when
get bin
returns. However, if not
set possible for the channel (and neither
stand in nor
stand out can be set), then no backspace is
possible for binary transput and so the terminating character will
have been read.
A number of miscellaneous procedures fall into this category.
REF FILE
value.
put
or a put bin
.
A number of procedures are available for interrogating the properties of files:-
TRUE
if binary transput is possible.
TRUE
if data can be sent to the book.
TRUE
if data can be got from the book.
TRUE
if the book can be browsed: that is, if the position
in the book for further transput can be set.
TRUE
if the identification of the book can be changed.
f
.
f
.
Three procedures are provided for altering the properties of files:-
STRING term)VOID:
term
the current string terminator.
reidf
field of f
to the given value
so that
when the file is closed, the book will be renamed.
Four event routines are provided. For each routine, the default
behaviour will be described. In each case, if the user routine yields
FALSE
, the default action will be elaborated. If it yields
TRUE
, the action depends on the event.
PROC(REF FILE,
REF CHAR)BOOL p)VOID:
p
, which may be an
identifier or an anonymous procedure, to the char error mended
field of f
. The actions on character error are:-
The relevant situations are:-
"0"
.
"."
, is not
a
digit. Any decimal digit can be substituted. The default is "0"
.
"e"
or "E"
or "\"
has
been read),
and the first non-space character is not a digit. Any decimal digit
can be substituted. The default is "0"
.iI
. The default is
"i"
.
(REF FILE f,PROC(REF FILE)BOOL p)VOID:
p
, which may be an
identifier or an anonymous procedure, to the logical file
mended field of f
. The actions on logical file end are:-
p
yields FALSE. If it yields TRUE then it is
presumed that the end of the file has been attended to and transput
is resumed. On any channel, if the end of the file has been reached or, in
unformatted character transput, an eof char
is read then the
error message logical file end not mended will be issued and
the program terminated with the exit value logical file end
not mended.
(REF FILE f,PROC(REF FILE)BOOL p)VOID:
p
, whether an identifier
or an anonymous procedure, to thephysical file mendedfield of
f
. The actions on physical file end are:-
p
yields FALSE then the
default action is elaborated, If p yields TRUE
then the ending of the file is presumed to be attended to and
transput is then re-attempted. On any channel, if there is no more
room on the physical medium, the program issues the error message
physical file end not mendedand then terminates the program with the exit value physical file end not mended.
(REF FILE f,PROC(REF FILE)BOOL p)VOID:
p
to the value error
mended field of f
. The actions taken on a value error are:-
value error not mended
and then terminates with the same exit value.max int
for the precision
concerned.min real
for the precision concerned.The conversion routines consist of three procedures converting
numbers to strings of characters, one operator and the procedure
char in string. All the procedures whole
,
fixed
and float
will return a string of
error char
if the number to be converted is too large for the
given width, or, if the number is a real, if it is infinite or
otherwise invalid.
(CHAR c,REF INT p,STRING s)BOOL:
c
occurs in the string s
, its
index is
assigned to p
and the procedure yields TRUE
, otherwise
no
value is assigned to p
and the procedure yields FALSE
.
width>0
. If width
is
zero, the shortest possible string is yielded. If a real number is
supplied for the parameter v
, then the call
fixed(v, width, 0)
is elaborated.
PROC fixed=(NUMBER v,
width
whose sign controls the
presence of a sign in the converted value as for whole
. The
parameter after
specifies the number of required digits after
the decimal point. From the values of width
and after
,
the number of digits in front of the decimal point can be calculated.
If the space left in front of the decimal point is insufficient to
contain the integral part of the value being converted, digits after
the decimal point are sacrificed.
INT width,after,exp)STRING:
width
whose sign
controls the presence of a sign in the converted value as for
whole
. Likewise, the sign of exp
controls the presence
of
a preceding sign for the exponent. If exp
is zero, then the
exponent is expressed in a string of minimum length. In this case, the
value of width
must not be zero. Note that float
always
leaves a position for the sign. If there is no sign, a blank is
produced instead. The values of width
, after
and
exp
determine how many digits are available before the decimal
point and, therefore, the value of the exponent. The latter value has
to fit into the width specified by exp
and so, if it cannot
fit,
decimal places are sacrificed one by one until either it fits or there
are no more decimal places (and no decimal point). If it still doesn't
fit, digits before the decimal place are also sacrificed. If no space
for digits remains, the whole string is filled with error char
.
OP HEX=(L BITS v)[]CHAR:
L
BITS
into a
row of hexadecimal digits. The total number of digits equals
l bits width OVER 4
. For example, HEX 4r3
yields
00000003
.
These routines provide formatting capability on both input and output.
f
by 1 byte. It
does
not read or write a blank.
f
by -1 bytes. It
does not read or write a backspace. Note that not every channel
permits backspacing more than once consecutively.
lf
is read. On output, emits a linefeed character. This is
non-standard behaviour.
ff
is read. Note that if the character following a number is
a
formfeed character, then that character will have been read during the
read of the number. Hence, the skip to formfeed character will skip the
whole of the following page. On output, a formfeed
character is
emitted immediately.
STRING
terminators are skipped on input
and the file positioned at the next non-terminating character. The
procedure is usually called after a STRING
has been read.
Sian Mountbatten 2012-01-19