These files have been made freely available by SGS-Thomson and may not be used to generate commercial products without explicit permission and agreed licensing terms OR placed in a public archive or given to third parties without explicit written permission from SGS-Thomson in Bristol.
Tony Debling, SGS-Thomson Microelectronics Ltd, 1000 Aztec West, Almondsbury, Bristol BS12 4SQ, England. June 7, 1995.
Converted to HTML via RTFtoHTML, PERL5 and by hand by Dave Beckett <D.J.Beckett@ukc.ac.uk>.
WARNING: This has been converted from RTF format and may have mistakes compared to the printed version. If you find any in this file, please send them to me, and I will update it.
Dave Beckett <D.J.Beckett@ukc.ac.uk>
Library: hostio.lib
The host file server library contains routines that are used to communicate with the host file server. The routines are independent of the host on which the server is running. Using routines from this library you can guarantee that programs will be portable across all implementations of the toolset.
Constant and protocol definitions for the hostio library, including error and return codes, are provided in the include file hostio.inc.
The result value from many of the routines in this library can take the value w spr.operation.failed which is a server dependent failure result. It has been left open with the use of w because future server implementations may give more information back via this byte.
In particular, the hostio routines do not check the validity of stream identifiers, and the consequences of specifying an incorrect streamid may differ from system to system. For example, some systems may return an error tag, some may return a text message. If you use only those stream ids returned by the hostio routines that open files (so.open, so.open.temp, and so.popen.read), invalid ids are unlikely to occur. It is also possible in rare circumstances for a program to fail altogether with an invalid streamid because of the way the C library is implemented on the system. This error can only occur if direct use of the library to perform the operation would produce the same error.
For details of the occam syntax for real numbers see the occam 2 Reference Manual.
Procedure Parameter Specifiers
so.open CHAN OF SP fs, ts, VAL []BYTE name,
VAL BYTE type, mode, INT32 streamid,
BYTE result
so.open.temp CHAN OF SP fs, ts, VAL BYTE type,
[so.temp.filename.length]BYTE filename,
INT32 streamid, BYTE result
so.popen.read CHAN OF SP fs, ts, VAL []BYTE filename,
VAL []BYTE path.variable.name,
VAL BYTE open.type, INT full.len,
[]BYTE full.name, INT32 streamid,
BYTE result
so.close CHAN OF SP fs, ts, VAL INT32 streamid,
BYTE result
so.read CHAN OF SP fs, ts, VAL INT32 streamid,
INT length, []BYTE data
so.write CHAN OF SP fs, ts, VAL INT32 streamid,
VAL []BYTE data, INT length
so.gets CHAN OF SP fs, ts, VAL INT32 streamid,
INT length, []BYTE data, BYTE result
so.puts CHAN OF SP fs, ts, VAL INT32 streamid,
VAL []BYTE data, BYTE result
so.flush CHAN OF SP fs, ts, VAL INT32 streamid,
BYTE result
so.seek CHAN OF SP fs, ts, VAL INT32 streamid,
VAL INT32 offset, origin, BYTE result
so.tell CHAN OF SP fs, ts, VAL INT32 streamid,
INT32 position, BYTE result
so.eof CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result
so.ferror CHAN OF SP fs, ts, VAL INT32 streamid, INT32 error.no,
INT length,
[]BYTE message, BYTE result
so.remove CHAN OF SP fs, ts, VAL []BYTE name,
BYTE result
so.rename CHAN OF SP fs, ts,
VAL []BYTE oldname, newname, BYTE result
so.test.exists CHAN OF SP fs, ts,
VAL []BYTE filename, BOOL exists
PROC so.open (CHAN OF SP fs, ts,
VAL []BYTE name,
VAL BYTE type, mode,
INT32 streamid, BYTE result)
Opens the file given by name and returns a stream identifier streamid for all future operations on the file until it is closed. If name does not include a directory then the file is searched for in the current directory. File type is specified by type and the mode of opening by mode. type can take the following values:
spt.binary File contains raw bytes only.Binary byte
stream
spt.text File contains text records separated by
newline sequences.Text:stream
mode can take the following values:
spm.input Open existing file for reading.
spm.output Open new file, or truncate an existing
one, for writing.
spm.append Open a new file, or append to an
existing one, for writing.
spm.existing.update Open an existing file for update
(reading and writing), starting at
beginning of the file.
spm.new.update Open new file, or truncate existing one,
for update.
spm.append.update Open new file, or append to an existing
one, for update.
result can take the following values:
spr.ok The open was successful.
spr.bad.name Null file name supplied.
spr.bad.type Invalid file type.
spr.bad.mode Invalid open mode.
spr.bad.packet.size File name too large
(i.e.> sp.max.openname.size).
wspr.operation.failed If result w spr.operation.failed then
this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.open.temp
PROC so.open.temp
(CHAN OF SP fs, ts,
VAL BYTE type,
[so.temp.filename.length]BYTE filename,
INT32 streamid, BYTE result)
Opens a temporary file in spm.new.update mode. The first filename tried is temp00. If the file already exists the nn suffix on the name tempnn is incremented up to a maximum of 9999 until an unused number is found. If the number exceeds 2 digits the last character of temp is overwritten. For example: if the number exceeds 99 the p is overwritten, as in tem999; if the number exceeds 999, the m is overwritten, as in te9999. File type can be spt.binary or spt.text, as with so.open. The name of the file actually opened is returned in filename. The result returned can take any of the following values:
spr.ok The open was successful.
spr.notok There are already 10,000 temporary
files.
spr.bad.type Invalid file type specified.
wspr.operation.failed If result w spr.operation.failed then
this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.popen.read
PROC so.popen.read
(CHAN OF SP fs, ts,
VAL []BYTE filename,
VAL []BYTE path.variable.name,
VAL BYTE open.type,
INT full.len, []BYTE full.name,
INT32 streamid, BYTE result)
As for so.open, but if the file is not found and the filename does not include a directory, the routine uses the directory path string associated with the host environment variable, given in path.variable.name, and performs a search in each directory in the path in turn. This corresponds to the searching rules used by the toolset, using the environment variable ISEARCH, see section in the occam 2 Toolset User Guide. File type can be spt.binary or spt.text, as with so.open. The mode of opening is always spm.input. The name of the file opened is returned in full.name, and the length of the file name is returned in full.len. If no file is opened, full.len and full.name are undefined, and the result will not be spr.ok. The result returned can take any of the following values:
spr.ok The open was successful.
spr.bad.name Null name supplied.
spr.bad.type Invalid file type specified.
spr.bad.packet.size File name is too large
(i.e. > sp.max.openname.size) or
path.variable.name is too large (i.e.>
sp.max.getenvname.size).
spr.buffer.overflow The environment string referenced by
path.variable.name is longer than 507
characters.
wspr.operation.failed If result w spr.operation.failed then
this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual).
so.close
PROC so.close (CHAN OF SP fs, ts,
VAL INT32 streamid,
BYTE result)
Closes the stream identified by streamid. The result returned can take any of the following values:
spr.ok The close was successful.
wspr.operation.failed If result w spr.operation.failed then
this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.read
PROC so.read (CHAN OF SP fs, ts,
VAL INT32 streamid,
INT length, []BYTE data)
Reads a block of bytes from the specified stream up to a maximum given by the size of the array data. If length returned is not the same as the size of data then the end of the file has been reached or an error has occurred. Note: so.read reads in multiples of the packet size defined by sp.max.readbuffer.size. For greatest efficiency, read requests should be made in multiples of this size.so.write
PROC so.write (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE data,
INT length)
Writes a block of data to the specified stream. If length is less than the size of data then an error has occurred. Note: so.write writes in multiples of the packet size defined by sp.max.writebuffer.size. For greatest efficiency, write requests should be made in multiples of this size.so.gets
PROC so.gets (CHAN OF SP fs, ts,
VAL INT32 streamid,
INT length, []BYTE data,
BYTE result)
Reads a line from the specified input stream. Characters are read until a newline sequence is found, the end of the file is reached, or sp.max.readbuffer.size characters have been read. The characters read are in the first length bytes of data. The newline sequence is not included in the returned array. If the read fails then either the end of file has been reached or an error has occurred. The result returned can take any of the following values:
spr.ok The read was successful.
spr.bad.packet.size Data is too large
(> sp.max.readbuffer.size).
spr.buffer.overflow The line was larger than the buffer
data and has been truncated to fit.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.puts
PROC so.puts (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE data, BYTE result)
Writes a line to the specified output stream. A newline sequence is added to the end of the line. The size of data must be less than or equal to the hostio constant sp.max.writebuffer.size. The result returned can take any of the following values:
spr.ok The write was successful.
spr.bad.packet.size SIZE data is too large
( > sp.max.writebuffer.size).
wspr.operation.failed If result wspr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.flush
PROC so.flush (CHAN OF SP fs, ts,
VAL INT32 streamid,
BYTE result)
Flushes the specified output stream. All internally buffered data is written to the stream. Write and put operations that are directed to standard output are flushed automatically. The stream remains open. The result returned can take any of the following values:
spr.ok The flush was successful.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.seek
PROC so.seek (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT32 offset, origin,
BYTE result)
Sets the file position for the specified stream. A subsequent read or write will access data at the new position. For a binary file the new position will be offset bytes from the position defined by origin. For a text file offset must be zero or a value returned by so.tell, in which case origin must be spo.start. origin may take the following values:
spo.start The start of the file. spo.current The current position in the file. spo.end The end of the file.
The result returned can take any of the following values:
spr.ok The operation was successful.
spr.bad.origin Invalid origin.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.tell
PROC so.tell (CHAN OF SP fs, ts,
VAL INT32 streamid,
INT32 position, BYTE result)
Returns the current file position for the specified stream. The result returned can take any of the following values:
spr.ok The operation was successful.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.eof
PROC so.eof (CHAN OF SP fs, ts,
VAL INT32 streamid, BYTE result)
Tests whether the specified stream has reached the end of a file. The end of file is reached when a read operation attempts to read past the end of file. The result returned can take any of the following values:
spr.ok End of file has been reached.
.spr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.) This result
will also be obtained if eof has not
been reached.
so.ferror
PROC so.ferror (CHAN OF SP fs, ts,
VAL INT32 streamid,
INT32 error.no, INT length,
[]BYTE message, BYTE result)
Indicates whether an error has occurred on the specified stream. The integer error.no is a host defined error number. The returned message is in the first length bytes of message. length will be zero if no message can be provided. If the returned message is longer than 503 bytes then it is truncated to this size. The result returned can take any of the following values:
spr.ok An error has occurred on the specified
stream.
spr.buffer.overflow An error has occurred but the message
is too large for message and has been
truncated to fit.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.) This
result will also be obtained if no
error has occurred on the specified
stream.
so.remove
PROC so.remove (CHAN OF SP fs, ts,
VAL []BYTE name, BYTE result)
Deletes the specified file. The result returned can take any of the following values:
spr.ok The delete was successful. spr.bad.name Null name supplied. spr.bad.packet.size SIZE name is too largeso.rename
( > sp.max.removename.size). wspr.operation.failed If result w spr.operation.failed then this denotes a server returned failure. (See section C.2 in the Toolset Reference Manual.)
PROC so.rename (CHAN OF SP fs, ts,
VAL []BYTE oldname, newname,
BYTE result)
Renames the specified file. The result returned can take any of the following values:
spr.ok The operation was successful. spr.bad.name Null name supplied. spr.bad.packet.size File names are too largeso.test.exists
((SIZE oldname + SIZE newname)
> sp.max.renamename.size). wspr.operation.failed If result w spr.operation.failed then this denotes a server returned failure. (See section C.2 in the Toolset Reference Manual.)
PROC so.test.exists (CHAN OF SP fs, ts,
VAL []BYTE filename,
BOOL exists)
Tests if the specified file exists. The value of exists is TRUE if the file exists, otherwise it is FALSE.
Procedure Parameter Specifiers so.commandline CHAN OF SP fs, ts,
VAL BYTE all, INT length,
[]BYTE string, BYTE result so.parse.command.line CHAN OF SP fs, ts,
VAL [][]BYTE option.strings,
VAL []INT
option.parameters.required,
[]BOOL option.exists,
[][2]INT option.parameters,
INT error.len, []BYTE line so.getenv CHAN OF SP fs, ts,
VAL []BYTE name, INT length,
[]BYTE value, BYTE result so.system CHAN OF SP fs, ts,
VAL []BYTE command,
INT32 status, BYTE result so.exit CHAN OF SP fs, ts,
VAL INT32 status so.core CHAN OF SP fs, ts
VAL INT32 offset,
INT bytes.read,
[]BYTE data, BYTE result so.version CHAN OF SP fs, ts,
BYTE version, host, os, board
PROC so.commandline (CHAN OF SP fs, ts,
VAL BYTE all, INT length,
[]BYTE string, BYTE result)
Returns the command line passed to the server when it was invoked. If all has the value sp.short.commandline then all valid server options and their arguments are stripped from the command line, as is the server command name. If all is sp.whole.commandline then the command line is returned exactly as it was invoked. The returned command line is in the first length bytes of string. If the command line string is longer than 507 bytes then it is truncated to this size. The result returned can take any of the following values:
spr.ok The operation was successful.
spr.buffer.overflow Command line too long for string and
has been truncated to fit.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.parse.command.line
PROC so.parse.command.line
(CHAN OF SP fs, ts,
VAL [][]BYTE option.strings,
VAL []INT option.parameters.required,
[]BOOL option.exists,
[][2]INT option.parameters,
INT error.len, []BYTE line)
This procedure reads the server command line and parses it for specified options and associated parameters. The parameter option.strings contains a list of all the possible options and must be in upper case. Options may be any length up to 256 bytes and when entered on the command line may be either upper or lower case. Because all of the strings in option.strings must be the same length, trailing spaces should be used to pad. To read a parameter that has no preceding option (such as a file name) then the first option string should be empty (contain only spaces). For example, consider a program to be supplied with a file name, and any of three options `A', 'B' and `C'. The array option.strings would look like this: VAL option.strings IS [" ", "A", "B", "C"]: The parameter option.parameters.required indicates if the corresponding option (in option.strings) requires a parameter. The values it may take are:
spopt.never Never takes a parameter. spopt.maybe Optionally takes a parameter. spopt.always Must take a parameter.
Continuing the above example, if the file name must be supplied and none of the options take parameters, except for `C', which may or may not have a parameter, then option.parameters.required would look like this:
VAL option.parameters.required IS
[spopt.always, spopt.never,
spopt.never, spopt.maybe]:
If an option was present on the command line the corresponding element of option.exists is set to TRUE, otherwise it is set to FALSE. If an option was followed by a parameter then the position in the array line where the parameter starts and the length of the parameter are given by the first and second elements respectively in the corresponding element in option.parameters. If an error occurs whilst the command line is being parsed then error.len will be greater than zero and line will contain an error message of the given length. If no error occurs then line will contain the command line as supplied by the host file server. Most of the possible error messages are self explanatory, however, it is worth noting the meaning of the error `Command line error: called incorrectly'. This error means that either:
PROC so.getenv (CHAN OF SP fs, ts,
VAL []BYTE name,
INT length, []BYTE value,
BYTE result)
Returns the string defined for the host environment variable name. The returned string is in the first length bytes of value. If name is not defined on the system result takes the value . spr.operation.failed. If the environment variable's string is longer than 507 bytes then it is truncated to this size. The result returned can take any of the following values:
spr.ok The operation was successful. spr.bad.name The specified name is a null string. spr.bad.packet.size SIZE name is too largeso.system
( > sp.max.getenvname.size). spr.buffer.overflow Environment string too large for value but has been truncated to fit. wspr.operation.failed If result w spr.operation.failed then this denotes a server returned failure. (See section C.2 in the Toolset Reference Manual.)
PROC so.system (CHAN OF SP fs, ts,
VAL []BYTE command,
INT32 status, BYTE result)
Passes the string command to the host command processor for execution. If the command string is of zero length result takes the value spr.ok if there is a host command processor, otherwise an error is returned. If command is non zero in length then status contains the host specified value of the command, otherwise it is undefined. The result returned can take any of the following values:
spr.ok Host command processor exists. spr.bad.packet.size The array command is too largeso.exit
(> sp.max.systemcommand.size). wspr.operation.failed If result w spr.operation.failed then this denotes a server returned failure. (See section C.2 in the Toolset Reference Manual.)
PROC so.exit (CHAN OF SP fs, ts,
VAL INT32 status)
Terminates the server, which returns the value of status to its caller. If status has the special value sps.success then the server will terminate with a host specific `success' result. If status has the special value sps.failure then the server will terminate with a host specific `failure' result.so.core
PROC so.core (CHAN OF SP fs, ts,
VAL INT32 offset, INT bytes.read,
[]BYTE data, BYTE result)
Returns the contents of the root transputer's memory as peeked from the transputer when iserver is invoked with the analyze (`SA') option. The start of the memory segment is given by offset which is an offset from the base of memory (and is therefore positive). The number of bytes to be read is given by the size of the data vector. The number of bytes actually read into data is given by bytes.read. An error is returned if offset is larger than the total amount of peeked memory. The result returned can take any of the following values:
spr.ok The operation was successful. spr.bad.packet.size The array data is too large
(> sp.max.corerequest.size). wspr.operation.failed If result w spr.operation.failed then this denotes a server returned failure. (See section C.2 in the Toolset Reference Manual.)
This procedure can also be used to determine whether the memory was peeked (whether the server was invoked with the `SA' option), by specifying a size of zero for data and offset. If the result returned is spr.ok the memory was peeked.so.version
PROC so.version (CHAN OF SP fs, ts,
BYTE version, host, os, board)
Returns version information about the server and the host on which it is running. A value of zero for any of the items indicates that the information is unavailable. The version of the server is given by version. The value should be divided by ten to yield the true version number. For example, a value of 15 means version 1.5. The host machine type is given by host, and can take any of the following values:
sph.unknown unknown host type sph.PC IBM PC IBM 370sph.S370 IBM 370 Architecture NEC PCsph.NECPC NEC PC DEC VAXsph.VAX DEC VAX sph.SUN3 Sun Microsystems Sun 3 Sun:host typessph.BOX.SUN4 Sun Microsystems Sun 4 sph.BOX.SUN386 Sun Microsystems Sun 386i Apollosph.BOX.APOLLO Apollo Apollosph.BOX.ATARI Atari ST or TT
Values up to 127 are reserved for use by INMOS. The host operating system is given by os, and can take any of the following values:
spo.unknown unknown OS type DOSspo.DOS DOS HELIOSspo.HELIOS HELIOS VMSspo.VMS VMS SunOSspo.SUNOS SunOS CMSspo.CMS CMS CMSspo.TOS TOS
Values up to 127 are reserved for use by INMOS. The interface board type is given by board, and can take any of the following values:
spb.unknown unknown board type IMS B004spb.B004 IMS B004 IMS B008spb.B008 IMS B008 IMS B010spb.B010 IMS B010 IMS B011spb.B011 IMS B011 IMS B014spb.B014 IMS B014 IMS B015spb.B015 IMS B015 IMS B016spb.B016 IMS B016 DRX-11spb.DRX11 DRX 11 CATspb.IBMCAT CAT Caplin QT0spb.QT0 Caplin QT0 UDPlinkspb.UDPLINK UDP link UDPlinkspb.TCPLINK TCP link UDPlinkspb.ACSILA ACSILA
Values up to 127 are reserved for use by INMOS.
Procedure Parameter Specifiers so.pollkey CHAN OF SP fs, ts,
BYTE key, result so.getkey CHAN OF SP fs, ts,
BYTE key, result so.read.line CHAN OF SP fs, ts,
INT len, [] BYTE line,
BYTE result so.read.echo.line CHAN OF SP fs, ts,
INT len, [] BYTE line,
BYTE result so.ask CHAN OF SP fs, ts,
VAL [] BYTE prompt, replies,
VAL BOOL display.possible.replies,
VAL BOOL echo.reply,
INT reply.number so.read.echo.int CHAN OF SP fs, ts, INT n,
BOOL error so.read.echo.int32 CHAN OF SP fs, ts, INT32 n,
BOOL error so.read.echo.int64 CHAN OF SP fs, ts, INT64 n,
BOOL error so.read.echo.hex.int CHAN OF SP fs, ts, INT n,
BOOL error so.read.echo.hex.int32 CHAN OF SP fs, ts, INT32 n,
BOOL error so.read.echo.hex.int64 CHAN OF SP fs, ts, INT64 n,
BOOL error so.read.echo.any.int CHAN OF SP fs, ts, INT n,
BOOL error so.read.echo.real32 CHAN OF SP fs, ts, REAL32 n,
BOOL error so.read.echo.real64 CHAN OF SP fs, ts, REAL64 n,
BOOL error
PROC so.pollkey (CHAN OF SP fs, ts,
BYTE key, result)
Reads a single character from the keyboard. If no key is available then it returns immediately with . spr.operation.failed. The key is not echoed on the screen. The result returned can take any of the following values:
spr.ok A key was available and has been
returned in key.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.getkey
PROC so.getkey (CHAN OF SP fs, ts,
BYTE key, result)
As so.pollkey but waits for a key if none is available.so.read.line
PROC so.read.line (CHAN OF SP fs, ts, INT len,
[]BYTE line, BYTE result)
Reads a line of text from the keyboard, without echoing it on the screen. The characters read are in the first len bytes of line. The line is read until `RETURN' is pressed at the keyboard. The line is truncated if line is not large enough. A newline or carriage return is not included in line. The result returned can take any of the following values:
spr.ok The read was successful.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.read.echo.line
PROC so.read.echo.line (CHAN OF SP fs, ts,
INT len, []BYTE line,
BYTE result)
As so.read.line, but user input (except newline or carriage return) is echoed on the screen.so.ask
PROC so.ask (CHAN OF SP fs, ts,
VAL []BYTE prompt, replies,
VAL BOOL display.possible.replies,
VAL BOOL echo.reply,
INT reply.number)
Prompts on the screen for a user response on the keyboard. The prompt is specified by the string prompt, and the list of permitted relies by the string replies. Only single character responses are permitted, and alphabetic characters are not case sensitive. For example if the permitted responses are `Y', `N' and `Q' then the replies string would contain the characters `YNQ', and `y', `n' and `q' would also be accepted. reply.number indicates which response was typed, numbered from zero. ` ? ' is automatically output at the end of the prompt. If display.possible.replies is TRUE the permitted replies are displayed on the screen. If echo.reply is TRUE the user's response is displayed. The procedure will not return until a valid response has been typed.so.read.echo.int
PROC so.read.echo.int (CHAN OF SP fs, ts, INT n,
BOOL error)
Reads a decimal integer typed at the keyboard and displays it on the screen. The number must be terminated by `RETURN'. The boolean error is set to TRUE if an invalid integer is typed, FALSE otherwise.so.read.echo.int32
PROC so.read.echo.int32 (CHAN OF SP fs, ts,
INT32 n, BOOL error)
As so.read.echo.int but reads 32 bit numbers.so.read.echo.int64
PROC so.read.echo.int64 (CHAN OF SP fs, ts,
INT64 n, BOOL error)
As so.read.echo.int but reads 64 bit numbers.so.read.echo.hex.int
PROC so.read.echo.hex.int (CHAN OF SP fs, ts,
INT n, BOOL error)
As so.read.echo.int but reads a number in hexadecimal format. The number may be in lower or upper case but must be prefixed with either `#', or `$' which directly indicates a hexadecimal number, or `%', which means add MOSTNEG INT to the given hex (using modulo arithmetic). For example, on a 32 bit transputer %70 is interpreted as #80000070, and on a 16 bit transputer as #8070. This is useful when specifying transputer addresses, which are signed and start at MOSTNEG INT.so.read.echo.hex.int32
PROC so.read.echo.hex.int32 (CHAN OF SP fs, ts,
INT32 n, BOOL error)
As so.read.echo.hex.int but reads 32 bit numbers.so.read.echo.hex.int64
PROC so.read.echo.hex.int64 (CHAN OF SP fs, ts,
INT64 n, BOOL error)
As so.read.echo.hex.int but reads 64 bit numbers.so.read.echo.any.int
PROC so.read.echo.any.int (CHAN OF SP fs, ts,
INT n, BOOL error)
As so.read.echo.int but accepts numbers in either decimal or hexadecimal format. Hexadecimal numbers may be lower or upper case but must be prefixed with either `#' or `$' which specifies the number directly, or `%', which means add MOSTNEG INT to the given hex (using modulo arithmetic). For example, on a 32 bit transputer %70 is interpreted as #80000070, and on a 16 bit transputer as #8070. This is useful when specifying transputer addresses, which are signed and start at MOSTNEG INT.so.read.echo.real32
PROC so.read.echo.real32 (CHAN OF SP fs, ts,
REAL32 n, BOOL error)
Reads a real number typed at the keyboard and displays it on the screen. The number must conform to occam syntax and be terminated by `RETURN'. The boolean variable error is set to TRUE if an invalid number is typed, FALSE otherwise.so.read.echo.real64
PROC so.read.echo.real64 (CHAN OF SP fs, ts,
REAL64 n, BOOL error)
As so.read.echo.real32 but for 64 bit real numbers.
Procedure Parameter Specifiers so.write.char CHAN OF SP fs, ts,
VAL BYTE char so.write.nl CHAN OF SP fs, ts, so.write.string CHAN OF SP fs, ts,
VAL [] BYTE string so.write.string.nl CHAN OF SP fs, ts,
VAL [] BYTE string so.write.int CHAN OF SP fs, ts,
VAL INT n, width so.write.int32 CHAN OF SP fs, ts,
VAL INT32 n, VAL INT width so.write.int64 CHAN OF SP fs, ts,
VAL INT64 n, VAL INT width so.write.hex.int CHAN OF SP fs, ts,
VAL INT n, width so.write.hex.int32 CHAN OF SP fs, ts,
VAL INT32 n, VAL INT width so.write.hex.int64 CHAN OF SP fs, ts,
VAL INT64 n, VAL INT width so.write.real32 CHAN OF SP fs, ts,
VAL REAL32 r, VAL INT Ip, Dp so.write.real.64 CHAN OF SP fs, ts,
VAL REAL64 r, VAL INT Ip, Dp
PROC so.write.char (CHAN OF SP fs, ts,
VAL BYTE char)
Writes the single byte char to the screen.so.write.nl
PROC so.write.nl (CHAN OF SP fs, ts)
Writes a newline sequence to the screen.so.write.string
PROC so.write.string (CHAN OF SP fs, ts,
VAL []BYTE string)
Writes the string string to the screen.so.write.string.nl
PROC so.write.string.nl (CHAN OF SP fs, ts,
VAL []BYTE string)
As so.write.string, but appends a newline sequence to the end of the string.so.write.int
PROC so.write.int (CHAN OF SP fs, ts,
VAL INT n, width)
Writes the value n (of type INT) to the screen as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width, width. If the field width is too small for the number it is widened as necessary; a zero value for width specifies minimum width. A negative value for width is an error.so.write.int32
PROC so.write.int32 (CHAN OF SP fs, ts,
VAL INT32 n, VAL INT width)
As so.write.int but for 32 bit integers.so.write.int64
PROC so.write.int64 (CHAN OF SP fs, ts,
VAL INT64 n, VAL INT width)
As so.write.int but for 64 bit integers.so.write.hex.int
PROC so.write.hex.int (CHAN OF SP fs, ts,
VAL INT n, width)
Writes the value n (of type INT) to the screen as hexadecimal ASCII digits, preceded by the `#' character. The number of characters printed is width + 1. If width is larger than the size of the number then the number is padded with leading `0's or `F's as appropriate. If width is smaller than the size of the number, the number is truncated, from the left, to width digits. A negative value for width is an error.so.write.hex.int32
PROC so.write.hex.int64 (CHAN OF SP fs, ts,
VAL INT32 n,
VAL INT width)
As so.write.hex.int but for 32 bit integers.so.write.hex.int64
PROC so.write.hex.int64 (CHAN OF SP fs, ts,
VAL INT64 n,
VAL INT width)
As so.write.hex.int but for 64 bit integers.so.write.real32
PROC so.write.real32 (CHAN OF SP fs, ts,
VAL REAL32 r,
VAL INT Ip, Dp)
Writes the value r (of type REAL32) to the screen as ASCII characters formatted using Ip and Dp as described under REAL32TOSTRING (see section 1.8). Note: Due to fixed size internal buffers, this procedure will be invalid if the string representing the real number is longer than 24 characters. If this is a problem, it is suggested you write your own procedure to perform this function. The procedure should include a buffer set to the required size, a call to REAL32TOSTRING, followed by a call to so.write.so.write.real64
PROC so.write.real64 (CHAN OF SP fs, ts,
VAL REAL64 r,
VAL INT Ip, Dp)
As so.write.real32 but for 64 bit real numbers. The formatting variables Ip and Dp are described under REAL32TOSTRING (see section 1.8). Note : Due to fixed size internal buffers, this procedure will be invalid if the string representing the real number is longer than 30 characters. If this is a problem, it is suggested you write your own procedure to perform this function. The procedure should include a buffer set to the required size, a call to REAL64TOSTRING, followed by a call to so.write.
Procedure Parameter Specifiers so.fwrite.char CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL BYTE char, BYTE result so.fwrite.nl CHAN OF SP fs, ts,
VAL INT32 streamid, BYTE result so.fwrite.string CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE string, BYTE result so.fwrite.string.nl CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE string,
BYTE result so.fwrite.int CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT n, width, BYTE result so.fwrite.int32 CHAN OF SP fs, ts,
VAL INT32 streamid, n,
VAL INT width,
BYTE result so.fwrite.int64 CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT64 n, VAL INT width,
BYTE result so.fwrite.hex.int CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT n, width, BYTE result so.fwrite.hex.int32 CHAN OF SP fs, ts,
VAL INT32 streamid, n
VAL INT width, BYTE result so.fwrite.hex.int64 CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT64 n, VAL INT width,
BYTE result so.fwrite.real32 CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL REAL32 r, VAL INT Ip, Dp,
BYTE result so.fwrite.real64 CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL REAL64 r, VAL INT Ip, Dp,
BYTE result
PROC so.fwrite.char (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL BYTE char,
BYTE result)
Writes a single character to the specified stream. The result spr.notok will be returned if the character is not written.so.fwrite.nl
PROC so.fwrite.nl (CHAN OF SP fs, ts,
VAL INT32 streamid,
BYTE result)
Writes a newline sequence to the specified stream. If result takes a value . spr.operation.failed then this denotes a server returned failure, details of which are documented in in section C.2 of the Toolset Reference Manual.so.fwrite.string
PROC so.fwrite.string (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE string,
BYTE result)
Writes a string to the specified stream. The result spr.notok will be returned if not all the characters are written.so.fwrite.string.nl
PROC so.fwrite.string.nl (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL []BYTE string,
BYTE result)
As so.fwrite.string, but appends a newline sequence to the end of the string. The result returned can take any of the following values:
spr.ok The operation was successful.
spr.notok Not all of the characters were written.
wspr.operation.failed If result w spr.operation.failed
then this denotes a server returned
failure. (See section C.2 in the
Toolset Reference Manual.)
so.fwrite.int
PROC so.fwrite.int (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT n, width,
BYTE result)
Writes the value n (of type INT) to the specified stream as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width, width. If the field width is too small for the number it is widened as necessary; a zero value for width specifies minimum width. A negative value for width is an error. The result spr.notok will be returned if not all of the digits are written.so.fwrite.int32
PROC so.fwrite.int32 (CHAN OF SP fs, ts,
VAL INT32 streamid, n,
VAL INT width,
BYTE result)
As so.fwrite.int but for 32 bit integers.so.fwrite.int64
PROC so.fwrite.int64 (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT64 n, VAL INT width,
BYTE result)
As so.fwrite.int but for 64 bit integers.so.fwrite.hex.int
PROC so.fwrite.hex.int (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT n, width,
BYTE result)
Writes the value n (of type INT) to the specified stream as hexadecimal ASCII digits preceded by the `#' character. The number of characters printed is width + 1. If width is larger than the size of the number then the number is padded with leading `0's or `F's as appropriate. If width is smaller than the size of the number, then the number is truncated, from the left, to width digits. A negative value for width is an error. The result spr.notok will be returned if not all the characters are written.so.fwrite.hex.int32
PROC so.fwrite.hex.int32 (CHAN OF SP fs, ts,
VAL INT32 streamid, n
VAL INT width,
BYTE result)
As so.fwrite.hex.int but for 32 bit integers.so.fwrite.hex.int64
PROC so.fwrite.hex.int64 (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL INT64 n,
VAL INT width,
BYTE result)
As so.fwrite.hex.int but for 64 bit integers.so.fwrite.real32
PROC so.fwrite.real32 (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL REAL32 r,
VAL INT Ip, Dp,
BYTE result)
Writes the value r (of type REAL32) to the specified stream as ASCII characters formatted using Ip and Dp as described under REAL32TOSTRING (see section 1.8). The result spr.notok will be returned if not all the characters are written. Note: Due to fixed size internal buffers, this procedure will be invalid if the string representing the real number is longer than 24 characters. If this is a problem, it is suggested you write your own procedure to perform this function. The procedure should include a buffer set to the required size, a call to REAL32TOSTRING, followed by a call to so.write.so.fwrite.real64
PROC so.fwrite.real64 (CHAN OF SP fs, ts,
VAL INT32 streamid,
VAL REAL64 r,
VAL INT Ip, Dp,
BYTE result)
As so.fwrite.real32 but for 64 bit real numbers. The formatting variables Ip and Dp are described under REAL32TOSTRING (see section 1.8). Note : Due to fixed size internal buffers, this procedure will be invalid if the string representing the real number is longer than 30 characters. If this is a problem, it is suggested you write your own procedure to perform this function. The procedure should include a buffer set to the required size, a call to REAL64TOSTRING, followed by a call to so.write.
Procedure Parameter Specifiers so.time CHAN OF SP fs, ts,so.time
INT32 localtime, UTCtime so.time.to.date VAL INT32 input.time,
[so.date.len]INT date so.date.to.ascii VAL [so.date.len]INT date,
VAL BOOL long.years,
VAL BOOL days.first,
[so.time.string.len]BYTE string so.time.to.ascii VAL INT32 time,
VAL BOOL long.years,
VAL BOOL days.first
[so.time.string.len]BYTE string so.today.date CHAN OF SP fs, ts,
[so.date.len]INT date so.today.ascii CHAN OF SP fs, ts,
VAL BOOL long.years,
VAL BOOL days.first,
[so.time.string.len]BYTE string
PROC so.time (CHAN OF SP fs, ts,
INT32 localtime, UTCtime)
Returns the local time and Coordinated Universal Time. Both times are expressed as the number of seconds that have elapsed since midnight on 1st January, 1970. If UTC time is unavailable then it will have a value of zero. The times are given as unsigned INT32s.so.time.to.date
PROC so.time.to.date (VAL INT32 input.time,
[so.date.len]INT date)
Converts time (as supplied by so.time) to six integers, stored in the date array. The elements of the array are as follows:
Element of array Data
0 Seconds past the minute
1 Minutes past the hour
2 The hour (24 hour clock)
3 The day of the month
4 The month (1 to 12)
5 The year (4 digits)
so.date.to.ascii
PROC so.date.to.ascii
(VAL [so.date.len]INT date,
VAL BOOL long.years,
VAL BOOL days.first,
[so.time.string.len]BYTE string)
Converts an array of six integers containing the date (as supplied by so.time.to.date) into an ASCII string of the form:
HH:MM:SS DD/MM/YYYY
If long.years is FALSE then year is reduced to two characters, and the last two characters of the year field are padded with spaces. If days.first is FALSE then the ordering of day and month is changed (to the U.S. standard).so.time.to.ascii
PROC so.time.to.ascii
(VAL INT32 time,
VAL BOOL long.years,
VAL BOOL days.first
[so.time.string.len]BYTE string)
Converts time (as supplied by so.time) into an ASCII string, as described for so.date.to.ascii.so.today.date
PROC so.today.date (CHAN OF SP fs, ts,
[so.date.len]INT date)
Gives today's date, in local time, as six integers, stored in the array date. The format of the array is the same as for so.time.to.date. If the date is unavailable all elements in date are set to zero.so.today.ascii
PROC so.today.ascii
(CHAN OF SP fs, ts,
VAL BOOL long.years, days.first,
[so.time.string.len]BYTE string)
Gives today's date, in local time, as an ASCII string, in the same format as procedure so.date.to.ascii. If the date is unavailable string is filled with spaces.
Procedure Parameter Specifiers so.buffer CHAN OF SP fs, ts,
from.user, to.user,
CHAN OF BOOL stopper so.overlapped.buffer CHAN OF SP fs, ts,
from.user, to.user,
CHAN OF BOOL stopper so.multiplexor CHAN OF SP fs, ts,
[]CHAN OF SP from.user,
to.user,
CHAN OF BOOL stopper so.overlapped.multiplexor CHAN OF SP fs, ts,
[]CHAN OF SP from.user,
to.user,
CHAN OF BOOL stopper
[]INT queue so.pri.multiplexor CHAN OF SP fs, ts,
[]CHAN OF SP from.user,
to.user,
CHAN OF BOOL stopper so.overlapped.pri.multiplexor CHAN OF SP fs, ts,
[]CHAN OF SP from.user,
to.user,
CHAN OF BOOL stopper
[]INT queue
PROC so.buffer (CHAN OF SP fs, ts,
from.user, to.user,
CHAN OF BOOL stopper)
This procedure buffers data between the user and the host. It can be used by processes on a network to pass data to the host across intervening processes. It is terminated by sending either a TRUE or FALSE value on the channel stopper.so.overlapped.buffer
PROC so.overlapped.buffer (CHAN OF SP fs, ts,
from.user,
to.user,
CHAN OF BOOL stopper)
Similar to so.buffer, but allows many host communications to occur simultaneously through a train of processes. This can improve efficiency if the communications pass through many processes before reaching the server. It is terminated by either a TRUE or FALSE value on the channel stopper.
PROC so.multiplexor (CHAN OF SP fs, ts,
[]CHAN OF SP from.user,
to.user,
CHAN OF BOOL stopper)
This procedure multiplexes any number of pairs of SP protocol channels onto a single pair of SP protocol channels, which may go to the file server or another SP protocol multiplexor (or buffer). It is terminated by sending either a TRUE or FALSE value on the channel stopper. For n channels, each channel is guaranteed to be able to pass on a message for every n messages that pass through the multiplexor. This is achieved by cycling the selection priority from the lowest index of from.user. However, stopper always has highest priority.so.overlapped.multiplexor
PROC so.overlapped.multiplexor
(CHAN OF SP fs, ts,
[]CHAN OF SP from.user, to.user,
CHAN OF BOOL stopper,
[]INT queue)
Similar to so.multiplexor, but can pipeline server requests. The number of requests than can be pipelined is determined by the size of queue, which must provide one word for each request that can be pipelined. If SIZE queue is zero then the routine simply waits for input from stopper. Pipelining improves efficiency if the server requests have to pass through many processes on the way to and from the server. It is terminated by sending either a TRUE or FALSE value on the channel stopper. The multiplexing is done in the same cyclic manner as inso.pri.multiplexor
so.multiplexor. stopper has higher priority than any of from.user.
PROC so.pri.multiplexor
(CHAN OF SP fs, ts,
[]CHAN OF SP from.user, to.user,
CHAN OF BOOL stopper)
As so.multiplexor but the multiplexing is not done in a cyclic manner; rather there is a hierarchy of priorities amongst the channels -so.overlapped.pri.multiplexor
from.user: from.user[i] is of higher priority than from.user[j], for i < j. Also stopper is of lower priority than any of from.user.
PROC so.overlapped.pri.multiplexor
(CHAN OF SP fs, ts,
[]CHAN OF SP from.user, to.user,
CHAN OF BOOL stopper,
[]INT queue)
As so.overlapped.multiplexor but the multiplexing is done in the same prioritized manner as in so.pri.multiplexor. stopper has higher priority than any of from.user.