doc/ref.sgml

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