r9734: Document idiosyncrasies of the individual backends and differences from CommonSQL.

[clsql.git] / doc / csql.xml

diff --git a/doc/csql.xml b/doc/csql.xml
index d0d09fa4c76caaa7efab2ccecd36dd4d1a59eac1..284de249342ffdf05aff263f9b1fc574f8bddc2d 100644 (file)
--- a/doc/csql.xml
+++ b/doc/csql.xml
@@ -135,20 +135,16 @@
     </para>
 
 <programlisting>
-CREATE TABLE EMPLOYEE (
-       emplid          NOT NULL        number(38),
-       first_name      NOT NULL        varchar2(30),
-       last_name       NOT NULL        varchar2(30),
-       emall                           varchar2(100),
-       companyid       NOT NULL        number(38),
-       managerid                       number(38)
-)
-
-CREATE TABLE COMPANY (
-       companyid       NOT NULL        number(38),
-       name            NOT NULL        varchar2(100),
-       presidentid     NOT NULL        number(38)
-)
+CREATE TABLE EMPLOYEE ( emplid     NOT NULL number(38),
+                        first_name NOT NULL varchar2(30),
+                        last_name  NOT NULL varchar2(30),
+                        email               varchar2(100),
+                        companyid  NOT NULL number(38),
+                        managerid           number(38))
+
+CREATE TABLE COMPANY ( companyid   NOT NULL number(38),
+                       name        NOT NULL varchar2(100),
+                       presidentid NOT NULL number(38))
 </programlisting>
 
 <para>
@@ -181,15 +177,17 @@ mapped into a database).  They would be defined as follows:
     :nulls-ok t
     :initarg :email)
    (companyid
-    :type integer)
+    :type integer
+    :initarg :companyid)
    (managerid
     :type integer
-    :nulls-ok t))
+    :nulls-ok t
+    :initarg :managerid))
   (:base-table employee))
 
 (clsql:def-view-class company ()
   ((companyid
-    :db-type :key
+    :db-kind :key
     :db-constraints :not-null
     :type integer
     :initarg :companyid)
@@ -197,7 +195,8 @@ mapped into a database).  They would be defined as follows:
     :type (string 100)
     :initarg :name)
    (presidentid
-    :type integer))
+    :type integer
+    :initarg :presidentid))
   (:base-table company))
 </programlisting>
 
@@ -251,16 +250,14 @@ mapped into a database).  They would be defined as follows:
 
   <listitem>
     <para>
-      <symbol>:db-type</symbol> - A string which will be used as the
+      <symbol>:column-</symbol> - A string which will be used as the
       type specifier for this slots column definition in the database.
       </para></listitem>
 
   <listitem>
     <para>
-      <symbol>:nulls-ok</symbol> - If &t;, all &sql; &null; values
-      retrieved from the database become nil; if &nil;, all &null;
-      values retrieved are converted by
-      <function>DATABASE-NULL-VALUE</function>. </para></listitem>
+      <symbol>:void-value</symbol> - The Lisp value to return if the
+      field is &null;. The default is &nil;.</para></listitem>
 
   <listitem>
     <para>
@@ -303,7 +300,7 @@ mapped into a database).  They would be defined as follows:
 <para>
 In an &sql; only application, the <symbol>EMPLOYEE</symbol> and
 <symbol>COMPANY</symbol> tables can be queried to determine things
-like, "Who is Vladamir's manager?", What company does Josef work
+like, "Who is Vladamir's manager?", "What company does Josef work
 for?", and "What employees work for Widgets Inc.".  This is done by
 joining tables with an &sql; query.
 </para>
@@ -469,7 +466,7 @@ first need to create our tables in the database:
 </para>
 
 <para>
-Note: the file <filename>doc/clsql-tutorial.lisp</filename> contains
+Note: the file <filename>examples/clsql-tutorial.lisp</filename> contains
 view class definitions which you can load into your list at this point
 in order to play along at home.
 </para>
@@ -485,22 +482,25 @@ any other CLOS object:
 </para>
 
 <programlisting>
-(defvar employee1 (make-instance 'employee
-                              :emplid 1
-                              :first-name "Vladamir"
-                              :last-name "Lenin"
-                              :email "lenin@soviet.org"))
-
 (defvar company1 (make-instance 'company
                              :companyid 1
+                             :presidentid 1
                              :name "Widgets Inc."))
                              
+(defvar employee1 (make-instance 'employee
+                              :emplid 1
+                              :first-name "Vladamir"
+                              :last-name "Lenin"
+                              :email "lenin@soviet.org"
+                              :companyid 1))
 
 (defvar employee2 (make-instance 'employee
                               :emplid 2
                               :first-name "Josef"
                               :last-name "Stalin"
-                              :email "stalin@soviet.org"))
+                              :email "stalin@soviet.org"
+                              :companyid 1
+                              :managerid 1))
 </programlisting>
 
 <para>
@@ -514,26 +514,6 @@ In order to insert an objects into the database we use the
 (clsql:update-records-from-instance company1)
 </programlisting>
 
-<para>
-Now we can set up some of the relations between employees and
-companies, and their managers.  The
-<function>ADD-TO-RELATION</function> method provides us with an easy
-way of doing that.  It will update both the relation slot, as well as
-the home-key and foreign-key slots in both objects in the relation.
-</para>
-
-<programlisting>
-;; Lenin manages Stalin (for now)
-(clsql:add-to-relation employee2 'manager employee1)
-
-;; Lenin and Stalin both work for Widgets Inc.
-(clsql:add-to-relation company1 'employees employee1)
-(clsql:add-to-relation company1 'employees employee2)
-
-;; Lenin is president of Widgets Inc.
-(clsql:add-to-relation company1 'president employee1)
-</programlisting>
-
 <para>
   After you make any changes to an object, you have to specifically
   tell &clsql; to update the &sql; database.  The