From 3a45ae325932b9565993407c5c94b28cdefd1f14 Mon Sep 17 00:00:00 2001 From: "Kevin M. Rosenberg" Date: Wed, 7 Jul 2004 18:04:32 +0000 Subject: [PATCH] r9740: documentation additions --- ChangeLog | 1 + doc/global-index.xml | 2 +- doc/ref-ooddl.xml | 472 ++++++++++++++++++++++++++++++++++--------- doc/ref-oodml.xml | 73 ++++--- 4 files changed, 429 insertions(+), 119 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6bdb6fa..fc2e0b7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,4 +1,5 @@ 7 Jul 2004 Kevin Rosenberg + * doc/ref-ooddl.xml, doc-ref-oodml.xml: documentation additions * sql/ooddl.lisp: Added SMALLINT type * sql/generic-postgresql.lisp: Added INT2 as SMALLINT type * db-mysql/mysql-objects.lisp: Added SMALLINT type diff --git a/doc/global-index.xml b/doc/global-index.xml index 766d859..b7a4110 100644 --- a/doc/global-index.xml +++ b/doc/global-index.xml @@ -19,7 +19,7 @@ *DEFAULT-DATABASE* *DEFAULT-DATABASE-TYPE* *DEFAULT-UPDATE-OBJECTS-MAX-LEN* - *DEFAULT-STRING-LENGTH* + *DEFAULT-STRING-LENGTH* *INITIALIZED-DATABASE-TYPES* diff --git a/doc/ref-ooddl.xml b/doc/ref-ooddl.xml index da340c7..e61a1cc 100644 --- a/doc/ref-ooddl.xml +++ b/doc/ref-ooddl.xml @@ -9,9 +9,24 @@ Object Oriented Data Definition Language (OODDL) - - - + + The Object Oriented Data Definition Language (OODDL) provides + access to relational SQL tables using Common Lisp Object System + (CLOS) objects. SQL tables are mapped to CLOS objects with the + SQL columns being mapped to slots of the CLOS object. + + + The mapping between SQL tables and CLOS objects is defined + with the macro def-view-class. SQL + tables are created with create-view-from-class + and SQL tables can be deleted with drop-view-from-class. + + The above functions refer to the Lisp view of the SQL + table. This Lisp view should not be confused with SQL VIEW statement. + @@ -42,16 +57,18 @@ Slots - slot VIEW-DATABASE is of type T + slot VIEW-DATABASE is of type (OR NULL DATABASE) + which stores the associated database for the + instance. - + *DEFAULT-STRING-LENGTH* - Default length of SQL strings + Default length of SQL strings. Variable @@ -62,14 +79,14 @@ Initial Value - 255 + 255 Description If a slot of a class defined by DEF-VIEW-CLASS is of the type - STRING or VARCHAR and does + STRING or VARCHAR and does not have a length specified, then the value of this variable is used as SQL length. @@ -91,7 +108,7 @@ Affected By - Some SQL backends do not support VARCHAR + Some SQL backends do not support VARCHAR lengths greater than 255 . @@ -107,18 +124,42 @@ CREATE-VIEW-FROM-CLASS - Create a SQL table from Lisp class + Create a SQL table from a view class. Function Syntax - (CREATE-VIEW-FROM-CLASS VIEW-CLASS-NAME &KEY (DATABASE *DEFAULT-DATABASE*) (TRANSACTIONS T)) [function] => + (create-view-from-class view-class-name &key (database *default-database*) (transactions t)) => Arguments and Values - + + view-class-name + + + The name of a view class that has been defined with + def-view-class. + + + + + database + + + The database in which to create the SQL table. + + + + + transactions + + + When &nil; specifies that a table type which does not support transactions should be used. + + + @@ -131,7 +172,11 @@ Examples - + * (def-view-class 'foo () ((a :type (string 80)))) + #<CLSQL-SYS::STANDARD-DB-CLASS FOO> + * (create-view-from-class 'foo) + * (list-tables) + ("FOO") @@ -143,29 +188,35 @@ Affected by - - - + Most SQL database systems will signal an error if a table + creation is attempted when a table with the same name already + exists. The SQL user, as specified in the database connection, + must have sufficient permission for table creation. Exceptional Situations - + A condition will be signaled if the table can not be created + in the SQL database. See Also - - + def-view-class + drop-view-from-class + Notes - + Currently, only &mysql; supports transactionless + tables. &clsql; provides the ability to create such tables for + applications which would benefit from faster table access and + do not require transaction support. @@ -173,57 +224,233 @@ DEF-VIEW-CLASS - - Function + Defines CLOS classes with mapping to SQL database. + Macro Syntax - (DEF-VIEW-CLASS CLASS SUPERS SLOTS &REST CL-OPTIONS) [macro] => + (def-view-class name superclasses slots &rest class-options) [macro] => class Arguments and Values - + + name + + + The class name. + + + + + name + + + The superclasses for the defined class. + + + + + slots + + + The class slot definitions. + + + + + class + + + The defined class. + + + + + Slot Options + + + + :db-kind - specifies the kind of + DB mapping which is performed for this slot and defaults + to :base which indicates that the + slot maps to an ordinary column of the database table. A + :db-kind value of + :key indicates that this slot is + a special kind of :base slot + which maps onto a column which is one of the unique keys + for the database table, the value + :join indicates this slot + represents a join onto another View Class which contains + View Class objects, and the value + :virtual indicates a standard + CLOS slot which does not map onto columns of the + database table. + + + + + :db-info - if a slot is specified with + :db-kind :join, the + slot option :db-info contains a list + which specifies the nature of the join. + + + + + :type - for slots of + :db-kind :base or + :key, the :type slot + option has a special interpretation such that Lisp + types, such as string, integer and float are + automatically converted into appropriate SQL types for + the column onto which the slot maps. This behaviour may + be overridden using the :db-type slot + option. The valid values are: + + + string - a variable length character field up to + *default-string-length* characters. + + + (string n) - a fixed length character field + n characters long. + + + varchar - a variable length character field up to + *default-string-length* characters. + + + (varchar n) - a variable length character field up to + n characters in length. + + + char - a single character field + + integer - signed integer at least 32-bits wide + (integer n) + float + (float n) + long-float + number + (number n) + (number n p) + + smallint - An integer column 16-bits + wide. [not supported by all database backends] + + + bigint - An integer column + 64-bits wide. [not supported by all database backends] + + + universal-time - an integer + field sufficiently wide to store a + universal-time. On most databases, a slot of this + type assigned a SQL type of + BIGINT + + + wall-time - a slot which + stores a date and time in a SQL timestamp + column. &clsql; provides a number of time + manipulation functions to support objects of type + wall-time. + + + duration - stores a duration structure. + &clsql; provides routines for wall-time and duration + processing. + + boolean - stores a &t; or &nil; value. + + generalized-boolean - similar + to a boolean in that either a + &t; or &nil; value is stored in the SQL + database. However, any Lisp object can be stored in + the Lisp object. A Lisp value of &nil; is stored as + FALSE in the database, any + other Lisp value is stored as + TRUE. + + + keyword - stores a keyword + + symbol - stores a symbol + + list - stores a list by writing it to a string. The items + in the list must be able to be readable written. + + vector - stores a vector similarly to list + array - stores a array similarly to list + + + + + + + :column - specifies the name of + the SQL column which the slot maps onto, if + :db-kind is not + :virtual, and defaults to the + slot name. + + + + + :void-value - specifies + the value to store in the Lisp instance if the SQL value is NULL and defaults + to NIL. + + + + + :db-constraints - is a string + representing an SQL table constraint expression or a + list of such strings. + + + + + :db-type - a string to specify the SQL + column type. If specified, this string overrides the SQL + column type as computed from the :type + slot value. + + + + + + Class Options + + + + + :base-table - specifies the name of the + SQL database table. The default value is the class name. + + + + + Description - Creates a View Class called CLASS whose slots SLOTS can - map onto the attributes of a table in a database. If SUPERS is - nil then the superclass of CLASS will be STANDARD-DB-OBJECT, - otherwise SUPERS is a list of superclasses for CLASS which - must include STANDARD-DB-OBJECT or a descendent of this - class. The syntax of DEFCLASS is extended through the addition - of a class option :base-table which defines the database table - onto which the View Class maps and which defaults to - CLASS. The DEFCLASS syntax is also extended through additional - slot options. The :db-kind slot option specifies the kind of - DB mapping which is performed for this slot and defaults to - :base which indicates that the slot maps to an ordinary column - of the database table. A :db-kind value of :key indicates that - this slot is a special kind of :base slot which maps onto a - column which is one of the unique keys for the database table, - the value :join indicates this slot represents a join onto - another View Class which contains View Class objects, and the - value :virtual indicates a standard CLOS slot which does not - map onto columns of the database table. If a slot is specified - with :db-kind :join, the slot option :db-info contains a list - which specifies the nature of the join. For slots of :db-kind - :base or :key, the :type slot option has a special - interpretation such that Lisp types, such as string, integer - and float are automatically converted into appropriate SQL - types for the column onto which the slot maps. This behaviour - may be over-ridden using the :db-type slot option which is a - string specifying the vendor-specific database type for this - slot's column definition in the database. The :column slot - option specifies the name of the SQL column which the slot - maps onto, if :db-kind is not :virtual, and defaults to the - slot name. The :void-value slot option specifies the value to - store if the SQL value is NULL and defaults to NIL. The - :db-constraints slot option is a string representing an SQL - table constraint expression or a list of such strings. + + Creates a View Class called NAME whose + slots SLOTS can map onto the attributes + of a table in a database. If + SUPERCLASSES is &nil; then the + superclass of CLASS will be + STANDARD-DB-OBJECT, otherwise + SUPERCLASSES is a list of superclasses + for CLASS which must include + STANDARD-DB-OBJECT or a descendent of this + class. + Examples @@ -233,36 +460,39 @@ Side Effects - - - + Creates a new CLOS class. Affected by - - - + Nothing. Exceptional Situations - + None. See Also - + create-view-from-class + standard-db-object + drop-view-from-class Notes - + The actual SQL type for a column depends up the database type + in which the SQL table is stored. As an example, the view + class type (varchar 100) specifies a + SQL column type VARCHAR(100) in &mysql; + and a column type VARCHAR2(100) in + &oracle; @@ -270,58 +500,71 @@ DROP-VIEW-FROM-CLASS - + Delete table from SQL database. Function Syntax - (DROP-VIEW-FROM-CLASS VIEW-CLASS-NAME &KEY (DATABASE *DEFAULT-DATABASE*)) [function] => + (drop-view-from-class view-class-name &key (database *default-database*)) => Arguments and Values - + + view-class-name + + + The name of the view class. + + + Description Removes a table defined by the View Class - VIEW-CLASS-NAME from DATABASE which defaults to - *DEFAULT-DATABASE*. + VIEW-CLASS-NAME from + DATABASE which defaults to + *DEFAULT-DATABASE*. Examples - + * (list-tables) + ("FOO" "BAR") + * (drop-view-from-class 'foo) + * (list-tables) + ("BAR") Side Effects - + Deletes a table from the SQL database. Affected by - - - + Whether the specified table exists in the SQL database. Exceptional Situations - + A condition may be signalled if the table does not exist in + the SQL database or if the SQL connection does not have + sufficient permissions to delete tables. See Also - + create-view-from-class + def-view-class @@ -336,62 +579,103 @@ LIST-CLASSES - + List classes for tables in SQL database. Function Syntax - (LIST-CLASSES &KEY (TEST #'IDENTITY) (ROOT-CLASS (FIND-CLASS 'STANDARD-DB-OBJECT)) (DATABASE *DEFAULT-DATABASE*)) [function] => + (list-classes &key (test #'identity) (root-class (find-class 'standard-db-object)) (database *default-database*)) => classes Arguments and Values - + + test + + + a function used to filter the search. By default, identity is used which + will return all classes. + + + + + root-class + + + specifies the root class to the search. By default, standard-db-object is used + which is the root for all view classes. + + + + + database + + + The database to search for view classes. + + + + + classes + + + List of view classes. + + + Description - Returns a list of all the View Classes which - are connected to DATABASE, which defaults to - *DEFAULT-DATABASE*, and which descend from the class - ROOT-CLASS and which satisfy the function TEST. By - default ROOT-CLASS is STANDARD-DB-OBJECT and TEST is - IDENTITY. + Returns a list of all the View Classes which have been + defined in the Lisp session and are connected to + DATABASE, which defaults to + *DEFAULT-DATABASE*, and which descended + from the class ROOT-CLASS and which satisfy the function + TEST. By default ROOT-CLASS is STANDARD-DB-OBJECT and + TEST is IDENTITY. Examples - + * (list-classes) + (#<clsql-sys::standard-db-class big> #<clsql-sys::standard-db-class employee-address> + #<clsql-sys::standard-db-class address> #<clsql-sys::standard-db-class company> + #<clsql-sys::standard-db-class employee>) + + * (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3))) + (#<clsql-sys::standard-db-class employee-address> #<clsql-sys::standard-db-class address> + #<clsql-sys::standard-db-class company> #<clsql-sys::standard-db-class employee>) Side Effects - + None. Affected by - + Which view classes have been defined in the Lisp session. Exceptional Situations - + None. See Also - - + def-view-class + diff --git a/doc/ref-oodml.xml b/doc/ref-oodml.xml index f068a5d..4a5900c 100644 --- a/doc/ref-oodml.xml +++ b/doc/ref-oodml.xml @@ -17,27 +17,37 @@ *DB-AUTO-SYNC* - + Enables SQL storage during Lisp object creation. Variable Value Type - + Boolean Initial Value - nil + &nil; Description - + When this variable is &t; an instance is stored in the SQL database when the instance is created + by make-instance. When this variable is &nil;, which is the default value, &clsql; + behaves like &commonsql;: instances of view classes are stored to the SQL database only when + update-record-from-slots + is called. Examples - + (let ((instance (make-instance 'foo))) + (update-record-from-slots instance)) + + ;; is equivalent to + + (let ((*db-auto-sync* t)) + (make-instance 'foo)) @@ -46,7 +56,9 @@ See Also - None. + + update-record-from-slots + Notes @@ -57,27 +69,31 @@ *DEFAULT-UPDATE-OBJECTS-MAX-LEN* - + The default maximum number of objects each query to perform a join Variable Value Type - + (or null integer) Initial Value - nil + &nil; Description - + + This special variable provides the default value for the + max-len argument of the function update-object-joins. + Examples - + (setq *default-update-objects-max-len* 100) @@ -97,13 +113,13 @@ DELETE-INSTANCE-RECORDS - + Delete SQL records represented by a view class object Function Syntax - (DELETE-INSTANCE-RECORDS OBJECT) [generic] => + (delete-instance-records object) => Arguments and Values @@ -122,41 +138,50 @@ Examples - + * (def-view-class tab () ((a :type integer :db-kind :key) (b :type string))) + #<clsql-sys::db-standard-class tab> + * (defvar obj (let ((*db-auto-sync* t)) + (make-instance 'tab :a 5 :b "the string"))) + * (start-sql-recording :type :both) + * (delete-instance-records obj) + + Side Effects - + Deletes data from the SQL database. Affected by - - - + Permissions granted by the SQL database to the user in the database connection. Exceptional Situations - + An exception may be signaled if the database connection user does not have + sufficient privileges to modify the database. See Also - - - + + update-records + update-records-from-instance + Notes - + Instances are referenced in the database by values stored in the key slots. If + delete-records-from-instance is called with an instance of a class that does + not contain any keys, then all records in that table will be deleted. @@ -170,7 +195,7 @@ Syntax - (INSTANCE-REFRESHED OBJECT) [generic] => + (instance-refreshed object) => Arguments and Values -- 2.34.1