doc/ref-ooddl.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 Definition Language -->
   9 <reference id="ref-ooddl">
  10   <title>Object Oriented Data Definition Language (OODDL)</title>
  11   <partintro>
  12     <para>
  13       The Object Oriented Data Definition Language (OODDL) provides
  14       access to relational SQL tables using Common Lisp Object System
  15       (CLOS) objects.  SQL tables are mapped to CLOS objects with the
  16       SQL columns being mapped to slots of the CLOS object.
  17     </para>
  18     <para>
  19       The mapping between SQL tables and CLOS objects is defined
  20       with the macro <link
  21       linkend="def-view-class"><function>def-view-class</function></link>. SQL
  22       tables are created with <link
  23       linkend="create-view-from-class"><function>create-view-from-class</function></link>
  24       and SQL tables can be deleted with <link
  25       linkend="drop-view-from-class"><function>drop-view-from-class</function></link>.
  26     </para>
  27     <note>
  28       <para>The above functions refer to the Lisp <emphasis>view</emphasis> of the SQL
  29     table. This Lisp view should not be confused with SQL <function>VIEW</function> statement.</para>
  30     </note>
  31   </partintro>
  32
  33   <refentry id="standard-db-object">
  34     <refnamediv>
  35       <refname>STANDARD-DB-OBJECT</refname>
  36       <refpurpose>Superclass for all &clsql; View Classes.</refpurpose>
  37       <refclass>Class</refclass>
  38     </refnamediv>
  39     <refsect1>
  40       <title>Class Precedence List</title>
  41       <para>
  42         <simplelist type="inline">
  43           <member><type>standard-db-object</type></member>
  44           <member><type>standard-object</type></member>
  45           <member><type>t</type></member>
  46         </simplelist>
  47       </para>
  48     </refsect1>
  49     <refsect1>
  50       <title>Description</title> <para>This class is the superclass
  51       of all &clsql; View Classes.</para>
  52     </refsect1>
  53     <refsect1>
  54       <title>Class details</title>
  55       <programlisting>(defclass STANDARD-DB-OBJECT ()(...))</programlisting>
  56     </refsect1>
  57     <refsect1>
  58       <title>Slots</title>
  59       <para>
  60         <simplelist>
  61           <member>slot VIEW-DATABASE is of type (OR NULL DATABASE)
  62           which stores the associated database for the
  63           instance.</member>
  64         </simplelist>
  65       </para>
  66     </refsect1>
  67   </refentry>
  68
  69   <refentry id="default-string-length">
  70     <refnamediv>
  71       <refname>*DEFAULT-STRING-LENGTH*</refname>
  72       <refpurpose>Default length of SQL strings.</refpurpose>
  73       <refclass>Variable</refclass>
  74     </refnamediv>
  75     <refsect1>
  76       <title>Value Type</title>
  77       <para>
  78         Fixnum
  79       </para>
  80     </refsect1>
  81     <refsect1>
  82       <title>Initial Value</title>
  83       <para><parameter>255</parameter></para>
  84     </refsect1>
  85     <refsect1>
  86       <title>Description</title>
  87       <para>
  88         If a slot of a class defined by
  89         <function>DEF-VIEW-CLASS</function> is of the type
  90         <parameter>STRING</parameter> or <parameter>VARCHAR</parameter> and does
  91         not have a length specified, then the value of this variable
  92         is used as SQL length.
  93       </para>
  94     </refsect1>
  95     <refsect1>
  96       <title>Examples</title>
  97       <screen>
  98         (let ((*default-string-length* 80))
  99         (def-view-class s80 ()
 100         ((a :type string)
 101         (b :type (string 80))
 102         (c :type varchar))))
 103         (create-view-from-class 's80)
 104       </screen>
 105       <para>
 106         The above code causes a SQL table to be created with the SQL command
 107       </para>
 108       <screen>CREATE TABLE (A VARCHAR(80), B CHAR(80), C VARCHAR(80))</screen>
 109     </refsect1>
 110     <refsect1>
 111       <title>Affected By</title>
 112       <para>Some SQL backends do not support <parameter>VARCHAR</parameter>
 113       lengths greater than 255 .</para>
 114     </refsect1>
 115     <refsect1>
 116       <title>See Also</title>
 117       <para>None.</para>
 118     </refsect1>
 119     <refsect1>
 120       <title>Notes</title>
 121       <para>This is a CLSQL extension to the CommonSQL API.</para>
 122     </refsect1>
 123   </refentry>
 124
 125   <refentry id="create-view-from-class">
 126     <refnamediv>
 127       <refname>CREATE-VIEW-FROM-CLASS</refname>
 128       <refpurpose>Create a SQL table from a view class.</refpurpose>
 129       <refclass>Function</refclass>
 130     </refnamediv>
 131     <refsect1>
 132       <title>Syntax</title>
 133       <synopsis>
 134       <function> (create-view-from-class view-class-name &amp;key (database *default-database*) (transactions t))</function> => <returnvalue><!-- no values --></returnvalue></synopsis>
 135     </refsect1>
 136     <refsect1>
 137       <title>Arguments and Values</title>
 138       <variablelist>
 139         <varlistentry>
 140           <term><parameter>view-class-name</parameter></term>
 141           <listitem>
 142             <para>
 143               The name of a view class that has been defined with
 144               <link linkend="def-view-class"><function>def-view-class</function></link>.
 145             </para>
 146           </listitem>
 147         </varlistentry>
 148         <varlistentry>
 149           <term><parameter>database</parameter></term>
 150           <listitem>
 151             <para>
 152               The database in which to create the SQL table.
 153             </para>
 154           </listitem>
 155         </varlistentry>
 156         <varlistentry>
 157           <term><parameter>transactions</parameter></term>
 158           <listitem>
 159             <para>
 160               When &nil; specifies that a table type which does not support transactions should be used.
 161             </para>
 162           </listitem>
 163         </varlistentry>
 164       </variablelist>
 165     </refsect1>
 166     <refsect1>
 167       <title>Description</title>
 168       <para>
 169         Creates a table as defined by the View Class
 170         <parameter>view-class-name</parameter> in <parameter>database</parameter>.
 171       </para>
 172     </refsect1>
 173     <refsect1>
 174       <title>Examples</title>
 175       <screen>
 176         * (def-view-class 'foo () ((a :type (string 80))))
 177         #&lt;CLSQL-SYS::STANDARD-DB-CLASS FOO>
 178         * (create-view-from-class 'foo)
 179         * (list-tables)
 180         ("FOO")
 181       </screen>
 182     </refsect1>
 183     <refsect1>
 184       <title>Side Effects</title>
 185       <para>
 186         Causes a table to be created in the SQL database.
 187       </para>
 188     </refsect1>
 189     <refsect1>
 190       <title>Affected by</title>
 191       <para>
 192         Most SQL database systems will signal an error if a table
 193         creation is attempted when a table with the same name already
 194         exists. The SQL user, as specified in the database connection,
 195         must have sufficient permission for table creation.
 196       </para>
 197     </refsect1>
 198     <refsect1>
 199       <title>Exceptional Situations</title>
 200       <para>
 201         A condition will be signaled if the table can not be created
 202         in the SQL database.
 203       </para>
 204     </refsect1>
 205     <refsect1>
 206       <title>See Also</title>
 207       <para>
 208         <simplelist>
 209           <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
 210           <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
 211         </simplelist>
 212       </para>
 213     </refsect1>
 214     <refsect1>
 215       <title>Notes</title>
 216       <para>
 217         Currently, only &mysql; supports transactionless
 218         tables. &clsql; provides the ability to create such tables for
 219         applications which would benefit from faster table access and
 220         do not require transaction support.
 221       </para>
 222       <para>
 223         The case of the table name is determined by the type of the
 224         database. &mysql;, for example, creates databases in upper-case
 225         while &postgresql; uses lowercase.
 226       </para>
 227     </refsect1>
 228   </refentry>
 229
 230   <refentry id="def-view-class">
 231     <refnamediv>
 232       <refname>DEF-VIEW-CLASS</refname>
 233       <refpurpose>Defines CLOS classes with mapping to SQL database.</refpurpose>
 234       <refclass>Macro</refclass>
 235     </refnamediv>
 236     <refsect1>
 237       <title>Syntax</title>
 238       <synopsis>
 239       <function>(def-view-class name superclasses slots &amp;rest class-options)</function> => <returnvalue>class</returnvalue></synopsis>
 240     </refsect1>
 241     <refsect1>
 242       <title>Arguments and Values</title>
 243       <variablelist>
 244         <varlistentry>
 245           <term><parameter>name</parameter></term>
 246           <listitem>
 247             <para>
 248               The class name.
 249             </para>
 250           </listitem>
 251         </varlistentry>
 252         <varlistentry>
 253           <term><parameter>name</parameter></term>
 254           <listitem>
 255             <para>
 256               The superclasses for the defined class.
 257             </para>
 258           </listitem>
 259         </varlistentry>
 260         <varlistentry>
 261           <term><parameter>slots</parameter></term>
 262           <listitem>
 263             <para>
 264               The class slot definitions.
 265             </para>
 266           </listitem>
 267         </varlistentry>
 268         <varlistentry>
 269           <term><parameter>class</parameter></term>
 270           <listitem>
 271             <para>
 272               The defined class.
 273             </para>
 274           </listitem>
 275         </varlistentry>
 276       </variablelist>
 277     </refsect1>
 278     <refsect1>
 279       <title>Slot Options</title>
 280       <itemizedlist>
 281         <listitem>
 282           <para>
 283             <parameter>:db-kind</parameter> - specifies the kind of
 284             database mapping which is performed for this slot and defaults
 285             to <parameter>:base</parameter> which indicates that the
 286             slot maps to an ordinary column of the database table. A
 287             <parameter>:db-kind</parameter> value of
 288             <parameter>:key</parameter> indicates that this slot is
 289             a special kind of <parameter>:base</parameter> slot
 290             which maps onto a column which is one of the unique keys
 291             for the database table, the value
 292             <parameter>:join</parameter> indicates this slot
 293             represents a join onto another View Class which contains
 294             View Class objects, and the value
 295             <parameter>:virtual</parameter> indicates a standard
 296             CLOS slot which does not map onto columns of the
 297             database table.
 298           </para>
 299         </listitem>
 300         <listitem>
 301           <para>
 302             <parameter>:db-info</parameter> - if a slot is specified with
 303             <parameter>:db-kind</parameter> <parameter>:join</parameter>, the
 304             slot option <parameter>:db-info</parameter> contains a property list
 305             which specifies the nature of the join. The valid members of the list
 306             are:
 307           </para>
 308           <itemizedlist>
 309             <listitem>
 310               <para>
 311                 <parameter>:join-class</parameter>
 312                 <emphasis>class-name</emphasis> - the name of the
 313                 class to join on.
 314               </para>
 315             </listitem>
 316             <listitem>
 317               <para>
 318                 <parameter>:home-key</parameter>
 319                 <emphasis>slot-name</emphasis> - the name of the slot
 320                 of this class for joining
 321               </para>
 322             </listitem>
 323             <listitem>
 324               <para>
 325                 <parameter>:foreign-key</parameter>
 326                 <emphasis>slot-name</emphasis> - the name of the slot
 327                 of the <parameter>:join-class</parameter> for joining
 328               </para>
 329             </listitem>
 330             <listitem>
 331               <para>
 332                 <parameter>:target-slot</parameter>
 333                 <emphasis>target-slot</emphasis> - this is an optional
 334                 parameter. If specified, then the join slot of the
 335                 defining class will contain instances of this target
 336                 slot rather than of the join class. This can be useful
 337                 when the <parameter>:join-class</parameter> is an
 338                 intermediate class in a
 339                 <emphasis>many-to-many</emphasis> relationship and the
 340                 application is actually interested in the
 341                 <parameter>:target-slot</parameter>.
 342               </para>
 343             </listitem>
 344             <listitem>
 345               <para>
 346                 <parameter>:retrieval</parameter>
 347                 <emphasis>time</emphasis> - The default value is
 348                 <parameter>:deferred</parameter>, which defers filling
 349                 this slot until the value is accessed. The other valid
 350                 value is <parameter>:immediate</parameter> which
 351                 performs the SQL query when the instance of the class
 352                 is created. In this case, the
 353                 <parameter>:set</parameter> is automatically set to
 354                 &nil;
 355               </para>
 356             </listitem>
 357             <listitem>
 358               <para>
 359                 <parameter>:set</parameter>
 360                 <emphasis>set</emphasis> - This controls what is stored in the join slot.
 361                 The default value is &t;. When <emphasis>set</emphasis> is &t; and
 362                 <emphasis>target-slot</emphasis> is undefined, the join slot will contain
 363                 a list of instances of the join class. Whereas, if <emphasis>target-slot</emphasis> is defined,
 364                 then the join slot will contain a list of pairs of <emphasis>(target-value join-instance)</emphasis>.
 365                 When <emphasis>set</emphasis> is &nil;, the join slot will contain a single instances.
 366               </para>
 367             </listitem>
 368           </itemizedlist>
 369         </listitem>
 370         <listitem>
 371           <para>
 372             <parameter>:type</parameter> - for slots of
 373             <parameter>:db-kind</parameter> <parameter>:base</parameter> or
 374             <parameter>:key</parameter>, the <parameter>:type</parameter> slot
 375             option has a special interpretation such that Lisp
 376             types, such as string, integer and float are
 377             automatically converted into appropriate SQL types for
 378             the column onto which the slot maps. This behaviour may
 379             be overridden using the <parameter>:db-type</parameter> slot
 380             option. The valid values are:
 381             <simplelist>
 382               <member>
 383                 <parameter>string</parameter> - a variable length character field up to
 384                 <link linkend="default-string-length">*default-string-length*</link> characters.
 385               </member>
 386               <member>
 387                 <parameter>(string n)</parameter> - a fixed length character field
 388                 <parameter>n</parameter> characters long.
 389               </member>
 390               <member>
 391                 <parameter>varchar</parameter> - a variable length character field up to
 392                 <link linkend="default-string-length">*default-string-length*</link> characters.
 393               </member>
 394               <member>
 395                 <parameter>(varchar n)</parameter> - a variable length character field up to
 396                 <parameter>n</parameter> characters in length.
 397               </member>
 398               <member>
 399                 <parameter>char</parameter> - a single character field
 400               </member>
 401               <member><parameter>integer</parameter> - signed integer at least 32-bits wide</member>
 402               <member><parameter>(integer n)</parameter></member>
 403               <member><parameter>float</parameter></member>
 404               <member><parameter>(float n)</parameter></member>
 405               <member><parameter>long-float</parameter></member>
 406               <member><parameter>number</parameter></member>
 407               <member><parameter>(number n)</parameter></member>
 408               <member><parameter>(number n p)</parameter></member>
 409               <member>
 410                 <parameter>smallint</parameter> - An integer column 16-bits
 411                 wide. [not supported by all database backends]
 412               </member>
 413               <member>
 414                 <parameter>bigint</parameter> - An integer column
 415                 64-bits wide. [not supported by all database backends]
 416               </member>
 417               <member>
 418                 <parameter>universal-time</parameter> - an integer
 419                 field sufficiently wide to store a
 420                 universal-time. On most databases, a slot of this
 421                 type assigned a SQL type of
 422                 <parameter>BIGINT</parameter>
 423               </member>
 424               <member>
 425                 <parameter>wall-time</parameter> - a slot which
 426                 stores a date and time in a SQL timestamp
 427                 column. &clsql; provides a number of time
 428                 manipulation functions to support objects of type
 429                 <type>wall-time</type>.
 430               </member>
 431               <member>
 432                 <parameter>duration</parameter> - stores a <type>duration</type> structure.
 433                 &clsql; provides routines for <type>wall-time</type> and <type>duration</type>
 434                 processing.
 435               </member>
 436               <member><parameter>boolean</parameter> - stores a &t; or &nil; value.</member>
 437               <member>
 438                 <parameter>generalized-boolean</parameter> - similar
 439                 to a <parameter>boolean</parameter> in that either a
 440                 &t; or &nil; value is stored in the SQL
 441                 database. However, any Lisp object can be stored in
 442                 the Lisp object. A Lisp value of &nil; is stored as
 443                 <constant>FALSE</constant> in the database, any
 444                 other Lisp value is stored as
 445                 <constant>TRUE</constant>.
 446               </member>
 447               <member>
 448                 <parameter>keyword</parameter> - stores a keyword
 449               </member>
 450               <member><parameter>symbol</parameter> - stores a symbol</member>
 451               <member>
 452                 <parameter>list</parameter> - stores a list by writing it to a string. The items
 453                 in the list must be able to be readable written.
 454               </member>
 455               <member><parameter>vector</parameter> - stores a vector similarly to <parameter>list</parameter></member>
 456               <member><parameter>array</parameter> - stores a array similarly to <parameter>list</parameter></member>
 457             </simplelist>
 458           </para>
 459
 460         </listitem>
 461         <listitem>
 462           <para>
 463             <parameter>:column</parameter> - specifies the name of
 464             the SQL column which the slot maps onto, if
 465             <parameter>:db-kind</parameter> is not
 466             <parameter>:virtual</parameter>, and defaults to the
 467             slot name. If the slot name is used for the SQL column
 468             name, any hypens in the slot name are converted
 469             to underscore characters.
 470           </para>
 471         </listitem>
 472         <listitem>
 473           <para>
 474             <parameter>:void-value</parameter> - specifies
 475             the value to store in the Lisp instance if the SQL value is NULL and defaults
 476             to NIL.
 477           </para>
 478         </listitem>
 479         <listitem>
 480           <para>
 481             <parameter>:db-constraints</parameter> - is a string
 482             representing an SQL table constraint expression or a
 483             list of such strings.
 484           </para>
 485         </listitem>
 486         <listitem>
 487           <para>
 488             <parameter>:db-type</parameter> - a string to specify the SQL
 489             column type. If specified, this string overrides the SQL
 490             column type as computed from the <parameter>:type</parameter>
 491             slot value.
 492           </para>
 493         </listitem>
 494       </itemizedlist>
 495     </refsect1>
 496     <refsect1>
 497       <title>Class Options</title>
 498       <para>
 499         <itemizedlist>
 500           <listitem>
 501             <para>
 502               <parameter>:base-table</parameter> - specifies the name of the
 503               SQL database table. The default value is the class name. Like slot names,
 504               hypens in the class name are converted to underscore characters.
 505             </para>
 506           </listitem>
 507         </itemizedlist>
 508       </para>
 509     </refsect1>
 510     <refsect1>
 511       <title>Description</title>
 512       <para>
 513         Creates a View Class called <parameter>name</parameter> whose
 514         slots <parameter>slots</parameter> can map onto the attributes
 515         of a table in a database. If
 516         <parameter>superclasses</parameter> is &nil; then the
 517         superclass of <parameter>class</parameter> will be
 518         <parameter>standard-db-object</parameter>, otherwise
 519         <parameter>superclasses</parameter> is a list of superclasses
 520         for <parameter>class</parameter> which must include
 521         <parameter>standard-db-object</parameter> or a descendent of this
 522         class.
 523       </para>
 524
 525     </refsect1>
 526     <refsect1>
 527       <title>Examples</title>
 528       <para>
 529         The following examples are from the &clsql; test suite.
 530       </para>
 531       <screen>
 532 (def-view-class person (thing)
 533   ((height :db-kind :base :accessor height :type float
 534            :initarg :height)
 535    (married :db-kind :base :accessor married :type boolean
 536             :initarg :married)
 537    (birthday :type clsql:wall-time :initarg :birthday)
 538    (bd-utime :type clsql:universal-time :initarg :bd-utime)
 539    (hobby :db-kind :virtual :initarg :hobby :initform nil)))
 540
 541 (def-view-class employee (person)
 542   ((emplid
 543     :db-kind :key
 544     :db-constraints :not-null
 545     :type integer
 546     :initarg :emplid)
 547    (groupid
 548     :db-kind :key
 549     :db-constraints :not-null
 550     :type integer
 551     :initarg :groupid)
 552    (first-name
 553     :accessor first-name
 554     :type (varchar 30)
 555     :initarg :first-name)
 556    (last-name
 557     :accessor last-name
 558     :type (varchar 30)
 559     :initarg :last-name)
 560    (email
 561     :accessor employee-email
 562     :type (varchar 100)
 563     :initarg :email)
 564    (ecompanyid
 565     :type integer
 566     :initarg :companyid)
 567    (company
 568     :accessor employee-company
 569     :db-kind :join
 570     :db-info (:join-class company
 571                           :home-key ecompanyid
 572                           :foreign-key companyid
 573                           :set nil))
 574    (managerid
 575     :type integer
 576     :initarg :managerid)
 577    (manager
 578     :accessor employee-manager
 579     :db-kind :join
 580     :db-info (:join-class employee
 581                           :home-key managerid
 582                           :foreign-key emplid
 583                           :set nil))
 584    (addresses
 585     :accessor employee-addresses
 586     :db-kind :join
 587     :db-info (:join-class employee-address
 588                           :home-key emplid
 589                           :foreign-key aemplid
 590                           :target-slot address
 591                           :set t)))
 592   (:base-table employee))
 593
 594 (def-view-class company ()
 595   ((companyid
 596     :db-kind :key
 597     :db-constraints :not-null
 598     :type integer
 599     :initarg :companyid)
 600    (groupid
 601     :db-kind :key
 602     :db-constraints :not-null
 603     :type integer
 604     :initarg :groupid)
 605    (name
 606     :type (varchar 100)
 607     :initarg :name)
 608    (presidentid
 609     :type integer
 610     :initarg :presidentid)
 611    (president
 612     :reader president
 613     :db-kind :join
 614     :db-info (:join-class employee
 615                           :home-key presidentid
 616                           :foreign-key emplid
 617                           :set nil))
 618    (employees
 619     :reader company-employees
 620     :db-kind :join
 621     :db-info (:join-class employee
 622                           :home-key (companyid groupid)
 623                           :foreign-key (ecompanyid groupid)
 624                           :set t))))
 625
 626 (def-view-class address ()
 627   ((addressid
 628     :db-kind :key
 629     :db-constraints :not-null
 630     :type integer
 631     :initarg :addressid)
 632    (street-number
 633     :type integer
 634     :initarg :street-number)
 635    (street-name
 636     :type (varchar 30)
 637     :void-value ""
 638     :initarg :street-name)
 639    (city
 640     :column "city_field"
 641     :void-value "no city"
 642     :type (varchar 30)
 643     :initarg :city)
 644    (postal-code
 645     :column zip
 646     :type integer
 647     :void-value 0
 648     :initarg :postal-code))
 649   (:base-table addr))
 650
 651 ;; many employees can reside at many addressess
 652 (def-view-class employee-address ()
 653   ((aemplid :type integer :initarg :emplid)
 654    (aaddressid :type integer :initarg :addressid)
 655    (verified :type boolean :initarg :verified)
 656    (address :db-kind :join
 657             :db-info (:join-class address
 658                                   :home-key aaddressid
 659                                   :foreign-key addressid
 660                                   :retrieval :immediate)))
 661   (:base-table "ea_join"))
 662
 663 (def-view-class deferred-employee-address ()
 664   ((aemplid :type integer :initarg :emplid)
 665    (aaddressid :type integer :initarg :addressid)
 666    (verified :type boolean :initarg :verified)
 667    (address :db-kind :join
 668             :db-info (:join-class address
 669                                   :home-key aaddressid
 670                                   :foreign-key addressid
 671                                   :retrieval :deferred
 672                                   :set nil)))
 673   (:base-table "ea_join"))
 674       </screen>
 675     </refsect1>
 676     <refsect1>
 677       <title>Side Effects</title>
 678       <para>Creates a new CLOS class.</para>
 679     </refsect1>
 680     <refsect1>
 681       <title>Affected by</title>
 682       <para>
 683         Nothing.
 684       </para>
 685     </refsect1>
 686     <refsect1>
 687       <title>Exceptional Situations</title>
 688       <para>
 689         None.
 690       </para>
 691     </refsect1>
 692     <refsect1>
 693       <title>See Also</title>
 694       <para>
 695         <simplelist>
 696           <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
 697           <member><link linkend="standard-db-object"><parameter>standard-db-object</parameter></link></member>
 698           <member><link linkend="drop-view-from-class"><function>drop-view-from-class</function></link></member>
 699         </simplelist>
 700       </para>
 701     </refsect1>
 702     <refsect1>
 703       <title>Notes</title>
 704       <para>
 705         The actual SQL type for a column depends up the database type
 706         in which the SQL table is stored. As an example, the view
 707         class type <parameter>(varchar 100)</parameter> specifies a
 708         SQL column type <parameter>VARCHAR(100)</parameter> in &mysql;
 709         and a column type <parameter>VARCHAR2(100)</parameter> in
 710         &oracle;
 711       </para>
 712       <para>
 713         The actual lisp type for a slot may be different than the
 714         value specified by the <parameter>:type</parameter> attribute.
 715         For example, a slot declared with "<parameter>:type (string
 716         30)</parameter>" actually sets the slots Lisp type as
 717         <parameter>(or null string)</parameter>. This is to allow a
 718         &nil; value or a string shorter than 30 characters to be
 719         stored in the slot.
 720       </para>
 721     </refsect1>
 722   </refentry>
 723
 724   <refentry id="drop-view-from-class">
 725     <refnamediv>
 726       <refname>DROP-VIEW-FROM-CLASS</refname>
 727       <refpurpose>Delete table from SQL database.</refpurpose>
 728       <refclass>Function</refclass>
 729     </refnamediv>
 730     <refsect1>
 731       <title>Syntax</title>
 732       <synopsis>
 733       <function>(drop-view-from-class view-class-name &amp;key (database *default-database*))</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 734     </refsect1>
 735     <refsect1>
 736       <title>Arguments and Values</title>
 737       <variablelist>
 738         <varlistentry>
 739           <term><parameter>view-class-name</parameter></term>
 740           <listitem>
 741             <para>
 742               The name of the view class.
 743             </para>
 744           </listitem>
 745         </varlistentry>
 746       </variablelist>
 747     </refsect1>
 748     <refsect1>
 749       <title>Description</title>
 750       <para>Removes a table defined by the View Class
 751       <parameter>VIEW-CLASS-NAME</parameter> from
 752       <parameter>DATABASE</parameter> which defaults to
 753       <parameter>*DEFAULT-DATABASE*</parameter>.
 754       </para>
 755     </refsect1>
 756     <refsect1>
 757       <title>Examples</title>
 758       <screen>
 759         * (list-tables)
 760         ("FOO" "BAR")
 761         * (drop-view-from-class 'foo)
 762         * (list-tables)
 763         ("BAR")
 764       </screen>
 765     </refsect1>
 766     <refsect1>
 767       <title>Side Effects</title>
 768       <para>
 769         Deletes a table from the SQL database.
 770       </para>
 771     </refsect1>
 772     <refsect1>
 773       <title>Affected by</title>
 774       <para>
 775         Whether the specified table exists in the SQL database.
 776       </para>
 777     </refsect1>
 778     <refsect1>
 779       <title>Exceptional Situations</title>
 780       <para>
 781         A condition may be signalled if the table does not exist in
 782         the SQL database or if the SQL connection does not have
 783         sufficient permissions to delete tables.
 784       </para>
 785     </refsect1>
 786     <refsect1>
 787       <title>See Also</title>
 788       <para>
 789         <simplelist>
 790           <member><link linkend="create-view-from-class"><function>create-view-from-class</function></link></member>
 791           <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
 792         </simplelist>
 793       </para>
 794     </refsect1>
 795     <refsect1>
 796       <title>Notes</title>
 797       <para>
 798         <!-- notes -->
 799       </para>
 800     </refsect1>
 801   </refentry>
 802
 803   <refentry id="list-classes">
 804     <refnamediv>
 805       <refname>LIST-CLASSES</refname>
 806       <refpurpose>List classes for tables in SQL database.</refpurpose>
 807       <refclass>Function</refclass>
 808     </refnamediv>
 809     <refsect1>
 810       <title>Syntax</title>
 811       <synopsis>
 812       <function>(list-classes &amp;key (test #'identity) (root-class (find-class 'standard-db-object)) (database *default-database*))</function> => <returnvalue>classes</returnvalue></synopsis>
 813     </refsect1>
 814     <refsect1>
 815       <title>Arguments and Values</title>
 816       <variablelist>
 817         <varlistentry>
 818           <term><parameter>test</parameter></term>
 819           <listitem>
 820             <para>
 821               a function used to filter the search. By default, <parameter>identity</parameter> is used which
 822               will return all classes.
 823             </para>
 824           </listitem>
 825         </varlistentry>
 826         <varlistentry>
 827           <term><parameter>root-class</parameter></term>
 828           <listitem>
 829             <para>
 830               specifies the root class to the search. By default, <parameter>standard-db-object</parameter> is used
 831               which is the root for all view classes.
 832             </para>
 833           </listitem>
 834         </varlistentry>
 835         <varlistentry>
 836           <term><parameter>database</parameter></term>
 837           <listitem>
 838             <para>
 839               The database to search for view classes.
 840             </para>
 841           </listitem>
 842         </varlistentry>
 843         <varlistentry>
 844           <term><parameter>classes</parameter></term>
 845           <listitem>
 846             <para>
 847               List of view classes.
 848             </para>
 849           </listitem>
 850         </varlistentry>
 851       </variablelist>
 852     </refsect1>
 853     <refsect1>
 854       <title>Description</title>
 855       <para>Returns a list of all the View Classes which have been
 856       defined in the Lisp session and are connected to
 857       <parameter>database</parameter> and which descended from the
 858       class <parameter>root-class</parameter> and which satisfy the
 859       function <parameter>test</parameter>.
 860       </para>
 861     </refsect1>
 862     <refsect1>
 863       <title>Examples</title>
 864       <screen>
 865         * (list-classes)
 866         (#&lt;clsql-sys::standard-db-class big> #&lt;clsql-sys::standard-db-class employee-address>
 867         #&lt;clsql-sys::standard-db-class address> #&lt;clsql-sys::standard-db-class company>
 868         #&lt;clsql-sys::standard-db-class employee>)
 869
 870         * (list-classes :test #'(lambda (c) (> (length (symbol-name (class-name c))) 3)))
 871         (#&lt;clsql-sys::standard-db-class employee-address> #&lt;clsql-sys::standard-db-class address>
 872         #&lt;clsql-sys::standard-db-class company> #&lt;clsql-sys::standard-db-class employee>)
 873       </screen>
 874     </refsect1>
 875     <refsect1>
 876       <title>Side Effects</title>
 877       <para>
 878         None.
 879       </para>
 880     </refsect1>
 881     <refsect1>
 882       <title>Affected by</title>
 883       <para>
 884         <simplelist>
 885           <member>Which view classes have been defined in the Lisp session.</member>
 886         </simplelist>
 887       </para>
 888     </refsect1>
 889     <refsect1>
 890       <title>Exceptional Situations</title>
 891       <para>
 892         None.
 893       </para>
 894     </refsect1>
 895     <refsect1>
 896       <title>See Also</title>
 897       <para>
 898         <simplelist>
 899           <member><link linkend="def-view-class"><function>def-view-class</function></link></member>
 900         </simplelist>
 901       </para>
 902     </refsect1>
 903   </refentry>
 904
 905
 906 </reference>