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