r9753: all docbook fixes done except for removing hovertext
[clsql.git] / doc / ref-fdml.xml
index fa444a43367b385c266942406607e5a7064b2d05..ca725bdd492e25973f4169adadabcb56f9f57bd1 100644 (file)
   <title>Functional Data Manipulation Language (FDML)</title> 
   <partintro>
     <para>
-      <!-- introduction --> 
+      The functional data manipulation interface provided by &clsql;
+      includes functions for inserting, updating and deleting records
+      in existing database tables and executing SQL queries and
+      statements with the results of queries returned as Lisp types.
+      SQL statements expressed as strings may be executed with the
+      <link linkend="query"><function>query</function></link> and
+      <link
+      linkend="execute-command"><function>execute-command</function></link>
+      functions. The <link
+      linkend="select"><function>select</function></link> function, on
+      the other hand, allows for the construction of queries in Lisp
+      using the symbolic SQL syntax. Finally, iterative manipulation
+      of query results is supported by <link
+      linkend="do-query"><function>do-query</function></link>, <link
+      linkend="map-query"><function>map-query</function></link> and an
+      extended clause for the <link
+      linkend="loop-tuples"><function>loop</function></link> macro.
     </para>
   </partintro>
 
-
   <!-- Caching table queries --> 
 
   <refentry id="cache-table-queries-default">
@@ -22,7 +37,7 @@
       <refentrytitle>*CACHE-TABLE-QUERIES-DEFAULT*</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Variable</emphasis> <emphasis role="bold">*CACHE-TABLE-QUERIES-DEFAULT*</emphasis></refname>
+      <refname>*CACHE-TABLE-QUERIES-DEFAULT*</refname>
       <refpurpose>Specifies the default behaviour for caching of
       attribute types.</refpurpose>
       <refclass>Variable</refclass>
       <refentrytitle>CACHE-TABLE-QUERIES</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">CACHE-TABLE-QUERIES</emphasis></refname>
-      <refpurpose>Controls the caching of attribute type information for a database table.</refpurpose>
-      <refclass>Function</refclass>
+      <refname>CACHE-TABLE-QUERIES</refname>
+      <refpurpose>Control the caching of table attribute types.</refpurpose>
     </refnamediv>
     <refsect1>
       <title>Syntax</title>
-      <synopsis>
-      <function>cache-table-queries</function> <replaceable>table</replaceable> &amp;key <replaceable>action</replaceable> <replaceable>database</replaceable>) => <returnvalue></returnvalue></synopsis>
-    </refsect1>
-    <refsect1>
-      <title>Arguments and Values</title>
-      <variablelist>
-        <varlistentry>
-          <term><parameter>table</parameter></term>
-          <listitem>
-            <para>
-              A string representing a database table, &t; or
-              <symbol>:default</symbol>.
-            </para> 
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>action</parameter></term>
-          <listitem>
-            <para>
-              &t;, &nil; or <symbol>:flush</symbol>. 
-            </para> 
-          </listitem>
-        </varlistentry>
-        <varlistentry>
-          <term><parameter>database</parameter></term>
-          <listitem>
-            <para>A 
-            <glossterm linkend="gloss-database-object">database
-            object</glossterm>. This will default to the value
-            of <symbol>*default-database*</symbol>.</para>
-          </listitem>
-      </varlistentry>
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>Controls the caching of attribute type information on the
-      table specified by <parameter>table</parameter> in
-      <parameter>database</parameter> which defaults to
-      <symbol>*default-database*</symbol>. <parameter>action</parameter>
-      specifies the caching behaviour to adopt. If its value is &t;
-      then attribute type information is cached whereas if its value
-      is &nil; then attribute type information is not cached. If
-      <parameter>action</parameter> is <symbol>:flush</symbol> then
-      all existing type information in the cache for
-      <parameter>table</parameter> is removed, but caching is still
-      enabled. <parameter>table</parameter> may be a string
-      representing a table for which the caching action is to be taken
-      while the caching action is applied to all tables if
-      <parameter>table</parameter> is &t;. Alternatively, when
-      <parameter>table</parameter> is <symbol>:default</symbol>, the
-      default caching action specified by
-      <symbol>*cache-table-queries-default*</symbol> is applied to all
-      tables for which a caching action has not been explicitly set.
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-(setf *cache-table-queries-default* t)
-=> T
-(create-table [foo]
-              '(([id] integer)
-                ([height] float)
-                ([name] (string 24))
-                ([comments] varchar)))
-=> 
-(cache-table-queries "foo")
-=> 
-(list-attribute-types "foo")
-=> (("id" :INT4 4 NIL 1) ("height" :FLOAT8 8 NIL 1) ("name" :BPCHAR 24 NIL 1)
-    ("comments" :VARCHAR 255 NIL 1))
-(drop-table "foo")
-=> 
-(create-table [foo]
-              '(([id] integer)
-                ([height] float)
-                ([name] (string 36))
-                ([comments] (string 100))))
-=> 
-(cache-table-queries "foo" :action :flush)
-=> 
-(list-attribute-types "foo")
-=> (("id" :INT4 4 NIL 1) ("height" :FLOAT8 8 NIL 1) ("name" :BPCHAR 36 NIL 1)
-    ("comments" :BPCHAR 100 NIL 1))
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        The internal attribute cache for
-        <parameter>database</parameter> is modified.
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <simplelist>
-        <member><link linkend="cache-table-queries-default"><symbol>*cache-table-queries-default*</symbol></link></member>
-      </simplelist>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        None. 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <simplelist>
-        <member><link linkend="cache-table-queries-default"><symbol>*cache-table-queries-default*</symbol></link></member>
-      </simplelist>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
       <para>
