LIBHOSTIO-INMOS(3)

NAME
so.ask, so.buffer, so.close, so.commandline, so.core, so.date.to.ascii, so.eof, so.exit, so.ferror, so.flush, so.fwrite.char, so.fwrite.hex.int, so.fwrite.hex.int32, so.fwrite.hex.int64, so.fwrite.int, so.fwrite.int32, so.fwrite.int64, so.fwrite.nl, so.fwrite.real32, so.fwrite.real64, so.fwrite.string, so.fwrite.string.nl, so.getenv, so.getkey, so.gets, so.multiplexor, so.open, so.open.temp, so.overlapped.buffer, so.overlapped.multiplexor, so.overlapped.pri.multiplexor, so.parse.command.line, so.pollkey, so.pri.multiplexor, so.puts, so.read, so.read.echo.any.int, so.read.echo.hex.int, so.read.echo.hex.int32, so.read.echo.hex.int64, so.read.echo.int, so.read.echo.int32, so.read.echo.int64, so.read.echo.line, so.read.echo.real32, so.read.echo.real64, so.read.line, so.remove, so.rename, so.seek, so.system, so.tell, so.test.exists, so.time, so.time.to.ascii, so.time.to.date, so.today.ascii, so.today.date, so.version, so.write, so.write.char, so.write.hex.int, so.write.hex.int32, so.write.hex.int64, so.write.int, so.write.int32, so.write.int64, so.write.nl, so.write.real32, so.write.real64, so.write.string, so.write.string.nl, sp.receive.packet, sp.send.packet - KRoC INMOS occam toolset host file server library

SYNOPSIS
#INCLUDE "hostio.inc"
#USE "hostio.lib"
kroc -lhostio

PROC so.ask (CHAN OF SP fs, ts, VAL []BYTE prompt, VAL []BYTE replies, VAL BOOL display.possible.replies, VAL BOOL echo.reply, INT reply.number)
PROC so.buffer (CHAN OF SP fs, ts, CHAN OF SP from.user, to.user CHAN OF BOOL stopper)
PROC so.close (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)
PROC so.commandline (CHAN OF SP fs, ts, VAL BYTE all, INT length, []BYTE string, BYTE result)
PROC so.core (CHAN OF SP fs, ts, VAL INT32 offset, INT bytes.read, []BYTE data, BYTE result)
PROC so.date.to.ascii (VAL [6]INT date, VAL BOOL long.years, VAL BOOL days.first, [19]BYTE string)
PROC so.eof (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)
PROC so.exit (CHAN OF SP fs, ts, VAL INT32 status)
PROC so.ferror (CHAN OF SP fs, ts, VAL INT32 streamid, INT32 error.no, INT length, []BYTE message, BYTE result)
PROC so.flush (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)

PROC so.fwrite.char (CHAN OF SP fs, ts, VAL INT32 streamid, VAL BYTE char, BYTE result)
PROC so.fwrite.hex.int (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT n, VAL INT width, BYTE result)
PROC so.fwrite.hex.int32 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT32 n, VAL INT width, BYTE result)
PROC so.fwrite.hex.int64 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT64 n, VAL INT width, BYTE result)
PROC so.fwrite.int (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT n, VAL INT width, BYTE result)
PROC so.fwrite.int32 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT32 n, VAL INT width, BYTE result)
PROC so.fwrite.int64 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT64 n, VAL INT width, BYTE result)
PROC so.fwrite.nl (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)
PROC so.fwrite.real32 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL REAL32 r, VAL INT Ip, VAL INT Dp, BYTE result)
PROC so.fwrite.real64 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL REAL64 r, VAL INT Ip, VAL INT Dp, BYTE result)
PROC so.fwrite.string (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE string, BYTE result)
PROC so.fwrite.string.nl (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE string, BYTE result)

PROC so.getenv (CHAN OF SP fs, ts, VAL []BYTE name, INT length, []BYTE value, BYTE result)
PROC so.getkey (CHAN OF SP fs, ts, BYTE key, BYTE result)
PROC so.gets (CHAN OF SP fs, ts, VAL INT32 streamid, INT bytes.read, []BYTE data, BYTE result)
PROC so.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper)
PROC so.open (CHAN OF SP fs, ts, VAL []BYTE name, VAL BYTE type, VAL BYTE mode, INT32 streamid, BYTE result)
PROC so.open.temp (CHAN OF SP fs, ts, VAL BYTE type, [6]BYTE filename, INT32 streamid, BYTE result)
PROC so.overlapped.buffer (CHAN OF SP fs, ts, CHAN OF SP from.user, to.user, CHAN OF BOOL stopper)
PROC so.overlapped.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user CHAN OF BOOL stopper, []INT queue)
PROC so.overlapped.pri.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user CHAN OF BOOL stopper, []INT queue)

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)
PROC so.pollkey (CHAN OF SP fs, ts, BYTE key, BYTE result)
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 stream.id, BYTE result)
PROC so.pri.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper)
PROC so.puts (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE data, BYTE result)
PROC so.read (CHAN OF SP fs, ts, VAL INT32 streamid, INT bytes.read, []BYTE data)

