r9421: Docstrings for table.lisp

diff --git a/ChangeLog b/ChangeLog
index 7591d42c156d4ce62ebbf05a3e7d70deccc20ca0..b3254f6756afa91233b0650369c071b7af35b771 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+20 May 2004 Marcus Pearce (m.t.pearce@city.ac.uk) 
+       * sql/classes.lisp: remove unused PARAMS slot in SQL-IDENT-ATTRIBUTE. 
+       * sql/syntax.lisp: remove unused PARAMS keyword arg to SQL-EXPRESSION. 
+       * sql/table.lisp: reworked docstrings. 
+       * sql/objects.lisp: moved *default-update-objects-max-len* here from 
+       table.lisp. 
+       * doc/TODO: notes about :if-does-not-exist arg to DROP-TABLE, 
+       DROP-VIEW and DROP-INDEX and the use of the :transactions and 
+       :constraints keyword args to CREATE-TABLE. 
+       * sql/classes.lisp: the DESCRIPTION argument to CREATE-TABLE is now 
+       CommonSQL compatible with respect to column constraints. 
+

 20 May 2004 Kevin Rosenberg (kevin@rosenberg.net)
        * sql/oracle-sql.lisp: Now compiles and runs on SBCL.
        Requires UFFI 1.5.0 or higher
 20 May 2004 Kevin Rosenberg (kevin@rosenberg.net)
        * sql/oracle-sql.lisp: Now compiles and runs on SBCL.
        Requires UFFI 1.5.0 or higher

diff --git a/doc/TODO b/doc/TODO
index f6b1715b7a945c47c126f21a6857f6bdb6188c92..8d976c8effe4dfbd6df648850be005fb5e9a761e 100644 (file)
--- a/doc/TODO
+++ b/doc/TODO
@@ -33,7 +33,14 @@ DOCUMENTATION TO DO LIST
  - SQL-RECORDING-P: also accepts :both and :either values for the TYPE 
    parameter. 
 
  - SQL-RECORDING-P: also accepts :both and :either values for the TYPE 
    parameter. 
 

- - SQL-EXPRESSION: also accepts a :params keyword arg which is passed 
+ - DROP-TABLE/DROP-VIEW/DROP-INDEX: keyword arg :if-does-not-exist. 
+
+ - DROP-INDEX: keyword arg :on (for MySQL). 
+
+ - DEF-VIEW-CLASS: DB-CONSTRAINTS and DB-TYPE slot options. 
+
+ - CREATE-TABLE: keyword args :TRANSACTIONS (for MySQL) and :CONSTRAINTS 
+                 description arg accepts optional DB-TYPE string. 

 
 4. Documenting lower level, non-CommonSQL functions (some of this is already 
    done). 
 
 4. Documenting lower level, non-CommonSQL functions (some of this is already 
    done). 


@@ -41,6 +48,7 @@ DOCUMENTATION TO DO LIST
  - connection pools
  - database-query-result-set 
 
  - connection pools
  - database-query-result-set 
 

+

 5. Notes on any peculiarities of each of the backends (e.g., unsupported 
    features, notable extensions etc.). 
 
 5. Notes on any peculiarities of each of the backends (e.g., unsupported 
    features, notable extensions etc.). 
 


@@ -51,6 +59,8 @@ DOCUMENTATION TO DO LIST
    queries:      nested subqueries are not supported
    syntax:       doesn't support the sql concatenation operator (||). 
                  doesn't support INTERSECT/EXCEPT set operations. 
    queries:      nested subqueries are not supported
    syntax:       doesn't support the sql concatenation operator (||). 
                  doesn't support INTERSECT/EXCEPT set operations. 

+   create-table: the transactions keyword arg controls whether the created 
+                 table is an InnoDB table (supporting transactions) or not. 

 
  - SQLITE 
 
 
  - SQLITE 
 

