# Module `hostio`

## Index

- Process `so.ask` - Provide a general purpose routine for interactively asking a user of a program a question requiring only a one character answer
- Process `so.date.to.ascii` - Format a time and date given in the form of six integers
- Process `so.exit` - Terminate the server
- Process `so.fwrite.char` - Write a single character to a stream
- Process `so.fwrite.hex.int` - Write an integer as hexadecimal ASCII characters preceded by the '#' character to a stream
- Process `so.fwrite.hex.int32` - Write a 32-bit integer as hexadecimal ASCII characters preceded by the '#' character to a file
- Process `so.fwrite.hex.int64` - Write a 64-bit integer as hexadecimal ASCII characters preceded by the '#' character to a file
- Process `so.fwrite.int` - Write to the specified file stream an integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.fwrite.int32` - Write to the specified file stream a 32-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.fwrite.int64` - Write to the specified file stream a 64-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.fwrite.nl` - Write a newline to a stream
- Process `so.fwrite.real32` - Write a single precision real as decimal ASCII characters to a stream
- Process `so.fwrite.real64` - Write a double precision real as decimal ASCII characters to a stream
- Process `so.fwrite.string` - Write a string to a stream
- Process `so.fwrite.string.nl` - Write a string appended by a newline to a stream
- Process `so.open.temp` - Open a temporary file in spm.new.update mode
- Process `so.parse.command.line` - Read the server command line and parse it for specified options and associated parameters
- Process `so.popen.read` - Perform a general purpose open file for reading
- Process `so.read` - Read an unlimited number of bytes from a stream
- Process `so.read.echo.any.int` - Read an integer in either ( two's complement ) hexadecimal form or in decimal form from the keyboard, and to echo it to standard out
- Process `so.read.echo.hex.int` - Read an integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out
- Process `so.read.echo.hex.int32` - Read a 32-bit integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out
- Process `so.read.echo.hex.int64` - Read a 64-bit integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out
- Process `so.read.echo.int` - Read a string containing a representation of a decimal integer from the keyboard, and to echo it to standard out
- Process `so.read.echo.int32` - Read a string containing a representation of a 32-bit decimal integer from the keyboard, and to echo it to standard out
- Process `so.read.echo.int64` - Read a string containing a representation of a 64-bit decimal integer from the keyboard, and to echo it to standard out
- Process `so.read.echo.line` - Read a line from the keyboard, echoing it to standard out
- Process `so.read.echo.real32` - Read a string containing a representation of a single precision real in occam syntax ( though a + or - is allowed as first character ) from the keyboard and to echo it to standard out
- Process `so.read.echo.real64` - Read a string containing a representation of a double precision real in occam syntax ( though a + or - is allowed as first character ) from the keyboard and to echo it to standard out
- Process `so.read.line` - Read a line from the keyboard without echoing it
- Process `so.test.exists` - Test for the existence of a file
- Process `so.time` - Retrieve the local and UTC time from the host system
- Process `so.time.to.ascii` - Convert the number of seconds since the midnight before 1st January 1970 into a formatted time and date
- Process `so.time.to.date` - Convert the number of seconds since the midnight before 1st January 1970 into the associated time and date
- Process `so.today.ascii` - Give the time and date, in formatted form, of when this routine was called
- Process `so.today.date` - Give the time and date, in the form of six integers, of when this routine was called
- Process `so.version` - Return identification information about the server and the host that it is running on
- Process `so.write` - Write an unlimited number of bytes to a stream
- Process `so.write.char` - Write a single character to standard out
- Process `so.write.hex.int` - Write an integer as hexadecimal ASCII characters preceded by the '#' character to standard out
- Process `so.write.hex.int32` - Write a 32-bit integer as hexadecimal ASCII characters preceded by the '#' character to standard out
- Process `so.write.hex.int64` - Write a 64-bit integer as hexadecimal ASCII characters preceded by the '#' character to standard out
- Process `so.write.int` - Write to standard out an integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.write.int32` - Write to standard out a 32-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.write.int64` - Write to standard out a 64-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width
- Process `so.write.nl` - Write a newline to standard out
- Process `so.write.real32` - Write a single precision real as decimal ASCII characters to standard out
- Process `so.write.real64` - Write a double precision real as decimal ASCII characters to standard out
- Process `so.write.string` - Write a string to standard out
- Process `so.write.string.nl` - Write a string appended by a newline to standard out
- Process `sp.buffer` - Act as a communication buffer
- Process `sp.close` - Close a stream
- Process `sp.commandline` - Return the command line passed to the server on invocation
- Process `sp.core` - Return the contents of the root transputer's memory as peeked from the transputer when the server was invoked with the analyse option
- Process `sp.eof` - Test whether the specified stream has end of file status or not
- Process `sp.exit` - Terminate the server
- Process `sp.ferror` - Test for the occurrence of an error on the specified stream
- Process `sp.flush` - Flush the specified output stream
- Process `sp.getenv` - Return the contents of an environment variable from whatever host is being used
- Process `sp.gets` - Read a line from the specified input stream
- Process `sp.multiplexor` - Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels
- Process `sp.open` - Open a file
- Process `sp.overlapped.buffer` - Act as two almost independent buffers
- Process `sp.overlapped.multiplexor` - Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels, where the multiplexing is overlapped so that output through this routine can continue independently of the receipt of replies
- Process `sp.overlapped.pri.multiplexor` - Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels, where the multiplexing is overlapped so that output through this routine can continue independently of the receipt of replies
- Process `sp.pollkey` - Read a single character from the keyboard, without waiting for one if there is none
- Process `sp.pri.multiplexor` - Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels
- Process `sp.puts` - Write a line to the specified output stream
- Process `sp.read` - Read a limited number of bytes from a stream
- Process `sp.receive.packet` - Receive an SP protocol packet
- Process `sp.remove` - Delete the specified file
- Process `sp.rename` - Rename the specified file
- Process `sp.seek` - Set the file position for the specified stream
- Process `sp.send.packet` - Send an SP protocol packet
- Process `sp.system` - Execute a command on the host system
- Process `sp.tell` - Return the current file position for the specified stream
- Process `sp.time` - Retrieve the local and UTC time from the host system
- Process `sp.version` - Return identification information about the server and the host that it is running on
- Process `sp.write` - Write an unlimited number of bytes to a stream

## Declarations

### `version.occ`:45Process `sp.version`

`PROC sp.version (CHAN OF SP fs, ts, BYTE version, host, os, board, result)`

Return identification information about the server and the host that it is running on.

If any of the information ( except result ) has the value zero then that information is not available. The parameter version cannot distinguish between e.g. 1.41 and 1.42.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`BYTE` | `version` | on division by 10 this gives the version of the server
`BYTE` | `host` | identifies the host via sph. constants
`BYTE` | `os` | identifies the host environment via spo. constants
`BYTE` | `board` | identifies the interface board via spb. constants
`BYTE` | `result` | spr.ok if the request was successful; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `version.occ`:70Process `so.version`

`PROC so.version (CHAN OF SP fs, ts, BYTE version, host, os, board)`

Return identification information about the server and the host that it is running on.

If any of the information has the value zero then that information is not available. The parameter version cannot distinguish between e.g. 1.41 and 1.42.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`BYTE` | `version` | on division by 10 this gives the version of the server
`BYTE` | `host` | identifies the host via sph. constants
`BYTE` | `os` | identifies the host environment via spo. constants
`BYTE` | `board` | identifies the interface board via spb. constants

### `soread.occ`:39Process `so.read`

`PROC so.read (CHAN OF SP fs, ts, VAL INT32 streamid, INT bytes.read, []BYTE data)`

Read an unlimited number of bytes from a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to be read from
`INT` | `bytes.read` | this gives the number of bytes read from the file; these bytes will be [data FROM 0 FOR bytes.read]; if bytes.read <> (SIZE data) then either an error occurred or the end of the file was reached.
`[]BYTE` | `data` | this contains the bytes read from the file; the number of bytes requested to be read is (SIZE data).

### `reint64.occ`:42Process `so.read.echo.int64`

`PROC so.read.echo.int64 (CHAN OF SP fs, ts, INT64 n, BOOL error)`

Read a string containing a representation of a 64-bit decimal integer from the keyboard, and to echo it to standard out.

The integer may commence with a + or a - sign. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT64` | `n` | if error is FALSE, the value of the integer read; otherwise undefined
`BOOL` | `error` | FALSE if nothing went wrong in the operation; otherwise TRUE: 1) if the integer read overflows the INT64 range 2) if a non-numeric character is found in the input string ( other than a + or - in the first character position )

