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 <!-- Connection and Initialisation -->
   9 <reference id="ref-connect">
  10   <title>Connection and Initialisation</title>
  11   <partintro>
  12     <para>
  13       <!-- introduction -->
  14     </para>
  15   </partintro>
  16
  17     <refentry id="database">
  18     <refnamediv>
  19       <refname>DATABASE</refname>
  20       <refpurpose>The super-type of all &clsql; databases</refpurpose>
  21       <refclass>Class</refclass>
  22     </refnamediv>
  23     <refsect1>
  24       <title>Class Precedence List</title>
  25       <para>
  26         <simplelist type="inline">
  27           <member><type>database</type></member>
  28           <member><type>standard-object</type></member>
  29           <member><type>t</type></member>
  30         </simplelist>
  31       </para>
  32     </refsect1>
  33     <refsect1>
  34       <title>Description</title> <para>This class is the superclass
  35       of all &clsql; databases. The different database back-ends
  36       derive subclasses of this class to implement their databases.
  37       No instances of this class are ever created by &clsql;.</para>
  38     </refsect1>
  39     <refsect1>
  40       <title class="contenttitle">Class details</title>
  41       <programlisting>(defclass DATABASE ()(...))</programlisting>
  42     </refsect1>
  43     <refsect1>
  44       <title class="contenttitle">Slots</title>
  45       <para>
  46         <simplelist>
  47           <property>slot COMMAND-RECORDING-STREAM is of type T</property>
  48           <property>slot CONN-POOL is of type T</property>
  49           <property>slot NAME is of type T</property>
  50           <property>slot RECORD-CACHES is of type T</property>
  51           <property>slot RESULT-RECORDING-STREAM is of type T</property>
  52           <property>slot STATE is of type T</property>
  53           <property>slot TRANSACTION is of type T</property>
  54           <property>slot TRANSACTION-LEVEL is of type T</property>
  55           <property>slot VIEW-CLASSES is of type T</property>
  56         </simplelist>
  57       </para>
  58     </refsect1>
  59   </refentry>
  60
  61   <refentry id="connect-if-exists">
  62     <refnamediv>
  63       <refname>*CONNECT-IF-EXISTS*</refname>
  64       <refpurpose>Default value for the
  65       <parameter>if-exists</parameter> parameter of
  66       <function>connect</function>.</refpurpose>
  67       <refclass>Variable</refclass>
  68     </refnamediv>
  69     <refsect1>
  70       <title>Value Type</title>
  71       <para>A valid argument to the <parameter>if-exists</parameter>
  72       parameter of <function>connect</function>, i.e. one of
  73       <simplelist type="inline">
  74         <member><symbol>:new</symbol></member>
  75         <member><symbol>:warn-new</symbol></member>
  76         <member><symbol>:error</symbol></member>
  77         <member><symbol>:warn-old</symbol></member>
  78         <member><symbol>:old</symbol></member>
  79         </simplelist>.
  80       </para>
  81     </refsect1>
  82     <refsect1>
  83       <title>Initial Value</title>
  84       <para><symbol>:error</symbol></para>
  85     </refsect1>
  86     <refsect1>
  87       <title>Description</title>
  88       <para>The value of this variable is used in calls to
  89       <function>connect</function> as the default
  90       value of the <parameter>if-exists</parameter>
  91       parameter.  See <link
  92       linkend="connect"><function>connect</function></link> for
  93       the semantics of the valid values for this variable.</para>
  94     </refsect1>
  95     <refsect1>
  96       <title>Examples</title>
  97       <para>None.</para>
  98     </refsect1>
  99     <refsect1>
 100       <title>Affected By</title>
 101       <para>None.</para>
 102     </refsect1>
 103     <refsect1>
 104       <title>See Also</title>
 105       <para>
 106         <simplelist>
 107           <member><link
 108           linkend="connect"><function>connect</function></link></member>
 109         </simplelist>
 110       </para>
 111     </refsect1>
 112     <refsect1>
 113       <title>Notes</title>
 114       <para>None.</para>
 115     </refsect1>
 116   </refentry>
 117
 118
 119   <refentry id="default-database">
 120     <refnamediv>
 121       <refname>*DEFAULT-DATABASE*</refname>
 122       <refpurpose>The default database object to use</refpurpose>
 123       <refclass>Variable</refclass>
 124     </refnamediv>
 125     <refsect1>
 126       <title>Value Type</title>
 127       <para>Any object of type <type>database</type>, or nil to
 128       indicate no default database.</para>
 129     </refsect1>
 130     <refsect1>
 131       <title>Initial Value</title>
 132       <para><symbol>nil</symbol></para>
 133     </refsect1>
 134     <refsect1>
 135       <title>Description</title>
 136       <para>Any function or macro in
 137       &clsql; that operates on a
 138       database uses the value of this variable as the default
 139       value for it's <parameter>database</parameter>
 140       parameter.</para>
 141       <para>The value of this parameter is changed by calls to
 142       <function>connect</function>, which sets
 143       <symbol>*default-database*</symbol> to the database object
 144       it returns.  It is also changed by calls to
 145       <function>disconnect</function>, when the database object
 146       being disconnected is the same as the value of
 147       <symbol>*default-database*</symbol>.  In this case
 148       <function>disconnect</function> sets
 149       <symbol>*default-database*</symbol> to the first database
 150       that remains in the list of active databases as returned by
 151       <function>connected-databases</function>, or
 152       <symbol>nil</symbol> if no further active databases
 153       exist.</para>
 154       <para>The user may change <symbol>*default-database*</symbol>
 155       at any time to a valid value of his choice.</para>
 156       <caution>
 157         <para>If the value of <symbol>*default-database*</symbol> is
 158         <symbol>nil</symbol>, then all calls to
 159         &clsql; functions on databases
 160         must provide a suitable <parameter>database</parameter>
 161         parameter, or an error will be signalled.</para>
 162       </caution>
 163     </refsect1>
 164     <refsect1>
 165       <title>Examples</title>
 166       <screen>
 167         (connected-databases)
 168         => NIL
 169         (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
 170         => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
 171         (connect '(nil "template1" "dent" nil) :database-type :postgresql)
 172         => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
 173         (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
 174         => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
 175         *default-database*
 176         => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
 177         (disconnect)
 178         => T
 179         *default-database*
 180         => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
 181         (disconnect)
 182         => T
 183         *default-database*
 184         => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
 185         (disconnect)
 186         => T
 187         *default-database*
 188         => NIL
 189         (connected-databases)
 190         => NIL
 191       </screen>
 192     </refsect1>
 193     <refsect1>
 194       <title>Affected By</title>
 195       <para>
 196         <simplelist>
 197           <member><link linkend="connect"><function>connect</function></link></member>
 198           <member><link linkend="disconnect"><function>disconnect</function></link></member>
 199         </simplelist>
 200       </para>
 201     </refsect1>
 202     <refsect1>
 203       <title>See Also</title>
 204       <para>
 205         <simplelist>
 206           <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
 207         </simplelist>
 208       </para>
 209     </refsect1>
 210     <refsect1>
 211       <title>Notes</title>
 212       <note>
 213         <para>This variable is intended to facilitate working with
 214         &clsql; in an interactive
 215         fashion at the top-level loop, and because of this,
 216         <function>connect</function> and
 217         <function>disconnect</function> provide some fairly
 218         complex  behaviour to keep
 219         <symbol>*default-database*</symbol> set to  useful values.
 220         Programmatic use of &clsql;
 221         should never depend on the value of
 222         <symbol>*default-database*</symbol> and should provide
 223         correct database objects via the
 224         <parameter>database</parameter> parameter to functions
 225         called.</para>
 226       </note>
 227     </refsect1>
 228   </refentry>
 229
 230
 231   <refentry id="default-database-type">
 232     <refnamediv>
 233       <refname>*DEFAULT-DATABASE-TYPE*</refname>
 234       <refpurpose>The default database type to use</refpurpose>
 235       <refclass>Variable</refclass>
 236     </refnamediv>
 237     <refsect1>
 238       <title>Value Type</title>
 239       <para>Any keyword representing a valid database back-end of
 240       &clsql;, or
 241       <symbol>nil</symbol>.</para>
 242     </refsect1>
 243     <refsect1>
 244       <title>Initial Value</title>
 245       <para><symbol>nil</symbol></para>
 246     </refsect1>
 247     <refsect1>
 248       <title>Description</title>
 249       <para>The value of this variable is used in calls to
 250       <function>initialize-database-type</function> and
 251       <function>connect</function> as the default
 252       value of the <parameter>database-type</parameter>
 253       parameter.</para>
 254       <caution>
 255         <para>If the value of this variable is <symbol>nil</symbol>,
 256         then all calls to
 257         <function>initialize-database-type</function> or
 258         <function>connect</function> will have to specify the
 259         <parameter>database-type</parameter> to use, or a
 260         general-purpose error will be signalled.</para>
 261       </caution>
 262     </refsect1>
 263     <refsect1>
 264       <title>Examples</title>
 265       <screen>
 266         (setf *default-database-type* :mysql)
 267         => :mysql
 268         (initialize-database-type)
 269         => t
 270       </screen>
 271     </refsect1>
 272     <refsect1>
 273       <title>Affected By</title>
 274       <para>None.</para>
 275     </refsect1>
 276     <refsect1>
 277       <title>See Also</title>
 278       <para>None.</para>
 279     </refsect1>
 280     <refsect1>
 281       <title>Notes</title>
 282       <para>None.</para>
 283     </refsect1>
 284   </refentry>
 285
 286   <refentry id="initialized-database-types">
 287     <refnamediv>
 288       <refname>*INITIALIZED-DATABASE-TYPES*</refname>
 289       <refpurpose>List of all initialized database types</refpurpose>
 290       <refclass>Variable</refclass>
 291     </refnamediv>
 292     <refsect1>
 293       <title>Value Type</title>
 294       <para>A list of all initialized database types, each of which
 295       represented by it's corresponding keyword.</para>
 296     </refsect1>
 297     <refsect1>
 298       <title>Initial Value</title>
 299       <para><symbol>nil</symbol></para>
 300     </refsect1>
 301     <refsect1>
 302       <title>Description</title>
 303       <para>This variable is updated whenever
 304       <function>initialize-database-type</function> is called for a
 305       database type which hasn't already been initialized before,
 306       as determined by this variable.  In that case the keyword
 307       representing the database type is pushed onto the list
 308       stored in
 309       <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
 310       <caution>
 311         <para>Attempts to modify the value of this variable will
 312         result in undefined behaviour.</para>
 313       </caution>
 314     </refsect1>
 315     <refsect1>
 316       <title>Examples</title>
 317       <screen>
 318         (setf *default-database-type* :mysql)
 319         => :mysql
 320         (initialize-database-type)
 321         => t
 322         *initialized-database-types*
 323         => (:MYSQL)
 324       </screen>
 325     </refsect1>
 326     <refsect1>
 327       <title>Affected By</title>
 328       <para>
 329         <simplelist>
 330           <member><function>initialize-database-type</function></member>
 331         </simplelist>
 332       </para>
 333     </refsect1>
 334     <refsect1>
 335       <title>See Also</title>
 336       <para>None.</para>
 337     </refsect1>
 338     <refsect1>
 339       <title>Notes</title>
 340       <para>Direct access to this variable is primarily provided
 341       because of compatibility with Harlequin's <application>Common
 342       SQL</application>.</para>
 343     </refsect1>
 344   </refentry>
 345
 346   <refentry id="connect">
 347     <refnamediv>
 348       <refname>CONNECT</refname>
 349       <refpurpose><!-- purpose --></refpurpose>
 350       <refclass>Function</refclass>
 351     </refnamediv>
 352     <refsect1>
 353       <title>Syntax</title>
 354       <synopsis>
 355       <function> (CONNECT CONNECTION-SPEC &amp;KEY (IF-EXISTS *CONNECT-IF-EXISTS*) (MAKE-DEFAULT T) (POOL NIL) (DATABASE-TYPE *DEFAULT-DATABASE-TYPE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 356     </refsect1>
 357     <refsect1>
 358       <title>Arguments and Values</title>
 359       <variablelist>
 360         <!-- arguments and values -->
 361       </variablelist>
 362     </refsect1>
 363     <refsect1>
 364       <title>Description</title>
 365       <para>Connects to a database of the supplied DATABASE-TYPE
 366       which defaults to *DEFAULT-DATABASE-TYPE*, using the
 367       type-specific connection specification CONNECTION-SPEC. The
 368       value of IF-EXISTS, which defaults to *CONNECT-IF-EXISTS*,
 369       determines what happens if a connection to the database
 370       specified by CONNECTION-SPEC is already established.  A value
 371       of :new means create a new connection.  A value of :warn-new
 372       means warn the user and create a new connect.  A value of
 373       :warn-old means warn the user and use the old connection.  A
 374       value of :error means fail, notifying the user.  A value of
 375       :old means return the old connection.  MAKE-DEFAULT is t by
 376       default which means that *DEFAULT-DATABASE* is set to the new
 377       connection, otherwise *DEFAULT-DATABASE* is not changed. If
 378       POOL is t the connection will be taken from the general pool,
 379       if POOL is a CONN-POOL object the connection will be taken
 380       from this pool.
 381       </para>
 382     </refsect1>
 383     <refsect1>
 384       <title>Examples</title>
 385       <screen>
 386         <!-- examples -->
 387       </screen>
 388     </refsect1>
 389     <refsect1>
 390       <title>Side Effects</title>
 391       <para>
 392         <!-- side effects -->
 393       </para>
 394     </refsect1>
 395     <refsect1>
 396       <title>Affected by</title>
 397       <para>
 398         <simplelist>
 399           <!-- affected by -->
 400         </simplelist>
 401       </para>
 402     </refsect1>
 403     <refsect1>
 404       <title>Exceptional Situations</title>
 405       <para>
 406         <!-- execeptional situations -->
 407       </para>
 408     </refsect1>
 409     <refsect1>
 410       <title>See Also</title>
 411       <para>
 412         <simplelist>
 413           <!-- see also list here -->
 414         </simplelist>
 415       </para>
 416     </refsect1>
 417     <refsect1>
 418       <title>Notes</title>
 419       <para>
 420         <!-- notes here -->
 421       </para>
 422     </refsect1>
 423   </refentry>
 424
 425   <refentry id="connected-databases">
 426     <refnamediv>
 427       <refname>CONNECTED-DATABASES</refname>
 428       <refpurpose><!-- purpose --></refpurpose>
 429       <refclass>Function</refclass>
 430     </refnamediv>
 431     <refsect1>
 432       <title>Syntax</title>
 433       <synopsis>
 434       <function> (CONNECTED-DATABASES) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 435     </refsect1>
 436     <refsect1>
 437       <title>Arguments and Values</title>
 438       <variablelist>
 439         <!-- arguments and values -->
 440       </variablelist>
 441     </refsect1>
 442     <refsect1>
 443       <title>Description</title>
 444       <para>Returns the list of active database objects.
 445       </para>
 446     </refsect1>
 447     <refsect1>
 448       <title>Examples</title>
 449       <screen>
 450         <!-- examples -->
 451       </screen>
 452     </refsect1>
 453     <refsect1>
 454       <title>Side Effects</title>
 455       <para>
 456         <!-- side effects -->
 457       </para>
 458     </refsect1>
 459     <refsect1>
 460       <title>Affected by</title>
 461       <para>
 462         <simplelist>
 463           <!-- affected by -->
 464         </simplelist>
 465       </para>
 466     </refsect1>
 467     <refsect1>
 468       <title>Exceptional Situations</title>
 469       <para>
 470         <!-- execeptional situations -->
 471       </para>
 472     </refsect1>
 473     <refsect1>
 474       <title>See Also</title>
 475       <para>
 476         <simplelist>
 477           <!-- see also -->
 478         </simplelist>
 479       </para>
 480     </refsect1>
 481     <refsect1>
 482       <title>Notes</title>
 483       <para>
 484         <!-- notes -->
 485       </para>
 486     </refsect1>
 487   </refentry>
 488
 489   <refentry id="create-database">
 490     <refnamediv>
 491       <refname>CREATE-DATABASE</refname>
 492       <refpurpose><!-- purpose --></refpurpose>
 493       <refclass>Function</refclass>
 494     </refnamediv>
 495     <refsect1>
 496       <title>Syntax</title>
 497       <synopsis>
 498       <function> (CREATE-DATABASE CONNECTION-SPEC &amp;KEY DATABASE-TYPE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 499     </refsect1>
 500     <refsect1>
 501       <title>Arguments and Values</title>
 502       <variablelist>
 503         <!-- arguments and values -->
 504       </variablelist>
 505     </refsect1>
 506     <refsect1>
 507       <title>Description</title>
 508       <para>
 509         <!-- description -->
 510       </para>
 511     </refsect1>
 512     <refsect1>
 513       <title>Examples</title>
 514       <screen>
 515         <!-- examples -->
 516       </screen>
 517     </refsect1>
 518     <refsect1>
 519       <title>Side Effects</title>
 520       <para>
 521         <!-- side effects -->
 522       </para>
 523     </refsect1>
 524     <refsect1>
 525       <title>Affected by</title>
 526       <para>
 527         <simplelist>
 528           <!-- affected by -->
 529         </simplelist>
 530       </para>
 531     </refsect1>
 532     <refsect1>
 533       <title>Exceptional Situations</title>
 534       <para>
 535         <!-- execeptional situations -->
 536       </para>
 537     </refsect1>
 538     <refsect1>
 539       <title>See Also</title>
 540       <para>
 541         <simplelist>
 542           <!-- see also list here -->
 543         </simplelist>
 544       </para>
 545     </refsect1>
 546     <refsect1>
 547       <title>Notes</title>
 548       <para>
 549         <!-- notes here -->
 550       </para>
 551     </refsect1>
 552   </refentry>
 553
 554   <refentry id="database-name">
 555     <refnamediv>
 556       <refname>DATABASE-NAME</refname>
 557       <refpurpose><!-- purpose --></refpurpose>
 558       <refclass>Function</refclass>
 559     </refnamediv>
 560     <refsect1>
 561       <title>Syntax</title>
 562       <synopsis>
 563       <function> (DATABASE-NAME (OBJ DATABASE)) [reader]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 564     </refsect1>
 565     <refsect1>
 566       <title>Arguments and Values</title>
 567       <variablelist>
 568         <!-- arguments and values -->
 569       </variablelist>
 570     </refsect1>
 571     <refsect1>
 572       <title>Description</title>
 573       <para>
 574         "Returns the name of DATABASE."
 575       </para>
 576     </refsect1>
 577     <refsect1>
 578       <title>Examples</title>
 579       <screen>
 580         <!-- examples -->
 581       </screen>
 582     </refsect1>
 583     <refsect1>
 584       <title>Side Effects</title>
 585       <para>
 586         <!-- side effects -->
 587       </para>
 588     </refsect1>
 589     <refsect1>
 590       <title>Affected by</title>
 591       <para>
 592         <simplelist>
 593           <!-- affected by -->
 594         </simplelist>
 595       </para>
 596     </refsect1>
 597     <refsect1>
 598       <title>Exceptional Situations</title>
 599       <para>
 600         <!-- execeptional situations -->
 601       </para>
 602     </refsect1>
 603     <refsect1>
 604       <title>See Also</title>
 605       <para>
 606         <simplelist>
 607           <!-- see also list here -->
 608         </simplelist>
 609       </para>
 610     </refsect1>
 611     <refsect1>
 612       <title>Notes</title>
 613       <para>
 614         <!-- notes here -->
 615       </para>
 616     </refsect1>
 617   </refentry>
 618
 619   <refentry id="database-type">
 620     <refnamediv>
 621       <refname>DATABASE-TYPE</refname>
 622       <refpurpose><!-- purpose --></refpurpose>
 623       <refclass>Function</refclass>
 624     </refnamediv>
 625     <refsect1>
 626       <title>Syntax</title>
 627       <synopsis>
 628       <function> (DATABASE-TYPE (OBJ DATABASE)) [reader]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 629     </refsect1>
 630     <refsect1>
 631       <title>Arguments and Values</title>
 632       <variablelist>
 633         <!-- arguments and values -->
 634       </variablelist>
 635     </refsect1>
 636     <refsect1>
 637       <title>Description</title>
 638       <para>
 639         "Returns the type of DATABASE."
 640       </para>
 641     </refsect1>
 642     <refsect1>
 643       <title>Examples</title>
 644       <screen>
 645         <!-- examples -->
 646       </screen>
 647     </refsect1>
 648     <refsect1>
 649       <title>Side Effects</title>
 650       <para>
 651         <!-- side effects -->
 652       </para>
 653     </refsect1>
 654     <refsect1>
 655       <title>Affected by</title>
 656       <para>
 657         <simplelist>
 658           <!-- affected by -->
 659         </simplelist>
 660       </para>
 661     </refsect1>
 662     <refsect1>
 663       <title>Exceptional Situations</title>
 664       <para>
 665         <!-- execeptional situations -->
 666       </para>
 667     </refsect1>
 668     <refsect1>
 669       <title>See Also</title>
 670       <para>
 671         <simplelist>
 672           <!-- see also list here -->
 673         </simplelist>
 674       </para>
 675     </refsect1>
 676     <refsect1>
 677       <title>Notes</title>
 678       <para>
 679         <!-- notes here -->
 680       </para>
 681     </refsect1>
 682   </refentry>
 683
 684   <refentry id="destroy-database">
 685     <refnamediv>
 686       <refname>DESTROY-DATABASE</refname>
 687       <refpurpose><!-- purpose --></refpurpose>
 688       <refclass>Function</refclass>
 689     </refnamediv>
 690     <refsect1>
 691       <title>Syntax</title>
 692       <synopsis>
 693       <function> (DESTROY-DATABASE CONNECTION-SPEC &amp;KEY DATABASE-TYPE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 694     </refsect1>
 695     <refsect1>
 696       <title>Arguments and Values</title>
 697       <variablelist>
 698         <!-- arguments and values -->
 699       </variablelist>
 700     </refsect1>
 701     <refsect1>
 702       <title>Description</title>
 703       <para>
 704         <!-- description -->
 705       </para>
 706     </refsect1>
 707     <refsect1>
 708       <title>Examples</title>
 709       <screen>
 710         <!-- examples -->
 711       </screen>
 712     </refsect1>
 713     <refsect1>
 714       <title>Side Effects</title>
 715       <para>
 716         <!-- side effects -->
 717       </para>
 718     </refsect1>
 719     <refsect1>
 720       <title>Affected by</title>
 721       <para>
 722         <simplelist>
 723           <!-- affected by -->
 724         </simplelist>
 725       </para>
 726     </refsect1>
 727     <refsect1>
 728       <title>Exceptional Situations</title>
 729       <para>
 730         <!-- execeptional situations -->
 731       </para>
 732     </refsect1>
 733     <refsect1>
 734       <title>See Also</title>
 735       <para>
 736         <simplelist>
 737           <!-- see also list here -->
 738         </simplelist>
 739       </para>
 740     </refsect1>
 741     <refsect1>
 742       <title>Notes</title>
 743       <para>
 744         <!-- notes here -->
 745       </para>
 746     </refsect1>
 747   </refentry>
 748
 749   <refentry id="disconnect">
 750     <refnamediv>
 751       <refname>DISCONNECT</refname>
 752       <refpurpose><!-- purpose --></refpurpose>
 753       <refclass>Function</refclass>
 754     </refnamediv>
 755     <refsect1>
 756       <title>Syntax</title>
 757       <synopsis>
 758       <function> (DISCONNECT &amp;KEY (DATABASE *DEFAULT-DATABASE*) (ERROR NIL)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 759     </refsect1>
 760     <refsect1>
 761       <title>Arguments and Values</title>
 762       <variablelist>
 763         <!-- arguments and values -->
 764       </variablelist>
 765     </refsect1>
 766     <refsect1>
 767       <title>Description</title>
 768       <para>Closes the connection to DATABASE and resets
 769       *DEFAULT-DATABASE* if that database was
 770       disconnected. If DATABASE is a database instance, this
 771       object is closed. If DATABASE is a string, then a
 772       connected database whose name matches DATABASE is
 773       sought in the list of connected databases. If no
 774       matching database is found and ERROR and DATABASE are
 775       both non-nil an error is signaled, otherwise nil is
 776       returned. If the database is from a pool it will be
 777       released to this pool.
 778       </para>
 779     </refsect1>
 780     <refsect1>
 781       <title>Examples</title>
 782       <screen>
 783         <!-- examples -->
 784       </screen>
 785     </refsect1>
 786     <refsect1>
 787       <title>Side Effects</title>
 788       <para>
 789         <!-- side effects -->
 790       </para>
 791     </refsect1>
 792     <refsect1>
 793       <title>Affected by</title>
 794       <para>
 795         <simplelist>
 796           <!-- affected by -->
 797         </simplelist>
 798       </para>
 799     </refsect1>
 800     <refsect1>
 801       <title>Exceptional Situations</title>
 802       <para>
 803         <!-- execeptional situations -->
 804       </para>
 805     </refsect1>
 806     <refsect1>
 807       <title>See Also</title>
 808       <para>
 809         <simplelist>
 810           <!-- see also -->
 811         </simplelist>
 812       </para>
 813     </refsect1>
 814     <refsect1>
 815       <title>Notes</title>
 816       <para>
 817         <!-- notes -->
 818       </para>
 819     </refsect1>
 820   </refentry>
 821
 822   <refentry id="disconnect-pooled">
 823     <refnamediv>
 824       <refname>DISCONNECT-POOLED</refname>
 825       <refpurpose><!-- purpose --></refpurpose>
 826       <refclass>Function</refclass>
 827     </refnamediv>
 828     <refsect1>
 829       <title>Syntax</title>
 830       <synopsis>
 831       <function> (DISCONNECT-POOLED &amp;OPTIONAL CLEAR) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 832     </refsect1>
 833     <refsect1>
 834       <title>Arguments and Values</title>
 835       <variablelist>
 836         <!-- arguments and values -->
 837       </variablelist>
 838     </refsect1>
 839     <refsect1>
 840       <title>Description</title>
 841       <para>Disconnects all connections in the pool.
 842       </para>
 843     </refsect1>
 844     <refsect1>
 845       <title>Examples</title>
 846       <screen>
 847         <!-- examples -->
 848       </screen>
 849     </refsect1>
 850     <refsect1>
 851       <title>Side Effects</title>
 852       <para>
 853         <!-- side effects -->
 854       </para>
 855     </refsect1>
 856     <refsect1>
 857       <title>Affected by</title>
 858       <para>
 859         <simplelist>
 860           <!-- affected by -->
 861         </simplelist>
 862       </para>
 863     </refsect1>
 864     <refsect1>
 865       <title>Exceptional Situations</title>
 866       <para>
 867         <!-- execeptional situations -->
 868       </para>
 869     </refsect1>
 870     <refsect1>
 871       <title>See Also</title>
 872       <para>
 873         <simplelist>
 874           <!-- see also -->
 875         </simplelist>
 876       </para>
 877     </refsect1>
 878     <refsect1>
 879       <title>Notes</title>
 880       <para>
 881         <!-- notes -->
 882       </para>
 883     </refsect1>
 884   </refentry>
 885
 886
 887   <refentry id="find-database">
 888     <refnamediv>
 889       <refname>FIND-DATABASE</refname>
 890       <refpurpose><!-- purpose --></refpurpose>
 891       <refclass>Function</refclass>
 892     </refnamediv>
 893     <refsect1>
 894       <title>Syntax</title>
 895       <synopsis>
 896       <function> (FIND-DATABASE DATABASE &amp;KEY (ERRORP T) (DB-TYPE NIL)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 897     </refsect1>
 898     <refsect1>
 899       <title>Arguments and Values</title>
 900       <variablelist>
 901         <!-- arguments and values -->
 902       </variablelist>
 903     </refsect1>
 904     <refsect1>
 905       <title>Description</title>
 906       <para>Returns the connected databases of type
 907       DB-TYPE whose names match the string DATABASE. If
 908       DATABASE is a database object, it is returned. If
 909       DB-TYPE is nil all databases matching the string
 910       DATABASE are considered.  If no matching databases are
 911       found and ERRORP is nil then nil is returned. If
 912       ERRORP is nil and one or more matching databases are
 913       found, then the most recently connected database is
 914       returned as a first value and the number of matching
 915       databases is returned as a second value. If no, or
 916       more than one, matching databases are found and ERRORP
 917       is true, an error is signalled.
 918       </para>
 919     </refsect1>
 920     <refsect1>
 921       <title>Examples</title>
 922       <screen>
 923         <!-- examples -->
 924       </screen>
 925     </refsect1>
 926     <refsect1>
 927       <title>Side Effects</title>
 928       <para>
 929         <!-- side effects -->
 930       </para>
 931     </refsect1>
 932     <refsect1>
 933       <title>Affected by</title>
 934       <para>
 935         <simplelist>
 936           <!-- affected by -->
 937         </simplelist>
 938       </para>
 939     </refsect1>
 940     <refsect1>
 941       <title>Exceptional Situations</title>
 942       <para>
 943         <!-- execeptional situations -->
 944       </para>
 945     </refsect1>
 946     <refsect1>
 947       <title>See Also</title>
 948       <para>
 949         <simplelist>
 950           <!-- see also -->
 951         </simplelist>
 952       </para>
 953     </refsect1>
 954     <refsect1>
 955       <title>Notes</title>
 956       <para>
 957         <!-- notes -->
 958       </para>
 959     </refsect1>
 960   </refentry>
 961
 962   <refentry id="initialize-database-type">
 963     <refnamediv>
 964       <refname>INITIALIZE-DATABASE-TYPE</refname>
 965       <refpurpose><!-- purpose --></refpurpose>
 966       <refclass>Function</refclass>
 967     </refnamediv>
 968     <refsect1>
 969       <title>Syntax</title>
 970       <synopsis>
 971       <function> (INITIALIZE-DATABASE-TYPE &amp;KEY (DATABASE-TYPE *DEFAULT-DATABASE-TYPE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 972     </refsect1>
 973     <refsect1>
 974       <title>Arguments and Values</title>
 975       <variablelist>
 976         <!-- arguments and values -->
 977       </variablelist>
 978     </refsect1>
 979     <refsect1>
 980       <title>Description</title>
 981       <para>Initializes the supplied DATABASE-TYPE, if it
 982       is not already initialized, as indicated by
 983       *INITIALIZED-DATABASE-TYPES* and returns
 984       DATABASE-TYPE. *DEFAULT-DATABASE-TYPE* is set to
 985       DATABASE-TYPE and, if DATABASE-TYPE has not been
 986       initialised, it is added to
 987       *INITIALIZED-DATABASE-TYPES*.
 988       </para>
 989     </refsect1>
 990     <refsect1>
 991       <title>Examples</title>
 992       <screen>
 993         <!-- examples -->
 994       </screen>
 995     </refsect1>
 996     <refsect1>
 997       <title>Side Effects</title>
 998       <para>
 999         <!-- side effects -->
1000       </para>
1001     </refsect1>
1002     <refsect1>
1003       <title>Affected by</title>
1004       <para>
1005         <simplelist>
1006           <!-- affected by -->
1007         </simplelist>
1008       </para>
1009     </refsect1>
1010     <refsect1>
1011       <title>Exceptional Situations</title>
1012       <para>
1013         <!-- execeptional situations -->
1014       </para>
1015     </refsect1>
1016     <refsect1>
1017       <title>See Also</title>
1018       <para>
1019         <simplelist>
1020           <!-- see also -->
1021         </simplelist>
1022       </para>
1023     </refsect1>
1024     <refsect1>
1025       <title>Notes</title>
1026       <para>
1027         <!-- notes -->
1028       </para>
1029     </refsect1>
1030   </refentry>
1031
1032   <refentry id="list-databases">
1033     <refnamediv>
1034       <refname>LIST-DATABASES</refname>
1035       <refpurpose><!-- purpose --></refpurpose>
1036       <refclass>Function</refclass>
1037     </refnamediv>
1038     <refsect1>
1039       <title>Syntax</title>
1040       <synopsis>
1041       <function> (LIST-DATABASES CONNECTION-SPEC &amp;KEY DATABASE-TYPE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1042     </refsect1>
1043     <refsect1>
1044       <title>Arguments and Values</title>
1045       <variablelist>
1046         <!-- arguments and values -->
1047       </variablelist>
1048     </refsect1>
1049     <refsect1>
1050       <title>Description</title>
1051       <para>
1052         <!-- description -->
1053       </para>
1054     </refsect1>
1055     <refsect1>
1056       <title>Examples</title>
1057       <screen>
1058         <!-- examples -->
1059       </screen>
1060     </refsect1>
1061     <refsect1>
1062       <title>Side Effects</title>
1063       <para>
1064         <!-- side effects -->
1065       </para>
1066     </refsect1>
1067     <refsect1>
1068       <title>Affected by</title>
1069       <para>
1070         <simplelist>
1071           <!-- affected by -->
1072         </simplelist>
1073       </para>
1074     </refsect1>
1075     <refsect1>
1076       <title>Exceptional Situations</title>
1077       <para>
1078         <!-- execeptional situations -->
1079       </para>
1080     </refsect1>
1081     <refsect1>
1082       <title>See Also</title>
1083       <para>
1084         <simplelist>
1085           <!-- see also list here -->
1086         </simplelist>
1087       </para>
1088     </refsect1>
1089     <refsect1>
1090       <title>Notes</title>
1091       <para>
1092         <!-- notes here -->
1093       </para>
1094     </refsect1>
1095   </refentry>
1096
1097   <refentry id="probe-database">
1098     <refnamediv>
1099       <refname>PROBE-DATABASE</refname>
1100       <refpurpose><!-- purpose --></refpurpose>
1101       <refclass>Function</refclass>
1102     </refnamediv>
1103     <refsect1>
1104       <title>Syntax</title>
1105       <synopsis>
1106       <function> (PROBE-DATABASE CONNECTION-SPEC &amp;KEY DATABASE-TYPE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1107     </refsect1>
1108     <refsect1>
1109       <title>Arguments and Values</title>
1110       <variablelist>
1111         <!-- arguments and values -->
1112       </variablelist>
1113     </refsect1>
1114     <refsect1>
1115       <title>Description</title>
1116       <para>
1117         <!-- description -->
1118       </para>
1119     </refsect1>
1120     <refsect1>
1121       <title>Examples</title>
1122       <screen>
1123         <!-- examples -->
1124       </screen>
1125     </refsect1>
1126     <refsect1>
1127       <title>Side Effects</title>
1128       <para>
1129         <!-- side effects -->
1130       </para>
1131     </refsect1>
1132     <refsect1>
1133       <title>Affected by</title>
1134       <para>
1135         <simplelist>
1136           <!-- affected by -->
1137         </simplelist>
1138       </para>
1139     </refsect1>
1140     <refsect1>
1141       <title>Exceptional Situations</title>
1142       <para>
1143         <!-- execeptional situations -->
1144       </para>
1145     </refsect1>
1146     <refsect1>
1147       <title>See Also</title>
1148       <para>
1149         <simplelist>
1150           <!-- see also list here -->
1151         </simplelist>
1152       </para>
1153     </refsect1>
1154     <refsect1>
1155       <title>Notes</title>
1156       <para>
1157         <!-- notes here -->
1158       </para>
1159     </refsect1>
1160   </refentry>
1161
1162   <refentry id="reconnect">
1163     <refnamediv>
1164       <refname>RECONNECT</refname>
1165       <refpurpose><!-- purpose --></refpurpose>
1166       <refclass>Function</refclass>
1167     </refnamediv>
1168     <refsect1>
1169       <title>Syntax</title>
1170       <synopsis>
1171       <function> (RECONNECT &amp;KEY (DATABASE *DEFAULT-DATABASE*) (ERROR NIL) (FORCE T)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1172     </refsect1>
1173     <refsect1>
1174       <title>Arguments and Values</title>
1175       <variablelist>
1176         <!-- arguments and values -->
1177       </variablelist>
1178     </refsect1>
1179     <refsect1>
1180       <title>Description</title>
1181       <para>Reconnects DATABASE which defaults to
1182       *DEFAULT-DATABASE* to the underlying database
1183       management system. On success, t is returned and the
1184       variable *DEFAULT-DATABASE* is set to the newly
1185       reconnected database. If DATABASE is a database
1186       instance, this object is closed. If DATABASE is a
1187       string, then a connected database whose name matches
1188       DATABASE is sought in the list of connected
1189       databases. If no matching database is found and ERROR
1190       and DATABASE are both non-nil an error is signaled,
1191       otherwise nil is returned. When the current database
1192       connection cannot be closed, if FORCE is non-nil, as
1193       it is by default, the connection is closed and errors
1194       are suppressed. If force is nil and the database
1195       connection cannot be closed, an error is
1196       signalled.
1197       </para>
1198     </refsect1>
1199     <refsect1>
1200       <title>Examples</title>
1201       <screen>
1202         <!-- examples -->
1203       </screen>
1204     </refsect1>
1205     <refsect1>
1206       <title>Side Effects</title>
1207       <para>
1208         <!-- side effects -->
1209       </para>
1210     </refsect1>
1211     <refsect1>
1212       <title>Affected by</title>
1213       <para>
1214         <simplelist>
1215           <!-- affected by -->
1216         </simplelist>
1217       </para>
1218     </refsect1>
1219     <refsect1>
1220       <title>Exceptional Situations</title>
1221       <para>
1222         <!-- execeptional situations -->
1223       </para>
1224     </refsect1>
1225     <refsect1>
1226       <title>See Also</title>
1227       <para>
1228         <simplelist>
1229           <!-- see also -->
1230         </simplelist>
1231       </para>
1232     </refsect1>
1233     <refsect1>
1234       <title>Notes</title>
1235       <para>
1236         <!-- notes -->
1237       </para>
1238     </refsect1>
1239   </refentry>
1240
1241   <refentry id="status">
1242     <refnamediv>
1243       <refname>STATUS</refname>
1244       <refpurpose><!-- purpose --></refpurpose>
1245       <refclass>Function</refclass>
1246     </refnamediv>
1247     <refsect1>
1248       <title>Syntax</title>
1249       <synopsis>
1250       <function> (STATUS &amp;OPTIONAL FULL) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1251     </refsect1>
1252     <refsect1>
1253       <title>Arguments and Values</title>
1254       <variablelist>
1255         <!-- arguments and values -->
1256       </variablelist>
1257     </refsect1>
1258     <refsect1>
1259       <title>Description</title>
1260       <para>Prints information about the currently connected databases to
1261       *STANDARD-OUTPUT*. The argument FULL is nil by default and a
1262       value of t means that more detailed information about each
1263       database is printed.
1264       </para>
1265     </refsect1>
1266     <refsect1>
1267       <title>Examples</title>
1268       <screen>
1269         <!-- examples -->
1270       </screen>
1271     </refsect1>
1272     <refsect1>
1273       <title>Side Effects</title>
1274       <para>
1275         <!-- side effects -->
1276       </para>
1277     </refsect1>
1278     <refsect1>
1279       <title>Affected by</title>
1280       <para>
1281         <simplelist>
1282           <!-- affected by -->
1283         </simplelist>
1284       </para>
1285     </refsect1>
1286     <refsect1>
1287       <title>Exceptional Situations</title>
1288       <para>
1289         <!-- execeptional situations -->
1290       </para>
1291     </refsect1>
1292     <refsect1>
1293       <title>See Also</title>
1294       <para>
1295         <simplelist>
1296           <!-- see also -->
1297         </simplelist>
1298       </para>
1299     </refsect1>
1300     <refsect1>
1301       <title>Notes</title>
1302       <para>
1303         <!-- notes -->
1304       </para>
1305     </refsect1>
1306   </refentry>
1307
1308   <refentry id="truncate-database">
1309     <refnamediv>
1310       <refname>TRUNCATE-DATABASE</refname>
1311       <refpurpose><!-- purpose --></refpurpose>
1312       <refclass>Function</refclass>
1313     </refnamediv>
1314     <refsect1>
1315       <title>Syntax</title>
1316       <synopsis>
1317       <function> (TRUNCATE-DATABASE &amp;KEY (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1318     </refsect1>
1319     <refsect1>
1320       <title>Arguments and Values</title>
1321       <variablelist>
1322         <!-- arguments and values -->
1323       </variablelist>
1324     </refsect1>
1325     <refsect1>
1326       <title>Description</title>
1327       <para>
1328         <!-- description -->
1329       </para>
1330     </refsect1>
1331     <refsect1>
1332       <title>Examples</title>
1333       <screen>
1334         <!-- examples -->
1335       </screen>
1336     </refsect1>
1337     <refsect1>
1338       <title>Side Effects</title>
1339       <para>
1340         <!-- side effects -->
1341       </para>
1342     </refsect1>
1343     <refsect1>
1344       <title>Affected by</title>
1345       <para>
1346         <simplelist>
1347           <!-- affected by -->
1348         </simplelist>
1349       </para>
1350     </refsect1>
1351     <refsect1>
1352       <title>Exceptional Situations</title>
1353       <para>
1354         <!-- execeptional situations -->
1355       </para>
1356     </refsect1>
1357     <refsect1>
1358       <title>See Also</title>
1359       <para>
1360         <simplelist>
1361           <!-- see also list here -->
1362         </simplelist>
1363       </para>
1364     </refsect1>
1365     <refsect1>
1366       <title>Notes</title>
1367       <para>
1368         <!-- notes here -->
1369       </para>
1370     </refsect1>
1371   </refentry>
1372
1373   <refentry id="with-database">
1374     <refnamediv>
1375       <refname>WITH-DATABASE</refname>
1376       <refpurpose><!-- purpose --></refpurpose>
1377       <refclass>Function</refclass>
1378     </refnamediv>
1379     <refsect1>
1380       <title>Syntax</title>
1381       <synopsis>
1382       <function> (WITH-DATABASE DB-VAR CONNECTION-SPEC &amp;REST CONNECT-ARGS &amp;BODY BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1383     </refsect1>
1384     <refsect1>
1385       <title>Arguments and Values</title>
1386       <variablelist>
1387         <!-- arguments and values -->
1388       </variablelist>
1389     </refsect1>
1390     <refsect1>
1391       <title>Description</title>
1392       <para>Evaluate the body in an environment, where
1393       `db-var' is bound to the database connection given by
1394       `connection-spec' and `connect-args'.  The connection
1395       is automatically closed or released to the pool on
1396       exit from the body.
1397       </para>
1398     </refsect1>
1399     <refsect1>
1400       <title>Examples</title>
1401       <screen>
1402         <!-- examples -->
1403       </screen>
1404     </refsect1>
1405     <refsect1>
1406       <title>Side Effects</title>
1407       <para>
1408         <!-- side effects -->
1409       </para>
1410     </refsect1>
1411     <refsect1>
1412       <title>Affected by</title>
1413       <para>
1414         <simplelist>
1415           <!-- affected by -->
1416         </simplelist>
1417       </para>
1418     </refsect1>
1419     <refsect1>
1420       <title>Exceptional Situations</title>
1421       <para>
1422         <!-- execeptional situations -->
1423       </para>
1424     </refsect1>
1425     <refsect1>
1426       <title>See Also</title>
1427       <para>
1428         <simplelist>
1429           <!-- see also -->
1430         </simplelist>
1431       </para>
1432     </refsect1>
1433     <refsect1>
1434       <title>Notes</title>
1435       <para>
1436         <!-- notes -->
1437       </para>
1438     </refsect1>
1439   </refentry>
1440
1441   <refentry id="with-default-database">
1442     <refnamediv>
1443       <refname>WITH-DEFAULT-DATABASE</refname>
1444       <refpurpose><!-- purpose --></refpurpose>
1445       <refclass>Function</refclass>
1446     </refnamediv>
1447     <refsect1>
1448       <title>Syntax</title>
1449       <synopsis>
1450       <function> (WITH-DEFAULT-DATABASE DATABASE &amp;REST BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1451     </refsect1>
1452     <refsect1>
1453       <title>Arguments and Values</title>
1454       <variablelist>
1455         <!-- arguments and values -->
1456       </variablelist>
1457     </refsect1>
1458     <refsect1>
1459       <title>Description</title>
1460       <para>Perform BODY with DATABASE bound as
1461       *default-database*.
1462       </para>
1463     </refsect1>
1464     <refsect1>
1465       <title>Examples</title>
1466       <screen>
1467         <!-- examples -->
1468       </screen>
1469     </refsect1>
1470     <refsect1>
1471       <title>Side Effects</title>
1472       <para>
1473         <!-- side effects -->
1474       </para>
1475     </refsect1>
1476     <refsect1>
1477       <title>Affected by</title>
1478       <para>
1479         <simplelist>
1480           <!-- affected by -->
1481         </simplelist>
1482       </para>
1483     </refsect1>
1484     <refsect1>
1485       <title>Exceptional Situations</title>
1486       <para>
1487         <!-- execeptional situations -->
1488       </para>
1489     </refsect1>
1490     <refsect1>
1491       <title>See Also</title>
1492       <para>
1493         <simplelist>
1494           <!-- see also -->
1495         </simplelist>
1496       </para>
1497     </refsect1>
1498     <refsect1>
1499       <title>Notes</title>
1500       <para>
1501         <!-- notes -->
1502       </para>
1503     </refsect1>
1504   </refentry>
1505
1506
1507 </reference>