diff --git a/sql/classes.lisp b/sql/classes.lisp
index 55801df9712ee977242ebff4433687b9b545ef31..bf74b6ecc3e4c8e6f01fee30820eaa91517421bf 100644 (file)
--- a/sql/classes.lisp
+++ b/sql/classes.lisp
@@ -119,10 +119,7 @@
     :initform "NULL")
    (type
     :initarg :type
     :initform "NULL")
    (type
     :initarg :type

-    :initform "NULL")
-   (params
-    :initarg :params
-    :initform nil))
+    :initform "NULL"))

   (:documentation "An SQL Attribute identifier."))
 
 (defmethod collect-table-refs (sql)
   (:documentation "An SQL Attribute identifier."))
 
 (defmethod collect-table-refs (sql)


@@ -144,7 +141,7 @@
       :type ',type)))
 
 (defmethod output-sql ((expr sql-ident-attribute) database)
       :type ',type)))
 
 (defmethod output-sql ((expr sql-ident-attribute) database)

-  (with-slots (qualifier name type params)
+  (with-slots (qualifier name type)

       expr
     (if (and (not qualifier) (not type))
        (write-string (sql-escape (convert-to-db-default-case 
       expr
     (if (and (not qualifier) (not type))
        (write-string (sql-escape (convert-to-db-default-case 


@@ -169,9 +166,9 @@
 
 (defmethod output-sql-hash-key ((expr sql-ident-attribute) database)
   (declare (ignore database))
 
 (defmethod output-sql-hash-key ((expr sql-ident-attribute) database)
   (declare (ignore database))

-  (with-slots (qualifier name type params)
+  (with-slots (qualifier name type)

     expr
     expr

-    (list 'sql-ident-attribute qualifier name type params)))
+    (list 'sql-ident-attribute qualifier name type)))

 
 ;; For SQL Identifiers for tables
 (defclass sql-ident-table (sql-ident)
 
 ;; For SQL Identifiers for tables
 (defclass sql-ident-table (sql-ident)


@@ -770,8 +767,11 @@ uninclusive, and the args from that keyword to the end."
                 (if (stringp db-type) db-type ; override definition
                     (database-get-type-specifier (car type) (cdr type) database))
                 *sql-stream*)
                 (if (stringp db-type) db-type ; override definition
                     (database-get-type-specifier (car type) (cdr type) database))
                 *sql-stream*)

-               (let ((constraints
-                      (database-constraint-statement constraints database)))
+               (let ((constraints (database-constraint-statement  
+                                   (if (and db-type (symbolp db-type))
+                                       (cons db-type constraints)
+                                       constraints)
+                                   database)))

                  (when constraints
                    (write-string " " *sql-stream*)
                    (write-string constraints *sql-stream*)))))))
                  (when constraints
                    (write-string " " *sql-stream*)
                    (write-string constraints *sql-stream*)))))))


@@ -824,7 +824,11 @@ uninclusive, and the args from that keyword to the end."
 (defparameter *constraint-types*
   (list 
    (cons (symbol-name-default-case "NOT-NULL") "NOT NULL") 
 (defparameter *constraint-types*
   (list 
    (cons (symbol-name-default-case "NOT-NULL") "NOT NULL") 

-   (cons (symbol-name-default-case "PRIMARY-KEY") "PRIMARY KEY")))
+   (cons (symbol-name-default-case "PRIMARY-KEY") "PRIMARY KEY")
+   (cons (symbol-name-default-case "NOT") "NOT") 
+   (cons (symbol-name-default-case "NULL") "NULL") 
+   (cons (symbol-name-default-case "PRIMARY") "PRIMARY") 
+   (cons (symbol-name-default-case "KEY") "KEY")))

 
 ;;
 ;; Convert type spec to sql syntax
 
 ;;
 ;; Convert type spec to sql syntax

diff --git a/sql/objects.lisp b/sql/objects.lisp
index af5aaea1c476cbd5f1b8690e5f8b110a8d1b88ef..e6a9457a9dacf8fa2d00b814b37ba9fed7aedc96 100644 (file)
--- a/sql/objects.lisp
+++ b/sql/objects.lisp
@@ -808,6 +808,13 @@ superclass of the newly-defined View Class."
                     :from (sql-expression :table jc-view-table)
                     :where jq)))))))
 
                     :from (sql-expression :table jc-view-table)
                     :where jq)))))))
 