### `rename.occ`:56Process `sp.rename`

`PROC sp.rename (CHAN OF SP fs, ts, VAL []BYTE oldfname, newfname, BYTE result)`

Rename the specified file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `oldfname` | the present name of the file to be renamed
`VAL []BYTE` | `newfname` | the desired name of the file to be renamed

`BYTE`

`result`

equals spr.ok if the renaming was successful; otherwise takes on a value indicating what went wrong: spr.bad.packet.size the combined lengths of oldname and newname is too large - it must be less than sp.max.renamename.size spr.bad.name either or both of the filenames are null >=spr.operation.failed the renaming failed - see hostio.inc or iserver documentation for further details

### `spsocore.occ`:51Process `sp.core`

`PROC sp.core (CHAN OF SP fs, ts, VAL INT32 offset, INT bytes.read, []BYTE data, BYTE result)`

Return the contents of the root transputer's memory as peeked from the transputer when the server was invoked with the analyse option.

If offset + (SIZE data) is larger than the total memory peeked then only those bytes from offset up to the end of that memory peeked are returned in data. If both offset and SIZE data are zero, the routine fails if the memory was not peeked, succeeds otherwise.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `offset` | this gives the offset from base of memory ( (MOSTNEG INT) ) of the memory segment to be read ( so offset should be non-negative ); result will be >= spr.operation.failed if offset is larger than the amount of memory that was peeked
`INT` | `bytes.read` | the number of bytes read, which will be [data FROM 0 FOR bytes.read], if result = spr.ok; otherwise will be zero
`[]BYTE` | `data` | contains the contents of the memory read; (SIZE data) is the amount of memory in bytes that is requested to be read

`BYTE`

`result`

equal to spr.ok if the peeked memory was successfully returned; otherwise takes on a value indicating what the problem was: spr.bad.packet.size data is too large, (SIZE data) > sp.max.corerequest.size >=spr.operation.failed the operation failed or the transputer was not analysed when the server was invoked or offset is greater than the amount of memory peeked - refer to hostio.inc or iserver documentation for further details

### `spwrite.occ`:57Process `sp.write`

`PROC sp.write (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE data, INT length, BYTE result)`

Write an unlimited number of bytes to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to write to
`VAL []BYTE` | `data` | a string of bytes ALL of which are to be written to the file
`INT` | `length` | this gives the number of bytes written; if length <> (SIZE data) then an error occurred
`BYTE` | `result` | spr.ok if the request was successful; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `popen.occ`:66Process `so.popen.read`

`PROC so.popen.read (CHAN OF SP fs, ts, VAL []BYTE filename, path.variable.name, VAL BYTE open.type, INT full.len, []BYTE full.name, INT32 stream.id, BYTE result)`

Perform a general purpose open file for reading.

This procedure performs the following actions: 1. An attempt is made to open the file as given by filename ( so if there is no directory part to filename the current directory will be tried ); 2. If the attempt in 1 is not successful and there is no explicit directory part to filename, the path is searched for the file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `filename` | a string with the name of the file to be opened. There may be an explicit directory part to the file's name.
`VAL []BYTE` | `path.variable.name` | a string holding the name of a path environment variable; there is a limit imposed on the number of characters accepted from sp.getenv for the environment variable contents: the limit is imposed by this routine and is given by 507 ( called path.string.size in the program text ).
`VAL BYTE` | `open.type` | either spt.binary, for a file containing raw bytes only or spt.text, for a file stored as text records separated by newlines
`INT` | `full.len` | the number of characters in full.name if result is spr.ok; undefined otherwise
`[]BYTE` | `full.name` | if result is spr.ok, [full.name FROM 0 FOR full.len] is the name of the file that was successfully opened; undefined otherwise. full.name clearly should be at least as large as filename.
`INT32` | `stream.id` | if result is spr.ok, the identification number of the stream associated with the file that was opened; undefined otherwise

`BYTE`

`result`

spr.ok if a file was opened successfully; otherwise some value indicating what went wrong: spr.bad.packet.size (SIZE filename) > sp.max.openname.size or (SIZE path.variable.name) > sp.max.getenvname.size spr.bad.name null file name supplied spr.bad.type invalid file type specified spr.full.name.too.short (SIZE full.name) not large enough to hold name of a file to open spr.buffer.overflow length of environment string > 507 >=spr.operation.failed the open failed or could not read environment string - see hostio.inc or iserver documentation for more details

### `eof.occ`:33Process `sp.eof`

`PROC sp.eof (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)`

Test whether the specified stream has end of file status or not.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to test
`BYTE` | `result` | equals spr.ok if end of file status is set; >= spr.operation.failed if the end of file status has not been set

### `reint32.occ`:42Process `so.read.echo.int32`

`PROC so.read.echo.int32 (CHAN OF SP fs, ts, INT32 n, BOOL error)`

Read a string containing a representation of a 32-bit decimal integer from the keyboard, and to echo it to standard out.

