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

diff --git a/doc/ref_clsql.xml b/doc/ref_clsql.xml
index a567cc7..c24b2ce 100644
--- a/doc/ref_clsql.xml
+++ b/doc/ref_clsql.xml
@@ -1,18 +1,18 @@
 <?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">
@@ -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>
@@ -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>
@@ -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.  
@@ -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.