# Module `hostsp`

## Index

- Process `so.close` - Close a stream
- Process `so.commandline` - Return the command line passed to the server on invocation
- Process `so.exit` - Terminate the server
- Process `so.exit` - Terminate the server
- Process `so.flush` - Flush the specified output stream
- Process `so.getenv` - Return the contents of an environment variable from whatever host is being used
- Process `so.gets` - Read a line from the specified input stream
- Process `so.open` - Open a file
- Process `so.putblock` - Write a limited number of bytes to a stream
- Process `so.read` - Read an unlimited number of bytes from a stream
- Process `so.remove` - Delete the specified file
- Process `so.rename` - Rename the specified file
- Process `so.seek` - Set the file position for the specified stream
- Process `so.system` - Execute a command on the host system
- Process `so.tell` - Return the current file position for the specified stream
- Process `so.time` - Retrieve the local and UTC time from the host system
- Process `so.time` - Retrieve the local and UTC time from the host system
- 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 `sp.close` - Close a stream
- Process `sp.commandline` - Return the command line passed to the server on invocation
- Process `sp.exit` - Terminate the server
- 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.getkey` - Read a single character from the keyboard, waiting for one if there is none
- Process `sp.gets` - Read a line from the specified input stream
- Process `sp.open` - Open a file
- Process `sp.pollkey` - Read a single character from the keyboard, without waiting for one if there is none
- Process `sp.read` - Read a limited number of bytes from a stream
- 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.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.write` - Write a limited number of bytes to a stream

## Declarations

### `flush.occ`:39Process `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

### `tell.occ`:38Process `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

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

`PROC sp.open (CHAN OF SP fs, ts, VAL []BYTE name, 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` | `name` | 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

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

`PROC sp.remove (CHAN OF SP fs, ts, VAL []BYTE name, 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` | `name` | 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

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

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

Write a limited 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 stream
`INT` | `length.written` | this gives the number of bytes written. If length.written <> (SIZE data) then an error occurred. 0 <= length.written <= sp.max.writebuffer.size
`BYTE` | `result` | if not equal to spr.bad.packet.size meaning that too many bytes were requested, ie (SIZE data) > sp.max.writebuffer.size, then it is equal to spr.ok

### `exit.occ`:38Process `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`:67Process `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

### `getkey.occ`:38Process `sp.getkey`

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

Read a single character from the keyboard, 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 the read was successful; otherwise >= spr.operation.failed - see hostio.inc or iserver documentation for further details

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

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

Rename the specified file.

#### Parameters:

`CHAN OF SP` | `fs` | from server
`CHAN OF SP` | `ts` | to server
`VAL []BYTE` | `oldname` | the present name of the file to be renamed
`VAL []BYTE` | `newname` | 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

### `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`:79Process `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

### `hostunix.occ`:82Process `so.close`

`PROC so.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

### `hostunix.occ`:130Process `so.commandline`

`PROC so.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

### `hostunix.occ`:155Process `so.flush`

`PROC so.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

### `hostunix.occ`:216Process `so.getenv`

`PROC so.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

### `hostunix.occ`:281Process `so.gets`

`PROC so.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

### `hostunix.occ`:345Process `so.open`

`PROC so.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

### `hostunix.occ`:396Process `so.putblock`

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

Write a limited 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 stream
`INT` | `length.written` | this gives the number of bytes written. If length.written <> (SIZE data) then an error occurred. 0 <= length.written <= sp.max.writebuffer.size
`BYTE` | `result` | if not equal to spr.bad.packet.size meaning that too many bytes were requested, ie (SIZE data) > sp.max.writebuffer.size, then it is equal to spr.ok

### `hostunix.occ`:443Process `so.remove`

`PROC so.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

### `hostunix.occ`:485Process `so.rename`

`PROC so.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

### `hostunix.occ`:524Process `so.seek`

`PROC so.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

### `hostunix.occ`:565Process `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).

### `hostunix.occ`:625Process `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

### `hostunix.occ`:683Process `so.system`

`PROC so.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

### `hostunix.occ`:713Process `so.tell`

`PROC so.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

### `hostunix.occ`:737Process `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 UTC, and are given as unsigned INT32s.

#### 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

### `hostunix.occ`:757Process `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 ( 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

### `hostunix.occ`:778Process `so.exit`

`PROC so.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

### `getenv.occ`:53Process `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

### `spread.occ`:46Process `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`:39Process `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

### `system.occ`:39Process `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

### `command.occ`:47Process `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

### `gets.occ`:60Process `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

### `pollkey.occ`:38Process `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

### `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