Object Oriented Data Manipulation Language (OODML)
-
+ Object Oriented Data Manipulation Language (OODML) provides a Common Lisp
+ Object System (CLOS) interface to SQL databases. View classes are defined with
+ the OODDL interface and objects are read and
+ written with the OODML.
+
+
+ The main function for reading data with the OODML is the select
+ function. The select is also used in the
+ FDML. However, when select is given a view
+ class name, it returns a list of instances of view classes.
+
+
+ View class instances can be updated to reflect any changes in
+ the database with the functions update-slot-from-record
+ and update-instance-from-records.
+
+ To update the database to reflect changes made to instances of view classes, use the functions update-records-from-instance,
+ update-record-from-slot, and
+ update-record-from-slots.
+
+
+ The function delete-instance-records
+ deletes the records corresponding to an instance of a view
+ class.
*DB-AUTO-SYNC*
-
+ Enables SQL storage during Lisp object creation.VariableValue Type
-
+ Boolean
Initial Value
- nil
+ &nil;
- Description
-
+ 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 +91,9 @@
See Also
- None.
+
+ update-record-from-slots
+ Notes
@@ -57,27 +104,31 @@
*DEFAULT-UPDATE-OBJECTS-MAX-LEN*
-
+ The default maximum number of objects each query to perform a joinVariableValue 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)
@@ -86,7 +137,9 @@
See Also
- None.
+
+ update-object-joins
+ Notes
@@ -97,66 +150,82 @@
DELETE-INSTANCE-RECORDS
-
+ Delete SQL records represented by a view class
+ object.FunctionSyntax
- (DELETE-INSTANCE-RECORDS OBJECT) [generic] =>
+ (delete-instance-records object) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+ Description
- Deletes the records represented by OBJECT in the
- appropriate table of the database associated with OBJECT. If
- OBJECT is not yet associated with a database, an error is
- signalled.
+ Deletes the records represented by
+ object in the appropriate table of the
+ database associated with object. If
+ object is not yet associated with a
+ database, an error is signalled.
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.
@@ -164,30 +233,39 @@
INSTANCE-REFRESHED
-
- Function
+ User hook to call on object refresh.
+ Generic functionSyntax
- (INSTANCE-REFRESHED OBJECT) [generic] =>
+ (instance-refreshed object) => Arguments and Values
-
+
+ object
+
+
+ The view class object which is being refreshed.
+
+
+ Description
- Provides a hook which is called within an object
- oriented call to SELECT with a non-nil value of REFRESH when
- the View Class instance OBJECT has been updated from the
- database. A method specialised on STANDARD-DB-OBJECT is
- provided which has no effects. Methods specialised on
- particular View Classes can be used to specify any operations
- that need to be made on View Classes instances which have been
- updated in calls to SELECT.
+ Provides a hook which is called within an object oriented
+ call to select with a non-nil value of
+ refresh when the View Class instance
+ object has been updated from the
+ database. A method specialised on
+ standard-db-object is provided which has no
+ effects. Methods specialised on particular View Classes can be
+ used to specify any operations that need to be made on View
+ Classes instances which have been updated in calls to
+ select.
@@ -199,64 +277,67 @@
Side Effects
-
-
-
-
- Affected by
-
-
-
-
+ The user hook function may cause side effects.
Exceptional Situations
-
+ None.
See Also
-
+ select
-
- Notes
-
-
-
- UPDATE-INSTANCE-FROM-RECORDS
-
+ Update slot values from database.FunctionSyntax
- (UPDATE-INSTANCE-FROM-RECORDS OBJECT &KEY DATABASE) [generic] =>
+ (update-instance-from-records object &key database) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+
+
+ database
+
+
+ A database connection.
+
+
+ DescriptionUpdates the slot values of the View Class instance
- OBJECT using the attribute values of the appropriate table of
- DATABASE which defaults to the database associated with OBJECT
- or, if OBJECT is not associated with a database,
- *DEFAULT-DATABASE*. Join slots are updated but instances of
- the class on which the join is made are not updated.
+ object using the attribute values of the
+ appropriate table of database which
+ defaults to the database associated with
+ object or, if object is not associated
+ with a database, *default-database*. Join slots are updated but
+ instances of the class on which the join is made are not
+ updated.
@@ -268,29 +349,26 @@
Side Effects
-
+ Slot values of object may be modified.
Affected by
-
+ Data in SQL database.Exceptional Situations
-
+ If database is not able to be read.
See Also
-
-
-
@@ -304,37 +382,74 @@
UPDATE-OBJECTS-JOINS
-
+ Updates joined slots of objects.FunctionSyntax
- (UPDATE-OBJECTS-JOINS OBJECTS &KEY (SLOTS T) (FORCE-P T) CLASS-NAME (MAX-LEN *DEFAULT-UPDATE-OBJECTS-MAX-LEN*)) [function] =>
+ (update-objects-joins objects &key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*)) => Arguments and Values
-
+
+ objects
+
+
+ A list of instances of a view class.
+
+
+
+
+ slots
+
+
+
+
+
+
+ force-p
+
+
+
+
+
+
+ class-name
+
+
+ A list of instances of a view class.
+
+
+
+
+ max-len
+
+
+
+
+ Description
- Updates from the records of the appropriate
- database tables the join slots specified by SLOTS in
- the supplied list of View Class instances OBJECTS.
- SLOTS is t by default which means that all join slots
- with :retrieval :immediate are updated. CLASS-NAME is
- used to specify the View Class of all instance in
- OBJECTS and default to nil which means that the class
- of the first instance in OBJECTS is used. FORCE-P is t
- by default which means that all join slots are updated
- whereas a value of nil means that only unbound join
- slots are updated. MAX-LEN defaults to
- *DEFAULT-UPDATE-OBJECTS-MAX-LEN* and when non-nil
- specifies that UPDATE-OBJECT-JOINS may issue multiple
- database queries with a maximum of MAX-LEN instances
- updated in each query.
+ Updates from the records of the appropriate database
+ tables the join slots specified by slots
+ in the supplied list of View Class instances
+ objects. slots
+ when &t; means that all join slots with :retrieval :immediate
+ are updated. class-name is used to
+ specify the View Class of all instance in
+ objects, when &nil; then the class of the
+ first instance in objects is
+ used. force-p when &t; means that all
+ join slots are updated whereas a value of &nil; means that only
+ unbound join slots are updated. max-len
+ when non-nil specifies that
+ update-object-joins may issue multiple
+ database queries with a maximum of
+ max-len instances updated in each query.
@@ -353,21 +468,23 @@
Affected by
-
-
+ *default-update-objects-max-len*
+
Exceptional Situations
-
+ Database errors.
See Also
-
+ *default-update-objects-max-len*
@@ -382,31 +499,57 @@
UPDATE-RECORD-FROM-SLOT
-
+ Updates database from slot value.FunctionSyntax
- (UPDATE-RECORD-FROM-SLOT OBJECT SLOT &KEY DATABASE) [generic] =>
+ (update-record-from-slot object slot &key database) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+
+
+ slot
+
+
+ The name of a slot in object.
+
+
+
+
+ database
+
+
+ A database connection.
+
+
+ Description
- Updates the value stored in the column represented by
- the slot, specified by the CLOS slot name SLOT, of View Class
- instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
+ Updates the value stored in the column represented by the
+ slot, specified by the CLOS slot name
+ slot, of View Class instance
+ object. database
specifies the database in which the update is made only if
- OBJECT is not associated with a database. In this case, a
- record is created in DATABASE and the attribute represented by
- SLOT is initialised from the value of the supplied slots with
- other attributes having default values. Furthermore, OBJECT
- becomes associated with DATABASE.
+ object is not associated with a
+ database. In this case, a record is created in
+ database and the attribute represented by
+ slot is initialised from the value of the
+ supplied slots with other attributes having default
+ values. Furthermore, object becomes
+ associated with database.
@@ -418,33 +561,32 @@
Side Effects
-
+ Modifies database.
- Affected by
+ Affected By
-
-
-
+ Nothing.
Exceptional Situations
-
+ Database errors.
See Also
-
+ update-record-from-slots
+ update-records-from-instance
- Notes
+ notes
@@ -453,33 +595,58 @@
- UPDATE-RECORD-FROM-SLOTS
-
- Function
+ update-record-from-slots
+ update database from slots of view class object.
+ function
- Syntax
+ syntax
- (UPDATE-RECORD-FROM-SLOTS OBJECT SLOTS &KEY DATABASE) [generic] =>
+ (update-record-from-slots object slots &key (database *default-database*)) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+
+
+ slots
+
+
+ A list of slot names in object.
+
+
+
+
+ database
+
+
+ A database connection.
+
+
+ DescriptionUpdates the values stored in the columns represented by
- the slots, specified by the CLOS slot names SLOTS, of View
- Class instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE*
- and specifies the database in which the update is made only if
- OBJECT is not associated with a database. In this case, a
- record is created in the appropriate table of DATABASE and the
- attributes represented by SLOTS are initialised from the
- values of the supplied slots with other attributes having
- default values. Furthermore, OBJECT becomes associated with
- DATABASE.
+ the slots, specified by the clos slot names
+ slots, of view class instance
+ object. database
+ specifies the database in which the update is made only if
+ object is not associated with a
+ database. In this case, a record is created in the appropriate
+ table of database and the attributes
+ represented by slots are initialised from
+ the values of the supplied slots with other attributes having
+ default values. Furthermore, object
+ becomes associated with database.
@@ -491,28 +658,27 @@
Side Effects
-
+ Modifies the SQL database.
Affected by
-
-
-
+ Nothing.
Exceptional Situations
-
+ Database errors.
See Also
-
+ update-record-from-slot
+ update-records-from-instance
@@ -528,29 +694,47 @@
UPDATE-RECORDS-FROM-INSTANCE
-
+ Update database from view class object.FunctionSyntax
- (UPDATE-RECORDS-FROM-INSTANCE OBJECT &KEY DATABASE) [generic] =>
+ (update-records-from-instance object &key (database *default-database*)) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+
+
+ database
+
+
+ A database connection.
+
+
+ Description
- Using an instance of a View Class, OBJECT, update the
- table that stores its instance data. DATABASE defaults to
- *DEFAULT-DATABASE* and specifies the database in which the
- update is made only if OBJECT is not associated with a
+ Using an instance of a View Class,
+ object, update the table that stores its
+ instance data. database specifies the
+ database in which the update is made only if
+ object is not associated with a
database. In this case, a record is created in the appropriate
- table of DATABASE using values from the slot values of OBJECT,
- and OBJECT becomes associated with DATABASE.
+ table of database using values from the
+ slot values of object, and
+ object becomes associated with
+ database.
@@ -562,28 +746,27 @@
Side Effects
-
+ Modifies the database.
Affected by
-
-
-
+ Nothing.
Exceptional Situations
-
+ Database errors.
See Also
-
+ update-record-from-slot
+ update-record-from-slots
@@ -598,29 +781,55 @@
UPDATE-SLOT-FROM-RECORD
-
+ Update objects slot from database.FunctionSyntax
- (UPDATE-SLOT-FROM-RECORD OBJECT SLOT &KEY DATABASE) [generic] =>
+ (update-slot-from-record object slot &key (database *default-database*)) => Arguments and Values
-
+
+ object
+
+
+ An instance of a view class.
+
+
+
+
+ slot
+
+
+ The name of a slot in object.
+
+
+
+
+ database
+
+
+ A database connection.
+
+
+ DescriptionUpdates the slot value, specified by the CLOS slot name
- SLOT, of the View Class instance OBJECT using the attribute
- values of the appropriate table of DATABASE which defaults to
- the database associated with OBJECT or, if OBJECT is not
- associated with a database, *DEFAULT-DATABASE*. Join slots
- are updated but instances of the class on which the join is
- made are not updated.
+ slot, of the View Class instance
+ object using the attribute values of the
+ appropriate table of database which
+ defaults to the database associated with
+ object or, if
+ object is not associated with a database,
+ *default-database*. Join slots are updated
+ but instances of the class on which the join is made are not
+ updated.
@@ -632,29 +841,26 @@
Side Effects
-
+ Modifies the slot value of the object.
Affected by
-
+ Data in SQL database.Exceptional Situations
-
+ Database errors.
See Also
-
-
-