<title>Object Oriented Data Manipulation Language (OODML)</title>
<partintro>
<para>
- Object Oriented Data Manipulation Language (OODML) provides a Common Lisp
- Object System (CLOS) interface to SQL databases. View classes are defined with
- the <link linkend="ref-ooddl">OODDL</link> 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 <link
+ linkend="ref-ooddl">OODDL</link> interface and objects are read
+ and written with the OODML.
</para>
<para>
The main function for reading data with the OODML is the <link
<para>
When this variable is &t; an instance is stored in the SQL
database when the instance is created by
- <function>make-instance</function>. 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 <link
- linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
- is called.
+ <function>make-instance</function>. Furthermore, the
+ appropriate database records are updated whenever the slots of
+ a <glossterm linkend="gloss-view-class">View Class</glossterm>
+ instance are modified.
+ </para>
+ <para>
+ 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 <link
+ linkend="update-records-from-instance"><function>update-record-from-instance</function></link>,
+ <link
+ linkend="update-record-from-slot"><function>update-record-from-slot</function></link>
+ or <link
+ linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
+ are called.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
(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"))
</screen>
</refsect1>
<refsect1>
<refsect1>
<title>See Also</title>
<simplelist>
+ <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
+ <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
<member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
</simplelist>
</refsect1>
<refsect1>
<title>Notes</title>
- <para>None.</para>
+ <para>This is a CLSQL extension to the CommonSQL API.</para>
</refsect1>
</refentry>
<para>
This special variable provides the default value for the
<parameter>max-len</parameter> argument of the function <link
- linkend="update-object-joins"><function>update-object-joins</function></link>.
+ linkend="update-objects-joins"><function>update-object-joins</function></link>.
</para>
</refsect1>
<refsect1>
<refsect1>
<title>See Also</title>
<simplelist>
- <member><link linkend="update-object-joins"><function>update-object-joins</function></link></member>
+ <member><link linkend="update-objects-joins"><function>update-object-joins</function></link></member>
</simplelist>
</refsect1>
<refsect1>
</refsect1>
</refentry>
- <refentry id="delete-instance-records">
- <refnamediv>
- <refname>DELETE-INSTANCE-RECORDS</refname>
- <refpurpose>Delete SQL records represented by a view class
- object.</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis>
- <function>(delete-instance-records object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>object</parameter></term>
- <listitem>
- <para>
- An instance of a view class.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>Deletes the records represented by
- <parameter>object</parameter> in the appropriate table of the
- database associated with <parameter>object</parameter>. If
- <parameter>object</parameter> is not yet associated with a
- database, an error is signalled.
- </para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <screen>
- * (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)
- </screen>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>
- Deletes data from the SQL database.
- </para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>
- Permissions granted by the SQL database to the user in the database connection.
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>
- An exception may be signaled if the database connection user does not have
- sufficient privileges to modify the database.
- </para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="update-records"><function>update-records</function></link></member>
- <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>
- Instances are referenced in the database by values stored in the key slots. If
- <function>delete-records-from-instance</function> is called with an instance of a class that does
- not contain any keys, then all records in that table will be deleted.
- </para>
- </refsect1>
- </refentry>
-
<refentry id="instance-refreshed">
<refnamediv>
<refname>INSTANCE-REFRESHED</refname>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function>(instance-refreshed object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>instance-refreshed</function> <replaceable>object</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- The view class object which is being refreshed.
+ The <glossterm linkend="gloss-view-class">View Class</glossterm> object which is being refreshed.
</para>
</listitem>
</varlistentry>
<title>Description</title>
<para>Provides a hook which is called within an object oriented
call to <function>select</function> with a non-nil value of
- <parameter>refresh</parameter> when the View Class instance
+ <parameter>refresh</parameter> when the <glossterm
+ linkend="gloss-view-class">View Class</glossterm> instance
<parameter>object</parameter> has been updated from the
database. A method specialised on
<type>standard-db-object</type> is provided which has no
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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 Vladamir Lenin have been updated from the database.
+=> (#<EMPLOYEE {48149995}>)
+(slot-value (car *) 'email)
+=> "v.lenin@soviet.org"
</screen>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<simplelist>
- <member><link linkend="select"><function>select</function></link></member>
+ <member><link linkend="select"><function>select</function></link></member>
</simplelist>
</para>
</refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>
+ None.
+ </para>
+ </refsect1>
</refentry>
- <refentry id="update-instance-from-records">
+ <refentry id="delete-instance-records">
<refnamediv>
- <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
- <refpurpose>Update slot values from database.</refpurpose>
+ <refname>DELETE-INSTANCE-RECORDS</refname>
+ <refpurpose>Delete SQL records represented by a <glossterm linkend="gloss-view-class">View Class</glossterm>
+ object.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function>(update-instance-from-records object &key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>delete-instance-records</function> <replaceable>object</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- An instance of a view class.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>
- A database connection.
+ An instance of a <glossterm linkend="gloss-view-class">View
+ Class</glossterm>.
</para>
</listitem>
</varlistentry>
</refsect1>
<refsect1>
<title>Description</title>
- <para>Updates the slot values of the View Class instance
- <parameter>object</parameter> using the attribute values of the
- appropriate table of <parameter>database</parameter> which
- defaults to the database associated with
- <parameter>object</parameter> or, if <parameter>object</parameter> is not associated
- with a database, <variable>*default-database*</variable>. Join slots are updated but
- instances of the class on which the join is made are not
- updated.
+ <para>Deletes the records represented by
+ <parameter>object</parameter> in the appropriate table of the
+ database associated with <parameter>object</parameter>. If
+ <parameter>object</parameter> is not yet associated with a
+ database, an error is signalled.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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
+=>
</screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
<para>
- Slot values of <parameter>object</parameter> may be modified.
+ Deletes data from the SQL database.
</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
- <simplelist>
- Data in SQL database.
- </simplelist>
+ Permissions granted by the SQL database to the user in the
+ database connection.
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- If <parameter>database</parameter> 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 <type>sql-database-error</type> is signalled if
+ <replaceable>object</replaceable> is not associated with an
+ active database.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
- <para>
- <simplelist>
- <!-- see also -->
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="update-records"><function>update-records</function></link></member>
+ <member><link linkend="delete-records"><function>delete-records</function></link></member>
+ <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
+ </simplelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ Instances are referenced in the database by values stored in
+ the key slots. If
+ <function>delete-records-from-instance</function> is called
+ with an instance of a class that does not contain any keys,
+ then all records in that table will be deleted.
</para>
</refsect1>
</refentry>
- <refentry id="update-objects-joins">
+ <refentry id="update-records-from-instance">
<refnamediv>
- <refname>UPDATE-OBJECTS-JOINS</refname>
- <refpurpose>Updates joined slots of objects.</refpurpose>
+ <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
+ <refpurpose>Update database from view class object.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <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>
+ <function>update-records-from-instance</function> <replaceable>object</replaceable> &key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<variablelist>
<varlistentry>
- <term><parameter>objects</parameter></term>
- <listitem>
- <para>
- A list of instances of a view class.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>slots</parameter></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>force-p</parameter></term>
- <listitem>
- <para>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>class-name</parameter></term>
+ <term><parameter>object</parameter></term>
<listitem>
<para>
- A list of instances of a view class.
+ An instance of a <glossterm linkend="gloss-view-class">View
+ Class</glossterm>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><parameter>max-len</parameter></term>
+ <term><parameter>database</parameter></term>
<listitem>
<para>
+ <glossterm linkend="gloss-database-object">database
+ object</glossterm>. This will default to the value of
+ <symbol>*default-database*</symbol>.
</para>
</listitem>
</varlistentry>
</refsect1>
<refsect1>
<title>Description</title>
- <para>Updates from the records of the appropriate database
- tables the join slots specified by <parameter>slots</parameter>
- in the supplied list of View Class instances
- <parameter>objects</parameter>. <parameter>slots</parameter>
- when &t; means that all join slots with :retrieval :immediate
- are updated. <parameter>class-name</parameter> is used to
- specify the View Class of all instance in
- <parameter>objects</parameter>, when &nil; then the class of the
- first instance in <parameter>objects</parameter> is
- used. <parameter>force-p</parameter> when &t; means that all
- join slots are updated whereas a value of &nil; means that only
- unbound join slots are updated. <parameter>max-len</parameter>
- when non-nil specifies that
- <function>update-object-joins</function> may issue multiple
- database queries with a maximum of
- <parameter>max-len</parameter> instances updated in each query.
+ <para>Using an instance of a <glossterm
+ linkend="gloss-view-class">View Class</glossterm>,
+ <parameter>object</parameter>, update the table that stores its
+ instance data. <parameter>database</parameter> specifies the
+ database in which the update is made only if
+ <parameter>object</parameter> is not associated with a
+ database. In this case, a record is created in the appropriate
+ table of <parameter>database</parameter> using values from the
+ slot values of <parameter>object</parameter>, and
+ <parameter>object</parameter> becomes associated with
+ <parameter>database</parameter>.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- examples -->
- </screen>
+(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")
+ </screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
<para>
- <!-- side effects -->
+ Modifies the database.
</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
- <simplelist>
- <simplelist>
- <member><link
- linkend="default-update-objects-max-len"><variable>*default-update-objects-max-len*</variable></link></member>
- </simplelist>
- </simplelist>
+ Nothing.
</para>
</refsect1>
<refsect1>
</refsect1>
<refsect1>
<title>See Also</title>
- <para>
- <simplelist>
- <!-- see also -->
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
+ <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
+ <member><link linkend="update-records"><function>update-records</function></link></member>
+ </simplelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ None.
</para>
</refsect1>
- </refentry>
+ </refentry>
<refentry id="update-record-from-slot">
<refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function>(update-record-from-slot object slot &key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>update-record-from-slot</function> <replaceable>object</replaceable> <replaceable>slot</replaceable> &key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- An instance of a view class.
+ An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
</para>
</listitem>
</varlistentry>
<term><parameter>database</parameter></term>
<listitem>
<para>
- A database connection.
+ A <glossterm linkend="gloss-database-object">database
+ object</glossterm>. This will default to the value of
+ <symbol>*default-database*</symbol>.
</para>
</listitem>
</varlistentry>
<title>Description</title>
<para>Updates the value stored in the column represented by the
slot, specified by the CLOS slot name
- <parameter>slot</parameter>, of View Class instance
+ <parameter>slot</parameter>, of <glossterm linkend="gloss-view-class">View Class</glossterm> instance
<parameter>object</parameter>. <parameter>database</parameter>
specifies the database in which the update is made only if
<parameter>object</parameter> is not associated with a
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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")
</screen>
</refsect1>
<refsect1>
</refsect1>
<refsect1>
<title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
- <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
+ <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
+ </simplelist>
</refsect1>
<refsect1>
- <title>notes</title>
+ <title>Notes</title>
<para>
- <!-- notes -->
+ None.
</para>
</refsect1>
</refentry>
<refentry id="update-record-from-slots">
<refnamediv>
- <refname>update-record-from-slots</refname>
- <refpurpose>update database from slots of view class object.</refpurpose>
+ <refname>UPDATE-RECORD-FROM-SLOTS</refname>
+ <refpurpose>Update database from slots of view class object.</refpurpose>
<refclass>function</refclass>
</refnamediv>
<refsect1>
<title>syntax</title>
<synopsis>
- <function>(update-record-from-slots object slots &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>update-record-from-slots</function> <replaceable>object</replaceable> <replaceable>slots</replaceable> &key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- An instance of a view class.
+ An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
</para>
</listitem>
</varlistentry>
<term><parameter>database</parameter></term>
<listitem>
<para>
- A database connection.
+ A <glossterm linkend="gloss-database-object">database
+ object</glossterm>. This will default to the value of
+ <symbol>*default-database*</symbol>.
</para>
</listitem>
</varlistentry>
<title>Description</title>
<para>Updates the values stored in the columns represented by
the slots, specified by the clos slot names
- <parameter>slots</parameter>, of view class instance
+ <parameter>slots</parameter>, of <glossterm linkend="gloss-view-class">View Class</glossterm> instance
<parameter>object</parameter>. <parameter>database</parameter>
specifies the database in which the update is made only if
<parameter>object</parameter> is not associated with a
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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"))
</screen>
</refsect1>
<refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ None.
</para>
</refsect1>
</refentry>
-
- <refentry id="update-records-from-instance">
+ <refentry id="update-instance-from-records">
<refnamediv>
- <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
- <refpurpose>Update database from view class object.</refpurpose>
+ <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
+ <refpurpose>Update slot values from database.</refpurpose>
<refclass>Function</refclass>
</refnamediv>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function>(update-records-from-instance object &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>update-instance-from-records</function> <replaceable>object</replaceable> &key <replaceable>database</replaceable> => <returnvalue>object</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- An instance of a view class.
+ An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
</para>
</listitem>
</varlistentry>
<term><parameter>database</parameter></term>
<listitem>
<para>
- A database connection.
+ A <glossterm linkend="gloss-database-object">database
+ object</glossterm>. This will default to the value of
+ <symbol>*default-database*</symbol>.
</para>
</listitem>
</varlistentry>
</refsect1>
<refsect1>
<title>Description</title>
- <para>Using an instance of a View Class,
- <parameter>object</parameter>, update the table that stores its
- instance data. <parameter>database</parameter> specifies the
- database in which the update is made only if
- <parameter>object</parameter> is not associated with a
- database. In this case, a record is created in the appropriate
- table of <parameter>database</parameter> using values from the
- slot values of <parameter>object</parameter>, and
- <parameter>object</parameter> becomes associated with
- <parameter>database</parameter>.
+ <para>Updates the slot values of the <glossterm
+ linkend="gloss-view-class">View Class</glossterm> instance
+ <parameter>object</parameter> using the attribute values of the
+ appropriate table of <parameter>database</parameter> which
+ defaults to the database associated with
+ <parameter>object</parameter> or, if
+ <parameter>object</parameter> is not associated with a database,
+ <varname>*default-database*</varname>. Join slots are updated
+ but instances of the class on which the join is made are not
+ updated.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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"
</screen>
</refsect1>
<refsect1>
<title>Side Effects</title>
<para>
- Modifies the database.
+ Slot values of <parameter>object</parameter> may be modified.
</para>
</refsect1>
<refsect1>
<title>Affected by</title>
<para>
- Nothing.
+ <simplelist>
+ <member>Data in SQL database.</member>
+ </simplelist>
</para>
</refsect1>
<refsect1>
<title>Exceptional Situations</title>
<para>
- Database errors.
+ If <parameter>database</parameter> is not able to be read.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
- <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
- </simplelist>
- </para>
+ <simplelist>
+ <member><link linkend="update-slot-from-record"><function>update-slot-from-record</function></link></member>
+ <member><link linkend="update-objects-joins"><function>update-objects-joins</function></link></member>
+ </simplelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ None.
</para>
</refsect1>
</refentry>
<refsect1>
<title>Syntax</title>
<synopsis>
- <function>(update-slot-from-record object slot &key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
+ <function>update-slot-from-record</function> <replaceable>object</replaceable> <replaceable>slot</replaceable> &key <replaceable>database</replaceable> => <returnvalue>object</returnvalue></synopsis>
</refsect1>
<refsect1>
<title>Arguments and Values</title>
<term><parameter>object</parameter></term>
<listitem>
<para>
- An instance of a view class.
+ An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
</para>
</listitem>
</varlistentry>
<term><parameter>database</parameter></term>
<listitem>
<para>
- A database connection.
+ A <glossterm linkend="gloss-database-object">database
+ object</glossterm>. This will default to the value of
+ <symbol>*default-database*</symbol>.
</para>
</listitem>
</varlistentry>
<refsect1>
<title>Description</title>
<para>Updates the slot value, specified by the CLOS slot name
- <parameter>slot</parameter>, of the View Class instance
+ <parameter>slot</parameter>, of the <glossterm
+ linkend="gloss-view-class">View Class</glossterm> instance
<parameter>object</parameter> using the attribute values of the
appropriate table of <parameter>database</parameter> which
defaults to the database associated with
<parameter>object</parameter> or, if
<parameter>object</parameter> is not associated with a database,
- <variable>*default-database*</variable>. Join slots are updated
+ <varname>*default-database*</varname>. Join slots are updated
but instances of the class on which the join is made are not
updated.
</para>
<refsect1>
<title>Examples</title>
<screen>
- <!-- 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"
</screen>
</refsect1>
<refsect1>
</refsect1>
<refsect1>
<title>See Also</title>
+ <simplelist>
+ <member><link linkend="update-instance-from-records"><function>update-instance-from-records</function></link></member>
+ <member><link linkend="update-objects-joins"><function>update-objects-joins</function></link></member>
+ </simplelist>
+ </refsect1>
+ <refsect1>
+ <title>Notes</title>
+ <para>
+ None.
+ </para>
+ </refsect1>
+ </refentry>
+
+ <refentry id="update-objects-joins">
+ <refnamediv>
+ <refname>UPDATE-OBJECTS-JOINS</refname>
+ <refpurpose>Updates joined slots of objects.</refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+ <synopsis>
+ <function>update-objects-joins</function> <replaceable>objects</replaceable> &key <replaceable>slots</replaceable> <replaceable>force-p</replaceable> <replaceable>class-name</replaceable> <replaceable>max-len</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>objects</parameter></term>
+ <listitem>
+ <para>
+ A list of instances of a <glossterm
+ linkend="gloss-view-class">View Class</glossterm>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>slots</parameter></term>
+ <listitem>
+ <para>
+ A list of slot names in <parameter>object</parameter> or &t;.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>force-p</parameter></term>
+ <listitem>
+ <para>
+ A Boolean, defaulting to &t;.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>class-name</parameter></term>
+ <listitem>
+ <para>
+ A list of instances of a <glossterm
+ linkend="gloss-view-class">View Class</glossterm>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>max-len</parameter></term>
+ <listitem>
+ <para>
+ A non-negative integer or &nil; defaulting to
+ <symbol>*default-update-objects-max-len*</symbol>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>Updates from the records of the appropriate database
+ tables the join slots specified by <parameter>slots</parameter>
+ in the supplied list of <glossterm linkend="gloss-view-class">View
+ Class</glossterm> instances
+ <parameter>objects</parameter>. <parameter>slots</parameter>
+ when &t; means that all join slots with
+ <symbol>:retrieval</symbol> <symbol>:immediate</symbol> are
+ updated. <parameter>class-name</parameter> is used to specify
+ the <glossterm linkend="gloss-view-class">View Class</glossterm> of
+ all instance in <parameter>objects</parameter>, when &nil; then
+ the class of the first instance in
+ <parameter>objects</parameter> is
+ used. <parameter>force-p</parameter> when &t; means that all
+ join slots are updated whereas a value of &nil; means that only
+ unbound join slots are updated. <parameter>max-len</parameter>
+ when non-nil specifies that
+ <function>update-object-joins</function> may issue multiple
+ database queries with a maximum of
+ <parameter>max-len</parameter> instances updated in each query.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <screen>
+(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}>
+ </screen>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>
+ The slot values of <parameter>objects</parameter> are modified.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
<para>
<simplelist>
- <!-- see also -->
- </simplelist>
+ <member><link
+ linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
+ </simplelist>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>
+ Database errors.
</para>
</refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <simplelist>
+ <member><link linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
+ <member><link linkend="update-instance-from-records"><function>update-instance-from-records</function></link></member>
+ <member><link linkend="update-slot-from-record"><function>update-slot-from-record</function></link></member>
+ </simplelist>
+ </refsect1>
<refsect1>
<title>Notes</title>
<para>
- <!-- notes -->
+ None.
</para>
</refsect1>
- </refentry>
+ </refentry>
</reference>
projects / clsql.git / blobdiff