The integer may commence with a + or a - sign. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT32` | `n` | if error is FALSE, the value of the integer read; undefined otherwise
`BOOL` | `error` | FALSE if nothing went wrong in the operation; otherwise TRUE: 1) if the integer read overflows the INT32 range 2) if a non-numeric character is found in the input string ( other than a + or - in the first character position )

### `ask.occ`:53Process `so.ask`

`PROC so.ask (CHAN OF SP fs, ts, VAL []BYTE prompt, replies, VAL BOOL display.possible.replies, echo.reply, INT reply.number)`

Provide a general purpose routine for interactively asking a user of a program a question requiring only a one character answer.

After the prompt and possibly the printable replies, " ? " is output and a valid key is waited for from the keyboard; invalid keys are ignored.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `prompt` | the prompt to be displayed on the screen to the user, but any list of possible replies and a question mark will be taken care of outside of this prompt
`VAL []BYTE` | `replies` | the possible single character replies allowed, which do not necessarily need to be printable
`VAL BOOL` | `display.possible.replies` | if TRUE the printable replies are displayed ( in upper case ) inside round brackets with commas inbetween each character, this display being one space after the given prompt; if FALSE then this is not done
`VAL BOOL` | `echo.reply` | if TRUE then the reply typed at the keyboard by the user is echoed if it is printable, and it is echoed as an upper case letter if a letter; if FALSE the reply typed is not echoed
`INT` | `reply.number` | an integer corresponding to the reply typed, where 0 is associated with the first possible reply, 1 with the second possible reply, etc., where the order is as in replies

### `ovprimux.occ`:68Process `sp.overlapped.pri.multiplexor`

`PROC sp.overlapped.pri.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper, []INT queue)`

Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels, where the multiplexing is overlapped so that output through this routine can continue independently of the receipt of replies.

There is a relative priority to the input channels: from.user[ i ] is of higher priority than from.user[ j ] where i < j.

It is an error if the size of from.user is different to that of to.user. It is permissible for the size of from.user ( and hence to.user ) to be zero. The maximum number of bytes that can be channelled through this routine in each direction is sp.max.packet.data.size. It is assumed that replies for messages are received in the same sequence as the messages are sent.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine
`CHAN OF SP` | `ts` | output from this routine
`[]CHAN OF SP` | `from.user` | input to this routine
`[]CHAN OF SP` | `to.user` | output from this routine
`CHAN OF BOOL` | `stopper` | input to this routine: TRUE or FALSE received on this channel will cause the routine to stop listening on the from.user channels and wait until all replies have been received before terminating; this channel has the highest priority of all input channels

`[]INT`

`queue`

the values in queue on entry are irrelevant but the size of it is the maximum number of communications that can be output through this routine before a reply is received and to be passed back; the values in queue on termination are equally irrelevant; queue is used for storage only; if it is of zero length then no communication can be done and the routine simply waits on stopper for an input which immediately causes termination of this routine

### `fwstring.occ`:54Process `so.fwrite.string`

`PROC so.fwrite.string (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE string, BYTE result)`

Write a string to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write the string to
`VAL []BYTE` | `string` | the string to be written, which can be any length
`BYTE` | `result` | spr.ok if the string was written; spr.notok if not all of the string was written

### `fwstring.occ`:107Process `so.fwrite.char`

`PROC so.fwrite.char (CHAN OF SP fs, ts, VAL INT32 streamid, VAL BYTE char, BYTE result)`

Write a single character to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write to
`VAL BYTE` | `char` | the single character to write
`BYTE` | `result` | spr.ok if the character was written; otherwise spr.notok

### `fwstring.occ`:139Process `so.fwrite.string.nl`

`PROC so.fwrite.string.nl (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE string, BYTE result)`

Write a string appended by a newline to a stream.

The newline sequence is appended by this routine.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write the string to
`VAL []BYTE` | `string` | the string to be written, which can be any length
`BYTE` | `result` | spr.ok if the string was successfully written; spr.notok if not all of the string was written; if >= spr.operation.failed refer to hostio.inc or iserver documentation for further details

### `fwstring.occ`:194Process `so.fwrite.nl`

`PROC so.fwrite.nl (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)`

Write a newline to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write to
`BYTE` | `result` | spr.ok if the newline was successfully written; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `wint64.occ`:45Process `so.fwrite.int64`

`PROC so.fwrite.int64 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT64 n, VAL INT width, BYTE result)`

Write to the specified file stream a 64-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative field width is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to which the string representing the integer is to be sent
`VAL INT64` | `n` | the 64-bit integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string
`BYTE` | `result` | equal to spr.ok if the string was written all right; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `wint64.occ`:95Process `so.write.int64`

`PROC so.write.int64 (CHAN OF SP fs, ts, VAL INT64 n, VAL INT width)`

Write to standard out a 64-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative field width is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT64` | `n` | the 64-bit integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string

### `seek.occ`:46Process `sp.seek`

`PROC sp.seek (CHAN OF SP fs, ts, VAL INT32 streamid, offset, origin, BYTE result)`

Set the file position for the specified stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream associated with the file the position of which is to be set
`VAL INT32` | `offset` | the offset from origin of the new position for reading or writing. For a binary file the new position will be offset bytes, perhaps negative, from the position defined by origin. For a text file offset must be zero or a value returned by so.tell; in the latter case origin must be spo.start, and offset greater than or equal to zero.
`VAL INT32` | `origin` | one of spo.start the start of the file spo.current the current position in the file spo.end the end of the file
`BYTE` | `result` | equal to spr.ok if the file position was successfully set; otherwise takes on a value indicating what the problem was: spr.bad.origin invalid origin >=spr.operation.failed the seek failed - see hostio.inc or iserver documentation for further details

### `rehint32.occ`:47Process `so.read.echo.hex.int32`

`PROC so.read.echo.hex.int32 (CHAN OF SP fs, ts, INT32 n, BOOL error)`

Read a 32-bit integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out.

The hexadecimal number must begin with one of '#', '$' or '%'; a sign is not allowed ( nor necessary since the most significant bit indicates the sign ). A '#' and '$' mean exactly the same thing: the following digits form a hex integer. A '%' means add the given hex integer to MOSTNEG INT32 using modulo arithmetic to give the result. Both upper and lower case hex digits are permissible. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT32` | `n` | if error is FALSE, the value of the hexadecimal number read; otherwise undefined
`BOOL` | `error` | FALSE if everything was in order; TRUE otherwise: 1) if the integer overflows the INT32 range; 2) if there is a non-hex character in the string read from the keyboard ( other than #, $, or % in the first character position )

### `wstring.occ`:50Process `so.write.string`

`PROC so.write.string (CHAN OF SP fs, ts, VAL []BYTE string)`

Write a string to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `string` | the string to be written, which can be any length

### `wstring.occ`:68Process `so.write.char`

`PROC so.write.char (CHAN OF SP fs, ts, VAL BYTE char)`

Write a single character to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL BYTE` | `char` | the single character to write

### `wstring.occ`:82Process `so.write.string.nl`

`PROC so.write.string.nl (CHAN OF SP fs, ts, VAL []BYTE string)`

Write a string appended by a newline to standard out.

The newline sequence is appended by this routine.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `string` | the string to be written, which can be any length

### `wstring.occ`:127Process `so.write.nl`

`PROC so.write.nl (CHAN OF SP fs, ts)`

Write a newline to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server

### `wreal32.occ`:43Process `so.fwrite.real32`

`PROC so.fwrite.real32 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL REAL32 r, VAL INT Ip, Dp, BYTE result)`

Write a single precision real as decimal ASCII characters to a stream.

Behaves as an invalid process if the string to write is longer than 24 characters.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write the real to
`VAL REAL32` | `r` | a single precision real
`VAL INT` | `Ip`, `Dp` | formatting values; see REAL32TOSTRING for their effect
`BYTE` | `result` | spr.ok if the string representing the real was written; otherwise not all of the characters were written in which case spr.notok

### `wreal32.occ`:75Process `so.write.real32`

`PROC so.write.real32 (CHAN OF SP fs, ts, VAL REAL32 r, VAL INT Ip, Dp)`

Write a single precision real as decimal ASCII characters to standard out.

Behaves as an invalid process if the string to write is longer than 24 characters.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL REAL32` | `r` | a single precision real
`VAL INT` | `Ip`, `Dp` | formatting values; see REAL32TOSTRING for their effect

### `wint.occ`:45Process `so.fwrite.int`

`PROC so.fwrite.int (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT n, width, BYTE result)`

Write to the specified file stream an integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative value is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to which the string representing the integer is to be sent
`VAL INT` | `n` | the integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string
`BYTE` | `result` | equal to spr.ok if the string was written all right; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `wint.occ`:95Process `so.write.int`

`PROC so.write.int (CHAN OF SP fs, ts, VAL INT n, width)`

Write to standard out an integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative field width is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT` | `n` | the integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string

