doc/ref-oodml.xml

   1 <?xml version='1.0' ?>
   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">
   5 %myents;
   6 ]>
   7
   8 <!-- Object Oriented Data Manipulation Language -->
   9 <reference id="ref-oodml">
  10   <title>Object Oriented Data Manipulation Language (OODML)</title>
  11     <partintro>
  12     <para>
  13       Object Oriented Data Manipulation Language (OODML) provides a
  14       Common Lisp Object System (CLOS) interface to SQL
  15       databases. View classes are defined with the <link
  16       linkend="ref-ooddl">OODDL</link> interface and objects are read
  17       and written with the OODML.
  18     </para>
  19     <para>
  20       The main function for reading data with the OODML is the <link
  21       linkend="select"><function>select</function></link>
  22       function. The <function>select</function> is also used in the
  23       FDML. However, when <function>select</function> is given a view
  24       class name, it returns a list of instances of view classes.
  25     </para>
  26     <para>
  27       View class instances can be updated to reflect any changes in
  28       the database with the functions <link
  29       linkend="update-slot-from-record"><function>update-slot-from-record</function></link>
  30       and <link
  31       linkend="update-instance-from-records"><function>update-instance-from-records</function></link>.
  32     </para>
  33     <para>To update the database to reflect changes made to instances of view classes, use the functions <link
  34       linkend="update-records-from-instance"><function>update-records-from-instance</function></link>,
  35       <link
  36       linkend="update-record-from-slot"><function>update-record-from-slot</function></link>, and
  37       <link
  38       linkend="update-record-from-slots"><function>update-record-from-slots</function></link>.
  39     </para>
  40     <para>
  41       The function <link
  42       linkend="delete-instance-records"><function>delete-instance-records</function></link>
  43       deletes the records corresponding to an instance of a view
  44       class.
  45     </para>
  46   </partintro>
  47
  48   <refentry id="db-auto-sync">
  49     <refnamediv>
  50       <refname>*DB-AUTO-SYNC*</refname>
  51       <refpurpose>Enables SQL storage during Lisp object creation.</refpurpose>
  52       <refclass>Variable</refclass>
  53     </refnamediv>
  54     <refsect1>
  55       <title>Value Type</title>
  56       <para>
  57         Boolean
  58       </para>
  59     </refsect1>
  60     <refsect1>
  61       <title>Initial Value</title>
  62       <para>&nil;</para>
  63     </refsect1>
  64     <refsect1>
  65       <title>Description</title>
  66       <para>
  67         When this variable is &t; an instance is stored in the SQL
  68         database when the instance is created by
  69         <function>make-instance</function>. Furthermore, the
  70         appropriate database records are updated whenever the slots of
  71         a <glossterm linkend="gloss-view-class">View Class</glossterm>
  72         instance are modified.
  73       </para>
  74       <para>
  75         When this variable is &nil;, which is the default value,
  76         &clsql; behaves like &commonsql;: instances of view classes
  77         are stored or updated in the SQL database only when <link
  78         linkend="update-records-from-instance"><function>update-record-from-instance</function></link>,
  79         <link
  80         linkend="update-record-from-slot"><function>update-record-from-slot</function></link>
  81         or <link
  82         linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
  83         are called.
  84       </para>
  85     </refsect1>
  86     <refsect1>
  87       <title>Examples</title>
  88       <screen>
  89         (let ((instance (make-instance 'foo)))
  90           (update-records-from-instance instance))
  91
  92         ;; is equivalent to
  93
  94         (let ((*db-auto-sync* t))
  95           (make-instance 'foo))
  96
  97         ;; and
  98
  99         (progn
 100           (setf (slot-value instance 'bar) "baz")
 101           (update-record-from-slot instance 'bar))
 102
 103         ;; is equivalent to
 104
 105         (let ((*db-auto-sync* t))
 106           (setf (slot-value instance 'bar) "baz"))
 107       </screen>
 108     </refsect1>
 109     <refsect1>
 110       <title>Affected By</title>
 111       <para>None.</para>
 112     </refsect1>
 113     <refsect1>
 114       <title>See Also</title>
 115       <simplelist>
 116         <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 117         <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
 118         <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
 119       </simplelist>
 120     </refsect1>
 121     <refsect1>
 122       <title>Notes</title>
 123       <para>This is a CLSQL extension to the CommonSQL API.</para>
 124     </refsect1>
 125   </refentry>
 126
 127   <refentry id="default-update-objects-max-len">
 128     <refnamediv>
 129       <refname>*DEFAULT-UPDATE-OBJECTS-MAX-LEN*</refname>
 130       <refpurpose>The default maximum number of objects each query to perform a join</refpurpose>
 131       <refclass>Variable</refclass>
 132     </refnamediv>
 133     <refsect1>
 134       <title>Value Type</title>
 135       <para>
 136         (or null integer)
 137       </para>
 138     </refsect1>
 139     <refsect1>
 140       <title>Initial Value</title>
 141       <para>&nil;</para>
 142     </refsect1>
 143     <refsect1>
 144       <title>Description</title>
 145       <para>
 146         This special variable provides the default value for the
 147         <parameter>max-len</parameter> argument of the function <link
 148         linkend="update-objects-joins"><function>update-object-joins</function></link>.
 149       </para>
 150     </refsect1>
 151     <refsect1>
 152       <title>Examples</title>
 153       <screen>
 154         (setq *default-update-objects-max-len* 100)
 155       </screen>
 156     </refsect1>
 157     <refsect1>
 158       <title>Affected By</title>
 159       <para>None.</para>
 160     </refsect1>
 161     <refsect1>
 162       <title>See Also</title>
 163       <simplelist>
 164         <member><link linkend="update-objects-joins"><function>update-object-joins</function></link></member>
 165       </simplelist>
 166     </refsect1>
 167     <refsect1>
 168       <title>Notes</title>
 169       <para>None.</para>
 170     </refsect1>
 171   </refentry>
 172
 173   <refentry id="instance-refreshed">
 174     <refnamediv>
 175       <refname>INSTANCE-REFRESHED</refname>
 176       <refpurpose>User hook to call on object refresh.</refpurpose>
 177       <refclass>Generic function</refclass>
 178     </refnamediv>
 179     <refsect1>
 180       <title>Syntax</title>
 181       <synopsis>
 182       <function>instance-refreshed</function> <replaceable>object</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 183     </refsect1>
 184     <refsect1>
 185       <title>Arguments and Values</title>
 186       <variablelist>
 187         <varlistentry>
 188           <term><parameter>object</parameter></term>
 189           <listitem>
 190             <para>
 191               The <glossterm linkend="gloss-view-class">View Class</glossterm> object which is being refreshed.
 192             </para>
 193           </listitem>
 194         </varlistentry>
 195       </variablelist>
 196     </refsect1>
 197     <refsect1>
 198       <title>Description</title>
 199       <para>Provides a hook which is called within an object oriented
 200       call to <function>select</function> with a non-nil value of
 201       <parameter>refresh</parameter> when the <glossterm
 202       linkend="gloss-view-class">View Class</glossterm> instance
 203       <parameter>object</parameter> has been updated from the
 204       database. A method specialised on
 205       <type>standard-db-object</type> is provided which has no
 206       effects. Methods specialised on particular View Classes can be
 207       used to specify any operations that need to be made on View
 208       Classes instances which have been updated in calls to
 209       <function>select</function>.
 210       </para>
 211     </refsect1>
 212     <refsect1>
 213       <title>Examples</title>
 214       <screen>
 215 (slot-value employee1 'email)
 216 => "lenin@soviet.org"
 217 (defmethod instance-refreshed ((e employee))
 218    (format t "~&amp;Details for ~A ~A have been updated from the database."
 219            (slot-value e 'first-name)
 220            (slot-value e 'last-name)))
 221 => #&lt;Standard-Method INSTANCE-REFRESHED (EMPLOYEE) {48174D9D}>
 222 (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)
 223 => (#&lt;EMPLOYEE {48149995}>)
 224 (slot-value (car *) 'email)
 225 => "lenin@soviet.org"
 226 (update-records [employee] :av-pairs '(([email] "v.lenin@soviet.org"))
 227                 :where [= [emplid] 1])
 228 =>
 229 (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)
 230 => (#&lt;EMPLOYEE {48149995}>)
 231 (slot-value (car *) 'email)
 232 => "lenin@soviet.org"
 233 (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t :refresh t)
 234 Details for Vladamir Lenin have been updated from the database.
 235 => (#&lt;EMPLOYEE {48149995}>)
 236 (slot-value (car *) 'email)
 237 => "v.lenin@soviet.org"
 238       </screen>
 239     </refsect1>
 240     <refsect1>
 241       <title>Side Effects</title>
 242       <para>
 243         The user hook function may cause side effects.
 244       </para>
 245     </refsect1>
 246     <refsect1>
 247       <title>Exceptional Situations</title>
 248       <para>
 249         None.
 250       </para>
 251     </refsect1>
 252     <refsect1>
 253       <title>See Also</title>
 254       <para>
 255         <simplelist>
 256           <member><link linkend="select"><function>select</function></link></member>
 257         </simplelist>
 258       </para>
 259     </refsect1>
 260     <refsect1>
 261       <title>Notes</title>
 262       <para>
 263         None.
 264       </para>
 265     </refsect1>
 266   </refentry>
 267
 268   <refentry id="delete-instance-records">
 269     <refnamediv>
 270       <refname>DELETE-INSTANCE-RECORDS</refname>
 271       <refpurpose>Delete SQL records represented by a <glossterm linkend="gloss-view-class">View Class</glossterm>
 272       object.</refpurpose>
 273       <refclass>Function</refclass>
 274     </refnamediv>
 275     <refsect1>
 276       <title>Syntax</title>
 277       <synopsis>
 278       <function>delete-instance-records</function> <replaceable>object</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 279     </refsect1>
 280     <refsect1>
 281       <title>Arguments and Values</title>
 282       <variablelist>
 283         <varlistentry>
 284           <term><parameter>object</parameter></term>
 285           <listitem>
 286             <para>
 287               An instance of a <glossterm linkend="gloss-view-class">View
 288               Class</glossterm>.
 289             </para>
 290           </listitem>
 291         </varlistentry>
 292       </variablelist>
 293     </refsect1>
 294     <refsect1>
 295       <title>Description</title>
 296       <para>Deletes the records represented by
 297       <parameter>object</parameter> in the appropriate table of the
 298       database associated with <parameter>object</parameter>. If
 299       <parameter>object</parameter> is not yet associated with a
 300       database, an error is signalled.
 301       </para>
 302     </refsect1>
 303     <refsect1>
 304       <title>Examples</title>
 305       <screen>
 306 (def-view-class tab ()
 307   ((a :initarg :a :type integer :db-kind :key)
 308    (b :initarg :b :type string)))
 309 => #&lt;Standard-Db-Class TAB {49B01845}>
 310 (create-view-from-class 'tab)
 311 =>
 312 (defvar obj (let ((*db-auto-sync* t))
 313               (make-instance 'tab :a 5 :b "the string")))
 314 => OBJ
 315 (start-sql-recording :type :both)
 316 =>
 317 (delete-instance-records obj)
 318 ;; 2004-07-17 11:07:19 foo/bar/baz => DELETE FROM tab WHERE tab.a = 5
 319 ;; 2004-07-17 11:07:19 foo/bar/baz &lt;= T
 320 =>
 321       </screen>
 322     </refsect1>
 323     <refsect1>
 324       <title>Side Effects</title>
 325       <para>
 326         Deletes data from the SQL database.
 327       </para>
 328     </refsect1>
 329     <refsect1>
 330       <title>Affected by</title>
 331       <para>
 332         Permissions granted by the SQL database to the user in the
 333         database connection.
 334       </para>
 335     </refsect1>
 336     <refsect1>
 337       <title>Exceptional Situations</title>
 338       <para>
 339         An exception may be signaled if the database connection user
 340         does not have sufficient privileges to modify the database. An
 341         error of type <type>sql-database-error</type> is signalled if
 342         <replaceable>object</replaceable> is not associated with an
 343         active database.
 344       </para>
 345     </refsect1>
 346     <refsect1>
 347       <title>See Also</title>
 348       <simplelist>
 349         <member><link linkend="update-records"><function>update-records</function></link></member>
 350         <member><link linkend="delete-records"><function>delete-records</function></link></member>
 351         <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 352       </simplelist>
 353     </refsect1>
 354     <refsect1>
 355       <title>Notes</title>
 356       <para>
 357         Instances are referenced in the database by values stored in
 358         the key slots. If
 359         <function>delete-records-from-instance</function> is called
 360         with an instance of a class that does not contain any keys,
 361         then all records in that table will be deleted.
 362       </para>
 363     </refsect1>
 364   </refentry>
 365
 366   <refentry id="update-records-from-instance">
 367     <refnamediv>
 368       <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
 369       <refpurpose>Update database from view class object.</refpurpose>
 370       <refclass>Function</refclass>
 371     </refnamediv>
 372     <refsect1>
 373       <title>Syntax</title>
 374       <synopsis>
 375       <function>update-records-from-instance</function> <replaceable>object</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 376     </refsect1>
 377     <refsect1>
 378       <title>Arguments and Values</title>
 379       <variablelist>
 380         <varlistentry>
 381           <term><parameter>object</parameter></term>
 382           <listitem>
 383             <para>
 384               An instance of a <glossterm linkend="gloss-view-class">View
 385               Class</glossterm>.
 386             </para>
 387           </listitem>
 388         </varlistentry>
 389         <varlistentry>
 390           <term><parameter>database</parameter></term>
 391           <listitem>
 392             <para>
 393               <glossterm linkend="gloss-database-object">database
 394               object</glossterm>. This will default to the value of
 395               <symbol>*default-database*</symbol>.
 396             </para>
 397           </listitem>
 398         </varlistentry>
 399       </variablelist>
 400     </refsect1>
 401     <refsect1>
 402       <title>Description</title>
 403       <para>Using an instance of a <glossterm
 404       linkend="gloss-view-class">View Class</glossterm>,
 405       <parameter>object</parameter>, update the table that stores its
 406       instance data. <parameter>database</parameter> specifies the
 407       database in which the update is made only if
 408       <parameter>object</parameter> is not associated with a
 409       database. In this case, a record is created in the appropriate
 410       table of <parameter>database</parameter> using values from the
 411       slot values of <parameter>object</parameter>, and
 412       <parameter>object</parameter> becomes associated with
 413       <parameter>database</parameter>.
 414       </para>
 415     </refsect1>
 416     <refsect1>
 417       <title>Examples</title>
 418       <screen>
 419 (select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
 420 => ("lenin@soviet.org")
 421 (defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
 422 => *E1*
 423 (slot-value *e1* 'email)
 424 => "lenin@soviet.org"
 425 (setf (slot-value *e1* 'email) "v.lenin@soviet.org")
 426 => "v.lenin@soviet.org"
 427 (update-records-from-instance *e1*)
 428 =>
 429 (select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
 430 => ("v.lenin@soviet.org")
 431      </screen>
 432     </refsect1>
 433     <refsect1>
 434       <title>Side Effects</title>
 435       <para>
 436         Modifies the database.
 437       </para>
 438     </refsect1>
 439     <refsect1>
 440       <title>Affected by</title>
 441       <para>
 442         Nothing.
 443       </para>
 444     </refsect1>
 445     <refsect1>
 446       <title>Exceptional Situations</title>
 447       <para>
 448         Database errors.
 449       </para>
 450     </refsect1>
 451     <refsect1>
 452       <title>See Also</title>
 453       <simplelist>
 454         <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
 455         <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
 456         <member><link linkend="update-records"><function>update-records</function></link></member>
 457       </simplelist>
 458     </refsect1>
 459     <refsect1>
 460       <title>Notes</title>
 461       <para>
 462         None.
 463       </para>
 464     </refsect1>
 465   </refentry>
 466
 467   <refentry id="update-record-from-slot">
 468     <refnamediv>
 469       <refname>UPDATE-RECORD-FROM-SLOT</refname>
 470       <refpurpose>Updates database from slot value.</refpurpose>
 471       <refclass>Function</refclass>
 472     </refnamediv>
 473     <refsect1>
 474       <title>Syntax</title>
 475       <synopsis>
 476       <function>update-record-from-slot</function> <replaceable>object</replaceable> <replaceable>slot</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 477     </refsect1>
 478     <refsect1>
 479       <title>Arguments and Values</title>
 480       <variablelist>
 481         <varlistentry>
 482           <term><parameter>object</parameter></term>
 483           <listitem>
 484             <para>
 485               An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
 486             </para>
 487           </listitem>
 488         </varlistentry>
 489         <varlistentry>
 490           <term><parameter>slot</parameter></term>
 491           <listitem>
 492             <para>
 493               The name of a slot in <parameter>object</parameter>.
 494             </para>
 495           </listitem>
 496         </varlistentry>
 497         <varlistentry>
 498           <term><parameter>database</parameter></term>
 499           <listitem>
 500             <para>
 501               A <glossterm linkend="gloss-database-object">database
 502               object</glossterm>. This will default to the value of
 503               <symbol>*default-database*</symbol>.
 504             </para>
 505           </listitem>
 506         </varlistentry>
 507       </variablelist>
 508     </refsect1>
 509     <refsect1>
 510       <title>Description</title>
 511       <para>Updates the value stored in the column represented by the
 512       slot, specified by the CLOS slot name
 513       <parameter>slot</parameter>, of <glossterm linkend="gloss-view-class">View Class</glossterm> instance
 514       <parameter>object</parameter>. <parameter>database</parameter>
 515       specifies the database in which the update is made only if
 516       <parameter>object</parameter> is not associated with a
 517       database. In this case, a record is created in
 518       <parameter>database</parameter> and the attribute represented by
 519       <parameter>slot</parameter> is initialised from the value of the
 520       supplied slots with other attributes having default
 521       values. Furthermore, <parameter>object</parameter> becomes
 522       associated with <parameter>database</parameter>.
 523       </para>
 524     </refsect1>
 525     <refsect1>
 526       <title>Examples</title>
 527       <screen>
 528 (select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
 529 => ("lenin@soviet.org")
 530 (defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
 531 => *E1*
 532 (slot-value *e1* 'email)
 533 => "lenin@soviet.org"
 534 (setf (slot-value *e1* 'email) "v.lenin@soviet.org")
 535 => "v.lenin@soviet.org"
 536 (update-record-from-slot *e1* 'email)
 537 =>
 538 (select [email] :from [employee] :where [= [emplid] 1] :field-names nil :flatp t)
 539 => ("v.lenin@soviet.org")
 540       </screen>
 541     </refsect1>
 542     <refsect1>
 543       <title>Side Effects</title>
 544       <para>
 545         Modifies database.
 546       </para>
 547     </refsect1>
 548     <refsect1>
 549       <title>Affected By</title>
 550       <para>
 551         Nothing.
 552       </para>
 553     </refsect1>
 554     <refsect1>
 555       <title>Exceptional Situations</title>
 556       <para>
 557         Database errors.
 558       </para>
 559     </refsect1>
 560     <refsect1>
 561       <title>See Also</title>
 562       <simplelist>
 563         <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
 564         <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 565       </simplelist>
 566     </refsect1>
 567     <refsect1>
 568       <title>Notes</title>
 569       <para>
 570         None.
 571       </para>
 572     </refsect1>
 573   </refentry>
 574
 575   <refentry id="update-record-from-slots">
 576     <refnamediv>
 577       <refname>UPDATE-RECORD-FROM-SLOTS</refname>
 578       <refpurpose>Update database from slots of view class object.</refpurpose>
 579       <refclass>function</refclass>
 580     </refnamediv>
 581     <refsect1>
 582       <title>syntax</title>
 583       <synopsis>
 584       <function>update-record-from-slots</function> <replaceable>object</replaceable> <replaceable>slots</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 585     </refsect1>
 586     <refsect1>
 587       <title>Arguments and Values</title>
 588       <variablelist>
 589         <varlistentry>
 590           <term><parameter>object</parameter></term>
 591           <listitem>
 592             <para>
 593               An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
 594             </para>
 595           </listitem>
 596         </varlistentry>
 597         <varlistentry>
 598           <term><parameter>slots</parameter></term>
 599           <listitem>
 600             <para>
 601               A list of slot names in <parameter>object</parameter>.
 602             </para>
 603           </listitem>
 604         </varlistentry>
 605         <varlistentry>
 606           <term><parameter>database</parameter></term>
 607           <listitem>
 608             <para>
 609               A <glossterm linkend="gloss-database-object">database
 610               object</glossterm>. This will default to the value of
 611               <symbol>*default-database*</symbol>.
 612             </para>
 613           </listitem>
 614         </varlistentry>
 615       </variablelist>
 616     </refsect1>
 617     <refsect1>
 618       <title>Description</title>
 619       <para>Updates the values stored in the columns represented by
 620       the slots, specified by the clos slot names
 621       <parameter>slots</parameter>, of <glossterm linkend="gloss-view-class">View Class</glossterm> instance
 622       <parameter>object</parameter>. <parameter>database</parameter>
 623       specifies the database in which the update is made only if
 624       <parameter>object</parameter> is not associated with a
 625       database. In this case, a record is created in the appropriate
 626       table of <parameter>database</parameter> and the attributes
 627       represented by <parameter>slots</parameter> are initialised from
 628       the values of the supplied slots with other attributes having
 629       default values. Furthermore, <parameter>object</parameter>
 630       becomes associated with <parameter>database</parameter>.
 631       </para>
 632     </refsect1>
 633     <refsect1>
 634       <title>Examples</title>
 635       <screen>
 636 (select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil)
 637 => (("Lenin" "lenin@soviet.org"))
 638 (defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
 639 => *E1*
 640 (slot-value *e1* 'last-name)
 641 => "Lenin"
 642 (slot-value *e1* 'email)
 643 => "lenin@soviet.org"
 644 (setf (slot-value *e1* 'last-name) "Ivanovich")
 645 => "Ivanovich"
 646 (setf (slot-value *e1* 'email) "v.ivanovich@soviet.org")
 647 => "v.ivanovich@soviet.org"
 648 (update-record-from-slots *e1* '(email last-name))
 649 =>
 650 (select [last-name] [email] :from [employee] :where [= [emplid] 1] :field-names nil)
 651 => (("Ivanovich" "v.ivanovich@soviet.org"))
 652       </screen>
 653     </refsect1>
 654     <refsect1>
 655       <title>Side Effects</title>
 656       <para>
 657         Modifies the SQL database.
 658       </para>
 659     </refsect1>
 660     <refsect1>
 661       <title>Affected by</title>
 662       <para>
 663         Nothing.
 664       </para>
 665     </refsect1>
 666     <refsect1>
 667       <title>Exceptional Situations</title>
 668       <para>
 669         Database errors.
 670       </para>
 671     </refsect1>
 672     <refsect1>
 673       <title>See Also</title>
 674       <para>
 675         <simplelist>
 676           <member><link linkend="update-record-from-slot"><function>update-record-from-slot</function></link></member>
 677           <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 678         </simplelist>
 679       </para>
 680     </refsect1>
 681     <refsect1>
 682       <title>Notes</title>
 683       <para>
 684         None.
 685       </para>
 686     </refsect1>
 687   </refentry>
 688
 689   <refentry id="update-instance-from-records">
 690     <refnamediv>
 691       <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
 692       <refpurpose>Update slot values from database.</refpurpose>
 693       <refclass>Function</refclass>
 694     </refnamediv>
 695     <refsect1>
 696       <title>Syntax</title>
 697       <synopsis>
 698       <function>update-instance-from-records</function> <replaceable>object</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>object</returnvalue></synopsis>
 699     </refsect1>
 700     <refsect1>
 701       <title>Arguments and Values</title>
 702       <variablelist>
 703         <varlistentry>
 704           <term><parameter>object</parameter></term>
 705           <listitem>
 706             <para>
 707               An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
 708             </para>
 709           </listitem>
 710         </varlistentry>
 711         <varlistentry>
 712           <term><parameter>database</parameter></term>
 713           <listitem>
 714             <para>
 715               A <glossterm linkend="gloss-database-object">database
 716               object</glossterm>. This will default to the value of
 717               <symbol>*default-database*</symbol>.
 718             </para>
 719           </listitem>
 720         </varlistentry>
 721       </variablelist>
 722     </refsect1>
 723     <refsect1>
 724       <title>Description</title>
 725       <para>Updates the slot values of the <glossterm
 726       linkend="gloss-view-class">View Class</glossterm> instance
 727       <parameter>object</parameter> using the attribute values of the
 728       appropriate table of <parameter>database</parameter> which
 729       defaults to the database associated with
 730       <parameter>object</parameter> or, if
 731       <parameter>object</parameter> is not associated with a database,
 732       <varname>*default-database*</varname>.  Join slots are updated
 733       but instances of the class on which the join is made are not
 734       updated.
 735       </para>
 736     </refsect1>
 737     <refsect1>
 738       <title>Examples</title>
 739       <screen>
 740 (defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
 741 => *E1*
 742 (slot-value *e1* 'email)
 743 => "lenin@soviet.org"
 744 (update-records [employee]
 745                 :av-pairs '(([email] "v.lenin@soviet.org"))
 746                 :where [= [emplid] 1])
 747 =>
 748 (update-instance-from-records *e1*)
 749 => #&lt;EMPLOYEE {4806B53D}>
 750 (slot-value *e1* 'email)
 751 => "v.lenin@soviet.org"
 752       </screen>
 753     </refsect1>
 754     <refsect1>
 755       <title>Side Effects</title>
 756       <para>
 757         Slot values of <parameter>object</parameter> may be modified.
 758       </para>
 759     </refsect1>
 760     <refsect1>
 761       <title>Affected by</title>
 762       <para>
 763         <simplelist>
 764           <member>Data in SQL database.</member>
 765         </simplelist>
 766       </para>
 767     </refsect1>
 768     <refsect1>
 769       <title>Exceptional Situations</title>
 770       <para>
 771         If <parameter>database</parameter> is not able to be read.
 772       </para>
 773     </refsect1>
 774     <refsect1>
 775       <title>See Also</title>
 776       <simplelist>
 777         <member><link linkend="update-slot-from-record"><function>update-slot-from-record</function></link></member>
 778         <member><link linkend="update-objects-joins"><function>update-objects-joins</function></link></member>
 779       </simplelist>
 780     </refsect1>
 781     <refsect1>
 782       <title>Notes</title>
 783       <para>
 784         None.
 785       </para>
 786     </refsect1>
 787   </refentry>
 788
 789   <refentry id="update-slot-from-record">
 790     <refnamediv>
 791       <refname>UPDATE-SLOT-FROM-RECORD</refname>
 792       <refpurpose>Update objects slot from database.</refpurpose>
 793       <refclass>Function</refclass>
 794     </refnamediv>
 795     <refsect1>
 796       <title>Syntax</title>
 797       <synopsis>
 798       <function>update-slot-from-record</function> <replaceable>object</replaceable> <replaceable>slot</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>object</returnvalue></synopsis>
 799     </refsect1>
 800     <refsect1>
 801       <title>Arguments and Values</title>
 802       <variablelist>
 803         <varlistentry>
 804           <term><parameter>object</parameter></term>
 805           <listitem>
 806             <para>
 807               An instance of a <glossterm linkend="gloss-view-class">View Class</glossterm>.
 808             </para>
 809           </listitem>
 810         </varlistentry>
 811         <varlistentry>
 812           <term><parameter>slot</parameter></term>
 813           <listitem>
 814             <para>
 815               The name of a slot in <parameter>object</parameter>.
 816             </para>
 817           </listitem>
 818         </varlistentry>
 819         <varlistentry>
 820           <term><parameter>database</parameter></term>
 821           <listitem>
 822             <para>
 823               A <glossterm linkend="gloss-database-object">database
 824               object</glossterm>. This will default to the value of
 825               <symbol>*default-database*</symbol>.
 826             </para>
 827           </listitem>
 828         </varlistentry>
 829       </variablelist>
 830     </refsect1>
 831     <refsect1>
 832       <title>Description</title>
 833       <para>Updates the slot value, specified by the CLOS slot name
 834       <parameter>slot</parameter>, of the <glossterm
 835       linkend="gloss-view-class">View Class</glossterm> instance
 836       <parameter>object</parameter> using the attribute values of the
 837       appropriate table of <parameter>database</parameter> which
 838       defaults to the database associated with
 839       <parameter>object</parameter> or, if
 840       <parameter>object</parameter> is not associated with a database,
 841       <varname>*default-database*</varname>.  Join slots are updated
 842       but instances of the class on which the join is made are not
 843       updated.
 844       </para>
 845     </refsect1>
 846     <refsect1>
 847       <title>Examples</title>
 848       <screen>
 849 (defvar *e1* (car (select 'employee :where [= [slot-value 'employee 'emplid] 1] :flatp t)))
 850 => *E1*
 851 (slot-value *e1* 'email)
 852 => "lenin@soviet.org"
 853 (update-records [employee]
 854                 :av-pairs '(([email] "v.lenin@soviet.org"))
 855                 :where [= [emplid] 1])
 856 =>
 857 (update-slot-from-record *e1* 'email)
 858 => #&lt;EMPLOYEE {4806B53D}>
 859 (slot-value *e1* 'email)
 860 => "v.lenin@soviet.org"
 861       </screen>
 862     </refsect1>
 863     <refsect1>
 864       <title>Side Effects</title>
 865       <para>
 866         Modifies the slot value of the object.
 867       </para>
 868     </refsect1>
 869     <refsect1>
 870       <title>Affected by</title>
 871       <para>
 872         <simplelist>
 873           <member>Data in SQL database.</member>
 874         </simplelist>
 875       </para>
 876     </refsect1>
 877     <refsect1>
 878       <title>Exceptional Situations</title>
 879       <para>
 880         Database errors.
 881       </para>
 882     </refsect1>
 883     <refsect1>
 884       <title>See Also</title>
 885       <simplelist>
 886         <member><link linkend="update-instance-from-records"><function>update-instance-from-records</function></link></member>
 887         <member><link linkend="update-objects-joins"><function>update-objects-joins</function></link></member>
 888       </simplelist>
 889     </refsect1>
 890     <refsect1>
 891       <title>Notes</title>
 892       <para>
 893         None.
 894       </para>
 895     </refsect1>
 896   </refentry>
 897
 898   <refentry id="update-objects-joins">
 899     <refnamediv>
 900       <refname>UPDATE-OBJECTS-JOINS</refname>
 901       <refpurpose>Updates joined slots of objects.</refpurpose>
 902       <refclass>Function</refclass>
 903     </refnamediv>
 904     <refsect1>
 905       <title>Syntax</title>
 906       <synopsis>
 907       <function>update-objects-joins</function> <replaceable>objects</replaceable> &amp;key <replaceable>slots</replaceable> <replaceable>force-p</replaceable> <replaceable>class-name</replaceable> <replaceable>max-len</replaceable> => <returnvalue><!-- no result --></returnvalue></synopsis>
 908     </refsect1>
 909     <refsect1>
 910       <title>Arguments and Values</title>
 911       <variablelist>
 912         <varlistentry>
 913           <term><parameter>objects</parameter></term>
 914           <listitem>
 915             <para>
 916               A list of instances of a <glossterm
 917               linkend="gloss-view-class">View Class</glossterm>.
 918             </para>
 919           </listitem>
 920         </varlistentry>
 921         <varlistentry>
 922           <term><parameter>slots</parameter></term>
 923           <listitem>
 924             <para>
 925               A list of slot names in <parameter>object</parameter> or &t;.
 926             </para>
 927           </listitem>
 928         </varlistentry>
 929         <varlistentry>
 930           <term><parameter>force-p</parameter></term>
 931           <listitem>
 932             <para>
 933               A Boolean, defaulting to &t;.
 934             </para>
 935           </listitem>
 936         </varlistentry>
 937         <varlistentry>
 938           <term><parameter>class-name</parameter></term>
 939           <listitem>
 940             <para>
 941               A list of instances of a <glossterm
 942               linkend="gloss-view-class">View Class</glossterm>.
 943             </para>
 944           </listitem>
 945         </varlistentry>
 946         <varlistentry>
 947           <term><parameter>max-len</parameter></term>
 948           <listitem>
 949             <para>
 950               A non-negative integer or &nil; defaulting to
 951               <symbol>*default-update-objects-max-len*</symbol>.
 952             </para>
 953           </listitem>
 954         </varlistentry>
 955       </variablelist>
 956     </refsect1>
 957     <refsect1>
 958       <title>Description</title>
 959       <para>Updates from the records of the appropriate database
 960       tables the join slots specified by <parameter>slots</parameter>
 961       in the supplied list of <glossterm linkend="gloss-view-class">View
 962       Class</glossterm> instances
 963       <parameter>objects</parameter>. <parameter>slots</parameter>
 964       when &t; means that all join slots with
 965       <symbol>:retrieval</symbol> <symbol>:immediate</symbol> are
 966       updated. <parameter>class-name</parameter> is used to specify
 967       the <glossterm linkend="gloss-view-class">View Class</glossterm> of
 968       all instance in <parameter>objects</parameter>, when &nil; then
 969       the class of the first instance in
 970       <parameter>objects</parameter> is
 971       used. <parameter>force-p</parameter> when &t; means that all
 972       join slots are updated whereas a value of &nil; means that only
 973       unbound join slots are updated. <parameter>max-len</parameter>
 974       when non-nil specifies that
 975       <function>update-object-joins</function> may issue multiple
 976       database queries with a maximum of
 977       <parameter>max-len</parameter> instances updated in each query.
 978       </para>
 979     </refsect1>
 980     <refsect1>
 981       <title>Examples</title>
 982       <screen>
 983 (defvar *addresses* (select 'deferred-employee-address :order-by [ea_join aaddressid] :flatp t))
 984 => *ADDRESSES*
 985 (slot-boundp (car *addresses*) 'address)
 986 => NIL
 987 (update-objects-joins *addresses*)
 988 =>
 989 (slot-boundp (car *addresses*) 'address)
 990 => T
 991 (slot-value (car *addresses*) 'address)
 992 => #&lt;ADDRESS {480B0F1D}>
 993       </screen>
 994     </refsect1>
 995     <refsect1>
 996       <title>Side Effects</title>
 997       <para>
 998         The slot values of <parameter>objects</parameter> are modified.
 999       </para>
1000     </refsect1>
1001     <refsect1>
1002       <title>Affected by</title>
1003       <para>
1004         <simplelist>
1005           <member><link
1006           linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
1007         </simplelist>
1008       </para>
1009     </refsect1>
1010     <refsect1>
1011       <title>Exceptional Situations</title>
1012       <para>
1013         Database errors.
1014       </para>
1015     </refsect1>
1016     <refsect1>
1017       <title>See Also</title>
1018       <simplelist>
1019         <member><link linkend="default-update-objects-max-len"><varname>*default-update-objects-max-len*</varname></link></member>
1020         <member><link linkend="update-instance-from-records"><function>update-instance-from-records</function></link></member>
1021         <member><link linkend="update-slot-from-record"><function>update-slot-from-record</function></link></member>
1022       </simplelist>
1023     </refsect1>
1024     <refsect1>
1025       <title>Notes</title>
1026       <para>
1027         None.
1028       </para>
1029     </refsect1>
1030   </refentry>
1031
1032 </reference>