2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.inc">
8 <!-- Object Oriented Data Manipulation Language -->
9 <reference id="ref-oodml">
10 <title>Object Oriented Data Manipulation Language (OODML)</title>
13 Object Oriented Data Manipulation Language (OODML) provides a Common Lisp
14 Object System (CLOS) interface to SQL databases. View classes are defined with
15 the <link linkend="ref-ooddl">OODDL</link> interface and objects are read and
16 written with the OODML.
19 The main function for reading data with the OODML is the <link
20 linkend="select"><function>select</function></link>
21 function. The <function>select</function> is also used in the
22 FDML. However, when <function>select</function> is given a view
23 class name, it returns a list of instances of view classes.
26 View class instances can be updated to reflect any changes in
27 the database with the functions <link
28 linkend="update-slot-from-record"><function>update-slot-from-record</function></link>
30 linkend="update-instance-from-records"><function>update-instance-from-records</function></link>.
32 <para>To update the database to reflect changes made to instances of view classes, use the functions <link
33 linkend="update-records-from-instance"><function>update-records-from-instance</function></link>,
35 linkend="update-record-from-slot"><function>update-record-from-slot</function></link>, and
37 linkend="update-record-from-slots"><function>update-record-from-slots</function></link>.
41 linkend="delete-instance-records"><function>delete-instance-records</function></link>
42 deletes the records corresponding to an instance of a view
47 <refentry id="db-auto-sync">
49 <refname>*DB-AUTO-SYNC*</refname>
50 <refpurpose>Enables SQL storage during Lisp object creation.</refpurpose>
51 <refclass>Variable</refclass>
54 <title>Value Type</title>
60 <title>Initial Value</title>
64 <title>Description</title>
66 When this variable is &t; an instance is stored in the SQL
67 database when the instance is created by
68 <function>make-instance</function>. When this variable is
69 &nil;, which is the default value, &clsql; behaves like
70 &commonsql;: instances of view classes are stored to the SQL
71 database only when <link
72 linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
77 <title>Examples</title>
79 (let ((instance (make-instance 'foo)))
80 (update-record-from-slots instance))
84 (let ((*db-auto-sync* t))
89 <title>Affected By</title>
93 <title>See Also</title>
95 <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
104 <refentry id="default-update-objects-max-len">
106 <refname>*DEFAULT-UPDATE-OBJECTS-MAX-LEN*</refname>
107 <refpurpose>The default maximum number of objects each query to perform a join</refpurpose>
108 <refclass>Variable</refclass>
111 <title>Value Type</title>
117 <title>Initial Value</title>
121 <title>Description</title>
123 This special variable provides the default value for the
124 <parameter>max-len</parameter> argument of the function <link
125 linkend="update-objects-joins"><function>update-object-joins</function></link>.
129 <title>Examples</title>
131 (setq *default-update-objects-max-len* 100)
135 <title>Affected By</title>
139 <title>See Also</title>
141 <member><link linkend="update-objects-joins"><function>update-object-joins</function></link></member>
150 <refentry id="delete-instance-records">
152 <refname>DELETE-INSTANCE-RECORDS</refname>
153 <refpurpose>Delete SQL records represented by a view class
155 <refclass>Function</refclass>
158 <title>Syntax</title>
160 <function>(delete-instance-records object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
163 <title>Arguments and Values</title>
166 <term><parameter>object</parameter></term>
169 An instance of a view class.
176 <title>Description</title>
177 <para>Deletes the records represented by
178 <parameter>object</parameter> in the appropriate table of the
179 database associated with <parameter>object</parameter>. If
180 <parameter>object</parameter> is not yet associated with a
181 database, an error is signalled.
185 <title>Examples</title>
187 * (def-view-class tab () ((a :type integer :db-kind :key) (b :type string)))
188 #<clsql-sys::db-standard-class tab>
189 * (defvar obj (let ((*db-auto-sync* t))
190 (make-instance 'tab :a 5 :b "the string")))
191 * (start-sql-recording :type :both)
192 * (delete-instance-records obj)
196 <title>Side Effects</title>
198 Deletes data from the SQL database.
202 <title>Affected by</title>
204 Permissions granted by the SQL database to the user in the database connection.
208 <title>Exceptional Situations</title>
210 An exception may be signaled if the database connection user does not have
211 sufficient privileges to modify the database.
215 <title>See Also</title>
218 <member><link linkend="update-records"><function>update-records</function></link></member>
219 <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
226 Instances are referenced in the database by values stored in the key slots. If
227 <function>delete-records-from-instance</function> is called with an instance of a class that does
228 not contain any keys, then all records in that table will be deleted.
233 <refentry id="instance-refreshed">
235 <refname>INSTANCE-REFRESHED</refname>
236 <refpurpose>User hook to call on object refresh.</refpurpose>
237 <refclass>Generic function</refclass>
240 <title>Syntax</title>
242 <function>(instance-refreshed object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
245 <title>Arguments and Values</title>
248 <term><parameter>object</parameter></term>
251 The view class object which is being refreshed.
258 <title>Description</title>
259 <para>Provides a hook which is called within an object oriented
260 call to <function>select</function> with a non-nil value of
261 <parameter>refresh</parameter> when the View Class instance
262 <parameter>object</parameter> has been updated from the
263 database. A method specialised on
264 <type>standard-db-object</type> is provided which has no
265 effects. Methods specialised on particular View Classes can be
266 used to specify any operations that need to be made on View
267 Classes instances which have been updated in calls to
268 <function>select</function>.
272 <title>Examples</title>
278 <title>Side Effects</title>
280 The user hook function may cause side effects.
284 <title>Exceptional Situations</title>
290 <title>See Also</title>
293 <member><link linkend="select"><function>select</function></link></member>
299 <refentry id="update-instance-from-records">
301 <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
302 <refpurpose>Update slot values from database.</refpurpose>
303 <refclass>Function</refclass>
306 <title>Syntax</title>
308 <function>(update-instance-from-records object &key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
311 <title>Arguments and Values</title>
314 <term><parameter>object</parameter></term>
317 An instance of a view class.
322 <term><parameter>database</parameter></term>
325 A database connection.
332 <title>Description</title>
333 <para>Updates the slot values of the View Class instance
334 <parameter>object</parameter> using the attribute values of the
335 appropriate table of <parameter>database</parameter> which
336 defaults to the database associated with
337 <parameter>object</parameter> or, if <parameter>object</parameter> is not associated
338 with a database, <varname>*default-database*</varname>. Join slots are updated but
339 instances of the class on which the join is made are not
344 <title>Examples</title>
350 <title>Side Effects</title>
352 Slot values of <parameter>object</parameter> may be modified.
356 <title>Affected by</title>
359 <member>Data in SQL database.</member>
364 <title>Exceptional Situations</title>
366 If <parameter>database</parameter> is not able to be read.
370 <title>See Also</title>
382 <refentry id="update-objects-joins">
384 <refname>UPDATE-OBJECTS-JOINS</refname>
385 <refpurpose>Updates joined slots of objects.</refpurpose>
386 <refclass>Function</refclass>
389 <title>Syntax</title>
391 <function>(update-objects-joins objects &key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
394 <title>Arguments and Values</title>
397 <term><parameter>objects</parameter></term>
400 A list of instances of a view class.
405 <term><parameter>slots</parameter></term>
412 <term><parameter>force-p</parameter></term>
419 <term><parameter>class-name</parameter></term>
422 A list of instances of a view class.
427 <term><parameter>max-len</parameter></term>
436 <title>Description</title>
437 <para>Updates from the records of the appropriate database
438 tables the join slots specified by <parameter>slots</parameter>
439 in the supplied list of View Class instances
440 <parameter>objects</parameter>. <parameter>slots</parameter>
441 when &t; means that all join slots with :retrieval :immediate
442 are updated. <parameter>class-name</parameter> is used to
443 specify the View Class of all instance in
444 <parameter>objects</parameter>, when &nil; then the class of the
445 first instance in <parameter>objects</parameter> is
446 used. <parameter>force-p</parameter> when &t; means that all
447 join slots are updated whereas a value of &nil; means that only
448 unbound join slots are updated. <parameter>max-len</parameter>
449 when non-nil specifies that
450 <function>update-object-joins</function> may issue multiple
451 database queries with a maximum of
452 <parameter>max-len</parameter> instances updated in each query.
456 <title>Examples</title>
462 <title>Side Effects</title>
464 <!-- side effects -->
468 <title>Affected by</title>
472 linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
477 <title>Exceptional Situations</title>
483 <title>See Also</title>
487 linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
499 <refentry id="update-record-from-slot">
501 <refname>UPDATE-RECORD-FROM-SLOT</refname>
502 <refpurpose>Updates database from slot value.</refpurpose>
503 <refclass>Function</refclass>
506 <title>Syntax</title>
508 <function>(update-record-from-slot object slot &key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
511 <title>Arguments and Values</title>
514 <term><parameter>object</parameter></term>
517 An instance of a view class.
522 <term><parameter>slot</parameter></term>
525 The name of a slot in <parameter>object</parameter>.
530 <term><parameter>database</parameter></term>
533 A database connection.
540 <title>Description</title>
541 <para>Updates the value stored in the column represented by the
542 slot, specified by the CLOS slot name
543 <parameter>slot</parameter>, of View Class instance
544 <parameter>object</parameter>. <parameter>database</parameter>
545 specifies the database in which the update is made only if
546 <parameter>object</parameter> is not associated with a
547 database. In this case, a record is created in
548 <parameter>database</parameter> and the attribute represented by
549 <parameter>slot</parameter> is initialised from the value of the
550 supplied slots with other attributes having default
551 values. Furthermore, <parameter>object</parameter> becomes
552 associated with <parameter>database</parameter>.
556 <title>Examples</title>
562 <title>Side Effects</title>
568 <title>Affected By</title>
574 <title>Exceptional Situations</title>
580 <title>See Also</title>
583 <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
584 <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
596 <refentry id="update-record-from-slots">
598 <refname>update-record-from-slots</refname>
599 <refpurpose>update database from slots of view class object.</refpurpose>
600 <refclass>function</refclass>
603 <title>syntax</title>
605 <function>(update-record-from-slots object slots &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
608 <title>Arguments and Values</title>
611 <term><parameter>object</parameter></term>
614 An instance of a view class.
619 <term><parameter>slots</parameter></term>
622 A list of slot names in <parameter>object</parameter>.
627 <term><parameter>database</parameter></term>
630 A database connection.
637 <title>Description</title>
638 <para>Updates the values stored in the columns represented by
639 the slots, specified by the clos slot names
640 <parameter>slots</parameter>, of view class instance
641 <parameter>object</parameter>. <parameter>database</parameter>
642 specifies the database in which the update is made only if
643 <parameter>object</parameter> is not associated with a
644 database. In this case, a record is created in the appropriate
645 table of <parameter>database</parameter> and the attributes
646 represented by <parameter>slots</parameter> are initialised from
647 the values of the supplied slots with other attributes having
648 default values. Furthermore, <parameter>object</parameter>
649 becomes associated with <parameter>database</parameter>.
653 <title>Examples</title>
659 <title>Side Effects</title>
661 Modifies the SQL database.
665 <title>Affected by</title>
671 <title>Exceptional Situations</title>
677 <title>See Also</title>
680 <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
681 <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
694 <refentry id="update-records-from-instance">
696 <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
697 <refpurpose>Update database from view class object.</refpurpose>
698 <refclass>Function</refclass>
701 <title>Syntax</title>
703 <function>(update-records-from-instance object &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
706 <title>Arguments and Values</title>
709 <term><parameter>object</parameter></term>
712 An instance of a view class.
717 <term><parameter>database</parameter></term>
720 A database connection.
727 <title>Description</title>
728 <para>Using an instance of a View Class,
729 <parameter>object</parameter>, update the table that stores its
730 instance data. <parameter>database</parameter> specifies the
731 database in which the update is made only if
732 <parameter>object</parameter> is not associated with a
733 database. In this case, a record is created in the appropriate
734 table of <parameter>database</parameter> using values from the
735 slot values of <parameter>object</parameter>, and
736 <parameter>object</parameter> becomes associated with
737 <parameter>database</parameter>.
741 <title>Examples</title>
747 <title>Side Effects</title>
749 Modifies the database.
753 <title>Affected by</title>
759 <title>Exceptional Situations</title>
765 <title>See Also</title>
768 <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
769 <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
781 <refentry id="update-slot-from-record">
783 <refname>UPDATE-SLOT-FROM-RECORD</refname>
784 <refpurpose>Update objects slot from database.</refpurpose>
785 <refclass>Function</refclass>
788 <title>Syntax</title>
790 <function>(update-slot-from-record object slot &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
793 <title>Arguments and Values</title>
796 <term><parameter>object</parameter></term>
799 An instance of a view class.
804 <term><parameter>slot</parameter></term>
807 The name of a slot in <parameter>object</parameter>.
812 <term><parameter>database</parameter></term>
815 A database connection.
822 <title>Description</title>
823 <para>Updates the slot value, specified by the CLOS slot name
824 <parameter>slot</parameter>, of the View Class instance
825 <parameter>object</parameter> using the attribute values of the
826 appropriate table of <parameter>database</parameter> which
827 defaults to the database associated with
828 <parameter>object</parameter> or, if
829 <parameter>object</parameter> is not associated with a database,
830 <varname>*default-database*</varname>. Join slots are updated
831 but instances of the class on which the join is made are not
836 <title>Examples</title>
842 <title>Side Effects</title>
844 Modifies the slot value of the object.
848 <title>Affected by</title>
851 <member>Data in SQL database.</member>
856 <title>Exceptional Situations</title>
862 <title>See Also</title>