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>)</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           </variablelist>
 281         </sect3>
 282       </sect2>
 283       <sect2><title>Notes</title>
 284       <sect3><title>FDDL</title>
 285       <itemizedlist mark='opencircle'>
 286         <listitem>
 287           <para>
 288             <link
 289             linkend="drop-index"><function>drop-index</function></link>
 290             requires a table to be specified with the
 291             <symbol>:on</symbol> keyword parameter.
 292           </para>
 293         </listitem>
 294         <listitem>
 295           <para>
 296             <glossterm linkend="gloss-view">views</glossterm> are not
 297             supported by &mysql;.
 298           </para>
 299         </listitem>
 300         <listitem>
 301           <para>
 302             The <symbol>:transactions</symbol> keyword argument to
 303             <link
 304             linkend="create-table"><function>create-table</function></link>
 305             controls whether or not the created table is an InnoDB
 306             table which supports transactions.
 307           </para>
 308         </listitem>
 309         <listitem>
 310           <para>
 311             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 312             for listing and testing for database objects is ignored.
 313           </para>
 314         </listitem>
 315       </itemizedlist>
 316       </sect3>
 317       <sect3><title>FDML</title>
 318       <itemizedlist mark='opencircle'>
 319         <listitem>
 320           <para>
 321             Prior to version 4.1, &mysql; does not support nested
 322             subqueries in calls to <link
 323             linkend="select"><function>select</function></link>.
 324           </para>
 325         </listitem>
 326       </itemizedlist>
 327       </sect3>
 328       <sect3><title>Symbolic SQL Syntax</title>
 329       <itemizedlist mark='opencircle'>
 330         <listitem>
 331           <para>
 332             &mysql; does not support the <function>||</function>
 333             concatenation operator. Use <function>concat</function>
 334             instead.
 335           </para>
 336         </listitem>
 337         <listitem>
 338           <para>
 339             &mysql; does not support the <function>substr</function>
 340             operator. Use <function>substring</function> instead.
 341           </para>
 342         </listitem>
 343         <listitem>
 344           <para>
 345             &mysql; does not support the
 346             <function>intersect</function> and
 347             <function>except</function> set operations.
 348           </para>
 349         </listitem>
 350         <listitem>
 351           <para>
 352             &mysql; (version 4.0 and later) does not support string
 353             table aliases unless the server is started with
 354             ANSI_QUOTES enabled.
 355           </para>
 356         </listitem>
 357       </itemizedlist>
 358       </sect3>
 359       </sect2>
 360     </sect1>
 361
 362     <sect1 id="odbc">
 363       <title>&odbc;</title>
 364       <sect2>
 365         <title>Libraries</title>
 366         <para>
 367           The &odbc; back-end requires access to an &odbc; driver
 368           manager as well as &odbc; drivers for the underlying
 369           database server. &clsql; has been tested with
 370           <application>unixODBC</application> ODBC Driver Manager as
 371           well as Microsoft's ODBC manager.  These driver managers
 372           have been tested with the <ulink
 373           url="http://odbc.postgresql.org">
 374           <citetitle>psqlODBC</citetitle></ulink> driver for
 375           &postgresql; and the <ulink
 376           url="http://www.mysql.com/products/connector/odbc/">
 377           <citetitle>MyODBC</citetitle></ulink> driver for &mysql;.
 378         </para>
 379       </sect2>
 380       <sect2>
 381         <title>Initialization</title>
 382         <para>
 383           Use
 384           <screen>
 385 (asdf:operate 'asdf:load-op 'clsql-odbc)
 386           </screen>
 387           to load the &odbc; back-end.  The database type for the &odbc;
 388           back-end is <symbol>:odbc</symbol>.
 389         </para>
 390       </sect2>
 391       <sect2>
 392         <title>Connection Specification</title>
 393         <sect3>
 394           <title>Syntax of connection-spec</title>
 395           <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 396         </sect3>
 397         <sect3>
 398           <title>Description of connection-spec</title>
 399           <variablelist>
 400             <varlistentry>
 401               <term><parameter>dsn</parameter></term>
 402               <listitem>
 403                 <para>String representing the ODBC data source name.</para>
 404               </listitem>
 405             </varlistentry>
 406             <varlistentry>
 407               <term><parameter>user</parameter></term>
 408               <listitem>
 409                 <para>String representing the user name to use for
 410                   authentication.</para>
 411               </listitem>
 412             </varlistentry>
 413             <varlistentry>
 414               <term><parameter>password</parameter></term>
 415               <listitem>
 416                 <para>String representing the unencrypted password to
 417                   use for authentication.</para>
 418               </listitem>
 419             </varlistentry>
 420           </variablelist>
 421         </sect3>
 422       </sect2>
 423       <sect2><title>Notes</title>
 424       <sect3><title>FDDL</title>
 425       <itemizedlist mark='opencircle'>
 426         <listitem>
 427           <para>
 428             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 429             for listing and testing for database objects is ignored.
 430           </para>
 431         </listitem>
 432       </itemizedlist>
 433       </sect3>
 434       </sect2>
 435     </sect1>
 436
 437     <sect1 id="aodbc">
 438       <title>&aodbc;</title>
 439       <sect2>
 440         <title>Libraries</title> <para>The &aodbc; back-end requires
 441         access to the &odbc; interface of &acl; named DBI. This
 442         interface is not available in the trial version of
 443         &acl;</para>
 444       </sect2>
 445       <sect2>
 446         <title>Initialization</title>
 447         <para>
 448           Use
 449           <screen>
 450 (require 'aodbc-v2)
 451 (asdf:operate 'asdf:load-op 'clsql-aodbc)
 452           </screen>
 453           to load the &aodbc; back-end.  The database type for the &aodbc;
 454           back-end is <symbol>:aodbc</symbol>.
 455         </para>
 456       </sect2>
 457       <sect2>
 458         <title>Connection Specification</title>
 459         <sect3>
 460           <title>Syntax of connection-spec</title>
 461           <synopsis>
 462             (<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)
 463           </synopsis>
 464         </sect3>
 465         <sect3>
 466           <title>Description of connection-spec</title>
 467           <variablelist>
 468             <varlistentry>
 469               <term><parameter>dsn</parameter></term>
 470               <listitem>
 471                 <para>String representing the ODBC data source name.</para>
 472               </listitem>
 473             </varlistentry>
 474             <varlistentry>
 475               <term><parameter>user</parameter></term>
 476               <listitem>
 477                 <para>String representing the user name to use for
 478                   authentication.</para>
 479               </listitem>
 480             </varlistentry>
 481             <varlistentry>
 482               <term><parameter>password</parameter></term>
 483               <listitem>
 484                 <para>String representing the unencrypted password to
 485                   use for authentication.</para>
 486               </listitem>
 487             </varlistentry>
 488           </variablelist>
 489         </sect3>
 490       </sect2>
 491       <sect2><title>Notes</title>
 492       <para>
 493         None.
 494       </para>
 495       </sect2>
 496     </sect1>
 497
 498     <sect1 id="sqlite">
 499       <title>&sqlite;</title>
 500       <sect2>
 501         <title>Libraries</title> <para>The &sqlite; back-end requires
 502         the &sqlite; shared library file. Its default file name is
 503         <filename>/usr/lib/libsqlite.so</filename>.</para>
 504       </sect2>
 505       <sect2>
 506         <title>Initialization</title>
 507         <para>
 508           Use
 509           <screen>
 510 (asdf:operate 'asdf:load-op 'clsql-sqlite)
 511           </screen>
 512           to load the &sqlite; back-end.  The database type for the &sqlite;
 513           back-end is <symbol>:sqlite</symbol>.
 514         </para>
 515       </sect2>
 516       <sect2>
 517         <title>Connection Specification</title>
 518         <sect3>
 519           <title>Syntax of connection-spec</title>
 520           <synopsis>(<replaceable>filename</replaceable>)</synopsis>
 521         </sect3>
 522         <sect3>
 523           <title>Description of connection-spec</title>
 524           <variablelist>
 525             <varlistentry>
 526               <term><parameter>filename</parameter></term>
 527               <listitem>
 528                 <para>String representing the filename of the &sqlite;
 529                 database file.</para>
 530               </listitem>
 531             </varlistentry>
 532           </variablelist>
 533         </sect3>
 534       </sect2>
 535       <sect2><title>Notes</title>
 536       <sect3><title>Connection</title>
 537       <itemizedlist mark='opencircle'>
 538         <listitem>
 539           <para>
 540             Passing <parameter>filename</parameter> a value of
 541             <filename>:memory:</filename> will create a database in
 542             physical memory instead of using a file on disk.
 543           </para>
 544         </listitem>
 545         <listitem>
 546           <para>
 547             Some operations will be many times faster if database
 548             integrity checking is disabled by setting the SYNCHRONOUS
 549             flag to OFF (see the SQLITE manual for details).
 550           </para>
 551         </listitem>
 552       </itemizedlist>
 553       </sect3>
 554       <sect3><title>FDDL</title>
 555       <itemizedlist mark='opencircle'>
 556         <listitem>
 557           <para>
 558             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 559             for listing and testing for database objects is ignored.
 560           </para>
 561         </listitem>
 562         <listitem>
 563           <para>
 564             The <symbol>:column-list</symbol> keyword argument to
 565             <link
 566             linkend="create-view"><function>create-view</function></link>
 567             is not supported by &sqlite;.
 568           </para>
 569         </listitem>
 570       </itemizedlist>
 571       </sect3>
 572       <sect3><title>Symbolic SQL Syntax</title>
 573       <itemizedlist mark='opencircle'>
 574         <listitem>
 575           <para>
 576             &sqlite; does not support the <function>all</function>,
 577             <function>some</function>, <function>any</function> and
 578             <function>exists</function> subquery operations.
 579           </para>
 580         </listitem>
 581       </itemizedlist>
 582       </sect3>
 583       </sect2>
 584     </sect1>
 585
 586     <sect1 id="sqlite3">
 587       <title>&sqlite3;</title>
 588       <sect2>
 589         <title>Libraries</title> <para>The &sqlite3; back-end requires
 590         the &sqlite3; shared library file. Its default file name is
 591         <filename>/usr/lib/libsqlite3.so</filename>.</para>
 592       </sect2>
 593       <sect2>
 594         <title>Initialization</title>
 595         <para>
 596           Use
 597           <screen>
 598 (asdf:operate 'asdf:load-op 'clsql-sqlite3)
 599           </screen>
 600           to load the &sqlite3; back-end.  The database type for the &sqlite3;
 601           back-end is <symbol>:sqlite3</symbol>.
 602         </para>
 603       </sect2>
 604       <sect2>
 605         <title>Connection Specification</title>
 606         <sect3>
 607           <title>Syntax of connection-spec</title>
 608           <synopsis>(<replaceable>filename</replaceable> &amp;optional <replaceable>init-function</replaceable>)</synopsis>
 609         </sect3>
 610         <sect3>
 611           <title>Description of connection-spec</title>
 612           <variablelist>
 613             <varlistentry>
 614               <term><parameter>filename</parameter></term>
 615               <listitem>
 616                 <para>String representing the filename of the &sqlite3;
 617                 database file.</para>
 618               </listitem>
 619             </varlistentry>
 620             <varlistentry>
 621               <term><parameter>init-function</parameter></term>
 622               <listitem>
 623                 <para>
 624                  A function designator.
 625                  <replaceable>init-function</replaceable> takes a
 626                  single argument of type
 627                  <type>sqlite3:sqlite3-db</type>, a foreign pointer to
 628                  the C descriptor of the newly opened database.
 629                  <replaceable>init-function</replaceable> is called by
 630                  the back-end immediately after &sqlite3;
 631                  <function>sqlite3_open</function> library function,
 632                  and can be used to perform optional database
 633                  initializations by calling foreign functions in the
 634                  &sqlite3; library.
 635                 </para>
 636                 <para>
 637                  An example of an initialization function which
 638                  defines a new collating sequence for text columns is
 639                  provided in
 640                  <filename>./examples/sqlite3/init-func/</filename>.
 641                 </para>
 642               </listitem>
 643             </varlistentry>
 644           </variablelist>
 645         </sect3>
 646       </sect2>
 647       <sect2><title>Notes</title>
 648       <sect3><title>Connection</title>
 649       <itemizedlist mark='opencircle'>
 650         <listitem>
 651           <para>
 652             Passing <parameter>filename</parameter> a value of
 653             <filename>:memory:</filename> will create a database in
 654             physical memory instead of using a file on disk.
 655           </para>
 656         </listitem>
 657         <listitem>
 658           <para>
 659             Some operations will be many times faster if database
 660             integrity checking is disabled by setting the SYNCHRONOUS
 661             flag to OFF (see the SQLITE manual for details).
 662           </para>
 663         </listitem>
 664       </itemizedlist>
 665       </sect3>
 666       <sect3><title>FDDL</title>
 667       <itemizedlist mark='opencircle'>
 668         <listitem>
 669           <para>
 670             The <symbol>:owner</symbol> keyword argument to the FDDL functions
 671             for listing and testing for database objects is ignored.
 672           </para>
 673         </listitem>
 674         <listitem>
 675           <para>
 676             The <symbol>:column-list</symbol> keyword argument to
 677             <link
 678             linkend="create-view"><function>create-view</function></link>
 679             is not supported by &sqlite3;.
 680           </para>
 681         </listitem>
 682       </itemizedlist>
 683       </sect3>
 684       <sect3><title>Symbolic SQL Syntax</title>
 685       <itemizedlist mark='opencircle'>
 686         <listitem>
 687           <para>
 688             &sqlite3; does not support the <function>all</function>,
 689             <function>some</function>, <function>any</function> and
 690             <function>exists</function> subquery operations.
 691           </para>
 692         </listitem>
 693       </itemizedlist>
 694       </sect3>
 695       </sect2>
 696     </sect1>
 697
 698   <sect1 id="oracle">
 699     <title>Oracle</title>
 700     <sect2>
 701       <title>Libraries</title>
 702       <para>The &oracle; back-end requires the &oracle; OCI client
 703       library. (<filename>libclntsh.so</filename>).  The location of
 704       this library is specified relative to the
 705       <symbol>ORACLE_HOME</symbol> value in the operating system
 706       environment.
 707       </para>
 708     </sect2>
 709     <sect2>
 710       <title>Library Versions</title>
 711       <para>
 712         &clsql; has tested sucessfully using the client library from
 713         Oracle 9i and Oracle 10g server installations as well as
 714         Oracle's 10g Instant Client library. For Oracle 8 and earlier
 715         versions, there is vestigial support by pushing the symbol
 716         <symbol>:oci7</symbol> onto <symbol>cl:*features*</symbol>
 717         prior to loading the <filename>clsql-oracle</filename> &asdf;
 718         system.
 719         <screen>
 720           (push :oci7 cl:*features*)
 721           (asdf:operate 'asdf:load-op 'clsql-oracle)
 722         </screen>
 723       </para>
 724     </sect2>
 725     <sect2>
 726       <title>Initialization</title>
 727       <para>
 728         Use
 729         <screen>
 730 (asdf:operate 'asdf:load-op 'clsql-oracle)
 731         </screen>
 732         to load the &oracle; back-end.  The database type for the Oracle
 733         back-end is <symbol>:oracle</symbol>.
 734       </para>
 735       </sect2>
 736       <sect2>
 737         <title>Connection Specification</title>
 738         <sect3>
 739           <title>Syntax of connection-spec</title>
 740           <synopsis>(<replaceable>global-name</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
 741         </sect3>
 742         <sect3>
 743           <title>Description of connection-spec</title>
 744           <variablelist>
 745             <varlistentry>
 746               <term><parameter>global-name</parameter></term>
 747               <listitem>
 748                 <para>String representing the global name of the Oracle database.
 749                   This is looked up through the tnsnames.ora file.</para>
 750               </listitem>
 751             </varlistentry>
 752             <varlistentry>
 753               <term><parameter>user</parameter></term>
 754               <listitem>
 755                 <para>String representing the user name to use for
 756                   authentication.</para>
 757               </listitem>
 758             </varlistentry>
 759             <varlistentry>
 760               <term><parameter>password</parameter></term>
 761               <listitem>
 762                 <para>String representing the password to
 763                   use for authentication..</para>
 764               </listitem>
 765             </varlistentry>
 766           </variablelist>
 767         </sect3>
 768       </sect2>
 769       <sect2><title>Notes</title>
 770       <sect3><title>Symbolic SQL Syntax</title>
 771       <itemizedlist mark='opencircle'>
 772         <listitem>
 773           <para>
 774             The <function>userenv</function> operator is &oracle; specific.
 775           </para>
 776         </listitem>
 777         <listitem>
 778           <para>
 779             &oracle; does not support the <function>except</function>
 780             operator. Use <function>minus</function> instead.
 781           </para>
 782         </listitem>
 783         <listitem>
 784           <para>
 785             &oracle; does not support the <function>all</function>,
 786             <function>some</function>, <function>any</function>
 787             subquery operations.
 788           </para>
 789         </listitem>
 790       </itemizedlist>
 791       </sect3>
 792       <sect3><title>Transactions</title>
 793       <itemizedlist mark='opencircle'>
 794         <listitem>
 795           <para>
 796             By default, &clsql; starts in transaction AUTOCOMMIT mode
 797             (see <link
 798             linkend="set-autocommit"><function>set-autocommit</function></link>).
 799             To begin a transaction in autocommit mode, <link
 800             linkend="start-transaction"><function>start-transaction</function></link>
 801             has to be called explicitly.
 802           </para>
 803         </listitem>
 804       </itemizedlist>
 805       </sect3>
 806       </sect2>
 807     </sect1>
 808
 809   </appendix>