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       <!-- introduction -->
  14     </para>
  15   </partintro>
  16
  17   <refentry id="db-auto-sync">
  18     <refnamediv>
  19       <refname>*DB-AUTO-SYNC*</refname>
  20       <refpurpose>Enables SQL storage during Lisp object creation.</refpurpose>
  21       <refclass>Variable</refclass>
  22     </refnamediv>
  23     <refsect1>
  24       <title>Value Type</title>
  25       <para>
  26         Boolean
  27       </para>
  28     </refsect1>
  29     <refsect1>
  30       <title>Initial Value</title>
  31       <para>&nil;</para>
  32     </refsect1>
  33     <refsect1>
  34       <title>Description</title>
  35       When this variable is &t; an instance is stored in the SQL database when the instance is created
  36       by <function>make-instance</function>. When this variable is &nil;, which is the default value, &clsql;
  37       behaves like &commonsql;: instances of view classes are stored to the SQL database only when
  38       <link linkend="update-record-from-slots"><function>update-record-from-slots</function></link>
  39       is called.
  40     </refsect1>
  41     <refsect1>
  42       <title>Examples</title>
  43       <screen>
  44         (let ((instance (make-instance 'foo)))
  45           (update-record-from-slots instance))
  46
  47         ;; is equivalent to
  48
  49         (let ((*db-auto-sync* t))
  50           (make-instance 'foo))
  51       </screen>
  52     </refsect1>
  53     <refsect1>
  54       <title>Affected By</title>
  55       <para>None.</para>
  56     </refsect1>
  57     <refsect1>
  58       <title>See Also</title>
  59       <simplelist>
  60         <member><link linkend="update-record-from-slots"><function>update-record-from-slots</function></link></member>
  61       </simplelist>
  62     </refsect1>
  63     <refsect1>
  64       <title>Notes</title>
  65       <para>None.</para>
  66     </refsect1>
  67   </refentry>
  68
  69   <refentry id="default-update-objects-max-len">
  70     <refnamediv>
  71       <refname>*DEFAULT-UPDATE-OBJECTS-MAX-LEN*</refname>
  72       <refpurpose>The default maximum number of objects each query to perform a join</refpurpose>
  73       <refclass>Variable</refclass>
  74     </refnamediv>
  75     <refsect1>
  76       <title>Value Type</title>
  77       <para>
  78         (or null integer)
  79       </para>
  80     </refsect1>
  81     <refsect1>
  82       <title>Initial Value</title>
  83       <para>&nil;</para>
  84     </refsect1>
  85     <refsect1>
  86       <title>Description</title>
  87       <para>
  88         This special variable provides the default value for the
  89         <parameter>max-len</parameter> argument of the function <link
  90         linkend="update-object-joins"><function>update-object-joins</function></link>.
  91       </para>
  92     </refsect1>
  93     <refsect1>
  94       <title>Examples</title>
  95       <screen>
  96         (setq *default-update-objects-max-len* 100)
  97       </screen>
  98     </refsect1>
  99     <refsect1>
 100       <title>Affected By</title>
 101       <para>None.</para>
 102     </refsect1>
 103     <refsect1>
 104       <title>See Also</title>
 105       <para>None.</para>
 106     </refsect1>
 107     <refsect1>
 108       <title>Notes</title>
 109       <para>None.</para>
 110     </refsect1>
 111   </refentry>
 112
 113   <refentry id="delete-instance-records">
 114     <refnamediv>
 115       <refname>DELETE-INSTANCE-RECORDS</refname>
 116       <refpurpose>Delete SQL records represented by a view class object</refpurpose>
 117       <refclass>Function</refclass>
 118     </refnamediv>
 119     <refsect1>
 120       <title>Syntax</title>
 121       <synopsis>
 122       <function>(delete-instance-records object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 123     </refsect1>
 124     <refsect1>
 125       <title>Arguments and Values</title>
 126       <variablelist>
 127         <!-- arguments and values -->
 128       </variablelist>
 129     </refsect1>
 130     <refsect1>
 131       <title>Description</title>
 132       <para>Deletes the records represented by OBJECT in the
 133       appropriate table of the database associated with OBJECT. If
 134       OBJECT is not yet associated with a database, an error is
 135       signalled.
 136       </para>
 137     </refsect1>
 138     <refsect1>
 139       <title>Examples</title>
 140       <screen>
 141         * (def-view-class tab () ((a :type integer :db-kind :key) (b :type string)))
 142         #&lt;clsql-sys::db-standard-class tab>
 143         * (defvar obj (let ((*db-auto-sync* t))
 144                         (make-instance 'tab :a 5 :b "the string")))
 145         * (start-sql-recording :type :both)
 146         * (delete-instance-records obj)
 147
 148
 149       </screen>
 150     </refsect1>
 151     <refsect1>
 152       <title>Side Effects</title>
 153       <para>
 154         Deletes data from the SQL database.
 155       </para>
 156     </refsect1>
 157     <refsect1>
 158       <title>Affected by</title>
 159       <para>
 160         Permissions granted by the SQL database to the user in the database connection.
 161       </para>
 162     </refsect1>
 163     <refsect1>
 164       <title>Exceptional Situations</title>
 165       <para>
 166         An exception may be signaled if the database connection user does not have
 167         sufficient privileges to modify the database.
 168       </para>
 169     </refsect1>
 170     <refsect1>
 171       <title>See Also</title>
 172       <para>
 173         <simplelist>
 174           <member><link linkend="update-records"><function>update-records</function></link></member>
 175           <member><link linkend="update-records-from-instance"><function>update-records-from-instance</function></link></member>
 176         </simplelist>
 177       </para>
 178     </refsect1>
 179     <refsect1>
 180       <title>Notes</title>
 181       <para>
 182         Instances are referenced in the database by values stored in the key slots. If
 183         <function>delete-records-from-instance</function> is called with an instance of a class that does
 184         not contain any keys, then all records in that table will be deleted.
 185       </para>
 186     </refsect1>
 187   </refentry>
 188
 189   <refentry id="instance-refreshed">
 190     <refnamediv>
 191       <refname>INSTANCE-REFRESHED</refname>
 192       <refpurpose>Hook to call on object refresh</refpurpose>
 193       <refclass>Generic function</refclass>
 194     </refnamediv>
 195     <refsect1>
 196       <title>Syntax</title>
 197       <synopsis>
 198       <function>(instance-refreshed object)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 199     </refsect1>
 200     <refsect1>
 201       <title>Arguments and Values</title>
 202       <variablelist>
 203         <varlistentry>
 204           <term><parameter>object</parameter></term>
 205           <listitem>
 206             <para>
 207               The view class object which is being refreshed.
 208             </para>
 209           </listitem>
 210         </varlistentry>
 211       </variablelist>
 212     </refsect1>
 213     <refsect1>
 214       <title>Description</title>
 215       <para>Provides a hook which is called within an object
 216       oriented call to SELECT with a non-nil value of REFRESH when
 217       the View Class instance OBJECT has been updated from the
 218       database. A method specialised on STANDARD-DB-OBJECT is
 219       provided which has no effects. Methods specialised on
 220       particular View Classes can be used to specify any operations
 221       that need to be made on View Classes instances which have been
 222       updated in calls to SELECT.
 223       </para>
 224     </refsect1>
 225     <refsect1>
 226       <title>Examples</title>
 227       <screen>
 228         <!-- examples -->
 229       </screen>
 230     </refsect1>
 231     <refsect1>
 232       <title>Side Effects</title>
 233       <para>
 234         <!-- side effects -->
 235       </para>
 236     </refsect1>
 237     <refsect1>
 238       <title>Affected by</title>
 239       <para>
 240         <simplelist>
 241           <!-- affected by -->
 242         </simplelist>
 243       </para>
 244     </refsect1>
 245     <refsect1>
 246       <title>Exceptional Situations</title>
 247       <para>
 248         None.
 249       </para>
 250     </refsect1>
 251     <refsect1>
 252       <title>See Also</title>
 253       <para>
 254         <simplelist>
 255           <!-- see also -->
 256         </simplelist>
 257       </para>
 258     </refsect1>
 259     <refsect1>
 260       <title>Notes</title>
 261       <para>
 262         <!-- notes -->
 263       </para>
 264     </refsect1>
 265   </refentry>
 266
 267   <refentry id="update-instance-from-records">
 268     <refnamediv>
 269       <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
 270       <refpurpose>Update slot values from database.</refpurpose>
 271       <refclass>Function</refclass>
 272     </refnamediv>
 273     <refsect1>
 274       <title>Syntax</title>
 275       <synopsis>
 276       <function>(update-instance-from-records object &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 277     </refsect1>
 278     <refsect1>
 279       <title>Arguments and Values</title>
 280       <variablelist>
 281         <!-- arguments and values -->
 282       </variablelist>
 283     </refsect1>
 284     <refsect1>
 285       <title>Description</title>
 286       <para>Updates the slot values of the View Class instance
 287       OBJECT using the attribute values of the appropriate table of
 288       DATABASE which defaults to the database associated with OBJECT
 289       or, if OBJECT is not associated with a database,
 290       *DEFAULT-DATABASE*.  Join slots are updated but instances of
 291       the class on which the join is made are not updated.
 292       </para>
 293     </refsect1>
 294     <refsect1>
 295       <title>Examples</title>
 296       <screen>
 297         <!-- examples -->
 298       </screen>
 299     </refsect1>
 300     <refsect1>
 301       <title>Side Effects</title>
 302       <para>
 303         <!-- side effects -->
 304       </para>
 305     </refsect1>
 306     <refsect1>
 307       <title>Affected by</title>
 308       <para>
 309         <simplelist>
 310           <!-- affected by -->
 311         </simplelist>
 312       </para>
 313     </refsect1>
 314     <refsect1>
 315       <title>Exceptional Situations</title>
 316       <para>
 317         <!-- execeptional situations -->
 318       </para>
 319     </refsect1>
 320     <refsect1>
 321       <title>See Also</title>
 322       <para>
 323         <simplelist>
 324           <!-- see also -->
 325         </simplelist>
 326       </para>
 327     </refsect1>
 328     <refsect1>
 329       <title>Notes</title>
 330       <para>
 331         <!-- notes -->
 332       </para>
 333     </refsect1>
 334   </refentry>
 335
 336   <refentry id="update-objects-joins">
 337     <refnamediv>
 338       <refname>UPDATE-OBJECTS-JOINS</refname>
 339       <refpurpose>Updates joined slots of objects</refpurpose>
 340       <refclass>Function</refclass>
 341     </refnamediv>
 342     <refsect1>
 343       <title>Syntax</title>
 344       <synopsis>
 345       <function>(update-objects-joins objects &amp;key (slots t) (force-p t) class-name (max-len *default-update-objects-max-len*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 346     </refsect1>
 347     <refsect1>
 348       <title>Arguments and Values</title>
 349       <variablelist>
 350         <!-- arguments and values -->
 351       </variablelist>
 352     </refsect1>
 353     <refsect1>
 354       <title>Description</title>
 355       <para>Updates from the records of the appropriate
 356       database tables the join slots specified by SLOTS in
 357       the supplied list of View Class instances OBJECTS.
 358       SLOTS is t by default which means that all join slots
 359       with :retrieval :immediate are updated. CLASS-NAME is
 360       used to specify the View Class of all instance in
 361       OBJECTS and default to nil which means that the class
 362       of the first instance in OBJECTS is used. FORCE-P is t
 363       by default which means that all join slots are updated
 364       whereas a value of nil means that only unbound join
 365       slots are updated. MAX-LEN defaults to
 366       *DEFAULT-UPDATE-OBJECTS-MAX-LEN* and when non-nil
 367       specifies that UPDATE-OBJECT-JOINS may issue multiple
 368       database queries with a maximum of MAX-LEN instances
 369       updated in each query.
 370       </para>
 371     </refsect1>
 372     <refsect1>
 373       <title>Examples</title>
 374       <screen>
 375         <!-- examples -->
 376       </screen>
 377     </refsect1>
 378     <refsect1>
 379       <title>Side Effects</title>
 380       <para>
 381         <!-- side effects -->
 382       </para>
 383     </refsect1>
 384     <refsect1>
 385       <title>Affected by</title>
 386       <para>
 387         <simplelist>
 388           <!-- affected by -->
 389         </simplelist>
 390       </para>
 391     </refsect1>
 392     <refsect1>
 393       <title>Exceptional Situations</title>
 394       <para>
 395         <!-- execeptional situations -->
 396       </para>
 397     </refsect1>
 398     <refsect1>
 399       <title>See Also</title>
 400       <para>
 401         <simplelist>
 402           <!-- see also -->
 403         </simplelist>
 404       </para>
 405     </refsect1>
 406     <refsect1>
 407       <title>Notes</title>
 408       <para>
 409         <!-- notes -->
 410       </para>
 411     </refsect1>
 412   </refentry>
 413
 414   <refentry id="update-record-from-slot">
 415     <refnamediv>
 416       <refname>UPDATE-RECORD-FROM-SLOT</refname>
 417       <refpurpose>Updates database from slot value</refpurpose>
 418       <refclass>Function</refclass>
 419     </refnamediv>
 420     <refsect1>
 421       <title>Syntax</title>
 422       <synopsis>
 423       <function>(update-record-from-slot object slot &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 424     </refsect1>
 425     <refsect1>
 426       <title>Arguments and Values</title>
 427       <variablelist>
 428         <!-- arguments and values -->
 429       </variablelist>
 430     </refsect1>
 431     <refsect1>
 432       <title>Description</title>
 433       <para>Updates the value stored in the column represented by
 434       the slot, specified by the CLOS slot name SLOT, of View Class
 435       instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
 436       specifies the database in which the update is made only if
 437       OBJECT is not associated with a database. In this case, a
 438       record is created in DATABASE and the attribute represented by
 439       SLOT is initialised from the value of the supplied slots with
 440       other attributes having default values. Furthermore, OBJECT
 441       becomes associated with DATABASE.
 442       </para>
 443     </refsect1>
 444     <refsect1>
 445       <title>Examples</title>
 446       <screen>
 447         <!-- examples -->
 448       </screen>
 449     </refsect1>
 450     <refsect1>
 451       <title>Side Effects</title>
 452       <para>
 453         <!-- side effects -->
 454       </para>
 455     </refsect1>
 456     <refsect1>
 457       <title>Affected by</title>
 458       <para>
 459         <simplelist>
 460           <!-- affected by -->
 461         </simplelist>
 462       </para>
 463     </refsect1>
 464     <refsect1>
 465       <title>Exceptional Situations</title>
 466       <para>
 467         <!-- execeptional situations -->
 468       </para>
 469     </refsect1>
 470     <refsect1>
 471       <title>See Also</title>
 472       <para>
 473         <simplelist>
 474           <!-- see also -->
 475         </simplelist>
 476       </para>
 477     </refsect1>
 478     <refsect1>
 479       <title>Notes</title>
 480       <para>
 481         <!-- notes -->
 482       </para>
 483     </refsect1>
 484   </refentry>
 485
 486   <refentry id="update-record-from-slots">
 487     <refnamediv>
 488       <refname>UPDATE-RECORD-FROM-SLOTS</refname>
 489       <refpurpose>Update database from slots of view class object</refpurpose>
 490       <refclass>Function</refclass>
 491     </refnamediv>
 492     <refsect1>
 493       <title>Syntax</title>
 494       <synopsis>
 495       <function>(update-record-from-slots object slots &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 496     </refsect1>
 497     <refsect1>
 498       <title>Arguments and Values</title>
 499       <variablelist>
 500         <!-- arguments and values -->
 501       </variablelist>
 502     </refsect1>
 503     <refsect1>
 504       <title>Description</title>
 505       <para>Updates the values stored in the columns represented by
 506       the slots, specified by the CLOS slot names SLOTS, of View
 507       Class instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE*
 508       and specifies the database in which the update is made only if
 509       OBJECT is not associated with a database. In this case, a
 510       record is created in the appropriate table of DATABASE and the
 511       attributes represented by SLOTS are initialised from the
 512       values of the supplied slots with other attributes having
 513       default values. Furthermore, OBJECT becomes associated with
 514       DATABASE.
 515       </para>
 516     </refsect1>
 517     <refsect1>
 518       <title>Examples</title>
 519       <screen>
 520         <!-- examples -->
 521       </screen>
 522     </refsect1>
 523     <refsect1>
 524       <title>Side Effects</title>
 525       <para>
 526         <!-- side effects -->
 527       </para>
 528     </refsect1>
 529     <refsect1>
 530       <title>Affected by</title>
 531       <para>
 532         <simplelist>
 533           <!-- affected by -->
 534         </simplelist>
 535       </para>
 536     </refsect1>
 537     <refsect1>
 538       <title>Exceptional Situations</title>
 539       <para>
 540         <!-- execeptional situations -->
 541       </para>
 542     </refsect1>
 543     <refsect1>
 544       <title>See Also</title>
 545       <para>
 546         <simplelist>
 547           <!-- see also -->
 548         </simplelist>
 549       </para>
 550     </refsect1>
 551     <refsect1>
 552       <title>Notes</title>
 553       <para>
 554         <!-- notes -->
 555       </para>
 556     </refsect1>
 557   </refentry>
 558
 559
 560   <refentry id="update-records-from-instance">
 561     <refnamediv>
 562       <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
 563       <refpurpose>Update database from view class object.</refpurpose>
 564       <refclass>Function</refclass>
 565     </refnamediv>
 566     <refsect1>
 567       <title>Syntax</title>
 568       <synopsis>
 569       <function>(update-records-from-instance object &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 570     </refsect1>
 571     <refsect1>
 572       <title>Arguments and Values</title>
 573       <variablelist>
 574         <!-- arguments and values -->
 575       </variablelist>
 576     </refsect1>
 577     <refsect1>
 578       <title>Description</title>
 579       <para>Using an instance of a View Class, OBJECT, update the
 580       table that stores its instance data. DATABASE defaults to
 581       *DEFAULT-DATABASE* and specifies the database in which the
 582       update is made only if OBJECT is not associated with a
 583       database. In this case, a record is created in the appropriate
 584       table of DATABASE using values from the slot values of OBJECT,
 585       and OBJECT becomes associated with DATABASE.
 586       </para>
 587     </refsect1>
 588     <refsect1>
 589       <title>Examples</title>
 590       <screen>
 591         <!-- examples -->
 592       </screen>
 593     </refsect1>
 594     <refsect1>
 595       <title>Side Effects</title>
 596       <para>
 597         <!-- side effects -->
 598       </para>
 599     </refsect1>
 600     <refsect1>
 601       <title>Affected by</title>
 602       <para>
 603         <simplelist>
 604           <!-- affected by -->
 605         </simplelist>
 606       </para>
 607     </refsect1>
 608     <refsect1>
 609       <title>Exceptional Situations</title>
 610       <para>
 611         <!-- execeptional situations -->
 612       </para>
 613     </refsect1>
 614     <refsect1>
 615       <title>See Also</title>
 616       <para>
 617         <simplelist>
 618           <!-- see also -->
 619         </simplelist>
 620       </para>
 621     </refsect1>
 622     <refsect1>
 623       <title>Notes</title>
 624       <para>
 625         <!-- notes -->
 626       </para>
 627     </refsect1>
 628   </refentry>
 629
 630   <refentry id="update-slot-from-record">
 631     <refnamediv>
 632       <refname>UPDATE-SLOT-FROM-RECORD</refname>
 633       <refpurpose>Update objects slot from database.</refpurpose>
 634       <refclass>Function</refclass>
 635     </refnamediv>
 636     <refsect1>
 637       <title>Syntax</title>
 638       <synopsis>
 639       <function>(update-slot-from-record object slot &amp;key database)</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 640     </refsect1>
 641     <refsect1>
 642       <title>Arguments and Values</title>
 643       <variablelist>
 644         <!-- arguments and values -->
 645       </variablelist>
 646     </refsect1>
 647     <refsect1>
 648       <title>Description</title>
 649       <para>Updates the slot value, specified by the CLOS slot name
 650       SLOT, of the View Class instance OBJECT using the attribute
 651       values of the appropriate table of DATABASE which defaults to
 652       the database associated with OBJECT or, if OBJECT is not
 653       associated with a database, *DEFAULT-DATABASE*.  Join slots
 654       are updated but instances of the class on which the join is
 655       made are not updated.
 656       </para>
 657     </refsect1>
 658     <refsect1>
 659       <title>Examples</title>
 660       <screen>
 661         <!-- examples -->
 662       </screen>
 663     </refsect1>
 664     <refsect1>
 665       <title>Side Effects</title>
 666       <para>
 667         <!-- side effects -->
 668       </para>
 669     </refsect1>
 670     <refsect1>
 671       <title>Affected by</title>
 672       <para>
 673         <simplelist>
 674           <!-- affected by -->
 675         </simplelist>
 676       </para>
 677     </refsect1>
 678     <refsect1>
 679       <title>Exceptional Situations</title>
 680       <para>
 681         <!-- execeptional situations -->
 682       </para>
 683     </refsect1>
 684     <refsect1>
 685       <title>See Also</title>
 686       <para>
 687         <simplelist>
 688           <!-- see also -->
 689         </simplelist>
 690       </para>
 691     </refsect1>
 692     <refsect1>
 693       <title>Notes</title>
 694       <para>
 695         <!-- notes -->
 696       </para>
 697     </refsect1>
 698   </refentry>
 699
 700 </reference>