doc/ref-fddl.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 <!-- Functional Data Definition Language -->
   9 <reference id="ref-fddl">
  10   <title>Functional Data Definition Language (FDDL)</title>
  11   <partintro>
  12     <para>
  13       &clsql; provides a functional DDL which supports the creation
  14       and destruction of a variety of database objects including
  15       tables, views, indexes and sequences. Functions which return
  16       information about currently defined database objects are also
  17       provided. In addition, the FDDL includes functionality for
  18       examining table attributes and attribute types.
  19     </para>
  20   </partintro>
  21
  22   <refentry id="create-table">
  23     <refmeta>
  24       <refentrytitle>CREATE-TABLE</refentrytitle>
  25     </refmeta>
  26     <refnamediv>
  27       <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-TABLE</emphasis></refname>
  28       <refpurpose>Create a database table.</refpurpose>
  29       <refclass>Function</refclass>
  30     </refnamediv>
  31     <refsect1>
  32       <title>Syntax</title>
  33       <synopsis>
  34       <function>create-table</function> <replaceable>name</replaceable> <replaceable>description</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>constraints</replaceable> <replaceable>transactions</replaceable> => <returnvalue></returnvalue></synopsis>
  35     </refsect1>
  36     <refsect1>
  37       <title>Arguments and Values</title>
  38       <variablelist>
  39         <varlistentry>
  40           <term><parameter>name</parameter></term>
  41           <listitem>
  42             <para>
  43               The name of the table as a string, symbol or SQL expression.
  44             </para>
  45           </listitem>
  46         </varlistentry>
  47         <varlistentry>
  48           <term><parameter>database</parameter></term>
  49           <listitem>
  50             <para>
  51               A database object which defaults to
  52               <symbol>*default-database*</symbol>.
  53             </para>
  54           </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57           <term><parameter>description</parameter></term>
  58           <listitem>
  59             <para>
  60               A list.
  61             </para>
  62           </listitem>
  63         </varlistentry>
  64         <varlistentry>
  65           <term><parameter>constraints</parameter></term>
  66           <listitem>
  67             <para>
  68               A string, a list of strings or &nil;.
  69             </para>
  70           </listitem>
  71         </varlistentry>
  72         <varlistentry>
  73           <term><parameter>transactions</parameter></term>
  74           <listitem>
  75             <para>
  76               A Boolean. The default value is &t;.
  77             </para>
  78           </listitem>
  79         </varlistentry>
  80       </variablelist>
  81     </refsect1>
  82     <refsect1>
  83       <title>Description</title>
  84       <para>Creates a table called <parameter>name</parameter>, which
  85       may be a string, symbol or SQL table identifier, in
  86       <parameter>database</parameter> which defaults to
  87       <symbol>*default-database*</symbol>. <parameter>description</parameter>
  88       is a list whose elements are lists containing the attribute
  89       names, types, and other constraints such as not-null or
  90       primary-key for each column in the table.
  91       </para>
  92       <para>
  93         <parameter>constraints</parameter> is a string representing an
  94         SQL table constraint expression or a list of such strings.
  95       </para>
  96       <para>
  97         With MySQL databases, if <parameter>transactions</parameter>
  98         is &t; an InnoDB table is created which supports transactions.
  99       </para>
 100     </refsect1>
 101     <refsect1>
 102       <title>Examples</title>
 103       <screen>
 104 (create-table [foo]
 105               '(([id] integer)
 106                 ([height] float)
 107                 ([name] (string 24))
 108                 ([comments] longchar)))
 109 =>
 110 (table-exists-p [foo])
 111 => T
 112       </screen>
 113     </refsect1>
 114     <refsect1>
 115       <title>Side Effects</title>
 116       <para>
 117         A table is created in <parameter>database</parameter>.
 118       </para>
 119     </refsect1>
 120     <refsect1>
 121       <title>Affected by</title>
 122       <para>
 123         <symbol>*default-database*</symbol>
 124       </para>
 125     </refsect1>
 126     <refsect1>
 127       <title>Exceptional Situations</title>
 128       <para>
 129         An error is signalled if <parameter>name</parameter> is not a
 130         string, symbol or SQL expression. An error of type
 131         <symbol>sql-database-data-error</symbol> is signalled if a
 132         relation called <parameter>name</parameter> already exists.
 133       </para>
 134     </refsect1>
 135     <refsect1>
 136       <title>See Also</title>
 137       <simplelist>
 138         <member><link linkend="drop-table"><function>drop-table</function></link></member>
 139         <member><link linkend="list-tables"><function>list-tables</function></link></member>
 140         <member><link linkend="table-exists-p"><function>table-exists-p</function></link></member>
 141       </simplelist>
 142     </refsect1>
 143     <refsect1>
 144       <title>Notes</title>
 145       <para>
 146         The <parameter>constraints</parameter> and
 147         <parameter>transactions</parameter> keyword arguments to
 148         <function>create-table</function> are &clsql; extensions. The
 149         <parameter>transactions</parameter> keyword argument is for
 150         compatibility with MySQL databases.
 151       </para>
 152     </refsect1>
 153   </refentry>
 154
 155   <refentry id="drop-table">
 156     <refmeta>
 157       <refentrytitle>DROP-TABLE</refentrytitle>
 158     </refmeta>
 159     <refnamediv>
 160       <refname><emphasis>Function</emphasis> <emphasis role="bold">DROP-TABLE</emphasis></refname>
 161       <refpurpose>Drop a database table.</refpurpose>
 162       <refclass>Function</refclass>
 163     </refnamediv>
 164     <refsect1>
 165       <title>Syntax</title>
 166       <synopsis>
 167       <function>drop-table</function> <replaceable>name</replaceable> &amp;key <replaceable>if-does-not-exist</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 168     </refsect1>
 169     <refsect1>
 170       <title>Arguments and Values</title>
 171       <variablelist>
 172         <varlistentry>
 173           <term><parameter>name</parameter></term>
 174           <listitem>
 175             <para>
 176               The name of the table as a string, symbol or SQL expression.
 177             </para>
 178           </listitem>
 179         </varlistentry>
 180         <varlistentry>
 181           <term><parameter>database</parameter></term>
 182           <listitem>
 183             <para>
 184               A database object which defaults to
 185               <symbol>*default-database*</symbol>.
 186             </para>
 187           </listitem>
 188         </varlistentry>
 189         <varlistentry>
 190           <term><parameter>if-does-not-exist</parameter></term>
 191           <listitem>
 192             <para>
 193               A symbol. Meaningful values are <symbol>:ignore</symbol>
 194               or <symbol>:error</symbol> (the default).
 195             </para>
 196           </listitem>
 197         </varlistentry>
 198       </variablelist>
 199     </refsect1>
 200     <refsect1>
 201       <title>Description</title>
 202       <para>Drops the table called <parameter>name</parameter> from
 203       <parameter>database</parameter> which defaults to
 204       <symbol>*default-database*</symbol>. If the table does not exist
 205       and <parameter>if-does-not-exist</parameter> is
 206       <symbol>:ignore</symbol> then <function>drop-table</function>
 207       returns &nil; whereas an error is signalled if
 208       <parameter>if-does-not-exist</parameter> is
 209       <symbol>:error</symbol>.
 210       </para>
 211     </refsect1>
 212     <refsect1>
 213       <title>Examples</title>
 214       <screen>
 215 (table-exists-p [foo])
 216 => T
 217 (drop-table [foo] :if-does-not-exist :ignore)
 218 =>
 219 (table-exists-p [foo])
 220 => NIL
 221       </screen>
 222     </refsect1>
 223     <refsect1>
 224       <title>Side Effects</title>
 225       <para>
 226         A table is dropped <parameter>database</parameter>.
 227       </para>
 228     </refsect1>
 229     <refsect1>
 230       <title>Affected by</title>
 231       <para>
 232         <symbol>*default-database*</symbol>
 233       </para>
 234     </refsect1>
 235     <refsect1>
 236       <title>Exceptional Situations</title>
 237       <para>
 238         An error is signalled if <parameter>name</parameter> is not a
 239         string, symbol or SQL expression. An error of type
 240         <symbol>sql-database-data-error</symbol> is signalled if
 241         <parameter>name</parameter> doesn't exist and
 242         <parameter>if-does-not-exist</parameter> has a value of
 243         <symbol>:error</symbol>.
 244       </para>
 245     </refsect1>
 246     <refsect1>
 247       <title>See Also</title>
 248       <simplelist>
 249         <member><link linkend="create-table"><function>create-table</function></link></member>
 250         <member><link linkend="list-tables"><function>list-tables</function></link></member>
 251         <member><link linkend="table-exists-p"><function>table-exists-p</function></link></member>
 252       </simplelist>
 253     </refsect1>
 254     <refsect1>
 255       <title>Notes</title>
 256       <para>
 257         The <parameter>if-does-not-exist</parameter> keyword argument
 258         to <function>drop-table</function> is a &clsql; extension.
 259       </para>
 260     </refsect1>
 261   </refentry>
 262
 263   <refentry id="list-tables">
 264     <refmeta>
 265       <refentrytitle>LIST-TABLES</refentrytitle>
 266     </refmeta>
 267     <refnamediv>
 268       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-TABLES</emphasis></refname>
 269       <refpurpose>Returns a list of database tables.</refpurpose>
 270       <refclass>Function</refclass>
 271     </refnamediv>
 272     <refsect1>
 273       <title>Syntax</title>
 274       <synopsis>
 275       <function>list-tables</function> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 276     </refsect1>
 277     <refsect1>
 278       <title>Arguments and Values</title>
 279       <variablelist>
 280         <varlistentry>
 281           <term><parameter>owner</parameter></term>
 282           <listitem>
 283             <para>
 284               A string, &nil; or <symbol>:all</symbol>.
 285             </para>
 286           </listitem>
 287         </varlistentry>
 288         <varlistentry>
 289           <term><parameter>database</parameter></term>
 290           <listitem>
 291             <para>
 292               A database object which defaults to
 293               <symbol>*default-database*</symbol>.
 294             </para>
 295           </listitem>
 296         </varlistentry>
 297         <varlistentry>
 298           <term><parameter>result</parameter></term>
 299           <listitem>
 300             <para>
 301               A list of strings.
 302             </para>
 303           </listitem>
 304         </varlistentry>
 305       </variablelist>
 306     </refsect1>
 307     <refsect1>
 308       <title>Description</title>
 309       <para>Returns a list of strings representing table names in
 310       <parameter>database</parameter> which defaults to
 311       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
 312       is &nil; by default which means that only tables owned by users
 313       are listed. If <parameter>owner</parameter> is a string denoting
 314       a user name, only tables owned by <parameter>owner</parameter>
 315       are listed. If <parameter>owner</parameter> is
 316       <symbol>:all</symbol> then all tables are listed.
 317       </para>
 318     </refsect1>
 319     <refsect1>
 320       <title>Examples</title>
 321       <screen>
 322 (list-tables :owner "fred")
 323 => ("type_table" "type_bigint" "employee" "company" "addr" "ea_join" "big")
 324
 325 (list-tables :owner :all)
 326 => ("pg_description" "pg_group" "pg_proc" "pg_rewrite" "pg_type" "pg_attribute"
 327     "pg_class" "pg_inherits" "pg_index" "pg_operator" "pg_opclass" "pg_am"
 328     "pg_amop" "pg_amproc" "pg_language" "pg_largeobject" "pg_aggregate"
 329     "pg_trigger" "pg_listener" "pg_cast" "pg_namespace" "pg_shadow"
 330     "pg_conversion" "pg_depend" "pg_attrdef" "pg_constraint" "pg_database"
 331     "type_table" "type_bigint" "employee" "company" "pg_statistic" "addr"
 332     "ea_join" "big")
 333       </screen>
 334     </refsect1>
 335     <refsect1>
 336       <title>Side Effects</title>
 337       <para>
 338         None.
 339       </para>
 340     </refsect1>
 341     <refsect1>
 342       <title>Affected by</title>
 343       <para>
 344         <symbol>*default-database*</symbol>
 345       </para>
 346     </refsect1>
 347     <refsect1>
 348       <title>Exceptional Situations</title>
 349       <para>
 350         None.
 351       </para>
 352     </refsect1>
 353     <refsect1>
 354       <title>See Also</title>
 355       <simplelist>
 356         <member><link linkend="create-table"><function>create-table</function></link></member>
 357         <member><link linkend="drop-table"><function>drop-table</function></link></member>
 358         <member><link linkend="table-exists-p"><function>table-exists-p</function></link></member>
 359       </simplelist>
 360     </refsect1>
 361     <refsect1>
 362       <title>Notes</title>
 363       <para>
 364         None.
 365       </para>
 366     </refsect1>
 367   </refentry>
 368
 369   <refentry id="table-exists-p">
 370     <refmeta>
 371       <refentrytitle>TABLE-EXISTS-P</refentrytitle>
 372     </refmeta>
 373     <refnamediv>
 374       <refname><emphasis>Function</emphasis> <emphasis role="bold">TABLE-EXISTS-P</emphasis></refname>
 375       <refpurpose>Tests for the existence of a database table.</refpurpose>
 376       <refclass>Function</refclass>
 377     </refnamediv>
 378     <refsect1>
 379       <title>Syntax</title>
 380       <synopsis>
 381       <function>table-exists-p</function> <replaceable>name</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 382     </refsect1>
 383     <refsect1>
 384       <title>Arguments and Values</title>
 385       <variablelist>
 386         <varlistentry>
 387           <term><parameter>name</parameter></term>
 388           <listitem>
 389             <para>
 390               The name of the table as a string, symbol or SQL expression.
 391             </para>
 392           </listitem>
 393         </varlistentry>
 394         <varlistentry>
 395           <term><parameter>owner</parameter></term>
 396           <listitem>
 397             <para>
 398               A string, &nil; or <symbol>:all</symbol>.
 399             </para>
 400           </listitem>
 401         </varlistentry>
 402         <varlistentry>
 403           <term><parameter>database</parameter></term>
 404           <listitem>
 405             <para>
 406               A database object which defaults to
 407               <symbol>*default-database*</symbol>.
 408             </para>
 409           </listitem>
 410         </varlistentry>
 411         <varlistentry>
 412           <term><parameter>result</parameter></term>
 413           <listitem>
 414             <para>
 415               A Boolean.
 416             </para>
 417           </listitem>
 418         </varlistentry>
 419       </variablelist>
 420     </refsect1>
 421     <refsect1>
 422       <title>Description</title>
 423       <para>Tests for the existence of an SQL table called
 424       <parameter>name</parameter> in <parameter>database</parameter>
 425       which defaults to <symbol>*default-database*</symbol>.
 426       <parameter>owner</parameter> is &nil; by default which means
 427       that only tables owned by users are examined. If
 428       <parameter>owner</parameter> is a string denoting a user name,
 429       only tables owned by <parameter>owner</parameter> are
 430       examined. If <parameter>owner</parameter> is
 431       <symbol>:all</symbol> then all tables are examined.
 432       </para>
 433     </refsect1>
 434     <refsect1>
 435       <title>Examples</title>
 436       <screen>
 437 (table-exists-p [foo])
 438 => T
 439       </screen>
 440     </refsect1>
 441     <refsect1>
 442       <title>Side Effects</title>
 443       <para>
 444         None.
 445       </para>
 446     </refsect1>
 447     <refsect1>
 448       <title>Affected by</title>
 449       <para>
 450         <symbol>*default-database*</symbol>
 451       </para>
 452     </refsect1>
 453     <refsect1>
 454       <title>Exceptional Situations</title>
 455       <para>
 456         None.
 457       </para>
 458     </refsect1>
 459     <refsect1>
 460       <title>See Also</title>
 461       <simplelist>
 462         <member><link linkend="create-table"><function>create-table</function></link></member>
 463         <member><link linkend="drop-table"><function>drop-table</function></link></member>
 464         <member><link linkend="list-tables"><function>list-tables</function></link></member>
 465       </simplelist>
 466     </refsect1>
 467     <refsect1>
 468       <title>Notes</title>
 469       <para>
 470         None.
 471       </para>
 472     </refsect1>
 473   </refentry>
 474
 475   <refentry id="create-view">
 476     <refmeta>
 477       <refentrytitle>CREATE-VIEW</refentrytitle>
 478     </refmeta>
 479     <refnamediv>
 480       <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-VIEW</emphasis></refname>
 481       <refpurpose>Create a database view.</refpurpose>
 482       <refclass>Function</refclass>
 483     </refnamediv>
 484     <refsect1>
 485       <title>Syntax</title>
 486       <synopsis>
 487       <function>create-view</function> <replaceable>name</replaceable> &amp;key <replaceable>as</replaceable> <replaceable>column-list</replaceable> <replaceable>with-check-option</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 488     </refsect1>
 489     <refsect1>
 490       <title>Arguments and Values</title>
 491       <variablelist>
 492         <varlistentry>
 493           <term><parameter>name</parameter></term>
 494           <listitem>
 495             <para>
 496               The name of the view as a string, symbol or SQL expression.
 497             </para>
 498           </listitem>
 499         </varlistentry>
 500         <varlistentry>
 501           <term><parameter>database</parameter></term>
 502           <listitem>
 503             <para>
 504               A database object which defaults to
 505               <symbol>*default-database*</symbol>.
 506             </para>
 507           </listitem>
 508         </varlistentry>
 509         <varlistentry>
 510           <term><parameter>as</parameter></term>
 511           <listitem>
 512             <para>
 513               A symbolic SQL query expression.
 514             </para>
 515           </listitem>
 516         </varlistentry>
 517         <varlistentry>
 518           <term><parameter>column-list</parameter></term>
 519           <listitem>
 520             <para>
 521               A list.
 522             </para>
 523           </listitem>
 524         </varlistentry>
 525         <varlistentry>
 526           <term><parameter>with-check-option</parameter></term>
 527           <listitem>
 528             <para>
 529               A Boolean.
 530             </para>
 531           </listitem>
 532         </varlistentry>
 533       </variablelist>
 534     </refsect1>
 535     <refsect1>
 536       <title>Description</title>
 537       <para>Creates a view called <parameter>name</parameter> in
 538       <parameter>database</parameter> which defaults to
 539       <symbol>*default-database*</symbol>. The view is created using
 540       the query <parameter>as</parameter> and the columns of the view
 541       may be specified using the <parameter>column-list</parameter>
 542       parameter. The <parameter>with-check-option</parameter> is &nil;
 543       by default but if it has a non-&nil; value, then all
 544       insert/update commands on the view are checked to ensure that
 545       the new data satisfy the query <parameter>as</parameter>.
 546       </para>
 547     </refsect1>
 548     <refsect1>
 549       <title>Examples</title>
 550       <screen>
 551 (create-view [lenins-group]
 552              :as [select [first-name] [last-name] [email]
 553                          :from [employee]
 554                          :where [= [managerid] 1]])
 555 =>
 556
 557 (select [*] :from [lenins-group])
 558 => (("Josef" "Stalin" "stalin@soviet.org")
 559     ("Leon" "Trotsky" "trotsky@soviet.org")
 560     ("Nikita" "Kruschev" "kruschev@soviet.org")
 561     ("Leonid" "Brezhnev" "brezhnev@soviet.org")
 562     ("Yuri" "Andropov" "andropov@soviet.org")
 563     ("Konstantin" "Chernenko" "chernenko@soviet.org")
 564     ("Mikhail" "Gorbachev" "gorbachev@soviet.org")
 565     ("Boris" "Yeltsin" "yeltsin@soviet.org")
 566     ("Vladamir" "Putin" "putin@soviet.org")),
 567    ("first_name" "last_name" "email")
 568       </screen>
 569     </refsect1>
 570     <refsect1>
 571       <title>Side Effects</title>
 572       <para>
 573         A view is created in <parameter>database</parameter>.
 574       </para>
 575     </refsect1>
 576     <refsect1>
 577       <title>Affected by</title>
 578       <para>
 579         <symbol>*default-database*</symbol>
 580       </para>
 581     </refsect1>
 582     <refsect1>
 583       <title>Exceptional Situations</title>
 584       <para>
 585         An error is signalled if <parameter>name</parameter> is not a
 586         string, symbol or SQL expression. An error of type
 587         <symbol>sql-database-data-error</symbol> is signalled if a
 588         relation called <parameter>name</parameter> already exists.
 589       </para>
 590     </refsect1>
 591     <refsect1>
 592       <title>See Also</title>
 593       <simplelist>
 594         <member><link linkend="drop-view"><function>drop-view</function></link></member>
 595         <member><link linkend="list-views"><function>list-views</function></link></member>
 596         <member><link linkend="view-exists-p"><function>view-exists-p</function></link></member>
 597       </simplelist>
 598     </refsect1>
 599     <refsect1>
 600       <title>Notes</title>
 601       <para>
 602         None.
 603       </para>
 604     </refsect1>
 605   </refentry>
 606
 607   <refentry id="drop-view">
 608     <refmeta>
 609       <refentrytitle>DROP-VIEW</refentrytitle>
 610     </refmeta>
 611     <refnamediv>
 612       <refname><emphasis>Function</emphasis> <emphasis role="bold">DROP-VIEW</emphasis></refname>
 613       <refpurpose>Drops a database view.</refpurpose>
 614       <refclass>Function</refclass>
 615     </refnamediv>
 616     <refsect1>
 617       <title>Syntax</title>
 618       <synopsis>
 619       <function>drop-view</function> <replaceable>name</replaceable> &amp;key <replaceable>if-does-not-exist</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 620     </refsect1>
 621     <refsect1>
 622       <title>Arguments and Values</title>
 623       <variablelist>
 624         <varlistentry>
 625           <term><parameter>name</parameter></term>
 626           <listitem>
 627             <para>
 628               The name of the view as a string, symbol or SQL expression.
 629             </para>
 630           </listitem>
 631         </varlistentry>
 632         <varlistentry>
 633           <term><parameter>database</parameter></term>
 634           <listitem>
 635             <para>
 636               A database object which defaults to
 637               <symbol>*default-database*</symbol>.
 638             </para>
 639           </listitem>
 640         </varlistentry>
 641         <varlistentry>
 642           <term><parameter>if-does-not-exist</parameter></term>
 643           <listitem>
 644             <para>
 645               A symbol. Meaningful values are <symbol>:ignore</symbol>
 646               or <symbol>:error</symbol> (the default).
 647             </para>
 648           </listitem>
 649         </varlistentry>
 650       </variablelist>
 651     </refsect1>
 652     <refsect1>
 653       <title>Description</title>
 654       <para>Drops the view called <parameter>name</parameter> from
 655       <parameter>database</parameter> which defaults to
 656       <symbol>*default-database*</symbol>. If the view does not exist
 657       and <parameter>if-does-not-exist</parameter> is
 658       <symbol>:ignore</symbol> then <function>drop-view</function>
 659       returns &nil; whereas an error is signalled if
 660       <parameter>if-does-not-exist</parameter> is
 661       <symbol>:error</symbol>.
 662       </para>
 663     </refsect1>
 664     <refsect1>
 665       <title>Examples</title>
 666       <screen>
 667 (view-exists-p [foo])
 668 => T
 669 (drop-view [foo] :if-does-not-exist :ignore)
 670 =>
 671 (view-exists-p [foo])
 672 => NIL
 673       </screen>
 674     </refsect1>
 675     <refsect1>
 676       <title>Side Effects</title>
 677       <para>
 678         A view is dropped <parameter>database</parameter>.
 679       </para>
 680     </refsect1>
 681     <refsect1>
 682       <title>Affected by</title>
 683       <para>
 684         <symbol>*default-database*</symbol>
 685       </para>
 686     </refsect1>
 687     <refsect1>
 688       <title>Exceptional Situations</title>
 689       <para>
 690         An error is signalled if <parameter>name</parameter> is not a
 691         string, symbol or SQL expression. An error of type
 692         <symbol>sql-database-data-error</symbol> is signalled if
 693         <parameter>name</parameter> doesn't exist and
 694         <parameter>if-does-not-exist</parameter> has a value of
 695         <symbol>:error</symbol>.
 696       </para>
 697     </refsect1>
 698     <refsect1>
 699       <title>See Also</title>
 700       <simplelist>
 701         <member><link linkend="create-view"><function>create-view</function></link></member>
 702         <member><link linkend="list-views"><function>list-views</function></link></member>
 703         <member><link linkend="view-exists-p"><function>view-exists-p</function></link></member>
 704       </simplelist>
 705     </refsect1>
 706     <refsect1>
 707       <title>Notes</title>
 708       <para>
 709         The <parameter>if-does-not-exist</parameter> keyword argument
 710         to <function>drop-view</function> is a &clsql; extension.
 711       </para>
 712     </refsect1>
 713   </refentry>
 714
 715   <refentry id="list-views">
 716     <refmeta>
 717       <refentrytitle>LIST-VIEWS</refentrytitle>
 718     </refmeta>
 719     <refnamediv>
 720       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-VIEWS</emphasis></refname>
 721       <refpurpose>Returns a list of database views.</refpurpose>
 722       <refclass>Function</refclass>
 723     </refnamediv>
 724     <refsect1>
 725       <title>Syntax</title>
 726       <synopsis>
 727       <function>list-views</function> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 728     </refsect1>
 729     <refsect1>
 730       <title>Arguments and Values</title>
 731       <variablelist>
 732         <varlistentry>
 733           <term><parameter>owner</parameter></term>
 734           <listitem>
 735             <para>
 736               A string, &nil; or <symbol>:all</symbol>.
 737             </para>
 738           </listitem>
 739         </varlistentry>
 740         <varlistentry>
 741           <term><parameter>database</parameter></term>
 742           <listitem>
 743             <para>
 744               A database object which defaults to
 745               <symbol>*default-database*</symbol>.
 746             </para>
 747           </listitem>
 748         </varlistentry>
 749         <varlistentry>
 750           <term><parameter>result</parameter></term>
 751           <listitem>
 752             <para>
 753               A list of strings.
 754             </para>
 755           </listitem>
 756         </varlistentry>
 757       </variablelist>
 758     </refsect1>
 759     <refsect1>
 760       <title>Description</title>
 761       <para>Returns a list of strings representing view names in
 762       <parameter>database</parameter> which defaults to
 763       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
 764       is &nil; by default which means that only views owned by users
 765       are listed. If <parameter>owner</parameter> is a string denoting
 766       a user name, only views owned by <parameter>owner</parameter>
 767       are listed. If <parameter>owner</parameter> is
 768       <symbol>:all</symbol> then all views are listed.
 769       </para>
 770     </refsect1>
 771     <refsect1>
 772       <title>Examples</title>
 773       <screen>
 774 (list-views :owner "fred")
 775 => ("lenins_group")
 776
 777 (list-views :owner :all)
 778 => ("pg_user" "pg_rules" "pg_views" "pg_tables" "pg_indexes" "pg_stats"
 779     "pg_stat_all_tables" "pg_stat_sys_tables" "pg_stat_user_tables"
 780     "pg_statio_all_tables" "pg_statio_sys_tables" "pg_statio_user_tables"
 781     "pg_stat_all_indexes" "pg_stat_sys_indexes" "pg_stat_user_indexes"
 782     "pg_statio_all_indexes" "pg_statio_sys_indexes" "pg_statio_user_indexes"
 783     "pg_statio_all_sequences" "pg_statio_sys_sequences"
 784     "pg_statio_user_sequences" "pg_stat_activity" "pg_stat_database"
 785     "pg_locks" "pg_settings" "lenins_group")
 786       </screen>
 787     </refsect1>
 788     <refsect1>
 789       <title>Side Effects</title>
 790       <para>
 791         None.
 792       </para>
 793     </refsect1>
 794     <refsect1>
 795       <title>Affected by</title>
 796       <para>
 797         <symbol>*default-database*</symbol>
 798       </para>
 799     </refsect1>
 800     <refsect1>
 801       <title>Exceptional Situations</title>
 802       <para>
 803         None.
 804       </para>
 805     </refsect1>
 806     <refsect1>
 807       <title>See Also</title>
 808       <simplelist>
 809         <member><link linkend="create-view"><function>create-view</function></link></member>
 810         <member><link linkend="drop-view"><function>drop-view</function></link></member>
 811         <member><link linkend="view-exists-p"><function>view-exists-p</function></link></member>
 812       </simplelist>
 813     </refsect1>
 814     <refsect1>
 815       <title>Notes</title>
 816       <para>
 817         <function>list-views</function> is a &clsql; extension.
 818       </para>
 819     </refsect1>
 820   </refentry>
 821
 822   <refentry id="view-exists-p">
 823     <refmeta>
 824       <refentrytitle>VIEW-EXISTS-P</refentrytitle>
 825     </refmeta>
 826     <refnamediv>
 827       <refname><emphasis>Function</emphasis> <emphasis role="bold">VIEW-EXISTS-P</emphasis></refname>
 828       <refpurpose>Tests for the existence of a database view.</refpurpose>
 829       <refclass>Function</refclass>
 830     </refnamediv>
 831     <refsect1>
 832       <title>Syntax</title>
 833       <synopsis>
 834       <function>view-exists-p</function> <replaceable>name</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
 835     </refsect1>
 836     <refsect1>
 837       <title>Arguments and Values</title>
 838       <variablelist>
 839         <varlistentry>
 840           <term><parameter>name</parameter></term>
 841           <listitem>
 842             <para>
 843               The name of the view as a string, symbol or SQL expression.
 844             </para>
 845           </listitem>
 846         </varlistentry>
 847         <varlistentry>
 848           <term><parameter>owner</parameter></term>
 849           <listitem>
 850             <para>
 851               A string, &nil; or <symbol>:all</symbol>.
 852             </para>
 853           </listitem>
 854         </varlistentry>
 855         <varlistentry>
 856           <term><parameter>database</parameter></term>
 857           <listitem>
 858             <para>
 859               A database object which defaults to
 860               <symbol>*default-database*</symbol>.
 861             </para>
 862           </listitem>
 863         </varlistentry>
 864         <varlistentry>
 865           <term><parameter>result</parameter></term>
 866           <listitem>
 867             <para>
 868               A Boolean.
 869             </para>
 870           </listitem>
 871         </varlistentry>
 872       </variablelist>
 873     </refsect1>
 874     <refsect1>
 875       <title>Description</title>
 876       <para>Tests for the existence of an SQL view called
 877       <parameter>name</parameter> in <parameter>database</parameter>
 878       which defaults to <symbol>*default-database*</symbol>.
 879       <parameter>owner</parameter> is &nil; by default which means
 880       that only views owned by users are examined. If
 881       <parameter>owner</parameter> is a string denoting a user name,
 882       only views owned by <parameter>owner</parameter> are
 883       examined. If <parameter>owner</parameter> is
 884       <symbol>:all</symbol> then all views are examined.
 885       </para>
 886     </refsect1>
 887     <refsect1>
 888       <title>Examples</title>
 889       <screen>
 890 (view-exists-p [lenins-group])
 891 => T
 892       </screen>
 893     </refsect1>
 894     <refsect1>
 895       <title>Side Effects</title>
 896       <para>
 897         None.
 898       </para>
 899     </refsect1>
 900     <refsect1>
 901       <title>Affected by</title>
 902       <para>
 903         <symbol>*default-database*</symbol>
 904       </para>
 905     </refsect1>
 906     <refsect1>
 907       <title>Exceptional Situations</title>
 908       <para>
 909         None.
 910       </para>
 911     </refsect1>
 912     <refsect1>
 913       <title>See Also</title>
 914       <simplelist>
 915         <member><link linkend="create-view"><function>create-view</function></link></member>
 916         <member><link linkend="drop-view"><function>drop-view</function></link></member>
 917         <member><link linkend="list-views"><function>list-views</function></link></member>
 918       </simplelist>
 919     </refsect1>
 920     <refsect1>
 921       <title>Notes</title>
 922       <para>
 923         <function>view-exists-p</function> is a &clsql; extension.
 924       </para>
 925     </refsect1>
 926   </refentry>
 927
 928   <refentry id="create-index">
 929     <refmeta>
 930       <refentrytitle>CREATE-INDEX</refentrytitle>
 931     </refmeta>
 932     <refnamediv>
 933       <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-INDEX</emphasis></refname>
 934       <refpurpose>Create a database index.</refpurpose>
 935       <refclass>Function</refclass>
 936     </refnamediv>
 937     <refsect1>
 938       <title>Syntax</title>
 939       <synopsis>
 940       <function>create-index</function> <replaceable>name</replaceable> &amp;key <replaceable>on</replaceable> <replaceable>unique</replaceable> <replaceable>attributes</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 941     </refsect1>
 942     <refsect1>
 943       <title>Arguments and Values</title>
 944       <variablelist>
 945         <varlistentry>
 946           <term><parameter>name</parameter></term>
 947           <listitem>
 948             <para>
 949               The name of the index as a string, symbol or SQL expression.
 950             </para>
 951           </listitem>
 952         </varlistentry>
 953         <varlistentry>
 954           <term><parameter>on</parameter></term>
 955           <listitem>
 956             <para>
 957               The name of a table as a string, symbol or SQL expression.
 958             </para>
 959           </listitem>
 960         </varlistentry>
 961         <varlistentry>
 962           <term><parameter>unique</parameter></term>
 963           <listitem>
 964             <para>
 965               A Boolean.
 966             </para>
 967           </listitem>
 968         </varlistentry>
 969         <varlistentry>
 970           <term><parameter>attributes</parameter></term>
 971           <listitem>
 972             <para>
 973               A list of attribute names.
 974             </para>
 975           </listitem>
 976         </varlistentry>
 977         <varlistentry>
 978           <term><parameter>database</parameter></term>
 979           <listitem>
 980             <para>
 981               A database object which defaults to
 982               <symbol>*default-database*</symbol>.
 983             </para>
 984           </listitem>
 985         </varlistentry>
 986       </variablelist>
 987     </refsect1>
 988     <refsect1>
 989       <title>Description</title>
 990       <para>Creates an index called <parameter>name</parameter> on the
 991       table specified by <parameter>on</parameter> in
 992       <parameter>database</parameter> which default to
 993       <symbol>*default-database*</symbol>. The table attributes to use
 994       in constructing the index <parameter>name</parameter> are
 995       specified by <parameter>attributes</parameter>. The
 996       <parameter>unique</parameter> argument is &nil; by default but
 997       if it has a non-&nil; value then the indexed attributes must
 998       have unique values.
 999       </para>