-        None. 
       </para>
     </refsect1>
   </refentry>
 
-
-  <!-- insert/update/delete records --> 
-
   <refentry id="insert-records">
     <refmeta>
       <refentrytitle>INSERT-RECORDS</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">INSERT-RECORDS</emphasis></refname>
+      <refname>INSERT-RECORDS</refname>
       <refpurpose>Insert tuples of data into a database table.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
       <refentrytitle>UPDATE-RECORDS</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">UPDATE-RECORDS</emphasis></refname>
+      <refname>UPDATE-RECORDS</refname>
       <refpurpose>Updates the values of existing records.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
       <refentrytitle>DELETE-RECORDS</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">DELETE-RECORDS</emphasis></refname>
+      <refname>DELETE-RECORDS</refname>
       <refpurpose>Delete records from a database table.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
       <refentrytitle>EXECUTE-COMMAND</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">EXECUTE-COMMAND</emphasis></refname>
+      <refname>EXECUTE-COMMAND</refname>
       <refpurpose>Execute an SQL command which returns no values.</refpurpose>
       <refclass>Generic Function</refclass>
     </refnamediv>
       <refentrytitle>QUERY</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Generic Function</emphasis> <emphasis role="bold">QUERY</emphasis></refname>
+      <refname>QUERY</refname>
       <refpurpose>Execute an SQL query and return the tuples as a 
       list.</refpurpose>
       <refclass>Generic Function</refclass>
       <refentrytitle>PRINT-QUERY</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">PRINT-QUERY</emphasis></refname>
+      <refname>PRINT-QUERY</refname>
       <refpurpose>Prints a tabular report of query results.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -1114,7 +1010,7 @@ ID FORENAME   SURNAME   EMAIL
       <refentrytitle>SELECT</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">SELECT</emphasis></refname>
+      <refname>SELECT</refname>
       <refpurpose>Executes a query given the supplied constraints.</refpurpose>
       <refclass>Function</refclass>
     </refnamediv>
@@ -1278,7 +1174,7 @@ ID FORENAME   SURNAME   EMAIL
               in the tuple.
             </para>
           </listitem>
-        </varlistentry>
+        </varlistentry>        
       </variablelist>
     </refsect1>
     <refsect1>
@@ -1429,10 +1325,8 @@ ID FORENAME   SURNAME   EMAIL
     </refsect1>
     <refsect1>
       <title>Side Effects</title>
-      <para>
         <para>Whatever effects the execution of the SQL query has on
         the underlying database, if any.</para>
-      </para>
     </refsect1>
     <refsect1>
       <title>Affected by</title>
