;
; except.sh
;
; Sapphire exception handling
;
; © 1994-1998 Straylight
;

;----- Licensing note -------------------------------------------------------
;
; This file is part of Straylight's Sapphire library.
;
; Sapphire is free software; you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation; either version 2, or (at your option)
; any later version.
;
; Sapphire is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with Sapphire.  If not, write to the Free Software Foundation,
; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

;----- Overview -------------------------------------------------------------
;
; Functions provided:
;
;  except_init
;  except_fatal
;  except_atExit
;  except_returnPt

		[	:LNOT::DEF:except__dfn
		GBLL	except__dfn

; --- except_init ---
;
; On entry:	--
;
; On exit:	--
;
; Use:		Initialises the exception handler.

		IMPORT	except_init

; --- except_fatal ---
;
; On entry:	R0 == pointer to an error block
;
; On exit:	Doesn't
;
; Use:		Reports an error to our /caller's/ error handler.  We quit
;		and die at this point.  Don't use unless you have absolutely
;		no choice in the matter.

		IMPORT	except_fatal

; --- except_atExit ---
;
; On entry:	R0 == pointer to routine to call on exit
;		R1 == R12 value to call with
;
; On exit:	--
;
; Use:		Registers a routine to get called when the application quits.
;		Later-registered routines are called earlier than earlier-
;		registered routines, so everything closes down in a nice
;		manner.

		IMPORT	except_atExit

; --- except_returnPt ---
;
; On entry:	R0 == pointer to exception handler routine
;		R1 == R12 value to enter routine with
;		R2 == R13 value to enter routine with
;
; On exit:	--
;
; Use:		Sets up a routine to be called whenever there's an error.
;		The idea is that it should ask the user whether to quit,
;		and if not, resume to some known (safe?) state.
;
; 		The routine is called with R0 == pointer to error block, and
;		R12 and R13 being the values set up here(*).  It should
;		return with R0 == pointer to a routine to resume at, and R1
;		being the value to pass to the resume routine in R12.  If
;		you decide to quit, just call OS_Exit -- this should tidy
;		everything up.
;
;		Note that the error is held in the scratchpad buffer, so
;		you can't use the first 256 bytes of that until you've
;		finished with the error message.
;
;		(*) Actually, R13 is 4 bytes lower because it's assumed that
;		it points to a full descending stack that we can use.  This
;		shouldn't make any difference as long as you're using R13
;		as a full descending stack pointer.

		IMPORT	except_returnPt

		]

;----- That's all, folks ----------------------------------------------------

		END