doc/ref_clsql.xml

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