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><!-- purpose --></refpurpose>
 193       <refclass>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         <!-- arguments and values -->
 204       </variablelist>
 205     </refsect1>
 206     <refsect1>
 207       <title>Description</title>
 208       <para>Provides a hook which is called within an object
 209       oriented call to SELECT with a non-nil value of REFRESH when
 210       the View Class instance OBJECT has been updated from the
 211       database. A method specialised on STANDARD-DB-OBJECT is
 212       provided which has no effects. Methods specialised on
 213       particular View Classes can be used to specify any operations
 214       that need to be made on View Classes instances which have been
 215       updated in calls to SELECT.
 216       </para>
 217     </refsect1>
 218     <refsect1>
 219       <title>Examples</title>
 220       <screen>
 221         <!-- examples -->
 222       </screen>
 223     </refsect1>
 224     <refsect1>
 225       <title>Side Effects</title>
 226       <para>
 227         <!-- side effects -->
 228       </para>
 229     </refsect1>
 230     <refsect1>
 231       <title>Affected by</title>
 232       <para>
 233         <simplelist>
 234           <!-- affected by -->
 235         </simplelist>
 236       </para>
 237     </refsect1>
 238     <refsect1>
 239       <title>Exceptional Situations</title>
 240       <para>
 241         <!-- execeptional situations -->
 242       </para>
 243     </refsect1>
 244     <refsect1>
 245       <title>See Also</title>
 246       <para>
 247         <simplelist>
 248           <!-- see also -->
 249         </simplelist>
 250       </para>
 251     </refsect1>
 252     <refsect1>
 253       <title>Notes</title>
 254       <para>
 255         <!-- notes -->
 256       </para>
 257     </refsect1>
 258   </refentry>
 259
 260   <refentry id="update-instance-from-records">
 261     <refnamediv>
 262       <refname>UPDATE-INSTANCE-FROM-RECORDS</refname>
 263       <refpurpose><!-- purpose --></refpurpose>
 264       <refclass>Function</refclass>
 265     </refnamediv>
 266     <refsect1>
 267       <title>Syntax</title>
 268       <synopsis>
 269       <function> (UPDATE-INSTANCE-FROM-RECORDS OBJECT &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 270     </refsect1>
 271     <refsect1>
 272       <title>Arguments and Values</title>
 273       <variablelist>
 274         <!-- arguments and values -->
 275       </variablelist>
 276     </refsect1>
 277     <refsect1>
 278       <title>Description</title>
 279       <para>Updates the slot values of the View Class instance
 280       OBJECT using the attribute values of the appropriate table of
 281       DATABASE which defaults to the database associated with OBJECT
 282       or, if OBJECT is not associated with a database,
 283       *DEFAULT-DATABASE*.  Join slots are updated but instances of
 284       the class on which the join is made are not updated.
 285       </para>
 286     </refsect1>
 287     <refsect1>
 288       <title>Examples</title>
 289       <screen>
 290         <!-- examples -->
 291       </screen>
 292     </refsect1>
 293     <refsect1>
 294       <title>Side Effects</title>
 295       <para>
 296         <!-- side effects -->
 297       </para>
 298     </refsect1>
 299     <refsect1>
 300       <title>Affected by</title>
 301       <para>
 302         <simplelist>
 303           <!-- affected by -->
 304         </simplelist>
 305       </para>
 306     </refsect1>
 307     <refsect1>
 308       <title>Exceptional Situations</title>
 309       <para>
 310         <!-- execeptional situations -->
 311       </para>
 312     </refsect1>
 313     <refsect1>
 314       <title>See Also</title>
 315       <para>
 316         <simplelist>
 317           <!-- see also -->
 318         </simplelist>
 319       </para>
 320     </refsect1>
 321     <refsect1>
 322       <title>Notes</title>
 323       <para>
 324         <!-- notes -->
 325       </para>
 326     </refsect1>
 327   </refentry>
 328
 329   <refentry id="update-objects-joins">
 330     <refnamediv>
 331       <refname>UPDATE-OBJECTS-JOINS</refname>
 332       <refpurpose><!-- purpose --></refpurpose>
 333       <refclass>Function</refclass>
 334     </refnamediv>
 335     <refsect1>
 336       <title>Syntax</title>
 337       <synopsis>
 338       <function> (UPDATE-OBJECTS-JOINS OBJECTS &amp;KEY (SLOTS T) (FORCE-P T) CLASS-NAME (MAX-LEN *DEFAULT-UPDATE-OBJECTS-MAX-LEN*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 339     </refsect1>
 340     <refsect1>
 341       <title>Arguments and Values</title>
 342       <variablelist>
 343         <!-- arguments and values -->
 344       </variablelist>
 345     </refsect1>
 346     <refsect1>
 347       <title>Description</title>
 348       <para>Updates from the records of the appropriate
 349       database tables the join slots specified by SLOTS in
 350       the supplied list of View Class instances OBJECTS.
 351       SLOTS is t by default which means that all join slots
 352       with :retrieval :immediate are updated. CLASS-NAME is
 353       used to specify the View Class of all instance in
 354       OBJECTS and default to nil which means that the class
 355       of the first instance in OBJECTS is used. FORCE-P is t
 356       by default which means that all join slots are updated
 357       whereas a value of nil means that only unbound join
 358       slots are updated. MAX-LEN defaults to
 359       *DEFAULT-UPDATE-OBJECTS-MAX-LEN* and when non-nil
 360       specifies that UPDATE-OBJECT-JOINS may issue multiple
 361       database queries with a maximum of MAX-LEN instances
 362       updated in each query.
 363       </para>
 364     </refsect1>
 365     <refsect1>
 366       <title>Examples</title>
 367       <screen>
 368         <!-- examples -->
 369       </screen>
 370     </refsect1>
 371     <refsect1>
 372       <title>Side Effects</title>
 373       <para>
 374         <!-- side effects -->
 375       </para>
 376     </refsect1>
 377     <refsect1>
 378       <title>Affected by</title>
 379       <para>
 380         <simplelist>
 381           <!-- affected by -->
 382         </simplelist>
 383       </para>
 384     </refsect1>
 385     <refsect1>
 386       <title>Exceptional Situations</title>
 387       <para>
 388         <!-- execeptional situations -->
 389       </para>
 390     </refsect1>
 391     <refsect1>
 392       <title>See Also</title>
 393       <para>
 394         <simplelist>
 395           <!-- see also -->
 396         </simplelist>
 397       </para>
 398     </refsect1>
 399     <refsect1>
 400       <title>Notes</title>
 401       <para>
 402         <!-- notes -->
 403       </para>
 404     </refsect1>
 405   </refentry>
 406
 407   <refentry id="update-record-from-slot">
 408     <refnamediv>
 409       <refname>UPDATE-RECORD-FROM-SLOT</refname>
 410       <refpurpose><!-- purpose --></refpurpose>
 411       <refclass>Function</refclass>
 412     </refnamediv>
 413     <refsect1>
 414       <title>Syntax</title>
 415       <synopsis>
 416       <function> (UPDATE-RECORD-FROM-SLOT OBJECT SLOT &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 417     </refsect1>
 418     <refsect1>
 419       <title>Arguments and Values</title>
 420       <variablelist>
 421         <!-- arguments and values -->
 422       </variablelist>
 423     </refsect1>
 424     <refsect1>
 425       <title>Description</title>
 426       <para>Updates the value stored in the column represented by
 427       the slot, specified by the CLOS slot name SLOT, of View Class
 428       instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE* and
 429       specifies the database in which the update is made only if
 430       OBJECT is not associated with a database. In this case, a
 431       record is created in DATABASE and the attribute represented by
 432       SLOT is initialised from the value of the supplied slots with
 433       other attributes having default values. Furthermore, OBJECT
 434       becomes associated with DATABASE.
 435       </para>
 436     </refsect1>
 437     <refsect1>
 438       <title>Examples</title>
 439       <screen>
 440         <!-- examples -->
 441       </screen>
 442     </refsect1>
 443     <refsect1>
 444       <title>Side Effects</title>
 445       <para>
 446         <!-- side effects -->
 447       </para>
 448     </refsect1>
 449     <refsect1>
 450       <title>Affected by</title>
 451       <para>
 452         <simplelist>
 453           <!-- affected by -->
 454         </simplelist>
 455       </para>
 456     </refsect1>
 457     <refsect1>
 458       <title>Exceptional Situations</title>
 459       <para>
 460         <!-- execeptional situations -->
 461       </para>
 462     </refsect1>
 463     <refsect1>
 464       <title>See Also</title>
 465       <para>
 466         <simplelist>
 467           <!-- see also -->
 468         </simplelist>
 469       </para>
 470     </refsect1>
 471     <refsect1>
 472       <title>Notes</title>
 473       <para>
 474         <!-- notes -->
 475       </para>
 476     </refsect1>
 477   </refentry>
 478
 479   <refentry id="update-record-from-slots">
 480     <refnamediv>
 481       <refname>UPDATE-RECORD-FROM-SLOTS</refname>
 482       <refpurpose><!-- purpose --></refpurpose>
 483       <refclass>Function</refclass>
 484     </refnamediv>
 485     <refsect1>
 486       <title>Syntax</title>
 487       <synopsis>
 488       <function> (UPDATE-RECORD-FROM-SLOTS OBJECT SLOTS &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 489     </refsect1>
 490     <refsect1>
 491       <title>Arguments and Values</title>
 492       <variablelist>
 493         <!-- arguments and values -->
 494       </variablelist>
 495     </refsect1>
 496     <refsect1>
 497       <title>Description</title>
 498       <para>Updates the values stored in the columns represented by
 499       the slots, specified by the CLOS slot names SLOTS, of View
 500       Class instance OBJECT. DATABASE defaults to *DEFAULT-DATABASE*
 501       and specifies the database in which the update is made only if
 502       OBJECT is not associated with a database. In this case, a
 503       record is created in the appropriate table of DATABASE and the
 504       attributes represented by SLOTS are initialised from the
 505       values of the supplied slots with other attributes having
 506       default values. Furthermore, OBJECT becomes associated with
 507       DATABASE.
 508       </para>
 509     </refsect1>
 510     <refsect1>
 511       <title>Examples</title>
 512       <screen>
 513         <!-- examples -->
 514       </screen>
 515     </refsect1>
 516     <refsect1>
 517       <title>Side Effects</title>
 518       <para>
 519         <!-- side effects -->
 520       </para>
 521     </refsect1>
 522     <refsect1>
 523       <title>Affected by</title>
 524       <para>
 525         <simplelist>
 526           <!-- affected by -->
 527         </simplelist>
 528       </para>
 529     </refsect1>
 530     <refsect1>
 531       <title>Exceptional Situations</title>
 532       <para>
 533         <!-- execeptional situations -->
 534       </para>
 535     </refsect1>
 536     <refsect1>
 537       <title>See Also</title>
 538       <para>
 539         <simplelist>
 540           <!-- see also -->
 541         </simplelist>
 542       </para>
 543     </refsect1>
 544     <refsect1>
 545       <title>Notes</title>
 546       <para>
 547         <!-- notes -->
 548       </para>
 549     </refsect1>
 550   </refentry>
 551
 552
 553   <refentry id="update-records-from-instance">
 554     <refnamediv>
 555       <refname>UPDATE-RECORDS-FROM-INSTANCE</refname>
 556       <refpurpose><!-- purpose --></refpurpose>
 557       <refclass>Function</refclass>
 558     </refnamediv>
 559     <refsect1>
 560       <title>Syntax</title>
 561       <synopsis>
 562       <function> (UPDATE-RECORDS-FROM-INSTANCE OBJECT &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 563     </refsect1>
 564     <refsect1>
 565       <title>Arguments and Values</title>
 566       <variablelist>
 567         <!-- arguments and values -->
 568       </variablelist>
 569     </refsect1>
 570     <refsect1>
 571       <title>Description</title>
 572       <para>Using an instance of a View Class, OBJECT, update the
 573       table that stores its instance data. DATABASE defaults to
 574       *DEFAULT-DATABASE* and specifies the database in which the
 575       update is made only if OBJECT is not associated with a
 576       database. In this case, a record is created in the appropriate
 577       table of DATABASE using values from the slot values of OBJECT,
 578       and OBJECT becomes associated with DATABASE.
 579       </para>
 580     </refsect1>
 581     <refsect1>
 582       <title>Examples</title>
 583       <screen>
 584         <!-- examples -->
 585       </screen>
 586     </refsect1>
 587     <refsect1>
 588       <title>Side Effects</title>
 589       <para>
 590         <!-- side effects -->
 591       </para>
 592     </refsect1>
 593     <refsect1>
 594       <title>Affected by</title>
 595       <para>
 596         <simplelist>
 597           <!-- affected by -->
 598         </simplelist>
 599       </para>
 600     </refsect1>
 601     <refsect1>
 602       <title>Exceptional Situations</title>
 603       <para>
 604         <!-- execeptional situations -->
 605       </para>
 606     </refsect1>
 607     <refsect1>
 608       <title>See Also</title>
 609       <para>
 610         <simplelist>
 611           <!-- see also -->
 612         </simplelist>
 613       </para>
 614     </refsect1>
 615     <refsect1>
 616       <title>Notes</title>
 617       <para>
 618         <!-- notes -->
 619       </para>
 620     </refsect1>
 621   </refentry>
 622
 623   <refentry id="update-slot-from-record">
 624     <refnamediv>
 625       <refname>UPDATE-SLOT-FROM-RECORD</refname>
 626       <refpurpose><!-- purpose --></refpurpose>
 627       <refclass>Function</refclass>
 628     </refnamediv>
 629     <refsect1>
 630       <title>Syntax</title>
 631       <synopsis>
 632       <function> (UPDATE-SLOT-FROM-RECORD OBJECT SLOT &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 633     </refsect1>
 634     <refsect1>
 635       <title>Arguments and Values</title>
 636       <variablelist>
 637         <!-- arguments and values -->
 638       </variablelist>
 639     </refsect1>
 640     <refsect1>
 641       <title>Description</title>
 642       <para>Updates the slot value, specified by the CLOS slot name
 643       SLOT, of the View Class instance OBJECT using the attribute
 644       values of the appropriate table of DATABASE which defaults to
 645       the database associated with OBJECT or, if OBJECT is not
 646       associated with a database, *DEFAULT-DATABASE*.  Join slots
 647       are updated but instances of the class on which the join is
 648       made are not updated.
 649       </para>
 650     </refsect1>
 651     <refsect1>
 652       <title>Examples</title>
 653       <screen>
 654         <!-- examples -->
 655       </screen>
 656     </refsect1>
 657     <refsect1>
 658       <title>Side Effects</title>
 659       <para>
 660         <!-- side effects -->
 661       </para>
 662     </refsect1>
 663     <refsect1>
 664       <title>Affected by</title>
 665       <para>
 666         <simplelist>
 667           <!-- affected by -->
 668         </simplelist>
 669       </para>
 670     </refsect1>
 671     <refsect1>
 672       <title>Exceptional Situations</title>
 673       <para>
 674         <!-- execeptional situations -->
 675       </para>
 676     </refsect1>
 677     <refsect1>
 678       <title>See Also</title>
 679       <para>
 680         <simplelist>
 681           <!-- see also -->
 682         </simplelist>
 683       </para>
 684     </refsect1>
 685     <refsect1>
 686       <title>Notes</title>
 687       <para>
 688         <!-- notes -->
 689       </para>
 690     </refsect1>
 691   </refentry>
 692
 693 </reference>