PROC so.read.echo.any.int (CHAN OF SP fs, ts, INT n, BOOL error)
PROC so.read.echo.hex.int (CHAN OF SP fs, ts, INT n, BOOL error)
PROC so.read.echo.hex.int32 (CHAN OF SP fs, ts, INT32 n, BOOL error)
PROC so.read.echo.hex.int64 (CHAN OF SP fs, ts, INT64 n, BOOL error)
PROC so.read.echo.int (CHAN OF SP fs, ts, INT n, BOOL error)
PROC so.read.echo.int32 (CHAN OF SP fs, ts, INT32 n, BOOL error)
PROC so.read.echo.int64 (CHAN OF SP fs, ts, INT64 n, BOOL error)
PROC so.read.echo.line (CHAN OF SP fs, ts, INT len, []BYTE line, BYTE result)
PROC so.read.echo.real32 (CHAN OF SP fs, ts, REAL32 n, BOOL error)
PROC so.read.echo.real64 (CHAN OF SP fs, ts, REAL64 n, BOOL error)
PROC so.read.line (CHAN OF SP fs, ts, INT len, []BYTE line, BYTE result)

PROC so.remove (CHAN OF SP fs, ts, VAL []BYTE name, BYTE result)
PROC so.rename (CHAN OF SP fs, ts, VAL []BYTE oldname, VAL []BYTE newname, BYTE result)
PROC so.seek (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT32 offset, VAL INT32 origin, BYTE result)
PROC so.system (CHAN OF SP fs, ts, VAL []BYTE command, INT32 status, BYTE result)
PROC so.tell (CHAN OF SP fs, ts, VAL INT32 streamid, INT32 position, BYTE result)
PROC so.test.exists (CHAN OF SP fs, ts, VAL []BYTE filename, BOOL exists)
PROC so.time (CHAN OF SP fs, ts, INT32 localtime, INT32 UTCtime)
PROC so.time.to.ascii (VAL INT32 time, VAL BOOL long.years, VAL BOOL days.first, [19]BYTE string)
PROC so.time.to.date (VAL INT32 input.time, [6]INT date)
PROC so.today.ascii (CHAN OF SP fs, ts, VAL BOOL long.years, VAL BOOL days.first, [19]BYTE string)
PROC so.today.date (CHAN OF SP fs, ts, [6]INT date)
PROC so.version (CHAN OF SP fs, ts, BYTE version, BYTE host, BYTE os, BYTE board)
PROC so.write (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE data, INT length)

PROC so.write.char (CHAN OF SP fs, ts, VAL BYTE char)
PROC so.write.hex.int (CHAN OF SP fs, ts, VAL INT n, VAL INT width)
PROC so.write.hex.int32 (CHAN OF SP fs, ts, VAL INT32 n, VAL INT width)
PROC so.write.hex.int64 (CHAN OF SP fs, ts, VAL INT64 n, VAL INT width)
PROC so.write.int (CHAN OF SP fs, ts, VAL INT n, VAL INT width)
PROC so.write.int32 (CHAN OF SP fs, ts, VAL INT32 n, VAL INT width)
PROC so.write.int64 (CHAN OF SP fs, ts, VAL INT64 n, VAL INT width)
PROC so.write.nl (CHAN OF SP fs, ts)
PROC so.write.real32 (CHAN OF SP fs, ts, VAL REAL32 r, VAL INT Ip, VAL INT Dp)
PROC so.write.real64 (CHAN OF SP fs, ts, VAL REAL64 r, VAL INT Ip, VAL INT Dp)
PROC so.write.string (CHAN OF SP fs, ts, VAL []BYTE string)
PROC so.write.string.nl (CHAN OF SP fs, ts, VAL []BYTE string)

PROC sp.receive.packet (CHAN OF SP fs, INT16 length, []BYTE packet, BOOL error)
PROC sp.send.packet (CHAN OF SP ts, VAL []BYTE packet, BOOL error)

SUMMARY
The occam toolset library hostio.lib provides the main interface between the host and the transputer network.

The pair of channels CHAN OF SP fs, ts to and from the server are the first two parameters for most hostio.lib library procedure.

When a new stream is opened with so.open, a VAL INT32 streamid is returned. This is used to reference the stream and is used in all procedure calls related to files.

Error returns from procedures are passed out a variable called result which can take the following values:
spr.ok | The operation was successful
spr.notok | Too many temporary files opened (so.open.temp)
spr.bad.name | Invalid name parameter
spr.bad.type | Invalid type parameter (so.open, so.open.temp)
spr.bad.mode | Invalid mode parameter (so.open)
spr.bad.origin | Invalid origin parameter (so.seek)
spr.bad.packet.size | Some data was larger than the built in buffer
spr.buffer.overflow | Part of the operation exceeded the 256 byte buffer
>=spr.operation.failed | Server returned a failure