+
+;;; Remote Joins
+
+(defvar *default-update-objects-max-len* nil
+  "The default maximum number of objects supplying data for a
+  query when updating remote joins.")
+

 (defun update-object-joins (objects &key (slots t) (force-p t)
                            class-name (max-len *default-update-objects-max-len*))
   "Updates the remote join slots, that is those slots defined without
 (defun update-object-joins (objects &key (slots t) (force-p t)
                            class-name (max-len *default-update-objects-max-len*))
   "Updates the remote join slots, that is those slots defined without

diff --git a/sql/syntax.lisp b/sql/syntax.lisp
index 0202cedc00dddaa570c6bfc1f30e25709f14d882..e4bf1507324dcbe1c4f73894110a76578803dd54 100644 (file)
--- a/sql/syntax.lisp
+++ b/sql/syntax.lisp
@@ -114,23 +114,18 @@ reader syntax is disabled."
             (sql-expression :string (car arglist))
              (sql-expression :attribute (car arglist))))
        ((<= 2 (length arglist))
             (sql-expression :string (car arglist))
              (sql-expression :attribute (car arglist))))
        ((<= 2 (length arglist))

-        (let ((sqltype (if (keywordp (caddr arglist))
-                           (caddr arglist) nil))
-              (sqlparam (if (keywordp (caddr arglist))
-                            (caddr arglist))))
-          (cond
+        (let ((sqltype (when (keywordp (caddr arglist)) (caddr arglist) nil)))
+           (cond

              ((stringp (cadr arglist))
             (sql-expression :table (car arglist)
                             :alias (cadr arglist)
                             :type sqltype))
            ((keywordp (cadr arglist))
             (sql-expression :attribute (car arglist)
              ((stringp (cadr arglist))
             (sql-expression :table (car arglist)
                             :alias (cadr arglist)
                             :type sqltype))
            ((keywordp (cadr arglist))
             (sql-expression :attribute (car arglist)

-                            :type (cadr arglist)
-                            :params sqlparam))
+                            :type (cadr arglist)))

            (t
             (sql-expression :attribute (cadr arglist)
                             :table (car arglist)
            (t
             (sql-expression :attribute (cadr arglist)
                             :table (car arglist)

-                            :params sqlparam

                             :type sqltype)))))
        (t
         (error 'sql-user-error :message "bad expression syntax"))))
                             :type sqltype)))))
        (t
         (error 'sql-user-error :message "bad expression syntax"))))


@@ -144,7 +139,7 @@ ARGS. The expressions are translated into SQL strings and then
 concatenated with a single space delimiting each expression."
   (format nil "~{~A~^ ~}" (mapcar #'sql-output args)))
 
 concatenated with a single space delimiting each expression."
   (format nil "~{~A~^ ~}" (mapcar #'sql-output args)))
 

-(defun sql-expression (&key string table alias attribute type params)
+(defun sql-expression (&key string table alias attribute type)

   "Returns an SQL expression constructed from the supplied arguments
 which may be combined as follows: ATTRIBUTE and TYPE; ATTRIBUTE;
 ALIAS or TABLE and ATTRIBUTE and TYPE; ALIAS or TABLE and
   "Returns an SQL expression constructed from the supplied arguments
 which may be combined as follows: ATTRIBUTE and TYPE; ATTRIBUTE;
 ALIAS or TABLE and ATTRIBUTE and TYPE; ALIAS or TABLE and


@@ -156,8 +151,7 @@ and ALIAS; TABLE; and STRING."
     (attribute
      (make-instance 'sql-ident-attribute  :name attribute
                     :qualifier (or table alias)
     (attribute
      (make-instance 'sql-ident-attribute  :name attribute
                     :qualifier (or table alias)

-                    :type type
-                    :params params))
+                    :type type))

     ((and table (not attribute))
      (make-instance 'sql-ident-table :name table
                     :table-alias alias))))
     ((and table (not attribute))
      (make-instance 'sql-ident-table :name table
                     :table-alias alias))))

diff --git a/sql/table.lisp b/sql/table.lisp
index 1b28c4ff10db3b6b37bf181ee09b702576978b3e..72895cfa97f699ff463b253ae2dcf33cdaa4f01e 100644 (file)
--- a/sql/table.lisp
+++ b/sql/table.lisp
@@ -34,9 +34,15 @@
 
 (defun create-table (name description &key (database *default-database*)
                           (constraints nil) (transactions t))
 
 (defun create-table (name description &key (database *default-database*)
                           (constraints nil) (transactions t))

-  "Create a table called NAME, in DATABASE which defaults to
-*DEFAULT-DATABASE*, containing the attributes in DESCRIPTION which is
-a list containing lists of attribute-name and type information pairs."
+  "Creates a table called NAME, which may be a string, symbol or
+SQL table identifier, in DATABASE which defaults to
+*DEFAULT-DATABASE*. DESCRIPTION is a list whose elements are
+lists containing the attribute names, types, and other
+constraints such as not-null or primary-key for each column in
+the table.  CONSTRAINTS is a string representing an SQL table
+constraint expression or a list of such strings. With MySQL
+databases, if TRANSACTIONS is t an InnoDB table is created which
+supports transactions."

   (let* ((table-name (etypecase name 
                        (symbol (sql-expression :attribute name))
                        (string (sql-expression :attribute (make-symbol name)))
   (let* ((table-name (etypecase name 
                        (symbol (sql-expression :attribute name))
                        (string (sql-expression :attribute (make-symbol name)))


@@ -50,10 +56,10 @@ a list containing lists of attribute-name and type information pairs."
 
 (defun drop-table (name &key (if-does-not-exist :error)
                         (database *default-database*))
 
 (defun drop-table (name &key (if-does-not-exist :error)
                         (database *default-database*))

-  "Drops table NAME from DATABASE which defaults to
-*DEFAULT-DATABASE*. If the table does not exist and IF-DOES-NOT-EXIST
-is :ignore then DROP-TABLE returns nil whereas an error is signalled
-if IF-DOES-NOT-EXIST is :error."
+  "Drops the table called NAME from DATABASE which defaults to
+*DEFAULT-DATABASE*. If the table does not exist and
+IF-DOES-NOT-EXIST is :ignore then DROP-TABLE returns nil whereas
+an error is signalled if IF-DOES-NOT-EXIST is :error."

   (let ((table-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore
   (let ((table-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore


@@ -68,21 +74,20 @@ if IF-DOES-NOT-EXIST is :error."
       (execute-command expr :database database))))
 
 (defun list-tables (&key (owner nil) (database *default-database*))
       (execute-command expr :database database))))
 
 (defun list-tables (&key (owner nil) (database *default-database*))

-  "List all tables in DATABASE which defaults to
-*DEFAULT-DATABASE*. If OWNER is nil, only user-owned tables are
-considered. This is the default. If OWNER is :all , all tables are
-considered. If OWNER is a string, this denotes a username and only
-tables owned by OWNER are considered. Table names are returned as a
-list of strings."
+  "Returns a list of strings representing table names in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only tables owned by users are listed. If OWNER
+is a string denoting a user name, only tables owned by OWNER are
+listed. If OWNER is :all then all tables are listed."

   (database-list-tables database :owner owner))
 
 (defun table-exists-p (name &key (owner nil) (database *default-database*))
   (database-list-tables database :owner owner))
 
 (defun table-exists-p (name &key (owner nil) (database *default-database*))

-  "Test for existence of an SQL table called NAME in DATABASE which
-defaults to *DEFAULT-DATABASE*. If OWNER is nil, only user-owned
-tables are considered. This is the default. If OWNER is :all , all
-tables are considered. If OWNER is a string, this denotes a username
-and only tables owned by OWNER are considered. Table names are
-returned as a list of strings."
+  "Tests for the existence of an SQL table called NAME in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only tables owned by users are examined. If
+OWNER is a string denoting a user name, only tables owned by
+OWNER are examined. If OWNER is :all then all tables are
+examined."

   (when (member (database-identifier name database)
                 (list-tables :owner owner :database database)
                 :test #'string-equal)
   (when (member (database-identifier name database)
                 (list-tables :owner owner :database database)
                 :test #'string-equal)


@@ -93,11 +98,12 @@ returned as a list of strings."
 
 (defun create-view (name &key as column-list (with-check-option nil)
                          (database *default-database*))
 
 (defun create-view (name &key as column-list (with-check-option nil)
                          (database *default-database*))

-  "Creates a view called NAME using the AS query and the optional
-COLUMN-LIST and WITH-CHECK-OPTION. The COLUMN-LIST argument is a list
-of columns to add to the view. The WITH-CHECK-OPTION adds 'WITH CHECK
-OPTION' to the resulting SQL. The default value of WITH-CHECK-OPTION
-is NIL. The default value of DATABASE is *DEFAULT-DATABASE*."
+  "Creates a view called NAME in DATABASE which defaults to
+*DEFAULT-DATABASE*. The view is created using the query AS and
+the columns of the view may be specified using the COLUMN-LIST
+parameter. The WITH-CHECK-OPTION is nil by default but if it has
+a non-nil value, then all insert/update commands on the view are
+checked to ensure that the new data satisfy the query AS."

   (let* ((view-name (etypecase name 
                       (symbol (sql-expression :attribute name))
                       (string (sql-expression :attribute (make-symbol name)))
   (let* ((view-name (etypecase name 
                       (symbol (sql-expression :attribute name))
                       (string (sql-expression :attribute (make-symbol name)))


@@ -111,10 +117,10 @@ is NIL. The default value of DATABASE is *DEFAULT-DATABASE*."
 
 (defun drop-view (name &key (if-does-not-exist :error)
                        (database *default-database*))
 
 (defun drop-view (name &key (if-does-not-exist :error)
                        (database *default-database*))

-  "Deletes view NAME from DATABASE which defaults to
-*DEFAULT-DATABASE*. If the view does not exist and IF-DOES-NOT-EXIST
-is :ignore then DROP-VIEW returns nil whereas an error is signalled if
-IF-DOES-NOT-EXIST is :error."
+  "Drops the view called NAME from DATABASE which defaults to
+*DEFAULT-DATABASE*. If the view does not exist and
+IF-DOES-NOT-EXIST is :ignore then DROP-VIEW returns nil whereas
+an error is signalled if IF-DOES-NOT-EXIST is :error."

   (let ((view-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore
   (let ((view-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore


@@ -126,20 +132,19 @@ IF-DOES-NOT-EXIST is :error."
       (execute-command expr :database database))))
 
 (defun list-views (&key (owner nil) (database *default-database*))
       (execute-command expr :database database))))
 
 (defun list-views (&key (owner nil) (database *default-database*))

-  "List all views in DATABASE which defaults to *DEFAULT-DATABASE*. If
-OWNER is nil, only user-owned views are considered. This is the
-default. If OWNER is :all , all views are considered. If OWNER is a
-string, this denotes a username and only views owned by OWNER are
-considered. View names are returned as a list of strings."
+  "Returns a list of strings representing view names in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only views owned by users are listed. If OWNER
+is a string denoting a user name, only views owned by OWNER are
+listed. If OWNER is :all then all views are listed."

   (database-list-views database :owner owner))
 
 (defun view-exists-p (name &key (owner nil) (database *default-database*))
   (database-list-views database :owner owner))
 
 (defun view-exists-p (name &key (owner nil) (database *default-database*))

-  "Test for existence of an SQL view called NAME in DATABASE which
-defaults to *DEFAULT-DATABASE*. If OWNER is nil, only user-owned views
-are considered. This is the default. If OWNER is :all , all views are
-considered. If OWNER is a string, this denotes a username and only
-views owned by OWNER are considered. View names are returned as a list
-of strings."
+  "Tests for the existence of an SQL view called NAME in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only views owned by users are examined. If OWNER
+is a string denoting a user name, only views owned by OWNER are
+examined. If OWNER is :all then all views are examined."

   (when (member (database-identifier name database)
                 (list-views :owner owner :database database)
                 :test #'string-equal)
   (when (member (database-identifier name database)
                 (list-views :owner owner :database database)
                 :test #'string-equal)


@@ -150,11 +155,12 @@ of strings."
 
 (defun create-index (name &key on (unique nil) attributes
                           (database *default-database*))
 
 (defun create-index (name &key on (unique nil) attributes
                           (database *default-database*))

-  "Creates an index called NAME on the table specified by ON. The
-attributes of the table to index are given by ATTRIBUTES. Setting
-UNIQUE to T includes UNIQUE in the SQL index command, specifying that
-the columns indexed must contain unique values. The default value of
-UNIQUE is nil. The default value of DATABASE is *DEFAULT-DATABASE*."
+  "Creates an index called NAME on the table specified by ON in
+DATABASE which default to *DEFAULT-DATABASE*. The table
+attributes to use in constructing the index NAME are specified by
+ATTRIBUTES. The UNIQUE argument is nil by default but if it has a
+non-nil value then the indexed attributes must have unique
+values."

   (let* ((index-name (database-identifier name database))
          (table-name (database-identifier on database))
          (attributes (mapcar #'(lambda (a) (database-identifier a database)) (listify attributes)))
   (let* ((index-name (database-identifier name database))
          (table-name (database-identifier on database))
          (attributes (mapcar #'(lambda (a) (database-identifier a database)) (listify attributes)))


@@ -166,11 +172,12 @@ UNIQUE is nil. The default value of DATABASE is *DEFAULT-DATABASE*."
 (defun drop-index (name &key (if-does-not-exist :error)
                         (on nil)
                         (database *default-database*))
 (defun drop-index (name &key (if-does-not-exist :error)
                         (on nil)
                         (database *default-database*))

-  "Deletes index NAME from table FROM in DATABASE which defaults to
-*DEFAULT-DATABASE*. If the index does not exist and IF-DOES-NOT-EXIST
-is :ignore then DROP-INDEX returns nil whereas an error is signalled
-if IF-DOES-NOT-EXIST is :error. The argument ON allows the optional
-specification of a table to drop the index from."
+  "Drops the index called NAME in DATABASE which defaults to
+*DEFAULT-DATABASE*. If the index does not exist and
+IF-DOES-NOT-EXIST is :ignore then DROP-INDEX returns nil whereas
+an error is signalled if IF-DOES-NOT-EXIST is :error. The
+argument ON allows the optional specification of a table to drop
+the index from."

   (let ((index-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore
   (let ((index-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore


@@ -187,27 +194,31 @@ specification of a table to drop the index from."
                      :database database)))
 
 (defun list-indexes (&key (owner nil) (database *default-database*))
                      :database database)))
 
 (defun list-indexes (&key (owner nil) (database *default-database*))

-  "List all indexes in DATABASE, which defaults to
-*default-database*. If OWNER is :all , all indexs are considered. If
-OWNER is a string, this denotes a username and only indexs owned by
-OWNER are considered. Index names are returned as a list of strings."
+  "Returns a list of strings representing index names in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only indexes owned by users are listed. If OWNER
+is a string denoting a user name, only indexes owned by OWNER are
+listed. If OWNER is :all then all indexes are listed."

   (database-list-indexes database :owner owner))
 
 (defun list-table-indexes (table &key (owner nil)
                                      (database *default-database*))
   (database-list-indexes database :owner owner))
 
 (defun list-table-indexes (table &key (owner nil)
                                      (database *default-database*))

-  "List all indexes in DATABASE for a TABLE, which defaults to
-*default-database*. If OWNER is :all , all indexs are considered. If
-OWNER is a string, this denotes a username and only indexs owned by
-OWNER are considered. Index names are returned as a list of strings."
+  "Returns a list of strings representing index names on the
+table specified by TABLE in DATABASE which defaults to
+*DEFAULT-DATABASE*. OWNER is nil by default which means that only
+indexes owned by users are listed. If OWNER is a string denoting
+a user name, only indexes owned by OWNER are listed. If OWNER
+is :all then all indexes are listed."

   (database-list-table-indexes (database-identifier table database)
                               database :owner owner))
   
 (defun index-exists-p (name &key (owner nil) (database *default-database*))
   (database-list-table-indexes (database-identifier table database)
                               database :owner owner))
   
 (defun index-exists-p (name &key (owner nil) (database *default-database*))

-  "Test for existence of an index called NAME in DATABASE which
-defaults to *DEFAULT-DATABASE*. If OWNER is :all , all indexs are
-considered. If OWNER is a string, this denotes a username and only
-indexs owned by OWNER are considered. Index names are returned as a
-list of strings."
+  "Tests for the existence of an SQL index called NAME in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that only indexes owned by users are examined. If
+OWNER is a string denoting a user name, only indexes owned by
+OWNER are examined. If OWNER is :all then all indexes are
+examined."

   (when (member (database-identifier name database)
                 (list-indexes :owner owner :database database)
                 :test #'string-equal)
   (when (member (database-identifier name database)
                 (list-indexes :owner owner :database database)
                 :test #'string-equal)


@@ -215,22 +226,25 @@ list of strings."
 
 ;; Attributes 
 
 
 ;; Attributes 
 

-(defvar *cache-table-queries-default* "Default atribute type caching behavior.")
+(defvar *cache-table-queries-default* nil 
+  "Specifies the default behaivour for caching of attribute
+  types. Meaningful values are t, nil and :flush as described for
+  the action argument to CACHE-TABLE-QUERIES.")

 
 (defun cache-table-queries (table &key (action nil) (database *default-database*))
 
 (defun cache-table-queries (table &key (action nil) (database *default-database*))

-  "Provides per-table control on the caching in a particular database
-connection of attribute type information using during update
-operations. If TABLE is a string, it is the name of the table for
-which caching is to be altered. If TABLE is t, then the action applies
-to all tables. If TABLE is :default, then the default caching action
-is set for those tables which do not have an explicit setting. ACTION
-specifies the caching action. The value t means cache the attribute
-type information. The value nil means do not cache the attribute type
-information. If TABLE is :default, the setting applies to all tables
-which do not have an explicit setup. The value :flush means remove any
-existing cache for table in database, but continue to cache. This
-function should be called with action :flush when the attribute
-specifications in table have changed."
+  "Controls the caching of attribute type information on the
+table specified by TABLE in DATABASE which defaults to
+*DEFAULT-DATABASE*. ACTION 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 ACTION is :flush then all existing
+type information in the cache for TABLE is removed, but caching
+is still enabled. TABLE 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 TABLE is t. Alternativly, when TABLE
+is :default, the default caching action specified by
+*CACHE-TABLE-QUERIES-DEFAULT* is applied to all table for which a
+caching action has not been explicitly set."

   (with-slots (attribute-cache) database
     (cond
       ((stringp table)
   (with-slots (attribute-cache) database
     (cond
       ((stringp table)


@@ -269,24 +283,26 @@ specifications in table have changed."
                  
 
 (defun list-attributes (name &key (owner nil) (database *default-database*))
                  
 
 (defun list-attributes (name &key (owner nil) (database *default-database*))

-  "List the attributes of a attribute called NAME in DATABASE which
-defaults to *DEFAULT-DATABASE*. If OWNER is nil, only user-owned
-attributes are considered. This is the default. If OWNER is :all , all
-attributes are considered. If OWNER is a string, this denotes a
-username and only attributes owned by OWNER are considered. Attribute
-names are returned as a list of strings. Attributes are returned as a
-list of strings."
-  (database-list-attributes (database-identifier name database) database :owner owner))
+  "Returns a list of strings representing the attributes of table
+NAME in DATABASE which defaults to *DEFAULT-DATABASE*. OWNER is
+nil by default which means that only attributes owned by users
+are listed. If OWNER is a string denoting a user name, only
+attributes owned by OWNER are listed. If OWNER is :all then all
+attributes are listed."
+  (database-list-attributes (database-identifier name database) database 
+                            :owner owner))

 
 (defun attribute-type (attribute table &key (owner nil)
                                  (database *default-database*))
 
 (defun attribute-type (attribute table &key (owner nil)
                                  (database *default-database*))

-  "Return the field type of the ATTRIBUTE in TABLE.  The optional
-keyword argument DATABASE specifies the database to query, defaulting
-to *DEFAULT-DATABASE*. If OWNER is nil, only user-owned attributes are
-considered. This is the default. If OWNER is :all , all attributes are
-considered. If OWNER is a string, this denotes a username and only
-attributes owned by OWNER are considered. Attribute names are returned
-as a list of strings. Attributes are returned as a list of strings."
+  "Returns a string representing the field type of the supplied
+attribute ATTRIBUTE in the table specified by TABLE in DATABASE
+which defaults to *DEFAULT-DATABASE*. OWNER is nil by default
+which means that the attribute specified by ATTRIBUTE, if it
+exists, must be user owned else nil is returned. If OWNER is a
+string denoting a user name, the attribute, if it exists, must be
+owned by OWNER else nil is returned, whereas if OWNER is :all
+then the attribute, if it exists, will be returned regardless of
+its owner."

   (database-attribute-type (database-identifier attribute database)
                            (database-identifier table database)
                            database
   (database-attribute-type (database-identifier attribute database)
                            (database-identifier table database)
                            database


@@ -294,14 +310,17 @@ as a list of strings. Attributes are returned as a list of strings."
 
 (defun list-attribute-types (table &key (owner nil)
                                    (database *default-database*))
 
 (defun list-attribute-types (table &key (owner nil)
                                    (database *default-database*))

-  "Returns type information for the attributes in TABLE from DATABASE
-which has a default value of *default-database*. If OWNER is nil, only
-user-owned attributes are considered. This is the default. If OWNER is
-:all, all attributes are considered. If OWNER is a string, this
-denotes a username and only attributes owned by OWNER are
-considered. Returns a list in which each element is a list (attribute
-datatype). Attribute is a string denoting the atribute name. Datatype
-is the vendor-specific type returned by ATTRIBUTE-TYPE."
+  "Returns a list containing information about the SQL types of
+each of the attributes in the table specified by TABLE in
+DATABASE which has a default value of *DEFAULT-DATABASE*. OWNER
+is nil by default which means that only attributes owned by users
+are listed. If OWNER is a string denoting a user name, only
+attributes owned by OWNER are listed. If OWNER is :all then all
+attributes are listed. The elements of the returned list are
+lists where the first element is the name of the attribute, the
+second element is its SQL type, the third is the type precision,
+the fourth is the scale of the attribute and the fifth is 1 if
+the attribute accepts null values and otherwise 0."

   (with-slots (attribute-cache) database
     (let ((table-ident (database-identifier table database)))
       (multiple-value-bind (val found) (gethash table-ident attribute-cache)
   (with-slots (attribute-cache) database
     (let ((table-ident (database-identifier table database)))
       (multiple-value-bind (val found) (gethash table-ident attribute-cache)


@@ -311,23 +330,27 @@ is the vendor-specific type returned by ATTRIBUTE-TYPE."
                                     (cons attribute
                                           (multiple-value-list
                                            (database-attribute-type
                                     (cons attribute
                                           (multiple-value-list
                                            (database-attribute-type

-                                            (database-identifier attribute database)
+                                            (database-identifier attribute 
+                                                                  database)

                                             table-ident
                                             database
                                             :owner owner))))
                                             table-ident
                                             database
                                             :owner owner))))

-                                (list-attributes table :database database :owner owner))))
+                                (list-attributes table :database database 
+                                                  :owner owner))))

              (cond
                ((and (not found) (eq t *cache-table-queries-default*))
              (cond
                ((and (not found) (eq t *cache-table-queries-default*))

-                (setf (gethash table-ident attribute-cache) (list :unspecified types)))
+                (setf (gethash table-ident attribute-cache) 
+                       (list :unspecified types)))

                ((and found (eq t (first val)) 
                ((and found (eq t (first val)) 

-                     (setf (gethash table-ident attribute-cache) (list t types)))))
+                     (setf (gethash table-ident attribute-cache) 
+                            (list t types)))))

              types))))))
   
 
 ;; Sequences 
 
 (defun create-sequence (name &key (database *default-database*))
              types))))))
   
 
 ;; Sequences 
 
 (defun create-sequence (name &key (database *default-database*))

-  "Create a sequence called NAME in DATABASE which defaults to
+  "Creates a sequence called NAME in DATABASE which defaults to

 *DEFAULT-DATABASE*."
   (let ((sequence-name (database-identifier name database)))
     (database-create-sequence sequence-name database))
 *DEFAULT-DATABASE*."
   (let ((sequence-name (database-identifier name database)))
     (database-create-sequence sequence-name database))


@@ -335,10 +358,10 @@ is the vendor-specific type returned by ATTRIBUTE-TYPE."
 
 (defun drop-sequence (name &key (if-does-not-exist :error)
                            (database *default-database*))
 
 (defun drop-sequence (name &key (if-does-not-exist :error)
                            (database *default-database*))

-  "Drops sequence NAME from DATABASE which defaults to
+  "Drops the sequence called NAME from DATABASE which defaults to

 *DEFAULT-DATABASE*. If the sequence does not exist and
 *DEFAULT-DATABASE*. If the sequence does not exist and

-IF-DOES-NOT-EXIST is :ignore then DROP-SEQUENCE returns nil whereas an
-error is signalled if IF-DOES-NOT-EXIST is :error."
+IF-DOES-NOT-EXIST is :ignore then DROP-SEQUENCE returns nil
+whereas an error is signalled if IF-DOES-NOT-EXIST is :error."

   (let ((sequence-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore
   (let ((sequence-name (database-identifier name database)))
     (ecase if-does-not-exist
       (:ignore


@@ -349,38 +372,40 @@ error is signalled if IF-DOES-NOT-EXIST is :error."
   (values))
 
 (defun list-sequences (&key (owner nil) (database *default-database*))
   (values))
 
 (defun list-sequences (&key (owner nil) (database *default-database*))

-  "List all sequences in DATABASE, which defaults to
-*default-database*. If OWNER is nil, only user-owned sequences are
-considered. This is the default. If OWNER is :all , all sequences are
-considered. If OWNER is a string, this denotes a username and only
-sequences owned by OWNER are considered. Sequence names are returned
-as a list of strings."
+  "Returns a list of strings representing sequence names in
+DATABASE which defaults to *DEFAULT-DATABASE*. OWNER is nil by
+default which means that only sequences owned by users are
+listed. If OWNER is a string denoting a user name, only sequences
+owned by OWNER are listed. If OWNER is :all then all sequences
+are listed."

   (database-list-sequences database :owner owner))
 
 (defun sequence-exists-p (name &key (owner nil)
                                (database *default-database*))
   (database-list-sequences database :owner owner))
 
 (defun sequence-exists-p (name &key (owner nil)
                                (database *default-database*))

-  "Test for existence of a sequence called NAME in DATABASE which
-defaults to *DEFAULT-DATABASE*."
+  "Tests for the existence of an SQL sequence called NAME in
+DATABASE which defaults to *DEFAULT-DATABASE*. OWNER is nil by
+default which means that only sequences owned by users are
+examined. If OWNER is a string denoting a user name, only
+sequences owned by OWNER are examined. If OWNER is :all then all
+sequences are examined."

   (when (member (database-identifier name database)
                 (list-sequences :owner owner :database database)
                 :test #'string-equal)
     t))
   
 (defun sequence-next (name &key (database *default-database*))
   (when (member (database-identifier name database)
                 (list-sequences :owner owner :database database)
                 :test #'string-equal)
     t))
   
 (defun sequence-next (name &key (database *default-database*))

-  "Return the next value in the sequence NAME in DATABASE."
+  "Return the next value in the sequence called NAME in DATABASE
+  which defaults to *DEFAULT-DATABASE*."

   (database-sequence-next (database-identifier name database) database))
 
 (defun set-sequence-position (name position &key (database *default-database*))
   (database-sequence-next (database-identifier name database) database))
 
 (defun set-sequence-position (name position &key (database *default-database*))

-  "Explicitly set the the position of the sequence NAME in DATABASE to
-POSITION."
-  (database-set-sequence-position (database-identifier name database) position database))
+  "Explicitly set the the position of the sequence called NAME in
+DATABASE, which defaults to *DEFAULT-DATABSE*, to POSITION."
+  (database-set-sequence-position (database-identifier name database) 
+                                  position database))

 
 (defun sequence-last (name &key (database *default-database*))
 
 (defun sequence-last (name &key (database *default-database*))

-  "Return the last value of the sequence NAME in DATABASE."
+  "Return the last value of the sequence called NAME in DATABASE
+  which defaults to *DEFAULT-DATABASE*."

   (database-sequence-last (database-identifier name database) database))
 
   (database-sequence-last (database-identifier name database) database))
 

-;;; Remote Joins
-
-(defvar *default-update-objects-max-len* nil
-  "The default maximum number of objects supplying data for a query when updating remote joins.")
-