### `flush.occ`:41Process `sp.flush`

`PROC sp.flush (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)`

Flush the specified output stream.

To flush means to write out any internally buffered data to the stream that it is associated with. The stream remains open.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to be flushed
`BYTE` | `result` | equal to spr.ok stream successfully flushed; otherwise >= spr.operation.failed - see hostio.inc or iserver documentation for further details

### `ovbuffer.occ`:44Process `sp.overlapped.buffer`

`PROC sp.overlapped.buffer (CHAN OF SP fs, ts, from.user, to.user, CHAN OF BOOL stopper)`

Act as two almost independent buffers.

The dependence of the buffers is given by the fact that the number of communications through one buffer ( buffer2 ) must match the number through the other buffer ( buffer1 ) before the routine will terminate. No more than sp.max.packet.data.size bytes can be buffered in each of the buffers.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine and to buffer2
`CHAN OF SP` | `ts` | output from this routine and from buffer1
`CHAN OF SP` | `from.user` | input to this routine and to buffer1
`CHAN OF SP` | `to.user` | output from this routine and from buffer2
`CHAN OF BOOL` | `stopper` | input to this routine; TRUE or FALSE received will cause buffer1 to stop listening on the ts channel and to terminate when buffer2 has passed through the same number of reply communications on the fs/to.user channels as buffer1 sent on the from.user/ts channels. buffer1 terminates immediately after buffer1; the whole routine then terminates.

### `wreal64.occ`:43Process `so.fwrite.real64`

`PROC so.fwrite.real64 (CHAN OF SP fs, ts, VAL INT32 streamid, VAL REAL64 r, VAL INT Ip, Dp, BYTE result)`

Write a double precision real as decimal ASCII characters to a stream.

Behaves as an invalid process if the string to write is longer than 30 characters.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write the real to
`VAL REAL64` | `r` | a double precision real
`VAL INT` | `Ip`, `Dp` | formatting values; see REAL64TOSTRING for their effect
`BYTE` | `result` | spr.ok if the string representing the real was written; otherwise not all of the characters were written in which case spr.notok

### `wreal64.occ`:75Process `so.write.real64`

`PROC so.write.real64 (CHAN OF SP fs, ts, VAL REAL64 r, VAL INT Ip, Dp)`

Write a double precision real as decimal ASCII characters to standard out.

