CONTENTS | PREV | NEXT
13D. use of exception-ID's
--------------------------
In real life an exception-ID is of course a normal 32-bit value,
and you may pass just about anything to an exception handler: for
example, some use it to pass error-description strings

Raise('Could not open "gadtools.library"!')

However, if you want to use exceptions in expandabele fashion and you
want to be able to use future modules that raise exceptions not defined
by your program, follow the following guidelines:

- Use and define ID 0 as "no error" (i.e. normal termination)

- For exceptions specific to your program, use the ID's 1-10000.
  Define these in the usual fashion with ENUM:

  ENUM OK,NOMEM,NOFILE,...

  (OK will be 0, and others will be 1+)

- ID's 12336 to 2054847098 (these are all identifiers
  consisting of upper/lowercase letters and digits of length 2,3 or 4
  enclosed in "") are reserved as common exceptions. A common exception
  is an exception that need not be defined in your program, and that
  may be used by implementors of modules (with functions in them) to
  raise exceptions: for example, if you design a set of procedures that
  perform a certain task, you may want to raise exceptions. As you would
  want to use those functions in various programs, it would be
  unpractical to have to coordinate the IDs with the main program,
  furthermore, if you use more than one set of functions (in a module,
  in the future) and every module would have a different ID for
  'no memory!', things could get out of hand.
  This is where common exceptions come in: the common out-of-memory
  ID is "MEM" (including the quotes): any implementor can now simply

  Raise("MEM")

  from all different procedures, and the programmer that uses the module
  only needs to suply an exception handler that understands "MEM"

  future modules that contain sets of functions will specify what
  exception a certain procedure may raise, and if these overlap
  with the IDs of other procedures, the task of the programmer
  that has to deal with the exceptions will be greatly simplified.

  examples:

  (system)

  "MEM"		out of memory
  "FLOW"	(nearly) stack overflow
  "STCK"	garbage collector has stack problems
  "^C"		Control-C break
  "ARGS"	bad args

  (exec/libraries)

  "SIG"		could not allocate signal
  "PORT"	could not create messageport
  "LIB"		library not available
  "ASL"		no asl.library
  "UTIL"	no utility.library
  "LOC"		no locale.library
  "REQ"		no req.library
  "RT"		no reqtools.library
  "GT"		no gadtools.library (similar for others)

  (intuition/gadtools/asl/gfx)

  "WIN"		failed to open window
  "SCR"		failed to open screen
  "REQ"		could not open requester
  "FREQ"	could not open filerequester
  "GAD"		could not create gadget
  "MENU"	could not create menu(s)
  "FONT"	problem getting font

  (dos)

  "OPEN"	could not open a file / file does not exist
  "OUT"		problems while writing
  "IN"		problems while reading
  "EOF"		unexpected end of file
  "FORM"	input format error
  "SEG"		loadseg problems

  The general tendency is:
  * all uppercase for general system exceptions,
  * mixed case for exceptions used by >1 app, but not general enough.
  * all lowercase for exceptions raised within your own
    multi-module application

- all others (including all negative IDs) remain reserved.