Note that the following technical information was correct up to v1.92 of ResiDOS. The many additional features in v2.00 (including the new package APIs) are not yet described. If you wish to write a package, or use any of the new facilities in v2.00, then please contact me. However, please note that if you only want to write an application accessing files, then all the information below is good to use; file access is the same regardless of whether the user has a FAT or IDEDOS drive, and regardless of the hardware interface. All file access is done through the standard +3DOS calls, using the calling convention described here.
Eventually (hopefully in the not-too-distant future!) I will get around to updating this!
From v1.40, it is possible to access some of the features of the operating system from machine-code programs, so that utility programs which access files can be written.
Calls are available in ResiDOS using hook codes, which are invoked using the RST 8 instruction followed by a hook code. There are two main hook codes available to programmers: the version information hook code, which detects which version of ResiDOS is available (if any), and the package call hook code, which is used to access all other facilities.
All the following pieces of code are provided in the format used by Interlogic's free z80asm assembler which is available for many platforms at Z88 Forever!. Binaries are provided for several platforms, and most others (including MacOS X) can compile the source package. Additionally, instead of using "magic numbers" for the various call IDs etc, these are defined as meaningful words. You should download the following file, which contains the necessary include files, together with an example utility program (assembly file and pre-built TAP/TZX):
Any program which is going to use ResiDOS facilities must first check that it is installed, and that a suitable version number is available. You should check for a version which is high enough to support all the calls you are going to use. ResiDOS version 1.40 was the first to support package calls; each call introduced subsequently has the first version for which it was available listed.
Some suitable code for testing the version follows. It can be called from BASIC, and returns the version number in BC (or 0 if not installed).
.residetect ld hl,(ERR_SP) push hl ; save the existing ERR_SP ld hl,detect_error push hl ; stack error-handler return address ld hl,0 add hl,sp ld (ERR_SP),hl ; set the error-handler SP rst RST_HOOK ; invoke the version info hook code defb HOOK_VERSION pop hl ; ResiDOS doesn't return, so if we get jr noresidos ; here, some other hardware is present .detect_error pop hl ld (ERR_SP),hl ; restore the old ERR_SP ld a,(ERR_NR) inc a ; is the error code now "OK"? jr nz,noresidos ; if not, ResiDOS was not detected ex de,hl ; get HL=ResiDOS version push hl ; save the version ld de,$0140 ; DE=minimum version to run with and a sbc hl,de pop bc ; restore the version to BC ret nc ; and return with it if at least v1.40 .noresidos ld bc,0 ; no ResiDOS ld a,$ff ld (ERR_NR),a ; clear error ret
The facilities of ResiDOS are divided up into packages, each of which provides its own set of calls. Two packages are currently provided: the ResiDOS package itself, and the IDEDOS package. The first of these provides system functions not related to disk access; the other provides all the useful calls for accessing partitions and files.
Making a package call involves the following steps:
Here is some generic code to make a package call. Note that if you are intending to return to BASIC at any point, you should always preserve the alternate HL register pair (H'L') as this is required by BASIC:
; set up any entry parameters here exx ld b,package_id ld hl,call_id rst RST_HOOK ; invoke the package call hook code defb HOOK_PACKAGE jr nc,process_error ; handle error if Fc=0 ; handle any return values here
This package provides calls to access ResiDOS facilities and hardware features (such as extra built-in memory). The calls provided can be used without knowing whether your application is running on a ZXCF, ZXATASP or any future interface which may be supported by ResiDOS.
The full reference is here, or follow the links below for individual calls:
This package provides many of the calls available in +3DOS (used on the +3 and +3e) and IDEDOS (used on the +3e). The calls all use the same input and output parameters, but there are some "gotchas":
The following +3DOS calls may be used. Full details are in the +3 manual, which can be obtained from The World Of Spectrum. Calls marked with an asterisk probably won't work as expected, or be very useful.
The following IDEDOS calls are provided. Documentation is provided at the +3e website.
One slight difference is that for the IDE_DOS_MAP and IDE_DOS_UNMAP calls, the FLAGS3 variable is not used (it doesn't exist on all Spectrums). Instead, you can provide a drive letter as lower-case to make the mapping permanent.
A special call, IDE_ACCESS_DATA, is provided so that data which exists in the ResiDOS memory can be read or written by programs. Such addresses are referred to in the +3DOS documentation as being "in page 7". Instead, use this call, with the provided address as the source or destination, and your own buffer as the other address.