X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fappendix.xml;h=f06f035edfd4915831a7004018c66e278f0f6f46;hb=31ca29efddf77e342aa180dfd2d2e292f6055530;hp=a37c582a9459f1f2e012c45df0ac0f2d07a39f0f;hpb=d529146041f6265030edc25c735e063ebfdbd285;p=clsql.git

diff --git a/doc/appendix.xml b/doc/appendix.xml
index a37c582..f06f035 100644
--- a/doc/appendix.xml
+++ b/doc/appendix.xml
@@ -7,14 +7,53 @@
   
 <appendix id="appendix">
   <title>Database Back-ends</title>
-  
-    <sect1 id="postgresql">
-      <title>PostgreSQL</title>
-      <sect2>
-	<title>Libraries</title>
-	<para>The PostgreSQL back-end requires the PostgreSQL C 
-	  client library (<filename>libpq.so</filename>).  The
-	  location of this library is specified via 
+
+  <sect1 id="foreignlibs">
+    <title>How CLSQL finds and loads foreign  libraries</title>
+    <para>
+      For some database types CLSQL has to load external foreign
+      libaries.  These are usually searched for in the standard
+      locations the operating system uses but you can tell &clsql; to
+      look into other directories as well by using the function
+      <function>CLSQL:PUSH-LIBRARY-PATH</function> or by directly
+      manipulating the special variable
+      <varname>CLSQL:*FOREIGN-LIBRARY-SEARCH-PATHS*</varname>.  If,
+      say, the shared library libpq.so needed for PostgreSQL support
+      is located in the directory <filename>/opt/foo/</filename> on
+      your machine you'd use
+      <screen>
+	(clsql:push-library-path "/opt/foo/")
+      </screen>
+  before loading the CLSQL-POSTGRESQL module.  (Note the trailing
+  slash above!)
+
+  If you want to combine this with fully automatic loading of
+  libraries via ASDF a technique like the following works:
+
+  <screen>
+    (defmethod asdf:perform :after ((o asdf:load-op) 
+                                    (c (eql (asdf:find-system 'clsql))))
+      (funcall (find-symbol (symbol-name '#:push-library-path)
+                            (find-package 'clsql))
+               #p"/opt/foo/"))
+  </screen>
+    </para>
+
+    <para>
+      Additionally, site-specific initialization can be done using an
+initialization file. If the file <filename>/etc/clsql-init.lisp</filename> 
+exists, this file will be read after the &clsql; ASDF system is loaded.
+This file can contain forms to set site-specific paths as well as change
+&clsql; default values.
+    </para>
+  </sect1>
+  <sect1 id="postgresql">
+    <title>PostgreSQL</title>
+    <sect2>
+      <title>Libraries</title>
+      <para>The PostgreSQL back-end requires the PostgreSQL C 
+      client library (<filename>libpq.so</filename>).  The
+      location of this library is specified via 
 	  <symbol>*postgresql-so-load-path*</symbol>, which defaults
 	  to <filename>/usr/lib/libpq.so</filename>.  Additional flags 
 	  to <application>ld</application> needed for linking are
@@ -240,7 +279,7 @@
 	<title>Connection Specification</title>
 	<sect3>
 	  <title>Syntax of connection-spec</title>
-	  <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+	  <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;optional <replaceable>port</replaceable>)</synopsis>
 	</sect3>
 	<sect3>
 	  <title>Description of connection-spec</title>
@@ -277,6 +316,13 @@
 		  field.</para>
 	      </listitem>
 	    </varlistentry>
+	    <varlistentry>
+	      <term><parameter>port</parameter></term>
+	      <listitem>
+		<para>String representing the port to use for
+		  communication with the MySQL server.</para>
+	      </listitem>
+	    </varlistentry>
 	  </variablelist>
 	</sect3>
       </sect2>
@@ -392,7 +438,7 @@
 	<title>Connection Specification</title>
 	<sect3>
 	  <title>Syntax of connection-spec</title>
-	  <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+	  <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &amp;key <replaceable>connection-string</replaceable>)</synopsis>
 	</sect3>
 	<sect3>
 	  <title>Description of connection-spec</title>
@@ -417,6 +463,15 @@
 		  use for authentication.</para>
 	      </listitem>
 	    </varlistentry>
+	    <varlistentry>
+	      <term><parameter>connection-string</parameter></term>
+	      <listitem>
+		<para>Raw connection string passed to the underlying
+		ODBC driver. Allows bypassing creating a DSN on the
+		server.</para>
+	      </listitem>
+	    </varlistentry>
+
 	  </variablelist>
 	</sect3>
       </sect2>
@@ -432,6 +487,26 @@
       </itemizedlist>
       </sect3>
       </sect2>
+      <sect2><title>Connect Examples</title>
+	<screen>
+
+;; assumes a "mssql" DSN is configured on the lisp host, specifying database server
+;;  and database name.
+> (clsql:connect '("mssql" "database-user" "database-password") 
+               :database-type :odbc)
+=> #&lt;CLSQL-ODBC:ODBC-DATABASE mssql/database-user OPEN {100756D123}&gt;
+
+;; no DSN on the lisp host, specify connection information via :connection-string
+> (clsql:connect '("friendly-server-name" "friendly-username" "" 
+		 :connection-string "DRIVER={FreeTDS};SERVER=mssql-server;DATABASE=database-name;UID=database-user;PWD=database-password;PORT=1433;TDS_Version=8.0;APP=clsql") 
+               :database-type :odbc)
+=> #&lt;CLSQL-ODBC:ODBC-DATABASE friendly-server-name/friendly-username OPEN {100756D123}&gt;</screen>	
+	<para>
+          The <symbol>friendly-server-name</symbol>
+          and <symbol>friendly-username</symbol> are only used when
+          printing the connection object to a stream.
+        </para>
+      </sect2>
     </sect1>
 
     <sect1 id="aodbc">
@@ -525,8 +600,8 @@
 	    <varlistentry>
 	      <term><parameter>filename</parameter></term>
 	      <listitem>
-		<para>String representing the filename of the &sqlite;
-		database file.</para>
+		<para>String or pathname representing the filename of
+		the &sqlite; database file.</para>
 	      </listitem>
 	    </varlistentry>
 	  </variablelist>