Behaves as an invalid process if the string to write is longer than 30 characters.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL REAL64` | `r` | a double precision real
`VAL INT` | `Ip`, `Dp` | formatting values; see REAL64TOSTRING for their effect

### `ovmux.occ`:69Process `sp.overlapped.multiplexor`

`PROC sp.overlapped.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper, []INT queue)`

Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels, where the multiplexing is overlapped so that output through this routine can continue independently of the receipt of replies.

It is an error if the size of from.user is different to that of to.user. It is permissible for the size of from.user ( and hence to.user ) to be zero. The maximum number of bytes that can be channelled through this routine in each direction is sp.max.packet.data.size. It is assumed that replies for messages are received in the same sequence as the messages are sent. To attempt some degree of fairness, there is a heirarchy of priorities from from.user with index i for SIZE from.user, using modulo SIZE from.user on the indexes, with i starting from 0 and incrementing by one after each input accepted.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine
`CHAN OF SP` | `ts` | output from this routine
`[]CHAN OF SP` | `from.user` | input to this routine
`[]CHAN OF SP` | `to.user` | output from this routine
`CHAN OF BOOL` | `stopper` | input to this routine: TRUE or FALSE received on this channel will cause the routine to stop listening on the from.user channels and wait until all replies have been received before terminating; stopper has the highest priority amongst the channels

`[]INT`

`queue`

the values in queue on entry are irrelevant but the size of it is the maximum number of communications that can be output through this routine before a reply is received and to be passed back; the values in queue on termination are equally irrelevant; queue is used for storage only; if it is of zero length then no communication can be done and the routine simply waits on stopper for an input which immediately causes termination of this routine

### `sowrite.occ`:37Process `so.write`

`PROC so.write (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE data, INT length)`

Write an unlimited number of bytes to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to write to
`VAL []BYTE` | `data` | a string of bytes ALL of which are to be written to the file
`INT` | `length` | this gives the number of bytes written; if length <> (SIZE data) then an error occurred

### `remove.occ`:55Process `sp.remove`

`PROC sp.remove (CHAN OF SP fs, ts, VAL []BYTE fname, BYTE result)`

Delete the specified file.

No path environment variable is used; what is in name is all that is considered.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `fname` | the name of the file to be deleted; the filename must fill all of the bytes of name
`BYTE` | `result` | equals spr.ok if the file was removed; otherwise takes on a value indicating what went wrong: spr.bad.packet.size name too large, (SIZE name) > sp.max.removename.size spr.bad.name name is null >=spr.operation.failed the delete failed - see hostio.inc or iserver documentation for further details

### `rehint64.occ`:47Process `so.read.echo.hex.int64`

`PROC so.read.echo.hex.int64 (CHAN OF SP fs, ts, INT64 n, BOOL error)`

Read a 64-bit integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out.

The hexadecimal number must begin with one of '#', '$' or '%'; a sign is not allowed ( nor necessary since the most significant bit indicates the sign ). A '#' and '$' mean exactly the same thing: the following digits form a hex integer. A '%' means add the given hex integer to MOSTNEG INT64 using modulo arithmetic to give the result. Both upper and lower case hex digits are permissible. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT64` | `n` | if error is FALSE, the value of the hexadecimal number read; otherwise undefined
`BOOL` | `error` | FALSE if everything was in order; TRUE otherwise: 1) if the integer overflows the INT64 range; 2) if there is a non-hex character in the string read from the keyboard ( other than #, $, or % in the first character position )

### `wint32.occ`:45Process `so.fwrite.int32`

`PROC so.fwrite.int32 (CHAN OF SP fs, ts, VAL INT32 streamid, n, VAL INT width, BYTE result)`

Write to the specified file stream a 32-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative field width is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to which the string representing the integer is to be sent
`VAL INT32` | `n` | the 32-bit integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string
`BYTE` | `result` | equal to spr.ok if the string was written all right; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `wint32.occ`:94Process `so.write.int32`

`PROC so.write.int32 (CHAN OF SP fs, ts, VAL INT32 n, VAL INT width)`

Write to standard out a 32-bit integer as decimal ASCII digits, padded out with leading spaces and an optional sign to the specified field width.

If the field width is too small for the number, then it is widened as necessary; a zero value for the field width will give minimum width; a negative field width is an error.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `n` | the 32-bit integer that is desired to be written
`VAL INT` | `width` | the desired field width of the string

### `gets.occ`:79Process `sp.gets`

`PROC sp.gets (CHAN OF SP fs, ts, VAL INT32 streamid, INT bytes.read, []BYTE data, BYTE result)`

Read a line from the specified input stream.

Characters are read until a newline sequence is found, the end of the file is reached, or the number of characters is not less than sp.max.readbuffer.size. If a newline sequence is found, it is not included in data.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to be read from
`INT` | `bytes.read` | if result is spr.ok this is the number of bytes read; if result is spr.buffer.overflow then this will be (SIZE data) and will be less than the actual number of bytes read from the file; otherwise zero.
`[]BYTE` | `data` | an array of bytes holding line read if result is spr.ok; or holding a truncation of the line if result is spr.buffer.overflow. It is undefined otherwise. If result is spr.ok or spr.buffer.overflow then the bytes will be [data FROM 0 FOR bytes.read].

`BYTE`

`result`

equal to spr.ok if line was successfully read; otherwise takes on a value indicating what went wrong: spr.bad.packet.size data is too large, (SIZE data) > sp.max.readbuffer.size spr.buffer.overflow data not large enough to hold the line, in which case the line is truncated to fit >=spr.operation.failed the read failed, either because the end of the file has been reached or some error occurred - see hostio.inc or iserver documentation for further details

### `ferror.occ`:45Process `sp.ferror`

`PROC sp.ferror (CHAN OF SP fs, ts, VAL INT32 streamid, INT32 error.no, INT length, []BYTE message, BYTE result)`

Test for the occurrence of an error on the specified stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to be tested for error
`INT32` | `error.no` | a host defined error number
`INT` | `length` | the number of bytes in message. Equal to zero if result >= spr.operation.failed.
`[]BYTE` | `message` | if result is not spr.operation.failed then this contains a ( possibly null ) message corresponding to the last file error on the specified stream; this message is [message FROM 0 FOR length]
`BYTE` | `result` | equals spr.ok if there was an error on the specified stream and the message corresponding to it fits into message; equals spr.buffer.overflow if there was an error on the specified stream but the message corresponding to it is too large to fit into message, in which case it is truncated to fit; >= spr.operation.failed if there was no error on the specified stream

### `exists.occ`:36Process `so.test.exists`

`PROC so.test.exists (CHAN OF SP fs, ts, VAL []BYTE filename, BOOL exists)`

Test for the existence of a file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `filename` | the name of the file to test for the existence of. The name of the file must fit exactly into filename, i.e. there are (SIZE filename) characters in the name of the file. A directory specification may form part of filename.
`BOOL` | `exists` | TRUE if the file exists; FALSE otherwise

### `echoline.occ`:47Process `so.read.echo.line`

`PROC so.read.echo.line (CHAN OF SP fs, ts, INT len, []BYTE line, BYTE result)`

Read a line from the keyboard, echoing it to standard out.

The line to be read is considered terminated by a carriage return, ie ASCII ^M, which has value #0D = 13. This carriage return is not included in the line, and nor is a newline ( ASCII ^J, #0A = 10 ) if present in the input. Carriage return and newline are not echoed. If an error occurs whilst reading the line this routine terminates immediately.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT` | `len` | the number of bytes in line that form the line that was read
`[]BYTE` | `line` | if result = spr.ok, the line that was read is in the first len bytes, the remaining bytes being undefined or if the supplied byte array was not large enough for the read line, the read line is truncated to fit; otherwise undefined
`BYTE` | `result` | spr.ok if no problems encountered; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `whint64.occ`:48Process `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)`

Write a 64-bit integer as hexadecimal ASCII characters preceded by the '#' character to a file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write to
`VAL INT64` | `n` | the 64-bit integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error
`BYTE` | `result` | spr.ok if the integer was successfully written; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `whint64.occ`:129Process `so.write.hex.int64`

`PROC so.write.hex.int64 (CHAN OF SP fs, ts, VAL INT64 n, VAL INT width)`

Write a 64-bit integer as hexadecimal ASCII characters preceded by the '#' character to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT64` | `n` | the 64-bit integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error

### `primux.occ`:59Process `sp.pri.multiplexor`

`PROC sp.pri.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper)`

Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels.

There is a relative priority to the input channels: from.user[ i ] is of higher priority than from.user[ j ] where i < j.

It is an error if the number of channels in from.user is different to that in to.user. It is permissible for the number of channels in from.user ( and hence also to.user ) to be zero. No more than sp.max.packet.data.size bytes can be buffered as they passes through this routine. Primary input to this routine must be on the guard input channels from.user[ i ] or stopper. Input on from.user[ i ] is stored, output on ts, then a reply is expected on fs; this reply is stored and then output on to.user[ i ], and all this must finish before any new input can be received on any of the from.user channels or stopper.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine
`CHAN OF SP` | `ts` | output from this routine
`[]CHAN OF SP` | `from.user` | input to this routine
`[]CHAN OF SP` | `to.user` | output from this routine
`CHAN OF BOOL` | `stopper` | input to this routine: TRUE or FALSE received on this channel will cause the routine to terminate; this channel has the lowest priority of all input channels.

### `rereal64.occ`:43Process `so.read.echo.real64`

`PROC so.read.echo.real64 (CHAN OF SP fs, ts, REAL64 n, BOOL error)`

Read a string containing a representation of a double precision real in occam syntax ( though a + or - is allowed as first character ) from the keyboard and to echo it to standard out.

The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`REAL64` | `n` | if error is FALSE, the IEEE double precision format of the real that was read, otherwise undefined
`BOOL` | `error` | FALSE if the real was read and converted to binary without problem; TRUE otherwise - if the string read does not conform to the syntax of an occam real number, other than the fact that a plus or minus sign is allowed as the first character

### `rehint.occ`:47Process `so.read.echo.hex.int`

`PROC so.read.echo.hex.int (CHAN OF SP fs, ts, INT n, BOOL error)`

Read an integer in ( two's complement ) hexadecimal form from the keyboard, and to echo it to standard out.

The hexadecimal number must begin with one of '#', '$' or '%'; a sign is not allowed ( nor necessary since the most significant bit indicates the sign ). A '#' and '$' mean exactly the same thing: the following digits form a hex integer. A '%' means add the given hex integer to MOSTNEG INT using modulo arithmetic to give the result. Both upper and lower case hex digits are permissible. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT` | `n` | if error is FALSE, the value of the hexadecimal number read; otherwise undefined
`BOOL` | `error` | FALSE if everything was in order; TRUE otherwise: 1) if the integer overflows the INT range; 2) if there is a non-hex character in the string read from the keyboard ( other than #, $, or % in the first character position )

### `opentemp.occ`:51Process `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)`

Open a temporary file in spm.new.update mode.

The file will be opened in the current directory. The file name of the temporary file is chosen as follows: the first name tried is TEMP00; if there already exists such a file then TEMP01 is tried; if there already exists such a file then TEMP02 is tried; etc. up to TEMP99 when, if such a file exists then TEM100 is tried, and so on up to TEM999, at which point, if such a file exists, TE1000 is tried, and so on up to TE9999, which is the last name tried, i.e. a maximum of 10,000 possible temporary files can be created by this routine.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL BYTE` | `type` | either spt.binary or spt.text
`[so.temp.filename.length]BYTE` | `filename` | the name of the file opened
`INT32` | `streamid` | if result is spr.ok, the identification number of the stream associated with the file that was opened; undefined otherwise
`BYTE` | `result` | spr.ok if all went well; otherwise takes on a value indicating what went wrong: spr.bad.type invalid type spr.notok there are already 10,000 such temp files >=spr.operation.failed the open failed - refer to hostio.inc or iserver documentation for further details

### `open.occ`:78Process `sp.open`

`PROC sp.open (CHAN OF SP fs, ts, VAL []BYTE fname, VAL BYTE type, mode, INT32 streamid, BYTE result)`

Open a file.

No path environment variable is used to locate the file; what is in name is all that is used ( cf. so.popen.read )

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `fname` | the name of the file to be opened. The name of the file must fit exactly into name, i.e. there are (SIZE name) characters in the name of the file. A directory specification may form part of name.
`VAL BYTE` | `type` | either spt.binary, for a file containing raw bytes only or spt.text, for a file stored as text records separated by newlines

`VAL BYTE`

`mode`

one of spm.input open existing file for reading spm.output open new file, or truncate existing one, for writing spm.append open new file, or append to existing one, for writing spm.existing.update open existing file for update ( reading and writing ), starting at the 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 existing one, for update When a file is opened for update then the resulting stream may be used for input and output.

`INT32` | `streamid` | if result is spr.ok, the identification number of the stream associated with the file that was opened; undefined otherwise
`BYTE` | `result` | spr.ok if the file was successfully opened; otherwise it takes on a value indicating what went wrong: spr.bad.packet.size name too large: (SIZE name) > sp.max.openname.size spr.bad.name null file name spr.bad.type invalid type spr.bad.mode invalid mode >=spr.operation.failed the open failed - see hostio.inc or iserver documentation for further details

### `parse.occ`:62Process `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)`

Read the server command line and parse it for specified options and associated parameters.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server

`VAL [][]BYTE`

`option.strings`

a list of all possible options. These options must not be longer than 256 bytes and any letters should be in upper case, even though the options as given by the user on the command line are case insensitive. To read a parameter that has no preceding option ( such as a filename ) then the first option string should contain only spaces. Because all of these option strings must be the same length, trailing spaces should be used to pad.

`VAL []INT` | `option.parameters.required` | indicates if the corresponding option ( in option.strings ) requires a parameter. The permissible values are: spopt.never never takes a parameter spopt.maybe optionally takes a parameter spopt.always must take a parameter
`[]BOOL` | `option.exists` | TRUE if the corresponding option was present on the command line; otherwise FALSE
`[][2]INT` | `option.parameters` | 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 of this parameter, as long as an error did not occur
`INT` | `error.len` | zero if no error occurs whilst the command line is being parsed; otherwise greater than zero and is the number of bytes in line ( which will contain an error message )

`[]BYTE`

`line`

contains the command line as supplied by the server if there was no error ( in which case error.len is zero ); otherwise contains an error message ( the length of which is given by error.len ). There is no limitation on the size of line - if it is not long enough for an error message then that message is truncated to fit; if not long enough for the command line, then an error message is put into line.

### `tell.occ`:39Process `sp.tell`

`PROC sp.tell (CHAN OF SP fs, ts, VAL INT32 streamid, INT32 position, BYTE result)`

Return the current file position for the specified stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream associated whith the file the reading/writing position of which is desired
`INT32` | `position` | the current file position
`BYTE` | `result` | equal to spr.ok if the file position determined; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `system.occ`:54Process `sp.system`

`PROC sp.system (CHAN OF SP fs, ts, VAL []BYTE command, INT32 status, BYTE result)`

Execute a command on the host system.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `command` | the command to be executed, which may be null
`INT32` | `status` | if command is not null and result is spr.ok then this is the return value of the command, which is host dependent
`BYTE` | `result` | equal to spr.ok if a host command processor exists; otherwise: spr.bad.packet.size command too large, (SIZE command) > sp.max.systemcommand.size >=spr.operation.failed the operation failed - see hostio.inc or iserver documentation for further details

### `reint.occ`:42Process `so.read.echo.int`

`PROC so.read.echo.int (CHAN OF SP fs, ts, INT n, BOOL error)`

Read a string containing a representation of a decimal integer from the keyboard, and to echo it to standard out.

The integer may commence with a + or a - sign. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT` | `n` | if error is FALSE, the value of the integer read; otherwise undefined
`BOOL` | `error` | FALSE if nothing went wrong in the operation; otherwise TRUE: 1) if the integer read overflows the INT range 2) if a non-numeric character is found in the input string ( other than a + or - in the first character position )

