This chapter contains details of all EXOS function calls. Many of them have been described earlier in general terms. This section concentrates on details such as register usage and error codes, and describes the function calls from the point of view of the program making the call.
Parameters are passed to EXOS calls in registers A, BC and DE, and results are passed back in the same registers. Register A returns a status code which is zero if the call was successful and a nonzero error code otherwise. All other registers (HL, IX, IY, AF', BC', DE', HL') are preserved by all EXOS calls, and also the user's paging is not disturbed. EXOS calls can be made from any address in any Z80 page, and user's stack can be in any of the four pages.
The open channel and create channel function calls take a string parameter. This string defines which device driver the channel is being opened to, and also specifies a unit number and filename. The syntax of the string is:
[[device-name][["-"]unit-number]":"][file-name]
where [ ] denotes an optional part and ""
delimits literal characters.
The device name can be up to 28 characters and must be entirely letters, which will be uppercased before using so case is not significant. If it is not present then EXOS will use a default device name wich can be set with a set default device name EXOS call (code 19). If the unit number is also absent (see below) then the default unit number, which can also be set with this call, will be used.
The unitnumber, if present, can be seperated from the device name
with a single "-" (minus) character if desired or it can
immediately follow it. The unit number consists of a series of decimal
digits which will be converted into a one byte value by EXOS. If the
device name is specified with no unit number, then a default unit number
of zero is used.
The optional filename consists of up to 28 characters which can include letters, digits and any of the special characters:
£ $ % & ' ( ) * - . / ? [ \ ] ^ _ (Also ASCII 60h)
Letters will be uppercased before the string is used. If there is no filename then it will just be taken as the null string.
The filename and unit number will be passed through to the device driver
for interpretation. However if the device driver has the
DD_UNIT_COUNT field in its device descriptor set then some
manipulation of the unit number will occur.
If the DD_UNIT_COUNT field is set to N then this
means that the device driver only accepts unit numbers in the range
[ 0.. N-1 ]. If the unit number is greater than this then it
will reduced by N and the search of the device chain will
continue. When another device of the same name is found the process will
be repeated and if it is now within range then the device will be called
with the reduced unit number. In this way several device with the same
name can be supported, with the distinction being by unit number. This
is not used by any built in devices but could be used by add on disk
units.
Parameters : C Reset type flags
Results : A Status (always zero but flags not set)
Interrupts disabled
This call causes a reset of EXOS. The flags passed in register C control exactly what the reset does, as below:
Note that the status register is not set to be consistent with the status code (which is always zero anyway) and registers BC', DE' and HL' are corrupted by this EXOS call. Also a side effect of the call is that interrupts are disabled.
An automatic RESET call with flags set to 10h is done by
EXOS when a warm reset occurs (see section 3.2).
Also an automatic RESET call with flags set to 20h is done
by EXOS when it enters a RAM loaded applications program (see
section 10.6).
A RESET call (with flags set to 60h or 00h
depending on the action code) must be done by a system extension when it
takes control as a new applications program (see
section 9.3).
After any reset call, including the implicit ones done by EXOS as described above, the warm reset address, software interrupt address and hardware interrupt service routine address will all have been set to zero by EXOS and will thus have to be reinitialised by the user.
Parameters : A channel number (must not be 255)
DE pointer to device/filename string
Results : A status
The format of the filename string was specified above. The filename and unit numbers are passed to the device driver for interpretation and many devices will just ignore them. If the device is one which supports filenames then it will return an error code if the file specified does not already exists. Some devices require options to be selected (by special function calls) before the channel can be used. Also some devices require parameters to be specified by setting EXOS variables before a channel can be opened.
The unit number is ignored by all built in devices except the network driver. If a device name with no unit number is specified then a default of zero is used which devices could translate into their own internal default if desired.
For the open channel function to be successfully completed, the device must allocate itself a channel buffer before it returns and an error may be returned if there is insufficient RAM available.
Parameters : A channel number (must not be 255)
DE pointer to device/filename string
Results : A status
The create function is identical to the open function except that it if the device supports filenames, then the file will be created if it doesn't exist, and an error code returned if it does. It is identical to open channel for all built in devices except the cassette driver.
Parameters : A channel number (must not be 255)
Results : A status
The close function flushes any buffers and deallocates any RAM used by the channel. Further reference to this channel number will result in an error. The device's entry point is called before the channel RAM is deallocated.
Parameters : A channel number (must not be 255)
Results : A status
The destroy function is identical to the close function except that on a file handling device the file is deleted. It is identical for all built in devices.
Parameters : A channel number
Results : A status
B character
The read character call allows single characters to be read from a channel without the explicit use of a buffer. If no character is ready then it waits until one is ready. This call is passed directly through to the device driver.
Parameters : A channel number
BC byte count
DE buffer address
Results : A status
BC bytes left to read
DE modified buffer address
The read block function reads a variable sized block from a channel. The block may be from to 65535 bytes in length and can cross segment boundaries. Note that the byte count returned is valid even if the status code is negative, although not if it is an error such as nonexistent channel. This allows a partially successful block read to be retried from the first character which failed. This call is passed directly through to the device driver.
Parameters : A channel number
B character
Results : A status
The write character function allows single characters to be written to a channel. This call is passed directly to the device driver.
Parameters : A channel number
BC byte count
DE buffer address
Results : A status
BC bytes left to write
DE modified buffer address
The block write function allows a variable sized block to be written to a channel and is similar to block read. The byte count returned in BC is valid even if the status code is negative. This call is passed directly through to the device driver.
Parameters : A channel number
Results : A status
C 00h if character is ready to be read
FFh if at end of file
01h otherwise.
The read channel status function call is used to allow polling of a device such as the keyboard without making the system wait until a character is ready. This call is passed directly through to the device driver.
Parameters : A channel number
C write flags
DE pointer to parameter block (16 bytes)
Results : A status
C read flags
This function is used to provide random access facilities and file protection on file devices such as disk or a RAM driver. The format of the parameter block is:
Byte: 0 ... 3 - File pointer value (32 bits)
4 ... 7 - File size (32 bits)
8 - Protection byte (yet to be defined)
9 .. 15 - Zero (reserved for future expansion)
The assignment of bits in the read and write flags byte is as below. The specified action is taken if the bit is set.
Bit(s) Write Flags Read Flags
b0 Set new pointer value File pointer is valid
b1 not used (0) File size is valid
b2 Set new protection byte Protection byte is valid
b3 .. b7 not used (0) always zero
This allows the file pointer and/or the protection byte to be set
independently, or just to be read. Not all devices need to support this
function, indeed none of the built in devices support it. If a device
doesn't support it then it should return a .NOFN error code.
Parameters : A channel number
B sub-function number
C unspecified parameter
DE unspecified parameter
Result : A status
C unspecified parameter
DE unspecified parameter
This function call allows device specific functions to be performed on a
channel. If it is not supported by a device then a .ISPEC
error will be returned.
The subfunction number specified in register B determines which special function is required. Subfunction numbers should be different for all devices, unless equivalent functions are implemented. The special functions for built in devices are (see device driver specifications for details):
@@DISP = 1 Display page @@SIZE = 2 Return page size and mode @@ADDR = 3 Return video page address @@FONT = 4 Reset character font
@@FKEY = 8 Program function key @@JOY = 9 Read joystick directly
@@FLSH = 16 Flush output buffer @@CLR = 17 Clear input and output buffers
@@MARG = 24 Set margins @@CHLD = 25 Load a document @@CHSV = 26 Save a document
All other subfunction codes from zero to 63 are reserved for use by IS/Enterprise. Codes of 64 and above can be used by user devices.
Parameters : B = 0 read value
= 1 write value
= 2 toggle value
C EXOS variable number (0..255)
D new value to be written (only for write)
Results : A status
D new value of EXOS variable
This function allows EXOS variables to be set or inspected. These variables control various functions of the system and specific devices. Note that the value is returned in D even for write and toggle. There is a list of currently defined EXOS variables in chapter 8. System extensions can implement additional EXOS variables.
Parameters : A main channel number
C secondary channel number
(0FFh to cancel capture)
Results : A status
The capture channel function causes subsequent read function calls (read character, read block and read status) to the main channel, to read data instead from the secondary channel. When the function call is made, the main channel must exist but no check is made on the secondary channel existing.
The capture applies to all subsequent input from the main channel number
until either the secondary channel is closed or gives any error (such as
end of file) or the main channel is captured from somewhere else. The
effect of the capture can be cancelled by giving a secondary channel
number of 0FFh which is not a valid channel number.
Parameters : A main channel number
C secondary channel number
(0FFh to cancel redirection)
Results : A status
The redirect function causes subsequent output sent to the main
channel with write character or write
block function call, to be sent to the secondary channel instead. The
redirection lasts until the secondary channel is closed or returns an
error, or the main channel is redirected somewhere else. A secondary
channel number of 0FFh will cancel any redirection of the
main channel.
Parameters : DE device name pointer (no colon)
C device type 0 = non file handling
1 = file handling
Results : A status
The set default device name function specifies a device name and
(optionally) a unit number which will be used in subsequent
open channel or create
channel function calls if no device name is specified by the
user. Initially the default name will be "TAPE-1" but will
be set to "DISK-1" if a disk device is linked in. The
specified device name and unit number are checked for legality (ie. no
invalid charcters) but not for existence in the device chain.
If a string with only a unit number, such as "45", is
specified then this will set a new unit number but the default name will
be unchanged. If the device name but no unit number is given, then the
default unit number will be set to zero.
The device type given in register C is simply copied
to the device type EXOS variable. This will be zero in the
default machine because the default device is "TAPE" which
is not a file handling device. If a disk unit is connected then the
device type will be set to 1. This vaiable is not currently used by EXOS
but can be of some use to applications programs.
Parameters : DE pointer to parameter block (8 bytes)
Results : A status code, always 0
B version numner (currently 20h)
DE unchanged
This function returns the version number of the system and various parameters which describe the RAM segment usage in the system. The parameters (bytes) returned are, in order:
Parameters : DE pointer to RAM in Z80 space containing
device descriptor
BC amount of device RAM required.
Results : A status
The link device function causes the device descriptor pointed to by
DE to be linked into the descriptor chain. The descriptor will
be put at the start of the chain and any existing device with the same
name will be disabled. DE must point at the TYPE
field of the descriptor and the descriptor must not cross a segment
boundary. Once linked in the user must ensure that the device code and
descriptor are not corrupted until a reset function call
with bit 5 set (to unlink user devices) has been made.
The amount of RAM requested will be allocated in the system segment. When the device is first initialised, this RAM area will be pointed to by IX and the device must remember this address since it will never be told it again, even when it is reinitialised.
Parameters : none
Results : A status (always zero)
C shared segment number. 0 If nonexistent.
DE EXOS boundary in shared segment (0..3FFFh)
The read EXOS boundary function returns the offset within the currently shared segment, of the lowest byte which the system is using. If there is no shared segment then DE will point to where the EXOS boundary would be if a shared segment where allocated.
Parameters : DE offset of new USER boundary. (0..3FFFh)
Result : A status
The set user boundary function allows the user to move the USER boundary within the currently shared segment. If there is no shared segment then this function call is not allowed. The boundary may not be set higher than the current EXOS boundary.
Parameters : none
Results : A status
C segment number
DE EXOS boundary within this segment
The allocate segment function allows the user to obtain another 16K
segment for his use. If a free segment is available then it will be
allocated and status returned zero with the segment number in
C and DE will be 4000h.
If there are no free segments but the user can be allocated a shared
segment, then the segment number will be returned in C and
DE will be the initial EXOS boundary. In this case a
.SHARE error will be returned. The user boundary is
initially set equal to the EXOS boundary.
If there are no free segments and there is already a shared segment then
a .NOSEG error will be returned.
If this function call is made by a device driver then the segment will be marked as allocated to a device and a shared segment cannot be allocated.
Parameters : C segment number
Results : A status
The free segment function allows the user to free a 16K segment of RAM. The segment must be currently allocated to the user or be shared. The page zero segment cannot be freed as it was never allocated explicitly with an allocate segment call.
If this function call is made by a device driver then it must be to free a segment which was allocated to a device driver with an allocate segment call. There is no checking of which device is freeing the segment, devices are supposed to be well behaved.
Parameters : DE pointer to command string
Results : A status
This function causes the string to be passed around all system
extensions after some processing, with action code 2 (or 3 if the first
word of the string is "HELP"). This allows services to be
carried out by system extensions and also allows transfer to a new
applications program.
Parameters : DE amount of buffer which must be in one
segment
BC amount of buffer which needn't be in one
segment (only needed for video devices)
Results : A status
IX points to newly allocated buffer
PAGE-1 contains the new buffer segment.
The allocate channel buffer function is provided only for devices and may not be called by the applications program. It is used to provide a channel with a RAM buffer when it is opened. The multi segment size passed in register BC is ignored for nonvideo devices since they must have their buffer all in one segment. So for nonvideo devices BC need not be loaded before making the call.
Parameters : A error code which needs explaining
DE pointer to string buffer (64 bytes)
Results : A status (always zero).
DE unchanged.
This function allows an EXOS error code to be converted into a short text message. System extensions are given a chance of doing the translation. All error codes generated by the EXOS kernel and the built in devices are explained by the internal ROM. If the string returned is of zero length then it is an error code which no one was willing to explain.
Parameters : DE pointer to a buffer for the module
header (16 bytes)
A channel number to load from
Results : A status
DE unchanged
B if A = .ASCII : 1st character of file
if A = .ITYPE : module type
else : undefined
This function call was explained in the section on loading
module
format files. It will load a module header and then either load the
module itself, or pass it to the system extensions for loading. If the
system extensions don't want it then it will be returned to the user in
his buffer (pointed to by DE), for him to load.
If a module is loaded OK by EXOS or a system extension then a zero
status code is returned. In this case, or if the module is successfully
loaded by the user, the load module function call should be
repeated to load the next module. This should continue until a
.NOMOD error is returned which indicates that an end of
file was read, or until a fatal error occurs.
If the first byte is not zero, or the type byte is zero then the file is
not an
format file and a .ASCII error is returned with the first
character in B. The user can then do what he wants with the
ASCII data, but should not attempt to load another module from this file.
Parameters : A channel number to load from
DE starting address to load at
Results : A status
DE unchanged
This function call can be used by the user to load user relocatable modules, with header type 2, which will be rejected by the load module call above.
The user must find the correct sized chunk of RAM to load the module into (from the size in the header). If the function call returns a zero error code then the user should call the initialisation entry point of the code loaded (if there is one) and should then call load module again to get the next module header. This is explained in more detail in section 10.2.
Parameters : C hours 0 .. 23 (BCD)
D minutes 0 .. 59 (BCD)
E seconds 0 .. 59 (BCD)
Results : A status
This function sets the internal system clock. The parameters are checked
for legality and a .ITIME error returned if they are
illegal.
Parameters : none
Results : A status
C hours 0 .. 23 (BCD)
D minutes 0 .. 59 (BCD)
E seconds 0 .. 59 (BCD)
This function reads the current value of the system clock. This clock is incremented every second, using the Enterprise's 1Hz interrupt. When it reaches midnight the date will automatically be incremented (see below).
Parameters : C year 0 .. 99 (BCD)
D month 1 .. 12 (BCD)
E day 1 .. 32 (BCD)
Results : A status
This function sets the internal system date. The parameters are checked fully for legality, including the number of days in each month and leap years. The year is origined at 1980 so a year value of 4 actually represents 1984. This allows the date to go well into the future. (obsolescence built out !).
Parameters : none
Results : A status
C year 0 .. 99 (BCD)
D month 1 .. 12 (BCD)
E day 1 .. 31 (BCD)
This function reads the current value of the internal system calender. This can be set by the user and will increment automatically when the system clock reaches midnight, coping correctly with the number of days in each month including leap years.