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