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