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