doc/appendix.xml

   1 <?xml version='1.0' ?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % myents SYSTEM "entities.inc">
   5 %myents;
   6 ]>
   7
   8 <appendix id="appendix">
   9   <title>Database Back-ends</title>
  10
  11     <sect1 id="postgresql">
  12       <title>PostgreSQL</title>
  13       <sect2>
  14         <title>Libraries</title>
  15         <para>The PostgreSQL back-end requires the PostgreSQL C
  16           client library (<filename>libpq.so</filename>).  The
  17           location of this library is specified via
  18           <symbol>*postgresql-so-load-path*</symbol>, which defaults
  19           to <filename>/usr/lib/libpq.so</filename>.  Additional flags
  20           to <application>ld</application> needed for linking are
  21           specified via <symbol>*postgresql-so-libraries*</symbol>,
  22           which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
  23       </sect2>
  24       <sect2>
  25         <title>Initialization</title>
  26         <para>Use
  27           <screen>
  28 (asdf:operate 'asdf:load-op 'clsql-postgresql)
  29         </screen>
  30           to load the PostgreSQL back-end.  The database type for the
  31           PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
  32       </sect2>
  33       <sect2>
  34         <title>Connection Specification</title>
  35         <sect3>
  36           <title>Syntax of connection-spec</title>
  37           <synopsis>
  38             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
  39           </synopsis>
  40         </sect3>
  41         <sect3>
  42           <title>Description of connection-spec</title>
  43           <para>
  44             For every parameter in the connection-spec,
  45             <symbol>nil</symbol> indicates that the PostgreSQL default
  46             environment variables (see PostgreSQL documentation) will
  47             be used, or if those are unset, the compiled-in defaults
  48             of the C client library are used.
  49           </para>
  50           <variablelist>
  51             <varlistentry>
  52               <term><parameter>host</parameter></term>
  53               <listitem>
  54                 <para>String representing the hostname or IP address
  55                   the PostgreSQL server resides on.  Use the empty
  56                   string to indicate a connection to localhost via
  57                   Unix-Domain sockets instead of TCP/IP.</para>
  58               </listitem>
  59             </varlistentry>
  60             <varlistentry>
  61               <term><parameter>db</parameter></term>
  62               <listitem>
  63                 <para>String representing the name of the database on
  64                   the server to connect to.</para>
  65               </listitem>
  66             </varlistentry>
  67             <varlistentry>
  68               <term><parameter>user</parameter></term>
  69               <listitem>
  70                 <para>String representing the user name to use for
  71                   authentication.</para>
  72               </listitem>
  73             </varlistentry>
  74             <varlistentry>
  75               <term><parameter>password</parameter></term>
  76               <listitem>
  77                 <para>String representing the unencrypted password to
  78                   use for authentication.</para>
  79               </listitem>
  80             </varlistentry>
  81             <varlistentry>
  82               <term><parameter>port</parameter></term>
  83               <listitem>
  84                 <para>String representing the port to use for
  85                   communication with the PostgreSQL server.</para>
  86               </listitem>
  87             </varlistentry>
  88             <varlistentry>
  89               <term><parameter>options</parameter></term>
  90               <listitem>
  91                 <para>String representing further runtime options for
  92                   the PostgreSQL server.</para>
  93               </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96               <term><parameter>tty</parameter></term>
  97               <listitem>
  98                 <para>String representing the tty or file to use for
  99                   debugging messages from the PostgreSQL server.</para>
 100               </listitem>
 101             </varlistentry>
 102           </variablelist>
 103         </sect3>
 104       </sect2>
 105       <sect2><title>Notes</title>
 106       <para>None.</para>
 107       </sect2>
 108     </sect1>
 109
 110     <sect1 id="postgresql-socket">
 111       <title>PostgreSQL Socket</title>
 112       <sect2>
 113         <title>Libraries</title>
 114         <para>The PostgreSQL Socket back-end needs
 115           <emphasis>no</emphasis> access to the PostgreSQL C
 116           client library, since it communicates directly with the
 117           PostgreSQL server using the published frontend/backend
 118           protocol, version 2.0.  This eases installation and makes it
 119           possible to dump CMU CL images containing CLSQL and this
 120           backend, contrary to backends which require FFI code.</para>
 121       </sect2>
 122       <sect2>
 123         <title>Initialization</title>
 124         <para>
 125           Use
 126           <screen>
 127 (asdf:operate 'asdf:load-op 'clsql-postgresql-socket)
 128         </screen>
 129           to load the PostgreSQL Socket back-end.  The database type
 130           for the PostgreSQL Socket back-end is
 131           <symbol>:postgresql-socket</symbol>.
 132         </para>
 133       </sect2>
 134       <sect2>
 135         <title>Connection Specification</title>
 136         <sect3>
 137           <title>Syntax of connection-spec</title>
 138           <synopsis>
 139             (<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)
 140           </synopsis>
 141         </sect3>
 142         <sect3>
 143           <title>Description of connection-spec</title>
 144           <variablelist>
 145             <varlistentry>
 146               <term><parameter>host</parameter></term>
 147               <listitem>
 148                 <para>If this is a string, it represents the hostname or
 149                   IP address the PostgreSQL server resides on.  In
 150                   this case communication with the server proceeds via
 151                   a TCP connection to the given host and port.</para>
 152                 <para>
 153                   If this is a pathname, then it is assumed to name the
 154                   directory that contains the server's Unix-Domain
 155                   sockets.  The full name to the socket is then
 156                   constructed from this and the port number passed,
 157                   and communication will proceed via a connection to
 158                   this unix-domain socket.</para>
 159               </listitem>
 160             </varlistentry>
 161             <varlistentry>
 162               <term><parameter>db</parameter></term>
 163               <listitem>
 164                 <para>String representing the name of the database on
 165                   the server to connect to.</para>
 166               </listitem>
 167             </varlistentry>
 168             <varlistentry>
 169               <term><parameter>user</parameter></term>
 170               <listitem>
 171                 <para>String representing the user name to use for
 172                   authentication.</para>
 173               </listitem>
 174             </varlistentry>
 175             <varlistentry>
 176               <term><parameter>password</parameter></term>
 177               <listitem>
 178                 <para>String representing the unencrypted password to
 179                   use for authentication.  This can be the empty
 180                   string if no password is required for
 181                   authentication.</para>
 182               </listitem>
 183             </varlistentry>
 184             <varlistentry>
 185               <term><parameter>port</parameter></term>
 186               <listitem>
 187                 <para>Integer representing the port to use for
 188                   communication with the PostgreSQL server.  This
 189                   defaults to 5432.</para>
 190               </listitem>
 191             </varlistentry>
 192             <varlistentry>
 193               <term><parameter>options</parameter></term>
 194               <listitem>
 195                 <para>String representing further runtime options for
 196                   the PostgreSQL server.</para>
 197               </listitem>
 198             </varlistentry>
 199             <varlistentry>
 200               <term><parameter>tty</parameter></term>
 201               <listitem>
 202                 <para>String representing the tty or file to use for
 203                   debugging messages from the PostgreSQL server.</para>
 204               </listitem>
 205             </varlistentry>
 206           </variablelist>
 207         </sect3>
 208       </sect2>
 209       <sect2><title>Notes</title>
 210       <para>None.</para>
 211       </sect2>
 212     </sect1>
 213
 214   <sect1 id="mysql">
 215     <title>MySQL</title>
 216     <sect2>
 217       <title>Libraries</title>
 218       <para>The &mysql; back-end requires the &mysql; C
 219         client library (<filename>libmysqlclient.so</filename>).
 220         The location of this library is specified
 221         via <symbol>*mysql-so-load-path*</symbol>, which defaults
 222         to <filename>/usr/lib/libmysqlclient.so</filename>.
 223         Additional flags to <application>ld</application> needed for
 224         linking are specified via <symbol>*mysql-so-libraries*</symbol>,
 225         which defaults to <symbol>("-lc")</symbol>.
 226       </para>
 227     </sect2>
 228     <sect2>
 229       <title>Initialization</title>
 230       <para>
 231         Use
 232         <screen>
 233 (asdf:operate 'asdf:load-op 'clsql-mysql)
 234         </screen>
 235         to load the &mysql; back-end.  The database type for the MySQL
 236         back-end is <symbol>:mysql</symbol>.
 237       </para>
 238       </sect2>
 239       <sect2>
 240         <title>Connection Specification</title>
 241         <sect3>
 242           <title>Syntax of connection-spec</title>
 243           <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable>)</synopsis>
 244         </sect3>
 245         <sect3>
 246           <title>Description of connection-spec</title>
 247           <variablelist>
 248             <varlistentry>
 249               <term><parameter>host</parameter></term>
 250               <listitem>
 251                 <para>String representing the hostname or IP address
 252                   the &mysql; server resides on, or <symbol>nil</symbol>
 253                   to indicate the localhost.</para>
 254               </listitem>
 255             </varlistentry>
 256             <varlistentry>
 257               <term><parameter>db</parameter></term>
 258               <listitem>
 259                 <para>String representing the name of the database on
 260                   the server to connect to.</para>
 261               </listitem>
 262             </varlistentry>
 263             <varlistentry>
 264               <term><parameter>user</parameter></term>
 265               <listitem>
 266                 <para>String representing the user name to use for
 267                   authentication, or <symbol>nil</symbol> to use the
 268                   current Unix user ID.</para>
 269               </listitem>
 270             </varlistentry>
 271             <varlistentry>
 272               <term><parameter>password</parameter></term>
 273               <listitem>
 274                 <para>String representing the unencrypted password to
 275                   use for authentication, or <symbol>nil</symbol> if
 276                   the authentication record has an empty password
 277                   field.</para>
 278               </listitem>
 279             </varlistentry>
 280             <varlistentry>
 281               <term><parameter>port</parameter></term>
 282               <listitem>
 283                 <para>String representing the port to use for
 284                   communication with the MySQL server.</para>
 285               </listitem>
 286             </varlistentry>
 287           </variablelist>
 288         </sect3>
 289       </sect2>
 290       <sect2><title>Notes</title>
 291       <sect3><title>FDDL</title>
 292       <itemizedlist mark='opencircle'>
 293         <listitem>
 294           <para>
 295             <link
 296             linkend="drop-index"><function>drop-index</function></link>
 297             requires a table to be specified with the
 298             <symbol>:on</symbol> keyword parameter.
 299           </para>
 300         </listitem>
 301         <listitem>
 302           <para>
 303             <glossterm linkend="gloss-view">views</glossterm> are not
 304             supported by &mysql;.
 305           </para>
 306         </listitem>
 307         <listitem>
 308           <para>
 309             The <symbol>:transactions</symbol> keyword argument to
 310             <link
 311             linkend="create-table"><function>create-table</function></link>
 312             controls whether or not the created table is an InnoDB
 313             table which supports transactions.
 314           </para>
 315         </listitem>
 316         <listitem>
 317           <para>
 318             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 319             for listing and testing for database objects is ignored.
 320           </para>
 321         </listitem>
 322       </itemizedlist>
 323       </sect3>
 324       <sect3><title>FDML</title>
 325       <itemizedlist mark='opencircle'>
 326         <listitem>
 327           <para>
 328             Prior to version 4.1, &mysql; does not support nested
 329             subqueries in calls to <link
 330             linkend="select"><function>select</function></link>.
 331           </para>
 332         </listitem>
 333       </itemizedlist>
 334       </sect3>
 335       <sect3><title>Symbolic SQL Syntax</title>
 336       <itemizedlist mark='opencircle'>
 337         <listitem>
 338           <para>
 339             &mysql; does not support the <function>||</function>
 340             concatenation operator. Use <function>concat</function>
 341             instead.
 342           </para>
 343         </listitem>
 344         <listitem>
 345           <para>
 346             &mysql; does not support the <function>substr</function>
 347             operator. Use <function>substring</function> instead.
 348           </para>
 349         </listitem>
 350         <listitem>
 351           <para>
 352             &mysql; does not support the
 353             <function>intersect</function> and
 354             <function>except</function> set operations.
 355           </para>
 356         </listitem>
 357         <listitem>
 358           <para>
 359             &mysql; (version 4.0 and later) does not support string
 360             table aliases unless the server is started with
 361             ANSI_QUOTES enabled.
 362           </para>
 363         </listitem>
 364       </itemizedlist>
 365       </sect3>
 366       </sect2>
 367     </sect1>
 368
 369     <sect1 id="odbc">
 370       <title>&odbc;</title>
 371       <sect2>
 372         <title>Libraries</title>
 373         <para>
 374           The &odbc; back-end requires access to an &odbc; driver
 375           manager as well as &odbc; drivers for the underlying
 376           database server. &clsql; has been tested with
 377           <application>unixODBC</application> ODBC Driver Manager as
 378           well as Microsoft's ODBC manager.  These driver managers
 379           have been tested with the <ulink
 380           url="http://odbc.postgresql.org">
 381           <citetitle>psqlODBC</citetitle></ulink> driver for
 382           &postgresql; and the <ulink
 383           url="http://www.mysql.com/products/connector/odbc/">
 384           <citetitle>MyODBC</citetitle></ulink> driver for &mysql;.
 385         </para>
 386       </sect2>
 387       <sect2>
 388         <title>Initialization</title>
 389         <para>
 390           Use
 391           <screen>
 392 (asdf:operate 'asdf:load-op 'clsql-odbc)
 393           </screen>
 394           to load the &odbc; back-end.  The database type for the &odbc;
 395           back-end is <symbol>:odbc</symbol>.
 396         </para>
 397       </sect2>
 398       <sect2>
 399         <title>Connection Specification</title>
 400         <sect3>
 401           <title>Syntax of connection-spec</title>
 402           <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 403         </sect3>
 404         <sect3>
 405           <title>Description of connection-spec</title>
 406           <variablelist>
 407             <varlistentry>
 408               <term><parameter>dsn</parameter></term>
 409               <listitem>
 410                 <para>String representing the ODBC data source name.</para>
 411               </listitem>
 412             </varlistentry>
 413             <varlistentry>
 414               <term><parameter>user</parameter></term>
 415               <listitem>
 416                 <para>String representing the user name to use for
 417                   authentication.</para>
 418               </listitem>
 419             </varlistentry>
 420             <varlistentry>
 421               <term><parameter>password</parameter></term>
 422               <listitem>
 423                 <para>String representing the unencrypted password to
 424                   use for authentication.</para>
 425               </listitem>
 426             </varlistentry>
 427           </variablelist>
 428         </sect3>
 429       </sect2>
 430       <sect2><title>Notes</title>
 431       <sect3><title>FDDL</title>
 432       <itemizedlist mark='opencircle'>
 433         <listitem>
 434           <para>
 435             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 436             for listing and testing for database objects is ignored.
 437           </para>
 438         </listitem>
 439       </itemizedlist>
 440       </sect3>
 441       </sect2>
 442     </sect1>
 443
 444     <sect1 id="aodbc">
 445       <title>&aodbc;</title>
 446       <sect2>
 447         <title>Libraries</title> <para>The &aodbc; back-end requires
 448         access to the &odbc; interface of &acl; named DBI. This
 449         interface is not available in the trial version of
 450         &acl;</para>
 451       </sect2>
 452       <sect2>
 453         <title>Initialization</title>
 454         <para>
 455           Use
 456           <screen>
 457 (require 'aodbc-v2)
 458 (asdf:operate 'asdf:load-op 'clsql-aodbc)
 459           </screen>
 460           to load the &aodbc; back-end.  The database type for the &aodbc;
 461           back-end is <symbol>:aodbc</symbol>.
 462         </para>
 463       </sect2>
 464       <sect2>
 465         <title>Connection Specification</title>
 466         <sect3>
 467           <title>Syntax of connection-spec</title>
 468           <synopsis>
 469             (<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)
 470           </synopsis>
 471         </sect3>
 472         <sect3>
 473           <title>Description of connection-spec</title>
 474           <variablelist>
 475             <varlistentry>
 476               <term><parameter>dsn</parameter></term>
 477               <listitem>
 478                 <para>String representing the ODBC data source name.</para>
 479               </listitem>
 480             </varlistentry>
 481             <varlistentry>
 482               <term><parameter>user</parameter></term>
 483               <listitem>
 484                 <para>String representing the user name to use for
 485                   authentication.</para>
 486               </listitem>
 487             </varlistentry>
 488             <varlistentry>
 489               <term><parameter>password</parameter></term>
 490               <listitem>
 491                 <para>String representing the unencrypted password to
 492                   use for authentication.</para>
 493               </listitem>
 494             </varlistentry>
 495           </variablelist>
 496         </sect3>
 497       </sect2>
 498       <sect2><title>Notes</title>
 499       <para>
 500         None.
 501       </para>
 502       </sect2>
 503     </sect1>
 504
 505     <sect1 id="sqlite">
 506       <title>&sqlite;</title>
 507       <sect2>
 508         <title>Libraries</title> <para>The &sqlite; back-end requires
 509         the &sqlite; shared library file. Its default file name is
 510         <filename>/usr/lib/libsqlite.so</filename>.</para>
 511       </sect2>
 512       <sect2>
 513         <title>Initialization</title>
 514         <para>
 515           Use
 516           <screen>
 517 (asdf:operate 'asdf:load-op 'clsql-sqlite)
 518           </screen>
 519           to load the &sqlite; back-end.  The database type for the &sqlite;
 520           back-end is <symbol>:sqlite</symbol>.
 521         </para>
 522       </sect2>
 523       <sect2>
 524         <title>Connection Specification</title>
 525         <sect3>
 526           <title>Syntax of connection-spec</title>
 527           <synopsis>(<replaceable>filename</replaceable>)</synopsis>
 528         </sect3>
 529         <sect3>
 530           <title>Description of connection-spec</title>
 531           <variablelist>
 532             <varlistentry>
 533               <term><parameter>filename</parameter></term>
 534               <listitem>
 535                 <para>String representing the filename of the &sqlite;
 536                 database file.</para>
 537               </listitem>
 538             </varlistentry>
 539           </variablelist>
 540         </sect3>
 541       </sect2>
 542       <sect2><title>Notes</title>
 543       <sect3><title>Connection</title>
 544       <itemizedlist mark='opencircle'>
 545         <listitem>
 546           <para>
 547             Passing <parameter>filename</parameter> a value of
 548             <filename>:memory:</filename> will create a database in
 549             physical memory instead of using a file on disk.
 550           </para>
 551         </listitem>
 552         <listitem>
 553           <para>
 554             Some operations will be many times faster if database
 555             integrity checking is disabled by setting the SYNCHRONOUS
 556             flag to OFF (see the SQLITE manual for details).
 557           </para>
 558         </listitem>
 559       </itemizedlist>
 560       </sect3>
 561       <sect3><title>FDDL</title>
 562       <itemizedlist mark='opencircle'>
 563         <listitem>
 564           <para>
 565             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 566             for listing and testing for database objects is ignored.
 567           </para>
 568         </listitem>
 569         <listitem>
 570           <para>
 571             The <symbol>:column-list</symbol> keyword argument to
 572             <link
 573             linkend="create-view"><function>create-view</function></link>
 574             is not supported by &sqlite;.
 575           </para>
 576         </listitem>
 577       </itemizedlist>
 578       </sect3>
 579       <sect3><title>Symbolic SQL Syntax</title>
 580       <itemizedlist mark='opencircle'>
 581         <listitem>
 582           <para>
 583             &sqlite; does not support the <function>all</function>,
 584             <function>some</function>, <function>any</function> and
 585             <function>exists</function> subquery operations.
 586           </para>
 587         </listitem>
 588       </itemizedlist>
 589       </sect3>
 590       </sect2>
 591     </sect1>
 592
 593     <sect1 id="sqlite3">
 594       <title>&sqlite3;</title>
 595       <sect2>
 596         <title>Libraries</title> <para>The &sqlite3; back-end requires
 597         the &sqlite3; shared library file. Its default file name is
 598         <filename>/usr/lib/libsqlite3.so</filename>.</para>
 599       </sect2>
 600       <sect2>
 601         <title>Initialization</title>
 602         <para>
 603           Use
 604           <screen>
 605 (asdf:operate 'asdf:load-op 'clsql-sqlite3)
 606           </screen>
 607           to load the &sqlite3; back-end.  The database type for the &sqlite3;
 608           back-end is <symbol>:sqlite3</symbol>.
 609         </para>
 610       </sect2>
 611       <sect2>
 612         <title>Connection Specification</title>
 613         <sect3>
 614           <title>Syntax of connection-spec</title>
 615           <synopsis>(<replaceable>filename</replaceable> &amp;optional <replaceable>init-function</replaceable>)</synopsis>
 616         </sect3>
 617         <sect3>
 618           <title>Description of connection-spec</title>
 619           <variablelist>
 620             <varlistentry>
 621               <term><parameter>filename</parameter></term>
 622               <listitem>
 623                 <para>String representing the filename of the &sqlite3;
 624                 database file.</para>
 625               </listitem>
 626             </varlistentry>
 627             <varlistentry>
 628               <term><parameter>init-function</parameter></term>
 629               <listitem>
 630                 <para>
 631                  A function designator.
 632                  <replaceable>init-function</replaceable> takes a
 633                  single argument of type
 634                  <type>sqlite3:sqlite3-db</type>, a foreign pointer to
 635                  the C descriptor of the newly opened database.
 636                  <replaceable>init-function</replaceable> is called by
 637                  the back-end immediately after &sqlite3;
 638                  <function>sqlite3_open</function> library function,
 639                  and can be used to perform optional database
 640                  initializations by calling foreign functions in the
 641                  &sqlite3; library.
 642                 </para>
 643                 <para>
 644                  An example of an initialization function which
 645                  defines a new collating sequence for text columns is
 646                  provided in
 647                  <filename>./examples/sqlite3/init-func/</filename>.
 648                 </para>
 649               </listitem>
 650             </varlistentry>
 651           </variablelist>
 652         </sect3>
 653       </sect2>
 654       <sect2><title>Notes</title>
 655       <sect3><title>Connection</title>
 656       <itemizedlist mark='opencircle'>
 657         <listitem>
 658           <para>
 659             Passing <parameter>filename</parameter> a value of
 660             <filename>:memory:</filename> will create a database in
 661             physical memory instead of using a file on disk.
 662           </para>
 663         </listitem>
 664         <listitem>
 665           <para>
 666             Some operations will be many times faster if database
 667             integrity checking is disabled by setting the SYNCHRONOUS
 668             flag to OFF (see the SQLITE manual for details).
 669           </para>
 670         </listitem>
 671       </itemizedlist>
 672       </sect3>
 673       <sect3><title>FDDL</title>
 674       <itemizedlist mark='opencircle'>
 675         <listitem>
 676           <para>
 677             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 678             for listing and testing for database objects is ignored.
 679           </para>
 680         </listitem>
 681         <listitem>
 682           <para>
 683             The <symbol>:column-list</symbol> keyword argument to
 684             <link
 685             linkend="create-view"><function>create-view</function></link>
 686             is not supported by &sqlite3;.
 687           </para>
 688         </listitem>
 689       </itemizedlist>
 690       </sect3>
 691       <sect3><title>Symbolic SQL Syntax</title>
 692       <itemizedlist mark='opencircle'>
 693         <listitem>
 694           <para>
 695             &sqlite3; does not support the <function>all</function>,
 696             <function>some</function>, <function>any</function> and
 697             <function>exists</function> subquery operations.
 698           </para>
 699         </listitem>
 700       </itemizedlist>
 701       </sect3>
 702       </sect2>
 703     </sect1>
 704
 705   <sect1 id="oracle">
 706     <title>Oracle</title>
 707     <sect2>
 708       <title>Libraries</title>
 709       <para>The &oracle; back-end requires the &oracle; OCI client
 710       library. (<filename>libclntsh.so</filename>).  The location of
 711       this library is specified relative to the
 712       <symbol>ORACLE_HOME</symbol> value in the operating system
 713       environment.
 714       </para>
 715     </sect2>
 716     <sect2>
 717       <title>Library Versions</title>
 718       <para>
 719         &clsql; has tested sucessfully using the client library from
 720         Oracle 9i and Oracle 10g server installations as well as
 721         Oracle's 10g Instant Client library. For Oracle 8 and earlier
 722         versions, there is vestigial support by pushing the symbol
 723         <symbol>:oci7</symbol> onto <symbol>cl:*features*</symbol>
 724         prior to loading the <filename>clsql-oracle</filename> &asdf;
 725         system.
 726         <screen>
 727           (push :oci7 cl:*features*)
 728           (asdf:operate 'asdf:load-op 'clsql-oracle)
 729         </screen>
 730       </para>
 731     </sect2>
 732     <sect2>
 733       <title>Initialization</title>
 734       <para>
 735         Use
 736         <screen>
 737 (asdf:operate 'asdf:load-op 'clsql-oracle)
 738         </screen>
 739         to load the &oracle; back-end.  The database type for the Oracle
 740         back-end is <symbol>:oracle</symbol>.
 741       </para>
 742       </sect2>
 743       <sect2>
 744         <title>Connection Specification</title>
 745         <sect3>
 746           <title>Syntax of connection-spec</title>
 747           <synopsis>(<replaceable>global-name</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 748         </sect3>
 749         <sect3>
 750           <title>Description of connection-spec</title>
 751           <variablelist>
 752             <varlistentry>
 753               <term><parameter>global-name</parameter></term>
 754               <listitem>
 755                 <para>String representing the global name of the Oracle database.
 756                   This is looked up through the tnsnames.ora file.</para>
 757               </listitem>
 758             </varlistentry>
 759             <varlistentry>
 760               <term><parameter>user</parameter></term>
 761               <listitem>
 762                 <para>String representing the user name to use for
 763                   authentication.</para>
 764               </listitem>
 765             </varlistentry>
 766             <varlistentry>
 767               <term><parameter>password</parameter></term>
 768               <listitem>
 769                 <para>String representing the password to
 770                   use for authentication..</para>
 771               </listitem>
 772             </varlistentry>
 773           </variablelist>
 774         </sect3>
 775       </sect2>
 776       <sect2><title>Notes</title>
 777       <sect3><title>Symbolic SQL Syntax</title>
 778       <itemizedlist mark='opencircle'>
 779         <listitem>
 780           <para>
 781             The <function>userenv</function> operator is &oracle; specific.
 782           </para>
 783         </listitem>
 784         <listitem>
 785           <para>
 786             &oracle; does not support the <function>except</function>
 787             operator. Use <function>minus</function> instead.
 788           </para>
 789         </listitem>
 790         <listitem>
 791           <para>
 792             &oracle; does not support the <function>all</function>,
 793             <function>some</function>, <function>any</function>
 794             subquery operations.
 795           </para>
 796         </listitem>
 797       </itemizedlist>
 798       </sect3>
 799       <sect3><title>Transactions</title>
 800       <itemizedlist mark='opencircle'>
 801         <listitem>
 802           <para>
 803             By default, &clsql; starts in transaction AUTOCOMMIT mode
 804             (see <link
 805             linkend="set-autocommit"><function>set-autocommit</function></link>).
 806             To begin a transaction in autocommit mode, <link
 807             linkend="start-transaction"><function>start-transaction</function></link>
 808             has to be called explicitly.
 809           </para>
 810         </listitem>
 811       </itemizedlist>
 812       </sect3>
 813       </sect2>
 814     </sect1>
 815
 816   </appendix>