doc/ref.sgml

   1 <!-- -*- DocBook -*- -->
   2
   3   <reference>
   4     <title><symbol>CLSQL</symbol></title>
   5     <partintro>
   6     <para>This part gives a reference to all the symbols exported
   7         from the package <symbol>CLSQL-SYS</symbol>, which are also
   8         re-exported from the package <symbol>CLSQL</symbol>.  These
   9         symbols constitute the normal user-interface of
  10         &clsql;.</para>
  11     </partintro>
  12     <!-- Conditions -->
  13     <refentry id="maisql-condition">
  14       <refnamediv>
  15         <refname>CLSQL-CONDITION</refname>
  16         <refpurpose>the super-type of all
  17           &clsql;-specific
  18           conditions</refpurpose>
  19         <refclass>Condition Type</refclass>
  20       </refnamediv>
  21       <refsect1>
  22         <title>Class Precedence List</title>
  23         <para>
  24         <simplelist type="inline">
  25           <member><errortype>maisql-condition</errortype></member>
  26           <member><errortype>condition</errortype></member>
  27           <member><errortype>t</errortype></member>
  28         </simplelist>
  29         </para>
  30       </refsect1>
  31       <refsect1>
  32         <title>Description</title>
  33         <para>This is the super-type of all
  34           &clsql;-specific conditions
  35           defined by &clsql;, or any of it's
  36           database-specific interfaces.  There are no defined
  37           initialization arguments nor any accessors.</para>
  38       </refsect1>
  39     </refentry>
  40     <refentry id="maisql-error">
  41       <refnamediv>
  42         <refname>CLSQL-ERROR</refname>
  43         <refpurpose>the super-type of all
  44           &clsql;-specific
  45           errors</refpurpose>
  46         <refclass>Condition Type</refclass>
  47       </refnamediv>
  48       <refsect1>
  49         <title>Class Precedence List</title>
  50         <para>
  51         <simplelist type="inline">
  52           <member><errortype>maisql-error</errortype></member>
  53           <member><errortype>error</errortype></member>
  54           <member><errortype>serious-condition</errortype></member>
  55           <member><errortype>maisql-condition</errortype></member>
  56           <member><errortype>condition</errortype></member>
  57           <member><errortype>t</errortype></member>
  58         </simplelist>
  59         </para>
  60       </refsect1>
  61       <refsect1>
  62         <title>Description</title>
  63         <para>This is the super-type of all
  64           &clsql;-specific conditions that
  65           represent errors, as defined by
  66           &clsql;, or any of it's
  67           database-specific interfaces.  There are no defined
  68           initialization arguments nor any accessors.</para>
  69       </refsect1>
  70     </refentry>
  71     <refentry id="maisql-simple-error">
  72       <refnamediv>
  73         <refname>CLSQL-SIMPLE-ERROR</refname>
  74         <refpurpose>Unspecific simple
  75           &clsql; errors</refpurpose>
  76         <refclass>Condition Type</refclass>
  77       </refnamediv>
  78       <refsect1>
  79         <title>Class Precedence List</title>
  80         <para>
  81         <simplelist type="inline">
  82           <member><errortype>maisql-simple-error</errortype></member>
  83           <member><errortype>simple-condition</errortype></member>
  84           <member><errortype>maisql-error</errortype></member>
  85           <member><errortype>error</errortype></member>
  86           <member><errortype>serious-condition</errortype></member>
  87           <member><errortype>maisql-condition</errortype></member>
  88           <member><errortype>condition</errortype></member>
  89           <member><errortype>t</errortype></member>
  90         </simplelist>
  91         </para>
  92       </refsect1>
  93       <refsect1>
  94         <title>Description</title>
  95         <para>This condition is used in all instances of errors, where
  96           there exists no &clsql;-specific
  97           condition that is more specific.  The valid initialization
  98           arguments and accessors are the same as for
  99           <errortype>simple-condition</errortype>.</para>
 100       </refsect1>
 101     </refentry>
 102     <refentry id="maisql-warning">
 103       <refnamediv>
 104         <refname>CLSQL-WARNING</refname>
 105         <refpurpose>the super-type of all
 106           &clsql;-specific
 107           warnings</refpurpose>
 108         <refclass>Condition Type</refclass>
 109       </refnamediv>
 110       <refsect1>
 111         <title>Class Precedence List</title>
 112         <para>
 113         <simplelist type="inline">
 114           <member><errortype>maisql-warning</errortype></member>
 115           <member><errortype>warning</errortype></member>
 116           <member><errortype>maisql-condition</errortype></member>
 117           <member><errortype>condition</errortype></member>
 118           <member><errortype>t</errortype></member>
 119         </simplelist>
 120         </para>
 121       </refsect1>
 122       <refsect1>
 123         <title>Description</title>
 124         <para>This is the super-type of all
 125           &clsql;-specific conditions that
 126           represent warnings, as defined by
 127           &clsql;, or any of it's
 128           database-specific interfaces.  There are no defined
 129           initialization arguments nor any accessors.</para>
 130       </refsect1>
 131     </refentry>
 132     <refentry id="maisql-simple-warning">
 133       <refnamediv>
 134         <refname>CLSQL-SIMPLE-WARNING</refname>
 135         <refpurpose>Unspecific simple
 136           &clsql; warnings</refpurpose>
 137         <refclass>Condition Type</refclass>
 138       </refnamediv>
 139       <refsect1>
 140         <title>Class Precedence List</title>
 141         <para>
 142         <simplelist type="inline">
 143           <member><errortype>maisql-simple-warning</errortype></member>
 144           <member><errortype>simple-condition</errortype></member>
 145           <member><errortype>maisql-warning</errortype></member>
 146           <member><errortype>warning</errortype></member>
 147           <member><errortype>maisql-condition</errortype></member>
 148           <member><errortype>condition</errortype></member>
 149           <member><errortype>t</errortype></member>
 150         </simplelist>
 151         </para>
 152       </refsect1>
 153       <refsect1>
 154         <title>Description</title>
 155         <para>This condition is used in all instances of warnings,
 156           where  there exists no
 157           &clsql;-specific condition that is
 158           more specific.  The valid initialization arguments and
 159           accessors are the same as for
 160           <errortype>simple-condition</errortype>.</para>
 161       </refsect1>
 162     </refentry>
 163     <!-- Specifc Conditions -->
 164     <refentry id="maisql-invalid-spec-error">
 165       <refnamediv>
 166         <refname>CLSQL-INVALID-SPEC-ERROR</refname>
 167         <refpurpose>condition representing errors because of invalid
 168           connection specifications</refpurpose>
 169         <refclass>Condition Type</refclass>
 170       </refnamediv>
 171       <refsect1>
 172         <title>Class Precedence List</title>
 173         <para>
 174         <simplelist type="inline">
 175           <member><errortype>maisql-invalid-spec-error</errortype></member>
 176           <member><errortype>maisql-error</errortype></member>
 177           <member><errortype>error</errortype></member>
 178           <member><errortype>serious-condition</errortype></member>
 179           <member><errortype>maisql-condition</errortype></member>
 180           <member><errortype>condition</errortype></member>
 181           <member><errortype>t</errortype></member>
 182         </simplelist>
 183         </para>
 184       </refsect1>
 185       <refsect1>
 186         <title>Description</title>
 187         <para>This condition represents errors that occur because the
 188           user supplies an invalid connection specification to either
 189           <function>database-name-from-spec</function> or
 190           <function>connect</function>.  The following initialization
 191           arguments and accessors exist:</para>
 192         <segmentedlist>
 193           <segtitle>Initarg</segtitle>
 194           <segtitle>Accessor</segtitle>
 195           <segtitle>Description</segtitle>
 196           <seglistitem>
 197             <seg><symbol>:connection-spec</symbol></seg>
 198             <seg><function>maisql-invalid-spec-error-connection-spec</function></seg>
 199             <seg>The invalid connection specification used.</seg>
 200           </seglistitem>
 201           <seglistitem>
 202             <seg><symbol>:database-type</symbol></seg>
 203             <seg><function>maisql-invalid-spec-error-database-type</function></seg>
 204             <seg>The Database type used in the attempt.</seg>
 205           </seglistitem>
 206           <seglistitem>
 207             <seg><symbol>:template</symbol></seg>
 208             <seg><function>maisql-invalid-spec-error-template</function></seg>
 209             <seg>An argument describing the template that a valid
 210               connection specification must match for this database type.</seg>
 211           </seglistitem>
 212         </segmentedlist>
 213       </refsect1>
 214     </refentry>
 215     <refentry id="maisql-connect-error">
 216       <refnamediv>
 217         <refname>CLSQL-CONNECT-ERROR</refname>
 218         <refpurpose>condition representing errors during
 219           connection</refpurpose>
 220         <refclass>Condition Type</refclass>
 221       </refnamediv>
 222       <refsect1>
 223         <title>Class Precedence List</title>
 224         <para>
 225         <simplelist type="inline">
 226           <member><errortype>maisql-connect-error</errortype></member>
 227           <member><errortype>maisql-error</errortype></member>
 228           <member><errortype>error</errortype></member>
 229           <member><errortype>serious-condition</errortype></member>
 230           <member><errortype>maisql-condition</errortype></member>
 231           <member><errortype>condition</errortype></member>
 232           <member><errortype>t</errortype></member>
 233         </simplelist>
 234         </para>
 235       </refsect1>
 236       <refsect1>
 237         <title>Description</title>
 238         <para>This condition represents errors that occur while trying
 239           to connect to a database.  The following initialization
 240           arguments and accessors exist:</para>
 241         <segmentedlist>
 242           <segtitle>Initarg</segtitle>
 243           <segtitle>Accessor</segtitle>
 244           <segtitle>Description</segtitle>
 245           <seglistitem>
 246             <seg><symbol>:database-type</symbol></seg>
 247             <seg><function>maisql-connect-error-database-type</function></seg>
 248             <seg>Database type for the connection attempt</seg>
 249           </seglistitem>
 250           <seglistitem>
 251             <seg><symbol>:connection-spec</symbol></seg>
 252             <seg><function>maisql-connect-error-connection-spec</function></seg>
 253             <seg>The connection specification used in the
 254               connection attempt.</seg>
 255           </seglistitem>
 256           <seglistitem>
 257             <seg><symbol>:errno</symbol></seg>
 258             <seg><function>maisql-connect-error-errno</function></seg>
 259             <seg>The numeric or symbolic error specification
 260               returned by the database back-end.  The values and
 261               semantics of this are interface specific.</seg>
 262           </seglistitem>
 263           <seglistitem>
 264             <seg><symbol>:error</symbol></seg>
 265             <seg><function>maisql-connect-error-error</function></seg>
 266             <seg>A string describing the problem that occurred,
 267               possibly one returned by the database back-end.</seg>
 268           </seglistitem>
 269         </segmentedlist>
 270       </refsect1>
 271     </refentry>
 272     <refentry id="maisql-sql-error">
 273       <refnamediv>
 274         <refname>CLSQL-SQL-ERROR</refname>
 275         <refpurpose>condition representing errors during query or
 276           command execution</refpurpose>
 277         <refclass>Condition Type</refclass>
 278       </refnamediv>
 279       <refsect1>
 280         <title>Class Precedence List</title>
 281         <para>
 282         <simplelist type="inline">
 283           <member><errortype>maisql-sql-error</errortype></member>
 284           <member><errortype>maisql-error</errortype></member>
 285           <member><errortype>error</errortype></member>
 286           <member><errortype>serious-condition</errortype></member>
 287           <member><errortype>maisql-condition</errortype></member>
 288           <member><errortype>condition</errortype></member>
 289           <member><errortype>t</errortype></member>
 290         </simplelist>
 291         </para>
 292       </refsect1>
 293       <refsect1>
 294         <title>Description</title>
 295         <para>This condition represents errors that occur while
 296         executing SQL statements, either as part of query operations
 297         or command execution, either explicitly or implicitly, as
 298           caused e.g. by <function>with-transaction</function>.
 299           The following initialization arguments and accessors exist:</para>
 300         <segmentedlist>
 301           <segtitle>Initarg</segtitle>
 302           <segtitle>Accessor</segtitle>
 303           <segtitle>Description</segtitle>
 304           <seglistitem>
 305             <seg><symbol>:database</symbol></seg>
 306             <seg><function>maisql-sql-error-database</function></seg>
 307             <seg>The database object that was involved in the
 308               incident.</seg>
 309           </seglistitem>
 310           <seglistitem>
 311             <seg><symbol>:expression</symbol></seg>
 312             <seg><function>maisql-sql-error-expression</function></seg>
 313             <seg>The SQL expression whose execution caused the error.</seg>
 314           </seglistitem>
 315           <seglistitem>
 316             <seg><symbol>:errno</symbol></seg>
 317             <seg><function>maisql-sql-error-errno</function></seg>
 318             <seg>The numeric or symbolic error specification
 319               returned by the database back-end.  The values and
 320               semantics of this are interface specific.</seg>
 321           </seglistitem>
 322           <seglistitem>
 323             <seg><symbol>:error</symbol></seg>
 324             <seg><function>maisql-sql-error-error</function></seg>
 325             <seg>A string describing the problem that occurred,
 326               possibly one returned by the database back-end.</seg>
 327           </seglistitem>
 328         </segmentedlist>
 329       </refsect1>
 330     </refentry>
 331     <refentry id="maisql-exists-condition">
 332       <refnamediv>
 333         <refname>CLSQL-EXISTS-CONDITION</refname>
 334         <refpurpose>condition indicating situations arising because of
 335           existing connections</refpurpose>
 336         <refclass>Condition Type</refclass>
 337       </refnamediv>
 338       <refsect1>
 339         <title>Class Precedence List</title>
 340         <para>
 341         <simplelist type="inline">
 342           <member><errortype>maisql-exists-condition</errortype></member>
 343           <member><errortype>maisql-condition</errortype></member>
 344           <member><errortype>condition</errortype></member>
 345           <member><errortype>t</errortype></member>
 346         </simplelist>
 347         </para>
 348       </refsect1>
 349       <refsect1>
 350         <title>Description</title>
 351         <para>This condition is the super-type of all conditions which
 352           represents problems that occur during calls to
 353           <function>connect</function>, if a connection to the
 354           database exists already.  Depending on the value of
 355           <parameter>if-exists</parameter> to the call of
 356           <function>connect</function>, either a warning, an error or
 357           no condition at all is signalled.  If a warning or error is
 358           signalled, either
 359           <errortype>maisql-exists-warning</errortype> or
 360           <errortype>maisql-exists-error</errortype> is signalled,
 361           which are subtypes of
 362           <errortype>maisql-exists-condition</errortype> and
 363           <errortype>maisql-warning</errortype> or
 364           <errortype>maisql-error</errortype>.
 365           <errortype>maisql-exists-condition</errortype> is never
 366           signalled itself.</para>
 367         <para>
 368           The following initialization arguments and accessors exist:</para>
 369         <segmentedlist>
 370           <segtitle>Initarg</segtitle>
 371           <segtitle>Accessor</segtitle>
 372           <segtitle>Description</segtitle>
 373           <seglistitem>
 374             <seg><symbol>:old-db</symbol></seg>
 375             <seg><function>maisql-exists-condition-old-db</function></seg>
 376             <seg>The database object that represents the existing
 377               connection.  This slot is always filled.</seg>
 378           </seglistitem>
 379           <seglistitem>
 380             <seg><symbol>:new-db</symbol></seg>
 381             <seg><function>maisql-exists-condition-new-db</function></seg>
 382             <seg>The database object that will be used and returned by
 383               this call to connect, if execution continues normally.
 384               This can be either <symbol>nil</symbol>, indicating that
 385               a new database object is to be created on continuation,
 386               or a database object representing the newly created
 387               continuation, or the same database object as
 388               <symbol>old-db</symbol>, indicating that the existing
 389               database object will be reused.  This slot is always
 390               filled and defaults to <symbol>nil</symbol>.</seg>
 391           </seglistitem>
 392         </segmentedlist>
 393       </refsect1>
 394     </refentry>
 395     <refentry id="maisql-exists-warning">
 396       <refnamediv>
 397         <refname>CLSQL-EXISTS-WARNING</refname>
 398         <refpurpose>condition representing warnings arising because of
 399           existing connections</refpurpose>
 400         <refclass>Condition Type</refclass>
 401       </refnamediv>
 402       <refsect1>
 403         <title>Class Precedence List</title>
 404         <para>
 405         <simplelist type="inline">
 406           <member><errortype>maisql-exists-warning</errortype></member>
 407           <member><errortype>maisql-exists-condition</errortype></member>
 408           <member><errortype>maisql-warning</errortype></member>
 409           <member><errortype>warning</errortype></member>
 410           <member><errortype>maisql-condition</errortype></member>
 411           <member><errortype>condition</errortype></member>
 412           <member><errortype>t</errortype></member>
 413         </simplelist>
 414         </para>
 415       </refsect1>
 416       <refsect1>
 417         <title>Description</title>
 418         <para>This condition is a subtype of
 419         <errortype>maisql-exists-condition</errortype>, and is
 420           signalled during calls to <function>connect</function> when
 421           there is an existing connection, and
 422           <parameter>if-exists</parameter> is either
 423           <symbol>:warn-new</symbol> or <symbol>:warn-old</symbol>.
 424           In the former case, <symbol>new-db</symbol> will be the
 425           newly created database object, in the latter case it will be
 426           the existing old database object.</para>
 427         <para>
 428           The initialization arguments and accessors are the same as
 429           for <errortype>maisql-exists-condition</errortype>.</para>
 430       </refsect1>
 431     </refentry>
 432     <refentry id="maisql-exists-error">
 433       <refnamediv>
 434         <refname>CLSQL-EXISTS-ERROR</refname>
 435         <refpurpose>condition representing errors arising because of
 436           existing connections</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>maisql-exists-error</errortype></member>
 444           <member><errortype>maisql-exists-condition</errortype></member>
 445           <member><errortype>maisql-error</errortype></member>
 446           <member><errortype>error</errortype></member>
 447           <member><errortype>serious-condition</errortype></member>
 448           <member><errortype>maisql-condition</errortype></member>
 449           <member><errortype>condition</errortype></member>
 450           <member><errortype>t</errortype></member>
 451         </simplelist>
 452         </para>
 453       </refsect1>
 454       <refsect1>
 455         <title>Description</title>
 456         <para>This condition is a subtype of
 457         <errortype>maisql-exists-condition</errortype>, and is
 458           signalled during calls to <function>connect</function> when
 459           there is an existing connection, and
 460           <parameter>if-exists</parameter> is <symbol>:error</symbol>.
 461           In this case, <symbol>new-db</symbol> will be
 462           <symbol>nil</symbol>, indicating that the database object to
 463           be returned by <function>connect</function> depends on user
 464           action in continuing from this correctable error.</para>
 465         <para>
 466           The initialization arguments and accessors are the same as
 467           for <errortype>maisql-exists-condition</errortype>.</para>
 468       </refsect1>
 469     </refentry>
 470     <refentry id="maisql-closed-error">
 471       <refnamediv>
 472         <refname>CLSQL-CLOSED-ERROR</refname>
 473         <refpurpose>condition representing errors because the database
 474           has already been closed</refpurpose>
 475         <refclass>Condition Type</refclass>
 476       </refnamediv>
 477       <refsect1>
 478         <title>Class Precedence List</title>
 479         <para>
 480         <simplelist type="inline">
 481           <member><errortype>maisql-closed-error</errortype></member>
 482           <member><errortype>maisql-error</errortype></member>
 483           <member><errortype>error</errortype></member>
 484           <member><errortype>serious-condition</errortype></member>
 485           <member><errortype>maisql-condition</errortype></member>
 486           <member><errortype>condition</errortype></member>
 487           <member><errortype>t</errortype></member>
 488         </simplelist>
 489         </para>
 490       </refsect1>
 491       <refsect1>
 492         <title>Description</title>
 493         <para>This condition represents errors that occur because the
 494           user invokes an operation on the given database object,
 495           although the database is invalid because
 496           <function>disconnect</function> has already been called on
 497           this database object.</para>
 498         <para>Functions which signal this error when called with a
 499           closed database will usually provide a
 500           <symbol>continue</symbol> restart, that will just return nil
 501           from the function.</para>
 502         <para>
 503           The following initialization arguments and accessors exist:</para>
 504         <segmentedlist>
 505           <segtitle>Initarg</segtitle>
 506           <segtitle>Accessor</segtitle>
 507           <segtitle>Description</segtitle>
 508           <seglistitem>
 509             <seg><symbol>:database</symbol></seg>
 510             <seg><function>maisql-closed-error-database</function></seg>
 511             <seg>The database object that was involved in the
 512               incident.</seg>
 513           </seglistitem>
 514         </segmentedlist>
 515       </refsect1>
 516     </refentry>
 517
 518     <!-- Database Types -->
 519     <refentry id="default-database-type">
 520       <refnamediv>
 521         <refname>*DEFAULT-DATABASE-TYPE*</refname>
 522         <refpurpose>The default database type to use</refpurpose>
 523         <refclass>Variable</refclass>
 524       </refnamediv>
 525       <refsect1>
 526         <title>Value Type</title>
 527         <para>Any keyword representing a valid database back-end of
 528           &clsql;, or
 529           <symbol>nil</symbol>.</para>
 530       </refsect1>
 531       <refsect1>
 532         <title>Initial Value</title>
 533         <para><symbol>nil</symbol></para>
 534       </refsect1>
 535       <refsect1>
 536         <title>Description</title>
 537         <para>The value of this variable is used in calls to
 538           <function>initialize-database-type</function> and
 539           <function>connect</function> as the default
 540           value of the <parameter>database-type</parameter>
 541           parameter.</para>
 542         <caution>
 543           <para>If the value of this variable is <symbol>nil</symbol>,
 544             then all calls to
 545             <function>initialize-database-type</function> or
 546             <function>connect</function> will have to specify the
 547             <parameter>database-type</parameter> to use, or a
 548             general-purpose error will be signalled.</para>
 549         </caution>
 550       </refsect1>
 551       <refsect1>
 552         <title>Examples</title>
 553         <programlisting>
 554 (setf *default-database-type* :mysql)
 555 => :mysql
 556 (initialize-database-type)
 557 => t
 558         </programlisting>
 559       </refsect1>
 560       <refsect1>
 561         <title>Affected By</title>
 562         <para>None.</para>
 563       </refsect1>
 564       <refsect1>
 565         <title>See Also</title>
 566         <para>None.</para>
 567       </refsect1>
 568       <refsect1>
 569         <title>Notes</title>
 570         <para>None.</para>
 571       </refsect1>
 572     </refentry>
 573     <refentry id="initialized-database-types">
 574       <refnamediv>
 575         <refname>*INITIALIZED-DATABASE-TYPES*</refname>
 576         <refpurpose>List of all initialized database types</refpurpose>
 577         <refclass>Variable</refclass>
 578       </refnamediv>
 579       <refsect1>
 580         <title>Value Type</title>
 581         <para>A list of all initialized database types, each of which
 582           represented by it's corresponding keyword.</para>
 583       </refsect1>
 584       <refsect1>
 585         <title>Initial Value</title>
 586         <para><symbol>nil</symbol></para>
 587       </refsect1>
 588       <refsect1>
 589         <title>Description</title>
 590         <para>This variable is updated whenever
 591           <function>initialize-database-type</function> is called for a
 592           database type which hasn't already been initialized before,
 593           as determined by this variable.  In that case the keyword
 594           representing the database type is pushed onto the list
 595           stored in
 596           <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
 597         <caution>
 598           <para>Attempts to modify the value of this variable will
 599             result in undefined behaviour.</para>
 600         </caution>
 601       </refsect1>
 602       <refsect1>
 603         <title>Examples</title>
 604         <programlisting>
 605 (setf *default-database-type* :mysql)
 606 => :mysql
 607 (initialize-database-type)
 608 => t
 609 *initialized-database-types*
 610 => (:MYSQL)
 611         </programlisting>
 612       </refsect1>
 613       <refsect1>
 614         <title>Affected By</title>
 615         <para>
 616         <simplelist>
 617           <member><function>initialize-database-type</function></member>
 618         </simplelist>
 619         </para>
 620       </refsect1>
 621       <refsect1>
 622         <title>See Also</title>
 623         <para>None.</para>
 624       </refsect1>
 625       <refsect1>
 626         <title>Notes</title>
 627         <para>Direct access to this variable is primarily provided
 628           because of compatibility with Harlequin's <application>Common
 629             SQL</application>.</para>
 630       </refsect1>
 631     </refentry>
 632     <refentry id="initialize-database-type">
 633       <refnamediv>
 634         <refname>INITIALIZE-DATABASE-TYPE</refname>
 635         <refpurpose>Initializes a database type</refpurpose>
 636         <refclass>Function</refclass>
 637       </refnamediv>
 638       <refsect1>
 639         <title>Syntax</title>
 640         <synopsis><function>initialize-database-type</function> &amp;key <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
 641       </refsect1>
 642       <refsect1>
 643         <title>Arguments and Values</title>
 644         <variablelist>
 645           <varlistentry>
 646             <term><parameter>database-type</parameter></term>
 647             <listitem>
 648               <para>The database type to initialize, i.e. a keyword
 649                 symbol denoting a known database back-end.  Defaults to
 650                 the value of
 651                 <symbol>*default-database-type*</symbol>.</para>
 652             </listitem>
 653           </varlistentry>
 654           <varlistentry>
 655             <term><returnvalue>result</returnvalue></term>
 656             <listitem>
 657               <para>Either <symbol>nil</symbol> if the initialization
 658                 attempt fails, or <symbol>t</symbol> otherwise.</para>
 659             </listitem>
 660           </varlistentry>
 661         </variablelist>
 662       </refsect1>
 663       <refsect1>
 664         <title>Description</title>
 665         <para>If the back-end specified by
 666         <parameter>database-type</parameter> has not already been
 667           initialized, as seen from
 668           <symbol>*initialized-database-types*</symbol>, an attempt is
 669           made to initialize the database.  If this attempt succeeds,
 670           or the back-end has already been initialized, the function
 671           returns t, and places the keyword denoting the database type
 672           onto the list stored in
 673           <symbol>*initialized-database-types*</symbol>, if not
 674           already present.</para>
 675         <para>If initialization fails, the function returns
 676           <symbol>nil</symbol>, and/or signals an error of type
 677           <errortype>maisql-error</errortype>.  The kind of action
 678           taken depends on the back-end and the cause of the
 679           problem.</para>
 680       </refsect1>
 681       <refsect1>
 682         <title>Examples</title>
 683         <programlisting>
 684 *initialized-database-types*
 685 => NIL
 686 (setf *default-database-type* :mysql)
 687 => :MYSQL
 688 (initialize-database-type)
 689 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
 690 >> Compiling Top-Level Form:
 691 >>
 692 => T
 693 *initialized-database-types*
 694 => (:MYSQL)
 695 (initialize-database-type)
 696 => T
 697 *initialized-database-types*
 698 => (:MYSQL)
 699         </programlisting>
 700       </refsect1>
 701       <refsect1>
 702         <title>Side Effects</title>
 703         <para>The database back-end corresponding to the database type
 704           specified is initialized, unless it has already been
 705           initialized.  This can involve any number of other side
 706           effects, as determined by the back-end implementation (like
 707           e.g. loading of foreign code, calling of foreign code,
 708           networking operations, etc.).  If initialization is
 709           attempted and succeeds, the
 710           <parameter>database-type</parameter> is pushed onto the list
 711           stored in
 712           <symbol>*initialized-database-types*</symbol>.</para>
 713       </refsect1>
 714       <refsect1>
 715         <title>Affected by</title>
 716         <para>
 717         <simplelist>
 718           <member><symbol>*default-database-type*</symbol></member>
 719           <member><symbol>*initialized-database-types*</symbol></member>
 720         </simplelist>
 721         </para>
 722       </refsect1>
 723       <refsect1>
 724         <title>Exceptional Situations</title>
 725         <para>If an error is encountered during the initialization
 726           attempt, the back-end may signal errors of kind
 727           <errortype>maisql-error</errortype>.</para>
 728       </refsect1>
 729       <refsect1>
 730         <title>See Also</title>
 731         <para>None.</para>
 732       </refsect1>
 733       <refsect1>
 734         <title>Notes</title>
 735         <para>None.</para>
 736       </refsect1>
 737     </refentry>
 738     <!-- Databases Connection and Disconnection -->
 739     <refentry id="connect-if-exists">
 740       <refnamediv>
 741         <refname>*CONNECT-IF-EXISTS*</refname>
 742         <refpurpose>Default value for the
 743           <parameter>if-exists</parameter> parameter of
 744           <function>connect</function>.</refpurpose>
 745         <refclass>Variable</refclass>
 746       </refnamediv>
 747       <refsect1>
 748         <title>Value Type</title>
 749         <para>A valid argument to the <parameter>if-exists</parameter>
 750           parameter of <function>connect</function>, i.e. one of
 751           <simplelist type="inline">
 752             <member><symbol>:new</symbol></member>
 753             <member><symbol>:warn-new</symbol></member>
 754             <member><symbol>:error</symbol></member>
 755             <member><symbol>:warn-old</symbol></member>
 756             <member><symbol>:old</symbol></member>
 757           </simplelist>.
 758         </para>
 759       </refsect1>
 760       <refsect1>
 761         <title>Initial Value</title>
 762         <para><symbol>:error</symbol></para>
 763       </refsect1>
 764       <refsect1>
 765         <title>Description</title>
 766         <para>The value of this variable is used in calls to
 767           <function>connect</function> as the default
 768           value of the <parameter>if-exists</parameter>
 769           parameter.  See <link
 770           linkend="connect"><function>connect</function></link> for
 771           the semantics of the valid values for this variable.</para>
 772       </refsect1>
 773       <refsect1>
 774         <title>Examples</title>
 775         <para>None.</para>
 776       </refsect1>
 777       <refsect1>
 778         <title>Affected By</title>
 779         <para>None.</para>
 780       </refsect1>
 781       <refsect1>
 782         <title>See Also</title>
 783         <para>
 784         <simplelist>
 785           <member><link
 786           linkend="connect"><function>connect</function></link></member>
 787         </simplelist>
 788         </para>
 789       </refsect1>
 790       <refsect1>
 791         <title>Notes</title>
 792         <para>None.</para>
 793       </refsect1>
 794     </refentry>
 795     <refentry id="connected-databases">
 796       <refnamediv>
 797         <refname>CONNECTED-DATABASES</refname>
 798         <refpurpose>Return the list of active database
 799           objects.</refpurpose>
 800         <refclass>Function</refclass>
 801       </refnamediv>
 802       <refsect1>
 803         <title>Syntax</title>
 804         <synopsis><function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
 805       </refsect1>
 806       <refsect1>
 807         <title>Arguments and Values</title>
 808         <variablelist>
 809           <varlistentry>
 810             <term><returnvalue>databases</returnvalue></term>
 811             <listitem>
 812               <para>The list of active database objects.</para>
 813             </listitem>
 814           </varlistentry>
 815         </variablelist>
 816       </refsect1>
 817       <refsect1>
 818         <title>Description</title>
 819         <para>This function returns the list of active database
 820           objects, i.e. all those database objects created by calls to
 821           <function>connect</function>, which have not been closed by
 822           calling <function>disconnect</function> on them.</para>
 823         <caution>
 824           <para>The consequences of modifying the list returned by
 825             <function>connected-databases</function> are
 826             undefined.</para>
 827         </caution>
 828       </refsect1>
 829       <refsect1>
 830         <title>Examples</title>
 831         <programlisting>
 832 (connected-databases)
 833 => NIL
 834 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
 835 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
 836 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
 837 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
 838 (connected-databases)
 839 => (#&lt;CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
 840     #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
 841 (disconnect)
 842 => T
 843 (connected-databases)
 844 => (#&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
 845 (disconnect)
 846 => T
 847 (connected-databases)
 848 => NIL
 849         </programlisting>
 850       </refsect1>
 851       <refsect1>
 852         <title>Side Effects</title>
 853         <para>None.</para>
 854       </refsect1>
 855       <refsect1>
 856         <title>Affected By</title>
 857         <para>
 858         <simplelist>
 859           <member><function>connect</function></member>
 860           <member><function>disconnect</function></member>
 861         </simplelist>
 862         </para>
 863       </refsect1>
 864       <refsect1>
 865         <title>Exceptional Situations</title>
 866         <para>None.</para>
 867       </refsect1>
 868       <refsect1>
 869         <title>See Also</title>
 870         <para>None.</para>
 871       </refsect1>
 872       <refsect1>
 873         <title>Notes</title>
 874         <para>None.</para>
 875       </refsect1>
 876     </refentry>
 877     <refentry id="default-database">
 878       <refnamediv>
 879         <refname>*DEFAULT-DATABASE*</refname>
 880         <refpurpose>The default database object to use</refpurpose>
 881         <refclass>Variable</refclass>
 882       </refnamediv>
 883       <refsect1>
 884         <title>Value Type</title>
 885         <para>Any object of type <type>database</type>, or nil to
 886           indicate no default database.</para>
 887       </refsect1>
 888       <refsect1>
 889         <title>Initial Value</title>
 890         <para><symbol>nil</symbol></para>
 891       </refsect1>
 892       <refsect1>
 893         <title>Description</title>
 894         <para>Any function or macro in
 895           &clsql; that operates on a
 896           database uses the value of this variable as the default
 897           value for it's <parameter>database</parameter>
 898           parameter.</para>
 899         <para>The value of this parameter is changed by calls to
 900           <function>connect</function>, which sets
 901           <symbol>*default-database*</symbol> to the database object
 902           it returns.  It is also changed by calls to
 903           <function>disconnect</function>, when the database object
 904           being disconnected is the same as the value of
 905           <symbol>*default-database*</symbol>.  In this case
 906           <function>disconnect</function> sets
 907           <symbol>*default-database*</symbol> to the first database
 908           that remains in the list of active databases as returned by
 909           <function>connected-databases</function>, or
 910           <symbol>nil</symbol> if no further active databases
 911           exist.</para>
 912         <para>The user may change <symbol>*default-database*</symbol>
 913           at any time to a valid value of his choice.</para>
 914         <caution>
 915           <para>If the value of <symbol>*default-database*</symbol> is
 916             <symbol>nil</symbol>, then all calls to
 917             &clsql; functions on databases
 918             must provide a suitable <parameter>database</parameter>
 919             parameter, or an error will be signalled.</para>
 920         </caution>
 921       </refsect1>
 922       <refsect1>
 923         <title>Examples</title>
 924         <programlisting>
 925 (connected-databases)
 926 => NIL
 927 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
 928 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
 929 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
 930 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
 931 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
 932 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
 933 *default-database*
 934 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
 935 (disconnect)
 936 => T
 937 *default-database*
 938 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
 939 (disconnect)
 940 => T
 941 *default-database*
 942 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
 943 (disconnect)
 944 => T
 945 *default-database*
 946 => NIL
 947 (connected-databases)
 948 => NIL
 949         </programlisting>
 950       </refsect1>
 951       <refsect1>
 952         <title>Affected By</title>
 953         <para>
 954         <simplelist>
 955           <member><link linkend="connect"><function>connect</function></link></member>
 956           <member><link linkend="disconnect"><function>disconnect</function></link></member>
 957         </simplelist>
 958         </para>
 959       </refsect1>
 960       <refsect1>
 961         <title>See Also</title>
 962         <para>
 963         <simplelist>
 964           <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
 965         </simplelist>
 966         </para>
 967       </refsect1>
 968       <refsect1>
 969         <title>Notes</title>
 970         <note>
 971           <para>This variable is intended to facilitate working with
 972             &clsql; in an interactive
 973             fashion at the top-level loop, and because of this,
 974             <function>connect</function> and
 975             <function>disconnect</function> provide some fairly
 976             complex  behaviour to keep
 977             <symbol>*default-database*</symbol> set to  useful values.
 978             Programmatic use of &clsql;
 979             should never depend on the value of
 980             <symbol>*default-database*</symbol> and should provide
 981             correct database objects via the
 982             <parameter>database</parameter> parameter to functions
 983             called.</para>
 984         </note>
 985       </refsect1>
 986     </refentry>
 987     <!-- Classes -->
 988     <refentry id="database">
 989       <refnamediv>
 990         <refname>DATABASE</refname>
 991         <refpurpose>The super-type of all
 992           &clsql; databases</refpurpose>
 993         <refclass>Class</refclass>
 994       </refnamediv>
 995       <refsect1>
 996         <title>Class Precedence List</title>
 997         <para>
 998         <simplelist type="inline">
 999           <member><type>database</type></member>
1000           <member><type>standard-object</type></member>
1001           <member><type>t</type></member>
1002         </simplelist>
1003         </para>
1004       </refsect1>
1005       <refsect1>
1006         <title>Description</title>
1007         <para>This class is the superclass of all
1008           &clsql; databases. The different
1009           database back-ends derive subclasses of this class to
1010           implement their databases.  No instances of this class are
1011           ever created by &clsql;.</para>
1012       </refsect1>
1013     </refentry>
1014     <refentry id="closed-database">
1015       <refnamediv>
1016         <refname>CLOSED-DATABASE</refname>
1017         <refpurpose>The class representing all closed
1018           &clsql; databases</refpurpose>
1019         <refclass>Class</refclass>
1020       </refnamediv>
1021       <refsect1>
1022         <title>Class Precedence List</title>
1023         <para>
1024         <simplelist type="inline">
1025           <member><type>closed-database</type></member>
1026           <member><type>standard-object</type></member>
1027           <member><type>t</type></member>
1028         </simplelist>
1029         </para>
1030       </refsect1>
1031       <refsect1>
1032         <title>Description</title>
1033         <para>&clsql; <type>database</type>
1034           instances are changed to this class via
1035           <function>change-class</function> after they are closed via
1036           <function>disconnect</function>.  All functions and generic
1037           functions that take database objects as arguments will
1038           signal errors of type
1039           <errortype>maisql-closed-error</errortype> when they are
1040           called on instances of <type>closed-database</type>, with
1041           the exception of <function>database-name</function>, which
1042           will continue to work as for instances of
1043           <type>database</type>.</para>
1044       </refsect1>
1045     </refentry>
1046     <!-- Functions -->
1047     <refentry id="database-name">
1048       <refnamediv>
1049         <refname>DATABASE-NAME</refname>
1050         <refpurpose>Get the name of a database object</refpurpose>
1051         <refclass>Generic Function</refclass>
1052       </refnamediv>
1053       <refsect1>
1054         <title>Syntax</title>
1055         <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
1056       </refsect1>
1057       <refsect1>
1058         <title>Arguments and Values</title>
1059         <variablelist>
1060           <varlistentry>
1061             <term><parameter>database</parameter></term>
1062             <listitem>
1063               <para>A database object, either of type
1064                 <type>database</type> or of type
1065                 <type>closed-database</type>.</para>
1066             </listitem>
1067           </varlistentry>
1068           <varlistentry>
1069             <term><returnvalue>name</returnvalue></term>
1070             <listitem>
1071               <para>A string describing the identity of the database
1072                 to which this database object is connected to.</para>
1073             </listitem>
1074           </varlistentry>
1075         </variablelist>
1076       </refsect1>
1077       <refsect1>
1078         <title>Description</title>
1079         <para>This function returns the database name of the given
1080           database.  The database name is a string which somehow
1081           describes the identity of the database to which this
1082           database object is or has been connected.  The database name
1083           of a database object is determined at
1084           <function>connect</function> time, when a call to
1085           <function>database-name-from-spec</function> derives the
1086           database name from the connection specification passed to
1087           <function>connect</function> in the
1088           <parameter>connection-spec</parameter> parameter.</para>
1089         <para>The database name is used via
1090           <function>find-database</function> in
1091           <function>connect</function> to determine whether database
1092           connections to the specified database exist already.</para>
1093         <para>Usually the database name string will include
1094           indications of the  host, database name, user, or port that
1095           where used during the connection attempt.  The only
1096           important thing is that this string shall  try to identify
1097           the database at the other end of the connection.  Connection
1098           specifications parts like passwords and credentials shall
1099           not be used as part of the database name.</para>
1100       </refsect1>
1101       <refsect1>
1102         <title>Examples</title>
1103         <programlisting>
1104 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1105 => "dent/newesim/dent"
1106 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1107 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1108 (database-name *default-database*)
1109 => "dent/newesim/dent"
1110
1111 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1112 => "/template1/dent"
1113 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1114 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1115 (database-name *default-database*)
1116 => "/template1/dent"
1117
1118 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1119 => "www.pmsf.de/template1/dent"
1120         </programlisting>
1121       </refsect1>
1122       <refsect1>
1123         <title>Side Effects</title>
1124         <para>None.</para>
1125       </refsect1>
1126       <refsect1>
1127         <title>Affected By</title>
1128         <para>
1129         <simplelist>
1130           <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1131         </simplelist>
1132         </para>
1133       </refsect1>
1134       <refsect1>
1135         <title>Exceptional Situations</title>
1136         <para>Will signal an error if the object passed as the
1137           <parameter>database</parameter> parameter is neither of type
1138           <type>database</type> nor of type
1139           <type>closed-database</type>.</para>
1140       </refsect1>
1141       <refsect1>
1142         <title>See Also</title>
1143         <para>
1144         <simplelist>
1145           <member><link
1146           linkend="connect"><function>connect</function></link></member>
1147           <member><link
1148           linkend="find-database"><function>find-database</function></link></member>
1149         </simplelist>
1150         </para>
1151       </refsect1>
1152       <refsect1>
1153         <title>Notes</title>
1154         <para>None.</para>
1155       </refsect1>
1156     </refentry>
1157     <refentry id="find-database">
1158       <refnamediv>
1159         <refname>FIND-DATABASE</refname>
1160         <refpurpose>Locate a database object through it's
1161           name.</refpurpose>
1162         <refclass>Function</refclass>
1163       </refnamediv>
1164       <refsect1>
1165         <title>Syntax</title>
1166         <synopsis><function>find-database</function> <replaceable>database</replaceable> &amp;optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1167       </refsect1>
1168       <refsect1>
1169         <title>Arguments and Values</title>
1170         <variablelist>
1171           <varlistentry>
1172             <term><parameter>database</parameter></term>
1173             <listitem>
1174               <para>A database object or a string, denoting a database
1175                 name.</para>
1176             </listitem>
1177           </varlistentry>
1178           <varlistentry>
1179             <term><parameter>errorp</parameter></term>
1180             <listitem>
1181               <para>A generalized boolean.  Defaults to
1182                 <symbol>t</symbol>.</para>
1183             </listitem>
1184           </varlistentry>
1185           <varlistentry>
1186             <term><returnvalue>result</returnvalue></term>
1187             <listitem>
1188               <para>Either a database object, or, if
1189                 <parameter>errorp</parameter> is <symbol>nil</symbol>,
1190                 possibly <symbol>nil</symbol>.</para>
1191             </listitem>
1192           </varlistentry>
1193         </variablelist>
1194       </refsect1>
1195       <refsect1>
1196         <title>Description</title>
1197         <para><function>find-database</function> locates an active
1198           database object given the specification in
1199           <parameter>database</parameter>.  If
1200           <parameter>database</parameter> is an object of type
1201           <type>database</type>, <function>find-database</function>
1202           returns this.  Otherwise it will search the active databases
1203           as indicated by the list returned by
1204           <function>connected-databases</function> for a database
1205           whose name (as returned by
1206           <function>database-name</function> is equal as per
1207           <function>string=</function> to the string passed as
1208           <parameter>database</parameter>.  If it succeeds, it returns
1209           the first database found.</para>
1210         <para>If it fails to find a matching database, it will signal
1211           an error of type <errortype>maisql-error</errortype> if
1212           <parameter>errorp</parameter> is true.  If
1213           <parameter>errorp</parameter> is <symbol>nil</symbol>, it
1214           will return <symbol>nil</symbol> instead.</para>
1215       </refsect1>
1216       <refsect1>
1217         <title>Examples</title>
1218         <programlisting>
1219 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1220 => "dent/newesim/dent"
1221 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1222 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1223 (database-name *default-database*)
1224 => "dent/newesim/dent"
1225
1226 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1227 => "/template1/dent"
1228 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1229 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1230 (database-name *default-database*)
1231 => "/template1/dent"
1232
1233 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1234 => "www.pmsf.de/template1/dent"
1235
1236 (find-database "dent/newesim/dent")
1237 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1238 (find-database "/template1/dent")
1239 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1240 (find-database "www.pmsf.de/template1/dent" nil)
1241 => NIL
1242 (find-database **)
1243 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1244         </programlisting>
1245       </refsect1>
1246       <refsect1>
1247         <title>Side Effects</title>
1248         <para>None.</para>
1249       </refsect1>
1250       <refsect1>
1251         <title>Affected By</title>
1252         <para>
1253         <simplelist>
1254           <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1255         </simplelist>
1256         </para>
1257       </refsect1>
1258       <refsect1>
1259         <title>Exceptional Situations</title>
1260         <para>Will signal an error of type
1261         <errortype>maisql-error</errortype> if no matching database
1262           can be found, and <parameter>errorp</parameter> is true.
1263           Will signal an error if the value of
1264           <parameter>database</parameter> is neither an object of type
1265           <type>database</type> nor a string.</para>
1266       </refsect1>
1267       <refsect1>
1268         <title>See Also</title>
1269         <para>
1270         <simplelist>
1271           <member><link
1272           linkend="database-name"><function>database-name</function></link></member>
1273           <member><link
1274           linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1275         </simplelist>
1276         </para>
1277       </refsect1>
1278       <refsect1>
1279         <title>Notes</title>
1280         <para>None.</para>
1281       </refsect1>
1282     </refentry>
1283     <refentry id="connect">
1284       <refnamediv>
1285         <refname>CONNECT</refname>
1286         <refpurpose>create a connection to a database</refpurpose>
1287         <refclass>Function</refclass>
1288       </refnamediv>
1289       <refsect1>
1290         <title>Syntax</title>
1291         <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> => <returnvalue>database</returnvalue></synopsis>
1292       </refsect1>
1293       <refsect1>
1294         <title>Arguments and Values</title>
1295         <variablelist>
1296           <varlistentry>
1297             <term><parameter>connection-spec</parameter></term>
1298             <listitem>
1299               <para>A connection specification</para>
1300             </listitem>
1301           </varlistentry>
1302           <varlistentry>
1303             <term><parameter>if-exists</parameter></term>
1304             <listitem>
1305               <para>This indicates the action to take if a connection
1306                 to the same database exists already.  See below for the
1307                 legal values and actions.  It defaults to the value of
1308                 <symbol>*connect-if-exists*</symbol>.</para>
1309             </listitem>
1310           </varlistentry>
1311           <varlistentry>
1312             <term><parameter>database-type</parameter></term>
1313             <listitem>
1314               <para>A database type specifier, i.e. a keyword.
1315                 This defaults to the value of
1316                 <symbol>*default-database-type*</symbol></para>
1317             </listitem>
1318           </varlistentry>
1319           <varlistentry>
1320             <term><returnvalue>database</returnvalue></term>
1321             <listitem>
1322               <para>The database object representing the connection.</para>
1323             </listitem>
1324           </varlistentry>
1325         </variablelist>
1326       </refsect1>
1327       <refsect1>
1328         <title>Description</title>
1329         <para>This function takes a connection specification and
1330           a database type and creates a connection to the database
1331           specified by those.  The type and structure of the
1332           connection specification depend on the database type.</para>
1333         <para>The parameter <parameter>if-exists</parameter> specifies
1334           what to do if a connection to the database specified exists
1335           already, which is checked by calling
1336           <function>find-database</function> on the database name
1337           returned by <function>database-name-from-spec</function>
1338           when called with the <parameter>connection-spec</parameter>
1339           and <parameter>database-type</parameter> parameters. The
1340           possible values of <parameter>if-exists</parameter> are:
1341           <variablelist>
1342             <varlistentry>
1343               <term><symbol>:new</symbol></term>
1344               <listitem>
1345                 <para>Go ahead and create a new connection.</para>
1346               </listitem>
1347             </varlistentry>
1348             <varlistentry>
1349               <term><symbol>:warn-new</symbol></term>
1350               <listitem>
1351                 <para>This is just like <symbol>:new</symbol>, but
1352                   also signals a warning of type
1353                   <errortype>maisql-exists-warning</errortype>,
1354                   indicating the old and newly created
1355                   databases.</para>
1356               </listitem>
1357             </varlistentry>
1358             <varlistentry>
1359               <term><symbol>:error</symbol></term>
1360               <listitem>
1361                 <para>This will cause <function>connect</function> to
1362                   signal a correctable error of type
1363                   <errortype>maisql-exists-error</errortype>.  The
1364                   user may choose to proceed, either by indicating
1365                   that a new connection shall be created, via the
1366                   restart <symbol>create-new</symbol>, or by
1367                   indicating that the existing connection shall be
1368                   used, via the restart
1369                   <symbol>use-old</symbol>.</para>
1370               </listitem>
1371             </varlistentry>
1372             <varlistentry>
1373               <term><symbol>:old</symbol></term>
1374               <listitem>
1375                 <para>This will cause <function>connect</function> to
1376                   use an old connection if one exists.</para>
1377               </listitem>
1378             </varlistentry>
1379             <varlistentry>
1380               <term><symbol>:warn-old</symbol></term>
1381               <listitem>
1382                 <para>This is just like <symbol>:old</symbol>, but
1383                   also signals a warning of type
1384                   <errortype>maisql-exists-warning</errortype>,
1385                   indicating the old database used, via the slots
1386                   <symbol>old-db</symbol> and
1387                   <symbol>new-db</symbol></para>
1388               </listitem>
1389             </varlistentry>
1390           </variablelist>
1391         </para>
1392         <para>The database name of the returned database object will
1393           be the same under <function>string=</function> as that which
1394           would be returned by a call to
1395           <function>database-name-from-spec</function> with the given
1396           <parameter>connection-spec</parameter> and
1397           <parameter>database-type</parameter> parameters.</para>
1398       </refsect1>
1399       <refsect1>
1400         <title>Examples</title>
1401         <programlisting>
1402 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1403 => "dent/newesim/dent"
1404 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1405 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
1406 (database-name *)
1407 => "dent/newesim/dent"
1408
1409 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1410 >> In call to CONNECT:
1411 >>   There is an existing connection #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
1412 >>
1413 >> Restarts:
1414 >>   0: [CREATE-NEW] Create a new connection.
1415 >>   1: [USE-OLD   ] Use the existing connection.
1416 >>   2: [ABORT     ] Return to Top-Level.
1417 >>
1418 >> Debug  (type H for help)
1419 >>
1420 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
1421 >> Source:
1422 >> ; File: /prj/CLSQL/sql/sql.cl
1423 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
1424 >>               (CREATE-NEW NIL :REPORT "Create a new connection."
1425 >>                (SETQ RESULT #))
1426 >>               (USE-OLD NIL :REPORT "Use the existing connection."
1427 >>                (SETQ RESULT OLD-DB)))
1428 >> 0] 0
1429 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
1430         </programlisting>
1431       </refsect1>
1432       <refsect1>
1433         <title>Side Effects</title>
1434         <para>A database connection is established, and the resultant
1435           database object is registered, so as to appear in the list
1436           returned by <function>connected-databases</function>.</para>
1437       </refsect1>
1438       <refsect1>
1439         <title>Affected by</title>
1440         <para>
1441         <simplelist>
1442           <member><symbol>*default-database-type*</symbol></member>
1443           <member><symbol>*connect-if-exists*</symbol></member>
1444         </simplelist>
1445         </para>
1446       </refsect1>
1447       <refsect1>
1448         <title>Exceptional Situations</title>
1449         <para>If the connection specification is not syntactically or
1450           semantically correct for the given database type, an error
1451           of type <errortype>maisql-invalid-spec-error</errortype> is
1452           signalled.  If during the connection attempt an error is
1453           detected (e.g. because of permission problems, network
1454           trouble  or any other cause), an error of type
1455           <errortype>maisql-connect-error</errortype> is
1456           signalled.</para>
1457         <para>If a connection to the database specified by
1458           <parameter>connection-spec</parameter> exists already,
1459           conditions are signalled according to the
1460           <parameter>if-exists</parameter> parameter, as described
1461           above.</para>
1462       </refsect1>
1463       <refsect1>
1464         <title>See Also</title>
1465         <para>
1466         <simplelist>
1467           <member><function>connected-databases</function></member>
1468           <member><link linkend="disconnect"><function>disconnect</function></link></member>
1469         </simplelist>
1470         </para>
1471       </refsect1>
1472       <refsect1>
1473         <title>Notes</title>
1474         <para>None.</para>
1475       </refsect1>
1476     </refentry>
1477     <refentry id="disconnect">
1478       <refnamediv>
1479         <refname>DISCONNECT</refname>
1480         <refpurpose>close a database connection</refpurpose>
1481         <refclass>Function</refclass>
1482       </refnamediv>
1483       <refsect1>
1484         <title>Syntax</title>
1485         <synopsis><function>disconnect</function> &amp;key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1486       </refsect1>
1487       <refsect1>
1488         <title>Arguments and Values</title>
1489         <variablelist>
1490           <varlistentry>
1491             <term><parameter>database</parameter></term>
1492             <listitem>
1493               <para>The database to disconnect, which defaults to the
1494                 database indicated by
1495                 <symbol>*default-database*</symbol>.</para>
1496             </listitem>
1497           </varlistentry>
1498         </variablelist>
1499       </refsect1>
1500       <refsect1>
1501         <title>Description</title>
1502         <para>This function takes a <type>database</type> object as
1503           returned by <function>connect</function>, and closes the
1504           connection.  The class of the object passed is changed to
1505           <type>closed-database</type> after the disconnection
1506           succeeds,  thereby preventing further use of the object as
1507           an argument to &clsql; functions,
1508           with the exception of <function>database-name</function>.
1509           If the user does pass a  closed database object to any other
1510           &clsql; function, an error of type
1511           <errortype>maisql-closed-error</errortype> is
1512           signalled.</para>
1513       </refsect1>
1514       <refsect1>
1515         <title>Examples</title>
1516         <programlisting>
1517 (disconnect :database (find-database "dent/newesim/dent"))
1518 => T
1519         </programlisting>
1520       </refsect1>
1521       <refsect1>
1522         <title>Side Effects</title>
1523         <para>The database connection is closed, and the database
1524           object is removed from the list of connected databases as
1525           returned by <function>connected-databases</function>.</para>
1526         <para>The class of the database object is changed to
1527           <type>closed-database</type>.</para>
1528         <para>If the database object passed is the same under
1529           <function>eq</function> as the value of
1530           <symbol>*default-database*</symbol>, then
1531           <symbol>*default-database*</symbol> is set to the first
1532           remaining database from
1533           <function>connected-databases</function> or to nil if no
1534           further active database exists.</para>
1535       </refsect1>
1536       <refsect1>
1537         <title>Affected by</title>
1538         <para>
1539         <simplelist>
1540           <member><symbol>*default-database*</symbol></member>
1541         </simplelist>
1542         </para>
1543       </refsect1>
1544       <refsect1>
1545         <title>Exceptional Situations</title>
1546         <para>If during the disconnection attempt an error is
1547           detected (e.g. because of network trouble or any other
1548           cause), an error of type <errortype>maisql-error</errortype>
1549           might be signalled.</para>
1550       </refsect1>
1551       <refsect1>
1552         <title>See Also</title>
1553         <para>
1554         <simplelist>
1555           <member><link linkend="connect"><function>connect</function></link></member>
1556           <member><link linkend="connect"><function>closed-database</function></link></member>
1557         </simplelist>
1558         </para>
1559       </refsect1>
1560       <refsect1>
1561         <title>Notes</title>
1562         <para>None.</para>
1563       </refsect1>
1564     </refentry>
1565     <refentry id="database-name-from-spec">
1566       <refnamediv>
1567         <refname>DATABASE-NAME-FROM-SPEC</refname>
1568         <refpurpose>Return the database name string corresponding to
1569           the given connection specification.</refpurpose>
1570         <refclass>Generic Function</refclass>
1571       </refnamediv>
1572       <refsect1>
1573         <title>Syntax</title>
1574         <synopsis>
1575           <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
1576       </refsect1>
1577       <refsect1>
1578         <title>Arguments and Values</title>
1579         <variablelist>
1580           <varlistentry>
1581             <term><parameter>connection-spec</parameter></term>
1582             <listitem>
1583               <para>A connection specification, whose structure and
1584                 interpretation are dependent on the
1585                 <parameter>database-type</parameter>.</para>
1586             </listitem>
1587           </varlistentry>
1588           <varlistentry>
1589             <term><parameter>database-type</parameter></term>
1590             <listitem>
1591               <para>A database type specifier, i.e. a keyword.</para>
1592             </listitem>
1593           </varlistentry>
1594           <varlistentry>
1595             <term><returnvalue>name</returnvalue></term>
1596             <listitem>
1597               <para>A string denoting a database name.</para>
1598             </listitem>
1599           </varlistentry>
1600         </variablelist>
1601       </refsect1>
1602       <refsect1>
1603         <title>Description</title>
1604         <para>This generic function takes a connection specification
1605           and a database type and returns the database name of the
1606           database object that would be created had
1607           <function>connect</function> been called with the given
1608           connection specification and database types.</para>
1609         <para>This function is useful in determining a database name
1610           from the connection specification, since the way the
1611           connection specification is converted into a database name
1612           is dependent on the database type.</para>
1613       </refsect1>
1614       <refsect1>
1615         <title>Examples</title>
1616         <programlisting>
1617 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1618 => "dent/newesim/dent"
1619 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1620 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1621 (database-name *default-database*)
1622 => "dent/newesim/dent"
1623
1624 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1625 => "/template1/dent"
1626 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1627 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1628 (database-name *default-database*)
1629 => "/template1/dent"
1630
1631 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1632 => "www.pmsf.de/template1/dent"
1633
1634 (find-database "dent/newesim/dent")
1635 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1636 (find-database "/template1/dent")
1637 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1638 (find-database "www.pmsf.de/template1/dent" nil)
1639 => NIL
1640 (find-database **)
1641 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1642         </programlisting>
1643       </refsect1>
1644       <refsect1>
1645         <title>Side Effects</title>
1646         <para>None.</para>
1647       </refsect1>
1648       <refsect1>
1649         <title>Affected by</title>
1650         <para>None.</para>
1651       </refsect1>
1652       <refsect1>
1653         <title>Exceptional Situations</title>
1654         <para>If the value of <parameter>connection-spec</parameter>
1655           is not a valid connection specification for the given
1656           database type, an error of type
1657           <errortype>maisql-invalid-spec-error</errortype> might be
1658           signalled.</para>
1659       </refsect1>
1660       <refsect1>
1661         <title>See Also</title>
1662         <para>
1663         <simplelist>
1664           <member><link linkend="connect"><function>connect</function></link></member>
1665         </simplelist>
1666         </para>
1667       </refsect1>
1668       <refsect1>
1669         <title>Notes</title>
1670         <para>None.</para>
1671       </refsect1>
1672     </refentry>
1673     <!-- Querying Operations -->
1674     <refentry id="execute-command">
1675       <refnamediv>
1676         <refname>EXECUTE-COMMAND</refname>
1677         <refpurpose>Execute an SQL command which returns no
1678           values.</refpurpose>
1679         <refclass>Function</refclass>
1680       </refnamediv>
1681       <refsect1>
1682         <title>Syntax</title>
1683         <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1684       </refsect1>
1685       <refsect1>
1686         <title>Arguments and Values</title>
1687         <variablelist>
1688           <varlistentry>
1689             <term><parameter>sql-expression</parameter></term>
1690             <listitem>
1691               <para>An <glossterm linkend="gloss-sql-expression">sql
1692                   expression</glossterm> that represents an SQL
1693                 statement which will return no values.</para>
1694             </listitem>
1695           </varlistentry>
1696           <varlistentry>
1697             <term><parameter>database</parameter></term>
1698             <listitem>
1699               <para>A
1700                 <glossterm linkend="gloss-database-object">database
1701                   object</glossterm>. This will default to the value
1702                 of <symbol>*default-database*</symbol>.</para>
1703             </listitem>
1704           </varlistentry>
1705         </variablelist>
1706       </refsect1>
1707       <refsect1>
1708         <title>Description</title>
1709         <para>This will execute the command given by
1710           <parameter>sql-expression</parameter> in the
1711           <parameter>database</parameter> specified.  If the execution
1712           succeeds it will return <symbol>t</symbol>, otherwise an
1713           error of type <errortype>maisql-sql-error</errortype> will
1714           be signalled.</para>
1715       </refsect1>
1716       <refsect1>
1717         <title>Examples</title>
1718         <programlisting>
1719 (execute-command "create table eventlog (time char(30),event char(70))")
1720 => T
1721
1722 (execute-command "create table eventlog (time char(30),event char(70))")
1723 >>
1724 >> While accessing database #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
1725 >>   with expression "create table eventlog (time char(30),event char(70))":
1726 >>   Error NIL: ERROR:  amcreate: eventlog relation already exists
1727 >>   has occurred.
1728 >>
1729 >> Restarts:
1730 >>   0: [ABORT] Return to Top-Level.
1731 >>
1732 >> Debug  (type H for help)
1733 >>
1734 >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
1735 >>  #&lt;unused-arg>
1736 >>  #&lt;unused-arg>
1737 >>  #&lt;unavailable-arg>
1738 >>  #&lt;unavailable-arg>)
1739 >> Source: (ERROR 'CLSQL-SQL-ERROR :DATABASE DATABASE :EXPRESSION ...)
1740 >> 0] 0
1741
1742 (execute-command "drop table eventlog")
1743 => T
1744         </programlisting>
1745       </refsect1>
1746       <refsect1>
1747         <title>Side Effects</title>
1748         <para>Whatever effects the execution of the SQL statement has
1749           on the underlying database, if any.</para>
1750       </refsect1>
1751       <refsect1>
1752         <title>Affected by</title>
1753         <para>None.</para>
1754       </refsect1>
1755       <refsect1>
1756         <title>Exceptional Situations</title>
1757         <para>If the execution of  the SQL statement leads to any
1758           errors, an error of type
1759           <errortype>maisql-sql-error</errortype> is signalled.</para>
1760       </refsect1>
1761       <refsect1>
1762         <title>See Also</title>
1763         <para>
1764         <simplelist>
1765           <member><link linkend="query"><function>query</function></link></member>
1766         </simplelist>
1767         </para>
1768       </refsect1>
1769       <refsect1>
1770         <title>Notes</title>
1771         <para>None.</para>
1772       </refsect1>
1773     </refentry>
1774     <refentry id="query">
1775       <refnamediv>
1776         <refname>QUERY</refname>
1777         <refpurpose>Execute an SQL query and return the tuples as a
1778           list</refpurpose>
1779         <refclass>Function</refclass>
1780       </refnamediv>
1781       <refsect1>
1782         <title>Syntax</title>
1783         <synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1784       </refsect1>
1785       <refsect1>
1786         <title>Arguments and Values</title>
1787         <variablelist>
1788           <varlistentry>
1789             <term><parameter>query-expression</parameter></term>
1790             <listitem>
1791               <para>An <glossterm linkend="gloss-sql-expression">sql
1792                   expression</glossterm> that represents an SQL
1793                 query which is expected to return a (possibly empty)
1794                 result set.</para>
1795             </listitem>
1796           </varlistentry>
1797           <varlistentry>
1798             <term><parameter>database</parameter></term>
1799             <listitem>
1800               <para>A
1801                 <glossterm linkend="gloss-database-object">database
1802                   object</glossterm>. This will default to the value
1803                 of <symbol>*default-database*</symbol>.</para>
1804             </listitem>
1805           </varlistentry>
1806           <varlistentry>
1807             <term><returnvalue>result</returnvalue></term>
1808             <listitem>
1809               <para>A list representing the result set obtained.  For
1810                 each tuple in the result set, there is an element in
1811                 this list, which is itself a list of all the attribute
1812                 values in the tuple.</para>
1813             </listitem>
1814           </varlistentry>
1815         </variablelist>
1816       </refsect1>
1817       <refsect1>
1818         <title>Description</title>
1819         <para>This will execute the query given by
1820           <parameter>query-expression</parameter> in the
1821           <parameter>database</parameter> specified.  If the execution
1822           succeeds it will return the result set returned by the
1823           database, otherwise an error of type
1824           <errortype>maisql-sql-error</errortype> will
1825           be signalled.</para>
1826       </refsect1>
1827       <refsect1>
1828         <title>Examples</title>
1829         <programlisting>
1830 (execute-command "create table simple (name char(50), salary numeric(10,2))")
1831 => T
1832 (execute-command "insert into simple values ('Mai, Pierre',10000)")
1833 => T
1834 (execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
1835 => T
1836 (query "select * from simple")
1837 => (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
1838 (query "select salary from simple")
1839 => (("10000.00") ("8000.50"))
1840 (query "select salary from simple where salary > 10000")
1841 => NIL
1842 (query "select salary,name from simple where salary > 10000")
1843 => NIL
1844 (query "select salary,name from simple where salary > 9000")
1845 => (("10000.00" "Mai, Pierre"))
1846 (query "select salary,name from simple where salary > 8000")
1847 => (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
1848
1849 ;; MySQL-specific:
1850 (query "show tables")
1851 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
1852         </programlisting>
1853       </refsect1>
1854       <refsect1>
1855         <title>Side Effects</title>
1856         <para>Whatever effects the execution of the SQL query has
1857           on the underlying database, if any.</para>
1858       </refsect1>
1859       <refsect1>
1860         <title>Affected by</title>
1861         <para>None.</para>
1862       </refsect1>
1863       <refsect1>
1864         <title>Exceptional Situations</title>
1865         <para>If the execution of  the SQL query leads to any
1866           errors, an error of type
1867           <errortype>maisql-sql-error</errortype> is signalled.</para>
1868       </refsect1>
1869       <refsect1>
1870         <title>See Also</title>
1871         <para>
1872         <simplelist>
1873           <member><link linkend="execute-command"><function>execute-command</function></link></member>
1874         </simplelist>
1875         </para>
1876       </refsect1>
1877       <refsect1>
1878         <title>Notes</title>
1879         <para>None.</para>
1880       </refsect1>
1881     </refentry>
1882     <!-- Iteration -->
1883     <refentry id="map-query">
1884       <refnamediv>
1885         <refname>MAP-QUERY</refname>
1886         <refpurpose>Map a function over all the tuples from a
1887           query</refpurpose>
1888         <refclass>Function</refclass>
1889       </refnamediv>
1890       <refsect1>
1891         <title>Syntax</title>
1892         <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1893       </refsect1>
1894       <refsect1>
1895         <title>Arguments and Values</title>
1896         <variablelist>
1897           <varlistentry>
1898             <term><parameter>output-type-spec</parameter></term>
1899             <listitem>
1900               <para>A sequence type specifier or <symbol>nil</symbol>.</para>
1901             </listitem>
1902           </varlistentry>
1903           <varlistentry>
1904             <term><parameter>function</parameter></term>
1905             <listitem>
1906               <para>A function designator.
1907                 <parameter>function</parameter> must take as many
1908                 arguments as are attributes in the result set returned
1909                 by executing the SQL
1910                 <parameter>query-expression</parameter>.</para>
1911             </listitem>
1912           </varlistentry>
1913           <varlistentry>
1914             <term><parameter>query-expression</parameter></term>
1915             <listitem>
1916               <para>An <glossterm linkend="gloss-sql-expression">sql
1917                   expression</glossterm> that represents an SQL
1918                 query which is expected to return a (possibly empty)
1919                 result set, where each tuple has as many attributes as
1920                 <parameter>function</parameter> takes arguments.</para>
1921             </listitem>
1922           </varlistentry>
1923           <varlistentry>
1924             <term><parameter>database</parameter></term>
1925             <listitem>
1926               <para>A
1927                 <glossterm linkend="gloss-database-object">database
1928                   object</glossterm>. This will default to the value
1929                 of <symbol>*default-database*</symbol>.</para>
1930             </listitem>
1931           </varlistentry>
1932           <varlistentry>
1933             <term><returnvalue>result</returnvalue></term>
1934             <listitem>
1935               <para>If <parameter>output-type-spec</parameter> is a
1936                 type specifier other than <symbol>nil</symbol>, then a
1937                 sequence of the type it denotes.  Otherwise
1938                 <symbol>nil</symbol> is returned.</para>
1939             </listitem>
1940           </varlistentry>
1941         </variablelist>
1942       </refsect1>
1943       <refsect1>
1944         <title>Description</title>
1945         <para>Applies <parameter>function</parameter> to the
1946           attributes of successive tuples in the result set returned
1947           by executing the SQL
1948           <parameter>query-expression</parameter>.  If the
1949           <parameter>output-type-spec</parameter> is
1950           <symbol>nil</symbol>, then the result of each application
1951           of <parameter>function</parameter> is discarded, and
1952           <function>map-query</function> returns
1953           <symbol>nil</symbol>.  Otherwise the result of each
1954           successive application of <parameter>function</parameter> is
1955           collected in a sequence of type
1956           <parameter>output-type-spec</parameter>, where the jths
1957           element is the result of applying
1958           <parameter>function</parameter> to the attributes of the
1959           jths tuple in the result set.  The collected sequence is the
1960           result of the call to <function>map-query</function>.
1961         </para>
1962         <para>If the <parameter>output-type-spec</parameter> is a
1963           subtype of <type>list</type>, the result will be a
1964           <type>list</type>.</para>
1965         <para>If the <parameter>result-type</parameter> is a subtype
1966           of <type>vector</type>, then if the implementation can
1967           determine the element type specified for the
1968           <parameter>result-type</parameter>, the element type of the
1969           resulting array is the result of
1970           <emphasis>upgrading</emphasis> that element type; or, if the
1971           implementation can determine that the element type is
1972           unspecified (or <symbol>*</symbol>), the element type of the
1973           resulting array is <type>t</type>; otherwise, an error is
1974           signaled.</para>
1975       </refsect1>
1976       <refsect1>
1977         <title>Examples</title>
1978         <programlisting>
1979 (map-query 'list #'(lambda (salary name)
1980                      (declare (ignorable name))
1981                      (read-from-string salary))
1982            "select salary,name from simple where salary > 8000")
1983 => (10000.0 8000.5)
1984
1985 (map-query '(vector double-float)
1986            #'(lambda (salary name)
1987                (declare (ignorable name))
1988                (coerce (read-from-string salary) 'double-float))
1989            "select salary,name from simple where salary > 8000")
1990 => #(10000.0d0 8000.5d0)
1991 (type-of *)
1992 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
1993
1994 (let (list)
1995   (values (map-query nil #'(lambda (salary name)
1996                              (push (cons name (read-from-string salary)) list))
1997                      "select salary,name from simple where salary > 8000")
1998           list))
1999 => NIL
2000 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
2001         </programlisting>
2002       </refsect1>
2003       <refsect1>
2004         <title>Side Effects</title>
2005         <para>Whatever effects the execution of the SQL query has
2006           on the underlying database, if any.</para>
2007       </refsect1>
2008       <refsect1>
2009         <title>Affected by</title>
2010         <para>None.</para>
2011       </refsect1>
2012       <refsect1>
2013         <title>Exceptional Situations</title>
2014         <para>If the execution of  the SQL query leads to any
2015           errors, an error of type
2016           <errortype>maisql-sql-error</errortype> is signalled.</para>
2017         <para>An error of type <errortype>type-error</errortype> must
2018           be signaled if the <parameter>output-type-spec</parameter> is
2019           not a recognizable subtype of <type>list</type>, not a
2020           recognizable subtype of <type>vector</type>, and not
2021           <symbol>nil</symbol>.</para>
2022         <para>An error of type <errortype>type-error</errortype>
2023           should be signaled if
2024           <parameter>output-type-spec</parameter> specifies the number
2025           of elements and the size of the result set is different from
2026           that number.</para>
2027       </refsect1>
2028       <refsect1>
2029         <title>See Also</title>
2030         <para>
2031         <simplelist>
2032           <member><link linkend="query"><function>query</function></link></member>
2033           <member><link linkend="do-query"><function>do-query</function></link></member>
2034         </simplelist>
2035         </para>
2036       </refsect1>
2037       <refsect1>
2038         <title>Notes</title>
2039         <para>None.</para>
2040       </refsect1>
2041     </refentry>
2042     <refentry id="do-query">
2043       <refnamediv>
2044         <refname>DO-QUERY</refname>
2045         <refpurpose>Iterate over all the tuples of a
2046         query</refpurpose>
2047         <refclass>Macro</refclass>
2048       </refnamediv>
2049       <refsect1>
2050         <title>Syntax</title>
2051         <synopsis><function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable>) &amp;body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
2052       </refsect1>
2053       <refsect1>
2054         <title>Arguments and Values</title>
2055         <variablelist>
2056           <varlistentry>
2057             <term><parameter>args</parameter></term>
2058             <listitem>
2059               <para>A list of variable names.</para>
2060             </listitem>
2061           </varlistentry>
2062           <varlistentry>
2063             <term><parameter>query-expression</parameter></term>
2064             <listitem>
2065               <para>An <glossterm linkend="gloss-sql-expression">sql
2066                   expression</glossterm> that represents an SQL
2067                 query which is expected to return a (possibly empty)
2068                 result set, where each tuple has as many attributes as
2069                 <parameter>function</parameter> takes arguments.</para>
2070             </listitem>
2071           </varlistentry>
2072           <varlistentry>
2073             <term><parameter>database</parameter></term>
2074             <listitem>
2075               <para>A
2076                 <glossterm linkend="gloss-database-object">database
2077                   object</glossterm>. This will default to
2078                 <symbol>*default-database*</symbol>.</para>
2079             </listitem>
2080           </varlistentry>
2081           <varlistentry>
2082             <term><parameter>body</parameter></term>
2083             <listitem>
2084               <para>A body of Lisp code, like in a
2085                 <function>destructuring-bind</function> form.</para>
2086             </listitem>
2087           </varlistentry>
2088         </variablelist>
2089       </refsect1>
2090       <refsect1>
2091         <title>Description</title>
2092         <para>Executes the <parameter>body</parameter> of code
2093           repeatedly with the variable names in
2094           <parameter>args</parameter> bound to the attributes of each
2095           tuple in the result set returned by executing the SQL
2096           <parameter>query-expression</parameter> on the
2097           <parameter>database</parameter> specified.</para>
2098         <para>The body of code is executed in a block named
2099           <symbol>nil</symbol> which may be returned from prematurely
2100           via <function>return</function> or
2101           <function>return-from</function>.  In this case the result
2102           of evaluating the <function>do-query</function> form will be
2103           the one supplied to <function>return</function> or
2104           <function>return-from</function>.  Otherwise the result will
2105           be <symbol>nil</symbol>.</para>
2106         <para>The body of code appears also is if wrapped in a
2107           <function>destructuring-bind</function> form, thus allowing
2108           declarations at the start of the body, especially those
2109           pertaining to the bindings of the variables named in
2110           <parameter>args</parameter>.</para>
2111       </refsect1>
2112       <refsect1>
2113         <title>Examples</title>
2114         <programlisting>
2115 (do-query ((salary name) "select salary,name from simple")
2116   (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
2117 >> Mai, Pierre                    gets $10000.00
2118 >> Hacker, Random J.              gets $08000.50
2119 => NIL
2120
2121 (do-query ((salary name) "select salary,name from simple")
2122   (return (cons salary name)))
2123 => ("10000.00" . "Mai, Pierre")
2124         </programlisting>
2125       </refsect1>
2126       <refsect1>
2127         <title>Side Effects</title>
2128         <para>Whatever effects the execution of the SQL query has
2129           on the underlying database, if any.</para>
2130       </refsect1>
2131       <refsect1>
2132         <title>Affected by</title>
2133         <para>None.</para>
2134       </refsect1>
2135       <refsect1>
2136         <title>Exceptional Situations</title>
2137         <para>If the execution of  the SQL query leads to any
2138           errors, an error of type
2139           <errortype>maisql-sql-error</errortype> is signalled.</para>
2140         <para>If the number of variable names in
2141           <parameter>args</parameter> and the number of attributes in
2142           the tuples in the result set don't match up, an error is
2143           signalled.</para>
2144       </refsect1>
2145       <refsect1>
2146         <title>See Also</title>
2147         <para>
2148         <simplelist>
2149           <member><link linkend="query"><function>query</function></link></member>
2150           <member><link linkend="map-query"><function>map-query</function></link></member>
2151         </simplelist>
2152         </para>
2153       </refsect1>
2154       <refsect1>
2155         <title>Notes</title>
2156         <para>None.</para>
2157       </refsect1>
2158     </refentry>
2159     <refentry id="loop-tuples">
2160       <refnamediv>
2161         <refname>LOOP-FOR-AS-TUPLES</refname>
2162         <refpurpose>Iterate over all the tuples of a
2163         query via a loop clause</refpurpose>
2164         <refclass>Loop Clause</refclass>
2165       </refnamediv>
2166       <refsect1>
2167         <title>Syntax</title>
2168         <synopsis><replaceable>var</replaceable> [<replaceable>type-spec</replaceable>] being {each | the} {record | records | tuple | tuples} {in | of} <replaceable>query</replaceable> [from <replaceable>database</replaceable>]</synopsis>
2169       </refsect1>
2170       <refsect1>
2171         <title>Arguments and Values</title>
2172         <variablelist>
2173           <varlistentry>
2174             <term><parameter>var</parameter></term>
2175             <listitem>
2176               <para>A <literal>d-var-spec</literal>, as defined in the
2177                 grammar for <function>loop</function>-clauses in the
2178                 ANSI Standard for Common Lisp.  This allows for the
2179                 usual loop-style destructuring.</para>
2180             </listitem>
2181           </varlistentry>
2182           <varlistentry>
2183             <term><parameter>type-spec</parameter></term>
2184             <listitem>
2185               <para>An optional <literal>type-spec</literal> either
2186                 simple or destructured, as defined in the grammar for
2187                 <function>loop</function>-clauses in the ANSI Standard
2188                 for Common Lisp.</para>
2189             </listitem>
2190           </varlistentry>
2191           <varlistentry>
2192             <term><parameter>query</parameter></term>
2193             <listitem>
2194               <para>An <glossterm linkend="gloss-sql-expression">sql
2195                   expression</glossterm> that represents an SQL
2196                 query which is expected to return a (possibly empty)
2197                 result set, where each tuple has as many attributes as
2198                 <parameter>function</parameter> takes arguments.</para>
2199             </listitem>
2200           </varlistentry>
2201           <varlistentry>
2202             <term><parameter>database</parameter></term>
2203             <listitem>
2204               <para>An optional
2205                 <glossterm linkend="gloss-database-object">database
2206                   object</glossterm>. This will default to the value
2207                 of <symbol>*default-database*</symbol>.</para>
2208             </listitem>
2209           </varlistentry>
2210         </variablelist>
2211       </refsect1>
2212       <refsect1>
2213         <title>Description</title>
2214         <para>This clause is an iteration driver for
2215         <function>loop</function>, that binds the given variable
2216           (possibly destructured) to the consecutive tuples (which are
2217           represented as lists of attribute values) in the result set
2218           returned by executing the SQL <parameter>query</parameter>
2219           expression on the <parameter>database</parameter>
2220           specified.</para>
2221       </refsect1>
2222       <refsect1>
2223         <title>Examples</title>
2224         <programlisting>
2225 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
2226   "My database"
2227 => *MY-DB*
2228 (loop with time-graph = (make-hash-table :test #'equal)
2229       with event-graph = (make-hash-table :test #'equal)
2230       for (time event) being the tuples of "select time,event from log"
2231       from *my-db*
2232       do
2233       (incf (gethash time time-graph 0))
2234       (incf (gethash event event-graph 0))
2235       finally
2236       (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
2237         (format t "~&amp;Time-Graph:~%===========~%")
2238         (maphash #'show-graph time-graph)
2239         (format t "~&amp;~%Event-Graph:~%============~%")
2240         (maphash #'show-graph event-graph))
2241       (return (values time-graph event-graph)))
2242 >> Time-Graph:
2243 >> ===========
2244 >> D                                        => 53000
2245 >> X                                        =>     3
2246 >> test-me                                  =>  3000
2247 >>
2248 >> Event-Graph:
2249 >> ============
2250 >> CLOS Benchmark entry.                    =>  9000
2251 >> Demo Text...                             =>     3
2252 >> doit-text                                =>  3000
2253 >> C    Benchmark entry.                    => 12000
2254 >> CLOS Benchmark entry                     => 32000
2255 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
2256 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
2257         </programlisting>
2258       </refsect1>
2259       <refsect1>
2260         <title>Side Effects</title>
2261         <para>Whatever effects the execution of the SQL query has
2262           on the underlying database, if any.</para>
2263       </refsect1>
2264       <refsect1>
2265         <title>Affected by</title>
2266         <para>None.</para>
2267       </refsect1>
2268       <refsect1>
2269         <title>Exceptional Situations</title>
2270         <para>If the execution of  the SQL query leads to any
2271           errors, an error of type
2272           <errortype>maisql-sql-error</errortype> is signalled.</para>
2273         <para>Otherwise, any of the exceptional situations of
2274           <function>loop</function> applies.</para>
2275       </refsect1>
2276       <refsect1>
2277         <title>See Also</title>
2278         <para>
2279         <simplelist>
2280           <member><link linkend="query"><function>query</function></link></member>
2281           <member><link linkend="map-query"><function>map-query</function></link></member>
2282           <member><link linkend="do-query"><function>do-query</function></link></member>
2283         </simplelist>
2284         </para>
2285       </refsect1>
2286       <refsect1>
2287         <title>Notes</title>
2288         <para>None.</para>
2289       </refsect1>
2290     </refentry>
2291   </reference>
2292   <reference>
2293     <title><symbol>CLSQL-SYS</symbol></title>
2294     <partintro>
2295       <para>This part gives a reference to all the symbols exported
2296         from the package <symbol>CLSQL-SYS</symbol>, which are not also
2297         exported from <symbol>CLSQL</symbol>.  These symbols are part of
2298         the interface for database back-ends, but not part of the normal
2299         user-interface of &clsql;.</para>
2300       <note>
2301         <para>This part has only one demonstration entry, since the
2302           rest still has to be written.  In the meantime, use the
2303           source to understand the database back-end interface.</para>
2304       </note>
2305     </partintro>
2306     <refentry id="database-initialize-database-type">
2307       <refnamediv>
2308         <refname>DATABASE-INITIALIZE-DATABASE-TYPE</refname>
2309         <refpurpose>Back-end part of <link
2310         linkend="initialize-database-type"><function>initialize-database-type</function></link>.</refpurpose>
2311         <refclass>Generic Function</refclass>
2312       </refnamediv>
2313       <refsect1>
2314         <title>Syntax</title>
2315         <synopsis><function>database-initialize-database-type</function> <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
2316       </refsect1>
2317       <refsect1>
2318         <title>Arguments and Values</title>
2319         <variablelist>
2320           <varlistentry>
2321             <term><parameter>database-type</parameter></term>
2322             <listitem>
2323               <para>A keyword indicating the database type to
2324                 initialize.</para>
2325             </listitem>
2326           </varlistentry>
2327           <varlistentry>
2328             <term><returnvalue>result</returnvalue></term>
2329             <listitem>
2330               <para>Either <symbol>t</symbol> if the initialization
2331                 succeeds or <symbol>nil</symbol> if it fails.</para>
2332             </listitem>
2333           </varlistentry>
2334         </variablelist>
2335       </refsect1>
2336       <refsect1>
2337         <title>Description</title>
2338         <para>This generic function implements the main part of the
2339           database type initialization performed by
2340           <function>initialize-database-type</function>.  After
2341           <function>initialize-database-type</function> has checked
2342           that the given database type has not been initialized
2343           before, as indicated by
2344           <symbol>*initialized-database-types*</symbol>, it will call
2345           this function with the database type as it's sole
2346           parameter.  Database back-ends are required to define a
2347           method on this generic function which is specialized via an
2348           eql-specializer to the keyword representing their database
2349           type.</para>
2350         <para>Database back-ends shall indicate successful
2351           initialization by returning <symbol>t</symbol> from their
2352           method, and <symbol>nil</symbol> otherwise.  Methods for
2353           this generic function are allowed to signal errors of type
2354           <errortype>maisql-error</errortype> or subtypes thereof.
2355           They may also signal other types of conditions, if
2356           appropriate, but have to document this.</para>
2357       </refsect1>
2358       <refsect1>
2359         <title>Examples</title>
2360         <para></para>
2361       </refsect1>
2362       <refsect1>
2363         <title>Side Effects</title>
2364         <para>All necessary side effects to initialize the database
2365           instance.</para>
2366       </refsect1>
2367       <refsect1>
2368         <title>Affected By</title>
2369         <para>None.</para>
2370       </refsect1>
2371       <refsect1>
2372         <title>Exceptional Situations</title>
2373         <para>Conditions of type <errortype>maisql-error</errortype>
2374           or other conditions may be signalled, depending on the
2375           database back-end.</para>
2376       </refsect1>
2377       <refsect1>
2378         <title>See Also</title>
2379         <para>
2380         <simplelist>
2381           <member><link
2382           linkend="initialize-database-type"><function>initialize-database-type</function></link></member>
2383           <member><link linkend="initialized-database-types"><symbol>*initialized-database-types*</symbol></link></member>
2384         </simplelist>
2385         </para>
2386       </refsect1>
2387       <refsect1>
2388         <title>Notes</title>
2389         <para>None.</para>
2390       </refsect1>
2391     </refentry>
2392   </reference>