Debian Codegraph @

doc/sql.extensions/README.exception_handling

raw
1 ------------------
2 Exception handling
3 ------------------
4
5 The common syntax rules for EXCEPTION statement is:
6
7 EXCEPTION [[name] [value]];
8
9
10 Run-time exception messages (FB 1.5)
11 ------------------------------------
12
13 Function:
14 Allows to throw exceptions with text message
15 defined at runtime.
16
17 Author:
18 Dmitry Yemanov <[email protected]>
19
20 Syntax rules:
21 EXCEPTION <exception_name> <message_value>;
22
23 Scope:
24 PSQL
25
26 Example(s):
27 1. EXCEPTION E_EXCEPTION_1 'Error!';
28 2. EXCEPTION E_EXCEPTION_2 'Wrong type for record with ID=' || new.ID;
29
30
31 Exception re-raise semantics (FB 1.5)
32 -------------------------------------
33
34 Function:
35 Allows to re-initiate catched exception.
36
37 Author:
38 Digitman <[email protected]>
39
40 Syntax rules:
41 EXCEPTION;
42
43 Scope:
44 PSQL, context of the exception handling block
45
46 Example(s):
47 BEGIN
48 ...
49 WHEN SQLCODE -802 DO
50 EXCEPTION E_ARITH_EXCEPT;
51 WHEN SQLCODE -802 DO
52 EXCEPTION E_KEY_VIOLATION;
53 WHEN ANY DO
54 EXCEPTION;
55 END
56
57 Note(s):
58 Evaluates to no-op if used outside the exception handling block.
59
60
61 Run-time error codes (FB 1.5)
62 -----------------------------
63
64 Function:
65 Allows to get a numeric error code for the catched exception.
66
67 Author:
68 Dmitry Yemanov <[email protected]>
69
70 Syntax rules:
71 SQLCODE / GDSCODE;
72
73 Scope:
74 PSQL, context of the exception handling block
75
76 See also:
77 README.context_variables
78
79
80 Parameterized exceptions (FB 3.0)
81 ---------------------------------
82
83 Function:
84 Allow to define exception message with slots for parameters and pass the parameters when
85 raising the exception.
86
87 Author:
88 Adriano dos Santos Fernandes <adrianosf at gmail.com>
89
90 Syntax:
91 EXCEPTION <name> USING ( <value list> )
92
93 Example:
94 create exception e_invalid_val 'Invalid value @1 for the field @2';
95
96 ...
97 if (val < 1000) then
98 thing = val;
99 else
100 exception e_invalid_val using (val, 'thing');
101 end
102
103 Notes:
104 The maximum number of arguments passed is 9.
105
106 In the exception message, @NN (example: @10) is considered as @1 followed by the literal 0.
107
108 The status vector is generated using these codes combination:
109 isc_except, <exception number>,
110 isc_formatted_exception, <formatted exception message>, <exception parameters>
111
112 Since new error code (isc_formatted_exception) is used, it's necessary that the client is v3.0
113 or at least uses firebird.msg from v3.0 so that it can translate the status vector to string.
114
115 @N means the N parameter (where N starts at 1) passed in the exception raise command. If a N
116 parameter is not passed, the text is not substituted. If NULL is passed, it's replaced by string
117 '*** null ***'. If more parameters are passed than used in the exception message, they are
118 ignored.