doc/ref-conditions.xml

   1 <?xml version='1.0' ?>
   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">
   5 %myents;
   6 ]>
   7
   8 <!-- Condition System -->
   9 <reference id="ref-conditions">
  10   <title>CLSQL Condition System</title>
  11     <partintro>
  12     <para>
  13       <!-- introduction -->
  14     </para>
  15   </partintro>
  16
  17   <refentry id="backend-warning-behavior">
  18     <refnamediv>
  19       <refname>*BACKEND-WARNING-BEHAVIOR*</refname>
  20       <refpurpose><!-- purpose --></refpurpose>
  21       <refclass>Variable</refclass>
  22     </refnamediv>
  23     <refsect1>
  24       <title>Value Type</title>
  25       <para>
  26         <!-- value type -->
  27       </para>
  28     </refsect1>
  29     <refsect1>
  30       <title>Initial Value</title>
  31       <para><symbol>nil</symbol></para>
  32     </refsect1>
  33     <refsect1>
  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.
  37     </refsect1>
  38     <refsect1>
  39       <title>Examples</title>
  40       <screen>
  41         <!-- examples -->
  42       </screen>
  43     </refsect1>
  44     <refsect1>
  45       <title>Affected By</title>
  46       <para>None.</para>
  47     </refsect1>
  48     <refsect1>
  49       <title>See Also</title>
  50       <para>None.</para>
  51     </refsect1>
  52     <refsect1>
  53       <title>Notes</title>
  54       <para>None.</para>
  55     </refsect1>
  56   </refentry>
  57
  58     <refentry id="sql-condition">
  59       <refnamediv>
  60         <refname>SQL-CONDITION</refname>
  61         <refpurpose>the super-type of all
  62           &clsql;-specific
  63           conditions</refpurpose>
  64         <refclass>Condition Type</refclass>
  65       </refnamediv>
  66       <refsect1>
  67         <title>Class Precedence List</title>
  68         <para>
  69         <simplelist type="inline">
  70           <member><errortype>sql-condition</errortype></member>
  71           <member><errortype>condition</errortype></member>
  72           <member><errortype>t</errortype></member>
  73         </simplelist>
  74         </para>
  75       </refsect1>
  76       <refsect1>
  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>
  83       </refsect1>
  84     </refentry>
  85
  86     <refentry id="sql-error">
  87       <refnamediv>
  88         <refname>SQL-ERROR</refname>
  89         <refpurpose>the super-type of all
  90           &clsql;-specific
  91           errors</refpurpose>
  92         <refclass>Condition Type</refclass>
  93       </refnamediv>
  94       <refsect1>
  95         <title>Class Precedence List</title>
  96         <para>
  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>
 104         </simplelist>
 105         </para>
 106       </refsect1>
 107       <refsect1>
 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>
 115       </refsect1>
 116     </refentry>
 117
 118     <refentry id="sql-warning">
 119       <refnamediv>
 120         <refname>SQL-WARNING</refname>
 121         <refpurpose>the super-type of all
 122           &clsql;-specific
 123           warnings</refpurpose>
 124         <refclass>Condition Type</refclass>
 125       </refnamediv>
 126       <refsect1>
 127         <title>Class Precedence List</title>
 128         <para>
 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>
 135         </simplelist>
 136         </para>
 137       </refsect1>
 138       <refsect1>
 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>
 146       </refsect1>
 147     </refentry>
 148
 149     <refentry id="sql-database-warning">
 150       <refnamediv>
 151         <refname>SQL-DATABASE-WARNING</refname>
 152         <refpurpose>Used to warn while accessing a
 153           &clsql; database.</refpurpose>
 154         <refclass>Condition Type</refclass>
 155       </refnamediv>
 156       <refsect1>
 157         <title>Class Precedence List</title>
 158         <para>
 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>
 166         </simplelist>
 167         </para>
 168       </refsect1>
 169       <refsect1>
 170         <title>Description</title>
 171         <para>
 172           This condition represents warnings signalled while accessing
 173           a database. The following initialization arguments and
 174           accessors exist:
 175         </para>
 176         <segmentedlist>
 177           <segtitle>Initarg</segtitle>
 178           <segtitle>Accessor</segtitle>
 179           <segtitle>Description</segtitle>
 180           <seglistitem>
 181             <seg><symbol>:database</symbol></seg>
 182             <seg><function>sql-warning-database</function></seg>
 183             <seg>The database object that was involved in the
 184             incident.</seg>
 185           </seglistitem>
 186         </segmentedlist>
 187       </refsect1>
 188     </refentry>
 189
 190     <!-- Specific Conditions -->
 191
 192     <refentry id="sql-user-error">
 193       <refnamediv>
 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>
 198       </refnamediv>
 199       <refsect1>
 200         <title>Class Precedence List</title>
 201         <para>
 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>
 208         </simplelist>
 209         </para>
 210       </refsect1>
 211       <refsect1>
 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
 218           accessors exist:
 219         </para>
 220         <segmentedlist>
 221           <segtitle>Initarg</segtitle>
 222           <segtitle>Accessor</segtitle>
 223           <segtitle>Description</segtitle>
 224           <seglistitem>
 225             <seg><symbol>:message</symbol></seg>
 226             <seg><function>sql-user-error-message</function></seg>
 227             <seg>The error message.</seg>
 228           </seglistitem>
 229         </segmentedlist>
 230       </refsect1>
 231     </refentry>
 232
 233     <refentry id="sql-database-error">
 234       <refnamediv>
 235         <refname>SQL-DATABASE-ERROR</refname>
 236         <refpurpose>condition representing errors during query or
 237           command execution</refpurpose>
 238         <refclass>Condition Type</refclass>
 239       </refnamediv>
 240       <refsect1>
 241         <title>Class Precedence List</title>
 242         <para>
 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>
 251         </simplelist>
 252         </para>
 253       </refsect1>
 254       <refsect1>
 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>
 261         <segmentedlist>
 262           <segtitle>Initarg</segtitle>
 263           <segtitle>Accessor</segtitle>
 264           <segtitle>Description</segtitle>
 265           <seglistitem>
 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
 269               incident.</seg>
 270           </seglistitem>
 271           <seglistitem>
 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>
 277           </seglistitem>
 278           <seglistitem>
 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>
 284           </seglistitem>
 285           <seglistitem>
 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>
 290           </seglistitem>
 291         </segmentedlist>
 292       </refsect1>
 293     </refentry>
 294
 295     <refentry id="sql-connection-error">
 296       <refnamediv>
 297         <refname>SQL-CONNECTION-ERROR</refname>
 298         <refpurpose>condition representing errors during
 299           connection</refpurpose>
 300         <refclass>Condition Type</refclass>
 301       </refnamediv>
 302       <refsect1>
 303         <title>Class Precedence List</title>
 304         <para>
 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>
 312         </simplelist>
 313         </para>
 314       </refsect1>
 315       <refsect1>
 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>
 320         <segmentedlist>
 321           <segtitle>Initarg</segtitle>
 322           <segtitle>Accessor</segtitle>
 323           <segtitle>Description</segtitle>
 324           <seglistitem>
 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>
 328           </seglistitem>
 329           <seglistitem>
 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>
 334           </seglistitem>
 335           <seglistitem>
 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
 339               incident.</seg>
 340           </seglistitem>
 341           <seglistitem>
 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>
 347           </seglistitem>
 348           <seglistitem>
 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>
 354           </seglistitem>
 355           <seglistitem>
 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>
 360           </seglistitem>
 361         </segmentedlist>
 362       </refsect1>
 363     </refentry>
 364
 365     <refentry id="sql-database-data-error">
 366       <refnamediv>
 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>
 371       </refnamediv>
 372       <refsect1>
 373         <title>Class Precedence List</title>
 374         <para>
 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>
 384         </simplelist>
 385         </para>
 386       </refsect1>
 387       <refsect1>
 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>
 393         <segmentedlist>
 394           <segtitle>Initarg</segtitle>
 395           <segtitle>Accessor</segtitle>
 396           <segtitle>Description</segtitle>
 397           <seglistitem>
 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>
 401           </seglistitem>
 402           <seglistitem>
 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
 406               incident.</seg>
 407           </seglistitem>
 408           <seglistitem>
 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>
 414           </seglistitem>
 415           <seglistitem>
 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>
 421           </seglistitem>
 422           <seglistitem>
 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>
 427           </seglistitem>
 428         </segmentedlist>
 429       </refsect1>
 430     </refentry>
 431
 432     <refentry id="sql-temporary-error">
 433       <refnamediv>
 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>
 438       </refnamediv>
 439       <refsect1>
 440         <title>Class Precedence List</title>
 441         <para>
 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>
 450         </simplelist>
 451         </para>
 452       </refsect1>
 453       <refsect1>
 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>
 460         <segmentedlist>
 461           <segtitle>Initarg</segtitle>
 462           <segtitle>Accessor</segtitle>
 463           <segtitle>Description</segtitle>
 464           <seglistitem>
 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
 468               incident.</seg>
 469           </seglistitem>
 470           <seglistitem>
 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>
 476           </seglistitem>
 477           <seglistitem>
 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>
 483           </seglistitem>
 484           <seglistitem>
 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>
 489           </seglistitem>
 490         </segmentedlist>
 491       </refsect1>
 492     </refentry>
 493
 494     <refentry id="sql-timeout-error">
 495       <refnamediv>
 496         <refname>SQL-TIMEOUT-ERROR</refname>
 497         <refpurpose>condition representing errors when a connection
 498         times out.</refpurpose>
 499         <refclass>Condition Type</refclass>
 500       </refnamediv>
 501       <refsect1>
 502         <title>Class Precedence List</title>
 503         <para>
 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>
 511         </simplelist>
 512         </para>
 513       </refsect1>
 514       <refsect1>
 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>
 519         <segmentedlist>
 520           <segtitle>Initarg</segtitle>
 521           <segtitle>Accessor</segtitle>
 522           <segtitle>Description</segtitle>
 523           <seglistitem>
 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>
 527           </seglistitem>
 528           <seglistitem>
 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>
 533           </seglistitem>
 534           <seglistitem>
 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
 538               incident.</seg>
 539           </seglistitem>
 540           <seglistitem>
 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>
 546           </seglistitem>
 547           <seglistitem>
 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>
 553           </seglistitem>
 554           <seglistitem>
 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>
 559           </seglistitem>
 560         </segmentedlist>
 561       </refsect1>
 562     </refentry>
 563
 564     <refentry id="sql-fatal-error">
 565       <refnamediv>
 566         <refname>SQL-FATAL-ERROR</refname>
 567         <refpurpose>condition representing a fatal error in a database
 568         connection</refpurpose>
 569         <refclass>Condition Type</refclass>
 570       </refnamediv>
 571       <refsect1>
 572         <title>Class Precedence List</title>
 573         <para>
 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>
 581         </simplelist>
 582         </para>
 583       </refsect1>
 584       <refsect1>
 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>
 589         <segmentedlist>
 590           <segtitle>Initarg</segtitle>
 591           <segtitle>Accessor</segtitle>
 592           <segtitle>Description</segtitle>
 593           <seglistitem>
 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>
 597           </seglistitem>
 598           <seglistitem>
 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>
 603           </seglistitem>
 604           <seglistitem>
 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
 608               incident.</seg>
 609           </seglistitem>
 610           <seglistitem>
 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>
 616           </seglistitem>
 617           <seglistitem>
 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>
 623           </seglistitem>
 624           <seglistitem>
 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>
 629           </seglistitem>
 630         </segmentedlist>
 631       </refsect1>
 632     </refentry>
 633
 634 </reference>