mdw@git.distorted.org.uk Git - ssr/blob - StraySrc/Libraries/Sapphire/sh/except

   1 ;
   2 ; except.sh
   3 ;
   4 ; Sapphire exception handling
   5 ;
   6 ; © 1994-1998 Straylight
   7 ;
   8
   9 ;----- Licensing note -------------------------------------------------------
  10 ;
  11 ; This file is part of Straylight's Sapphire library.
  12 ;
  13 ; Sapphire is free software; you can redistribute it and/or modify
  14 ; it under the terms of the GNU General Public License as published by
  15 ; the Free Software Foundation; either version 2, or (at your option)
  16 ; any later version.
  17 ;
  18 ; Sapphire is distributed in the hope that it will be useful,
  19 ; but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21 ; GNU General Public License for more details.
  22 ;
  23 ; You should have received a copy of the GNU General Public License
  24 ; along with Sapphire.  If not, write to the Free Software Foundation,
  25 ; 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  26
  27 ;----- Overview -------------------------------------------------------------
  28 ;
  29 ; Functions provided:
  30 ;
  31 ;  except_init
  32 ;  except_fatal
  33 ;  except_atExit
  34 ;  except_returnPt
  35
  36                 [       :LNOT::DEF:except__dfn
  37                 GBLL    except__dfn
  38
  39 ; --- except_init ---
  40 ;
  41 ; On entry:     --
  42 ;
  43 ; On exit:      --
  44 ;
  45 ; Use:          Initialises the exception handler.
  46
  47                 IMPORT  except_init
  48
  49 ; --- except_fatal ---
  50 ;
  51 ; On entry:     R0 == pointer to an error block
  52 ;
  53 ; On exit:      Doesn't
  54 ;
  55 ; Use:          Reports an error to our /caller's/ error handler.  We quit
  56 ;               and die at this point.  Don't use unless you have absolutely
  57 ;               no choice in the matter.
  58
  59                 IMPORT  except_fatal
  60
  61 ; --- except_atExit ---
  62 ;
  63 ; On entry:     R0 == pointer to routine to call on exit
  64 ;               R1 == R12 value to call with
  65 ;
  66 ; On exit:      --
  67 ;
  68 ; Use:          Registers a routine to get called when the application quits.
  69 ;               Later-registered routines are called earlier than earlier-
  70 ;               registered routines, so everything closes down in a nice
  71 ;               manner.
  72
  73                 IMPORT  except_atExit
  74
  75 ; --- except_returnPt ---
  76 ;
  77 ; On entry:     R0 == pointer to exception handler routine
  78 ;               R1 == R12 value to enter routine with
  79 ;               R2 == R13 value to enter routine with
  80 ;
  81 ; On exit:      --
  82 ;
  83 ; Use:          Sets up a routine to be called whenever there's an error.
  84 ;               The idea is that it should ask the user whether to quit,
  85 ;               and if not, resume to some known (safe?) state.
  86 ;
  87 ;               The routine is called with R0 == pointer to error block, and
  88 ;               R12 and R13 being the values set up here(*).  It should
  89 ;               return with R0 == pointer to a routine to resume at, and R1
  90 ;               being the value to pass to the resume routine in R12.  If
  91 ;               you decide to quit, just call OS_Exit -- this should tidy
  92 ;               everything up.
  93 ;
  94 ;               Note that the error is held in the scratchpad buffer, so
  95 ;               you can't use the first 256 bytes of that until you've
  96 ;               finished with the error message.
  97 ;
  98 ;               (*) Actually, R13 is 4 bytes lower because it's assumed that
  99 ;               it points to a full descending stack that we can use.  This
 100 ;               shouldn't make any difference as long as you're using R13
 101 ;               as a full descending stack pointer.
 102
 103                 IMPORT  except_returnPt
 104
 105                 ]
 106
 107 ;----- That's all, folks ----------------------------------------------------
 108
 109                 END