doc/ref-fdml.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 Manipulation Language -->
   9 <reference id="ref-fdml">
  10   <title>Functional Data Manipulation Language (FDML)</title>
  11   <partintro>
  12     <para>
  13       The functional data manipulation interface provided by &clsql;
  14       includes functions for inserting, updating and deleting records
  15       in existing database tables and executing SQL queries and
  16       statements with the results of queries returned as Lisp types.
  17       SQL statements expressed as strings may be executed with the
  18       <link linkend="query"><function>query</function></link> and
  19       <link
  20       linkend="execute-command"><function>execute-command</function></link>
  21       functions. The <link
  22       linkend="select"><function>select</function></link> function, on
  23       the other hand, allows for the construction of queries in Lisp
  24       using the symbolic SQL syntax. Finally, iterative manipulation
  25       of query results is supported by <link
  26       linkend="do-query"><function>do-query</function></link>, <link
  27       linkend="map-query"><function>map-query</function></link> and an
  28       extended clause for the <link
  29       linkend="loop-tuples"><function>loop</function></link> macro.
  30     </para>
  31   </partintro>
  32
  33   <!-- Caching table queries -->
  34
  35   <refentry id="cache-table-queries-default">
  36     <refmeta>
  37       <refentrytitle>*CACHE-TABLE-QUERIES-DEFAULT*</refentrytitle>
  38     </refmeta>
  39     <refnamediv>
  40       <refname>*CACHE-TABLE-QUERIES-DEFAULT*</refname>
  41       <refpurpose>Specifies the default behaviour for caching of
  42       attribute types.</refpurpose>
  43       <refclass>Variable</refclass>
  44     </refnamediv>
  45     <refsect1>
  46       <title>Value Type</title>
  47       <para>
  48         A valid argument to the <parameter>action</parameter>
  49         parameter of <function>cache-table-queries</function>,
  50         i.e. one of
  51         <simplelist type="inline">
  52         <member>&t;</member>
  53         <member>&nil;</member>
  54         <member><symbol>:flush</symbol></member>
  55         </simplelist>.
  56       </para>
  57     </refsect1>
  58     <refsect1>
  59       <title>Initial Value</title>
  60       <para><symbol>nil</symbol></para>
  61     </refsect1>
  62     <refsect1>
  63       <title>Description</title>
  64       <para>
  65         Specifies the default behaivour for caching of attribute
  66         types. Meaningful values are &t;, &nil; and
  67         <symbol>:flush</symbol> as described for the
  68         <parameter>action</parameter> argument to
  69         <function>cache-table-queries</function>.
  70       </para>
  71     </refsect1>
  72     <refsect1>
  73       <title>Examples</title>
  74       <para>None.</para>
  75     </refsect1>
  76     <refsect1>
  77       <title>Affected By</title>
  78       <para>None.</para>
  79     </refsect1>
  80     <refsect1>
  81       <title>See Also</title>
  82       <simplelist>
  83         <member><link linkend="cache-table-queries"><function>cache-table-queries</function></link></member>
  84       </simplelist>
  85     </refsect1>
  86     <refsect1>
  87       <title>Notes</title>
  88       <para>None.</para>
  89     </refsect1>
  90   </refentry>
  91
  92   <refentry id="cache-table-queries">
  93     <refmeta>
  94       <refentrytitle>CACHE-TABLE-QUERIES</refentrytitle>
  95     </refmeta>
  96     <refnamediv>
  97       <refname>CACHE-TABLE-QUERIES</refname>
  98       <refpurpose>Control the caching of table attribute types.</refpurpose>
  99     </refnamediv>
 100   </refentry>
 101
 102   <refentry id="insert-records">
 103     <refmeta>
 104       <refentrytitle>INSERT-RECORDS</refentrytitle>
 105     </refmeta>
 106     <refnamediv>
 107       <refname>INSERT-RECORDS</refname>
 108       <refpurpose>Insert tuples of data into a database table.</refpurpose>
 109       <refclass>Function</refclass>
 110     </refnamediv>
 111     <refsect1>
 112       <title>Syntax</title>
 113       <synopsis>
 114       <function>insert-records</function> &amp;key <replaceable>into</replaceable> <replaceable>attributes</replaceable> <replaceable>values</replaceable> <replaceable>av-pairs</replaceable> <replaceable>query</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 115     </refsect1>
 116     <refsect1>
 117       <title>Arguments and Values</title>
 118       <variablelist>
 119         <varlistentry>
 120           <term><parameter>into</parameter></term>
 121           <listitem>
 122             <para>
 123               A string, symbol or symbolic SQL expression representing
 124               the name of a table existing in
 125               <parameter>database</parameter>.
 126             </para>
 127           </listitem>
 128         </varlistentry>
 129         <varlistentry>
 130           <term><parameter>attributes</parameter></term>
 131           <listitem>
 132             <para>
 133               A list of attribute identifiers or &nil;.
 134             </para>
 135           </listitem>
 136         </varlistentry>
 137         <varlistentry>
 138           <term><parameter>values</parameter></term>
 139           <listitem>
 140             <para>
 141               A list of attribute values or &nil;.
 142             </para>
 143           </listitem>
 144         </varlistentry>
 145         <varlistentry>
 146           <term><parameter>av-pairs</parameter></term>
 147           <listitem>
 148             <para>
 149               A list of attribute identifier/value pairs or &nil;.
 150             </para>
 151           </listitem>
 152         </varlistentry>
 153         <varlistentry>
 154           <term><parameter>query</parameter></term>
 155           <listitem>
 156             <para>
 157               A query expression or &nil;.
 158             </para>
 159           </listitem>
 160         </varlistentry>
 161         <varlistentry>
 162           <term><parameter>database</parameter></term>
 163           <listitem>
 164             <para>A
 165             <glossterm linkend="gloss-database-object">database
 166             object</glossterm>. This will default to the value
 167             of <symbol>*default-database*</symbol>.</para>
 168           </listitem>
 169       </varlistentry>
 170       </variablelist>
 171     </refsect1>
 172     <refsect1>
 173       <title>Description</title>
 174       <para>
 175         Inserts records into the table specified by
 176         <parameter>into</parameter> in <parameter>database</parameter>
 177         which defaults to <symbol>*default-database*</symbol>.
 178       </para>
 179       <para>
 180         There are five ways of specifying the values inserted into
 181         each row. In the first <parameter>values</parameter> contains
 182         a list of values to insert and
 183         <parameter>attributes</parameter>,
 184         <parameter>av-pairs</parameter> and
 185         <parameter>query</parameter> are &nil;. This can be used when
 186         values are supplied for all attributes in
 187         <parameter>into</parameter>. In the second,
 188         <parameter>attributes</parameter> is a list of column names,
 189         <parameter>values</parameter> is a corresponding list of
 190         values and <parameter>av-pairs</parameter> and
 191         <parameter>query</parameter> are &nil;. In the third,
 192         <parameter>attributes</parameter>,
 193         <parameter>values</parameter> and <parameter>query</parameter>
 194         are &nil; and <parameter>av-pairs</parameter> is an alist of
 195         (attribute value) pairs. In the fourth,
 196         <parameter>values</parameter>, <parameter>av-pairs</parameter>
 197         and <parameter>attributes</parameter> are &nil; and
 198         <parameter>query</parameter> is a symbolic SQL query
 199         expression in which the selected columns also exist in
 200         <parameter>into</parameter>. In the fifth method,
 201         <parameter>values</parameter> and
 202         <parameter>av-pairs</parameter> are nil and
 203         <parameter>attributes</parameter> is a list of column names
 204         and <parameter>query</parameter> is a symbolic SQL query
 205         expression which returns values for the specified columns.
 206       </para>
 207     </refsect1>
 208     <refsect1>
 209       <title>Examples</title>
 210       <screen>
 211 (select [first-name] [last-name] [email]
 212         :from [employee]
 213         :where [= [emplid] 11]
 214         :field-names nil)
 215 => NIL
 216 (insert-records :into [employee]
 217                 :attributes '(emplid groupid first_name last_name email
 218                               ecompanyid managerid)
 219                 :values '(11 1 "Yuri" "Gagarin" "gagarin@soviet.org"
 220                           1 1))
 221 =>
 222 (select [first-name] [last-name] [email]
 223         :from [employee]
 224         :where [= [emplid] 11]
 225         :field-names nil)
 226 => (("Yuri" "Gagarin" "gagarin@soviet.org"))
 227       </screen>
 228     </refsect1>
 229     <refsect1>
 230       <title>Side Effects</title>
 231       <para>
 232         Modifications are made to the underlying database.
 233       </para>
 234     </refsect1>
 235     <refsect1>
 236       <title>Affected by</title>
 237       <para>
 238         None.
 239       </para>
 240     </refsect1>
 241     <refsect1>
 242       <title>Exceptional Situations</title>
 243       <para>
 244         An error of type <symbol>sql-database-data-error</symbol> is
 245         signalled if <parameter>table</parameter> is not an existing
 246         table in <parameter>database</parameter> or if the specified
 247         attributes are not found.
 248       </para>
 249     </refsect1>
 250     <refsect1>
 251       <title>See Also</title>
 252       <simplelist>
 253         <member><link linkend="update-records"><function>update-records</function></link></member>
 254         <member><link linkend="delete-records"><function>delete-records</function></link></member>
 255       </simplelist>
 256     </refsect1>
 257     <refsect1>
 258       <title>Notes</title>
 259       <para>
 260         None.
 261       </para>
 262     </refsect1>
 263   </refentry>
 264
 265   <refentry id="update-records">
 266     <refmeta>
 267       <refentrytitle>UPDATE-RECORDS</refentrytitle>
 268     </refmeta>
 269     <refnamediv>
 270       <refname>UPDATE-RECORDS</refname>
 271       <refpurpose>Updates the values of existing records.</refpurpose>
 272       <refclass>Function</refclass>
 273     </refnamediv>
 274     <refsect1>
 275       <title>Syntax</title>
 276       <synopsis>
 277       <function>update-records</function> <replaceable>table</replaceable> &amp;key  <replaceable>attributes</replaceable> <replaceable>values</replaceable> <replaceable>av-pairs</replaceable> <replaceable>where</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 278     </refsect1>
 279     <refsect1>
 280       <title>Arguments and Values</title>
 281       <variablelist>
 282         <varlistentry>
 283           <term><parameter>table</parameter></term>
 284           <listitem>
 285             <para>
 286               A string, symbol or symbolic SQL expression representing
 287               the name of a table existing in
 288               <parameter>database</parameter>.
 289             </para>
 290           </listitem>
 291         </varlistentry>
 292         <varlistentry>
 293           <term><parameter>attributes</parameter></term>
 294           <listitem>
 295             <para>
 296               A list of attribute identifiers or &nil;.
 297             </para>
 298           </listitem>
 299         </varlistentry>
 300         <varlistentry>
 301           <term><parameter>values</parameter></term>
 302           <listitem>
 303             <para>
 304               A list of attribute values or &nil;.
 305             </para>
 306           </listitem>
 307         </varlistentry>
 308         <varlistentry>
 309           <term><parameter>av-pairs</parameter></term>
 310           <listitem>
 311             <para>
 312               A list of attribute identifier/value pairs or &nil;.
 313             </para>
 314           </listitem>
 315         </varlistentry>
 316         <varlistentry>
 317           <term><parameter>where</parameter></term>
 318           <listitem>
 319             <para>
 320               A symbolic SQL expression.
 321             </para>
 322           </listitem>
 323         </varlistentry>
 324         <varlistentry>
 325           <term><parameter>database</parameter></term>
 326           <listitem>
 327             <para>A
 328             <glossterm linkend="gloss-database-object">database
 329             object</glossterm>. This will default to the value
 330             of <symbol>*default-database*</symbol>.</para>
 331           </listitem>
 332       </varlistentry>
 333       </variablelist>
 334     </refsect1>
 335     <refsect1>
 336       <title>Description</title>
 337       <para>
 338         Updates the attribute values of existing records satsifying
 339         the SQL expression <parameter>where</parameter> in the table
 340         specified by <parameter>table</parameter> in
 341         <parameter>database</parameter> which defaults to
 342         <symbol>*default-database*</symbol>.
 343       </para>
 344       <para>
 345         There are three ways of specifying the values to update for
 346         each row. In the first, <parameter>values</parameter> contains
 347         a list of values to use in the update and
 348         <parameter>attributes</parameter> and
 349         <parameter>av-pairs</parameter> are &nil;. This can be used
 350         when values are supplied for all attributes in
 351         <parameter>table</parameter>. In the second,
 352         <parameter>attributes</parameter> is a list of column names,
 353         <parameter>values</parameter> is a corresponding list of
 354         values and <parameter>av-pairs</parameter> is &nil;. In the
 355         third, <parameter>attributes</parameter> and
 356         <parameter>values</parameter> are &nil; and
 357         <parameter>av-pairs</parameter> is an alist of (attribute
 358         value) pairs.
 359       </para>
 360     </refsect1>
 361     <refsect1>
 362       <title>Examples</title>
 363       <screen>
 364 (select [first-name] [last-name] [email]
 365         :from [employee]
 366         :where [= [emplid] 1]
 367         :field-names nil)
 368 => (("Vladamir" "Lenin" "lenin@soviet.org"))
 369 (update-records [employee]
 370                 :av-pairs'((first_name "Yuri")
 371                            (last_name "Gagarin")
 372                            (email "gagarin@soviet.org"))
 373                 :where [= [emplid] 1])
 374 =>
 375 (select [first-name] [last-name] [email]
 376         :from [employee]
 377         :where [= [emplid] 1]
 378         :field-names nil)
 379 => (("Yuri" "Gagarin" "gagarin@soviet.org"))
 380       </screen>
 381     </refsect1>
 382     <refsect1>
 383       <title>Side Effects</title>
 384       <para>
 385         Modifications are made to the underlying database.
 386       </para>
 387     </refsect1>
 388     <refsect1>
 389       <title>Affected by</title>
 390       <para>
 391         None.
 392       </para>
 393     </refsect1>
 394     <refsect1>
 395       <title>Exceptional Situations</title>
 396       <para>
 397         An error of type <symbol>sql-database-data-error</symbol> is
 398         signalled if <parameter>table</parameter> is not an existing
 399         table in <parameter>database</parameter>, if the specified
 400         attributes are not found or if the SQL statement resulting
 401         from the symbolic expression <parameter>where</parameter> does
 402         not return a Boolean value.
 403       </para>
 404       <para>If the execution of the SQL query leads to any errors, an
 405       error of type <errortype>sql-database-error</errortype> is
 406       signalled.</para>
 407     </refsect1>
 408     <refsect1>
 409       <title>See Also</title>
 410       <para>
 411         <simplelist>
 412           <member><link linkend="insert-records"><function>insert-records</function></link></member>
 413           <member><link linkend="delete-records"><function>delete-records</function></link></member>
 414         </simplelist>
 415       </para>
 416     </refsect1>
 417     <refsect1>
 418       <title>Notes</title>
 419       <para>
 420         None.
 421       </para>
 422     </refsect1>
 423   </refentry>
 424
 425   <refentry id="delete-records">
 426     <refmeta>
 427       <refentrytitle>DELETE-RECORDS</refentrytitle>
 428     </refmeta>
 429     <refnamediv>
 430       <refname>DELETE-RECORDS</refname>
 431       <refpurpose>Delete records from a database table.</refpurpose>
 432       <refclass>Function</refclass>
 433     </refnamediv>
 434     <refsect1>
 435       <title>Syntax</title>
 436       <synopsis>
 437       <function>delete-records</function> &amp;key <replaceable>from</replaceable> <replaceable>where</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 438     </refsect1>
 439     <refsect1>
 440       <title>Arguments and Values</title>
 441       <variablelist>
 442         <varlistentry>
 443           <term><parameter>from</parameter></term>
 444           <listitem>
 445             <para>
 446               A string, symbol or symbolic SQL expression representing
 447               the name of a table existing in
 448               <parameter>database</parameter>.
 449             </para>
 450           </listitem>
 451         </varlistentry>
 452                 <varlistentry>
 453           <term><parameter>where</parameter></term>
 454           <listitem>
 455             <para>
 456               A symbolic SQL expression.
 457             </para>
 458           </listitem>
 459         </varlistentry>
 460         <varlistentry>
 461           <term><parameter>database</parameter></term>
 462           <listitem>
 463             <para>A
 464             <glossterm linkend="gloss-database-object">database
 465             object</glossterm>. This will default to the value
 466             of <symbol>*default-database*</symbol>.</para>
 467           </listitem>
 468         </varlistentry>
 469       </variablelist>
 470     </refsect1>
 471     <refsect1>
 472       <title>Description</title>
 473       <para>Deletes records satisfying the SQL expression
 474       <parameter>where</parameter> from the table specified by
 475       <parameter>from</parameter> in <parameter>database</parameter>
 476       specifies a database which defaults to
 477       <symbol>*default-database*</symbol>.
 478       </para>
 479     </refsect1>
 480     <refsect1>
 481       <title>Examples</title>
 482       <screen>
 483 (select [first-name] [last-name] [email]
 484         :from [employee]
 485         :where [= [emplid] 11]
 486         :field-names nil)
 487 => (("Yuri" "Gagarin" "gagarin@soviet.org"))
 488 (delete-records :from [employee] :where [= [emplid] 11])
 489 =>
 490 (select [first-name] [last-name] [email]
 491         :from [employee]
 492         :where [= [emplid] 11]
 493         :field-names nil)
 494 => NIL
 495       </screen>
 496     </refsect1>
 497     <refsect1>
 498       <title>Side Effects</title>
 499       <para>
 500         Modifications are made to the underlying database.
 501       </para>
 502     </refsect1>
 503     <refsect1>
 504       <title>Affected by</title>
 505       <para>
 506         None.
 507       </para>
 508     </refsect1>
 509     <refsect1>
 510       <title>Exceptional Situations</title>
 511       <para>
 512         An error of type <symbol>sql-database-data-error</symbol> is
 513         signalled if <parameter>from</parameter> is not an existing
 514         table in <parameter>database</parameter> or if the SQL
 515         statement resulting from the symbolic expression
 516         <parameter>where</parameter> does not return a Boolean value.
 517       </para>
 518     </refsect1>
 519     <refsect1>
 520       <title>See Also</title>
 521       <para>
 522         <simplelist>
 523           <member><link linkend="insert-records"><function>insert-records</function></link></member>
 524           <member><link linkend="update-records"><function>update-records</function></link></member>
 525         </simplelist>
 526       </para>
 527     </refsect1>
 528     <refsect1>
 529       <title>Notes</title>
 530       <para>
 531         None.
 532       </para>
 533     </refsect1>
 534   </refentry>
 535
 536
 537   <!-- executing SQL commands and queries -->
 538
 539   <refentry id="execute-command">
 540     <refmeta>
 541       <refentrytitle>EXECUTE-COMMAND</refentrytitle>
 542     </refmeta>
 543     <refnamediv>
 544       <refname>EXECUTE-COMMAND</refname>
 545       <refpurpose>Execute an SQL command which returns no values.</refpurpose>
 546       <refclass>Generic Function</refclass>
 547     </refnamediv>
 548     <refsect1>
 549       <title>Syntax</title>
 550       <synopsis>
 551       <function>execute-command</function> <replaceable>sql-expression</replaceable> &amp;key <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 552     </refsect1>
 553     <refsect1>
 554       <title>Arguments and Values</title>
 555       <variablelist>
 556         <varlistentry>
 557           <term><parameter>sql-expression</parameter></term>
 558           <listitem>
 559             <para>An <glossterm linkend="gloss-sql-expression">sql
 560             expression</glossterm> that represents an SQL
 561             statement which will return no values.</para>
 562           </listitem>
 563         </varlistentry>
 564         <varlistentry>
 565           <term><parameter>database</parameter></term>
 566           <listitem>
 567             <para>A
 568             <glossterm linkend="gloss-database-object">database
 569             object</glossterm>. This will default to the value
 570             of <symbol>*default-database*</symbol>.</para>
 571           </listitem>
 572       </varlistentry></variablelist>
 573     </refsect1>
 574     <refsect1>
 575       <title>Description</title>
 576       <para>Executes the SQL command
 577       <parameter>sql-expression</parameter>, which may be a symbolic
 578       SQL expression or a string representing any SQL statement apart
 579       from a query, on the supplied <parameter>database</parameter>
 580       which defaults to <symbol>*default-database*</symbol>.
 581       </para>
 582     </refsect1>
 583     <refsect1>
 584       <title>Examples</title>
 585       <screen>
 586         (execute-command "create table eventlog (time char(30),event char(70))")
 587         =>
 588
 589         (execute-command "create table eventlog (time char(30),event char(70))")
 590         >>
 591         >> While accessing database #&lt;CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
 592         >>   with expression "create table eventlog (time char(30),event char(70))":
 593         >>   Error NIL: ERROR:  amcreate: eventlog relation already exists
 594         >>   has occurred.
 595         >>
 596         >> Restarts:
 597         >>   0: [ABORT] Return to Top-Level.
 598         >>
 599         >> Debug  (type H for help)
 600         >>
 601         >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
 602         >>  #&lt;unused-arg>
 603         >>  #&lt;unused-arg>
 604         >>  #&lt;unavailable-arg>
 605         >>  #&lt;unavailable-arg>)
 606         >> Source: (ERROR 'SQL-DATABASE-ERROR :DATABASE DATABASE :EXPRESSION ...)
 607         >> 0] 0
 608
 609         (execute-command "drop table eventlog")
 610         =>
 611       </screen>
 612     </refsect1>
 613     <refsect1>
 614       <title>Side Effects</title>
 615       <para>Whatever effects the execution of the SQL statement has
 616       on the underlying database, if any.</para>
 617     </refsect1>
 618     <refsect1>
 619       <title>Affected by</title>
 620       <para>None.</para>
 621     </refsect1>
 622     <refsect1>
 623       <title>Exceptional Situations</title>
 624       <para>If the execution of the SQL statement leads to any errors,
 625       an error of type <errortype>sql-database-error</errortype> is
 626       signalled.</para>
 627     </refsect1>
 628     <refsect1>
 629       <title>See Also</title>
 630       <para>
 631         <simplelist>
 632           <member><link linkend="query"><function>query</function></link></member>
 633         </simplelist>
 634       </para>
 635     </refsect1>
 636     <refsect1>
 637       <title>Notes</title>
 638       <para>None.</para>
 639     </refsect1>
 640   </refentry>
 641
 642
 643   <refentry id="query">
 644     <refmeta>
 645       <refentrytitle>QUERY</refentrytitle>
 646     </refmeta>
 647     <refnamediv>
 648       <refname>QUERY</refname>
 649       <refpurpose>Execute an SQL query and return the tuples as a
 650       list.</refpurpose>
 651       <refclass>Generic Function</refclass>
 652     </refnamediv>
 653     <refsect1>
 654       <title>Syntax</title>
 655       <synopsis>
 656       <function>query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> <replaceable>flatp</replaceable> <replaceable>field-names</replaceable> => <returnvalue>result</returnvalue></synopsis>
 657     </refsect1>
 658     <refsect1>
 659       <title>Arguments and Values</title>
 660       <variablelist>
 661         <varlistentry>
 662           <term><parameter>query-expression</parameter></term>
 663           <listitem>
 664             <para>An <glossterm linkend="gloss-sql-expression">sql
 665             expression</glossterm> that represents an SQL
 666             query which is expected to return a (possibly empty)
 667             result set.</para>
 668           </listitem>
 669         </varlistentry>
 670         <varlistentry>
 671           <term><parameter>database</parameter></term>
 672           <listitem>
 673             <para>A
 674             <glossterm linkend="gloss-database-object">database
 675             object</glossterm>. This will default to the value
 676             of <symbol>*default-database*</symbol>.</para>
 677           </listitem>
 678         </varlistentry>
 679         <varlistentry>
 680           <term><parameter>flatp</parameter></term>
 681           <listitem>
 682             <para>A Boolean whose default value is &nil;.</para>
 683           </listitem>
 684         </varlistentry>
 685         <varlistentry>
 686           <term><parameter>result-types</parameter></term>
 687           <listitem>
 688             <para>A
 689             <glossterm linkend="gloss-field-types">field type
 690             specifier</glossterm>. The default is &nil;.
 691             </para>
 692             <para>
 693               The purpose of this argument is cause &clsql; to
 694               import SQL numeric fields into numeric Lisp objects
 695               rather than strings. This reduces the cost of
 696               allocating a temporary string and the &clsql; users'
 697               inconvenience of converting number strings into number
 698               objects.
 699             </para>
 700             <para>
 701               A value of <symbol>:auto</symbol> causes &clsql;
 702               to automatically convert SQL fields into a
 703               numeric format where applicable. The default value of
 704               &nil; causes all fields to be returned as strings
 705               regardless of the SQL type. Otherwise a list is expected
 706               which has a element for each field that specifies the
 707               conversion. Valid type identifiers are:
 708               <simplelist type="vert">
 709                 <member><symbol>:int</symbol> Field is imported as a
 710                 signed integer, from 8-bits to 64-bits depending
 711                 upon the field type.
 712                 </member>
 713                 <member><symbol>:double</symbol> Field is imported as a
 714                 double-float number.
 715                 </member>
 716                 <member><symbol>t</symbol> Field is imported as a
 717                 string.
 718                 </member>
 719               </simplelist>
 720               If the list is shorter than the number of fields, the a
 721               value of <symbol>t</symbol> is assumed for the field.
 722               If the list is longer than the number of fields, the
 723               extra elements are ignored.
 724             </para>
 725           </listitem>
 726         </varlistentry>
 727         <varlistentry>
 728           <term><parameter>field-names</parameter></term>
 729           <listitem>
 730           <para>
 731             A boolean with a default value of &t;. When &t;, this
 732             function returns a second value of a list of field
 733             names. When &nil;, this function only returns one value -
 734             the list of rows.
 735           </para>
 736           </listitem>
 737         </varlistentry>
 738         <varlistentry>
 739           <term><returnvalue>result</returnvalue></term>
 740           <listitem>
 741             <para>A list representing the result set obtained.  For
 742             each tuple in the result set, there is an element in
 743             this list, which is itself a list of all the attribute
 744             values in the tuple.</para>
 745           </listitem>
 746         </varlistentry>
 747       </variablelist>
 748     </refsect1>
 749     <refsect1>
 750       <title>Description</title>
 751       <para>
 752         Executes the SQL query expression
 753         <parameter>query-expression</parameter>, which may be an SQL
 754         expression or a string, on the supplied
 755         <parameter>database</parameter> which defaults to
 756         <symbol>*default-database*</symbol>. <parameter>result-types</parameter>
 757         is a list of symbols which specifies the lisp type for each
 758         field returned by <parameter>query-expression</parameter>.
 759       </para>
 760       <para>
 761         If <parameter>result-types</parameter> is &nil; all results
 762         are returned as strings whereas the default value of
 763         <symbol>:auto</symbol> means that the lisp types are
 764         automatically computed for each field.
 765       </para>
 766       <para>
 767         <parameter>field-names</parameter> is &t; by default which
 768         means that the second value returned is a list of strings
 769         representing the columns selected by
 770         <parameter>query-expression</parameter>. If
 771         <parameter>field-names</parameter> is &nil;, the list of column
 772         names is not returned as a second value.
 773       </para>
 774       <para>
 775         <parameter>flatp</parameter> has a default value of &nil;
 776         which means that the results are returned as a list of
 777         lists.If FLATP is &t; and only one result is returned for each
 778         record selected by <parameter>query-expression</parameter>,
 779         the results are returned as elements of a list.
 780       </para>
 781     </refsect1>
 782     <refsect1>
 783       <title>Examples</title>
 784       <screen>
 785 (query "select emplid,first_name,last_name,height from employee where emplid = 1")
 786 => ((1 "Vladamir" "Lenin" 1.5564661d0)),
 787    ("emplid" "first_name" "last_name" "height")
 788
 789 (query "select emplid,first_name,last_name,height from employee where emplid = 1"
 790        :field-names nil)
 791 => ((1 "Vladamir" "Lenin" 1.5564661d0))
 792
 793 (query "select emplid,first_name,last_name,height from employee where emplid = 1"
 794        :field-names nil
 795        :result-types nil)
 796 => (("1" "Vladamir" "Lenin" "1.5564661"))
 797
 798 (query "select emplid,first_name,last_name,height from employee where emplid = 1"
 799        :field-names nil
 800        :result-types '(:int t t :double))
 801 => ((1 "Vladamir" "Lenin" 1.5564661))
 802
 803 (query "select last_name from employee where emplid > 5" :flatp t)
 804 => ("Andropov" "Chernenko" "Gorbachev" "Yeltsin" "Putin"),
 805    ("last_name")
 806
 807 (query "select last_name from employee where emplid > 10"
 808        :flatp t
 809        :field-names nil)
 810 => NIL
 811       </screen>
 812     </refsect1>
 813     <refsect1>
 814       <title>Side Effects</title>
 815       <para>Whatever effects the execution of the SQL query has
 816       on the underlying database, if any.</para>
 817     </refsect1>
 818     <refsect1>
 819       <title>Affected by</title>
 820       <para>None.</para>
 821     </refsect1>
 822     <refsect1>
 823       <title>Exceptional Situations</title>
 824       <para>If the execution of the SQL query leads to any errors, an
 825       error of type <errortype>sql-database-error</errortype> is
 826       signalled.</para>
 827     </refsect1>
 828     <refsect1>
 829       <title>See Also</title>
 830       <simplelist>
 831         <member><link linkend="execute-command"><function>execute-command</function></link></member>
 832         <member><link linkend="print-query"><function>print-query</function></link></member>
 833         <member><link linkend="do-query"><function>do-query</function></link></member>
 834         <member><link linkend="map-query"><function>map-query</function></link></member>
 835         <member><link linkend="loop-tuples"><function>loop</function></link></member>
 836         <member><link linkend="select"><function>select</function></link></member>
 837       </simplelist>
 838     </refsect1>
 839     <refsect1>
 840       <title>Notes</title>
 841       <para>The <parameter>field-names</parameter> and
 842       <parameter>result-types</parameter> keyword arguments are a
 843       &clsql; extension.</para>
 844     </refsect1>
 845   </refentry>
 846
 847   <refentry id="print-query">
 848     <refmeta>
 849       <refentrytitle>PRINT-QUERY</refentrytitle>
 850     </refmeta>
 851     <refnamediv>
 852       <refname>PRINT-QUERY</refname>
 853       <refpurpose>Prints a tabular report of query results.</refpurpose>
 854       <refclass>Function</refclass>
 855     </refnamediv>
 856     <refsect1>
 857       <title>Syntax</title>
 858       <synopsis>
 859       <function>print-query</function> <replaceable>query-expression</replaceable> &amp;key <replaceable>titles</replaceable> <replaceable>formats</replaceable> <replaceable>sizes</replaceable> <replaceable>stream</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
 860     </refsect1>
 861     <refsect1>
 862       <title>Arguments and Values</title>
 863       <variablelist>
 864         <varlistentry>
 865           <term><parameter>query-expression</parameter></term>
 866           <listitem>
 867             <para>An <glossterm linkend="gloss-sql-expression">sql
 868             expression</glossterm> that represents an SQL
 869             query which is expected to return a (possibly empty)
 870             result set.</para>
 871           </listitem>
 872         </varlistentry>
 873         <varlistentry>
 874           <term><parameter>database</parameter></term>
 875           <listitem>
 876             <para>A
 877             <glossterm linkend="gloss-database-object">database
 878             object</glossterm>. This will default to the value
 879             of <symbol>*default-database*</symbol>.</para>
 880           </listitem>
 881         </varlistentry>
 882         <varlistentry>
 883           <term><parameter>titles</parameter></term>
 884           <listitem>
 885             <para>
 886               A list of strings or &nil; which is the default value.
 887             </para>
 888           </listitem>
 889         </varlistentry>
 890         <varlistentry>
 891           <term><parameter>formats</parameter></term>
 892           <listitem>
 893             <para>
 894               A list of strings, &nil; or &t; which is the default value.
 895             </para>
 896           </listitem>
 897         </varlistentry>
 898         <varlistentry>
 899           <term><parameter>sizes</parameter></term>
 900           <listitem>
 901             <para>
 902               A list of numbers, &nil; or &t; which is the default value.
 903             </para>
 904           </listitem>
 905         </varlistentry>
 906         <varlistentry>
 907           <term><parameter>stream</parameter></term>
 908           <listitem>
 909             <para>
 910               An output stream or &t; which is the default value.
 911             </para>
 912           </listitem>
 913         </varlistentry>
 914       </variablelist>
 915     </refsect1>
 916     <refsect1>
 917       <title>Description</title>
 918       <para>Prints a tabular report of the results returned by the SQL
 919       query <parameter>query-expression</parameter>, which may be a
 920       symbolic SQL expression or a string, in
 921       <parameter>database</parameter> which defaults to
 922       <symbol>*default-database*</symbol>. The report is printed onto
 923       <parameter>stream</parameter> which has a default value of &t;
 924       which means that <symbol>*standard-output*</symbol> is used. The
 925       <parameter>title</parameter> argument, which defaults to &nil;,
 926       allows the specification of a list of strings to use as column
 927       titles in the tabular output. <parameter>sizes</parameter>
 928       accepts a list of column sizes, one for each column selected by
 929       <parameter>query-expression</parameter>, to use in formatting
 930       the tabular report. The default value of &t; means that minimum
 931       sizes are computed. <parameter>formats</parameter> is a list of
 932       format strings to be used for printing each column selected by
 933       <parameter>query-expression</parameter>. The default value of
 934       <parameter>formats</parameter> is &t; meaning that
 935       <symbol>~A</symbol> is used to format all columns or
 936       <symbol>~VA</symbol> if column sizes are used.
 937       </para>
 938     </refsect1>
 939     <refsect1>
 940       <title>Examples</title>
 941       <screen>
 942 (print-query [select [emplid] [first-name] [last-name] [email]
 943                      :from [employee]
 944                      :where [&lt; [emplid] 5]]
 945               :titles '("ID" "FORENAME" "SURNAME" "EMAIL"))
 946 ID FORENAME SURNAME  EMAIL
 947 1  Vladamir Lenin    lenin@soviet.org
 948 2  Josef    Stalin   stalin@soviet.org
 949 3  Leon     Trotsky  trotsky@soviet.org
 950 4  Nikita   Kruschev kruschev@soviet.org
 951 =>
 952
 953 (print-query "select emplid,first_name,last_name,email from employee where emplid >= 5"
 954              :titles '("ID" "FORENAME" "SURNAME" "EMAIL"))
 955 ID FORENAME   SURNAME   EMAIL
 956 5  Leonid     Brezhnev  brezhnev@soviet.org
 957 6  Yuri       Andropov  andropov@soviet.org
 958 7  Konstantin Chernenko chernenko@soviet.org
 959 8  Mikhail    Gorbachev gorbachev@soviet.org
 960 9  Boris      Yeltsin   yeltsin@soviet.org
 961 10 Vladamir   Putin     putin@soviet.org
 962 =>
 963 </screen>
 964     </refsect1>
 965     <refsect1>
 966       <title>Side Effects</title>
 967       <para>
 968         None.
 969       </para>
 970     </refsect1>
 971     <refsect1>
 972       <title>Affected by</title>
 973       <para>
 974         None.
 975       </para>
 976     </refsect1>
 977     <refsect1>
 978       <title>Exceptional Situations</title>
 979       <para>
 980         If the execution of the SQL query leads to any errors, an
 981         error of type <errortype>sql-database-error</errortype> is
 982         signalled.
 983       </para>
 984     </refsect1>
 985     <refsect1>
 986       <title>See Also</title>
 987       <simplelist>
 988         <member><link linkend="query"><function>query</function></link></member>
 989         <member><link linkend="do-query"><function>do-query</function></link></member>
 990         <member><link linkend="map-query"><function>map-query</function></link></member>
 991         <member><link linkend="loop-tuples"><function>loop</function></link></member>
 992         <member><link linkend="select"><function>select</function></link></member>
 993       </simplelist>
 994     </refsect1>
 995     <refsect1>
 996       <title>Notes</title>
 997       <para>
 998         None.
 999       </para>
1000     </refsect1>
1001   </refentry>
1002
1003   <refentry id="select">
1004     <refmeta>
1005       <refentrytitle>SELECT</refentrytitle>
1006     </refmeta>
1007     <refnamediv>
1008       <refname>SELECT</refname>
1009       <refpurpose>Executes a query given the supplied constraints.</refpurpose>
1010       <refclass>Function</refclass>
1011     </refnamediv>
1012     <refsect1>
1013       <title>Syntax</title>
1014       <synopsis>
1015       <function>select</function> &amp;rest <replaceable>identifiers</replaceable> &amp;key <replaceable>all</replaceable> <replaceable>distinct</replaceable> <replaceable>from</replaceable> <replaceable>group-by</replaceable> <replaceable>having</replaceable> <replaceable>order-by</replaceable> <replaceable>set-operation</replaceable> <replaceable>where</replaceable> <replaceable>result-types</replaceable> <replaceable>field-names</replaceable> <replaceable>flatp</replaceable> <replaceable>refresh</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
1016     </refsect1>
1017     <refsect1>
1018       <title>Arguments and Values</title>
1019       <variablelist>
1020         <varlistentry>
1021           <term><parameter>identifiers</parameter></term>
1022           <listitem>
1023             <para>
1024               A set of <glossterm linkend="gloss-sql-expression">sql
1025               expressions</glossterm> each of which indicates a column
1026               to query.
1027             </para>
1028           </listitem>
1029         </varlistentry>
1030         <varlistentry>
1031           <term><parameter>all</parameter></term>
1032           <listitem>
1033             <para>
1034               A Boolean.
1035             </para>
1036           </listitem>
1037         </varlistentry>
1038         <varlistentry>
1039           <term><parameter>distinct</parameter></term>
1040           <listitem>
1041             <para>
1042               A Boolean.
1043             </para>
1044           </listitem>
1045         </varlistentry>
1046         <varlistentry>
1047           <term><parameter>from</parameter></term>
1048           <listitem>
1049             <para>
1050               One or more SQL expression representing tables.
1051             </para>
1052           </listitem>
1053         </varlistentry>
1054         <varlistentry>
1055           <term><parameter>group-by</parameter></term>
1056           <listitem>
1057             <para>
1058               An SQL expression.
1059             </para>
1060           </listitem>
1061         </varlistentry>
1062         <varlistentry>
1063           <term><parameter>having</parameter></term>
1064           <listitem>
1065             <para>
1066               An SQL expression.
1067             </para>
1068           </listitem>
1069         </varlistentry>
1070         <varlistentry>
1071           <term><parameter>order-by</parameter></term>
1072           <listitem>
1073             <para>
1074               An SQL expression.
1075             </para>
1076           </listitem>
1077         </varlistentry>
1078         <varlistentry>
1079           <term><parameter>set-operation</parameter></term>
1080           <listitem>
1081             <para>
1082               An SQL expression.
1083             </para>
1084           </listitem>
1085         </varlistentry>
1086         <varlistentry>
1087           <term><parameter>where</parameter></term>
1088           <listitem>
1089             <para>
1090               An SQL expression.
1091             </para>
1092           </listitem>
1093         </varlistentry>
1094         <varlistentry>
1095           <term><parameter>database</parameter></term>
1096           <listitem>
1097             <para>A
1098             <glossterm linkend="gloss-database-object">database
1099             object</glossterm>. This will default to the value
1100             of <symbol>*default-database*</symbol>.</para>
1101           </listitem>
1102         </varlistentry>
1103         <varlistentry>
1104           <term><parameter>flatp</parameter></term>
1105           <listitem>
1106             <para>A Boolean whose default value is &nil;.</para>
1107           </listitem>
1108         </varlistentry>
1109         <varlistentry>
1110           <term><parameter>result-types</parameter></term>
1111           <listitem>
1112             <para>A
1113             <glossterm linkend="gloss-field-types">field type
1114             specifier</glossterm>. The default is &nil;.
1115             </para>
1116             <para>
1117               The purpose of this argument is cause &clsql; to
1118               import SQL numeric fields into numeric Lisp objects
1119               rather than strings. This reduces the cost of
1120               allocating a temporary string and the &clsql; users'
1121               inconvenience of converting number strings into number
1122               objects.
1123             </para>
1124             <para>
1125               A value of <symbol>:auto</symbol> causes &clsql;
1126               to automatically convert SQL fields into a
1127               numeric format where applicable. The default value of
1128               &nil; causes all fields to be returned as strings
1129               regardless of the SQL type. Otherwise a list is expected
1130               which has a element for each field that specifies the
1131               conversion. Valid type identifiers are:
1132               <simplelist type="vert">
1133                 <member><symbol>:int</symbol> Field is imported as a
1134                 signed integer, from 8-bits to 64-bits depending
1135                 upon the field type.
1136                 </member>
1137                 <member><symbol>:double</symbol> Field is imported as a
1138                 double-float number.
1139                 </member>
1140                 <member><symbol>t</symbol> Field is imported as a
1141                 string.
1142                 </member>
1143               </simplelist>
1144               If the list is shorter than the number of fields, the a
1145               value of <symbol>t</symbol> is assumed for the field.
1146               If the list is longer than the number of fields, the
1147               extra elements are ignored.
1148             </para>
1149           </listitem>
1150         </varlistentry>
1151         <varlistentry>
1152           <term><parameter>field-names</parameter></term>
1153           <listitem>
1154           <para>
1155             A boolean with a default value of &t;. When &t;, this
1156             function returns a second value of a list of field
1157             names. When &nil;, this function only returns one value -
1158             the list of rows.
1159           </para>
1160           </listitem>
1161         </varlistentry>
1162         <varlistentry>
1163           <term><parameter>result</parameter></term>
1164           <listitem>
1165             <para>
1166               A list representing the result set obtained.  For each
1167               tuple in the result set, there is an element in this
1168               list, which is itself a list of all the attribute values
1169               in the tuple.
1170             </para>
1171           </listitem>
1172         </varlistentry>
1173       </variablelist>
1174     </refsect1>
1175     <refsect1>
1176       <title>Description</title>
1177       <para>
1178         Executes a query on <parameter>database</parameter>, which has
1179         a default value of <symbol>*default-database*</symbol>,
1180         specified by the SQL expressions supplied using the remaining
1181         arguments in <parameter>args</parameter>. The
1182         <function>select</function> function can be used to generate
1183         queries in both functional and object oriented contexts.
1184       </para>
1185       <para>
1186         In the functional case, the required arguments specify the
1187         columns selected by the query and may be symbolic SQL
1188         expressions or strings representing attribute
1189         identifiers. Type modified identifiers indicate that the
1190         values selected from the specified column are converted to the
1191         specified lisp type. The keyword arguments
1192         <parameter>all</parameter>, <parameter>distinct</parameter>,
1193         <parameter>from</parameter>, <parameter>group-by</parameter>,
1194         <parameter>having</parameter>,
1195         <parameter>order-by</parameter>,
1196         <parameter>set-operation</parameter> and
1197         <parameter>where</parameter> are used to specify, using the
1198         symbolic SQL syntax, the corresponding components of the SQL
1199         query generated by the call to
1200         <function>select</function>.
1201       </para>
1202       <para>
1203         <parameter>result-types</parameter> is a list of symbols which
1204         specifies the lisp type for each field returned by the
1205         query. If <parameter>result-types</parameter> is &nil; all
1206         results are returned as strings whereas the default value of
1207         <symbol>:auto</symbol> means that the lisp types are
1208         automatically computed for each
1209         field. <parameter>field-names</parameter> is &t; by default
1210         which means that the second value returned is a list of
1211         strings representing the columns selected by the query. If
1212         <parameter>field-names</parameter> is &nil;, the list of
1213         column names is not returned as a second value.
1214       </para>
1215       <para>
1216         In the object oriented case, the required arguments to
1217         <function>select</function> are symbols denoting View Classes
1218         which specify the database tables to query. In this case,
1219         <function>select</function> returns a list of View Class
1220         instances whose slots are set from the attribute values of the
1221         records in the specified table. <symbol>Slot-value</symbol> is
1222         a legal operator which can be employed as part of the symbolic
1223         SQL syntax used in the <parameter>where</parameter> keyword
1224         argument to <function>select</function>.
1225         <parameter>refresh</parameter> is &nil; by default which means
1226         that the View Class instances returned are retrieved from a
1227         cache if an equivalent call to <function>select</function> has
1228         previously been issued. If <parameter>refresh</parameter> is
1229         true, the View Class instances returned are updated as
1230         necessary from the database and the generic function
1231         <function>instance-refreshed</function> is called to perform
1232         any necessary operations on the updated instances.
1233       </para>
1234       <para>
1235         In both object oriented and functional contexts,
1236         <parameter>flatp</parameter> has a default value of &nil;
1237         which means that the results are returned as a list of
1238         lists. If <parameter>flatp</parameter> is t and only one
1239         result is returned for each record selected in the query, the
1240         results are returned as elements of a list.
1241       </para>
1242     </refsect1>
1243     <refsect1>
1244       <title>Examples</title>
1245       <screen>
1246 (select [first-name] :from [employee] :flatp t :distinct t
1247                      :field-names nil
1248                      :result-types nil
1249                      :order-by [first-name])
1250 => ("Boris" "Josef" "Konstantin" "Leon" "Leonid" "Mikhail" "Nikita" "Vladamir"
1251     "Yuri")
1252
1253 (select [first-name] [count [*]] :from [employee]
1254                                  :result-types nil
1255                                  :group-by [first-name]
1256                                  :order-by [first-name]
1257                                  :field-names nil)
1258 => (("Boris" "1") ("Josef" "1") ("Konstantin" "1") ("Leon" "1") ("Leonid" "1")
1259     ("Mikhail" "1") ("Nikita" "1") ("Vladamir" "2") ("Yuri" "1"))
1260
1261 (select [last-name] :from [employee]
1262                     :where [like [email] "%org"]
1263                     :order-by [last-name]
1264                     :field-names nil
1265                     :result-types nil
1266                     :flatp t)
1267 => ("Andropov" "Brezhnev" "Chernenko" "Gorbachev" "Kruschev" "Lenin" "Putin"
1268     "Stalin" "Trotsky" "Yeltsin")
1269
1270 (select [max [emplid]] :from [employee]
1271                        :flatp t
1272                        :field-names nil
1273                        :result-types :auto)
1274 => (10)
1275
1276 (clsql:select [avg [height]] :from [employee] :flatp t :field-names nil)
1277 => (1.58999584d0)
1278
1279 (select [emplid] [last-name] :from [employee] :where [= [emplid] 1])
1280 => ((1 "Lenin")),
1281    ("emplid" "last_name")
1282
1283 (select [emplid :string] :from [employee]
1284                          :where [= 1 [emplid]]
1285                          :field-names nil
1286                          :flatp t)
1287 => ("1")
1288
1289 (select [emplid] :from [employee] :order-by [emplid]
1290                  :where [not [between [* [emplid] 10] [* 5 10] [* 10 10]]]
1291                  :field-names nil
1292                  :flatp t)
1293 => (1 2 3 4)
1294
1295 (clsql:select [emplid] :from [employee]
1296                        :where [in [emplid] '(1 2 3 4)]
1297                        :flatp t
1298                        :order-by [emplid]
1299                        :field-names nil)
1300 => (1 2 3 4)
1301
1302 (select [first-name] [last-name] :from [employee]
1303         :field-names nil
1304         :order-by '(([first-name] :asc) ([last-name] :desc)))
1305 => (("Boris" "Yeltsin") ("Josef" "Stalin") ("Konstantin" "Chernenko")
1306     ("Leon" "Trotsky") ("Leonid" "Brezhnev") ("Mikhail" "Gorbachev")
1307     ("Nikita" "Kruschev") ("Vladamir" "Putin") ("Vladamir" "Lenin")
1308     ("Yuri" "Andropov"))
1309
1310 (select [last-name] :from [employee]
1311                  :set-operation [union [select [first-name] :from [employee]
1312                                                :order-by [last-name]]]
1313                  :flatp t
1314                  :result-types nil
1315                  :field-names nil)
1316 => ("Andropov" "Boris" "Brezhnev" "Chernenko" "Gorbachev" "Josef" "Konstantin"
1317     "Kruschev" "Lenin" "Leon" "Leonid" "Mikhail" "Nikita" "Putin" "Stalin"
1318     "Trotsky" "Vladamir" "Yeltsin" "Yuri")
1319       </screen>
1320     </refsect1>
1321     <refsect1>
1322       <title>Side Effects</title>
1323       <para>
1324         <para>Whatever effects the execution of the SQL query has on
1325         the underlying database, if any.</para>
1326       </para>
1327     </refsect1>
1328     <refsect1>
1329       <title>Affected by</title>
1330       <para>
1331         None.
1332       </para>
1333     </refsect1>
1334     <refsect1>
1335       <title>Exceptional Situations</title>
1336       <para>
1337         If the execution of the SQL query leads to any errors, an
1338         error of type <errortype>sql-database-error</errortype> is
1339         signalled.
1340       </para>
1341     </refsect1>
1342     <refsect1>
1343       <title>See Also</title>
1344       <simplelist>
1345         <member><link linkend="query"><function>query</function></link></member>
1346         <member><link linkend="print-query"><function>print-query</function></link></member>
1347         <member><link linkend="do-query"><function>do-query</function></link></member>
1348         <member><link linkend="map-query"><function>map-query</function></link></member>
1349         <member><link linkend="loop-tuples"><function>loop</function></link></member>
1350         <member><link linkend="instance-refreshed"><function>instance-refreshed</function></link></member>
1351       </simplelist>
1352     </refsect1>
1353     <refsect1>
1354       <title>Notes</title>
1355       <para>
1356         The <function>select</function> function is actually
1357         implemented in &clsql; with a single
1358         <symbol>&amp;rest</symbol> parameter (which is subsequently
1359         destructured) rather than the keyword parameters presented
1360         here for the purposes of exposition. This means that incorrect
1361         or missing keywords or values may not trigger errors in the
1362         way that they would if <function>select</function> had been
1363         defined using keyword arguments.
1364       </para>
1365       <para>
1366         The <parameter>field-names</parameter> and
1367         <parameter>result-types</parameter> keyword arguments are a
1368         &clsql; extension.
1369       </para>
1370       <para>
1371         <parameter>select</parameter> is common across the functional
1372         and object-oriented data manipulation languages.
1373       </para>
1374     </refsect1>
1375   </refentry>
1376
1377
1378   <!-- iteration and mapping -->
1379
1380   <refentry id="do-query">
1381     <refmeta>
1382       <refentrytitle>DO-QUERY</refentrytitle>
1383     </refmeta>
1384     <refnamediv>
1385       <refname>DO-QUERY</refname>
1386       <refpurpose>Iterate over all the tuples of a query.</refpurpose>
1387       <refclass>Macro</refclass>
1388     </refnamediv>
1389     <refsect1>
1390       <title>Syntax</title>
1391       <synopsis>
1392       <function>do-query</function> ((&amp;rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> &amp;body <replaceable>body</replaceable> => <returnvalue>result</returnvalue></synopsis>
1393     </refsect1>
1394     <refsect1>
1395       <title>Arguments and Values</title>
1396       <variablelist>
1397         <varlistentry>
1398           <term><parameter>args</parameter></term>
1399           <listitem>
1400             <para>A list of variable names.</para>
1401           </listitem>
1402         </varlistentry>
1403         <varlistentry>
1404           <term><parameter>query-expression</parameter></term>
1405           <listitem>
1406             <para>An <glossterm linkend="gloss-sql-expression">sql
1407             expression</glossterm> that represents an SQL
1408             query which is expected to return a (possibly empty)
1409             result set, where each tuple has as many attributes as
1410             <parameter>function</parameter> takes arguments.</para>
1411           </listitem>
1412         </varlistentry>
1413         <varlistentry>
1414           <term><parameter>database</parameter></term>
1415           <listitem>
1416             <para>A
1417             <glossterm linkend="gloss-database-object">database
1418             object</glossterm>. This will default to
1419             <symbol>*default-database*</symbol>.</para>
1420           </listitem>
1421         </varlistentry>
1422         <varlistentry>
1423           <term><parameter>result-types</parameter></term>
1424           <listitem>
1425             <para>
1426               A <glossterm linkend="gloss-field-types">field type
1427               specifier</glossterm>.  The default is &nil;. See <link
1428               linkend="query"><function>query</function></link> for
1429               the semantics of this argument.
1430             </para>
1431           </listitem>
1432         </varlistentry>
1433         <varlistentry>
1434           <term><parameter>body</parameter></term>
1435           <listitem>
1436             <para>A body of Lisp code, like in a
1437             <function>destructuring-bind</function> form.</para>
1438           </listitem>
1439         </varlistentry>
1440         <varlistentry>
1441           <term><parameter>result</parameter></term>
1442           <listitem>
1443             <para>The result of executing <parameter>body</parameter>.</para>
1444           </listitem>
1445         </varlistentry>
1446       </variablelist>
1447     </refsect1>
1448     <refsect1>
1449       <title>Description</title>
1450       <para>
1451         Repeatedly executes <parameter>body</parameter> within a
1452         binding of <parameter>args</parameter> on the fields of each
1453         row selected by the SQL query
1454         <parameter>query-expression</parameter>, which may be a string
1455         or a symbolic SQL expression, in
1456         <parameter>database</parameter> which defaults to
1457         <symbol>*default-database*</symbol>.
1458       </para>
1459       <para>
1460         The body of code is executed in a block named
1461         <symbol>nil</symbol> which may be returned from prematurely
1462         via <function>return</function> or
1463         <function>return-from</function>.  In this case the result of
1464         evaluating the <function>do-query</function> form will be the
1465         one supplied to <function>return</function> or
1466         <function>return-from</function>.  Otherwise the result will
1467         be <symbol>nil</symbol>.
1468       </para>
1469       <para>
1470         The body of code appears also is if wrapped in a
1471         <function>destructuring-bind</function> form, thus allowing
1472         declarations at the start of the body, especially those
1473         pertaining to the bindings of the variables named in
1474         <parameter>args</parameter>.
1475       </para>
1476       <para>
1477         <parameter>result-types</parameter> is a list of symbols which
1478         specifies the lisp type for each field returned by
1479         <parameter>query-expression</parameter>. If
1480         <parameter>result-types</parameter> is &nil; all results are
1481         returned as strings whereas the default value of
1482         <symbol>:auto</symbol> means that the lisp types are
1483         automatically computed for each field.
1484       </para>
1485       <para>
1486         <parameter>query-expression</parameter> may be an object query
1487         (i.e., the selection arguments refer to View Classes), in
1488         which case <parameter>args</parameter> are bound to the tuples
1489         of View Class instances returned by the object oriented query.
1490       </para>
1491     </refsect1>
1492     <refsect1>
1493       <title>Examples</title>
1494       <screen>
1495 (do-query ((salary name) "select salary,name from simple")
1496   (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
1497 >> Mai, Pierre                    gets $10000.00
1498 >> Hacker, Random J.              gets $08000.50
1499 => NIL
1500
1501 (do-query ((salary name) "select salary,name from simple")
1502   (return (cons salary name)))
1503 => ("10000.00" . "Mai, Pierre")
1504
1505 (let ((result '()))
1506   (do-query ((name) [select [last-name] :from [employee]
1507                             :order-by [last-name]])
1508     (push name result))
1509   result)
1510 => ("Yeltsin" "Trotsky" "Stalin" "Putin" "Lenin" "Kruschev" "Gorbachev"
1511     "Chernenko" "Brezhnev" "Andropov")
1512
1513 (let ((result '()))
1514   (do-query ((e) [select 'employee :order-by [last-name]])
1515     (push (slot-value e 'last-name) result))
1516   result)
1517 => ("Yeltsin" "Trotsky" "Stalin" "Putin" "Lenin" "Kruschev" "Gorbachev"
1518     "Chernenko" "Brezhnev" "Andropov")
1519       </screen>
1520     </refsect1>
1521     <refsect1>
1522       <title>Side Effects</title>
1523       <para>Whatever effects the execution of the SQL query has
1524       on the underlying database, if any.</para>
1525     </refsect1>
1526     <refsect1>
1527       <title>Affected by</title>
1528       <para>None.</para>
1529     </refsect1>
1530     <refsect1>
1531       <title>Exceptional Situations</title>
1532       <para>If the execution of  the SQL query leads to any
1533       errors, an error of type
1534       <errortype>sql-database-error</errortype> is signalled.</para>
1535       <para>If the number of variable names in
1536       <parameter>args</parameter> and the number of attributes in
1537       the tuples in the result set don't match up, an error is
1538       signalled.</para>
1539     </refsect1>
1540     <refsect1>
1541       <title>See Also</title>
1542       <simplelist>
1543         <member><link linkend="query"><function>query</function></link></member>
1544         <member><link linkend="map-query"><function>map-query</function></link></member>
1545         <member><link linkend="print-query"><function>print-query</function></link></member>
1546         <member><link linkend="loop-tuples"><function>loop</function></link></member>
1547         <member><link linkend="select"><function>select</function></link></member>
1548       </simplelist>
1549     </refsect1>
1550     <refsect1>
1551       <title>Notes</title>
1552       <para>The <parameter>result-types</parameter> keyword argument
1553       is a &clsql; extension.</para>
1554       <para>
1555         <parameter>do-query</parameter> is common across the functional
1556         and object-oriented data manipulation languages.
1557       </para>
1558     </refsect1>
1559   </refentry>
1560
1561   <refentry id="loop-tuples">
1562     <refmeta>
1563       <refentrytitle>LOOP</refentrytitle>
1564     </refmeta>
1565     <refnamediv>
1566       <refname>LOOP</refname>
1567       <refpurpose>Extension to Common Lisp
1568       <computeroutput>Loop</computeroutput> to iterate over all the
1569       tuples of a query via a loop clause.</refpurpose>
1570       <refclass>Loop Clause</refclass>
1571     </refnamediv>
1572     <!-- refsect1>
1573       <title>Compatibility</title>
1574       <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
1575     </refsect1 -->
1576     <refsect1>
1577       <title>Syntax</title>
1578       <synopsis>{as | for} <replaceable>var</replaceable> [<replaceable>type-spec</replaceable>] being {each | the} {record | records | tuple | tuples} {in | of} <replaceable>query</replaceable> [from <replaceable>database</replaceable>]</synopsis>
1579     </refsect1>
1580     <refsect1>
1581       <title>Arguments and Values</title>
1582       <variablelist>
1583         <varlistentry>
1584           <term><parameter>var</parameter></term>
1585           <listitem>
1586             <para>A <literal>d-var-spec</literal>, as defined in the
1587             grammar for <function>loop</function>-clauses in the ANSI
1588             Standard for Common Lisp.  This allows for the usual
1589             loop-style destructuring.</para>
1590           </listitem>
1591         </varlistentry>
1592         <varlistentry>
1593           <term><parameter>type-spec</parameter></term>
1594           <listitem>
1595             <para>An optional <literal>type-spec</literal> either
1596             simple or destructured, as defined in the grammar for
1597             <function>loop</function>-clauses in the ANSI Standard for
1598             Common Lisp.</para>
1599           </listitem>
1600         </varlistentry>
1601         <varlistentry>
1602           <term><parameter>query</parameter></term>
1603           <listitem>
1604             <para>An <glossterm linkend="gloss-sql-expression">sql
1605             expression</glossterm> that represents an SQL
1606             query which is expected to return a (possibly empty)
1607             result set, where each tuple has as many attributes as
1608             <parameter>function</parameter> takes arguments.</para>
1609           </listitem>
1610         </varlistentry>
1611         <varlistentry>
1612           <term><parameter>database</parameter></term>
1613           <listitem>
1614             <para>An optional
1615             <glossterm linkend="gloss-database-object">database
1616             object</glossterm>. This will default to the value
1617             of <symbol>*default-database*</symbol>.</para>
1618           </listitem>
1619         </varlistentry>
1620       </variablelist>
1621     </refsect1>
1622     <refsect1>
1623       <title>Description</title>
1624       <para>This clause is an iteration driver for
1625       <function>loop</function>, that binds the given variable
1626       (possibly destructured) to the consecutive tuples (which are
1627       represented as lists of attribute values) in the result set
1628       returned by executing the SQL <parameter>query</parameter>
1629       expression on the <parameter>database</parameter>
1630       specified.</para>
1631       <para>
1632         <parameter>query</parameter> may be an object query (i.e., the
1633         selection arguments refer to View Classes), in which case the
1634         supplied variable is bound to the tuples of View Class
1635         instances returned by the object oriented query.
1636       </para>
1637     </refsect1>
1638     <refsect1>
1639       <title>Examples</title>
1640       <screen>
1641 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
1642 "My database"
1643 => *MY-DB*
1644 (loop with time-graph = (make-hash-table :test #'equal)
1645    with event-graph = (make-hash-table :test #'equal)
1646    for (time event) being the tuples of "select time,event from log"
1647    from *my-db*
1648    do
1649      (incf (gethash time time-graph 0))
1650      (incf (gethash event event-graph 0))
1651    finally
1652      (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
1653        (format t "~&amp;Time-Graph:~%===========~%")
1654        (maphash #'show-graph time-graph)
1655        (format t "~&amp;~%Event-Graph:~%============~%")
1656        (maphash #'show-graph event-graph))
1657      (return (values time-graph event-graph)))
1658 >> Time-Graph:
1659 >> ===========
1660 >> D                                        => 53000
1661 >> X                                        =>     3
1662 >> test-me                                  =>  3000
1663 >>
1664 >> Event-Graph:
1665 >> ============
1666 >> CLOS Benchmark entry.                    =>  9000
1667 >> Demo Text...                             =>     3
1668 >> doit-text                                =>  3000
1669 >> C    Benchmark entry.                    => 12000
1670 >> CLOS Benchmark entry                     => 32000
1671 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
1672 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
1673
1674 (loop for (forename surname)
1675       being each tuple in
1676         [select [first-name] [last-name] :from [employee]
1677                 :order-by [last-name]]
1678       collect (concatenate 'string forename " " surname))
1679 => ("Yuri Andropov" "Leonid Brezhnev" "Konstantin Chernenko" "Mikhail Gorbachev"
1680     "Nikita Kruschev" "Vladamir Lenin" "Vladamir Putin" "Josef Stalin"
1681     "Leon Trotsky" "Boris Yeltsin")
1682
1683 (loop for (e) being the records in
1684      [select 'employee :where [&lt; [emplid] 4] :order-by [emplid]]
1685   collect (slot-value e 'last-name))
1686 => ("Lenin" "Stalin" "Trotsky")
1687       </screen>
1688     </refsect1>
1689     <refsect1>
1690       <title>Side Effects</title>
1691       <para>Whatever effects the execution of the SQL query has
1692       on the underlying database, if any.</para>
1693     </refsect1>
1694     <refsect1>
1695       <title>Affected by</title>
1696       <para>None.</para>
1697     </refsect1>
1698     <refsect1>
1699       <title>Exceptional Situations</title>
1700       <para>If the execution of  the SQL query leads to any
1701       errors, an error of type
1702       <errortype>sql-database-error</errortype> is signalled.</para>
1703       <para>Otherwise, any of the exceptional situations of
1704       <function>loop</function> applies.</para>
1705     </refsect1>
1706     <refsect1>
1707       <title>See Also</title>
1708       <para>
1709         <simplelist>
1710           <member><link linkend="query"><function>query</function></link></member>
1711           <member><link linkend="map-query"><function>map-query</function></link></member>
1712           <member><link linkend="do-query"><function>do-query</function></link></member>
1713         <member><link linkend="print-query"><function>print-query</function></link></member>
1714         <member><link linkend="select"><function>select</function></link></member>
1715         </simplelist>
1716       </para>
1717     </refsect1>
1718     <refsect1>
1719       <title>Notes</title>
1720       <para>The <parameter>database</parameter> loop keyword is a
1721       &clsql; extension.</para>
1722       <para>
1723         The extended <function>loop</function> syntax is common across
1724         the functional and object-oriented data manipulation
1725         languages.
1726       </para>
1727     </refsect1>
1728   </refentry>
1729
1730   <refentry id="map-query">
1731     <refmeta>
1732       <refentrytitle>MAP-QUERY</refentrytitle>
1733     </refmeta>
1734     <refnamediv>
1735       <refname>MAP-QUERY</refname>
1736       <refpurpose>Map a function over all the tuples from a
1737       query</refpurpose>
1738       <refclass>Function</refclass>
1739     </refnamediv>
1740     <refsect1>
1741       <title>Syntax</title>
1742       <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &amp;key <replaceable>database</replaceable> <replaceable>result-types</replaceable> => <returnvalue>result</returnvalue></synopsis>
1743     </refsect1>
1744     <refsect1>
1745       <title>Arguments and Values</title>
1746       <variablelist>
1747         <varlistentry>
1748           <term><parameter>output-type-spec</parameter></term>
1749           <listitem>
1750             <para>A sequence type specifier or <symbol>nil</symbol>.</para>
1751           </listitem>
1752         </varlistentry>
1753         <varlistentry>
1754           <term><parameter>function</parameter></term>
1755           <listitem>
1756             <para>A function designator.
1757             <parameter>function</parameter> takes a single argument which
1758             is the atom value for a query single with a single column
1759             or is a list of values for a multi-column query.</para>
1760           </listitem>
1761         </varlistentry>
1762         <varlistentry>
1763           <term><parameter>query-expression</parameter></term>
1764           <listitem>
1765             <para>An <glossterm linkend="gloss-sql-expression">sql
1766             expression</glossterm> that represents an SQL
1767             query which is expected to return a (possibly empty)
1768             result set.</para>
1769           </listitem>
1770         </varlistentry>
1771         <varlistentry>
1772           <term><parameter>database</parameter></term>
1773           <listitem>
1774             <para>A
1775             <glossterm linkend="gloss-database-object">database
1776             object</glossterm>. This will default to the value
1777             of <symbol>*default-database*</symbol>.</para>
1778           </listitem>
1779         </varlistentry>
1780         <varlistentry>
1781           <term><parameter>result-types</parameter></term>
1782           <listitem>
1783             <para>
1784               A <glossterm linkend="gloss-field-types">field type
1785               specifier</glossterm>.  The default is &nil;. See <link
1786               linkend="query"><function>query</function></link> for
1787               the semantics of this argument.
1788             </para>
1789           </listitem>
1790         </varlistentry>
1791         <varlistentry>
1792           <term><returnvalue>result</returnvalue></term>
1793           <listitem>
1794             <para>If <parameter>output-type-spec</parameter> is a
1795             type specifier other than <symbol>nil</symbol>, then a
1796             sequence of the type it denotes.  Otherwise
1797             <symbol>nil</symbol> is returned.</para>
1798           </listitem>
1799         </varlistentry>
1800       </variablelist>
1801     </refsect1>
1802     <refsect1>
1803       <title>Description</title>
1804       <para>
1805         Applies <parameter>function</parameter> to the successive
1806         tuples in the result set returned by executing the SQL
1807         <parameter>query-expression</parameter>.  If the
1808         <parameter>output-type-spec</parameter> is
1809         <symbol>nil</symbol>, then the result of each application of
1810         <parameter>function</parameter> is discarded, and
1811         <function>map-query</function> returns <symbol>nil</symbol>.
1812         Otherwise the result of each successive application of
1813         <parameter>function</parameter> is collected in a sequence of
1814         type <parameter>output-type-spec</parameter>, where the jths
1815         element is the result of applying
1816         <parameter>function</parameter> to the attributes of the jths
1817         tuple in the result set.  The collected sequence is the result
1818         of the call to <function>map-query</function>.
1819       </para>
1820       <para>
1821         If the <parameter>output-type-spec</parameter> is a subtype of
1822         <type>list</type>, the result will be a <type>list</type>.
1823       </para>
1824       <para>
1825         If the <parameter>result-type</parameter> is a subtype of
1826         <type>vector</type>, then if the implementation can determine
1827         the element type specified for the
1828         <parameter>result-type</parameter>, the element type of the
1829         resulting array is the result of
1830         <emphasis>upgrading</emphasis> that element type; or, if the
1831         implementation can determine that the element type is
1832         unspecified (or <symbol>*</symbol>), the element type of the
1833         resulting array is <type>t</type>; otherwise, an error is
1834         signaled.
1835       </para>
1836       <para>
1837         If <parameter>result-types</parameter> is &nil; all results
1838         are returned as strings whereas the default value of
1839         <symbol>:auto</symbol> means that the lisp types are
1840         automatically computed for each field.</para>
1841       <para>
1842         <parameter>query-expression</parameter> may be an object query
1843         (i.e., the selection arguments refer to View Classes), in
1844         which case the supplied function is applied to the tuples of
1845         View Class instances returned by the object oriented query.
1846       </para>
1847     </refsect1>
1848     <refsect1>
1849       <title>Examples</title>
1850       <screen>
1851 (map-query 'list #'(lambda (tuple)
1852                      (multiple-value-bind (salary name) tuple
1853                         (declare (ignorable name))
1854                         (read-from-string salary)))
1855             "select salary,name from simple where salary > 8000")
1856 => (10000.0 8000.5)
1857
1858 (map-query '(vector double-float)
1859            #'(lambda (tuple)
1860                (multiple-value-bind (salary name) tuple
1861                   (declare (ignorable name))
1862                   (let ((*read-default-float-format* 'double-float))
1863                     (coerce (read-from-string salary) 'double-float))
1864            "select salary,name from simple where salary > 8000")))
1865 => #(10000.0d0 8000.5d0)
1866 (type-of *)
1867 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
1868
1869 (let (list)
1870   (values (map-query nil #'(lambda (tuple)
1871                              (multiple-value-bind (salary name) tuple
1872                                (push (cons name (read-from-string salary)) list))
1873                          "select salary,name from simple where salary > 8000"))
1874           list))
1875 => NIL
1876 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
1877
1878 (map-query 'vector #'identity
1879            [select [last-name] :from [employee] :flatp t
1880                    :order-by [last-name]])
1881 => #("Andropov" "Brezhnev" "Chernenko" "Gorbachev" "Kruschev" "Lenin" "Putin"
1882      "Stalin" "Trotsky" "Yeltsin")
1883
1884 (map-query 'list #'identity
1885            [select [first-name] [last-name] :from [employee]
1886                    :order-by [last-name]])
1887 => (("Yuri" "Andropov") ("Leonid" "Brezhnev") ("Konstantin" "Chernenko")
1888     ("Mikhail" "Gorbachev") ("Nikita" "Kruschev") ("Vladamir" "Lenin")
1889     ("Vladamir" "Putin") ("Josef" "Stalin") ("Leon" "Trotsky")
1890     ("Boris" "Yeltsin"))
1891
1892 (map-query 'list #'last-name [select 'employee :order-by [emplid]])
1893 => ("Lenin" "Stalin" "Trotsky" "Kruschev" "Brezhnev" "Andropov" "Chernenko"
1894     "Gorbachev" "Yeltsin" "Putin")
1895       </screen>
1896     </refsect1>
1897     <refsect1>
1898       <title>Side Effects</title>
1899       <para>Whatever effects the execution of the SQL query has
1900       on the underlying database, if any.</para>
1901     </refsect1>
1902     <refsect1>
1903       <title>Affected by</title>
1904       <para>None.</para>
1905     </refsect1>
1906     <refsect1>
1907       <title>Exceptional Situations</title>
1908       <para>If the execution of  the SQL query leads to any
1909       errors, an error of type
1910       <errortype>sql-database-error</errortype> is signalled.</para>
1911       <para>An error of type <errortype>type-error</errortype> must
1912       be signaled if the <parameter>output-type-spec</parameter> is
1913       not a recognizable subtype of <type>list</type>, not a
1914       recognizable subtype of <type>vector</type>, and not
1915       <symbol>nil</symbol>.</para>
1916       <para>An error of type <errortype>type-error</errortype>
1917       should be signaled if
1918       <parameter>output-type-spec</parameter> specifies the number
1919       of elements and the size of the result set is different from
1920       that number.</para>
1921     </refsect1>
1922     <refsect1>
1923       <title>See Also</title>
1924       <simplelist>
1925         <member><link linkend="query"><function>query</function></link></member>
1926         <member><link linkend="do-query"><function>do-query</function></link></member>
1927         <member><link linkend="print-query"><function>print-query</function></link></member>
1928         <member><link linkend="loop-tuples"><function>loop</function></link></member>
1929         <member><link linkend="select"><function>select</function></link></member>
1930       </simplelist>
1931     </refsect1>
1932     <refsect1>
1933       <title>Notes</title>
1934       <para>The <parameter>result-types</parameter> keyword argument
1935       is a &clsql; extension.</para>
1936       <para>
1937         <parameter>map-query</parameter> is common across the
1938         functional and object-oriented data manipulation languages.
1939       </para>
1940     </refsect1>
1941   </refentry>
1942
1943 </reference>
1944