X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref_clsql.xml;h=c24b2ced5462fb4ac7780fcd83e973e22638a296;hb=f716bb1161cf9e89a96945c4a444244f9d303691;hp=157df8cf95dd101fe6ff77a1c5d4e9f0e9883c70;hpb=a35619ce17c910796b4f6f58c5916f8f513073e1;p=clsql.git

diff --git a/doc/ref_clsql.xml b/doc/ref_clsql.xml
index 157df8c..c24b2ce 100644
--- a/doc/ref_clsql.xml
+++ b/doc/ref_clsql.xml
@@ -1,18 +1,18 @@
-<?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
+<?xml version='1.0' ?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
+<!ENTITY % myents SYSTEM "entities.inc">
 %myents;
 ]>
 
 <reference id="clsql">
   <title><symbol>CLSQL</symbol></title>
   <partintro>
-    <para>This part gives a reference to all the symbols exported
-      from the package <symbol>CLSQL-SYS</symbol>, which are also
-      re-exported from the package <symbol>CLSQL</symbol>.  These
-      symbols constitute the normal user-interface of
-      &clsql;.</para>
+    <para>This part gives a reference to the symbols exported from the
+    package <symbol>CLSQL-SYS</symbol>, which are also re-exported
+    from the package <symbol>CLSQL</symbol>.  These symbols constitute
+    the normal user-interface of &clsql;. Currently, the symbols of
+    the &commonsql;-API are not documented here.</para>
     </partintro>
     <!-- Conditions -->
     <refentry id="clsql-condition">
@@ -555,12 +555,12 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (setf *default-database-type* :mysql)
 => :mysql
 (initialize-database-type)
 => t
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Affected By</title>
@@ -606,14 +606,14 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (setf *default-database-type* :mysql)
 => :mysql
 (initialize-database-type)
 => t
 *initialized-database-types*
 => (:MYSQL)
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Affected By</title>
@@ -685,7 +685,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 *initialized-database-types*
 => NIL
 (setf *default-database-type* :mysql)
@@ -701,7 +701,7 @@
 => T
 *initialized-database-types*
 => (:MYSQL)
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -833,7 +833,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (connected-databases)
 => NIL
 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
@@ -851,7 +851,7 @@
 => T
 (connected-databases)
 => NIL
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -926,7 +926,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (connected-databases)
 => NIL
 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
@@ -951,7 +951,7 @@
 => NIL
 (connected-databases)
 => NIL
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Affected By</title>
@@ -1105,7 +1105,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
 => "dent/newesim/dent"
 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
@@ -1122,7 +1122,7 @@
 
 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
 => "www.pmsf.de/template1/dent"
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1220,7 +1220,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
 => "dent/newesim/dent"
 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
@@ -1246,7 +1246,7 @@
 => NIL
 (find-database **)
 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1413,7 +1413,7 @@
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
 => "dent/newesim/dent"
 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
@@ -1442,7 +1442,7 @@
 >>                (SETQ RESULT OLD-DB)))
 >> 0] 0
 => #&lt;CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1540,10 +1540,10 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (disconnect :database (find-database "dent/newesim/dent"))
 => T
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1610,10 +1610,10 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (disconnect-pool)
 => T
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1650,6 +1650,237 @@ The default is &nil;.
       </refsect1>
     </refentry>
 
