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 was
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 =>
1704 Error: While trying to access database localhost/new/dent
1705   using database-type MYSQL:
1706   Error database-create failed: mysqladmin: connect to server at 'localhost' failed
1707 error: 'Access denied for user: 'root@localhost' (Using password: YES)'
1708   has occurred.
1709   [condition type: CLSQL-ACCESS-ERROR]
1710         </screen>
1711       </refsect1>
1712       <refsect1>
1713         <title>Side Effects</title>
1714         <para>A database will be created on the filesystem of the host.</para>
1715       </refsect1>
1716       <refsect1>
1717         <title>Exceptional Situations</title>
1718         <para>An exception will be thrown if the database system does
1719         not allow new databases to be created or if database creation
1720         fails.</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;, the database was
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 =>
1786 Error: While trying to access database localhost/test2/root
1787   using database-type POSTGRESQL:
1788   Error database-destory failed: dropdb: database removal failed: ERROR:  database "test2" does not exist
1789   has occurred.
1790   [condition type: CLSQL-ACCESS-ERROR]
1791         </screen>
1792       </refsect1>
1793       <refsect1>
1794         <title>Side Effects</title>
1795         <para>A database will be removed from the filesystem of the host.</para>
1796       </refsect1>
1797       <refsect1>
1798         <title>Exceptional Situations</title>
1799         <para>An exception will be thrown if the database system does not
1800         allow databases to be removed, the database does not exist, or
1801         if database removal fails.</para>
1802       </refsect1>
1803       <refsect1>
1804         <title>Notes</title>
1805         <para>This function may invoke the operating systems
1806         functions.  Thus, some database systems may require the
1807         administration functions to be available in the current
1808         <symbol>PATH</symbol>. At this time, the
1809         <symbol>:mysql</symbol> backend requires
1810         <filename>mysqladmin</filename> and the
1811         <symbol>:postgresql</symbol> backend requires
1812         <filename>dropdb</filename>.</para>
1813       </refsect1>
1814     </refentry>
1815
1816     <refentry id="probe_db">
1817       <refnamediv>
1818         <refname>PROBE-DATABASE</refname>
1819         <refpurpose>tests for existence of a database</refpurpose>
1820         <refclass>Function</refclass>
1821       </refnamediv>
1822       <refsect1>
1823         <title>Syntax</title>
1824         <synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
1825       </refsect1>
1826       <refsect1>
1827         <title>Arguments and Values</title>
1828         <variablelist>
1829           <varlistentry>
1830             <term><parameter>connection-spec</parameter></term>
1831             <listitem>
1832               <para>A connection specification</para>
1833             </listitem>
1834           </varlistentry>
1835           <varlistentry>
1836             <term><parameter>database-type</parameter></term>
1837             <listitem>
1838               <para>A database type specifier, i.e. a keyword.
1839                 This defaults to the value of
1840                 <symbol>*default-database-type*</symbol></para>
1841             </listitem>
1842           </varlistentry>
1843           <varlistentry>
1844             <term><parameter>success</parameter></term>
1845             <listitem>
1846               <para>A boolean flag. If &t;, the database exists
1847               in the database system.
1848               </para>
1849             </listitem>
1850           </varlistentry>
1851         </variablelist>
1852       </refsect1>
1853       <refsect1>
1854         <title>Description</title>
1855         <para>This function tests for the existence of a database in
1856         the database system specified by
1857         <parameter>database-type</parameter>.
1858         </para>
1859       </refsect1>
1860       <refsect1>
1861         <title>Examples</title>
1862         <screen>
1863 (probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
1864 => T
1865         </screen>
1866       </refsect1>
1867       <refsect1>
1868         <title>Side Effects</title>
1869         <para>None</para>
1870       </refsect1>
1871       <refsect1>
1872         <title>Exceptional Situations</title>
1873         <para>An exception maybe thrown if the database system does
1874         not receive administrator-level authentication since function
1875         may need to read the administrative database of the database
1876         system.</para>
1877       </refsect1>
1878       <refsect1>
1879         <title>Notes</title>
1880         <para>None.</para>
1881       </refsect1>
1882     </refentry>
1883
1884     <refentry id="database-name-from-spec">
1885       <refnamediv>
1886         <refname>DATABASE-NAME-FROM-SPEC</refname>
1887         <refpurpose>Return the database name string corresponding to
1888           the given connection specification.</refpurpose>
1889         <refclass>Generic Function</refclass>
1890       </refnamediv>
1891       <refsect1>
1892         <title>Syntax</title>
1893         <synopsis>
1894           <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
1895       </refsect1>
1896       <refsect1>
1897         <title>Arguments and Values</title>
1898         <variablelist>
1899           <varlistentry>
1900             <term><parameter>connection-spec</parameter></term>
1901             <listitem>
1902               <para>A connection specification, whose structure and
1903                 interpretation are dependent on the
1904                 <parameter>database-type</parameter>.</para>
1905             </listitem>
1906           </varlistentry>
1907           <varlistentry>
1908             <term><parameter>database-type</parameter></term>
1909             <listitem>
1910               <para>A database type specifier, i.e. a keyword.</para>
1911             </listitem>
1912           </varlistentry>
1913           <varlistentry>
1914             <term><returnvalue>name</returnvalue></term>
1915             <listitem>
1916               <para>A string denoting a database name.</para>
1917             </listitem>
1918           </varlistentry>
1919         </variablelist>
1920       </refsect1>
1921       <refsect1>
1922         <title>Description</title>
1923         <para>This generic function takes a connection specification
1924           and a database type and returns the database name of the
1925           database object that would be created had
1926           <function>connect</function> been called with the given
1927           connection specification and database types.</para>
1928         <para>This function is useful in determining a database name
1929           from the connection specification, since the way the
1930           connection specification is converted into a database name
1931           is dependent on the database type.</para>
1932       </refsect1>
1933       <refsect1>
1934         <title>Examples</title>
1935         <screen>
1936 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1937 => "dent/newesim/dent"
1938 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1939 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1940 (database-name *default-database*)
1941 => "dent/newesim/dent"
1942
1943 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1944 => "/template1/dent"
1945 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1946 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1947 (database-name *default-database*)
1948 => "/template1/dent"
1949
1950 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1951 => "www.pmsf.de/template1/dent"
1952
1953 (find-database "dent/newesim/dent")
1954 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1955 (find-database "/template1/dent")
1956 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1957 (find-database "www.pmsf.de/template1/dent" nil)
1958 => NIL
1959 (find-database **)
1960 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1961         </screen>
1962       </refsect1>
1963       <refsect1>
1964         <title>Side Effects</title>
1965         <para>None.</para>
1966       </refsect1>
1967       <refsect1>
1968         <title>Affected by</title>
1969         <para>None.</para>
1970       </refsect1>
1971       <refsect1>
1972         <title>Exceptional Situations</title>
1973         <para>If the value of <parameter>connection-spec</parameter>
1974           is not a valid connection specification for the given
1975           database type, an error of type
1976           <errortype>clsql-invalid-spec-error</errortype> might be
1977           signalled.</para>
1978       </refsect1>
1979       <refsect1>
1980         <title>See Also</title>
1981         <para>
1982         <simplelist>
1983           <member><link linkend="connect"><function>connect</function></link></member>
1984         </simplelist>
1985         </para>
1986       </refsect1>
1987       <refsect1>
1988         <title>Notes</title>
1989         <para>None.</para>
1990       </refsect1>
1991     </refentry>
1992     <!-- Querying Operations -->
1993     <refentry id="execute-command">
1994       <refnamediv>
1995         <refname>EXECUTE-COMMAND</refname>
1996         <refpurpose>Execute an SQL command which returns no
1997           values.</refpurpose>
1998         <refclass>Function</refclass>
1999       </refnamediv>
2000       <refsect1>
2001         <title>Syntax</title>
2002         <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
2003       </refsect1>
2004       <refsect1>
2005         <title>Arguments and Values</title>
2006         <variablelist>
2007           <varlistentry>
2008             <term><parameter>sql-expression</parameter></term>
2009             <listitem>
2010               <para>An <glossterm linkend="gloss-sql-expression">sql
2011                   expression</glossterm> that represents an SQL
2012                 statement which will return no values.</para>
2013             </listitem>
2014           </varlistentry>
2015           <varlistentry>
2016             <term><parameter>database</parameter></term>
2017             <listitem>
2018               <para>A
2019                 <glossterm linkend="gloss-database-object">database
2020                   object</glossterm>. This will default to the value
2021                 of <symbol>*default-database*</symbol>.</para>
2022             </listitem>
2023           </varlistentry>
2024         </variablelist>
2025       </refsect1>
2026       <refsect1>
2027         <title>Description</title>
2028         <para>This will execute the command given by
2029           <parameter>sql-expression</parameter> in the
2030           <parameter>database</parameter> specified.  If the execution
2031           succeeds it will return <symbol>t</symbol>, otherwise an
2032           error of type <errortype>clsql-sql-error</errortype> will
2033           be signalled.</para>
2034       </refsect1>
2035       <refsect1>
2036         <title>Examples</title>
2037         <screen>
2038 (execute-command "create table eventlog (time char(30),event char(70))")
2039 => T
2040
2041 (execute-command "create table eventlog (time char(30),event char(70))")
2042 >>
2043 >> While accessing database #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
2044 >>   with expression "create table eventlog (time char(30),event char(70))":
2045 >>   Error NIL: ERROR:  amcreate: eventlog relation already exists
2046 >>   has occurred.
2047 >>
2048 >> Restarts:
2049 >>   0: [ABORT] Return to Top-Level.
2050 >>
2051 >> Debug  (type H for help)
2052 >>
2053 >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
2054 >>  #&lt;unused-arg>
2055 >>  #&lt;unused-arg>
2056 >>  #&lt;unavailable-arg>
2057 >>  #&lt;unavailable-arg>)
2058 >> Source: (ERROR 'CLSQL-SQL-ERROR :DATABASE DATABASE :EXPRESSION ...)
2059 >> 0] 0
2060
2061 (execute-command "drop table eventlog")
2062 => T
2063         </screen>
2064       </refsect1>
2065       <refsect1>
2066         <title>Side Effects</title>
2067         <para>Whatever effects the execution of the SQL statement has
2068           on the underlying database, if any.</para>
2069       </refsect1>
2070       <refsect1>
2071         <title>Affected by</title>
2072         <para>None.</para>
2073       </refsect1>
2074       <refsect1>
2075         <title>Exceptional Situations</title>
2076         <para>If the execution of  the SQL statement leads to any
2077           errors, an error of type
2078           <errortype>clsql-sql-error</errortype> is signalled.</para>
2079       </refsect1>
2080       <refsect1>
2081         <title>See Also</title>
2082         <para>
2083         <simplelist>
2084           <member><link linkend="query"><function>query</function></link></member>
2085         </simplelist>
2086         </para>
2087       </refsect1>
2088       <refsect1>
2089         <title>Notes</title>
2090         <para>None.</para>
2091       </refsect1>
2092     </refentry>
2093     <refentry id="query">
2094       <refnamediv>
2095         <refname>QUERY</refname>
2096         <refpurpose>Execute an SQL query and return the tuples as a
2097           list</refpurpose>
2098         <refclass>Function</refclass>
2099       </refnamediv>
2100       <refsect1>
2101         <title>Syntax</title>
2102         <synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> => <returnvalue>result</returnvalue></synopsis>
2103       </refsect1>
2104       <refsect1>
2105         <title>Arguments and Values</title>
2106         <variablelist>
2107           <varlistentry>
2108             <term><parameter>query-expression</parameter></term>
2109             <listitem>
2110               <para>An <glossterm linkend="gloss-sql-expression">sql
2111                   expression</glossterm> that represents an SQL
2112                 query which is expected to return a (possibly empty)
2113                 result set.</para>
2114             </listitem>
2115           </varlistentry>
2116           <varlistentry>
2117             <term><parameter>database</parameter></term>
2118             <listitem>
2119               <para>A
2120                 <glossterm linkend="gloss-database-object">database
2121                   object</glossterm>. This will default to the value
2122                 of <symbol>*default-database*</symbol>.</para>
2123             </listitem>
2124           </varlistentry>
2125           <varlistentry>
2126             <term><parameter>result-types</parameter></term>
2127             <listitem>
2128               <para>A
2129                 <glossterm linkend="gloss-field-types">field type
2130                   specifier</glossterm>. The default is &nil;.
2131                 </para>
2132                 <para>
2133                   The purpose of this argument is cause &clsql; to
2134                   import SQL numeric fields into numeric Lisp objects
2135                   rather than strings. This reduces the cost of
2136                   allocating a temporary string and the &clsql; users'
2137                   inconvenience of converting number strings into number
2138                   objects.
2139                 </para>
2140                 <para>
2141                   A value of <symbol>:auto</symbol> causes &clsql;
2142                   to automatically convert SQL fields into a
2143                   numeric format where applicable. The default value of
2144                   &nil; causes all fields to be returned as strings
2145                   regardless of the SQL type. Otherwise a list is expected
2146                   which has a element for each field that specifies the
2147                   conversion. If the list is shorter than the number
2148                   of fields, the a value of <symbol>t</symbol> is
2149                   assumed for the field.  If the list is longer than
2150                   the number of fields, the extra elements are
2151                   ignored.
2152                   <simplelist type="vert">
2153                     <member><symbol>:int</symbol> Field is imported as a
2154                       signed integer, from 8-bits to 64-bits depending
2155                       upon the field type.
2156                     </member>
2157                     <member><symbol>:double</symbol> Field is imported as a
2158                       double-float number.
2159                     </member>
2160                     <member><symbol>t</symbol> Field is imported as a
2161                       string.
2162                     </member>
2163                   </simplelist>
2164                 </para>
2165             </listitem>
2166           </varlistentry>
2167           <varlistentry>
2168             <term><parameter>field-names</parameter></term>
2169             <para>
2170               A boolean with a default value of &t;. When &t;, this
2171               function results a second value of a list of field
2172               names. When &nil;, this function only returns one value
2173               - the list of rows.
2174             </para>
2175           </varlistentry>
2176           <varlistentry>
2177             <term><returnvalue>result</returnvalue></term>
2178             <listitem>
2179               <para>A list representing the result set obtained.  For
2180                 each tuple in the result set, there is an element in
2181                 this list, which is itself a list of all the attribute
2182                 values in the tuple.</para>
2183             </listitem>
2184           </varlistentry>
2185         </variablelist>
2186       </refsect1>
2187       <refsect1>
2188         <title>Description</title>
2189         <para>This will execute the query given by
2190           <parameter>query-expression</parameter> in the
2191           <parameter>database</parameter> specified.  If the execution
2192           succeeds it will return the result set returned by the
2193           database, otherwise an error of type
2194           <errortype>clsql-sql-error</errortype> will
2195           be signalled.</para>
2196       </refsect1>
2197       <refsect1>
2198         <title>Examples</title>
2199         <screen>
2200 (execute-command "create table simple (name char(50), salary numeric(10,2))")
2201 => T
2202 (execute-command "insert into simple values ('Mai, Pierre',10000)")
2203 => T
2204 (execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
2205 => T
2206 (query "select * from simple")
2207 => (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
2208 (query "select salary from simple")
2209 => (("10000.00") ("8000.50"))
2210 (query "select salary from simple where salary > 10000")
2211 => NIL
2212 (query "select salary,name from simple where salary > 10000")
2213 => NIL
2214 (query "select salary,name from simple where salary > 9000")
2215 => (("10000.00" "Mai, Pierre"))
2216 (query "select salary,name from simple where salary > 8000")
2217 => (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
2218
2219 ;; MySQL-specific:
2220 (query "show tables")
2221 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
2222         </screen>
2223       </refsect1>
2224       <refsect1>
2225         <title>Side Effects</title>
2226         <para>Whatever effects the execution of the SQL query has
2227           on the underlying database, if any.</para>
2228       </refsect1>
2229       <refsect1>
2230         <title>Affected by</title>
2231         <para>None.</para>
2232       </refsect1>
2233       <refsect1>
2234         <title>Exceptional Situations</title>
2235         <para>If the execution of  the SQL query leads to any
2236           errors, an error of type
2237           <errortype>clsql-sql-error</errortype> is signalled.</para>
2238       </refsect1>
2239       <refsect1>
2240         <title>See Also</title>
2241         <para>
2242         <simplelist>
2243           <member><link linkend="execute-command"><function>execute-command</function></link></member>
2244         </simplelist>
2245         </para>
2246       </refsect1>
2247       <refsect1>
2248         <title>Notes</title>
2249         <para>None.</para>
2250       </refsect1>
2251     </refentry>
2252     <!-- Iteration -->
2253     <refentry id="map-query">
2254       <refnamediv>
2255         <refname>MAP-QUERY</refname>
2256         <refpurpose>Map a function over all the tuples from a
2257           query</refpurpose>
2258         <refclass>Function</refclass>
2259       </refnamediv>
2260       <refsect1>
2261         <title>Syntax</title>
2262         <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>
2263       </refsect1>
2264       <refsect1>
2265         <title>Arguments and Values</title>
2266         <variablelist>
2267           <varlistentry>
2268             <term><parameter>output-type-spec</parameter></term>
2269             <listitem>
2270               <para>A sequence type specifier or <symbol>nil</symbol>.</para>
2271             </listitem>
2272           </varlistentry>
2273           <varlistentry>
2274             <term><parameter>function</parameter></term>
2275             <listitem>
2276               <para>A function designator.
2277                 <parameter>function</parameter> must take as many
2278                 arguments as are attributes in the result set returned
2279                 by executing the SQL
2280                 <parameter>query-expression</parameter>.</para>
2281             </listitem>
2282           </varlistentry>
2283           <varlistentry>
2284             <term><parameter>query-expression</parameter></term>
2285             <listitem>
2286               <para>An <glossterm linkend="gloss-sql-expression">sql
2287                   expression</glossterm> that represents an SQL
2288                 query which is expected to return a (possibly empty)
2289                 result set, where each tuple has as many attributes as
2290                 <parameter>function</parameter> takes arguments.</para>
2291             </listitem>
2292           </varlistentry>
2293           <varlistentry>
2294             <term><parameter>database</parameter></term>
2295             <listitem>
2296               <para>A
2297                 <glossterm linkend="gloss-database-object">database
2298                   object</glossterm>. This will default to the value
2299                 of <symbol>*default-database*</symbol>.</para>
2300             </listitem>
2301           </varlistentry>
2302           <varlistentry>
2303             <term><parameter>result-types</parameter></term>
2304             <listitem>
2305               <para>
2306                 A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
2307                 The default is &nil;. See <link
2308                 linkend="query"><function>query</function></link>
2309                 for the semantics of this argument.
2310               </para>
2311             </listitem>
2312           </varlistentry>
2313           <varlistentry>
2314             <term><returnvalue>result</returnvalue></term>
2315             <listitem>
2316               <para>If <parameter>output-type-spec</parameter> is a
2317                 type specifier other than <symbol>nil</symbol>, then a
2318                 sequence of the type it denotes.  Otherwise
2319                 <symbol>nil</symbol> is returned.</para>
2320             </listitem>
2321           </varlistentry>
2322         </variablelist>
2323       </refsect1>
2324       <refsect1>
2325         <title>Description</title>
2326         <para>Applies <parameter>function</parameter> to the
2327           attributes of successive tuples in the result set returned
2328           by executing the SQL
2329           <parameter>query-expression</parameter>.  If the
2330           <parameter>output-type-spec</parameter> is
2331           <symbol>nil</symbol>, then the result of each application
2332           of <parameter>function</parameter> is discarded, and
2333           <function>map-query</function> returns
2334           <symbol>nil</symbol>.  Otherwise the result of each
2335           successive application of <parameter>function</parameter> is
2336           collected in a sequence of type
2337           <parameter>output-type-spec</parameter>, where the jths
2338           element is the result of applying
2339           <parameter>function</parameter> to the attributes of the
2340           jths tuple in the result set.  The collected sequence is the
2341           result of the call to <function>map-query</function>.
2342         </para>
2343         <para>If the <parameter>output-type-spec</parameter> is a
2344           subtype of <type>list</type>, the result will be a
2345           <type>list</type>.</para>
2346         <para>If the <parameter>result-type</parameter> is a subtype
2347           of <type>vector</type>, then if the implementation can
2348           determine the element type specified for the
2349           <parameter>result-type</parameter>, the element type of the
2350           resulting array is the result of
2351           <emphasis>upgrading</emphasis> that element type; or, if the
2352           implementation can determine that the element type is
2353           unspecified (or <symbol>*</symbol>), the element type of the
2354           resulting array is <type>t</type>; otherwise, an error is
2355           signaled.</para>
2356       </refsect1>
2357       <refsect1>
2358         <title>Examples</title>
2359         <screen>
2360 (map-query 'list #'(lambda (salary name)
2361                      (declare (ignorable name))
2362                      (read-from-string salary))
2363            "select salary,name from simple where salary > 8000")
2364 => (10000.0 8000.5)
2365
2366 (map-query '(vector double-float)
2367            #'(lambda (salary name)
2368                (declare (ignorable name))
2369                (let ((*read-default-float-format* 'double-float))
2370                  (coerce (read-from-string salary) 'double-float))
2371                   "select salary,name from simple where salary > 8000"))
2372 => #(10000.0d0 8000.5d0)
2373 (type-of *)
2374 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
2375
2376 (let (list)
2377   (values (map-query nil #'(lambda (salary name)
2378                              (push (cons name (read-from-string salary)) list))
2379                      "select salary,name from simple where salary > 8000")
2380           list))
2381 => NIL
2382 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
2383         </screen>
2384       </refsect1>
2385       <refsect1>
2386         <title>Side Effects</title>
2387         <para>Whatever effects the execution of the SQL query has
2388           on the underlying database, if any.</para>
2389       </refsect1>
2390       <refsect1>
2391         <title>Affected by</title>
2392         <para>None.</para>
2393       </refsect1>
2394       <refsect1>
2395         <title>Exceptional Situations</title>
2396         <para>If the execution of  the SQL query leads to any
2397           errors, an error of type
2398           <errortype>clsql-sql-error</errortype> is signalled.</para>
2399         <para>An error of type <errortype>type-error</errortype> must
2400           be signaled if the <parameter>output-type-spec</parameter> is
2401           not a recognizable subtype of <type>list</type>, not a
2402           recognizable subtype of <type>vector</type>, and not
2403           <symbol>nil</symbol>.</para>
2404         <para>An error of type <errortype>type-error</errortype>
2405           should be signaled if
2406           <parameter>output-type-spec</parameter> specifies the number
2407           of elements and the size of the result set is different from
2408           that number.</para>
2409       </refsect1>
2410       <refsect1>
2411         <title>See Also</title>
2412         <para>
2413         <simplelist>
2414           <member><link linkend="query"><function>query</function></link></member>
2415           <member><link linkend="do-query"><function>do-query</function></link></member>
2416         </simplelist>
2417         </para>
2418       </refsect1>
2419       <refsect1>
2420         <title>Notes</title>
2421         <para>None.</para>
2422       </refsect1>
2423     </refentry>
2424     <refentry id="do-query">
2425       <refnamediv>
2426         <refname>DO-QUERY</refname>
2427         <refpurpose>Iterate over all the tuples of a
2428         query</refpurpose>
2429         <refclass>Macro</refclass>
2430       </refnamediv>
2431       <refsect1>
2432         <title>Syntax</title>
2433         <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>
2434       </refsect1>
2435       <refsect1>
2436         <title>Arguments and Values</title>
2437         <variablelist>
2438           <varlistentry>
2439             <term><parameter>args</parameter></term>
2440             <listitem>
2441               <para>A list of variable names.</para>
2442             </listitem>
2443           </varlistentry>
2444           <varlistentry>
2445             <term><parameter>query-expression</parameter></term>
2446             <listitem>
2447               <para>An <glossterm linkend="gloss-sql-expression">sql
2448                   expression</glossterm> that represents an SQL
2449                 query which is expected to return a (possibly empty)
2450                 result set, where each tuple has as many attributes as
2451                 <parameter>function</parameter> takes arguments.</para>
2452             </listitem>
2453           </varlistentry>
2454           <varlistentry>
2455             <term><parameter>database</parameter></term>
2456             <listitem>
2457               <para>A
2458                 <glossterm linkend="gloss-database-object">database
2459                   object</glossterm>. This will default to
2460                 <symbol>*default-database*</symbol>.</para>
2461             </listitem>
2462           </varlistentry>
2463           <varlistentry>
2464             <term><parameter>result-types</parameter></term>
2465             <listitem>
2466               <para>
2467                 A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
2468                 The default is &nil;. See <link
2469                 linkend="query"><function>query</function></link>
2470                 for the semantics of this argument.
2471               </para>
2472             </listitem>
2473           </varlistentry>
2474           <varlistentry>
2475             <term><parameter>body</parameter></term>
2476             <listitem>
2477               <para>A body of Lisp code, like in a
2478                 <function>destructuring-bind</function> form.</para>
2479             </listitem>
2480           </varlistentry>
2481         </variablelist>
2482       </refsect1>
2483       <refsect1>
2484         <title>Description</title>
2485         <para>Executes the <parameter>body</parameter> of code
2486           repeatedly with the variable names in
2487           <parameter>args</parameter> bound to the attributes of each
2488           tuple in the result set returned by executing the SQL
2489           <parameter>query-expression</parameter> on the
2490           <parameter>database</parameter> specified.</para>
2491         <para>The body of code is executed in a block named
2492           <symbol>nil</symbol> which may be returned from prematurely
2493           via <function>return</function> or
2494           <function>return-from</function>.  In this case the result
2495           of evaluating the <function>do-query</function> form will be
2496           the one supplied to <function>return</function> or
2497           <function>return-from</function>.  Otherwise the result will
2498           be <symbol>nil</symbol>.</para>
2499         <para>The body of code appears also is if wrapped in a
2500           <function>destructuring-bind</function> form, thus allowing
2501           declarations at the start of the body, especially those
2502           pertaining to the bindings of the variables named in
2503           <parameter>args</parameter>.</para>
2504       </refsect1>
2505       <refsect1>
2506         <title>Examples</title>
2507         <screen>
2508 (do-query ((salary name) "select salary,name from simple")
2509   (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
2510 >> Mai, Pierre                    gets $10000.00
2511 >> Hacker, Random J.              gets $08000.50
2512 => NIL
2513
2514 (do-query ((salary name) "select salary,name from simple")
2515   (return (cons salary name)))
2516 => ("10000.00" . "Mai, Pierre")
2517         </screen>
2518       </refsect1>
2519       <refsect1>
2520         <title>Side Effects</title>
2521         <para>Whatever effects the execution of the SQL query has
2522           on the underlying database, if any.</para>
2523       </refsect1>
2524       <refsect1>
2525         <title>Affected by</title>
2526         <para>None.</para>
2527       </refsect1>
2528       <refsect1>
2529         <title>Exceptional Situations</title>
2530         <para>If the execution of  the SQL query leads to any
2531           errors, an error of type
2532           <errortype>clsql-sql-error</errortype> is signalled.</para>
2533         <para>If the number of variable names in
2534           <parameter>args</parameter> and the number of attributes in
2535           the tuples in the result set don't match up, an error is
2536           signalled.</para>
2537       </refsect1>
2538       <refsect1>
2539         <title>See Also</title>
2540         <para>
2541         <simplelist>
2542           <member><link linkend="query"><function>query</function></link></member>
2543           <member><link linkend="map-query"><function>map-query</function></link></member>
2544         </simplelist>
2545         </para>
2546       </refsect1>
2547       <refsect1>
2548         <title>Notes</title>
2549         <para>None.</para>
2550       </refsect1>
2551     </refentry>
2552     <refentry id="loop-tuples">
2553       <refnamediv>
2554         <refname>LOOP-FOR-AS-TUPLES</refname>
2555         <refpurpose>Iterate over all the tuples of a
2556         query via a loop clause</refpurpose>
2557         <refclass>Loop Clause</refclass>
2558       </refnamediv>
2559       <refsect1>
2560         <title>Compatibility</title>
2561         <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
2562       </refsect1>
2563       <refsect1>
2564         <title>Syntax</title>
2565         <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>
2566       </refsect1>
2567       <refsect1>
2568         <title>Arguments and Values</title>
2569         <variablelist>
2570           <varlistentry>
2571             <term><parameter>var</parameter></term>
2572             <listitem>
2573               <para>A <literal>d-var-spec</literal>, as defined in the
2574                 grammar for <function>loop</function>-clauses in the
2575                 ANSI Standard for Common Lisp.  This allows for the
2576                 usual loop-style destructuring.</para>
2577             </listitem>
2578           </varlistentry>
2579           <varlistentry>
2580             <term><parameter>type-spec</parameter></term>
2581             <listitem>
2582               <para>An optional <literal>type-spec</literal> either
2583                 simple or destructured, as defined in the grammar for
2584                 <function>loop</function>-clauses in the ANSI Standard
2585                 for Common Lisp.</para>
2586             </listitem>
2587           </varlistentry>
2588           <varlistentry>
2589             <term><parameter>query</parameter></term>
2590             <listitem>
2591               <para>An <glossterm linkend="gloss-sql-expression">sql
2592                   expression</glossterm> that represents an SQL
2593                 query which is expected to return a (possibly empty)
2594                 result set, where each tuple has as many attributes as
2595                 <parameter>function</parameter> takes arguments.</para>
2596             </listitem>
2597           </varlistentry>
2598           <varlistentry>
2599             <term><parameter>database</parameter></term>
2600             <listitem>
2601               <para>An optional
2602                 <glossterm linkend="gloss-database-object">database
2603                   object</glossterm>. This will default to the value
2604                 of <symbol>*default-database*</symbol>.</para>
2605             </listitem>
2606           </varlistentry>
2607         </variablelist>
2608       </refsect1>
2609       <refsect1>
2610         <title>Description</title>
2611         <para>This clause is an iteration driver for
2612         <function>loop</function>, that binds the given variable
2613           (possibly destructured) to the consecutive tuples (which are
2614           represented as lists of attribute values) in the result set
2615           returned by executing the SQL <parameter>query</parameter>
2616           expression on the <parameter>database</parameter>
2617           specified.</para>
2618       </refsect1>
2619       <refsect1>
2620         <title>Examples</title>
2621         <screen>
2622 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
2623   "My database"
2624 => *MY-DB*
2625 (loop with time-graph = (make-hash-table :test #'equal)
2626       with event-graph = (make-hash-table :test #'equal)
2627       for (time event) being the tuples of "select time,event from log"
2628       from *my-db*
2629       do
2630       (incf (gethash time time-graph 0))
2631       (incf (gethash event event-graph 0))
2632       finally
2633       (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
2634         (format t "~&amp;Time-Graph:~%===========~%")
2635         (maphash #'show-graph time-graph)
2636         (format t "~&amp;~%Event-Graph:~%============~%")
2637         (maphash #'show-graph event-graph))
2638       (return (values time-graph event-graph)))
2639 >> Time-Graph:
2640 >> ===========
2641 >> D                                        => 53000
2642 >> X                                        =>     3
2643 >> test-me                                  =>  3000
2644 >>
2645 >> Event-Graph:
2646 >> ============
2647 >> CLOS Benchmark entry.                    =>  9000
2648 >> Demo Text...                             =>     3
2649 >> doit-text                                =>  3000
2650 >> C    Benchmark entry.                    => 12000
2651 >> CLOS Benchmark entry                     => 32000
2652 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
2653 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
2654         </screen>
2655       </refsect1>
2656       <refsect1>
2657         <title>Side Effects</title>
2658         <para>Whatever effects the execution of the SQL query has
2659           on the underlying database, if any.</para>
2660       </refsect1>
2661       <refsect1>
2662         <title>Affected by</title>
2663         <para>None.</para>
2664       </refsect1>
2665       <refsect1>
2666         <title>Exceptional Situations</title>
2667         <para>If the execution of  the SQL query leads to any
2668           errors, an error of type
2669           <errortype>clsql-sql-error</errortype> is signalled.</para>
2670         <para>Otherwise, any of the exceptional situations of
2671           <function>loop</function> applies.</para>
2672       </refsect1>
2673       <refsect1>
2674         <title>See Also</title>
2675         <para>
2676         <simplelist>
2677           <member><link linkend="query"><function>query</function></link></member>
2678           <member><link linkend="map-query"><function>map-query</function></link></member>
2679           <member><link linkend="do-query"><function>do-query</function></link></member>
2680         </simplelist>
2681         </para>
2682       </refsect1>
2683       <refsect1>
2684         <title>Notes</title>
2685         <para>None.</para>
2686       </refsect1>
2687     </refentry>
2688   </reference>