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