### `readline.occ`:46Process `so.read.line`

`PROC so.read.line (CHAN OF SP fs, ts, INT len, []BYTE line, BYTE result)`

Read a line from the keyboard without echoing it.

The line to be read is considered terminated by a carriage return, ie ASCII ^M, which has value #0D = 13. This carriage return is not included in the line, and nor is a newline ( ASCII ^J, #0A = 10 ) if present in the input. If an error occurs whilst reading the line this routine terminates immediately.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT` | `len` | the number of bytes in the parameter line that form the line that was read
`[]BYTE` | `line` | if result = spr.ok, the line that was read is in the first len bytes, the remaining bytes being undefined or if the supplied byte array was not large enough for the read line, the read line is truncated to fit; otherwise undefined
`BYTE` | `result` | spr.ok if the line was successfully read; otherwise >= spr.operation.failed - see hostio.inc or iserver documentation for further details

### `packet.occ`:34Process `sp.send.packet`

`PROC sp.send.packet (CHAN OF SP ts, VAL []BYTE packet, BOOL error)`

Send an SP protocol packet.

#### Parameters:

`CHAN OF SP` | `ts` | the channel on which to send the packet
`VAL []BYTE` | `packet` | the packet to send
`BOOL` | `error` | FALSE if the packet size is greater than or equal to sp.min.packet.data.size, and is less than or equal to sp.max.packet.data.size, and is even; TRUE otherwise, in which case the packet is not sent

### `packet.occ`:54Process `sp.receive.packet`

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

Receive an SP protocol packet.

#### Parameters:

`CHAN OF SP` | `fs` | the channel on which to receive the packet
`INT16` | `length` | the number of bytes in the received packet
`[]BYTE` | `packet` | the received packet, left justified
`BOOL` | `error` | TRUE if length is greater than sp.max.packet.data.size; FALSE otherwise

### `mux.occ`:60Process `sp.multiplexor`

`PROC sp.multiplexor (CHAN OF SP fs, ts, []CHAN OF SP from.user, to.user, CHAN OF BOOL stopper)`

Multiplex any number of pairs of SP protocol channels onto a single pair of SP protocol channels.

It is an error if the number of channels in from.user is not equal to that in to.user. It is permissible for from.user ( and hence to.user ) to be null arrays. No more than sp.max.packet.data.size bytes can be buffered as they passes through this routine. Primary input to this routine must be on the guard input channels from.user[ i ] or stopper. Input on from.user[ i ] is stored, output on ts, then a reply is expected on fs; this reply is stored and then output on to.user[ i ], and all this must finish before any new input can be received on any of the from.user channels or stopper. To attempt some degree of fairness, there is a heirarchy of priorities from from.user with index i for SIZE from.user, using modulo SIZE from.user on the indexes, with i starting from 0 and incrementing by one after each input accepted.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine
`CHAN OF SP` | `ts` | output from this routine
`[]CHAN OF SP` | `from.user` | input to this routine
`[]CHAN OF SP` | `to.user` | output from this routine
`CHAN OF BOOL` | `stopper` | input to this routine: TRUE or FALSE received on this channel will cause the routine to terminate; this channel has the highest priority amongst the channels

### `rereal32.occ`:43Process `so.read.echo.real32`

`PROC so.read.echo.real32 (CHAN OF SP fs, ts, REAL32 n, BOOL error)`

Read a string containing a representation of a single precision real in occam syntax ( though a + or - is allowed as first character ) from the keyboard and to echo it to standard out.

The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`REAL32` | `n` | if error is FALSE, the IEEE single precision format of the real that was read, otherwise undefined
`BOOL` | `error` | FALSE if the real was read and converted to binary without problem; TRUE otherwise - if the string read does not conform to the syntax of an occam real number, other than the fact that a plus or minus sign is allowed as the first character