1000     </refsect1>
1001     <refsect1>
1002       <title>Examples</title>
1003       <screen>
1004 (create-index [bar] :on [employee]
1005               :attributes '([first-name] [last-name] [email])
1006               :unique t)
1007 =>
1008
1009 (index-exists-p [bar])
1010 => T
1011       </screen>
1012     </refsect1>
1013     <refsect1>
1014       <title>Side Effects</title>
1015       <para>
1016         An index is created in <parameter>database</parameter>.
1017       </para>
1018     </refsect1>
1019     <refsect1>
1020       <title>Affected by</title>
1021       <para>
1022         <symbol>*default-database*</symbol>
1023       </para>
1024     </refsect1>
1025     <refsect1>
1026       <title>Exceptional Situations</title>
1027       <para>
1028         An error is signalled if <parameter>name</parameter> is not a
1029         string, symbol or SQL expression. An error of type
1030         <symbol>sql-database-data-error</symbol> is signalled if a
1031         relation called <parameter>name</parameter> already exists.
1032       </para>
1033     </refsect1>
1034     <refsect1>
1035       <title>See Also</title>
1036       <simplelist>
1037         <member><link linkend="drop-index"><function>drop-index</function></link></member>
1038         <member><link linkend="list-indexes"><function>list-indexes</function></link></member>
1039         <member><link linkend="index-exists-p"><function>index-exists-p</function></link></member>
1040       </simplelist>
1041     </refsect1>
1042     <refsect1>
1043       <title>Notes</title>
1044       <para>
1045         None.
1046       </para>
1047     </refsect1>
1048   </refentry>
1049
1050   <refentry id="drop-index">
1051     <refmeta>
1052       <refentrytitle>DROP-INDEX</refentrytitle>
1053     </refmeta>
1054     <refnamediv>
1055       <refname><emphasis>Function</emphasis> <emphasis role="bold">DROP-INDEX</emphasis></refname>
1056       <refpurpose>Drop a database index.</refpurpose>
1057       <refclass>Function</refclass>
1058     </refnamediv>
1059     <refsect1>
1060       <title>Syntax</title>
1061       <synopsis>
1062       <function>drop-index</function> <replaceable>name</replaceable> &amp;key <replaceable>if-does-not-exist</replaceable> <replaceable>on</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
1063     </refsect1>
1064     <refsect1>
1065       <title>Arguments and Values</title>
1066       <variablelist>
1067         <varlistentry>
1068           <term><parameter>name</parameter></term>
1069           <listitem>
1070             <para>
1071               The name of the index as a string, symbol or SQL expression.
1072             </para>
1073           </listitem>
1074         </varlistentry>
1075         <varlistentry>
1076           <term><parameter>on</parameter></term>
1077           <listitem>
1078             <para>
1079               The name of a table as a string, symbol or SQL
1080               expression.
1081             </para>
1082           </listitem>
1083         </varlistentry>
1084         <varlistentry>
1085           <term><parameter>database</parameter></term>
1086           <listitem>
1087             <para>
1088               A database object which defaults to
1089               <symbol>*default-database*</symbol>.
1090             </para>
1091           </listitem>
1092         </varlistentry>
1093         <varlistentry>
1094           <term><parameter>if-does-not-exist</parameter></term>
1095           <listitem>
1096             <para>
1097               A symbol. Meaningful values are <symbol>:ignore</symbol>
1098               or <symbol>:error</symbol> (the default).
1099             </para>
1100           </listitem>
1101         </varlistentry>
1102       </variablelist>
1103     </refsect1>
1104     <refsect1>
1105       <title>Description</title>
1106       <para>Drops the index called <parameter>name</parameter> in
1107       <parameter>database</parameter> which defaults to
1108       <symbol>*default-database*</symbol>. If the index does not exist
1109       and <parameter>if-does-not-exist</parameter> is
1110       <symbol>:ignore</symbol> then <parameter>drop-index</parameter>
1111       returns &nil; whereas an error is signalled if
1112       <parameter>if-does-not-exist</parameter> is
1113       <symbol>:error</symbol>.
1114       </para>
1115       <para>
1116         The argument <parameter>on</parameter> allows the optional
1117         specification of a table to drop the index from. This is
1118         required for compatability with MySQL.
1119       </para>
1120     </refsect1>
1121     <refsect1>
1122       <title>Examples</title>
1123       <screen>
1124 (index-exists-p [foo])
1125 => T
1126 (drop-index [foo] :if-does-not-exist :ignore)
1127 =>
1128 (index-exists-p [foo])
1129 => NIL
1130       </screen>
1131     </refsect1>
1132     <refsect1>
1133       <title>Side Effects</title>
1134       <para>
1135         An index is dropped in <parameter>database</parameter>.
1136       </para>
1137     </refsect1>
1138     <refsect1>
1139       <title>Affected by</title>
1140       <para>
1141         <symbol>*default-database*</symbol>
1142       </para>
1143     </refsect1>
1144     <refsect1>
1145       <title>Exceptional Situations</title>
1146       <para>
1147         An error is signalled if <parameter>name</parameter> is not a
1148         string, symbol or SQL expression. An error of type
1149         <symbol>sql-database-data-error</symbol> is signalled if
1150         <parameter>name</parameter> doesn't exist and
1151         <parameter>if-does-not-exist</parameter> has a value of
1152         <symbol>:error</symbol>.
1153       </para>
1154     </refsect1>
1155     <refsect1>
1156       <title>See Also</title>
1157       <simplelist>
1158         <member><link linkend="create-index"><function>create-index</function></link></member>
1159         <member><link linkend="list-indexes"><function>list-indexes</function></link></member>
1160         <member><link linkend="index-exists-p"><function>index-exists-p</function></link></member>
1161       </simplelist>
1162     </refsect1>
1163     <refsect1>
1164       <title>Notes</title>
1165       <para>
1166         The <parameter>if-does-not-exist</parameter> and
1167         <parameter>on</parameter> keyword arguments to
1168         <function>drop-index</function> are &clsql; extensions.  The
1169         keyword argument <parameter>on</parameter> is provided for
1170         compatibility with MySQL.
1171       </para>
1172     </refsect1>
1173   </refentry>
1174
1175   <refentry id="list-indexes">
1176     <refmeta>
1177       <refentrytitle>LIST-INDEXES</refentrytitle>
1178     </refmeta>
1179     <refnamediv>
1180       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-INDEXES</emphasis></refname>
1181       <refpurpose>Returns a list of database indexes.</refpurpose>
1182       <refclass>Function</refclass>
1183     </refnamediv>
1184     <refsect1>
1185       <title>Syntax</title>
1186       <synopsis>
1187       <function>list-indexes</function> &amp;key <replaceable>on</replaceable><replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1188     </refsect1>
1189     <refsect1>
1190       <title>Arguments and Values</title>
1191       <variablelist>
1192         <varlistentry>
1193           <term><parameter>owner</parameter></term>
1194           <listitem>
1195             <para>
1196               A string, &nil; or <symbol>:all</symbol>.
1197             </para>
1198           </listitem>
1199         </varlistentry>
1200         <varlistentry>
1201           <term><parameter>database</parameter></term>
1202           <listitem>
1203             <para>
1204               A database object which defaults to
1205               <symbol>*default-database*</symbol>.
1206             </para>
1207           </listitem>
1208         </varlistentry>
1209         <varlistentry>
1210           <term><parameter>on</parameter></term>
1211           <listitem>
1212             <para>
1213               The name of a table as a string, symbol or SQL
1214               expression, a list of such names or &nil;.
1215             </para>
1216           </listitem>
1217         </varlistentry>
1218         <varlistentry>
1219           <term><parameter>result</parameter></term>
1220           <listitem>
1221             <para>
1222               A list of strings.
1223             </para>
1224           </listitem>
1225         </varlistentry>
1226       </variablelist>
1227     </refsect1>
1228     <refsect1>
1229       <title>Description</title>
1230       <para>Returns a list of strings representing index names in
1231       <parameter>database</parameter> which defaults to
1232       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
1233       is &nil; by default which means that only indexes owned by users
1234       are listed. If <parameter>owner</parameter> is a string denoting
1235       a user name, only indexes owned by <parameter>owner</parameter>
1236       are listed. If <parameter>owner</parameter> is
1237       <symbol>:all</symbol> then all indexes are listed.
1238       </para>
1239       <para>
1240          The keyword argument <parameter>on</parameter> limits the
1241          results to indexes on the specified tables. Meaningful values
1242          for <parameter>on</parameter> are &nil; (the default) which
1243          means that all tables are considered, a string, symbol or SQL
1244          expression representing a table name in
1245          <parameter>database</parameter> or a list of such table
1246          identifiers.
1247       </para>
1248     </refsect1>
1249     <refsect1>
1250       <title>Examples</title>
1251       <screen>
1252 (list-indexes)
1253 => ("employeepk" "companypk" "addrpk" "bar")
1254
1255 (list-indexes :on '([addr] [company]))
1256 => ("addrpk" "companypk")
1257       </screen>
1258     </refsect1>
1259     <refsect1>
1260       <title>Side Effects</title>
1261       <para>
1262         None.
1263       </para>
1264     </refsect1>
1265     <refsect1>
1266       <title>Affected by</title>
1267       <para>
1268         <symbol>*default-database*</symbol>
1269       </para>
1270     </refsect1>
1271     <refsect1>
1272       <title>Exceptional Situations</title>
1273       <para>
1274         None.
1275       </para>
1276     </refsect1>
1277     <refsect1>
1278       <title>See Also</title>
1279       <simplelist>
1280         <member><link linkend="create-index"><function>create-index</function></link></member>
1281         <member><link linkend="drop-index"><function>drop-index</function></link></member>
1282         <member><link linkend="index-exists-p"><function>index-exists-p</function></link></member>
1283       </simplelist>
1284     </refsect1>
1285     <refsect1>
1286       <title>Notes</title>
1287       <para>
1288         <function>list-indexes</function> is a &clsql; extension.
1289       </para>
1290     </refsect1>
1291   </refentry>
1292
1293   <refentry id="index-exists-p">
1294     <refmeta>
1295       <refentrytitle>INDEX-EXISTS-P</refentrytitle>
1296     </refmeta>
1297     <refnamediv>
1298       <refname><emphasis>Function</emphasis> <emphasis role="bold">INDEX-EXISTS-P</emphasis></refname>
1299       <refpurpose>Tests for the existence of a database index.</refpurpose>
1300       <refclass>Function</refclass>
1301     </refnamediv>
1302     <refsect1>
1303       <title>Syntax</title>
1304       <synopsis>
1305       <function>index-exists-p</function> <replaceable>name</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1306     </refsect1>
1307     <refsect1>
1308       <title>Arguments and Values</title>
1309       <variablelist>
1310         <varlistentry>
1311           <term><parameter>name</parameter></term>
1312           <listitem>
1313             <para>
1314               The name of the index as a string, symbol or SQL expression.
1315             </para>
1316           </listitem>
1317         </varlistentry>
1318         <varlistentry>
1319           <term><parameter>owner</parameter></term>
1320           <listitem>
1321             <para>
1322               A string, &nil; or <symbol>:all</symbol>.
1323             </para>
1324           </listitem>
1325         </varlistentry>
1326         <varlistentry>
1327           <term><parameter>database</parameter></term>
1328           <listitem>
1329             <para>
1330               A database object which defaults to
1331               <symbol>*default-database*</symbol>.
1332             </para>
1333           </listitem>
1334         </varlistentry>
1335         <varlistentry>
1336           <term><parameter>result</parameter></term>
1337           <listitem>
1338             <para>
1339               A Boolean.
1340             </para>
1341           </listitem>
1342         </varlistentry>
1343       </variablelist>
1344     </refsect1>
1345     <refsect1>
1346       <title>Description</title>
1347       <para>Tests for the existence of an SQL index called
1348       <parameter>name</parameter> in <parameter>database</parameter>
1349       which defaults to
1350       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
1351       is &nil; by default which means that only indexes owned by users
1352       are examined. If <parameter>owner</parameter> is a string
1353       denoting a user name, only indexes owned by
1354       <parameter>owner</parameter> are examined. If
1355       <parameter>owner</parameter> is <symbol>:all</symbol> then all
1356       indexes are examined.
1357       </para>
1358     </refsect1>
1359     <refsect1>
1360       <title>Examples</title>
1361       <screen>
1362 (index-exists-p [bar])
1363 => T
1364       </screen>
1365     </refsect1>
1366     <refsect1>
1367       <title>Side Effects</title>
1368       <para>
1369         None.
1370       </para>
1371     </refsect1>
1372     <refsect1>
1373       <title>Affected by</title>
1374       <para>
1375         <symbol>*default-database*</symbol>
1376       </para>
1377     </refsect1>
1378     <refsect1>
1379       <title>Exceptional Situations</title>
1380       <para>
1381         None.
1382       </para>
1383     </refsect1>
1384     <refsect1>
1385       <title>See Also</title>
1386       <simplelist>
1387         <member><link linkend="create-index"><function>create-index</function></link></member>
1388         <member><link linkend="drop-index"><function>drop-index</function></link></member>
1389         <member><link linkend="list-indexes"><function>list-indexes</function></link></member>
1390       </simplelist>
1391     </refsect1>
1392     <refsect1>
1393       <title>Notes</title>
1394       <para>
1395         <function>index-exists-p</function> is a &clsql; extension.
1396       </para>
1397     </refsect1>
1398   </refentry>
1399
1400   <refentry id="attribute-type">
1401     <refmeta>
1402       <refentrytitle>ATTRIBUTE-TYPE</refentrytitle>
1403     </refmeta>
1404     <refnamediv>
1405       <refname><emphasis>Function</emphasis> <emphasis role="bold">ATTRIBUTE-TYPE</emphasis></refname>
1406       <refpurpose>Returns the type of the supplied attribute.</refpurpose>
1407       <refclass>Function</refclass>
1408     </refnamediv>
1409     <refsect1>
1410       <title>Syntax</title>
1411       <synopsis>
1412       <function>attribute-type attribute</function> <replaceable>table</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>type</returnvalue>, <returnvalue>precision</returnvalue>, <returnvalue>scale</returnvalue>, <returnvalue>nulls-accepted</returnvalue></synopsis>
1413     </refsect1>
1414     <refsect1>
1415       <title>Arguments and Values</title>
1416       <variablelist>
1417         <varlistentry>
1418           <term><parameter>attribute</parameter></term>
1419           <listitem>
1420             <para>
1421               The name of the index as a string, symbol or SQL expression.
1422             </para>
1423           </listitem>
1424         </varlistentry>
1425         <varlistentry>
1426           <term><parameter>table</parameter></term>
1427           <listitem>
1428             <para>
1429               The name of a table as a string, symbol or SQL expression.
1430             </para>
1431           </listitem>
1432         </varlistentry>
1433         <varlistentry>
1434           <term><parameter>owner</parameter></term>
1435           <listitem>
1436             <para>
1437               A string, &nil; or <symbol>:all</symbol>.
1438             </para>
1439           </listitem>
1440         </varlistentry>
1441         <varlistentry>
1442           <term><parameter>database</parameter></term>
1443           <listitem>
1444             <para>
1445               A database object which defaults to
1446               <symbol>*default-database*</symbol>.
1447             </para>
1448           </listitem>
1449         </varlistentry>
1450         <varlistentry>
1451           <term><parameter>type</parameter></term>
1452           <listitem>
1453             <para>
1454               A keyword symbol denoting a vendor-specific SQL type.
1455             </para>
1456           </listitem>
1457         </varlistentry>
1458         <varlistentry>
1459           <term><parameter>precision</parameter></term>
1460           <listitem>
1461             <para>
1462               An integer denoting the precision of the attribute type
1463               or &nil;.
1464             </para>
1465           </listitem>
1466         </varlistentry>
1467         <varlistentry>
1468           <term><parameter>scale</parameter></term>
1469           <listitem>
1470             <para>
1471               An integer denoting the scale of the attribute type
1472               or &nil;.
1473             </para>
1474           </listitem>
1475         </varlistentry>
1476         <varlistentry>
1477           <term><parameter>nulls-accepted</parameter></term>
1478           <listitem>
1479             <para>
1480               0 or 1.
1481             </para>
1482           </listitem>
1483         </varlistentry>
1484       </variablelist>
1485     </refsect1>
1486     <refsect1>
1487       <title>Description</title>
1488       <para>Returns a keyword symbol representing the vendor-specific
1489       field type of the supplied attribute
1490       <parameter>attribute</parameter> in the table specified by
1491       <parameter>table</parameter> in <parameter>database</parameter>
1492       which defaults to
1493       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
1494       is &nil; by default which means that the attribute specified by
1495       <parameter>attribute</parameter>, if it exists, must be user
1496       owned else &nil; is returned. If <parameter>owner</parameter> is
1497       a string denoting a user name, the attribute, if it exists, must
1498       be owned by <parameter>owner</parameter> else &nil; is returned,
1499       whereas if <parameter>owner</parameter> is <symbol>:all</symbol>
1500       then the attribute, if it exists, will be returned regardless of
1501       its owner.
1502       </para>
1503
1504       <para>Other information is also returned. The second value is
1505       the type precision, the third is the scale and the fourth
1506       represents whether or not the attribute accepts null values (a
1507       value of 0) or not (a value of 1).
1508       </para>
1509     </refsect1>
1510     <refsect1>
1511       <title>Examples</title>
1512       <screen>
1513 (attribute-type [emplid] [employee])
1514 => :INT4, 4, NIL, 0
1515       </screen>
1516     </refsect1>
1517     <refsect1>
1518       <title>Side Effects</title>
1519       <para>
1520         None.
1521       </para>
1522     </refsect1>
1523     <refsect1>
1524       <title>Affected by</title>
1525       <para>
1526         <symbol>*default-database*</symbol>
1527       </para>
1528     </refsect1>
1529     <refsect1>
1530       <title>Exceptional Situations</title>
1531       <para>
1532         None.
1533       </para>
1534     </refsect1>
1535     <refsect1>
1536       <title>See Also</title>
1537       <simplelist>
1538         <member><link linkend="list-attributes"><function>list-attributes</function></link></member>
1539         <member><link linkend="list-attribute-types"><function>list-attribute-types</function></link></member>
1540       </simplelist>
1541     </refsect1>
1542     <refsect1>
1543       <title>Notes</title>
1544       <para>
1545         None.
1546       </para>
1547     </refsect1>
1548   </refentry>
1549
1550   <refentry id="list-attribute-types">
1551     <refmeta>
1552       <refentrytitle>LIST-ATTRIBUTE-TYPES</refentrytitle>
1553     </refmeta>
1554     <refnamediv>
1555       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-ATTRIBUTE-TYPES</emphasis></refname>
1556       <refpurpose>Returns information about the attribute types of a table.</refpurpose>
1557       <refclass>Function</refclass>
1558     </refnamediv>
1559     <refsect1>
1560       <title>Syntax</title>
1561       <synopsis>
1562       <function>list-attribute-types</function> <replaceable>table</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1563     </refsect1>
1564     <refsect1>
1565       <title>Arguments and Values</title>
1566       <variablelist>
1567         <varlistentry>
1568           <term><parameter>table</parameter></term>
1569           <listitem>
1570             <para>
1571               The name of a table as a string, symbol or SQL expression.
1572             </para>
1573           </listitem>
1574         </varlistentry>
1575         <varlistentry>
1576           <term><parameter>owner</parameter></term>
1577           <listitem>
1578             <para>
1579               A string, &nil; or <symbol>:all</symbol>.
1580             </para>
1581           </listitem>
1582         </varlistentry>
1583         <varlistentry>
1584           <term><parameter>database</parameter></term>
1585           <listitem>
1586             <para>
1587               A database object which defaults to
1588               <symbol>*default-database*</symbol>.
1589             </para>
1590           </listitem>
1591         </varlistentry>
1592         <varlistentry>
1593           <term><parameter>result</parameter></term>
1594           <listitem>
1595             <para>
1596               A list.
1597             </para>
1598           </listitem>
1599         </varlistentry>
1600       </variablelist>
1601     </refsect1>
1602     <refsect1>
1603       <title>Description</title>
1604       <para>Returns a list containing information about the SQL types
1605       of each of the attributes in the table specified by
1606       <parameter>table</parameter> in <parameter>database</parameter>
1607       which has a default value of
1608       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
1609       is &nil; by default which means that only attributes owned by
1610       users are listed. If <parameter>owner</parameter> is a string
1611       denoting a user name, only attributes owned by
1612       <parameter>owner</parameter> are listed. If
1613       <parameter>owner</parameter> is <symbol>:all</symbol> then all
1614       attributes are listed. The elements of the returned list are
1615       lists where the first element is the name of the attribute, the
1616       second element is its SQL type, the third is the type precision,
1617       the fourth is the scale of the attribute and the fifth is 1 if
1618       the attribute accepts null values and otherwise 0.
1619       </para>
1620     </refsect1>
1621     <refsect1>
1622       <title>Examples</title>
1623       <screen>
1624 (list-attribute-types [employee])
1625 => (("emplid" :INT4 4 NIL 0) ("groupid" :INT4 4 NIL 0)
1626     ("first_name" :VARCHAR 30 NIL 1) ("last_name" :VARCHAR 30 NIL 1)
1627     ("email" :VARCHAR 100 NIL 1) ("ecompanyid" :INT4 4 NIL 1)
1628     ("managerid" :INT4 4 NIL 1) ("height" :FLOAT8 8 NIL 1)
1629     ("married" :BOOL 1 NIL 1) ("birthday" :TIMESTAMP 8 NIL 1)
1630     ("bd_utime" :INT8 8 NIL 1))
1631       </screen>
1632     </refsect1>
1633     <refsect1>
1634       <title>Side Effects</title>
1635       <para>
1636         None.
1637       </para>
1638     </refsect1>
1639     <refsect1>
1640       <title>Affected by</title>
1641       <para>
1642         <symbol>*default-database*</symbol>
1643       </para>
1644     </refsect1>
1645     <refsect1>
1646       <title>Exceptional Situations</title>
1647       <para>
1648         None.
1649       </para>
1650     </refsect1>
1651     <refsect1>
1652       <title>See Also</title>
1653       <simplelist>
1654         <member><link linkend="attribute-type"><function>attribute-type</function></link></member>
1655         <member><link linkend="list-attribute-types"><function>list-attribute-types</function></link></member>
1656       </simplelist>
1657     </refsect1>
1658     <refsect1>
1659       <title>Notes</title>
1660       <para>
1661         None.
1662       </para>
1663     </refsect1>
1664   </refentry>
1665
1666   <refentry id="list-attributes">
1667     <refmeta>
1668       <refentrytitle>LIST-ATTRIBUTES</refentrytitle>
1669     </refmeta>
1670     <refnamediv>
1671       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-ATTRIBUTES</emphasis></refname>
1672       <refpurpose>Returns the attributes of a table as a list.</refpurpose>
1673       <refclass>Function</refclass>
1674     </refnamediv>
1675     <refsect1>
1676       <title>Syntax</title>
1677       <synopsis>
1678       <function>list-attributes</function> <replaceable>name</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1679     </refsect1>
1680     <refsect1>
1681       <title>Arguments and Values</title>
1682       <variablelist>
1683         <varlistentry>
1684           <term><parameter>name</parameter></term>
1685           <listitem>
1686             <para>
1687               The name of a table as a string, symbol or SQL expression.
1688             </para>
1689           </listitem>
1690         </varlistentry>
1691         <varlistentry>
1692           <term><parameter>owner</parameter></term>
1693           <listitem>
1694             <para>
1695               A string, &nil; or <symbol>:all</symbol>.
1696             </para>
1697           </listitem>
1698         </varlistentry>
1699         <varlistentry>
1700           <term><parameter>database</parameter></term>
1701           <listitem>
1702             <para>
1703               A database object which defaults to
1704               <symbol>*default-database*</symbol>.
1705             </para>
1706           </listitem>
1707         </varlistentry>
1708         <varlistentry>
1709           <term><parameter>result</parameter></term>
1710           <listitem>
1711             <para>
1712               A list.
1713             </para>
1714           </listitem>
1715         </varlistentry>
1716       </variablelist>
1717     </refsect1>
1718     <refsect1>
1719       <title>Description</title>
1720       <para>Returns a list of strings representing the attributes of
1721       table <parameter>name</parameter> in
1722       <parameter>database</parameter> which defaults to
1723       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
1724       is &nil; by default which means that only attributes owned by
1725       users are listed. If <parameter>owner</parameter> is a string
1726       denoting a user name, only attributes owned by
1727       <parameter>owner</parameter> are listed. If
1728       <parameter>owner</parameter> is <symbol>:all</symbol> then all
1729       attributes are listed.
1730       </para>
1731     </refsect1>
1732     <refsect1>
1733       <title>Examples</title>
1734       <screen>
1735 (list-attributes [employee])
1736 => ("emplid" "groupid" "first_name" "last_name" "email" "ecompanyid" "managerid"
1737     "height" "married" "birthday" "bd_utime")
1738       </screen>
1739     </refsect1>
1740     <refsect1>
1741       <title>Side Effects</title>
1742       <para>
1743         None.
1744       </para>
1745     </refsect1>
1746     <refsect1>
1747       <title>Affected by</title>
1748       <para>
1749         <symbol>*default-database*</symbol>
1750       </para>
1751     </refsect1>
1752     <refsect1>
1753       <title>Exceptional Situations</title>
1754       <para>
1755         None.
1756       </para>
1757     </refsect1>
1758     <refsect1>
1759       <title>See Also</title>
1760       <simplelist>
1761         <member><link linkend="attribute-type"><function>attribute-type</function></link></member>
1762         <member><link linkend="list-attribute-types"><function>list-attribute-types</function></link></member>
1763       </simplelist>
1764     </refsect1>
1765     <refsect1>
1766       <title>Notes</title>
1767       <para>
1768         None.
1769       </para>
1770     </refsect1>
1771   </refentry>
1772
1773   <refentry id="create-sequence">
1774     <refmeta>
1775       <refentrytitle>CREATE-SEQUENCE</refentrytitle>
1776     </refmeta>
1777     <refnamediv>
1778       <refname><emphasis>Function</emphasis> <emphasis role="bold">CREATE-SEQUENCE</emphasis></refname>
1779       <refpurpose>Create a database sequence.</refpurpose>
1780       <refclass>Function</refclass>
1781     </refnamediv>
1782     <refsect1>
1783       <title>Syntax</title>
1784       <synopsis>
1785       <function>create-sequence</function> <replaceable>name</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
1786     </refsect1>
1787     <refsect1>
1788       <title>Arguments and Values</title>
1789       <variablelist>
1790         <varlistentry>
1791           <term><parameter>name</parameter></term>
1792           <listitem>
1793             <para>
1794               The name of the sequence as a string, symbol or SQL expression.
1795             </para>
1796           </listitem>
1797         </varlistentry>
1798         <varlistentry>
1799           <term><parameter>database</parameter></term>
1800           <listitem>
1801             <para>
1802               A database object which defaults to
1803               <symbol>*default-database*</symbol>.
1804             </para>
1805           </listitem>
1806         </varlistentry>
1807       </variablelist>
1808     </refsect1>
1809     <refsect1>
1810       <title>Description</title>
1811       <para>Creates a sequence called <parameter>name</parameter> in
1812       <parameter>database</parameter> which defaults to
1813       <symbol>*default-database*</symbol>.
1814       </para>
1815     </refsect1>
1816     <refsect1>
1817       <title>Examples</title>
1818       <screen>
1819 (create-sequence [foo])
1820 =>
1821 (sequence-exists-p [foo])
1822 => T
1823       </screen>
1824     </refsect1>
1825     <refsect1>
1826       <title>Side Effects</title>
1827       <para>
1828         A sequence is created in <parameter>database</parameter>.
1829       </para>
1830     </refsect1>
1831     <refsect1>
1832       <title>Affected by</title>
1833       <para>
1834         <symbol>*default-database*</symbol>
1835       </para>
1836     </refsect1>
1837     <refsect1>
1838       <title>Exceptional Situations</title>
1839       <para>
1840         An error is signalled if <parameter>name</parameter> is not a
1841         string, symbol or SQL expression. An error of type
1842         <symbol>sql-database-data-error</symbol> is signalled if a
1843         relation called <parameter>name</parameter> already exists.
1844       </para>
1845     </refsect1>
1846     <refsect1>
1847       <title>See Also</title>
1848       <simplelist>
1849         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
1850         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
1851         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
1852         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
1853         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
1854         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
1855       </simplelist>
1856     </refsect1>
1857     <refsect1>
1858       <title>Notes</title>
1859       <para>
1860         <function>create-sequence</function> is a &clsql; extension.
1861       </para>
1862     </refsect1>
1863   </refentry>
1864
1865   <refentry id="drop-sequence">
1866     <refmeta>
1867       <refentrytitle>DROP-SEQUENCE</refentrytitle>
1868     </refmeta>
1869     <refnamediv>
1870       <refname><emphasis>Function</emphasis> <emphasis role="bold">DROP-SEQUENCE</emphasis></refname>
1871       <refpurpose>Drop a database sequence.</refpurpose>
1872       <refclass>Function</refclass>
1873     </refnamediv>
1874     <refsect1>
1875       <title>Syntax</title>
1876       <synopsis>
1877       <function>drop-sequence</function> <replaceable>name</replaceable> &amp;key <replaceable>if-does-not-exist</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
1878     </refsect1>
1879     <refsect1>
1880       <title>Arguments and Values</title>
1881       <variablelist>
1882         <varlistentry>
1883           <term><parameter>name</parameter></term>
1884           <listitem>
1885             <para>
1886               The name of the sequence as a string, symbol or SQL expression.
1887             </para>
1888           </listitem>
1889         </varlistentry>
1890         <varlistentry>
1891           <term><parameter>database</parameter></term>
1892           <listitem>
1893             <para>
1894               A database object which defaults to
1895               <symbol>*default-database*</symbol>.
1896             </para>
1897           </listitem>
1898         </varlistentry>
1899         <varlistentry>
1900           <term><parameter>if-does-not-exist</parameter></term>
1901           <listitem>
1902             <para>
1903               A symbol. Meaningful values are <symbol>:ignore</symbol>
1904               or <symbol>:error</symbol> (the default).
1905             </para>
1906           </listitem>
1907         </varlistentry>
1908       </variablelist>
1909     </refsect1>
1910     <refsect1>
1911       <title>Description</title>
1912       <para>Drops the sequence called <parameter>name</parameter> from
1913       <parameter>database</parameter> which defaults to
1914       <symbol>*default-database*</symbol>. If the sequence does not
1915       exist and <parameter>if-does-not-exist</parameter> is
1916       <symbol>:ignore</symbol> then
1917       <parameter>drop-sequence</parameter> returns &nil; whereas an
1918       error is signalled if <parameter>if-does-not-exist</parameter>
1919       is <symbol>:error</symbol>.
1920       </para>
1921     </refsect1>
1922     <refsect1>
1923       <title>Examples</title>
1924       <screen>
1925 (sequence-exists-p [foo])
1926 => T
1927 (drop-sequence [foo] :if-does-not-exist :ignore)
1928 =>
1929 (sequence-exists-p [foo])
1930 => NIL
1931       </screen>
1932     </refsect1>
1933     <refsect1>
1934       <title>Side Effects</title>
1935       <para>
1936         A sequence is dropped from <parameter>database</parameter>.
1937       </para>
1938     </refsect1>
1939     <refsect1>
1940       <title>Affected by</title>
1941       <para>
1942         <symbol>*default-database*</symbol>
1943       </para>
1944     </refsect1>
1945     <refsect1>
1946       <title>Exceptional Situations</title>
1947       <para>
1948         An error is signalled if <parameter>name</parameter> is not a
1949         string, symbol or SQL expression. An error of type
1950         <symbol>sql-database-data-error</symbol> is signalled if
1951         <parameter>name</parameter> doesn't exist and
1952         <parameter>if-does-not-exist</parameter> has a value of
1953         <symbol>:error</symbol>.
1954       </para>
1955     </refsect1>
1956     <refsect1>
1957       <title>See Also</title>
1958       <simplelist>
1959         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
1960         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
1961         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
1962         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
1963         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
1964         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
1965       </simplelist>
1966     </refsect1>
1967     <refsect1>
1968       <title>Notes</title>
1969       <para>
1970         <function>drop-sequence</function> is a &clsql; extension.
1971       </para>
1972     </refsect1>
1973   </refentry>
1974
1975   <refentry id="list-sequences">
1976     <refmeta>
1977       <refentrytitle>LIST-SEQUENCES</refentrytitle>
1978     </refmeta>
1979     <refnamediv>
1980       <refname><emphasis>Function</emphasis> <emphasis role="bold">LIST-SEQUENCES</emphasis></refname>
1981       <refpurpose>Returns a list of database sequences.</refpurpose>
1982       <refclass>Function</refclass>
1983     </refnamediv>
1984     <refsect1>
1985       <title>Syntax</title>
1986       <synopsis>
1987       <function>list-sequences</function> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1988     </refsect1>
1989     <refsect1>
1990       <title>Arguments and Values</title>
1991       <variablelist>
1992         <varlistentry>
1993           <term><parameter>owner</parameter></term>
1994           <listitem>
1995             <para>
1996               A string, &nil; or <symbol>:all</symbol>.
1997             </para>
1998           </listitem>
1999         </varlistentry>
2000         <varlistentry>
2001           <term><parameter>database</parameter></term>
2002           <listitem>
2003             <para>
2004               A database object which defaults to
2005               <symbol>*default-database*</symbol>.
2006             </para>
2007           </listitem>
2008         </varlistentry>
2009         <varlistentry>
2010           <term><parameter>result</parameter></term>
2011           <listitem>
2012             <para>
2013               A list of strings.
2014             </para>
2015           </listitem>
2016         </varlistentry>
2017       </variablelist>
2018     </refsect1>
2019     <refsect1>
2020       <title>Description</title>
2021       <para>Returns a list of strings representing sequence names in
2022       <parameter>database</parameter> which defaults to
2023       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
2024       is &nil; by default which means that only sequences owned by
2025       users are listed. If <parameter>owner</parameter> is a string
2026       denoting a user name, only sequences owned by
2027       <parameter>owner</parameter> are listed. If
2028       <parameter>owner</parameter> is <symbol>:all</symbol> then all
2029       sequences are listed.
2030       </para>
2031     </refsect1>
2032     <refsect1>
2033       <title>Examples</title>
2034       <screen>
2035 (list-sequences)
2036 => ("foo")
2037       </screen>
2038     </refsect1>
2039     <refsect1>
2040       <title>Side Effects</title>
2041       <para>
2042         None.
2043       </para>
2044     </refsect1>
2045     <refsect1>
2046       <title>Affected by</title>
2047       <para>
2048         <symbol>*default-database*</symbol>
2049       </para>
2050     </refsect1>
2051     <refsect1>
2052       <title>Exceptional Situations</title>
2053       <para>
2054         None.
2055       </para>
2056     </refsect1>
2057     <refsect1>
2058       <title>See Also</title>
2059       <simplelist>
2060         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
2061         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
2062         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
2063         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
2064         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
2065         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
2066       </simplelist>
2067     </refsect1>
2068     <refsect1>
2069       <title>Notes</title>
2070       <para>
2071         <function>list-sequences</function> is a &clsql; extension.
2072       </para>
2073     </refsect1>
2074   </refentry>
2075
2076   <refentry id="sequence-exists-p">
2077     <refmeta>
2078       <refentrytitle>SEQUENCE-EXISTS-P</refentrytitle>
2079     </refmeta>
2080     <refnamediv>
2081       <refname><emphasis>Function</emphasis> <emphasis role="bold">SEQUENCE-EXISTS-P</emphasis></refname>
2082       <refpurpose>Tests for the existence of a database sequence.</refpurpose>
2083       <refclass>Function</refclass>
2084     </refnamediv>
2085     <refsect1>
2086       <title>Syntax</title>
2087       <synopsis>
2088       <function>sequence-exists-p</function> <replaceable>name</replaceable> &amp;key <replaceable>owner</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
2089     </refsect1>
2090     <refsect1>
2091       <title>Arguments and Values</title>
2092       <variablelist>
2093         <varlistentry>
2094           <term><parameter>name</parameter></term>
2095           <listitem>
2096             <para>
2097               The name of the sequence as a string, symbol or SQL expression.
2098             </para>
2099           </listitem>
2100         </varlistentry>
2101         <varlistentry>
2102           <term><parameter>owner</parameter></term>
2103           <listitem>
2104             <para>
2105               A string, &nil; or <symbol>:all</symbol>.
2106             </para>
2107           </listitem>
2108         </varlistentry>
2109         <varlistentry>
2110           <term><parameter>database</parameter></term>
2111           <listitem>
2112             <para>
2113               A database object which defaults to
2114               <symbol>*default-database*</symbol>.
2115             </para>
2116           </listitem>
2117         </varlistentry>
2118         <varlistentry>
2119           <term><parameter>result</parameter></term>
2120           <listitem>
2121             <para>
2122               A Boolean.
2123             </para>
2124           </listitem>
2125         </varlistentry>
2126       </variablelist>
2127     </refsect1>
2128     <refsect1>
2129       <title>Description</title>
2130       <para>Tests for the existence of an SQL sequence called
2131       <parameter>name</parameter> in <parameter>database</parameter>
2132       which defaults to
2133       <symbol>*default-database*</symbol>. <parameter>owner</parameter>
2134       is &nil; by default which means that only sequences owned by
2135       users are examined. If <parameter>owner</parameter> is a string
2136       denoting a user name, only sequences owned by
2137       <parameter>owner</parameter> are examined. If
2138       <parameter>owner</parameter> is <symbol>:all</symbol> then all
2139       sequences are examined.
2140       </para>
2141     </refsect1>
2142     <refsect1>
2143       <title>Examples</title>
2144       <screen>
2145 (sequence-exists-p [foo])
2146 => NIL
2147       </screen>
2148     </refsect1>
2149     <refsect1>
2150       <title>Side Effects</title>
2151       <para>
2152         None.
2153       </para>
2154     </refsect1>
2155     <refsect1>
2156       <title>Affected by</title>
2157       <para>
2158         <symbol>*default-database*</symbol>
2159       </para>
2160     </refsect1>
2161     <refsect1>
2162       <title>Exceptional Situations</title>
2163       <para>
2164         None.
2165       </para>
2166     </refsect1>
2167     <refsect1>
2168       <title>See Also</title>
2169       <simplelist>
2170         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
2171         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
2172         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
2173         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
2174         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
2175         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
2176       </simplelist>
2177     </refsect1>
2178     <refsect1>
2179       <title>Notes</title>
2180       <para>
2181         <function>sequence-exists-p</function> is a &clsql; extension.
2182       </para>
2183     </refsect1>
2184   </refentry>
2185
2186   <refentry id="sequence-last">
2187     <refmeta>
2188       <refentrytitle>SEQUENCE-LAST</refentrytitle>
2189     </refmeta>
2190     <refnamediv>
2191       <refname><emphasis>Function</emphasis> <emphasis role="bold">SEQUENCE-LAST</emphasis></refname>
2192       <refpurpose>Return the last element in a database sequence.</refpurpose>
2193       <refclass>Function</refclass>
2194     </refnamediv>
2195     <refsect1>
2196       <title>Syntax</title>
2197       <synopsis>
2198       <function>sequence-last</function> <replaceable>name</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
2199     </refsect1>
2200     <refsect1>
2201       <title>Arguments and Values</title>
2202       <variablelist>
2203         <varlistentry>
2204           <term><parameter>name</parameter></term>
2205           <listitem>
2206             <para>
2207               The name of the sequence as a string, symbol or SQL expression.
2208             </para>
2209           </listitem>
2210         </varlistentry>
2211         <varlistentry>
2212           <term><parameter>database</parameter></term>
2213           <listitem>
2214             <para>
2215               A database object which defaults to
2216               <symbol>*default-database*</symbol>.
2217             </para>
2218           </listitem>
2219         </varlistentry>
2220         <varlistentry>
2221           <term><parameter>result</parameter></term>
2222           <listitem>
2223             <para>
2224               An integer.
2225             </para>
2226           </listitem>
2227         </varlistentry>
2228       </variablelist>
2229     </refsect1>
2230     <refsect1>
2231       <title>Description</title>
2232       <para>Return the last value allocated in the sequence called
2233       <parameter>name</parameter> in <parameter>database</parameter>
2234       which defaults to <symbol>*default-database*</symbol>.
2235       </para>
2236     </refsect1>
2237     <refsect1>
2238       <title>Examples</title>
2239       <screen>
2240 (sequence-last [foo])
2241 => 1
2242       </screen>
2243     </refsect1>
2244     <refsect1>
2245       <title>Side Effects</title>
2246       <para>
2247         None.
2248       </para>
2249     </refsect1>
2250     <refsect1>
2251       <title>Affected by</title>
2252       <para>
2253         The current value stored in database sequence
2254         <parameter>name</parameter>.
2255       </para>
2256       <para>
2257         <symbol>*default-database*</symbol>
2258       </para>
2259     </refsect1>
2260     <refsect1>
2261       <title>Exceptional Situations</title>
2262       <para>
2263         Will signal an error of type
2264         <symbol>sql-database-data-error</symbol> if a sequence called
2265         <parameter>name</parameter> does not exist in
2266         <parameter>database</parameter>.
2267       </para>
2268     </refsect1>
2269     <refsect1>
2270       <title>See Also</title>
2271       <simplelist>
2272         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
2273         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
2274         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
2275         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
2276         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
2277         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
2278       </simplelist>
2279     </refsect1>
2280     <refsect1>
2281       <title>Notes</title>
2282       <para>
2283         <function>sequence-last</function> is a &clsql; extension.
2284       </para>
2285     </refsect1>
2286   </refentry>
2287
2288   <refentry id="sequence-next">
2289     <refmeta>
2290       <refentrytitle>SEQUENCE-NEXT</refentrytitle>
2291     </refmeta>
2292     <refnamediv>
2293       <refname><emphasis>Function</emphasis> <emphasis role="bold">SEQUENCE-NEXT</emphasis></refname>
2294       <refpurpose>Increment the value of a database sequence.</refpurpose>
2295       <refclass>Function</refclass>
2296     </refnamediv>
2297     <refsect1>
2298       <title>Syntax</title>
2299       <synopsis>
2300       <function>sequence-next</function> <replaceable>name</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
2301     </refsect1>
2302     <refsect1>
2303       <title>Arguments and Values</title>
2304       <variablelist>
2305         <varlistentry>
2306           <term><parameter>name</parameter></term>
2307           <listitem>
2308             <para>
2309               The name of the sequence as a string, symbol or SQL expression.
2310             </para>
2311           </listitem>
2312         </varlistentry>
2313         <varlistentry>
2314           <term><parameter>database</parameter></term>
2315           <listitem>
2316             <para>
2317               A database object which defaults to
2318               <symbol>*default-database*</symbol>.
2319             </para>
2320           </listitem>
2321         </varlistentry>
2322         <varlistentry>
2323           <term><parameter>result</parameter></term>
2324           <listitem>
2325             <para>
2326               An integer.
2327             </para>
2328           </listitem>
2329         </varlistentry>
2330       </variablelist>
2331     </refsect1>
2332     <refsect1>
2333       <title>Description</title>
2334       <para>Increment and return the value of the sequence called
2335       <parameter>name</parameter> in <parameter>database</parameter>
2336       which defaults to <symbol>*default-database*</symbol>.
2337       </para>
2338     </refsect1>
2339     <refsect1>
2340       <title>Examples</title>
2341       <screen>
2342 (sequence-last [foo])
2343 => 3
2344 (sequence-next [foo])
2345 => 4
2346 (sequence-next [foo])
2347 => 5
2348 (sequence-next [foo])
2349 => 6
2350       </screen>
2351     </refsect1>
2352     <refsect1>
2353       <title>Side Effects</title>
2354       <para>
2355         Modifies the value of the sequence <parameter>name</parameter>
2356         in <parameter>database</parameter>.
2357       </para>
2358     </refsect1>
2359     <refsect1>
2360       <title>Affected by</title>
2361       <para>
2362         The current value stored in database sequence
2363         <parameter>name</parameter>.
2364       </para>
2365       <para>
2366         <symbol>*default-database*</symbol>
2367       </para>
2368     </refsect1>
2369     <refsect1>
2370       <title>Exceptional Situations</title>
2371       <para>
2372         Will signal an error of type
2373         <symbol>sql-database-data-error</symbol> if a sequence called
2374         <parameter>name</parameter> does not exist in
2375         <parameter>database</parameter>.
2376       </para>
2377     </refsect1>
2378     <refsect1>
2379       <title>See Also</title>
2380       <simplelist>
2381         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
2382         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
2383         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
2384         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
2385         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
2386         <member><link linkend="set-sequence-position"><function>set-sequence-position</function></link></member>
2387       </simplelist>
2388     </refsect1>
2389     <refsect1>
2390       <title>Notes</title>
2391       <para>
2392         <function>sequence-next</function> is a &clsql; extension.
2393       </para>
2394     </refsect1>
2395   </refentry>
2396
2397   <refentry id="set-sequence-position">
2398     <refmeta>
2399       <refentrytitle>SET-SEQUENCE-POSITION</refentrytitle>
2400     </refmeta>
2401     <refnamediv>
2402       <refname><emphasis>Function</emphasis> <emphasis role="bold">SET-SEQUENCE-POSITION</emphasis></refname>
2403       <refpurpose>Sets the position of a database sequence.</refpurpose>
2404       <refclass>Function</refclass>
2405     </refnamediv>
2406     <refsect1>
2407       <title>Syntax</title>
2408       <synopsis>
2409       <function>set-sequence-position</function> <replaceable>name</replaceable> <replaceable>position</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
2410     </refsect1>
2411     <refsect1>
2412       <title>Arguments and Values</title>
2413       <variablelist>
2414         <varlistentry>
2415           <term><parameter>name</parameter></term>
2416           <listitem>
2417             <para>
2418               The name of the sequence as a string, symbol or SQL expression.
2419             </para>
2420           </listitem>
2421         </varlistentry>
2422         <varlistentry>
2423           <term><parameter>position</parameter></term>
2424           <listitem>
2425             <para>
2426               An integer.
2427             </para>
2428           </listitem>
2429         </varlistentry>
2430         <varlistentry>
2431           <term><parameter>database</parameter></term>
2432           <listitem>
2433             <para>
2434               A database object which defaults to
2435               <symbol>*default-database*</symbol>.
2436             </para>
2437           </listitem>
2438         </varlistentry>
2439         <varlistentry>
2440           <term><parameter>result</parameter></term>
2441           <listitem>
2442             <para>
2443               An integer.
2444             </para>
2445           </listitem>
2446         </varlistentry>
2447       </variablelist>
2448     </refsect1>
2449     <refsect1>
2450       <title>Description</title>
2451       <para>Explicitly set the position of the sequence called
2452       <parameter>name</parameter> in <parameter>database</parameter>,
2453       which defaults to <symbol>*default-database*</symbol>, to
2454       <parameter>position</parameter> which is returned.
2455       </para>
2456     </refsect1>
2457     <refsect1>
2458       <title>Examples</title>
2459       <screen>
2460 (sequence-last [foo])
2461 => 4
2462 (set-sequence-position [foo] 50)
2463 => 50
2464 (sequence-next [foo])
2465 => 51
2466       </screen>
2467     </refsect1>
2468     <refsect1>
2469       <title>Side Effects</title>
2470       <para>
2471         Modifies the value of the sequence <parameter>name</parameter>
2472         in <parameter>database</parameter>.
2473       </para>
2474     </refsect1>
2475     <refsect1>
2476       <title>Affected by</title>
2477       <para>
2478         <symbol>*default-database*</symbol>
2479       </para>
2480     </refsect1>
2481     <refsect1>
2482       <title>Exceptional Situations</title>
2483       <para>
2484         Will signal an error of type
2485         <symbol>sql-database-data-error</symbol> if a sequence called
2486         <parameter>name</parameter> does not exist in
2487         <parameter>database</parameter>.
2488       </para>
2489     </refsect1>
2490     <refsect1>
2491       <title>See Also</title>
2492       <simplelist>
2493         <member><link linkend="create-sequence"><function>create-sequence</function></link></member>
2494         <member><link linkend="drop-sequence"><function>drop-sequence</function></link></member>
2495         <member><link linkend="list-sequences"><function>list-sequences</function></link></member>
2496         <member><link linkend="sequence-exists-p"><function>sequence-exists-p</function></link></member>
2497         <member><link linkend="sequence-last"><function>sequence-last</function></link></member>
2498         <member><link linkend="sequence-next"><function>sequence-next</function></link></member>
2499       </simplelist>
2500     </refsect1>
2501     <refsect1>
2502       <title>Notes</title>
2503       <para>
2504         <function>set-sequence-position</function> is a &clsql; extension.
2505       </para>
2506     </refsect1>
2507   </refentry>
2508
2509 </reference>