------------------
Exception handling
------------------

The common syntax rules for EXCEPTION statement is:

  EXCEPTION [[name] [value]];


Run-time exception messages (FB 1.5)
------------------------------------

  Function:
    Allows to throw exceptions with text message
    defined at runtime.

  Author:
    Dmitry Yemanov <[email protected]>

  Syntax rules:
    EXCEPTION <exception_name> <message_value>;

  Scope:
    PSQL

  Example(s):
    1. EXCEPTION E_EXCEPTION_1 'Error!';
    2. EXCEPTION E_EXCEPTION_2 'Wrong type for record with ID=' || new.ID;


Exception re-raise semantics (FB 1.5)
-------------------------------------

  Function:
    Allows to re-initiate catched exception.

  Author:
    Digitman <[email protected]>

  Syntax rules:
    EXCEPTION;

  Scope:
    PSQL, context of the exception handling block

  Example(s):
    BEGIN
      ...
    WHEN SQLCODE -802 DO
      EXCEPTION E_ARITH_EXCEPT;
    WHEN SQLCODE -802 DO
      EXCEPTION E_KEY_VIOLATION;
    WHEN ANY DO
      EXCEPTION;
    END

  Note(s):
    Evaluates to no-op if used outside the exception handling block.


Parameterized exceptions (FB 3.0)
---------------------------------

  Function:
    Allow to define exception message with slots for parameters and pass the parameters when
    raising the exception.

  Author:
    Adriano dos Santos Fernandes <adrianosf at gmail.com>

  Syntax:
    EXCEPTION <name> USING ( <value list> )

  Example:
    create exception e_invalid_val 'Invalid value @1 for the field @2';

    ...
    if (val < 1000) then
       thing = val;
    else
       exception e_invalid_val using (val, 'thing');
    end

  Notes:
    The maximum number of arguments passed is 9.

    In the exception message, @NN (example: @10) is considered as @1 followed by the literal 0.

    The status vector is generated using these codes combination:
      isc_except, <exception number>,
      isc_formatted_exception, <formatted exception message>, <exception parameters>

    Since new error code (isc_formatted_exception) is used, it's necessary that the client is v3.0
    or at least uses firebird.msg from v3.0 so that it can translate the status vector to string.

    @N means the N parameter (where N starts at 1) passed in the exception raise command. If a N
    parameter is not passed, the text is not substituted. If NULL is passed, it's replaced by string
    '*** null ***'. If more parameters are passed than used in the exception message, they are
    ignored.