TR-DOS example

15   MACHINE CODE PROGRAMMING

The inclusion of TRDOS  routines  in  machine  code  programs  are
relativey straightforward.

There are 3 elements required for the program:

(1) The machine code equivalent of the BASIC TRDOS command.
(2) The machine code routine to implement 1 above.
(3) The machine code routine to restore the system to its original
    state before calling and executing the command.

The actual memory locations used will depend upon the program as a
whole. For the  purpose  of  this  example  the  location  of  the
routines  will be at 49000 for the SAVE, at 49500 for the LOAD and
at 50000 for the instructions calling them. Thus item 1 will be at
either 49000 or 49500 and items 2 and 3 at 50000.

EXAMPLE:

Address     Code     Basic   Comment

49000       234      REM     Codes as in Appx A of Spectrum
49001        58       :      manual
49002       248      SAVE
49003        34       "
49004        69       E
49005       120       x
49006        97       a
49007       109       m      File name "Example"
49008       112       p
49009       108       l
49010       101       e
49011        34       "
49012        13      ENTER   Always end with ENTER

The  code for the LOAD commences at  49500 and is eaxctly the same
as above except that address 49502 will contain 239 (LOAD) instead
of 248 (SAVE).

These two  routines, LOAD, and  SAVE can be  located anywhere, but
the  initiator which we are locating at 50000 requires changing at
addresses  50007-50008 (Save  routine address)  and 50025  - 50026
(LOAD routine address) to point to the new addresses.

To relocate, the  initiator itself  requires reassembly.  For that
reason the Z80 mnemonics only are given below.

CHADD  EQU   23645         Location of SOS variable CHADD
       ORG   XXXXX         XXXX=address of this code
       LD    HL,(CHADD)    Start to save true CHADD
       LD    (TEMP), HL    Temporary store of true CHADD
       LD    HL,49000      Address of SAVE routine
       LD    (CHADD),HL    CHADD now points to our routine
       CALL  15363         ENTER TRDOS SAVE via chadd
       JP    BACK          Jump to program point from which
                           the whole routine was called
       LD    HL,(CHADD)
       LD    (TEMP),HL     The routine for LOAD now repeats
       LD    HL,49500      the above with just the address
       LD    (CHADD),HL    changed.
       CALL  15363
BACK   LD    HL,(TEMP)     Start to restore CHADD
       LD    (CHADD),HL    Reload original CHADD
       RET                 Return from where you came
TEMP                       Label allocating memory for
                           temporary storage

The whole routine  pointing to  both the  SAVE and  LOAD routines,
together with the  "return  to  point  of  entry"  ending  routine
occupies only 47 bytes.