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.
+ 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
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.
+ make-instance. Furthermore, the
+ appropriate database records are updated whenever the slots of
+ a View Class
+ instance are modified.
+
+
+ When this variable is &nil;, which is the default value,
+ &clsql; behaves like &commonsql;: instances of view classes
+ are stored or updated in the SQL database only when update-record-from-instance,
+ update-record-from-slot
+ or update-record-from-slots
+ are called.
Examples
(let ((instance (make-instance 'foo)))
- (update-record-from-slots instance))
+ (update-records-from-instance instance))
;; is equivalent to
(let ((*db-auto-sync* t))
(make-instance 'foo))
+
+ ;; and
+
+ (progn
+ (setf (slot-value instance 'bar) "baz")
+ (update-record-from-slot instance 'bar))
+
+ ;; is equivalent to
+
+ (let ((*db-auto-sync* t))
+ (setf (slot-value instance 'bar) "baz"))
@@ -92,43 +113,50 @@
See Also
+ update-records-from-instance
+ update-record-from-slotupdate-record-from-slotsNotes
- None.
+ This is a CLSQL extension to the CommonSQL API.
-
+
- *DEFAULT-UPDATE-OBJECTS-MAX-LEN*
- The default maximum number of objects each query to perform a join
+ *DEFAULT-CACHING*
+ Controls the default caching behavior.VariableValue Type
- (or null integer)
+ Boolean
Initial Value
- &nil;
+ &t;
- Description
+ Description
- This special variable provides the default value for the
- max-len argument of the function update-object-joins.
-
+ This variable stores the default value of the
+ CACHING keyword for the select.
+
Examples
- (setq *default-update-objects-max-len* 100)
+ (let ((*default-caching* nil)))
+ (select 'foo))
+
+ ;; is equivalent to
+
+ (select 'foo :caching nil)
@@ -138,97 +166,60 @@
See Also
- update-object-joins
+ select
- Notes
- None.
+ NotesThis is a CLSQL extension to the
+ &commonsql; API. &commonsql; has caching on at all times.
-
+
- DELETE-INSTANCE-RECORDS
- Delete SQL records represented by a view class
- object.
- Function
+ *DEFAULT-UPDATE-OBJECTS-MAX-LEN*
+ The default maximum number of objects each query to perform a join
+ Variable
- Syntax
-
- (delete-instance-records object) =>
+ Value Type
+
+ (or null integer)
+
- Arguments and Values
-
-
- object
-
-
- An instance of a view class.
-
-
-
-
+ Initial Value
+ &nil;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.
+
+ This special variable provides the default value for the
+ max-len argument of the function update-object-joins.
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)
+ (setq *default-update-objects-max-len* 100)
- 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.
-
+ Affected By
+ None.See Also
-
-
- update-records
- update-records-from-instance
-
-
+
+ update-object-joins
+ 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.
-
+ None.
-
+
@@ -239,7 +230,7 @@
Syntax
- (instance-refreshed object) =>
+ instance-refreshedobject => Arguments and Values
@@ -248,7 +239,7 @@
object
- The view class object which is being refreshed.
+ The View Class object which is being refreshed.
@@ -258,7 +249,8 @@
DescriptionProvides a hook which is called within an object oriented
call to select with a non-nil value of
- refresh when the View Class instance
+ 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
@@ -271,7 +263,29 @@
Examples
-
+(slot-value employee1 'email)
+=> "lenin@soviet.org"
+(defmethod instance-refreshed ((e employee))
+ (format t "~&Details for ~A ~A have been updated from the database."
+ (slot-value e 'first-name)
+ (slot-value e 'last-name)))
+=> #<Standard-Method INSTANCE-REFRESHED (EMPLOYEE) {48174D9D}>
+(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)
+=> (#<EMPLOYEE {48149995}>)
+(slot-value (car *) 'email)
+=> "lenin@soviet.org"
+(update-records [employee] :av-pairs '(([email] "v.lenin@soviet.org"))
+ :where [= [emplid] 1])
+=>
+(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)
+=> (#<EMPLOYEE {48149995}>)
+(slot-value (car *) 'email)
+=> "lenin@soviet.org"
+(select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t :refresh t)
+Details for Vladimir Lenin have been updated from the database.
+=> (#<EMPLOYEE {48149995}>)
+(slot-value (car *) 'email)
+=> "v.lenin@soviet.org"
@@ -290,22 +304,29 @@
See Also
- select
+ select
+
+ Notes
+
+ None.
+
+
-
+
- UPDATE-INSTANCE-FROM-RECORDS
- Update slot values from database.
+ DELETE-INSTANCE-RECORDS
+ Delete SQL records represented by a View Class
+ object.FunctionSyntax
- (update-instance-from-records object &key database) =>
+ delete-instance-recordsobject => Arguments and Values
@@ -314,15 +335,8 @@
object
- An instance of a view class.
-
-
-
-
- database
-
-
- A database connection.
+ An instance of a View
+ Class.
@@ -330,106 +344,106 @@
Description
- Updates 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.
+ 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 :initarg :a :type integer :db-kind :key)
+ (b :initarg :b :type string)))
+=> #<Standard-Db-Class TAB {49B01845}>
+(create-view-from-class 'tab)
+=>
+(defvar obj (let ((*db-auto-sync* t))
+ (make-instance 'tab :a 5 :b "the string")))
+=> OBJ
+(start-sql-recording :type :both)
+=>
+(delete-instance-records obj)
+;; 2004-07-17 11:07:19 foo/bar/baz => DELETE FROM tab WHERE tab.a = 5
+;; 2004-07-17 11:07:19 foo/bar/baz <= T
+=>
Side Effects
- Slot values of object may be modified.
+ Deletes data from the SQL database.
Affected by
-
- Data in SQL database.
-
+ Permissions granted by the SQL database to the user in the
+ database connection.
Exceptional Situations
- If database is not able to be read.
+ An exception may be signaled if the database connection user
+ does not have sufficient privileges to modify the database. An
+ error of type sql-database-error is signalled if
+ object is not associated with an
+ active database.
See Also
-
-
-
-
-
+
+ update-records
+ delete-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.
-
+
- UPDATE-OBJECTS-JOINS
- Updates joined slots of objects.
+ UPDATE-RECORDS-FROM-INSTANCE
+ Update database from view class object.FunctionSyntax
- (update-objects-joins objects &key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*)) =>
+ update-records-from-instanceobject &key database => Arguments and Values
- objects
-
-
- A list of instances of a view class.
-
-
-
-
- slots
-
-
-
-
-
-
- force-p
-
-
-
-
-
-
- class-name
+ object
- A list of instances of a view class.
+ An instance of a View
+ Class.
- max-len
+ database
+ database
+ object. This will default to the value of
+ *default-database*.
@@ -437,45 +451,46 @@
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
- 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.
+ 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.
Examples
-
-
+(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
+=> ("lenin@soviet.org")
+(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
+=> *E1*
+(slot-value *e1* 'email)
+=> "lenin@soviet.org"
+(setf (slot-value *e1* 'email) "v.lenin@soviet.org")
+=> "v.lenin@soviet.org"
+(update-records-from-instance *e1*)
+=>
+(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
+=> ("v.lenin@soviet.org")
+
Side Effects
-
+ Modifies the database.
Affected by
-
-
- *default-update-objects-max-len*
-
-
+ Nothing.
@@ -486,19 +501,19 @@
See Also
-
-
-
-
-
+
+ update-record-from-slot
+ update-record-from-slots
+ update-records
+ Notes
-
+ None.
-
+
@@ -509,7 +524,7 @@
Syntax
- (update-record-from-slot object slot &key database) =>
+ update-record-from-slotobjectslot &key database => Arguments and Values
@@ -518,7 +533,7 @@
object
- An instance of a view class.
+ An instance of a View Class.
@@ -534,7 +549,9 @@
database
- A database connection.
+ A database
+ object. This will default to the value of
+ *default-database*.
@@ -544,7 +561,7 @@
DescriptionUpdates the value stored in the column represented by the
slot, specified by the CLOS slot name
- slot, of View Class instance
+ slot, of View Class instance
object. database
specifies the database in which the update is made only if
object is not associated with a
@@ -559,7 +576,18 @@
Examples
-
+(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
+=> ("lenin@soviet.org")
+(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
+=> *E1*
+(slot-value *e1* 'email)
+=> "lenin@soviet.org"
+(setf (slot-value *e1* 'email) "v.lenin@soviet.org")
+=> "v.lenin@soviet.org"
+(update-record-from-slot *e1* 'email)
+=>
+(select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
+=> ("v.lenin@soviet.org")
@@ -582,31 +610,29 @@
See Also
-
-
- update-record-from-slots
- update-records-from-instance
-
-
+
+ update-record-from-slots
+ update-records-from-instance
+
- notes
+ Notes
-
+ None.
- update-record-from-slots
- update database from slots of view class object.
+ UPDATE-RECORD-FROM-SLOTS
+ Update database from slots of view class object.functionsyntax
- (update-record-from-slots object slots &key (database *default-database*)) =>
+ update-record-from-slotsobjectslots &key database => Arguments and Values
@@ -615,7 +641,7 @@
object
- An instance of a view class.
+ An instance of a View Class.
@@ -631,7 +657,9 @@
database
- A database connection.
+ A database
+ object. This will default to the value of
+ *default-database*.
@@ -641,7 +669,7 @@
DescriptionUpdates the values stored in the columns represented by
the slots, specified by the clos slot names
- slots, of view class instance
+ slots, of View Class instance
object. database
specifies the database in which the update is made only if
object is not associated with a
@@ -656,7 +684,22 @@
Examples
-
+(select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil)
+=> (("Lenin" "lenin@soviet.org"))
+(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
+=> *E1*
+(slot-value *e1* 'last-name)
+=> "Lenin"
+(slot-value *e1* 'email)
+=> "lenin@soviet.org"
+(setf (slot-value *e1* 'last-name) "Ivanovich")
+=> "Ivanovich"
+(setf (slot-value *e1* 'email) "v.ivanovich@soviet.org")
+=> "v.ivanovich@soviet.org"
+(update-record-from-slots *e1* '(email last-name))
+=>
+(select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil)
+=> (("Ivanovich" "v.ivanovich@soviet.org"))
@@ -689,22 +732,21 @@
Notes
-
+ None.
-
-
+
- UPDATE-RECORDS-FROM-INSTANCE
- Update database from view class object.
+ UPDATE-INSTANCE-FROM-RECORDS
+ Update slot values from database.FunctionSyntax
- (update-records-from-instance object &key (database *default-database*)) =>
+ update-instance-from-recordsobject &key database => objectArguments and Values
@@ -713,7 +755,7 @@
object
- An instance of a view class.
+ An instance of a View Class.
@@ -721,7 +763,9 @@
database
- A database connection.
+ A database
+ object. This will default to the value of
+ *default-database*.
@@ -729,55 +773,66 @@
Description
- 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.
+ Updates 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.
Examples
-
+(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
+=> *E1*
+(slot-value *e1* 'email)
+=> "lenin@soviet.org"
+(update-records [employee]
+ :av-pairs '(([email] "v.lenin@soviet.org"))
+ :where [= [emplid] 1])
+=>
+(update-instance-from-records *e1*)
+=> #<EMPLOYEE {4806B53D}>
+(slot-value *e1* 'email)
+=> "v.lenin@soviet.org"
Side Effects
- Modifies the database.
+ Slot values of object may be modified.
Affected by
- Nothing.
+
+ Data in SQL database.
+ Exceptional Situations
- Database errors.
+ If database is not able to be read.
See Also
-
-
- update-record-from-slot
- update-record-from-slots
-
-
+
+ update-slot-from-record
+ update-objects-joins
+ Notes
-
+ None.
@@ -791,7 +846,7 @@
Syntax
- (update-slot-from-record object slot &key (database *default-database*)) =>
+ update-slot-from-recordobjectslot &key database => objectArguments and Values
@@ -800,7 +855,7 @@
object
- An instance of a view class.
+ An instance of a View Class.
@@ -816,7 +871,9 @@
database
- A database connection.
+ A database
+ object. This will default to the value of
+ *default-database*.
@@ -825,13 +882,14 @@
DescriptionUpdates the slot value, specified by the CLOS slot name
- slot, of the View Class instance
+ 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
+ *default-database*. Join slots are updated
but instances of the class on which the join is made are not
updated.
@@ -839,7 +897,18 @@
Examples
-
+(defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
+=> *E1*
+(slot-value *e1* 'email)
+=> "lenin@soviet.org"
+(update-records [employee]
+ :av-pairs '(([email] "v.lenin@soviet.org"))
+ :where [= [emplid] 1])
+=>
+(update-slot-from-record *e1* 'email)
+=> #<EMPLOYEE {4806B53D}>
+(slot-value *e1* 'email)
+=> "v.lenin@soviet.org"
@@ -864,18 +933,151 @@
See Also
+
+ update-instance-from-records
+ update-objects-joins
+
+
+
+ Notes
+
+ None.
+
+
+
+
+
+
+ UPDATE-OBJECTS-JOINS
+ Updates joined slots of objects.
+ Function
+
+
+ Syntax
+
+ update-objects-joinsobjects &key slotsforce-pclass-namemax-len =>
+
+
+ Arguments and Values
+
+
+ objects
+
+
+ A list of instances of a View Class.
+
+
+
+
+ slots
+
+
+ A list of slot names in object or &t;.
+
+
+
+
+ force-p
+
+
+ A Boolean, defaulting to &t;.
+
+
+
+
+ class-name
+
+
+ A list of instances of a View Class.
+
+
+
+
+ max-len
+
+
+ A non-negative integer or &nil; defaulting to
+ *default-update-objects-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
+ 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.
+
+
+
+ Examples
+
+(defvar *addresses* (select 'deferred-employee-address :order-by [ea_join aaddressid] :flatp t))
+=> *ADDRESSES*
+(slot-boundp (car *addresses*) 'address)
+=> NIL
+(update-objects-joins *addresses*)
+=>
+(slot-boundp (car *addresses*) 'address)
+=> T
+(slot-value (car *addresses*) 'address)
+=> #<ADDRESS {480B0F1D}>
+
+
+
+ Side Effects
+
+ The slot values of objects are modified.
+
+
+
+ Affected by
-
-
+ *default-update-objects-max-len*
+
+
+ Exceptional Situations
+
+ Database errors.
+
+
+
+ See Also
+
+ *default-update-objects-max-len*
+ update-instance-from-records
+ update-slot-from-record
+
+ Notes
-
+ None.
-
+