doc/ref-syntax.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 <!-- Symbolic SQL Syntax -->
   9 <reference id="ref-syntax">
  10   <title>The Symbolic SQL Syntax</title>
  11   <partintro>
  12     <para>
  13       &clsql; provides a symbolic syntax allowing the construction of
  14       SQL expressions as lists delimited by square brackets. The
  15       syntax is turned off by default. This section describes
  16       utilities for enabling and disabling the square bracket reader
  17       syntax and for constructing symbolic SQL expressions.
  18     </para>
  19   </partintro>
  20
  21   <refentry id="enable-sql-reader-syntax">
  22     <refmeta>
  23       <refentrytitle>ENABLE-SQL-READER-SYNTAX</refentrytitle>
  24     </refmeta>
  25     <refnamediv>
  26       <refname><emphasis>Macro</emphasis> <emphasis role="bold">ENABLE-SQL-READER-SYNTAX</emphasis></refname>
  27       <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
  28       <refclass>Macro</refclass>
  29     </refnamediv>
  30     <refsect1>
  31       <title>Syntax</title>
  32       <synopsis>
  33       <function>enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
  34     </refsect1>
  35     <refsect1>
  36       <title>Arguments and Values</title>
  37       <para>None.</para>
  38     </refsect1>
  39     <refsect1>
  40       <title>Description</title>
  41       <para>Turns on the SQL reader syntax setting the syntax state
  42       such that if the syntax is subsequently disabled, <link
  43       linkend="restore-sql-reader-syntax-state">
  44       <function>restore-sql-reader-syntax-state</function></link> will
  45       enable it again.
  46       </para>
  47     </refsect1>
  48     <refsect1>
  49       <title>Examples</title>
  50       <para>None.</para>
  51     </refsect1>
  52     <refsect1>
  53       <title>Side Effects</title>
  54       <para>
  55         Sets the internal syntax state to enabled.
  56       </para>
  57       <para>
  58         Modifies the default readtable.
  59       </para>
  60     </refsect1>
  61     <refsect1>
  62       <title>Affected by</title>
  63       <para>
  64         None.
  65       </para>
  66     </refsect1>
  67     <refsect1>
  68       <title>Exceptional Situations</title>
  69       <para>
  70         None.
  71       </para>
  72     </refsect1>
  73     <refsect1>
  74       <title>See Also</title>
  75       <simplelist>
  76         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
  77         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
  78         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
  79         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
  80       </simplelist>
  81     </refsect1>
  82     <refsect1>
  83       <title>Notes</title>
  84       <para>
  85         The symbolic SQL syntax is disabled by default.
  86       </para>
  87     </refsect1>
  88   </refentry>
  89
  90   <refentry id="disable-sql-reader-syntax">
  91     <refmeta>
  92       <refentrytitle>DISABLE-SQL-READER-SYNTAX</refentrytitle>
  93     </refmeta>
  94     <refnamediv>
  95       <refname><emphasis>Macro</emphasis> <emphasis role="bold">DISABLE-SQL-READER-SYNTAX</emphasis></refname>
  96       <refpurpose>Globally disable square bracket reader syntax.</refpurpose>
  97       <refclass>Macro</refclass>
  98     </refnamediv>
  99     <refsect1>
 100       <title>Syntax</title>
 101       <synopsis>
 102       <function>disable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 103     </refsect1>
 104     <refsect1>
 105       <title>Arguments and Values</title>
 106       <para>None.</para>
 107     </refsect1>
 108     <refsect1>
 109       <title>Description</title>
 110       <para>Turns off the SQL reader syntax setting the syntax state
 111       such that if the syntax is subsequently enabled,
 112       <link linkend="restore-sql-reader-syntax-state">
 113         <function>restore-sql-reader-syntax-state</function></link> will
 114         disable it again.
 115       </para>
 116     </refsect1>
 117     <refsect1>
 118       <title>Examples</title>
 119       <para>None.</para>
 120     </refsect1>
 121     <refsect1>
 122       <title>Side Effects</title>
 123       <para>
 124         Sets the internal syntax state to disabled.
 125       </para>
 126       <para>
 127         Modifies the default readtable.
 128       </para>
 129     </refsect1>
 130     <refsect1>
 131       <title>Affected by</title>
 132       <para>
 133         None.
 134       </para>
 135     </refsect1>
 136     <refsect1>
 137       <title>Exceptional Situations</title>
 138       <para>
 139         None.
 140       </para>
 141     </refsect1>
 142     <refsect1>
 143       <title>See Also</title>
 144       <simplelist>
 145         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 146         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 147         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 148         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 149       </simplelist>
 150     </refsect1>
 151     <refsect1>
 152       <title>Notes</title>
 153       <para>
 154         The symbolic SQL syntax is disabled by default.
 155       </para>
 156     </refsect1>
 157   </refentry>
 158
 159   <refentry id="locally-enable-sql-reader-syntax">
 160     <refmeta>
 161       <refentrytitle>LOCALLY-ENABLE-SQL-READER-SYNTAX</refentrytitle>
 162     </refmeta>
 163     <refnamediv>
 164       <refname><emphasis>Macro</emphasis> <emphasis role="bold">LOCALLY-ENABLE-SQL-READER-SYNTAX</emphasis></refname>
 165       <refpurpose>Globally enable square bracket reader syntax.</refpurpose>
 166       <refclass>Macro</refclass>
 167     </refnamediv>
 168     <refsect1>
 169       <title>Syntax</title>
 170       <synopsis>
 171       <function>locally-enable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 172     </refsect1>
 173     <refsect1>
 174       <title>Arguments and Values</title>
 175       <para>None.</para>
 176     </refsect1>
 177     <refsect1>
 178       <title>Description</title>
 179       <para>Turns on the SQL reader syntax without changing the syntax
 180       state such that <link linkend="restore-sql-reader-syntax-state">
 181       <function>restore-sql-reader-syntax-state</function></link> will
 182       re-establish the current syntax state.
 183       </para>
 184     </refsect1>
 185     <refsect1>
 186       <title>Examples</title>
 187       <para>Intended to be used in a file for code which uses the
 188       square bracket syntax without changing the global state.
 189       </para>
 190       <screen>
 191         #.(locally-enable-sql-reader-syntax)
 192
 193         ... CODE USING SYMBOLIC SQL SYNTAX ...
 194
 195         #.(restore-sql-reader-syntax-state)
 196       </screen>
 197     </refsect1>
 198     <refsect1>
 199       <title>Side Effects</title>
 200       <para>
 201         Modifies the default readtable.
 202       </para>
 203     </refsect1>
 204     <refsect1>
 205       <title>Affected by</title>
 206       <para>None.</para>
 207     </refsect1>
 208     <refsect1>
 209       <title>Exceptional Situations</title>
 210       <para>
 211         None.
 212       </para>
 213     </refsect1>
 214     <refsect1>
 215       <title>See Also</title>
 216       <simplelist>
 217         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 218         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 219         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 220         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 221       </simplelist>
 222     </refsect1>
 223     <refsect1>
 224       <title>Notes</title>
 225       <para>
 226         The symbolic SQL syntax is disabled by default.
 227       </para>
 228     </refsect1>
 229   </refentry>
 230
 231
 232   <refentry id="locally-disable-sql-reader-syntax">
 233     <refmeta>
 234       <refentrytitle>LOCALLY-DISABLE-SQL-READER-SYNTAX</refentrytitle>
 235     </refmeta>
 236     <refnamediv>
 237       <refname><emphasis>Macro</emphasis> <emphasis role="bold">LOCALLY-DISABLE-SQL-READER-SYNTAX</emphasis></refname>
 238       <refpurpose>Locally disable square bracket reader syntax.</refpurpose>
 239       <refclass>Macro</refclass>
 240     </refnamediv>
 241     <refsect1>
 242       <title>Syntax</title>
 243       <synopsis>
 244       <function>locally-disable-sql-reader-syntax</function> => <returnvalue></returnvalue></synopsis>
 245     </refsect1>
 246     <refsect1>
 247       <title>Arguments and Values</title>
 248       <para>None.</para>
 249     </refsect1>
 250     <refsect1>
 251       <title>Description</title>
 252       <para>Turns off the SQL reader syntax without changing the
 253       syntax state such that <link
 254       linkend="restore-sql-reader-syntax-state">
 255       <function>restore-sql-reader-syntax-state</function></link> will
 256       re-establish the current syntax state.
 257       </para>
 258     </refsect1>
 259     <refsect1>
 260       <title>Examples</title>
 261       <para>Intended to be used in a file for code in which the square
 262       bracket syntax should be disabled without changing the global
 263       state.
 264       </para>
 265       <screen>
 266         #.(locally-disable-sql-reader-syntax)
 267
 268         ... CODE NOT USING SYMBOLIC SQL SYNTAX ...
 269
 270         #.(restore-sql-reader-syntax-state)
 271       </screen>
 272     </refsect1>
 273     <refsect1>
 274       <title>Side Effects</title>
 275       <para>
 276         Modifies the default readtable.
 277       </para>
 278     </refsect1>
 279     <refsect1>
 280       <title>Affected by</title>
 281       <para>
 282         None.
 283       </para>
 284     </refsect1>
 285     <refsect1>
 286       <title>Exceptional Situations</title>
 287       <para>
 288         None.
 289       </para>
 290     </refsect1>
 291     <refsect1>
 292       <title>See Also</title>
 293       <simplelist>
 294         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 295         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 296         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 297         <member><link linkend="restore-sql-reader-syntax-state"><function>restore-sql-reader-syntax-state</function></link></member>
 298       </simplelist>
 299     </refsect1>
 300     <refsect1>
 301       <title>Notes</title>
 302       <para>
 303         The symbolic SQL syntax is disabled by default.
 304       </para>
 305     </refsect1>
 306   </refentry>
 307
 308   <refentry id="restore-sql-reader-syntax-state">
 309     <refmeta>
 310       <refentrytitle>RESTORE-SQL-READER-SYNTAX-STATE</refentrytitle>
 311     </refmeta>
 312     <refnamediv>
 313       <refname><emphasis>Macro</emphasis> <emphasis role="bold">RESTORE-SQL-READER-SYNTAX-STATE</emphasis></refname>
 314       <refpurpose>
 315         Restore square bracket reader syntax to its previous state.
 316       </refpurpose>
 317       <refclass>Macro</refclass>
 318     </refnamediv>
 319     <refsect1>
 320       <title>Syntax</title>
 321       <synopsis>
 322       <function>restore-sql-reader-syntax-state</function> => <returnvalue></returnvalue></synopsis>
 323     </refsect1>
 324     <refsect1>
 325       <title>Arguments and Values</title>
 326       <para>None.</para>
 327     </refsect1>
 328     <refsect1>
 329       <title>Description</title>
 330       <para>Enables the SQL reader syntax if <link
 331       linkend="enable-sql-reader-syntax">
 332       <function>enable-sql-reader-syntax</function></link> has been
 333       called more recently than <link
 334       linkend="disable-sql-reader-syntax">
 335       <function>disable-sql-reader-syntax</function></link> and
 336       otherwise disables the SQL reader syntax. By default, the SQL
 337       reader syntax is disabled.
 338       </para>
 339     </refsect1>
 340     <refsect1>
 341       <title>Examples</title>
 342       <para>
 343         See <link
 344         linkend="locally-enable-sql-reader-syntax">
 345         <function>locally-enable-sql-reader-syntax</function></link> and
 346         <link
 347          linkend="locally-disable-sql-reader-syntax">
 348           <function>locally-disable-sql-reader-syntax</function></link>.
 349       </para>
 350     </refsect1>
 351     <refsect1>
 352       <title>Side Effects</title>
 353       <para>
 354         Reverts the internal syntax state.
 355       </para>
 356       <para>
 357         Modifies the default readtable.
 358       </para>
 359     </refsect1>
 360     <refsect1>
 361       <title>Affected by</title>
 362       <para>The current internal syntax state.</para>
 363     </refsect1>
 364     <refsect1>
 365       <title>Exceptional Situations</title>
 366       <para>
 367         None.
 368       </para>
 369     </refsect1>
 370     <refsect1>
 371       <title>See Also</title>
 372       <simplelist>
 373         <member><link linkend="enable-sql-reader-syntax"><function>enable-sql-reader-syntax</function></link></member>
 374         <member><link linkend="disable-sql-reader-syntax"><function>disable-sql-reader-syntax</function></link></member>
 375         <member><link linkend="locally-enable-sql-reader-syntax"><function>locally-enable-sql-reader-syntax</function></link></member>
 376         <member><link linkend="locally-disable-sql-reader-syntax"><function>locally-disable-sql-reader-syntax</function></link></member>
 377       </simplelist>
 378     </refsect1>
 379     <refsect1>
 380       <title>Notes</title>
 381       <para>
 382         The symbolic SQL syntax is disabled by default.
 383       </para>
 384     </refsect1>
 385   </refentry>
 386
 387   <refentry id="sql">
 388     <refmeta>
 389       <refentrytitle>SQL</refentrytitle>
 390     </refmeta>
 391     <refnamediv>
 392       <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL</emphasis></refname>
 393       <refpurpose>Construct an SQL string from supplied expressions.</refpurpose>
 394       <refclass>Function</refclass>
 395     </refnamediv>
 396     <refsect1>
 397       <title>Syntax</title>
 398       <synopsis>
 399       <function>sql &amp;rest</function> <replaceable>args</replaceable> => <returnvalue>sql-expression</returnvalue></synopsis>
 400     </refsect1>
 401     <refsect1>
 402       <title>Arguments and Values</title>
 403       <variablelist>
 404         <varlistentry>
 405           <term><parameter>args</parameter></term>
 406           <listitem>
 407             <para>A set of expressions.</para>
 408           </listitem>
 409         </varlistentry>
 410         <varlistentry>
 411           <term><returnvalue>sql-expression</returnvalue></term>
 412           <listitem>
 413             <para>A string representing an SQL expression.</para>
 414           </listitem>
 415         </varlistentry>
 416       </variablelist>
 417     </refsect1>
 418     <refsect1>
 419       <title>Description</title>
 420       <para>Returns an SQL string generated from the expressions
 421       <parameter>args</parameter>. The expressions are translated into
 422       SQL strings and then concatenated with a single space delimiting
 423       each expression.
 424       </para>
 425     </refsect1>
 426     <refsect1>
 427       <title>Examples</title>
 428       <screen>
 429 (sql nil)
 430 => "NULL"
 431
 432 (sql 'foo)
 433 => "FOO"
 434
 435 (sql "bar")
 436  => "'bar'"
 437
 438 (sql 10)
 439 => "10"
 440
 441 (sql '(nil foo "bar" 10))
 442 => "(NULL,FOO,'bar',10)"
 443
 444 (sql #(nil foo "bar" 10))
 445 => "NULL,FOO,'bar',10"
 446
 447 (sql [select [foo] [bar] :from [baz]] 'having [= [foo id] [bar id]]
 448      'and [foo val] '&lt; 5)
 449 => "SELECT FOO,BAR FROM BAZ HAVING (FOO.ID = BAR.ID) AND FOO.VAL &lt; 5"
 450       </screen>
 451     </refsect1>
 452     <refsect1>
 453       <title>Side Effects</title>
 454       <para>None.</para>
 455     </refsect1>
 456     <refsect1>
 457       <title>Affected by</title>
 458       <para>
 459         None.
 460       </para>
 461     </refsect1>
 462     <refsect1>
 463       <title>Exceptional Situations</title>
 464       <para>An error of type <link
 465       linkend="sql-user-error"><function>sql-user-error</function></link>
 466       is signalled if any element in <parameter>args</parameter> is
 467       not of the supported types (a symbol, string, number or symbolic
 468       SQL expression) or a list or vector containing only these
 469       supported types.
 470       </para>
 471     </refsect1>
 472     <refsect1>
 473       <title>See Also</title>
 474       <simplelist>
 475         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 476         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 477         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 478       </simplelist>
 479     </refsect1>
 480     <refsect1>
 481       <title>Notes</title>
 482       <para>None.</para>
 483     </refsect1>
 484   </refentry>
 485
 486   <refentry id="sql-expression">
 487     <refmeta>
 488       <refentrytitle>SQL-EXPRESSION</refentrytitle>
 489     </refmeta>
 490     <refnamediv>
 491       <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-EXPRESSION</emphasis></refname>
 492       <refpurpose>Constructs an SQL expression from supplied keyword arguments.</refpurpose>
 493       <refclass>Function</refclass>
 494     </refnamediv>
 495     <refsect1>
 496       <title>Syntax</title>
 497       <synopsis>
 498       <function>sql-expression &amp;key</function> <parameter>string</parameter> <parameter>table</parameter> <parameter>alias</parameter> <parameter>attribute</parameter> <parameter>type</parameter> => <returnvalue>result</returnvalue></synopsis>
 499     </refsect1>
 500     <refsect1>
 501       <title>Arguments and Values</title>
 502       <variablelist>
 503         <varlistentry>
 504           <term><parameter>string</parameter></term>
 505           <listitem>
 506             <para>A string.</para>
 507           </listitem>
 508         </varlistentry>
 509         <varlistentry>
 510           <term><parameter>table</parameter></term>
 511           <listitem>
 512             <para>A symbol representing a database table identifier.</para>
 513           </listitem>
 514         </varlistentry>
 515         <varlistentry>
 516           <term><parameter>alias</parameter></term>
 517           <listitem>
 518             <para>A table alias.</para>
 519           </listitem>
 520         </varlistentry>
 521         <varlistentry>
 522           <term><parameter>attribute</parameter></term>
 523           <listitem>
 524             <para>A symbol representing an attribute identifier.</para>
 525           </listitem>
 526         </varlistentry>
 527         <varlistentry>
 528           <term><parameter>type</parameter></term>
 529           <listitem>
 530             <para>A type specifier.</para>
 531           </listitem>
 532         </varlistentry>
 533         <varlistentry>
 534           <term><returnvalue>result</returnvalue></term>
 535           <listitem>
 536             <para>A object of type <type>sql-expression</type>.</para>
 537           </listitem>
 538         </varlistentry>
 539       </variablelist>
 540     </refsect1>
 541     <refsect1>
 542       <title>Description</title>
 543       <para>Returns an SQL expression constructed from the supplied
 544       arguments which may be combined as follows:</para>
 545       <itemizedlist mark='opencircle'>
 546         <listitem>
 547           <para>
 548             <parameter>attribute</parameter> and
 549             <parameter>type</parameter>;
 550           </para>
 551         </listitem>
 552         <listitem>
 553           <para>
 554             <parameter>attribute</parameter>;
 555           </para>
 556         </listitem>
 557         <listitem>
 558           <para>
 559             <parameter>alias</parameter> or <parameter>table</parameter> and
 560             <parameter>attribute</parameter> and
 561             <parameter>type</parameter>;
 562           </para>
 563         </listitem>
 564         <listitem>
 565           <para>
 566             <parameter>alias</parameter> or
 567             <parameter>table</parameter> and
 568             <parameter>attribute</parameter>;
 569           </para>
 570         </listitem>
 571         <listitem>
 572           <para>
 573             <parameter>table</parameter>,
 574             <parameter>attribute</parameter> and
 575             <parameter>type</parameter>;
 576           </para>
 577         </listitem>
 578         <listitem>
 579           <para>
 580             <parameter>table</parameter> and
 581             <parameter>attribute</parameter>;
 582           </para>
 583         </listitem>
 584         <listitem>
 585           <para>
 586             <parameter>table</parameter>
 587             and <parameter>alias</parameter>;
 588           </para>
 589         </listitem>
 590         <listitem>
 591           <para>
 592             <parameter>table</parameter>;
 593           </para>
 594         </listitem>
 595         <listitem>
 596           <para>
 597             <parameter>string</parameter>.
 598           </para>
 599         </listitem>
 600       </itemizedlist>
 601     </refsect1>
 602     <refsect1>
 603       <title>Examples</title>
 604       <screen>
 605 (sql-expression :table 'foo :attribute 'bar)
 606 => #&lt;CLSQL-SYS:SQL-IDENT-ATTRIBUTE FOO.BAR>
 607
 608 (sql-expression :attribute 'baz)
 609 => #&lt;CLSQL-SYS:SQL-IDENT-ATTRIBUTE BAZ>
 610       </screen>
 611     </refsect1>
 612     <refsect1>
 613       <title>Side Effects</title>
 614       <para>None.</para>
 615     </refsect1>
 616     <refsect1>
 617       <title>Affected by</title>
 618       <para>
 619         None.
 620       </para>
 621     </refsect1>
 622     <refsect1>
 623       <title>Exceptional Situations</title>
 624       <para>An error of type <link
 625       linkend="sql-user-error"><function>sql-user-error</function></link>
 626       is signalled if an unsupported combination of keyword arguments is
 627       specified.
 628       </para>
 629     </refsect1>
 630     <refsect1>
 631       <title>See Also</title>
 632       <simplelist>
 633         <member><link linkend="sql"><function>sql</function></link></member>
 634         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 635         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 636         </simplelist>
 637     </refsect1>
 638     <refsect1>
 639       <title>Notes</title>
 640       <para>None.</para>
 641     </refsect1>
 642   </refentry>
 643
 644   <refentry id="sql-operation">
 645     <refmeta>
 646       <refentrytitle>SQL-OPERATION</refentrytitle>
 647     </refmeta>
 648     <refnamediv>
 649       <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-OPERATION</emphasis></refname>
 650       <refpurpose>Constructs an SQL expression from a supplied operator and arguments.</refpurpose>
 651       <refclass>Function</refclass>
 652     </refnamediv>
 653     <refsect1>
 654       <title>Syntax</title>
 655       <synopsis>
 656       <function>sql-operation</function> <parameter>operator</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
 657       <synopsis>
 658       <function>sql-operation</function> 'function <parameter>func</parameter> <function>&amp;rest</function> <parameter>args</parameter> => <returnvalue>result</returnvalue></synopsis>
 659     </refsect1>
 660     <refsect1>
 661       <title>Arguments and Values</title>
 662       <variablelist>
 663         <varlistentry>
 664           <term><parameter>operator</parameter></term>
 665           <listitem>
 666             <para>A symbol denoting an SQL operator.</para>
 667           </listitem>
 668         </varlistentry>
 669         <varlistentry>
 670           <term><parameter>func</parameter></term>
 671           <listitem>
 672             <para>A string denoting an SQL function.</para>
 673           </listitem>
 674         </varlistentry>
 675         <varlistentry>
 676           <term><parameter>args</parameter></term>
 677           <listitem>
 678             <para>A set of arguments for the specified SQL operator or function.</para>
 679           </listitem>
 680         </varlistentry>
 681         <varlistentry>
 682           <term><returnvalue>result</returnvalue></term>
 683           <listitem>
 684             <para>A object of type <function>sql-expression</function>.</para>
 685           </listitem>
 686         </varlistentry>
 687       </variablelist>
 688     </refsect1>
 689     <refsect1>
 690       <title>Description</title>
 691       <para>Returns an SQL expression constructed from the supplied
 692       SQL operator or function <parameter>operator</parameter> and
 693       its arguments <parameter>args</parameter>. If
 694       <parameter>operator</parameter> is passed the symbol 'function
 695       then the first value in <parameter>args</parameter> is taken to
 696       be a valid SQL function and the remaining values in
 697       <parameter>args</parameter> its arguments.
 698       </para>
 699     </refsect1>
 700     <refsect1>
 701       <title>Examples</title>
 702       <screen>
 703 (sql-operation 'select
 704           (sql-expression :table 'foo :attribute 'bar)
 705           (sql-operation 'sum  (sql-expression :table 'foo :attribute 'baz))
 706           :from
 707           (sql-expression :table 'foo)
 708           :where
 709           (sql-operation '> (sql-expression :attribute 'bar) 12)
 710           :order-by (sql-operation 'sum (sql-expression :attribute 'baz)))
 711 => #&lt;SQL-QUERY SELECT FOO.BAR,SUM(FOO.BAZ) FROM FOO WHERE (BAR > 12) ORDER BY SUM(BAZ)>
 712
 713 (sql-operation 'function "strpos" "CLSQL" "SQL")
 714 => #&lt;CLSQL-SYS:SQL-FUNCTION-EXP STRPOS('CLSQL','SQL')>
 715       </screen>
 716     </refsect1>
 717     <refsect1>
 718       <title>Side Effects</title>
 719       <para>None.</para>
 720     </refsect1>
 721     <refsect1>
 722       <title>Affected by</title>
 723       <para>
 724         None.
 725       </para>
 726     </refsect1>
 727     <refsect1>
 728       <title>Exceptional Situations</title>
 729       <para>An error of type <link
 730       linkend="sql-user-error"><function>sql-user-error</function></link>
 731       is signalled if <parameter>operator</parameter> is not a symbol
 732       representing a supported SQL operator.</para>
 733     </refsect1>
 734     <refsect1>
 735       <title>See Also</title>
 736       <simplelist>
 737         <member><link linkend="sql"><function>sql</function></link></member>
 738         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 739         <member><link linkend="sql-operator"><function>sql-operator</function></link></member>
 740       </simplelist>
 741     </refsect1>
 742     <refsect1>
 743       <title>Notes</title>
 744       <para>None.</para>
 745     </refsect1>
 746   </refentry>
 747
 748   <refentry id="sql-operator">
 749     <refmeta>
 750       <refentrytitle>SQL-OPERATOR</refentrytitle>
 751     </refmeta>
 752     <refnamediv>
 753       <refname><emphasis>Function</emphasis> <emphasis role="bold">SQL-OPERATOR</emphasis></refname>
 754       <refpurpose>Returns the symbol for the supplied SQL operator.</refpurpose>
 755       <refclass>Function</refclass>
 756     </refnamediv>
 757     <refsect1>
 758       <title>Syntax</title>
 759       <synopsis>
 760       <function>sql-operator</function> <parameter>operator</parameter> => <returnvalue>result</returnvalue></synopsis>
 761     </refsect1>
 762     <refsect1>
 763       <title>Arguments and Values</title>
 764       <variablelist>
 765         <varlistentry>
 766           <term><parameter>operator</parameter></term>
 767           <listitem>
 768             <para>A symbol denoting an SQL operator.</para>
 769           </listitem>
 770         </varlistentry>
 771         <varlistentry>
 772           <term><returnvalue>result</returnvalue></term>
 773           <listitem>
 774             <para>The Lisp symbol used by &clsql; to represent the
 775             specified operator.</para>
 776           </listitem>
 777         </varlistentry>
 778       </variablelist>
 779     </refsect1>
 780     <refsect1>
 781       <title>Description</title>
 782       <para>Returns the Lisp symbol corresponding to the SQL operator
 783       represented by the symbol <parameter>operator</parameter>. If
 784       <parameter>operator</parameter> does not represent a supported
 785       SQL operator or is not a symbol, nil is returned.
 786       </para>
 787     </refsect1>
 788     <refsect1>
 789       <title>Examples</title>
 790       <screen>
 791 (sql-operator 'like)
 792 => SQL-LIKE
 793       </screen>
 794     </refsect1>
 795     <refsect1>
 796       <title>Side Effects</title>
 797       <para>None.</para>
 798     </refsect1>
 799     <refsect1>
 800       <title>Affected by</title>
 801       <para>
 802         None.
 803       </para>
 804     </refsect1>
 805     <refsect1>
 806       <title>Exceptional Situations</title>
 807       <para>None.</para>
 808     </refsect1>
 809     <refsect1>
 810       <title>See Also</title>
 811       <simplelist>
 812         <member><link linkend="sql"><function>sql</function></link></member>
 813         <member><link linkend="sql-expression"><function>sql-expression</function></link></member>
 814         <member><link linkend="sql-operation"><function>sql-operation</function></link></member>
 815       </simplelist>
 816     </refsect1>
 817     <refsect1>
 818       <title>Notes</title>
 819       <para>&clsql;'s symbolic SQL syntax currently has support for
 820       the following SQL operators:
 821       </para>
 822       <simplelist>
 823         <!-- CommonSQL Compatible -->
 824         <member><function>any
 825         </function></member>,
 826         <member><function>some
 827         </function></member>,
 828         <member><function>all
 829         </function></member>,
 830         <member><function>not
 831         </function></member>,
 832         <member><function>union
 833         </function></member>,
 834         <member><function>intersect
 835         </function></member>,
 836         <member><function>minus
 837         </function></member>,
 838         <member><function>except
 839         </function></member>,
 840         <member><function>order-by
 841         </function></member>,
 842         <member><function>null
 843         </function></member>,
 844         <member><function>*
 845         </function></member>,
 846         <member><function>+
 847         </function></member>,
 848         <member><function>/
 849         </function></member>,
 850         <member><function>-
 851         </function></member>,
 852         <member><function>like
 853         </function></member>,
 854         <member><function>and
 855         </function></member>,
 856         <member><function>or
 857         </function></member>,
 858         <member><function>in
 859         </function></member>,
 860         <member><function>substr
 861         </function></member>,
 862         <member><function>||
 863         </function></member>,
 864         <member><function>=
 865         </function></member>,
 866         <member><function>&lt;
 867         </function></member>,
 868         <member><function>>
 869         </function></member>,
 870         <member><function>>=
 871         </function></member>,
 872         <member><function>&lt;=
 873         </function></member>,
 874         <member><function>&lt;>
 875         </function></member>,
 876         <member><function>count
 877         </function></member>,
 878         <member><function>max
 879         </function></member>,
 880         <member><function>min
 881         </function></member>,
 882         <member><function>avg
 883         </function></member>,
 884         <member><function>sum
 885         </function></member>,
 886         <member><function>function
 887         </function></member>,
 888         <member><function>between
 889         </function></member>,
 890         <member><function>distinct
 891         </function></member>,
 892         <member><function>nvl
 893         </function></member>,
 894         <member><function>slot-value
 895         </function></member>,
 896         <member><function>userenv
 897         <!-- CLSQL Extensions -->
 898         </function></member>,
 899         <member><function>concat
 900         </function></member>,
 901         <member><function>substring
 902         </function></member>,
 903         <member><function>limit
 904         </function></member>,
 905         <member><function>group-by
 906         </function></member>,
 907         <member><function>having
 908         </function></member>,
 909         <member><function>not-null
 910         </function></member>,
 911         <member><function>exists
 912         </function></member>,
 913         <member><function>uplike
 914         </function></member>,
 915         <member><function>is
 916         </function></member>,
 917         <member><function>==
 918         </function></member>,
 919         <member><function>the
 920         </function></member>,
 921         <member><function>coalesce
 922         </function></member>,
 923         <member><function>view-class
 924         </function></member>
 925       </simplelist>
 926       <para>as well as the pseudo-operator
 927       <function>function</function>. Note that some of these operators
 928       are not supported by all of the RDBMS supported by
 929       &clsql;.</para>
 930     </refsect1>
 931   </refentry>
 932
 933 </reference>