doc/ref.xml

   1 <?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
   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.xml">
   5 %myents;
   6 ]>
   7
   8 <reference>
   9   <title><symbol>CLSQL</symbol></title>
  10   <partintro>
  11     <para>This part gives a reference to all the symbols exported
  12       from the package <symbol>CLSQL-SYS</symbol>, which are also
  13       re-exported from the package <symbol>CLSQL</symbol>.  These
  14       symbols constitute the normal user-interface of
  15       &clsql;.</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         <programlisting>
 559 (setf *default-database-type* :mysql)
 560 => :mysql
 561 (initialize-database-type)
 562 => t
 563         </programlisting>
 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         <programlisting>
 610 (setf *default-database-type* :mysql)
 611 => :mysql
 612 (initialize-database-type)
 613 => t
 614 *initialized-database-types*
 615 => (:MYSQL)
 616         </programlisting>
 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         <programlisting>
 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         </programlisting>
 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         <programlisting>
 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         </programlisting>
 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         <programlisting>
 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         </programlisting>
 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         <programlisting>
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         </programlisting>
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         <programlisting>
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         </programlisting>
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             </listitem>
1332           </varlistentry>
1333           <varlistentry>
1334             <term><returnvalue>database</returnvalue></term>
1335             <listitem>
1336               <para>The database object representing the connection.</para>
1337             </listitem>
1338           </varlistentry>
1339         </variablelist>
1340       </refsect1>
1341       <refsect1>
1342         <title>Description</title>
1343         <para>This function takes a connection specification and
1344           a database type and creates a connection to the database
1345           specified by those.  The type and structure of the
1346           connection specification depend on the database type.</para>
1347         <para>The parameter <parameter>if-exists</parameter> specifies
1348           what to do if a connection to the database specified exists
1349           already, which is checked by calling
1350           <function>find-database</function> on the database name
1351           returned by <function>database-name-from-spec</function>
1352           when called with the <parameter>connection-spec</parameter>
1353           and <parameter>database-type</parameter> parameters. The
1354           possible values of <parameter>if-exists</parameter> are:
1355           <variablelist>
1356             <varlistentry>
1357               <term><symbol>:new</symbol></term>
1358               <listitem>
1359                 <para>Go ahead and create a new connection.</para>
1360               </listitem>
1361             </varlistentry>
1362             <varlistentry>
1363               <term><symbol>:warn-new</symbol></term>
1364               <listitem>
1365                 <para>This is just like <symbol>:new</symbol>, but
1366                   also signals a warning of type
1367                   <errortype>clsql-exists-warning</errortype>,
1368                   indicating the old and newly created
1369                   databases.</para>
1370               </listitem>
1371             </varlistentry>
1372             <varlistentry>
1373               <term><symbol>:error</symbol></term>
1374               <listitem>
1375                 <para>This will cause <function>connect</function> to
1376                   signal a correctable error of type
1377                   <errortype>clsql-exists-error</errortype>.  The
1378                   user may choose to proceed, either by indicating
1379                   that a new connection shall be created, via the
1380                   restart <symbol>create-new</symbol>, or by
1381                   indicating that the existing connection shall be
1382                   used, via the restart
1383                   <symbol>use-old</symbol>.</para>
1384               </listitem>
1385             </varlistentry>
1386             <varlistentry>
1387               <term><symbol>:old</symbol></term>
1388               <listitem>
1389                 <para>This will cause <function>connect</function> to
1390                   use an old connection if one exists.</para>
1391               </listitem>
1392             </varlistentry>
1393             <varlistentry>
1394               <term><symbol>:warn-old</symbol></term>
1395               <listitem>
1396                 <para>This is just like <symbol>:old</symbol>, but
1397                   also signals a warning of type
1398                   <errortype>clsql-exists-warning</errortype>,
1399                   indicating the old database used, via the slots
1400                   <symbol>old-db</symbol> and
1401                   <symbol>new-db</symbol></para>
1402               </listitem>
1403             </varlistentry>
1404           </variablelist>
1405         </para>
1406         <para>The database name of the returned database object will
1407           be the same under <function>string=</function> as that which
1408           would be returned by a call to
1409           <function>database-name-from-spec</function> with the given
1410           <parameter>connection-spec</parameter> and
1411           <parameter>database-type</parameter> parameters.</para>
1412       </refsect1>
1413       <refsect1>
1414         <title>Examples</title>
1415         <programlisting>
1416 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1417 => "dent/newesim/dent"
1418 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1419 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
1420 (database-name *)
1421 => "dent/newesim/dent"
1422
1423 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1424 >> In call to CONNECT:
1425 >>   There is an existing connection #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
1426 >>
1427 >> Restarts:
1428 >>   0: [CREATE-NEW] Create a new connection.
1429 >>   1: [USE-OLD   ] Use the existing connection.
1430 >>   2: [ABORT     ] Return to Top-Level.
1431 >>
1432 >> Debug  (type H for help)
1433 >>
1434 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
1435 >> Source:
1436 >> ; File: /prj/CLSQL/sql/sql.cl
1437 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
1438 >>               (CREATE-NEW NIL :REPORT "Create a new connection."
1439 >>                (SETQ RESULT #))
1440 >>               (USE-OLD NIL :REPORT "Use the existing connection."
1441 >>                (SETQ RESULT OLD-DB)))
1442 >> 0] 0
1443 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
1444         </programlisting>
1445       </refsect1>
1446       <refsect1>
1447         <title>Side Effects</title>
1448         <para>A database connection is established, and the resultant
1449           database object is registered, so as to appear in the list
1450           returned by <function>connected-databases</function>.</para>
1451       </refsect1>
1452       <refsect1>
1453         <title>Affected by</title>
1454         <para>
1455         <simplelist>
1456           <member><symbol>*default-database-type*</symbol></member>
1457           <member><symbol>*connect-if-exists*</symbol></member>
1458         </simplelist>
1459         </para>
1460       </refsect1>
1461       <refsect1>
1462         <title>Exceptional Situations</title>
1463         <para>If the connection specification is not syntactically or
1464           semantically correct for the given database type, an error
1465           of type <errortype>clsql-invalid-spec-error</errortype> is
1466           signalled.  If during the connection attempt an error is
1467           detected (e.g. because of permission problems, network
1468           trouble  or any other cause), an error of type
1469           <errortype>clsql-connect-error</errortype> is
1470           signalled.</para>
1471         <para>If a connection to the database specified by
1472           <parameter>connection-spec</parameter> exists already,
1473           conditions are signalled according to the
1474           <parameter>if-exists</parameter> parameter, as described
1475           above.</para>
1476       </refsect1>
1477       <refsect1>
1478         <title>See Also</title>
1479         <para>
1480         <simplelist>
1481           <member><function>connected-databases</function></member>
1482           <member><link linkend="disconnect"><function>disconnect</function></link></member>
1483         </simplelist>
1484         </para>
1485       </refsect1>
1486       <refsect1>
1487         <title>Notes</title>
1488         <para>None.</para>
1489       </refsect1>
1490     </refentry>
1491
1492     <refentry id="disconnect">
1493       <refnamediv>
1494         <refname>DISCONNECT</refname>
1495         <refpurpose>close a database connection</refpurpose>
1496         <refclass>Function</refclass>
1497       </refnamediv>
1498       <refsect1>
1499         <title>Syntax</title>
1500         <synopsis><function>disconnect</function> &amp;key <replaceable>database</replaceable> <replaceable>pool</replaceable> => <returnvalue>t</returnvalue></synopsis>
1501       </refsect1>
1502       <refsect1>
1503         <title>Arguments and Values</title>
1504         <variablelist>
1505           <varlistentry>
1506             <term><parameter>pool</parameter></term>
1507             <listitem>
1508               <para>A boolean flag indicating whether to put the database into a
1509 pool of opened databases. If &t;, rather than terminating the database connection, the
1510 connection is left open and the connection is placed into a pool of connections. Subsequent
1511 calls to <link linkend="connect"><function>connect</function></link> can then reuse this connection.
1512 The default is &nil;.
1513             </listitem>
1514           </varlistentry>
1515           <varlistentry>
1516             <term><parameter>database</parameter></term>
1517             <listitem>
1518               <para>The database to disconnect, which defaults to the
1519                 database indicated by
1520                 <symbol>*default-database*</symbol>.</para>
1521             </listitem>
1522           </varlistentry>
1523         </variablelist>
1524       </refsect1>
1525       <refsect1>
1526         <title>Description</title>
1527         <para>This function takes a <type>database</type> object as
1528           returned by <function>connect</function>, and closes the
1529           connection.  The class of the object passed is changed to
1530           <type>closed-database</type> after the disconnection
1531           succeeds,  thereby preventing further use of the object as
1532           an argument to &clsql; functions,
1533           with the exception of <function>database-name</function>.
1534           If the user does pass a  closed database object to any other
1535           &clsql; function, an error of type
1536           <errortype>clsql-closed-error</errortype> is
1537           signalled.</para>
1538       </refsect1>
1539       <refsect1>
1540         <title>Examples</title>
1541         <programlisting>
1542 (disconnect :database (find-database "dent/newesim/dent"))
1543 => T
1544         </programlisting>
1545       </refsect1>
1546       <refsect1>
1547         <title>Side Effects</title>
1548         <para>The database connection is closed, and the database
1549           object is removed from the list of connected databases as
1550           returned by <function>connected-databases</function>.</para>
1551         <para>The class of the database object is changed to
1552           <type>closed-database</type>.</para>
1553         <para>If the database object passed is the same under
1554           <function>eq</function> as the value of
1555           <symbol>*default-database*</symbol>, then
1556           <symbol>*default-database*</symbol> is set to the first
1557           remaining database from
1558           <function>connected-databases</function> or to nil if no
1559           further active database exists.</para>
1560       </refsect1>
1561       <refsect1>
1562         <title>Affected by</title>
1563         <para>
1564         <simplelist>
1565           <member><symbol>*default-database*</symbol></member>
1566         </simplelist>
1567         </para>
1568       </refsect1>
1569       <refsect1>
1570         <title>Exceptional Situations</title>
1571         <para>If during the disconnection attempt an error is
1572           detected (e.g. because of network trouble or any other
1573           cause), an error of type <errortype>clsql-error</errortype>
1574           might be signalled.</para>
1575       </refsect1>
1576       <refsect1>
1577         <title>See Also</title>
1578         <para>
1579         <simplelist>
1580           <member><link linkend="connect"><function>connect</function></link></member>
1581           <member><link linkend="connect"><function>closed-database</function></link></member>
1582         </simplelist>
1583         </para>
1584       </refsect1>
1585       <refsect1>
1586         <title>Notes</title>
1587         <para>None.</para>
1588       </refsect1>
1589     </refentry>
1590
1591     <refentry id="disconnect-pooled">
1592       <refnamediv>
1593         <refname>DISCONNECT-POOLED</refname>
1594         <refpurpose>closes all pooled database connections</refpurpose>
1595         <refclass>Function</refclass>
1596       </refnamediv>
1597       <refsect1>
1598         <title>Syntax</title>
1599         <synopsis><function>disconnect-pool</function> => <returnvalue>t</returnvalue></synopsis>
1600       </refsect1>
1601       <refsect1>
1602         <title>Description</title>
1603         <para>This function disconnects all database connections
1604         that have been placed into the pool. Connections are placed
1605         in the pool by calling
1606         <link linkend="disconnect"><function>disconnection</function></link>.
1607       </refsect1>
1608       <refsect1>
1609         <title>Examples</title>
1610         <programlisting>
1611 (disconnect-pool)
1612 => T
1613         </programlisting>
1614       </refsect1>
1615       <refsect1>
1616         <title>Side Effects</title>
1617         <para>Database connections will be closed and entries in the pool are removed.
1618       </refsect1>
1619       <refsect1>
1620         <title>Affected by</title>
1621         <para>
1622         <simplelist>
1623           <member><function>disconnect</function></member>
1624         </simplelist>
1625         </para>
1626       </refsect1>
1627       <refsect1>
1628         <title>Exceptional Situations</title>
1629         <para>If during the disconnection attempt an error is
1630           detected (e.g. because of network trouble or any other
1631           cause), an error of type <errortype>clsql-error</errortype>
1632           might be signalled.</para>
1633       </refsect1>
1634       <refsect1>
1635         <title>See Also</title>
1636         <para>
1637         <simplelist>
1638           <member><link linkend="connect"><function>connect</function></link></member>
1639           <member><link linkend="connect"><function>closed-database</function></link></member>
1640         </simplelist>
1641         </para>
1642       </refsect1>
1643       <refsect1>
1644         <title>Notes</title>
1645         <para>None.</para>
1646       </refsect1>
1647     </refentry>
1648
1649     <refentry id="database-name-from-spec">
1650       <refnamediv>
1651         <refname>DATABASE-NAME-FROM-SPEC</refname>
1652         <refpurpose>Return the database name string corresponding to
1653           the given connection specification.</refpurpose>
1654         <refclass>Generic Function</refclass>
1655       </refnamediv>
1656       <refsect1>
1657         <title>Syntax</title>
1658         <synopsis>
1659           <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
1660       </refsect1>
1661       <refsect1>
1662         <title>Arguments and Values</title>
1663         <variablelist>
1664           <varlistentry>
1665             <term><parameter>connection-spec</parameter></term>
1666             <listitem>
1667               <para>A connection specification, whose structure and
1668                 interpretation are dependent on the
1669                 <parameter>database-type</parameter>.</para>
1670             </listitem>
1671           </varlistentry>
1672           <varlistentry>
1673             <term><parameter>database-type</parameter></term>
1674             <listitem>
1675               <para>A database type specifier, i.e. a keyword.</para>
1676             </listitem>
1677           </varlistentry>
1678           <varlistentry>
1679             <term><returnvalue>name</returnvalue></term>
1680             <listitem>
1681               <para>A string denoting a database name.</para>
1682             </listitem>
1683           </varlistentry>
1684         </variablelist>
1685       </refsect1>
1686       <refsect1>
1687         <title>Description</title>
1688         <para>This generic function takes a connection specification
1689           and a database type and returns the database name of the
1690           database object that would be created had
1691           <function>connect</function> been called with the given
1692           connection specification and database types.</para>
1693         <para>This function is useful in determining a database name
1694           from the connection specification, since the way the
1695           connection specification is converted into a database name
1696           is dependent on the database type.</para>
1697       </refsect1>
1698       <refsect1>
1699         <title>Examples</title>
1700         <programlisting>
1701 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1702 => "dent/newesim/dent"
1703 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1704 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1705 (database-name *default-database*)
1706 => "dent/newesim/dent"
1707
1708 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1709 => "/template1/dent"
1710 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1711 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1712 (database-name *default-database*)
1713 => "/template1/dent"
1714
1715 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1716 => "www.pmsf.de/template1/dent"
1717
1718 (find-database "dent/newesim/dent")
1719 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1720 (find-database "/template1/dent")
1721 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1722 (find-database "www.pmsf.de/template1/dent" nil)
1723 => NIL
1724 (find-database **)
1725 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1726         </programlisting>
1727       </refsect1>
1728       <refsect1>
1729         <title>Side Effects</title>
1730         <para>None.</para>
1731       </refsect1>
1732       <refsect1>
1733         <title>Affected by</title>
1734         <para>None.</para>
1735       </refsect1>
1736       <refsect1>
1737         <title>Exceptional Situations</title>
1738         <para>If the value of <parameter>connection-spec</parameter>
1739           is not a valid connection specification for the given
1740           database type, an error of type
1741           <errortype>clsql-invalid-spec-error</errortype> might be
1742           signalled.</para>
1743       </refsect1>
1744       <refsect1>
1745         <title>See Also</title>
1746         <para>
1747         <simplelist>
1748           <member><link linkend="connect"><function>connect</function></link></member>
1749         </simplelist>
1750         </para>
1751       </refsect1>
1752       <refsect1>
1753         <title>Notes</title>
1754         <para>None.</para>
1755       </refsect1>
1756     </refentry>
1757     <!-- Querying Operations -->
1758     <refentry id="execute-command">
1759       <refnamediv>
1760         <refname>EXECUTE-COMMAND</refname>
1761         <refpurpose>Execute an SQL command which returns no
1762           values.</refpurpose>
1763         <refclass>Function</refclass>
1764       </refnamediv>
1765       <refsect1>
1766         <title>Syntax</title>
1767         <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1768       </refsect1>
1769       <refsect1>
1770         <title>Arguments and Values</title>
1771         <variablelist>
1772           <varlistentry>
1773             <term><parameter>sql-expression</parameter></term>
1774             <listitem>
1775               <para>An <glossterm linkend="gloss-sql-expression">sql
1776                   expression</glossterm> that represents an SQL
1777                 statement which will return no values.</para>
1778             </listitem>
1779           </varlistentry>
1780           <varlistentry>
1781             <term><parameter>database</parameter></term>
1782             <listitem>
1783               <para>A
1784                 <glossterm linkend="gloss-database-object">database
1785                   object</glossterm>. This will default to the value
1786                 of <symbol>*default-database*</symbol>.</para>
1787             </listitem>
1788           </varlistentry>
1789         </variablelist>
1790       </refsect1>
1791       <refsect1>
1792         <title>Description</title>
1793         <para>This will execute the command given by
1794           <parameter>sql-expression</parameter> in the
1795           <parameter>database</parameter> specified.  If the execution
1796           succeeds it will return <symbol>t</symbol>, otherwise an
1797           error of type <errortype>clsql-sql-error</errortype> will
1798           be signalled.</para>
1799       </refsect1>
1800       <refsect1>
1801         <title>Examples</title>
1802         <programlisting>
1803 (execute-command "create table eventlog (time char(30),event char(70))")
1804 => T
1805
1806 (execute-command "create table eventlog (time char(30),event char(70))")
1807 >>
1808 >> While accessing database #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
1809 >>   with expression "create table eventlog (time char(30),event char(70))":
1810 >>   Error NIL: ERROR:  amcreate: eventlog relation already exists
1811 >>   has occurred.
1812 >>
1813 >> Restarts:
1814 >>   0: [ABORT] Return to Top-Level.
1815 >>
1816 >> Debug  (type H for help)
1817 >>
1818 >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
1819 >>  #&lt;unused-arg>
1820 >>  #&lt;unused-arg>
1821 >>  #&lt;unavailable-arg>
1822 >>  #&lt;unavailable-arg>)
1823 >> Source: (ERROR 'CLSQL-SQL-ERROR :DATABASE DATABASE :EXPRESSION ...)
1824 >> 0] 0
1825
1826 (execute-command "drop table eventlog")
1827 => T
1828         </programlisting>
1829       </refsect1>
1830       <refsect1>
1831         <title>Side Effects</title>
1832         <para>Whatever effects the execution of the SQL statement has
1833           on the underlying database, if any.</para>
1834       </refsect1>
1835       <refsect1>
1836         <title>Affected by</title>
1837         <para>None.</para>
1838       </refsect1>
1839       <refsect1>
1840         <title>Exceptional Situations</title>
1841         <para>If the execution of  the SQL statement leads to any
1842           errors, an error of type
1843           <errortype>clsql-sql-error</errortype> is signalled.</para>
1844       </refsect1>
1845       <refsect1>
1846         <title>See Also</title>
1847         <para>
1848         <simplelist>
1849           <member><link linkend="query"><function>query</function></link></member>
1850         </simplelist>
1851         </para>
1852       </refsect1>
1853       <refsect1>
1854         <title>Notes</title>
1855         <para>None.</para>
1856       </refsect1>
1857     </refentry>
1858     <refentry id="query">
1859       <refnamediv>
1860         <refname>QUERY</refname>
1861         <refpurpose>Execute an SQL query and return the tuples as a
1862           list</refpurpose>
1863         <refclass>Function</refclass>
1864       </refnamediv>
1865       <refsect1>
1866         <title>Syntax</title>
1867         <synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
1868       </refsect1>
1869       <refsect1>
1870         <title>Arguments and Values</title>
1871         <variablelist>
1872           <varlistentry>
1873             <term><parameter>query-expression</parameter></term>
1874             <listitem>
1875               <para>An <glossterm linkend="gloss-sql-expression">sql
1876                   expression</glossterm> that represents an SQL
1877                 query which is expected to return a (possibly empty)
1878                 result set.</para>
1879             </listitem>
1880           </varlistentry>
1881           <varlistentry>
1882             <term><parameter>database</parameter></term>
1883             <listitem>
1884               <para>A
1885                 <glossterm linkend="gloss-database-object">database
1886                   object</glossterm>. This will default to the value
1887                 of <symbol>*default-database*</symbol>.</para>
1888             </listitem>
1889           </varlistentry>
1890           <varlistentry>
1891             <term><parameter>types</parameter></term>
1892             <listitem>
1893               <para>A
1894                 <glossterm linkend="gloss-field-types">field type
1895                   specififier</glossterm>. The default is &nil;.
1896                 </para>
1897                 <para>
1898                   The purpose of this argument is cause &clsql; to
1899                   import SQL numeric fields into numeric Lisp objects
1900                   rather than strings. This reduces the cost of
1901                   allocating a temporary string and the &clsql; users'
1902                   inconvenience of converting number strings into number
1903                   objects.
1904                 </para>
1905                 <para>
1906                   A value of <symbol>:auto</symbol> causes &clsql;
1907                   to automatically convert SQL fields into a
1908                   numeric format where applicable. The default value of
1909                   &nil; causes all fields to be returned as strings
1910                   regardless of the SQL type. Otherwise a list is expected
1911                   which has a element for each field that specifies the
1912                   conversion. If the list is shorter than the number
1913                   of fields, the a value of <symbol>t</symbol> is
1914                   assumed for the field.  If the list is longer than
1915                   the number of fields, the extra elements are
1916                   ignored.
1917                   <simplelist type="vert">
1918                     <member><symbol>:int</symbol> Field is imported as a
1919                       signed integer, from 8-bits to 64-bits depending
1920                       upon the field type.
1921                     </member>
1922                     <member><symbol>:double</symbol> Field is imported as a
1923                       double-float number.
1924                     </member>
1925                     <member><symbol>t</symbol> Field is imported as a
1926                       string.
1927                     </member>
1928                   </simplelist>
1929                 </para>
1930             </listitem>
1931           </varlistentry>
1932           <varlistentry>
1933             <term><returnvalue>result</returnvalue></term>
1934             <listitem>
1935               <para>A list representing the result set obtained.  For
1936                 each tuple in the result set, there is an element in
1937                 this list, which is itself a list of all the attribute
1938                 values in the tuple.</para>
1939             </listitem>
1940           </varlistentry>
1941         </variablelist>
1942       </refsect1>
1943       <refsect1>
1944         <title>Description</title>
1945         <para>This will execute the query given by
1946           <parameter>query-expression</parameter> in the
1947           <parameter>database</parameter> specified.  If the execution
1948           succeeds it will return the result set returned by the
1949           database, otherwise an error of type
1950           <errortype>clsql-sql-error</errortype> will
1951           be signalled.</para>
1952       </refsect1>
1953       <refsect1>
1954         <title>Examples</title>
1955         <programlisting>
1956 (execute-command "create table simple (name char(50), salary numeric(10,2))")
1957 => T
1958 (execute-command "insert into simple values ('Mai, Pierre',10000)")
1959 => T
1960 (execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
1961 => T
1962 (query "select * from simple")
1963 => (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
1964 (query "select salary from simple")
1965 => (("10000.00") ("8000.50"))
1966 (query "select salary from simple where salary > 10000")
1967 => NIL
1968 (query "select salary,name from simple where salary > 10000")
1969 => NIL
1970 (query "select salary,name from simple where salary > 9000")
1971 => (("10000.00" "Mai, Pierre"))
1972 (query "select salary,name from simple where salary > 8000")
1973 => (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
1974
1975 ;; MySQL-specific:
1976 (query "show tables")
1977 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
1978         </programlisting>
1979       </refsect1>
1980       <refsect1>
1981         <title>Side Effects</title>
1982         <para>Whatever effects the execution of the SQL query has
1983           on the underlying database, if any.</para>
1984       </refsect1>
1985       <refsect1>
1986         <title>Affected by</title>
1987         <para>None.</para>
1988       </refsect1>
1989       <refsect1>
1990         <title>Exceptional Situations</title>
1991         <para>If the execution of  the SQL query leads to any
1992           errors, an error of type
1993           <errortype>clsql-sql-error</errortype> is signalled.</para>
1994       </refsect1>
1995       <refsect1>
1996         <title>See Also</title>
1997         <para>
1998         <simplelist>
1999           <member><link linkend="execute-command"><function>execute-command</function></link></member>
2000         </simplelist>
2001         </para>
2002       </refsect1>
2003       <refsect1>
2004         <title>Notes</title>
2005         <para>None.</para>
2006       </refsect1>
2007     </refentry>
2008     <!-- Iteration -->
2009     <refentry id="map-query">
2010       <refnamediv>
2011         <refname>MAP-QUERY</refname>
2012         <refpurpose>Map a function over all the tuples from a
2013           query</refpurpose>
2014         <refclass>Function</refclass>
2015       </refnamediv>
2016       <refsect1>
2017         <title>Syntax</title>
2018         <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
2019       </refsect1>
2020       <refsect1>
2021         <title>Arguments and Values</title>
2022         <variablelist>
2023           <varlistentry>
2024             <term><parameter>output-type-spec</parameter></term>
2025             <listitem>
2026               <para>A sequence type specifier or <symbol>nil</symbol>.</para>
2027             </listitem>
2028           </varlistentry>
2029           <varlistentry>
2030             <term><parameter>function</parameter></term>
2031             <listitem>
2032               <para>A function designator.
2033                 <parameter>function</parameter> must take as many
2034                 arguments as are attributes in the result set returned
2035                 by executing the SQL
2036                 <parameter>query-expression</parameter>.</para>
2037             </listitem>
2038           </varlistentry>
2039           <varlistentry>
2040             <term><parameter>query-expression</parameter></term>
2041             <listitem>
2042               <para>An <glossterm linkend="gloss-sql-expression">sql
2043                   expression</glossterm> that represents an SQL
2044                 query which is expected to return a (possibly empty)
2045                 result set, where each tuple has as many attributes as
2046                 <parameter>function</parameter> takes arguments.</para>
2047             </listitem>
2048           </varlistentry>
2049           <varlistentry>
2050             <term><parameter>database</parameter></term>
2051             <listitem>
2052               <para>A
2053                 <glossterm linkend="gloss-database-object">database
2054                   object</glossterm>. This will default to the value
2055                 of <symbol>*default-database*</symbol>.</para>
2056             </listitem>
2057           </varlistentry>
2058           <varlistentry>
2059             <term><parameter>types</parameter></term>
2060             <listitem>
2061               <para>
2062                 A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
2063                 The default is &nil;. See <link
2064                 linkend="query"><function>query</function></link>
2065                 for the semantics of this argument.
2066               </para>
2067             </listitem>
2068           </varlistentry>
2069           <varlistentry>
2070             <term><returnvalue>result</returnvalue></term>
2071             <listitem>
2072               <para>If <parameter>output-type-spec</parameter> is a
2073                 type specifier other than <symbol>nil</symbol>, then a
2074                 sequence of the type it denotes.  Otherwise
2075                 <symbol>nil</symbol> is returned.</para>
2076             </listitem>
2077           </varlistentry>
2078         </variablelist>
2079       </refsect1>
2080       <refsect1>
2081         <title>Description</title>
2082         <para>Applies <parameter>function</parameter> to the
2083           attributes of successive tuples in the result set returned
2084           by executing the SQL
2085           <parameter>query-expression</parameter>.  If the
2086           <parameter>output-type-spec</parameter> is
2087           <symbol>nil</symbol>, then the result of each application
2088           of <parameter>function</parameter> is discarded, and
2089           <function>map-query</function> returns
2090           <symbol>nil</symbol>.  Otherwise the result of each
2091           successive application of <parameter>function</parameter> is
2092           collected in a sequence of type
2093           <parameter>output-type-spec</parameter>, where the jths
2094           element is the result of applying
2095           <parameter>function</parameter> to the attributes of the
2096           jths tuple in the result set.  The collected sequence is the
2097           result of the call to <function>map-query</function>.
2098         </para>
2099         <para>If the <parameter>output-type-spec</parameter> is a
2100           subtype of <type>list</type>, the result will be a
2101           <type>list</type>.</para>
2102         <para>If the <parameter>result-type</parameter> is a subtype
2103           of <type>vector</type>, then if the implementation can
2104           determine the element type specified for the
2105           <parameter>result-type</parameter>, the element type of the
2106           resulting array is the result of
2107           <emphasis>upgrading</emphasis> that element type; or, if the
2108           implementation can determine that the element type is
2109           unspecified (or <symbol>*</symbol>), the element type of the
2110           resulting array is <type>t</type>; otherwise, an error is
2111           signaled.</para>
2112       </refsect1>
2113       <refsect1>
2114         <title>Examples</title>
2115         <programlisting>
2116 (map-query 'list #'(lambda (salary name)
2117                      (declare (ignorable name))
2118                      (read-from-string salary))
2119            "select salary,name from simple where salary > 8000")
2120 => (10000.0 8000.5)
2121
2122 (map-query '(vector double-float)
2123            #'(lambda (salary name)
2124                (declare (ignorable name))
2125                (let ((*read-default-float-format* 'double-float))
2126                  (coerce (read-from-string salary) 'double-float))
2127                   "select salary,name from simple where salary > 8000"))
2128 => #(10000.0d0 8000.5d0)
2129 (type-of *)
2130 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
2131
2132 (let (list)
2133   (values (map-query nil #'(lambda (salary name)
2134                              (push (cons name (read-from-string salary)) list))
2135                      "select salary,name from simple where salary > 8000")
2136           list))
2137 => NIL
2138 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
2139         </programlisting>
2140       </refsect1>
2141       <refsect1>
2142         <title>Side Effects</title>
2143         <para>Whatever effects the execution of the SQL query has
2144           on the underlying database, if any.</para>
2145       </refsect1>
2146       <refsect1>
2147         <title>Affected by</title>
2148         <para>None.</para>
2149       </refsect1>
2150       <refsect1>
2151         <title>Exceptional Situations</title>
2152         <para>If the execution of  the SQL query leads to any
2153           errors, an error of type
2154           <errortype>clsql-sql-error</errortype> is signalled.</para>
2155         <para>An error of type <errortype>type-error</errortype> must
2156           be signaled if the <parameter>output-type-spec</parameter> is
2157           not a recognizable subtype of <type>list</type>, not a
2158           recognizable subtype of <type>vector</type>, and not
2159           <symbol>nil</symbol>.</para>
2160         <para>An error of type <errortype>type-error</errortype>
2161           should be signaled if
2162           <parameter>output-type-spec</parameter> specifies the number
2163           of elements and the size of the result set is different from
2164           that number.</para>
2165       </refsect1>
2166       <refsect1>
2167         <title>See Also</title>
2168         <para>
2169         <simplelist>
2170           <member><link linkend="query"><function>query</function></link></member>
2171           <member><link linkend="do-query"><function>do-query</function></link></member>
2172         </simplelist>
2173         </para>
2174       </refsect1>
2175       <refsect1>
2176         <title>Notes</title>
2177         <para>None.</para>
2178       </refsect1>
2179     </refentry>
2180     <refentry id="do-query">
2181       <refnamediv>
2182         <refname>DO-QUERY</refname>
2183         <refpurpose>Iterate over all the tuples of a
2184         query</refpurpose>
2185         <refclass>Macro</refclass>
2186       </refnamediv>
2187       <refsect1>
2188         <title>Syntax</title>
2189         <synopsis><function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable>) &amp;body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
2190       </refsect1>
2191       <refsect1>
2192         <title>Arguments and Values</title>
2193         <variablelist>
2194           <varlistentry>
2195             <term><parameter>args</parameter></term>
2196             <listitem>
2197               <para>A list of variable names.</para>
2198             </listitem>
2199           </varlistentry>
2200           <varlistentry>
2201             <term><parameter>query-expression</parameter></term>
2202             <listitem>
2203               <para>An <glossterm linkend="gloss-sql-expression">sql
2204                   expression</glossterm> that represents an SQL
2205                 query which is expected to return a (possibly empty)
2206                 result set, where each tuple has as many attributes as
2207                 <parameter>function</parameter> takes arguments.</para>
2208             </listitem>
2209           </varlistentry>
2210           <varlistentry>
2211             <term><parameter>database</parameter></term>
2212             <listitem>
2213               <para>A
2214                 <glossterm linkend="gloss-database-object">database
2215                   object</glossterm>. This will default to
2216                 <symbol>*default-database*</symbol>.</para>
2217             </listitem>
2218           </varlistentry>
2219           <varlistentry>
2220             <term><parameter>types</parameter></term>
2221             <listitem>
2222               <para>
2223                 A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
2224                 The default is &nil;. See <link
2225                 linkend="query"><function>query</function></link>
2226                 for the semantics of this argument.
2227               </para>
2228             </listitem>
2229           </varlistentry>
2230           <varlistentry>
2231             <term><parameter>body</parameter></term>
2232             <listitem>
2233               <para>A body of Lisp code, like in a
2234                 <function>destructuring-bind</function> form.</para>
2235             </listitem>
2236           </varlistentry>
2237         </variablelist>
2238       </refsect1>
2239       <refsect1>
2240         <title>Description</title>
2241         <para>Executes the <parameter>body</parameter> of code
2242           repeatedly with the variable names in
2243           <parameter>args</parameter> bound to the attributes of each
2244           tuple in the result set returned by executing the SQL
2245           <parameter>query-expression</parameter> on the
2246           <parameter>database</parameter> specified.</para>
2247         <para>The body of code is executed in a block named
2248           <symbol>nil</symbol> which may be returned from prematurely
2249           via <function>return</function> or
2250           <function>return-from</function>.  In this case the result
2251           of evaluating the <function>do-query</function> form will be
2252           the one supplied to <function>return</function> or
2253           <function>return-from</function>.  Otherwise the result will
2254           be <symbol>nil</symbol>.</para>
2255         <para>The body of code appears also is if wrapped in a
2256           <function>destructuring-bind</function> form, thus allowing
2257           declarations at the start of the body, especially those
2258           pertaining to the bindings of the variables named in
2259           <parameter>args</parameter>.</para>
2260       </refsect1>
2261       <refsect1>
2262         <title>Examples</title>
2263         <programlisting>
2264 (do-query ((salary name) "select salary,name from simple")
2265   (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
2266 >> Mai, Pierre                    gets $10000.00
2267 >> Hacker, Random J.              gets $08000.50
2268 => NIL
2269
2270 (do-query ((salary name) "select salary,name from simple")
2271   (return (cons salary name)))
2272 => ("10000.00" . "Mai, Pierre")
2273         </programlisting>
2274       </refsect1>
2275       <refsect1>
2276         <title>Side Effects</title>
2277         <para>Whatever effects the execution of the SQL query has
2278           on the underlying database, if any.</para>
2279       </refsect1>
2280       <refsect1>
2281         <title>Affected by</title>
2282         <para>None.</para>
2283       </refsect1>
2284       <refsect1>
2285         <title>Exceptional Situations</title>
2286         <para>If the execution of  the SQL query leads to any
2287           errors, an error of type
2288           <errortype>clsql-sql-error</errortype> is signalled.</para>
2289         <para>If the number of variable names in
2290           <parameter>args</parameter> and the number of attributes in
2291           the tuples in the result set don't match up, an error is
2292           signalled.</para>
2293       </refsect1>
2294       <refsect1>
2295         <title>See Also</title>
2296         <para>
2297         <simplelist>
2298           <member><link linkend="query"><function>query</function></link></member>
2299           <member><link linkend="map-query"><function>map-query</function></link></member>
2300         </simplelist>
2301         </para>
2302       </refsect1>
2303       <refsect1>
2304         <title>Notes</title>
2305         <para>None.</para>
2306       </refsect1>
2307     </refentry>
2308     <refentry id="loop-tuples">
2309       <refnamediv>
2310         <refname>LOOP-FOR-AS-TUPLES</refname>
2311         <refpurpose>Iterate over all the tuples of a
2312         query via a loop clause</refpurpose>
2313         <refclass>Loop Clause</refclass>
2314       </refnamediv>
2315       <refsect1>
2316         <title>Compatibility</title>
2317         <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
2318       </refsect1>
2319       <refsect1>
2320         <title>Syntax</title>
2321         <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>
2322       </refsect1>
2323       <refsect1>
2324         <title>Arguments and Values</title>
2325         <variablelist>
2326           <varlistentry>
2327             <term><parameter>var</parameter></term>
2328             <listitem>
2329               <para>A <literal>d-var-spec</literal>, as defined in the
2330                 grammar for <function>loop</function>-clauses in the
2331                 ANSI Standard for Common Lisp.  This allows for the
2332                 usual loop-style destructuring.</para>
2333             </listitem>
2334           </varlistentry>
2335           <varlistentry>
2336             <term><parameter>type-spec</parameter></term>
2337             <listitem>
2338               <para>An optional <literal>type-spec</literal> either
2339                 simple or destructured, as defined in the grammar for
2340                 <function>loop</function>-clauses in the ANSI Standard
2341                 for Common Lisp.</para>
2342             </listitem>
2343           </varlistentry>
2344           <varlistentry>
2345             <term><parameter>query</parameter></term>
2346             <listitem>
2347               <para>An <glossterm linkend="gloss-sql-expression">sql
2348                   expression</glossterm> that represents an SQL
2349                 query which is expected to return a (possibly empty)
2350                 result set, where each tuple has as many attributes as
2351                 <parameter>function</parameter> takes arguments.</para>
2352             </listitem>
2353           </varlistentry>
2354           <varlistentry>
2355             <term><parameter>database</parameter></term>
2356             <listitem>
2357               <para>An optional
2358                 <glossterm linkend="gloss-database-object">database
2359                   object</glossterm>. This will default to the value
2360                 of <symbol>*default-database*</symbol>.</para>
2361             </listitem>
2362           </varlistentry>
2363         </variablelist>
2364       </refsect1>
2365       <refsect1>
2366         <title>Description</title>
2367         <para>This clause is an iteration driver for
2368         <function>loop</function>, that binds the given variable
2369           (possibly destructured) to the consecutive tuples (which are
2370           represented as lists of attribute values) in the result set
2371           returned by executing the SQL <parameter>query</parameter>
2372           expression on the <parameter>database</parameter>
2373           specified.</para>
2374       </refsect1>
2375       <refsect1>
2376         <title>Examples</title>
2377         <programlisting>
2378 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
2379   "My database"
2380 => *MY-DB*
2381 (loop with time-graph = (make-hash-table :test #'equal)
2382       with event-graph = (make-hash-table :test #'equal)
2383       for (time event) being the tuples of "select time,event from log"
2384       from *my-db*
2385       do
2386       (incf (gethash time time-graph 0))
2387       (incf (gethash event event-graph 0))
2388       finally
2389       (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
2390         (format t "~&amp;Time-Graph:~%===========~%")
2391         (maphash #'show-graph time-graph)
2392         (format t "~&amp;~%Event-Graph:~%============~%")
2393         (maphash #'show-graph event-graph))
2394       (return (values time-graph event-graph)))
2395 >> Time-Graph:
2396 >> ===========
2397 >> D                                        => 53000
2398 >> X                                        =>     3
2399 >> test-me                                  =>  3000
2400 >>
2401 >> Event-Graph:
2402 >> ============
2403 >> CLOS Benchmark entry.                    =>  9000
2404 >> Demo Text...                             =>     3
2405 >> doit-text                                =>  3000
2406 >> C    Benchmark entry.                    => 12000
2407 >> CLOS Benchmark entry                     => 32000
2408 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
2409 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
2410         </programlisting>
2411       </refsect1>
2412       <refsect1>
2413         <title>Side Effects</title>
2414         <para>Whatever effects the execution of the SQL query has
2415           on the underlying database, if any.</para>
2416       </refsect1>
2417       <refsect1>
2418         <title>Affected by</title>
2419         <para>None.</para>
2420       </refsect1>
2421       <refsect1>
2422         <title>Exceptional Situations</title>
2423         <para>If the execution of  the SQL query leads to any
2424           errors, an error of type
2425           <errortype>clsql-sql-error</errortype> is signalled.</para>
2426         <para>Otherwise, any of the exceptional situations of
2427           <function>loop</function> applies.</para>
2428       </refsect1>
2429       <refsect1>
2430         <title>See Also</title>
2431         <para>
2432         <simplelist>
2433           <member><link linkend="query"><function>query</function></link></member>
2434           <member><link linkend="map-query"><function>map-query</function></link></member>
2435           <member><link linkend="do-query"><function>do-query</function></link></member>
2436         </simplelist>
2437         </para>
2438       </refsect1>
2439       <refsect1>
2440         <title>Notes</title>
2441         <para>None.</para>
2442       </refsect1>
2443     </refentry>
2444   </reference>