DESCRIPTION
so.ask prompts for a user keyboard response from valid replies and return reply.number as index. If display.possible.replies is TRUE then print permitted replies on the screen. If echo.reply is TRUE then echo response on screen.

so.buffer provides buffering of the SP protocol passing requests from the user to the system until any boolean is sent along stopper.

so.close closes an open stream.

so.commandline returns the command line passed by the host in string of SIZE length bytes. If all is set to sp.short.commandline then strip server options or present them if sp.whole.commandline.

so.core returns peeked memory of the root transputer.

For so.date.to.ascii see so.time and so.time.to.ascii etc.

so.eof returns a result of spr.ok if end-of-file has been reached on the given stream.

so.exit terminates the server and exits the program with status sps.success or sps.failure.

so.ferror puts a description of the given host error.no in a message of SIZE length.

so.flush flushes the output buffer of the given stream.

Write the given data type to a stream, usually a file, formatting where necessary and possibly padding with spaces to a given field width or printing Ip integer places and Dp decimal places for REAL32 and REAL64 types. Hex numbers are written prefixed by a '#'. PROCedures ending in .nl write a newline sequence.

so.getenv returns the value of the given host environment variable of SIZE length bytes.

so.getkey waits for a keypress.

so.gets reads up to SIZE data bytes from a line of the stream and returns the number of bytes read. The newline is not returned.

For so.multiplexor see so.overlapped.multiplexor.

so.open attempts to open the file name and returns the streamid for file operations if successful. Valid types are spt.binary and spt.text. Valid modes are spm.input, spm.output, spm.append, spm.existing.update, spm.new.update and spm.append.update.

so.open.temp opens a temporary file and return its filename and streamid. See so.open for valid types.

so.overlapped.buffer provides buffering of the SP protocol passing requests from the user to the system until any boolean is sent along stopper. Communications are overlapped allowing inputs and outputs to happen concurrently.

so.overlapped.multiplexor and so.overlapped.pri.multiplexor provide multiplexing of the SP protocol. Procedures with pri in the name give priority to the lower numbered channels. Procedures with overlapped in the name, overlap communications allowing inputs and outputs to happen concurrently.

so.parse.command.line parses the command line for options. See INMOS documentation for details.

so.pollkey reads a character from the keyboard (result = spr.ok) or returns immediately if no key is ready (result >= spr.operation.failed).

so.popen.read opens a file like so.open but use the given environment variable as a path to search for it. The mode is always spm.input and the full name and length are returned also.

For so.pri.multiplexor see so.overlapped.multiplexor.

so.puts writes the given line to the stream followed by a newline.

so.read reads up to SIZE data bytes from the given stream and returns the number read.

These (with read.echo in the name) read some data from the keyboard terminated by return, echoing output to the screen. Hex numbers can be prefixed by a '#' or '$' or with

so.read.line reads a line of SIZE len bytes from the keyboard with no screen echo. The line terminator is removed. See also so.read.echo.line.

so.remove attempt to delete the given file.

so.rename attempts to rename file oldname to newname.

so.seek moves the file pointer on the given stream to a new offset. Origin can be spo.start, spo.current or spo.end.

so.system executes the given command on the host server.

so.tell returns the position of the file pointer for the given stream.

so.test.exists returns TRUE in exists if the file exists.

so.time.to.ascii, so.time.to.date, so.today.ascii and so.today.date perform various time and date to/from ASCII conversions. See also so.date.to.ascii, so.time and time(3). [6]INT date is [seconds, minutes, hour, day, month, year]. Date format is "HH:MM:SS DD/MM/YYYY". If long.years is FALSE use 2 digit years. If days.first is FALSE then swap DD and MM (for U.S.)

so.time returns the local and UTC time (UNIX format - see time(3)).

so.version returns version information. See INMOS documentation for values.

so.write writes up to SIZE data bytes to the given stream and returns the length written.

These write the given data type to the screen, formatting where necessary and possibly padding with spaces to a given field width or printing Ip integer places and Dp decimal places for REAL32 and REAL64 types. Hex numbers are written prefixed by a '#'. PROCedures ending in .nl write a newline sequence.

For descriptions of the sp. procedures, see section H.3 of the INMOS manual.

SEE ALSO
kroc(1)
INMOS occam 2 toolset user manual - part 2 (occam libraries and appendices) INMOS document number 72 TDS 276 02.

AUTHOR
This document is Copyright (C) 1993 David Beckett, University of Kent at Canterbury. This manual page is maintained by Fred Barnes <frmb@kent.ac.uk>

The library contents are Copyright (C) 1991 INMOS Limited.

NOTES
The hostio library is deprecated in favour of the new POSIX flavoured libraries provided with KRoC.