+    <refentry id="create_db">
+      <refnamediv>
+	<refname>CREATE-DATABASE</refname>
+	<refpurpose>create a database</refpurpose>
+	<refclass>Function</refclass>
+      </refnamediv>
+      <refsect1>
+	<title>Syntax</title>
+	<synopsis><function>create-database</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+      </refsect1>
+      <refsect1>
+	<title>Arguments and Values</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><parameter>connection-spec</parameter></term>
+	    <listitem>
+	      <para>A connection specification</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>database-type</parameter></term>
+	    <listitem>
+	      <para>A database type specifier, i.e. a keyword.
+		This defaults to the value of
+		<symbol>*default-database-type*</symbol></para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>success</parameter></term>
+	    <listitem>
+	      <para>A boolean flag. If &t;, a new database was
+	      successfully created.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Description</title>
+	<para>This function creates a database in the database system
+	specified by <parameter>database-type</parameter>.
+	</para>
+      </refsect1>
+      <refsect1>
+	<title>Examples</title>
+	<screen>
+(create-database '("localhost" "new" "dent" "dent") :database-type :mysql)
+=> T
+
+(create-database '("localhost" "new" "dent" "badpasswd") :database-type :mysql)
+=>
+Error: While trying to access database localhost/new/dent
+  using database-type MYSQL:
+  Error database-create failed: mysqladmin: connect to server at 'localhost' failed
+error: 'Access denied for user: 'root@localhost' (Using password: YES)'
+  has occurred.
+  [condition type: CLSQL-ACCESS-ERROR]
+	</screen>
+      </refsect1>
+      <refsect1>
+	<title>Side Effects</title>
+	<para>A database will be created on the filesystem of the host.</para>
+      </refsect1>
+      <refsect1>
+	<title>Exceptional Situations</title>
+	<para>An exception will be thrown if the database system does
+	not allow new databases to be created or if database creation
+	fails.</para>
+      </refsect1>
+      <refsect1>
+	<title>Notes</title>
+	<para>This function may invoke the operating systems
+	functions.  Thus, some database systems may require the
+	administration functions to be available in the current
+	<symbol>PATH</symbol>. At this time, the
+	<symbol>:mysql</symbol> backend requires
+	<filename>mysqladmin</filename> and the
+	<symbol>:postgresql</symbol> backend requires
+	<filename>createdb</filename>.</para>
+      </refsect1>
+    </refentry>
+
+    <refentry id="destroy_db">
+      <refnamediv>
+	<refname>DESTROY-DATABASE</refname>
+	<refpurpose>destroys a database</refpurpose>
+	<refclass>Function</refclass>
+      </refnamediv>
+      <refsect1>
+	<title>Syntax</title>
+	<synopsis><function>destroy-database</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+      </refsect1>
+      <refsect1>
+	<title>Arguments and Values</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><parameter>connection-spec</parameter></term>
+	    <listitem>
+	      <para>A connection specification</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>database-type</parameter></term>
+	    <listitem>
+	      <para>A database type specifier, i.e. a keyword.
+		This defaults to the value of
+		<symbol>*default-database-type*</symbol></para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>success</parameter></term>
+	    <listitem>
+	      <para>A boolean flag. If &t;, the database was
+	      successfully destroyed.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Description</title>
+	<para>This function destroy a database in the database system
+	specified by <parameter>database-type</parameter>.
+	</para>
+      </refsect1>
+      <refsect1>
+	<title>Examples</title>
+	<screen>
+(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=> T
+
+(destroy-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=>
+Error: While trying to access database localhost/test2/root
+  using database-type POSTGRESQL:
+  Error database-destory failed: dropdb: database removal failed: ERROR:  database "test2" does not exist
+  has occurred.
+  [condition type: CLSQL-ACCESS-ERROR]
+	</screen>
+      </refsect1>
+      <refsect1>
+	<title>Side Effects</title>
+	<para>A database will be removed from the filesystem of the host.</para>
+      </refsect1>
+      <refsect1>
+	<title>Exceptional Situations</title>
+	<para>An exception will be thrown if the database system does not
+	allow databases to be removed, the database does not exist, or
+	if database removal fails.</para>
+      </refsect1>
+      <refsect1>
+	<title>Notes</title>
+	<para>This function may invoke the operating systems
+	functions.  Thus, some database systems may require the
+	administration functions to be available in the current
+	<symbol>PATH</symbol>. At this time, the
+	<symbol>:mysql</symbol> backend requires
+	<filename>mysqladmin</filename> and the
+	<symbol>:postgresql</symbol> backend requires
+	<filename>dropdb</filename>.</para>
+      </refsect1>
+    </refentry>
+
+    <refentry id="probe_db">
+      <refnamediv>
+	<refname>PROBE-DATABASE</refname>
+	<refpurpose>tests for existence of a database</refpurpose>
+	<refclass>Function</refclass>
+      </refnamediv>
+      <refsect1>
+	<title>Syntax</title>
+	<synopsis><function>probe-database</function> <replaceable>connection-spec</replaceable> &amp;key <replaceable>database-type</replaceable> => <returnvalue>success</returnvalue></synopsis>
+      </refsect1>
+      <refsect1>
+	<title>Arguments and Values</title>
+	<variablelist>
+	  <varlistentry>
+	    <term><parameter>connection-spec</parameter></term>
+	    <listitem>
+	      <para>A connection specification</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>database-type</parameter></term>
+	    <listitem>
+	      <para>A database type specifier, i.e. a keyword.
+		This defaults to the value of
+		<symbol>*default-database-type*</symbol></para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>success</parameter></term>
+	    <listitem>
+	      <para>A boolean flag. If &t;, the database exists
+	      in the database system.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+      </refsect1>
+      <refsect1>
+	<title>Description</title>
+	<para>This function tests for the existence of a database in
+	the database system specified by
+	<parameter>database-type</parameter>.
+	</para>
+      </refsect1>
+      <refsect1>
+	<title>Examples</title>
+	<screen>
+(probe-database '("localhost" "new" "dent" "dent") :database-type :postgresql)
+=> T
+	</screen>
+      </refsect1>
+      <refsect1>
+	<title>Side Effects</title>
+	<para>None</para>
+      </refsect1>
+      <refsect1>
+	<title>Exceptional Situations</title>
+	<para>An exception maybe thrown if the database system does
+	not receive administrator-level authentication since function
+	may need to read the administrative database of the database
+	system.</para>
+      </refsect1>
+      <refsect1>
+	<title>Notes</title>
+	<para>None.</para>
+      </refsect1>
+    </refentry>
+
     <refentry id="database-name-from-spec">
       <refnamediv>
 	<refname>DATABASE-NAME-FROM-SPEC</refname>
@@ -1701,7 +1932,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
 => "dent/newesim/dent"
 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
@@ -1727,7 +1958,7 @@ The default is &nil;.
 => NIL
 (find-database **)
 => #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1803,7 +2034,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (execute-command "create table eventlog (time char(30),event char(70))")
 => T
 
@@ -1829,7 +2060,7 @@ The default is &nil;.
 
 (execute-command "drop table eventlog")
 => T
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -1868,7 +2099,7 @@ The default is &nil;.
       </refnamediv>
       <refsect1>
 	<title>Syntax</title>
-	<synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
+	<synopsis><function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> => <returnvalue>result</returnvalue></synopsis>
       </refsect1>
       <refsect1>
 	<title>Arguments and Values</title>
@@ -1892,11 +2123,11 @@ The default is &nil;.
 	    </listitem>
 	  </varlistentry>
 	  <varlistentry>
-	    <term><parameter>types</parameter></term>
+	    <term><parameter>result-types</parameter></term>
 	    <listitem>
 	      <para>A 
 		<glossterm linkend="gloss-field-types">field type
-		  specififier</glossterm>. The default is &nil;.
+		  specifier</glossterm>. The default is &nil;.
 		</para>
 		<para>
 		  The purpose of this argument is cause &clsql; to
@@ -1933,6 +2164,15 @@ The default is &nil;.
 		</para>
 	    </listitem>
 	  </varlistentry>
+	  <varlistentry>
+	    <term><parameter>field-names</parameter></term>
+	    <para>
+	      A boolean with a default value of &t;. When &t;, this
+	      function results a second value of a list of field
+	      names. When &nil;, this function only returns one value
+	      - the list of rows.
+	    </para>
+	  </varlistentry>
 	  <varlistentry>
 	    <term><returnvalue>result</returnvalue></term>
 	    <listitem>
@@ -1956,7 +2196,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (execute-command "create table simple (name char(50), salary numeric(10,2))")
 => T
 (execute-command "insert into simple values ('Mai, Pierre',10000)")
@@ -1979,7 +2219,7 @@ The default is &nil;.
 ;; MySQL-specific:
 (query "show tables")
 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -2019,7 +2259,7 @@ The default is &nil;.
       </refnamediv>
       <refsect1>
 	<title>Syntax</title>
-	<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>
+	<synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> => <returnvalue>result</returnvalue></synopsis>
       </refsect1>
       <refsect1>
 	<title>Arguments and Values</title>
@@ -2060,10 +2300,10 @@ The default is &nil;.
 	    </listitem>
 	  </varlistentry>
 	  <varlistentry>
-	    <term><parameter>types</parameter></term>
+	    <term><parameter>result-types</parameter></term>
 	    <listitem>
 	      <para>
-		A <glossterm linkend="gloss-field-types">field type specififier</glossterm>. 
+		A <glossterm linkend="gloss-field-types">field type specifier</glossterm>. 
 		The default is &nil;. See <link
 		linkend="query"><function>query</function></link>
 		for the semantics of this argument.  
@@ -2116,7 +2356,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (map-query 'list #'(lambda (salary name) 
 		     (declare (ignorable name))
 		     (read-from-string salary))
@@ -2140,7 +2380,7 @@ The default is &nil;.
 	  list))
 => NIL
 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -2190,7 +2430,7 @@ The default is &nil;.
       </refnamediv>
       <refsect1>
 	<title>Syntax</title>
-	<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>
+	<synopsis><function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable>) &amp;body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
       </refsect1>
       <refsect1>
 	<title>Arguments and Values</title>
@@ -2221,10 +2461,10 @@ The default is &nil;.
 	    </listitem>
 	  </varlistentry>
 	  <varlistentry>
-	    <term><parameter>types</parameter></term>
+	    <term><parameter>result-types</parameter></term>
 	    <listitem>
 	      <para>
-		A <glossterm linkend="gloss-field-types">field type specififier</glossterm>. 
+		A <glossterm linkend="gloss-field-types">field type specifier</glossterm>. 
 		The default is &nil;. See <link
 		linkend="query"><function>query</function></link>
 		for the semantics of this argument.  
@@ -2264,7 +2504,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (do-query ((salary name) "select salary,name from simple")
   (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
 >> Mai, Pierre                    gets $10000.00
@@ -2274,7 +2514,7 @@ The default is &nil;.
 (do-query ((salary name) "select salary,name from simple")
   (return (cons salary name)))
 => ("10000.00" . "Mai, Pierre")
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>
@@ -2378,7 +2618,7 @@ The default is &nil;.
       </refsect1>
       <refsect1>
 	<title>Examples</title>
-	<programlisting>
+	<screen>
 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
   "My database"
 => *MY-DB*
@@ -2411,7 +2651,7 @@ The default is &nil;.
 >> CLOS Benchmark entry                     => 32000
 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
-	</programlisting>
+	</screen>
       </refsect1>
       <refsect1>
 	<title>Side Effects</title>