### `getenv.occ`:75Process `sp.getenv`

`PROC sp.getenv (CHAN OF SP fs, ts, VAL []BYTE name, INT length, []BYTE value, BYTE result)`

Return the contents of an environment variable from whatever host is being used.

The largest size the returned contents of an environment variable can be is limited by the functionality of the server, not by this routine.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `name` | a string containing the name of the desired environment variable. name should not have more than sp.max.getenvname.size characters in it.
`INT` | `length` | if result is spr.ok, the number of bytes in value, starting at value[ 0 ]; (SIZE value) if result is spr.buffer.overflow; zero otherwise.
`[]BYTE` | `value` | the contents of the environment variable, if result is spr.ok; truncated environment variable if result is spr.buffer.overflow; undefined otherwise.

`BYTE`

`result`

spr.ok if the environment string successfully returned; some other value otherwise, indicating the sort of problem: spr.bad.name the specified name is a null string spr.bad.packet.size (SIZE name) > sp.max.getenvname.size spr.buffer.overflow environment string too large for value; it is truncated to fit >=spr.operation.failed could not read environment string - see hostio.inc or iserver documentation for further details

### `whint32.occ`:44Process `so.fwrite.hex.int32`

`PROC so.fwrite.hex.int32 (CHAN OF SP fs, ts, VAL INT32 streamid, n, VAL INT width, BYTE result)`

Write a 32-bit integer as hexadecimal ASCII characters preceded by the '#' character to a file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write to
`VAL INT32` | `n` | the 32-bit integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error
`BYTE` | `result` | spr.ok if the integer was successfully written; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `whint32.occ`:118Process `so.write.hex.int32`

`PROC so.write.hex.int32 (CHAN OF SP fs, ts, VAL INT32 n, VAL INT width)`

Write a 32-bit integer as hexadecimal ASCII characters preceded by the '#' character to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `n` | the 32-bit integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error

### `spread.occ`:67Process `sp.read`

`PROC sp.read (CHAN OF SP fs, ts, VAL INT32 streamid, INT bytes.read, []BYTE data, BYTE result)`

Read a limited number of bytes from a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to be read from
`INT` | `bytes.read` | if result is spr.ok then this gives the number of bytes read from the file; these bytes will be [data FROM 0 FOR bytes.read]; if bytes.read <> (SIZE data) then either an error occurred or the end of the file was reached. If result is not spr.ok then bytes.read will be zero. 0 <= bytes.read <= sp.max.readbuffer.size
`[]BYTE` | `data` | if result is spr.ok then this contains the bytes read from the file; otherwise it is undefined. The number of bytes requested to be read is (SIZE data); the limit to this is sp.max.readbuffer.size.
`BYTE` | `result` | equal to spr.bad.packet.size if too many bytes asked for ie (SIZE data) > sp.max.readbuffer.size, otherwise it is equal to spr.ok

### `close.occ`:41Process `sp.close`

`PROC sp.close (CHAN OF SP fs, ts, VAL INT32 streamid, BYTE result)`

Close a stream.

Before closing the stream unwritten data is flushed or any unread buffered input is discarded.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the open stream to be closed
`BYTE` | `result` | equal to spr.ok if the stream closed properly; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details

### `buffer.occ`:42Process `sp.buffer`

`PROC sp.buffer (CHAN OF SP fs, ts, from.user, to.user, CHAN OF BOOL stopper)`

Act as a communication buffer.

No more than sp.max.packet.data.size bytes can be buffered. Primary input to this routine must be on the guard input channels from.user or stopper. Input on from.user is stored, output on ts, then a reply is expected on fs; this reply is stored and then output on to.user, and all this must finish before any new input can be received on from.user or stopper.

#### Parameters:

`CHAN OF SP` | `fs` | input to this routine
`CHAN OF SP` | `ts` | output from this routine
`CHAN OF SP` | `from.user` | input to this routine
`CHAN OF SP` | `to.user` | output from this routine
`CHAN OF BOOL` | `stopper` | input to this routine; TRUE or FALSE received will terminate this routine

### `times.occ`:38Process `so.time.to.date`

`PROC so.time.to.date (VAL INT32 input.time, [so.date.len]INT date)`

Convert the number of seconds since the midnight before 1st January 1970 into the associated time and date.

#### Parameters:

`VAL INT32` | `input.time` | the number of seconds since the midnight before 1st January 1970
`[so.date.len]INT` | `date` | an array of six integers where the elements are, index data 0 seconds past the minute 1 minutes past the hour 2 the hour in the 24 hour clock 3 the day of the month 4 the month, where January is 1 5 the year expressed fully, i.e. 4 digits

### `times.occ`:183Process `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)`

Format a time and date given in the form of six integers.

#### Parameters:

`VAL [so.date.len]INT` | `date` | an array of six integers where the elements are, index data 0 seconds past the minute 1 minutes past the hour 2 the hour in the 24 hour clock 3 the day of the month 4 the month, where January is 1 5 the year expressed fully, i.e. 4 digits
`VAL BOOL` | `long.years` | TRUE if a four digit year is desired; FALSE if a two digit year is desired, the digits being the tens and units, followed by two spaces
`VAL BOOL` | `days.first` | TRUE if date to be written with the days preceding the month ( i.e. British format ); FALSE if the month is to precede the days ( i.e. U.S. format )

`[so.time.string.len]BYTE`

`string`

an ASCII string representing the time and date as follows: "HH:MM:SS DD/MM/YY " -- long.years = FALSE; days.first = TRUE "HH:MM:SS DD/MM/YYYY" -- long.years = TRUE; days.first = TRUE "HH:MM:SS MM/DD/YY " -- long.years = FALSE; days.first = FALSE "HH:MM:SS MM/DD/YYYY" -- long.years = TRUE; days.first = FALSE where HH:MM:SS is hours, minutes and seconds, and DD/MM/YY is day, month and year

### `times.occ`:249Process `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)`

Convert the number of seconds since the midnight before 1st January 1970 into a formatted time and date

#### Parameters:

`VAL INT32` | `time` | the number of seconds since the midnight before 1st January 1970
`VAL BOOL` | `long.years` | TRUE if a four digit year is desired; FALSE if a two digit year is desired, the digits being the tens and units, followed by two spaces
`VAL BOOL` | `days.first` | TRUE if date to be written with the days preceding the month ( i.e. British format ); FALSE if the month is to precede the days ( i.e. U.S. format )

`[so.time.string.len]BYTE`

`string`

an ASCII string representing the time and date as follows: "HH:MM:SS DD/MM/YY " -- long.years = FALSE; days.first = TRUE "HH:MM:SS DD/MM/YYYY" -- long.years = TRUE; days.first = TRUE "HH:MM:SS MM/DD/YY " -- long.years = FALSE; days.first = FALSE "HH:MM:SS MM/DD/YYYY" -- long.years = TRUE; days.first = FALSE where HH:MM:SS is hours, minutes and seconds, and DD/MM/YY is day, month and year

### `times.occ`:272Process `so.today.date`

`PROC so.today.date (CHAN OF SP fs, ts, [so.date.len]INT date)`

Give the time and date, in the form of six integers, of when this routine was called.

