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