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