2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <!-- Condition System -->
9 <reference id="ref-conditions">
10 <title>CLSQL Condition System</title>
17 <refentry id="backend-warning-behavior">
19 <refname>*BACKEND-WARNING-BEHAVIOR*</refname>
20 <refpurpose><!-- purpose --></refpurpose>
21 <refclass>Variable</refclass>
24 <title>Value Type</title>
30 <title>Initial Value</title>
31 <para><symbol>nil</symbol></para>
34 <title>Description</title> Action to perform on warning messages
35 from backend. Default is to :warn. May also be set to :error to
36 signal an error or :ignore/nil to silently ignore the warning.
39 <title>Examples</title>
45 <title>Affected By</title>
49 <title>See Also</title>
58 <refentry id="sql-condition">
60 <refname>SQL-CONDITION</refname>
61 <refpurpose>the super-type of all
63 conditions</refpurpose>
64 <refclass>Condition Type</refclass>
67 <title>Class Precedence List</title>
69 <simplelist type="inline">
70 <member><errortype>sql-condition</errortype></member>
71 <member><errortype>condition</errortype></member>
72 <member><errortype>t</errortype></member>
77 <title>Description</title>
78 <para>This is the super-type of all
79 &clsql;-specific conditions
80 defined by &clsql;, or any of it's
81 database-specific interfaces. There are no defined
82 initialization arguments nor any accessors.</para>
86 <refentry id="sql-error">
88 <refname>SQL-ERROR</refname>
89 <refpurpose>the super-type of all
92 <refclass>Condition Type</refclass>
95 <title>Class Precedence List</title>
97 <simplelist type="inline">
98 <member><errortype>sql-error</errortype></member>
99 <member><errortype>error</errortype></member>
100 <member><errortype>serious-condition</errortype></member>
101 <member><errortype>sql-condition</errortype></member>
102 <member><errortype>condition</errortype></member>
103 <member><errortype>t</errortype></member>
108 <title>Description</title>
109 <para>This is the super-type of all
110 &clsql;-specific conditions that
111 represent errors, as defined by
112 &clsql;, or any of it's
113 database-specific interfaces. There are no defined
114 initialization arguments nor any accessors.</para>
118 <refentry id="sql-warning">
120 <refname>SQL-WARNING</refname>
121 <refpurpose>the super-type of all
123 warnings</refpurpose>
124 <refclass>Condition Type</refclass>
127 <title>Class Precedence List</title>
129 <simplelist type="inline">
130 <member><errortype>sql-warning</errortype></member>
131 <member><errortype>warning</errortype></member>
132 <member><errortype>sql-condition</errortype></member>
133 <member><errortype>condition</errortype></member>
134 <member><errortype>t</errortype></member>
139 <title>Description</title>
140 <para>This is the super-type of all
141 &clsql;-specific conditions that
142 represent warnings, as defined by
143 &clsql;, or any of it's
144 database-specific interfaces. There are no defined
145 initialization arguments nor any accessors.</para>
149 <refentry id="sql-database-warning">
151 <refname>SQL-DATABASE-WARNING</refname>
152 <refpurpose>Used to warn while accessing a
153 &clsql; database.</refpurpose>
154 <refclass>Condition Type</refclass>
157 <title>Class Precedence List</title>
159 <simplelist type="inline">
160 <member><errortype>sql-database-warning</errortype></member>
161 <member><errortype>sql-warning</errortype></member>
162 <member><errortype>warning</errortype></member>
163 <member><errortype>sql-condition</errortype></member>
164 <member><errortype>condition</errortype></member>
165 <member><errortype>t</errortype></member>
170 <title>Description</title>
172 This condition represents warnings signalled while accessing
173 a database. The following initialization arguments and
177 <segtitle>Initarg</segtitle>
178 <segtitle>Accessor</segtitle>
179 <segtitle>Description</segtitle>
181 <seg><symbol>:database</symbol></seg>
182 <seg><function>sql-warning-database</function></seg>
183 <seg>The database object that was involved in the
190 <!-- Specific Conditions -->
192 <refentry id="sql-user-error">
194 <refname>SQL-USER-ERROR</refname>
195 <refpurpose>condition representing errors because of invalid
196 parameters from the library user.</refpurpose>
197 <refclass>Condition Type</refclass>
200 <title>Class Precedence List</title>
202 <simplelist type="inline">
203 <member><errortype>sql-user-error</errortype></member>
204 <member><errortype>sql-error</errortype></member>
205 <member><errortype>sql-condition</errortype></member>
206 <member><errortype>condition</errortype></member>
207 <member><errortype>t</errortype></member>
212 <title>Description</title>
213 <para>This condition represents errors that occur because the
214 user supplies invalid data to &clsql;. This includes errors such as
215 an invalid format connection specification or an error in the syntax
216 for the <function>LOOP</function> macro extensions.
217 The following initialization arguments and
221 <segtitle>Initarg</segtitle>
222 <segtitle>Accessor</segtitle>
223 <segtitle>Description</segtitle>
225 <seg><symbol>:message</symbol></seg>
226 <seg><function>sql-user-error-message</function></seg>
227 <seg>The error message.</seg>
233 <refentry id="sql-database-error">
235 <refname>SQL-DATABASE-ERROR</refname>
236 <refpurpose>condition representing errors during query or
237 command execution</refpurpose>
238 <refclass>Condition Type</refclass>
241 <title>Class Precedence List</title>
243 <simplelist type="inline">
244 <member><errortype>sql-database-error</errortype></member>
245 <member><errortype>sql-error</errortype></member>
246 <member><errortype>error</errortype></member>
247 <member><errortype>serious-condition</errortype></member>
248 <member><errortype>sql-condition</errortype></member>
249 <member><errortype>condition</errortype></member>
250 <member><errortype>t</errortype></member>
255 <title>Description</title>
256 <para>This condition represents errors that occur while
257 executing SQL statements, either as part of query operations
258 or command execution, either explicitly or implicitly, as
259 caused e.g. by <function>with-transaction</function>.
260 The following initialization arguments and accessors exist:</para>
262 <segtitle>Initarg</segtitle>
263 <segtitle>Accessor</segtitle>
264 <segtitle>Description</segtitle>
266 <seg><symbol>:database</symbol></seg>
267 <seg><function>sql-database-error-database</function></seg>
268 <seg>The database object that was involved in the
272 <seg><symbol>:error-id</symbol></seg>
273 <seg><function>sql-error-error-id</function></seg>
274 <seg>The numeric or symbolic error specification
275 returned by the database back-end. The values and
276 semantics of this are interface specific.</seg>
279 <seg><symbol>:secondary-error-id</symbol></seg>
280 <seg><function>sql-error-secondary-error-id</function></seg>
281 <seg>The secondary numeric or symbolic error specification
282 returned by the database back-end. The values and
283 semantics of this are interface specific.</seg>
286 <seg><symbol>:message</symbol></seg>
287 <seg><function>sql-error-database-message</function></seg>
288 <seg>A string describing the problem that occurred,
289 possibly one returned by the database back-end.</seg>
295 <refentry id="sql-connection-error">
297 <refname>SQL-CONNECTION-ERROR</refname>
298 <refpurpose>condition representing errors during
299 connection</refpurpose>
300 <refclass>Condition Type</refclass>
303 <title>Class Precedence List</title>
305 <simplelist type="inline">
306 <member><errortype>sql-connection-error</errortype></member>
307 <member><errortype>sql-database-error</errortype></member>
308 <member><errortype>sql-error</errortype></member>
309 <member><errortype>sql-condition</errortype></member>
310 <member><errortype>condition</errortype></member>
311 <member><errortype>t</errortype></member>
316 <title>Description</title>
317 <para>This condition represents errors that occur while trying
318 to connect to a database. The following initialization
319 arguments and accessors exist:</para>
321 <segtitle>Initarg</segtitle>
322 <segtitle>Accessor</segtitle>
323 <segtitle>Description</segtitle>
325 <seg><symbol>:database-type</symbol></seg>
326 <seg><function>sql-connection-error-database-type</function></seg>
327 <seg>Database type for the connection attempt</seg>
330 <seg><symbol>:connection-spec</symbol></seg>
331 <seg><function>sql-connection-error-connection-spec</function></seg>
332 <seg>The connection specification used in the
333 connection attempt.</seg>
336 <seg><symbol>:database</symbol></seg>
337 <seg><function>sql-database-error-database</function></seg>
338 <seg>The database object that was involved in the
342 <seg><symbol>:error-id</symbol></seg>
343 <seg><function>sql-error-error-id</function></seg>
344 <seg>The numeric or symbolic error specification
345 returned by the database back-end. The values and
346 semantics of this are interface specific.</seg>
349 <seg><symbol>:secondary-error-id</symbol></seg>
350 <seg><function>sql-error-secondary-error-id</function></seg>
351 <seg>The secondary numeric or symbolic error specification
352 returned by the database back-end. The values and
353 semantics of this are interface specific.</seg>
356 <seg><symbol>:message</symbol></seg>
357 <seg><function>sql-database-error-error</function></seg>
358 <seg>A string describing the problem that occurred,
359 possibly one returned by the database back-end.</seg>
365 <refentry id="sql-database-data-error">
367 <refname>SQL-DATABASE-DATA-ERROR</refname>
368 <refpurpose>Used to signal an error with the SQL data passed
369 to a database.</refpurpose>
370 <refclass>Condition Type</refclass>
373 <title>Class Precedence List</title>
375 <simplelist type="inline">
376 <member><errortype>sql-database-data-error</errortype></member>
377 <member><errortype>sql-database-error</errortype></member>
378 <member><errortype>sql-error</errortype></member>
379 <member><errortype>error</errortype></member>
380 <member><errortype>serious-condition</errortype></member>
381 <member><errortype>sql-condition</errortype></member>
382 <member><errortype>condition</errortype></member>
383 <member><errortype>t</errortype></member>
388 <title>Description</title>
389 <para>This condition represents errors that occur while
390 executing SQL statements, specifically as a result of
391 malformed SQL expressions. The following initialization
392 arguments and accessors exist:</para>
394 <segtitle>Initarg</segtitle>
395 <segtitle>Accessor</segtitle>
396 <segtitle>Description</segtitle>
398 <seg><symbol>:expression</symbol></seg>
399 <seg><function>sql-database-error-expression</function></seg>
400 <seg>The SQL expression whose execution caused the error.</seg>
403 <seg><symbol>:database</symbol></seg>
404 <seg><function>sql-database-error-database</function></seg>
405 <seg>The database object that was involved in the
409 <seg><symbol>:error-id</symbol></seg>
410 <seg><function>sql-error-error-id</function></seg>
411 <seg>The numeric or symbolic error specification
412 returned by the database back-end. The values and
413 semantics of this are interface specific.</seg>
416 <seg><symbol>:secondary-error-id</symbol></seg>
417 <seg><function>sql-error-secondary-error-id</function></seg>
418 <seg>The secondary numeric or symbolic error specification
419 returned by the database back-end. The values and
420 semantics of this are interface specific.</seg>
423 <seg><symbol>:message</symbol></seg>
424 <seg><function>sql-error-database-message</function></seg>
425 <seg>A string describing the problem that occurred,
426 possibly one returned by the database back-end.</seg>
432 <refentry id="sql-temporary-error">
434 <refname>SQL-TEMPORARY-ERROR</refname>
435 <refpurpose>Used to signal a temporary error in the database
436 backend.</refpurpose>
437 <refclass>Condition Type</refclass>
440 <title>Class Precedence List</title>
442 <simplelist type="inline">
443 <member><errortype>sql-database-error</errortype></member>
444 <member><errortype>sql-error</errortype></member>
445 <member><errortype>error</errortype></member>
446 <member><errortype>serious-condition</errortype></member>
447 <member><errortype>sql-condition</errortype></member>
448 <member><errortype>condition</errortype></member>
449 <member><errortype>t</errortype></member>
454 <title>Description</title>
455 <para>This condition represents errors occurring when the
456 database cannot currently process a valid interaction because,
457 for example, it is still executing another command possibly
458 issued by another user. The following initialization arguments
459 and accessors exist:</para>
461 <segtitle>Initarg</segtitle>
462 <segtitle>Accessor</segtitle>
463 <segtitle>Description</segtitle>
465 <seg><symbol>:database</symbol></seg>
466 <seg><function>sql-database-error-database</function></seg>
467 <seg>The database object that was involved in the
471 <seg><symbol>:error-id</symbol></seg>
472 <seg><function>sql-error-error-id</function></seg>
473 <seg>The numeric or symbolic error specification
474 returned by the database back-end. The values and
475 semantics of this are interface specific.</seg>
478 <seg><symbol>:secondary-error-id</symbol></seg>
479 <seg><function>sql-error-secondary-error-id</function></seg>
480 <seg>The secondary numeric or symbolic error specification
481 returned by the database back-end. The values and
482 semantics of this are interface specific.</seg>
485 <seg><symbol>:message</symbol></seg>
486 <seg><function>sql-error-database-message</function></seg>
487 <seg>A string describing the problem that occurred,
488 possibly one returned by the database back-end.</seg>
494 <refentry id="sql-timeout-error">
496 <refname>SQL-TIMEOUT-ERROR</refname>
497 <refpurpose>condition representing errors when a connection
498 times out.</refpurpose>
499 <refclass>Condition Type</refclass>
502 <title>Class Precedence List</title>
504 <simplelist type="inline">
505 <member><errortype>sql-connection-error</errortype></member>
506 <member><errortype>sql-database-error</errortype></member>
507 <member><errortype>sql-error</errortype></member>
508 <member><errortype>sql-condition</errortype></member>
509 <member><errortype>condition</errortype></member>
510 <member><errortype>t</errortype></member>
515 <title>Description</title>
516 <para>This condition represents errors that occur when the
517 database times out while processing some operation. The
518 following initialization arguments and accessors exist:</para>
520 <segtitle>Initarg</segtitle>
521 <segtitle>Accessor</segtitle>
522 <segtitle>Description</segtitle>
524 <seg><symbol>:database-type</symbol></seg>
525 <seg><function>sql-connection-error-database-type</function></seg>
526 <seg>Database type for the connection attempt</seg>
529 <seg><symbol>:connection-spec</symbol></seg>
530 <seg><function>sql-connection-error-connection-spec</function></seg>
531 <seg>The connection specification used in the
532 connection attempt.</seg>
535 <seg><symbol>:database</symbol></seg>
536 <seg><function>sql-database-error-database</function></seg>
537 <seg>The database object that was involved in the
541 <seg><symbol>:error-id</symbol></seg>
542 <seg><function>sql-error-error-id</function></seg>
543 <seg>The numeric or symbolic error specification
544 returned by the database back-end. The values and
545 semantics of this are interface specific.</seg>
548 <seg><symbol>:secondary-error-id</symbol></seg>
549 <seg><function>sql-error-secondary-error-id</function></seg>
550 <seg>The secondary numeric or symbolic error specification
551 returned by the database back-end. The values and
552 semantics of this are interface specific.</seg>
555 <seg><symbol>:message</symbol></seg>
556 <seg><function>sql-error-database-message</function></seg>
557 <seg>A string describing the problem that occurred,
558 possibly one returned by the database back-end.</seg>
564 <refentry id="sql-fatal-error">
566 <refname>SQL-FATAL-ERROR</refname>
567 <refpurpose>condition representing a fatal error in a database
568 connection</refpurpose>
569 <refclass>Condition Type</refclass>
572 <title>Class Precedence List</title>
574 <simplelist type="inline">
575 <member><errortype>sql-connection-error</errortype></member>
576 <member><errortype>sql-database-error</errortype></member>
577 <member><errortype>sql-error</errortype></member>
578 <member><errortype>sql-condition</errortype></member>
579 <member><errortype>condition</errortype></member>
580 <member><errortype>t</errortype></member>
585 <title>Description</title>
586 <para>This condition represents errors occurring when the
587 database connection is no longer usable. The following
588 initialization arguments and accessors exist:</para>
590 <segtitle>Initarg</segtitle>
591 <segtitle>Accessor</segtitle>
592 <segtitle>Description</segtitle>
594 <seg><symbol>:database-type</symbol></seg>
595 <seg><function>sql-connection-error-database-type</function></seg>
596 <seg>Database type for the connection attempt</seg>
599 <seg><symbol>:connection-spec</symbol></seg>
600 <seg><function>sql-connection-error-connection-spec</function></seg>
601 <seg>The connection specification used in the
602 connection attempt.</seg>
605 <seg><symbol>:database</symbol></seg>
606 <seg><function>sql-database-error-database</function></seg>
607 <seg>The database object that was involved in the
611 <seg><symbol>:error-id</symbol></seg>
612 <seg><function>sql-error-error-id</function></seg>
613 <seg>The numeric or symbolic error specification
614 returned by the database back-end. The values and
615 semantics of this are interface specific.</seg>
618 <seg><symbol>:secondary-error-id</symbol></seg>
619 <seg><function>sql-error-secondary-error-id</function></seg>
620 <seg>The secondary numeric or symbolic error specification
621 returned by the database back-end. The values and
622 semantics of this are interface specific.</seg>
625 <seg><symbol>:message</symbol></seg>
626 <seg><function>sql-error-database-message</function></seg>
627 <seg>A string describing the problem that occurred,
628 possibly one returned by the database back-end.</seg>