If the time and date are unavailable all elements of date are set to zero. Local time is used.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`[so.date.len]INT` | `date` | an array of six integers where the elements are, index data 0 seconds past the minute 1 minutes past the hour 2 the hour in the 24 hour clock 3 the day of the month 4 the month, where January is 1 5 the year expressed fully, i.e. 4 digits

### `times.occ`:308Process `so.today.ascii`

`PROC so.today.ascii (CHAN OF SP fs, ts, VAL BOOL long.years, days.first, [so.time.string.len]BYTE string)`

Give the time and date, in formatted form, of when this routine was called.

If the time and date are unavailable string is filled with spaces. Local time is used.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL BOOL` | `long.years` | TRUE if a four digit year is desired; FALSE if a two digit year is desired, the digits being the tens and units, followed by two spaces
`VAL BOOL` | `days.first` | TRUE if date to be written with the days preceding the month ( i.e. British format ); FALSE if the month is to precede the days ( i.e. U.S. format )

`[so.time.string.len]BYTE`

`string`

an ASCII string representing the time and date as follows: "HH:MM:SS DD/MM/YY " -- long.years = FALSE; days.first = TRUE "HH:MM:SS DD/MM/YYYY" -- long.years = TRUE; days.first = TRUE "HH:MM:SS MM/DD/YY " -- long.years = FALSE; days.first = FALSE "HH:MM:SS MM/DD/YYYY" -- long.years = TRUE; days.first = FALSE where HH:MM:SS is hours, minutes and seconds, and DD/MM/YY is day, month and year

### `whint.occ`:48Process `so.fwrite.hex.int`

`PROC so.fwrite.hex.int (CHAN OF SP fs, ts, VAL INT32 streamid, VAL INT n, width, BYTE result)`

Write an integer as hexadecimal ASCII characters preceded by the '#' character to a stream.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to write to
`VAL INT` | `n` | the integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error
`BYTE` | `result` | spr.ok if the integer was successfully written; otherwise not all of the string could be written, in which case result takes on a value of spr.notok

### `whint.occ`:122Process `so.write.hex.int`

`PROC so.write.hex.int (CHAN OF SP fs, ts, VAL INT n, width)`

Write an integer as hexadecimal ASCII characters preceded by the '#' character to standard out.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT` | `n` | the integer to write out
`VAL INT` | `width` | the field width to use when writing the hex; 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 at the left to width characters; width does not take the '#' into account; a negative field width is an error

### `time.occ`:43Process `sp.time`

`PROC sp.time (CHAN OF SP fs, ts, INT32 localtime, UTCtime, BYTE result)`

Retrieve the local and UTC time from the host system.

Both times are expressed as the number of seconds that have elapsed since midnight on the 1st of January, 1970, and are given as unsigned INT32s UTC time used to be known as Greenwich Mean Time ( GMT )

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT32` | `localtime` | the local time
`INT32` | `UTCtime` | the Coordinated Universal Time, if available; zero if not available
`BYTE` | `result` | spr.ok if operation successful; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for details

### `time.occ`:62Process `so.time`

`PROC so.time (CHAN OF SP fs, ts, INT32 localtime, UTCtime)`

Retrieve the local and UTC time from the host system.

Both times are expressed as the number of seconds that have elapsed since midnight on the 1st of January, 1970, and are given as unsigned INT32s UTC time used to be known as Greenwich Mean Time ( GMT )

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT32` | `localtime` | the local time
`INT32` | `UTCtime` | the Coordinated Universal Time, if available; zero if not available

### `command.occ`:66Process `sp.commandline`

`PROC sp.commandline (CHAN OF SP fs, ts, VAL BYTE all, INT length, []BYTE string, BYTE result)`

Return the command line passed to the server on invocation.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL BYTE` | `all` | either sp.short.commandline, remove the server's own name, its recognised options and their parameters or sp.whole.commandline, the entire command line
`INT` | `length` | the number of bytes returned in string, starting from string[ 0 ], being zero in the case of result >= spr.operation.failed
`[]BYTE` | `string` | contains the requested command line if result = spr.ok; contains a truncation of the requested command line if result = spr.buffer.overflow; is undefined otherwise. There is no restriction on the size of string.
`BYTE` | `result` | equal to spr.ok if the command line was successfully returned; otherwise takes on a value indicating what went wrong: spr.buffer.overflow string is not long enough to contain the command line, but the latter has been truncated to fit >=spr.operation.failed the operation failed - refer to hostio.inc or iserver documentation for further details

### `reaint.occ`:52Process `so.read.echo.any.int`

`PROC so.read.echo.any.int (CHAN OF SP fs, ts, INT n, BOOL error)`

Read an integer in either ( two's complement ) hexadecimal form or in decimal form from the keyboard, and to echo it to standard out.

The hexadecimal number must begin with one of '#', '$' or '%'; a sign is not allowed ( nor necessary since the most significant bit indicates the sign ). A '#' and '$' mean exactly the same thing: the following digits form a hex integer. A '%' means add the given hex integer to MOSTNEG INT using modulo arithmetic to give the result. Both upper and lower case hex digits are permissible. A sign is allowed in the first character position if it is a decimal integer that is entered. The number typed at the keyboard must be terminated by pressing 'RETURN'.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`INT` | `n` | if error is FALSE, the value of the integer read; otherwise undefined

`BOOL`

`error`

FALSE if everything was in order; TRUE otherwise: 1) if the integer overflows the INT range; 2a) if it is a hex integer, if there is a non-hex character in the string read from the keyboard ( other than #, $, or % in the first character position ) 2b) if it is a decimal integer, if there is a non-numeric character in the string read from the keyboard ( other than a + or - in the first character position )

### `exit.occ`:39Process `sp.exit`

`PROC sp.exit (CHAN OF SP fs, ts, VAL INT32 status, BYTE result)`

Terminate the server.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `status` | a value which the server passes directly on to the host environment, except in the following two cases: sps.success - a host specific success result is passed on sps.failure - a host specific failure result is passed on
`BYTE` | `result` | equals spr.ok if the operation succeeded; otherwise >= spr.operation.failed - see hostio.inc or iserver documentation for further details

### `exit.occ`:61Process `so.exit`

`PROC so.exit (CHAN OF SP fs, ts, VAL INT32 status)`

Terminate the server.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `status` | a value which the server passes directly on to the host environment, except in the following two cases: sps.success - a host specific success result is passed on sps.failure - a host specific failure result is passed on

### `puts.occ`:42Process `sp.puts`

`PROC sp.puts (CHAN OF SP fs, ts, VAL INT32 streamid, VAL []BYTE data, BYTE result)`

Write a line to the specified output stream.

A newline sequence is added to the end of the bytes to be written.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL INT32` | `streamid` | the identification number of the stream to be written to
`VAL []BYTE` | `data` | the line to be written ( without a terminating newline sequence )
`BYTE` | `result` | equal to spr.ok if the line was successfully written; otherwise takes on a value indicating what was wrong: spr.bad.packet.size too many bytes supplied, (SIZE data) > sp.max.writebuffer.size >=spr.operation.failed the write failed - see hostio.inc or iserver documentation for further details

### `pollkey.occ`:45Process `sp.pollkey`

`PROC sp.pollkey (CHAN OF SP fs, ts, BYTE key, result)`

Read a single character from the keyboard, without waiting for one if there is none.

The key is not echoed to the screen.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`BYTE` | `key` | the key that was read
`BYTE` | `result` | equals spr.ok if there was a key to read and the read was successful; otherwise >= spr.operation.failed - refer to hostio.inc or iserver documentation for further details