X-Git-Url: http://git.kpe.io/?a=blobdiff_plain;f=doc%2Fref-oodml.xml;h=76df3ec4db0f075f04561ec4a5f9f7ab45f6359f;hb=4413405fd38eaba7ba6d6d8b844fef118e326c9a;hp=4a5900cf6a300d27cc301d197ac5b220db59a70a;hpb=3a45ae325932b9565993407c5c94b28cdefd1f14;p=clsql.git diff --git a/doc/ref-oodml.xml b/doc/ref-oodml.xml index 4a5900c..76df3ec 100644 --- a/doc/ref-oodml.xml +++ b/doc/ref-oodml.xml @@ -10,7 +10,37 @@ 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. @@ -31,12 +61,17 @@ &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. + 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 @@ -87,7 +122,7 @@ This special variable provides the default value for the max-len argument of the function update-object-joins. + linkend="update-objects-joins">update-object-joins. @@ -102,7 +137,9 @@ See Also - None. + + update-object-joins + Notes @@ -113,7 +150,8 @@ DELETE-INSTANCE-RECORDS - Delete SQL records represented by a view class object + Delete SQL records represented by a view class + object. Function @@ -124,15 +162,23 @@ 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. @@ -144,8 +190,6 @@ (make-instance 'tab :a 5 :b "the string"))) * (start-sql-recording :type :both) * (delete-instance-records obj) - - @@ -189,8 +233,8 @@ INSTANCE-REFRESHED - - Function + User hook to call on object refresh. + Generic function Syntax @@ -200,19 +244,28 @@ 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. @@ -224,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. Function Syntax - (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. + + + 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. + 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. @@ -293,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 - - - @@ -329,37 +382,74 @@ UPDATE-OBJECTS-JOINS - + Updates joined slots of objects. Function Syntax - (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. @@ -378,21 +468,23 @@ Affected by - - + *default-update-objects-max-len* + Exceptional Situations - + Database errors. See Also - + *default-update-objects-max-len* @@ -407,31 +499,57 @@ UPDATE-RECORD-FROM-SLOT - + Updates database from slot value. Function Syntax - (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. @@ -443,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 @@ -478,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. + + + Description Updates 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. @@ -516,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 @@ -553,29 +694,47 @@ UPDATE-RECORDS-FROM-INSTANCE - + Update database from view class object. Function Syntax - (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. @@ -587,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 @@ -623,29 +781,55 @@ UPDATE-SLOT-FROM-RECORD - + Update objects slot from database. Function Syntax - (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. + + + Description Updates 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. @@ -657,29 +841,26 @@ Side Effects - + Modifies the slot value of the object. Affected by - + Data in SQL database. Exceptional Situations - + Database errors. See Also - - -