From v1.40, it is possible to access some of the features of the operating system from machine-code programs, so that utility programs and other applications which access files or use other ResiDOS facilities 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.
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
You may wish to detect whether ResiDOS is installed from BASIC (this may be done before attempting to use a ResiDOS BASIC command to load a machine code file from disk, for example).
The suggested way to do this (as used by the ResiDOS installer program) is to check whether the ResiDOS initialisation hook is present in the BASIC ROM. This is done as follows:
IF PEEK 4768=207 AND PEEK 4769=254 THEN PRINT "ResiDOS is installed"
Note that there is no way to determine the version of ResiDOS which is installed without using machine-code.
The facilities of ResiDOS are divided up into packages, each of which provides its own set of calls. The two main packages of interest to machine-code programmers are 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:
From ResiDOS v1.40, two packages have always been available: ResiDOS and IDEDOS. These packages work in a slightly different way to all subsequently-released packages.
For these packages, the alternate registers are set up with B=package ID (PKG_RESIDOS or PKG_IDEDOS) and HL=call ID (as listed in the call references).
Here is some generic code to make a ResiDOS or IDEDOS 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
From ResiDOS v2.00, a new standardised system was introduced to make calls to all subsequently-released packages.
For these packages, the alternate registers are set up with BC=call ID (as listed in the call references). In fact, this call ID is made up of two 8-bit values: B=package ID and C=call number, but these are usually referred to as a single 16-bit call ID value.
Note that any call to a standard package may fail with Fc=0 and A=rc_resi_package_not_found if the package is not installed, or if the version of the package installed is not high enough to support the call.
Code to invoke a call provided by a standard package would be:
; set up any entry parameters here exx ld bc,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
All standard packages provide a set of 8 standard calls (where B=package ID and C=$00..$07). These are mostly of use only to ResiDOS itself, to manage the packages. However, one of these standard calls can be used to determine the version of a package that is installed, and this can be used by application programs to ensure that a recent-enough version of the package is available to them.
This is the PKG_STDCALL_INFO ($02) call, and can be used by setting A=info_version (0) and making the call. If the package is present, the call will be successful (Fc=1) and BC contains the binary-coded-decimal version number of the installed package. If the call fails (Fc=0), an error of A=rc_resi_package_not_found will be returned.
For example, to check what version (if any) of the TapeIO package is installed, use the following code:
ld a,info_version exx ld bc,TAPEIOPKG_ID*$100+PKG_STDCALL_INFO rst RST_HOOK ; invoke the package call hook code defb HOOK_PACKAGE jr nc,process_error ; handle error if Fc=0 ; BC holds version number (in BCD form)