doc/ref-connect.xml

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