r10278: 24 Jan 2005 Kevin Rosenberg <kevin@rosenberg.net>

[clsql.git] / doc / ref-fdml.xml

diff --git a/doc/ref-fdml.xml b/doc/ref-fdml.xml
index 2908175042d8c71a5f54cb07c8c6df0a32192ff2..5eb4f070052f9a113c11814b9b6df6c92b2cdf37 100644 (file)
--- a/doc/ref-fdml.xml
+++ b/doc/ref-fdml.xml
@@ -37,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>
@@ -94,14 +94,14 @@
       <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>
+      <refname>CACHE-TABLE-QUERIES</refname>
+      <refpurpose>Control the caching of table attribute types.</refpurpose>
       <refclass>Function</refclass>
     </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>
+      <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>
@@ -189,11 +189,11 @@
     </refsect1>
     <refsect1>
       <title>Side Effects</title>
-      <para>
+       <para>
         The internal attribute cache for
         <parameter>database</parameter> is modified.
-      </para>
-    </refsect1>
+       </para>
+     </refsect1>
     <refsect1>
       <title>Affected by</title>
       <simplelist>
@@ -220,15 +220,12 @@
     </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>
@@ -391,7 +388,7 @@
       <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>
@@ -551,7 +548,7 @@
       <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>
@@ -665,7 +662,7 @@
       <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>
@@ -769,7 +766,7 @@
       <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>
@@ -973,7 +970,7 @@
       <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>
@@ -1129,14 +1126,14 @@ 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>
     <refsect1>
       <title>Syntax</title>
       <synopsis>
-      <function>select</function> &amp;rest <replaceable>identifiers</replaceable> &amp;key <replaceable>all</replaceable> <replaceable>distinct</replaceable> <replaceable>from</replaceable> <replaceable>group-by</replaceable> <replaceable>having</replaceable> <replaceable>order-by</replaceable> <replaceable>set-operation</replaceable> <replaceable>where</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> <replaceable>flatp</replaceable> <replaceable>refresh</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
+      <function>select</function> &amp;rest <replaceable>identifiers</replaceable> &amp;key <replaceable>all</replaceable> <replaceable>distinct</replaceable> <replaceable>from</replaceable> <replaceable>group-by</replaceable> <replaceable>having</replaceable> <replaceable>order-by</replaceable> <replaceable>set-operation</replaceable> <replaceable>where</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> <replaceable>flatp</replaceable> <replaceable>refresh</replaceable> <replaceable>caching</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
     </refsect1>
     <refsect1>
       <title>Arguments and Values</title>
@@ -1283,6 +1280,35 @@ ID FORENAME   SURNAME   EMAIL
           </para>
           </listitem>
         </varlistentry>
+        <varlistentry>
+          <term><parameter>refresh</parameter></term>
+          <listitem> 
+          <para>
+            This value is only considered when CLOS objects are being
+            selected. A boolean with a default value of &nil;. When
+            the value of the <varname>caching</varname> keyword is
+            &t;, a second equivalent <function>select</function> call
+            will return the same view class instance objects. When
+            <varname>refresh</varname> is &t;, then slots of the
+            existing instances are updated as necessary. In such
+            cases, you may wish to override the hook
+            <function>instance-refresh</function>.
+          </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><parameter>caching</parameter></term>
+          <listitem> 
+          <para>
+            This value is only considered when CLOS objects are being
+            selected.  A boolean with a default value of
+            <varname>*default-caching*</varname>. &clsql; caches
+            objects in accordance with the &commonsql; interface: a
+            second equivalent <function>select</function> call will
+            return the same view class instance objects.
+          </para>
+          </listitem>
+        </varlistentry>
         <varlistentry>
           <term><parameter>result</parameter></term>
           <listitem>
@@ -1444,10 +1470,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>
@@ -1506,7 +1530,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>
@@ -1687,9 +1711,10 @@ ID FORENAME   SURNAME   EMAIL
       <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>
@@ -1855,7 +1880,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>