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 -->
10 <reference id="ref-conditions">
11 <title>CLSQL Condition System</title>
14 &clsql; provides and uses a condition system in which all errors
15 and warnings are of type <link
16 linkend="sql-condition"><errortype>sql-condition</errortype></link>. This
17 section describes the various subclasses of <link
18 linkend="sql-condition"><errortype>sql-condition</errortype></link>
19 defined by &clsql;. Details are also provided for how they are
20 used in &clsql; and intended to be signalled in user
21 code. Finally, slot accessors for some of the condition types
26 <refentry id="backend-warning-behavior">
28 <refentrytitle>*BACKEND-WARNING-BEHAVIOR*</refentrytitle>
31 <refname>*BACKEND-WARNING-BEHAVIOR*</refname>
32 <refpurpose>Controls behaviour on warnings from underlying RDBMS.</refpurpose>
33 <refclass>Variable</refclass>
36 <title>Value Type</title>
38 Meaningful values are <symbol>:warn</symbol>,
39 <symbol>:error</symbol>, <symbol>:ignore</symbol> and &nil;.
43 <title>Initial Value</title>
44 <para><symbol>:warn</symbol></para>
47 <title>Description</title>
49 Action to perform on warning messages
50 from backend. Default is to <symbol>:warn</symbol>. May also be
51 set to <symbol>:error</symbol> to signal an error or
52 <symbol>:ignore</symbol> or &nil; to silently ignore the
57 <title>Examples</title>
63 <title>Affected By</title>
67 <title>See Also</title>
72 <para><symbol>*backend-warning-behaviour*</symbol> is a &clsql;
77 <refentry id="sql-condition">
79 <refentrytitle>SQL-CONDITION</refentrytitle>
82 <refname>SQL-CONDITION</refname>
83 <refpurpose>the super-type of all
85 conditions</refpurpose>
86 <refclass>Condition Type</refclass>
89 <title>Class Precedence List</title>
91 <simplelist type="inline">
92 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
93 <member><errortype>condition</errortype></member>
94 <member><errortype>t</errortype></member>
99 <title>Description</title>
101 This is the super-type of all &clsql;-specific conditions
102 defined by &clsql;, or any of it's database-specific
103 interfaces. There are no defined initialization arguments nor
109 <para><errortype>sql-condition</errortype> is a &clsql;
114 <refentry id="sql-error">
116 <refentrytitle>SQL-ERROR</refentrytitle>
119 <refname>SQL-ERROR</refname>
120 <refpurpose>the super-type of all
123 <refclass>Condition Type</refclass>
126 <title>Class Precedence List</title>
128 <simplelist type="inline">
129 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
130 <member><errortype>simple-error</errortype></member>
131 <member><errortype>simple-condition</errortype></member>
132 <member><errortype>error</errortype></member>
133 <member><errortype>serious-condition</errortype></member>
134 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
135 <member><errortype>condition</errortype></member>
136 <member><errortype>t</errortype></member>
141 <title>Description</title>
143 This is the super-type of all &clsql;-specific conditions that
144 represent errors, as defined by &clsql;, or any of it's
145 database-specific interfaces. There are no defined
146 initialization arguments nor any accessors.
151 <para><errortype>sql-error</errortype> is a &clsql; extension.</para>
155 <refentry id="sql-warning">
157 <refentrytitle>SQL-WARNING</refentrytitle>
160 <refname>SQL-WARNING</refname>
161 <refpurpose>the super-type of all
163 warnings</refpurpose>
164 <refclass>Condition Type</refclass>
167 <title>Class Precedence List</title>
169 <simplelist type="inline">
170 <member><link linkend="sql-warning"><errortype>sql-warning</errortype></link></member>
171 <member><errortype>warning</errortype></member>
172 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
173 <member><errortype>condition</errortype></member>
174 <member><errortype>t</errortype></member>
179 <title>Description</title>
181 This is the super-type of all &clsql;-specific conditions that
182 represent warnings, as defined by &clsql;, or any of it's
183 database-specific interfaces. There are no defined
184 initialization arguments nor any accessors.
189 <para><errortype>sql-warning</errortype> is a &clsql; extension.</para>
193 <refentry id="sql-database-warning">
195 <refentrytitle>SQL-DATABASE-WARNING</refentrytitle>
198 <refname>SQL-DATABASE-WARNING</refname>
199 <refpurpose>Used to warn while accessing a
200 &clsql; database.</refpurpose>
201 <refclass>Condition Type</refclass>
204 <title>Class Precedence List</title>
206 <simplelist type="inline">
207 <member><link linkend="sql-database-warning"><errortype>sql-database-warning</errortype></link></member>
208 <member><link linkend="sql-warning"><errortype>sql-warning</errortype></link></member>
209 <member><errortype>warning</errortype></member>
210 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
211 <member><errortype>condition</errortype></member>
212 <member><errortype>t</errortype></member>
217 <title>Description</title>
219 This condition represents warnings signalled while accessing
223 The following initialization arguments and accessors exist:
226 <segtitle>Initarg</segtitle>
227 <segtitle>Accessor</segtitle>
228 <segtitle>Description</segtitle>
230 <seg><symbol>:database</symbol></seg>
231 <seg><function>sql-warning-database</function></seg>
232 <seg>The database object that was involved in the
239 <para><errortype>sql-database-warning</errortype> is a &clsql;
244 <!-- Specific Conditions -->
246 <refentry id="sql-user-error">
248 <refentrytitle>SQL-USER-ERROR</refentrytitle>
251 <refname>SQL-USER-ERROR</refname>
252 <refpurpose>condition representing errors because of invalid
253 parameters from the library user.</refpurpose>
254 <refclass>Condition Type</refclass>
257 <title>Class Precedence List</title>
259 <simplelist type="inline">
260 <member><errortype>sql-user-error</errortype></member>
261 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
262 <member><errortype>simple-error</errortype></member>
263 <member><errortype>simple-condition</errortype></member>
264 <member><errortype>error</errortype></member>
265 <member><errortype>serious-condition</errortype></member>
266 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
267 <member><errortype>condition</errortype></member>
268 <member><errortype>t</errortype></member>
273 <title>Description</title>
275 This condition represents errors that occur because the user
276 supplies invalid data to &clsql;. This includes errors such
277 as an invalid format connection specification or an error in
278 the syntax for the <function>LOOP</function> macro extensions.
281 The following initialization arguments and accessors exist:
284 <segtitle>Initarg</segtitle>
285 <segtitle>Accessor</segtitle>
286 <segtitle>Description</segtitle>
288 <seg><symbol>:message</symbol></seg>
289 <seg><function>sql-user-error-message</function></seg>
290 <seg>The error message.</seg>
296 <para>The slot accessor
297 <function>sql-user-error-message</function> is a &clsql;
302 <refentry id="sql-database-error">
304 <refentrytitle>SQL-DATABASE-ERROR</refentrytitle>
307 <refname>SQL-DATABASE-ERROR</refname>
308 <refpurpose>condition representing errors during query or
309 command execution</refpurpose>
310 <refclass>Condition Type</refclass>
313 <title>Class Precedence List</title>
315 <simplelist type="inline">
316 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
317 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
318 <member><errortype>simple-error</errortype></member>
319 <member><errortype>simple-condition</errortype></member>
320 <member><errortype>error</errortype></member>
321 <member><errortype>serious-condition</errortype></member>
322 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
323 <member><errortype>condition</errortype></member>
324 <member><errortype>t</errortype></member>
329 <title>Description</title>
331 This condition represents errors that occur while executing
332 SQL statements, either as part of query operations or command
333 execution, either explicitly or implicitly, as caused e.g. by
334 <function>with-transaction</function>.
337 The following initialization arguments and accessors exist:
340 <segtitle>Initarg</segtitle>
341 <segtitle>Accessor</segtitle>
342 <segtitle>Description</segtitle>
344 <seg><symbol>:database</symbol></seg>
345 <seg><function>sql-error-database</function></seg>
346 <seg>The database object that was involved in the
350 <seg><symbol>:error-id</symbol></seg>
351 <seg><function>sql-error-error-id</function></seg>
352 <seg>The numeric or symbolic error specification
353 returned by the database back-end. The values and
354 semantics of this are interface specific.</seg>
357 <seg><symbol>:secondary-error-id</symbol></seg>
358 <seg><function>sql-error-secondary-error-id</function></seg>
359 <seg>The secondary numeric or symbolic error specification
360 returned by the database back-end. The values and
361 semantics of this are interface specific.</seg>
364 <seg><symbol>:message</symbol></seg>
365 <seg><function>sql-error-database-message</function></seg>
366 <seg>A string describing the problem that occurred,
367 possibly one returned by the database back-end.</seg>
375 <function>sql-error-database</function> is a &clsql;
381 <refentry id="sql-connection-error">
383 <refentrytitle>SQL-CONNECTION-ERROR</refentrytitle>
386 <refname>SQL-CONNECTION-ERROR</refname>
387 <refpurpose>condition representing errors during
388 connection</refpurpose>
389 <refclass>Condition Type</refclass>
392 <title>Class Precedence List</title>
394 <simplelist type="inline">
395 <member><link linkend="sql-connection-error"><errortype>sql-connection-error</errortype></link></member>
396 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
397 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
398 <member><errortype>simple-error</errortype></member>
399 <member><errortype>simple-condition</errortype></member>
400 <member><errortype>error</errortype></member>
401 <member><errortype>serious-condition</errortype></member>
402 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
403 <member><errortype>condition</errortype></member>
404 <member><errortype>t</errortype></member>
409 <title>Description</title>
411 This condition represents errors that occur while trying to
412 connect to a database.
415 The following initialization arguments and accessors exist:
418 <segtitle>Initarg</segtitle>
419 <segtitle>Accessor</segtitle>
420 <segtitle>Description</segtitle>
422 <seg><symbol>:database-type</symbol></seg>
423 <seg><function>sql-error-database-type</function></seg>
424 <seg>Database type for the connection attempt</seg>
427 <seg><symbol>:connection-spec</symbol></seg>
428 <seg><function>sql-error-connection-spec</function></seg>
429 <seg>The connection specification used in the
430 connection attempt.</seg>
433 <seg><symbol>:database</symbol></seg>
434 <seg><function>sql-error-database</function></seg>
435 <seg>The database object that was involved in the
439 <seg><symbol>:error-id</symbol></seg>
440 <seg><function>sql-error-error-id</function></seg>
441 <seg>The numeric or symbolic error specification
442 returned by the database back-end. The values and
443 semantics of this are interface specific.</seg>
446 <seg><symbol>:secondary-error-id</symbol></seg>
447 <seg><function>sql-error-secondary-error-id</function></seg>
448 <seg>The secondary numeric or symbolic error specification
449 returned by the database back-end. The values and
450 semantics of this are interface specific.</seg>
453 <seg><symbol>:message</symbol></seg>
454 <seg><function>sql-database-error-error</function></seg>
455 <seg>A string describing the problem that occurred,
456 possibly one returned by the database back-end.</seg>
464 <function>sql-error-database</function>,
465 <function>sql-error-database-type</function> and
466 <function>sql-error-connection-spec</function> are
472 <refentry id="sql-database-data-error">
474 <refentrytitle>SQL-DATABASE-DATA-ERROR</refentrytitle>
477 <refname>SQL-DATABASE-DATA-ERROR</refname>
478 <refpurpose>Used to signal an error with the SQL data passed
479 to a database.</refpurpose>
480 <refclass>Condition Type</refclass>
483 <title>Class Precedence List</title>
485 <simplelist type="inline">
486 <member><errortype>sql-database-data-error</errortype></member>
487 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
488 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
489 <member><errortype>simple-error</errortype></member>
490 <member><errortype>simple-condition</errortype></member>
491 <member><errortype>error</errortype></member>
492 <member><errortype>serious-condition</errortype></member>
493 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
494 <member><errortype>condition</errortype></member>
495 <member><errortype>t</errortype></member>
500 <title>Description</title>
501 <para>This condition represents errors that occur while
502 executing SQL statements, specifically as a result of
503 malformed SQL expressions.
506 The following initialization arguments and accessors exist:
509 <segtitle>Initarg</segtitle>
510 <segtitle>Accessor</segtitle>
511 <segtitle>Description</segtitle>
513 <seg><symbol>:expression</symbol></seg>
514 <seg><function>sql-error-expression</function></seg>
515 <seg>The SQL expression whose execution caused the error.</seg>
518 <seg><symbol>:database</symbol></seg>
519 <seg><function>sql-error-database</function></seg>
520 <seg>The database object that was involved in the
524 <seg><symbol>:error-id</symbol></seg>
525 <seg><function>sql-error-error-id</function></seg>
526 <seg>The numeric or symbolic error specification
527 returned by the database back-end. The values and
528 semantics of this are interface specific.</seg>
531 <seg><symbol>:secondary-error-id</symbol></seg>
532 <seg><function>sql-error-secondary-error-id</function></seg>
533 <seg>The secondary numeric or symbolic error specification
534 returned by the database back-end. The values and
535 semantics of this are interface specific.</seg>
538 <seg><symbol>:message</symbol></seg>
539 <seg><function>sql-error-database-message</function></seg>
540 <seg>A string describing the problem that occurred,
541 possibly one returned by the database back-end.</seg>
549 <function>sql-error-database</function> and
550 <function>sql-error-expression</function> are
556 <refentry id="sql-temporary-error">
558 <refentrytitle>SQL-TEMPORARY-ERROR</refentrytitle>
561 <refname>SQL-TEMPORARY-ERROR</refname>
562 <refpurpose>Used to signal a temporary error in the database
563 backend.</refpurpose>
564 <refclass>Condition Type</refclass>
567 <title>Class Precedence List</title>
569 <simplelist type="inline">
570 <member><errortype>sql-temporary-error</errortype></member>
571 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
572 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
573 <member><errortype>simple-error</errortype></member>
574 <member><errortype>simple-condition</errortype></member>
575 <member><errortype>error</errortype></member>
576 <member><errortype>serious-condition</errortype></member>
577 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
578 <member><errortype>condition</errortype></member>
579 <member><errortype>t</errortype></member>
584 <title>Description</title>
586 This condition represents errors occurring when the database
587 cannot currently process a valid interaction because, for
588 example, it is still executing another command possibly issued
592 The following initialization arguments and accessors exist:
595 <segtitle>Initarg</segtitle>
596 <segtitle>Accessor</segtitle>
597 <segtitle>Description</segtitle>
599 <seg><symbol>:database</symbol></seg>
600 <seg><function>sql-error-database</function></seg>
601 <seg>The database object that was involved in the
605 <seg><symbol>:error-id</symbol></seg>
606 <seg><function>sql-error-error-id</function></seg>
607 <seg>The numeric or symbolic error specification
608 returned by the database back-end. The values and
609 semantics of this are interface specific.</seg>
612 <seg><symbol>:secondary-error-id</symbol></seg>
613 <seg><function>sql-error-secondary-error-id</function></seg>
614 <seg>The secondary numeric or symbolic error specification
615 returned by the database back-end. The values and
616 semantics of this are interface specific.</seg>
619 <seg><symbol>:message</symbol></seg>
620 <seg><function>sql-error-database-message</function></seg>
621 <seg>A string describing the problem that occurred,
622 possibly one returned by the database back-end.</seg>
630 <function>sql-error-database</function> is a &clsql;
636 <refentry id="sql-timeout-error">
638 <refentrytitle>SQL-TIMEOUT-ERROR</refentrytitle>
641 <refname>SQL-TIMEOUT-ERROR</refname>
642 <refpurpose>condition representing errors when a connection
643 times out.</refpurpose>
644 <refclass>Condition Type</refclass>
647 <title>Class Precedence List</title>
649 <simplelist type="inline">
650 <member><link linkend="sql-connection-error"><errortype>sql-connection-error</errortype></link></member>
651 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
652 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
653 <member><errortype>simple-error</errortype></member>
654 <member><errortype>simple-condition</errortype></member>
655 <member><errortype>error</errortype></member>
656 <member><errortype>serious-condition</errortype></member>
657 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
658 <member><errortype>condition</errortype></member>
659 <member><errortype>t</errortype></member>
664 <title>Description</title>
665 <para>This condition represents errors that occur when the
666 database times out while processing some operation. The
667 following initialization arguments and accessors exist:</para>
669 <segtitle>Initarg</segtitle>
670 <segtitle>Accessor</segtitle>
671 <segtitle>Description</segtitle>
673 <seg><symbol>:database-type</symbol></seg>
674 <seg><function>sql-error-database-type</function></seg>
675 <seg>Database type for the connection attempt</seg>
678 <seg><symbol>:connection-spec</symbol></seg>
679 <seg><function>sql-error-connection-spec</function></seg>
680 <seg>The connection specification used in the
681 connection attempt.</seg>
684 <seg><symbol>:database</symbol></seg>
685 <seg><function>sql-error-database</function></seg>
686 <seg>The database object that was involved in the
690 <seg><symbol>:error-id</symbol></seg>
691 <seg><function>sql-error-error-id</function></seg>
692 <seg>The numeric or symbolic error specification
693 returned by the database back-end. The values and
694 semantics of this are interface specific.</seg>
697 <seg><symbol>:secondary-error-id</symbol></seg>
698 <seg><function>sql-error-secondary-error-id</function></seg>
699 <seg>The secondary numeric or symbolic error specification
700 returned by the database back-end. The values and
701 semantics of this are interface specific.</seg>
704 <seg><symbol>:message</symbol></seg>
705 <seg><function>sql-error-database-message</function></seg>
706 <seg>A string describing the problem that occurred,
707 possibly one returned by the database back-end.</seg>
715 <function>sql-error-database</function>,
716 <function>sql-error-database-type</function> and
717 <function>sql-error-connection-spec</function> are
723 <refentry id="sql-fatal-error">
725 <refentrytitle>SQL-FATAL-ERROR</refentrytitle>
728 <refname>SQL-FATAL-ERROR</refname>
729 <refpurpose>condition representing a fatal error in a database
730 connection</refpurpose>
731 <refclass>Condition Type</refclass>
734 <title>Class Precedence List</title>
736 <simplelist type="inline">
737 <member><link linkend="sql-connection-error"><errortype>sql-connection-error</errortype></link></member>
738 <member><link linkend="sql-database-error"><errortype>sql-database-error</errortype></link></member>
739 <member><link linkend="sql-error"><errortype>sql-error</errortype></link></member>
740 <member><errortype>simple-error</errortype></member>
741 <member><errortype>simple-condition</errortype></member>
742 <member><errortype>error</errortype></member>
743 <member><errortype>serious-condition</errortype></member>
744 <member><link linkend="sql-condition"><errortype>sql-condition</errortype></link></member>
745 <member><errortype>condition</errortype></member>
746 <member><errortype>t</errortype></member>
751 <title>Description</title>
752 <para>This condition represents errors occurring when the
753 database connection is no longer usable.
756 The following initialization arguments and accessors exist:
759 <segtitle>Initarg</segtitle>
760 <segtitle>Accessor</segtitle>
761 <segtitle>Description</segtitle>
763 <seg><symbol>:database-type</symbol></seg>
764 <seg><function>sql-error-database-type</function></seg>
765 <seg>Database type for the connection attempt</seg>
768 <seg><symbol>:connection-spec</symbol></seg>
769 <seg><function>sql-error-connection-spec</function></seg>
770 <seg>The connection specification used in the
771 connection attempt.</seg>
774 <seg><symbol>:database</symbol></seg>
775 <seg><function>sql-error-database</function></seg>
776 <seg>The database object that was involved in the
780 <seg><symbol>:error-id</symbol></seg>
781 <seg><function>sql-error-error-id</function></seg>
782 <seg>The numeric or symbolic error specification
783 returned by the database back-end. The values and
784 semantics of this are interface specific.</seg>
787 <seg><symbol>:secondary-error-id</symbol></seg>
788 <seg><function>sql-error-secondary-error-id</function></seg>
789 <seg>The secondary numeric or symbolic error specification
790 returned by the database back-end. The values and
791 semantics of this are interface specific.</seg>
794 <seg><symbol>:message</symbol></seg>
795 <seg><function>sql-error-database-message</function></seg>
796 <seg>A string describing the problem that occurred,
797 possibly one returned by the database back-end.</seg>
805 <function>sql-error-database</function>,
806 <function>sql-error-database-type</function> and
807 <function>sql-error-connection-spec</function> are