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