Trapping errors via ERRSP
                        =========================

Errors can be trapped by modifying ERRSP to point to an alternative stack
location (or other location) to return to your own error handler instead of
dropping to the command prompt. A typical use is the following:

ROUTINE:
  LD   HL,(ERRSP)
  PUSH HL          ; Save the current ERRSP
  CALL SUB         ; Call the routine that may generate errors
HERE:
  POP  HL          ; Get the saved ERRSP
  LD   (ERRSP),HL  ; Restore it
  RET
SUB:
  LD   (ERRSP),SP  ; Point ERRSP to this routine's return address
  ...              ; Do something that may generate an error
  RET              ; Return

On return from the subroutine, the code returns normally via the RET to
HERE. When an error is generated, the error handler returns via the address
on the stack at ERRSP, which is the return address to HERE.

Some points have to be borne in mind though.

When returning via ERRSP:
A     will be preserved
Cy    will be preserved
Z     will be preserved if no Interface 1 is present
Z     will be forced to NZ if Interface 1 is present
HL    will be corrupted - it will hold STKBOT and STKEND
ERRNR will be set to the inline byte, &FF=OK, etc.
All other registers will be preserved.
If the code may generate an Interface 1 error, SET 2,(IY+124) needs to be
done to tell the Interface 1 to return via ERRSP, otherwise the default
error handler is always used.

So, you must be careful if the routine you are calling returns something in
the Z flag, as the Interface 1 overwrites it, or in HL, as it is always
overwritten.


If you need to be able to distinguish between a normal return and an error
return and the above method is insufficient, code of the following lines can
be used.

ROUTINE:
  LD   HL,(ERRSP)
  PUSH HL          ; Save the current ERRSP
  CALL SUB         ; Call the routine that may generate errors
HERE:
  ; We will return here when an error occurs
  ; Set the registers to something indicating an error
  POP  HL          ; Get the saved ERRSP
  LD   (ERRSP),HL  ; Restore it
  RET
SUB:
  LD   (ERRSP),SP  ; Point ERRSP to this routine's return address
  ...              ; Do something that may generate an error
  ; We will continue here if no error occurs
  ; Set the registers to indicate no error
  POP  HL          ; Drop the return address
  POP  HL          ; Get the saved ERRSP
  LD   (ERRSP),HL  ; Restore it
  RET              ; Return to the original caller


An example would be the following code that calls LDBYTES and is able to
return a value to Basic indicating the result.

ROUTINE:
  LD   HL,(ERRSP)
  PUSH HL          ; Save the current ERRSP
  CALL SUB         ; Call the routine that may generate errors
  LD   BC,(ERRNR)
  LD   B,0         ; Return BC=ERRNR+1 if error occured
  INC  BC          ; Eg 0=OK, 12=BREAK, etc.
  JR   DONE        ; Restore ERRSP and return
SUB:
  LD   (ERRSP),SP  ; Point ERRSP to this routine's return address
  CALL &0556       ; Call LDBYTES
  POP  HL          ; Drop return address
  LD   BC,0
  JR   C,DONE      ; Return BC=0 if Ok
  INC  C           ; Return BC=1 if Block not loaded
DONE:
  POP  HL          ; Get the saved ERRSP
  LD   (ERRSP),HL  ; Restore it
  RET              ; Return