@@ -1461,6 +1355,16 @@ ID FORENAME   SURNAME   EMAIL
     </refsect1>
     <refsect1>
       <title>Notes</title>
+      <para> 
+        The <function>select</function> function is actually
+        implemented in &clsql; with a single
+        <symbol>&amp;rest</symbol> parameter (which is subsequently
+        destructured) rather than the keyword parameters presented
+        here for the purposes of exposition. This means that incorrect
+        or missing keywords or values may not trigger errors in the
+        way that they would if <function>select</function> had been
+        defined using keyword arguments.
+      </para>
       <para>
         The <parameter>field-names</parameter> and
         <parameter>result-types</parameter> keyword arguments are a
@@ -1481,7 +1385,7 @@ ID FORENAME   SURNAME   EMAIL
       <refentrytitle>DO-QUERY</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Macro</emphasis> <emphasis role="bold">DO-QUERY</emphasis></refname>
+      <refname>DO-QUERY</refname>
       <refpurpose>Iterate over all the tuples of a query.</refpurpose>
       <refclass>Macro</refclass>
     </refnamediv>
@@ -1657,85 +1561,15 @@ ID FORENAME   SURNAME   EMAIL
     </refsect1>
   </refentry>
 
-  <refentry id="for-each-row">
-    <refmeta>
-      <refentrytitle>FOR-EACH-ROW</refentrytitle>
-    </refmeta>
-    <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">FOR-EACH-ROW</emphasis></refname>
-      <refpurpose><!-- purpose --></refpurpose>
-      <refclass>Function</refclass>
-    </refnamediv>
-    <refsect1>
-      <title>Syntax</title>
-      <synopsis>
-      <function>for-each-row</function> &amp;KEY FROM ORDER-BY WHERE DISTINCT LIMIT &amp;REST FIELDS &amp;body <replaceable>body</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
-    </refsect1>
-    <refsect1>
-      <title>Arguments and Values</title>
-      <variablelist>
-        <!-- arguments and values --> 
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>
-        <!-- description --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-        <!-- examples --> 
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        <!-- execeptional situations -->
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <simplelist>
-        <member><link linkend="query"><function>query</function></link></member>
-        <member><link linkend="print-query"><function>print-query</function></link></member>
-        <member><link linkend="do-query"><function>do-query</function></link></member>
-        <member><link linkend="map-query"><function>map-query</function></link></member>
-        <member><link linkend="loop-tuples"><function>loop</function></link></member>
-        <member><link linkend="select"><function>select</function></link></member>
-        </simplelist>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes here --> 
-      </para>
-    </refsect1>
-  </refentry>
-
   <refentry id="loop-tuples">
     <refmeta>
       <refentrytitle>LOOP</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Additional clause</emphasis> for <emphasis role="bold">LOOP</emphasis></refname>
-      <refpurpose>Iterate over all the tuples of a
-      query via a loop clause.</refpurpose>
+      <refname>LOOP</refname>
+      <refpurpose>Extension to Common Lisp
+      <computeroutput>Loop</computeroutput> to iterate over all the
+      tuples of a query via a loop clause.</refpurpose>
       <refclass>Loop Clause</refclass>
     </refnamediv>
     <!-- refsect1>
@@ -1901,7 +1735,7 @@ ID FORENAME   SURNAME   EMAIL
       <refentrytitle>MAP-QUERY</refentrytitle>
     </refmeta>
     <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">MAP-QUERY</emphasis></refname>
+      <refname>MAP-QUERY</refname>
       <refpurpose>Map a function over all the tuples from a
       query</refpurpose>
       <refclass>Function</refclass>
@@ -2109,287 +1943,5 @@ ID FORENAME   SURNAME   EMAIL
     </refsect1>
   </refentry>
 
-
-  <!-- prepared statements --> 
-
-  <refentry id="prepare-sql">
-    <refmeta>
-      <refentrytitle>PREPARE-SQL</refentrytitle>
-    </refmeta>
-    <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">PREPARE-SQL</emphasis></refname>
-      <refpurpose>Create a prepared statement.</refpurpose>
-      <refclass>Function</refclass>
-    </refnamediv>
-    <refsect1>
-      <title>Syntax</title>
-      <synopsis>
-      <function>prepare-sql</function> <replaceable>sql-stmt types</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>
-      <variablelist>
-        <!-- arguments and values --> 
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>Prepares a SQL statement <parameter>sql-stmt</parameter>
-      for execution. <parameter>types</parameter> contains a list of
-      types corresponding to the input parameters. Returns a
-      prepared-statement object.
-      
-      A type can be
-      :int
-      :double
-      :null
-      (:string n)
-      
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-        <!-- examples -->
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        <!-- execeptional situations -->
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <para>
-        <simplelist>
-          <!-- see also --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>
-  </refentry>
-
-  <refentry id="run-prepared-sql">
-    <refmeta>
-      <refentrytitle>RUN-PREPARED-SQL</refentrytitle>
-    </refmeta>
-    <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">RUN-PREPARED-SQL</emphasis></refname>
-      <refpurpose>Execute a prepared statement.</refpurpose>
-      <refclass>Function</refclass>
-    </refnamediv>
-    <refsect1>
-      <title>Syntax</title>
-      <synopsis>
-      <function>run-prepared-sql</function> <replaceable>prepared-stmt</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
-    </refsect1>
-    <refsect1>
-      <title>Arguments and Values</title>
-      <variablelist>
-        <!-- arguments and values --> 
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>Execute the prepared sql statment. All input
-      parameters must be bound.
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-        <!-- examples -->
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        <!-- execeptional situations -->
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <para>
-        <simplelist>
-          <!-- see also --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>
-  </refentry>
-
-  <refentry id="free-prepared-sql">
-    <refmeta>
-      <refentrytitle>FREE-PREPARED-SQL</refentrytitle>
-    </refmeta>
-    <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">FREE-PREPARED-SQL</emphasis></refname>
-      <refpurpose>Delete a prepared statement object.</refpurpose>
-      <refclass>Function</refclass>
-    </refnamediv>
-    <refsect1>
-      <title>Syntax</title>
-      <synopsis>
-      <function>free-prepared-sql</function> <replaceable>prepared-stmt</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
-    </refsect1>
-    <refsect1>
-      <title>Arguments and Values</title>
-      <variablelist>
-        <!-- arguments and values --> 
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>Delete the objects associated with a prepared
-      statement.
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-        <!-- examples -->
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        <!-- execeptional situations -->
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <para>
-        <simplelist>
-          <!-- see also --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>
-  </refentry>
-
-  <refentry id="bind-parameter">
-    <refmeta>
-      <refentrytitle>BIND-PARAMETER</refentrytitle>
-    </refmeta>
-    <refnamediv>
-      <refname><emphasis>Function</emphasis> <emphasis role="bold">BIND-PARAMETER</emphasis></refname>
-      <refpurpose>Bind a parameter in a prepared statement.</refpurpose>
-      <refclass>Function</refclass>
-    </refnamediv>
-    <refsect1>
-      <title>Syntax</title>
-      <synopsis>
-      <function>bind-parameter</function> <replaceable>prepared-stmt</replaceable> <replaceable>position</replaceable> <replaceable>value</replaceable> => <returnvalue><!-- result --></returnvalue></synopsis>
-    </refsect1>
-    <refsect1>
-      <title>Arguments and Values</title>
-      <variablelist>
-        <!-- arguments and values --> 
-      </variablelist>
-    </refsect1>
-    <refsect1>
-      <title>Description</title>
-      <para>Sets the value of a parameter in a prepared statement.
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Examples</title>
-      <screen>
-        <!-- examples -->
-      </screen>
-    </refsect1>
-    <refsect1>
-      <title>Side Effects</title>
-      <para>
-        <!-- side effects --> 
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Affected by</title>
-      <para>
-        <simplelist>
-          <!-- affected by --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Exceptional Situations</title>
-      <para>
-        <!-- execeptional situations -->
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>See Also</title>
-      <para>
-        <simplelist>
-          <!-- see also --> 
-        </simplelist>
-      </para>
-    </refsect1>
-    <refsect1>
-      <title>Notes</title>
-      <para>
-        <!-- notes --> 
-      </para>
-    </refsect1>
-  </refentry>
-
 </reference> 
+