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       <!-- introduction -->
  14     </para>
  15   </partintro>
  16
  17   <refentry id="cache-table-queries-default">
  18     <refnamediv>
  19       <refname>*CACHE-TABLE-QUERIES-DEFAULT*</refname>
  20       <refpurpose><!-- purpose --></refpurpose>
  21       <refclass>Variable</refclass>
  22     </refnamediv>
  23     <refsect1>
  24       <title>Value Type</title>
  25       <para>
  26         <!-- value type -->
  27       </para>
  28     </refsect1>
  29     <refsect1>
  30       <title>Initial Value</title>
  31       <para><symbol>nil</symbol></para>
  32     </refsect1>
  33     <refsect1>
  34       <title>Description</title>
  35       <!-- description -->
  36     </refsect1>
  37     <refsect1>
  38       <title>Examples</title>
  39       <screen>
  40         <!-- examples -->
  41       </screen>
  42     </refsect1>
  43     <refsect1>
  44       <title>Affected By</title>
  45       <para>None.</para>
  46     </refsect1>
  47     <refsect1>
  48       <title>See Also</title>
  49       <para>None.</para>
  50     </refsect1>
  51     <refsect1>
  52       <title>Notes</title>
  53       <para>None.</para>
  54     </refsect1>
  55   </refentry>
  56
  57
  58
  59   <refentry id="bind-parameter">
  60     <refnamediv>
  61       <refname>BIND-PARAMETER</refname>
  62       <refpurpose><!-- purpose --></refpurpose>
  63       <refclass>Function</refclass>
  64     </refnamediv>
  65     <refsect1>
  66       <title>Syntax</title>
  67       <synopsis>
  68       <function> (BIND-PARAMETER PREPARED-STMT POSITION VALUE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
  69     </refsect1>
  70     <refsect1>
  71       <title>Arguments and Values</title>
  72       <variablelist>
  73         <!-- arguments and values -->
  74       </variablelist>
  75     </refsect1>
  76     <refsect1>
  77       <title>Description</title>
  78       <para>Sets the value of a parameter in a prepared statement.
  79       </para>
  80     </refsect1>
  81     <refsect1>
  82       <title>Examples</title>
  83       <screen>
  84         <!-- examples -->
  85       </screen>
  86     </refsect1>
  87     <refsect1>
  88       <title>Side Effects</title>
  89       <para>
  90         <!-- side effects -->
  91       </para>
  92     </refsect1>
  93     <refsect1>
  94       <title>Affected by</title>
  95       <para>
  96         <simplelist>
  97           <!-- affected by -->
  98         </simplelist>
  99       </para>
 100     </refsect1>
 101     <refsect1>
 102       <title>Exceptional Situations</title>
 103       <para>
 104         <!-- execeptional situations -->
 105       </para>
 106     </refsect1>
 107     <refsect1>
 108       <title>See Also</title>
 109       <para>
 110         <simplelist>
 111           <!-- see also -->
 112         </simplelist>
 113       </para>
 114     </refsect1>
 115     <refsect1>
 116       <title>Notes</title>
 117       <para>
 118         <!-- notes -->
 119       </para>
 120     </refsect1>
 121   </refentry>
 122
 123   <refentry id="cache-table-queries">
 124     <refnamediv>
 125       <refname>CACHE-TABLE-QUERIES</refname>
 126       <refpurpose><!-- purpose --></refpurpose>
 127       <refclass>Function</refclass>
 128     </refnamediv>
 129     <refsect1>
 130       <title>Syntax</title>
 131       <synopsis>
 132       <function> (CACHE-TABLE-QUERIES TABLE &amp;KEY (ACTION NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 133     </refsect1>
 134     <refsect1>
 135       <title>Arguments and Values</title>
 136       <variablelist>
 137         <!-- arguments and values -->
 138       </variablelist>
 139     </refsect1>
 140     <refsect1>
 141       <title>Description</title>
 142       <para>Controls the caching of attribute type information on
 143       the table specified by TABLE in DATABASE which defaults to
 144       *DEFAULT-DATABASE*. ACTION specifies the caching behaviour to
 145       adopt. If its value is t then attribute type information is
 146       cached whereas if its value is nil then attribute type
 147       information is not cached. If ACTION is :flush then all
 148       existing type information in the cache for TABLE is removed,
 149       but caching is still enabled. TABLE may be a string
 150       representing a table for which the caching action is to be
 151       taken while the caching action is applied to all tables if
 152       TABLE is t. Alternativly, when TABLE is :default, the default
 153       caching action specified by *CACHE-TABLE-QUERIES-DEFAULT* is
 154       applied to all table for which a caching action has not been
 155       explicitly set.
 156       </para>
 157     </refsect1>
 158     <refsect1>
 159       <title>Examples</title>
 160       <screen>
 161         <!-- examples -->
 162       </screen>
 163     </refsect1>
 164     <refsect1>
 165       <title>Side Effects</title>
 166       <para>
 167         <!-- side effects -->
 168       </para>
 169     </refsect1>
 170     <refsect1>
 171       <title>Affected by</title>
 172       <para>
 173         <simplelist>
 174           <!-- affected by -->
 175         </simplelist>
 176       </para>
 177     </refsect1>
 178     <refsect1>
 179       <title>Exceptional Situations</title>
 180       <para>
 181         <!-- execeptional situations -->
 182       </para>
 183     </refsect1>
 184     <refsect1>
 185       <title>See Also</title>
 186       <para>
 187         <simplelist>
 188           <!-- see also -->
 189         </simplelist>
 190       </para>
 191     </refsect1>
 192     <refsect1>
 193       <title>Notes</title>
 194       <para>
 195         <!-- notes -->
 196       </para>
 197     </refsect1>
 198   </refentry>
 199
 200
 201   <refentry id="delete-records">
 202     <refnamediv>
 203       <refname>DELETE-RECORDS</refname>
 204       <refpurpose><!-- purpose --></refpurpose>
 205       <refclass>Function</refclass>
 206     </refnamediv>
 207     <refsect1>
 208       <title>Syntax</title>
 209       <synopsis>
 210       <function> (DELETE-RECORDS &amp;KEY (FROM NIL) (WHERE NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 211     </refsect1>
 212     <refsect1>
 213       <title>Arguments and Values</title>
 214       <variablelist>
 215         <!-- arguments and values -->
 216       </variablelist>
 217     </refsect1>
 218     <refsect1>
 219       <title>Description</title>
 220       <para>Deletes records satisfying the SQL expression
 221       WHERE from the table specified by FROM in DATABASE
 222       specifies a database which defaults to
 223       *DEFAULT-DATABASE*.
 224       </para>
 225     </refsect1>
 226     <refsect1>
 227       <title>Examples</title>
 228       <screen>
 229         <!-- examples -->
 230       </screen>
 231     </refsect1>
 232     <refsect1>
 233       <title>Side Effects</title>
 234       <para>
 235         <!-- side effects -->
 236       </para>
 237     </refsect1>
 238     <refsect1>
 239       <title>Affected by</title>
 240       <para>
 241         <simplelist>
 242           <!-- affected by -->
 243         </simplelist>
 244       </para>
 245     </refsect1>
 246     <refsect1>
 247       <title>Exceptional Situations</title>
 248       <para>
 249         <!-- execeptional situations -->
 250       </para>
 251     </refsect1>
 252     <refsect1>
 253       <title>See Also</title>
 254       <para>
 255         <simplelist>
 256           <!-- see also -->
 257         </simplelist>
 258       </para>
 259     </refsect1>
 260     <refsect1>
 261       <title>Notes</title>
 262       <para>
 263         <!-- notes -->
 264       </para>
 265     </refsect1>
 266   </refentry>
 267
 268
 269   <refentry id="do-query">
 270     <refnamediv>
 271       <refname>DO-QUERY</refname>
 272       <refpurpose><!-- purpose --></refpurpose>
 273       <refclass>Function</refclass>
 274     </refnamediv>
 275     <refsect1>
 276       <title>Syntax</title>
 277       <synopsis>
 278       <function> (DO-QUERY &amp;KEY (DATABASE '*DEFAULT-DATABASE*) (RESULT-TYPES :AUTO) &amp;REST QUERY-EXPRESSION &amp;BODY BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 279     </refsect1>
 280     <refsect1>
 281       <title>Arguments and Values</title>
 282       <variablelist>
 283         <!-- arguments and values -->
 284       </variablelist>
 285     </refsect1>
 286     <refsect1>
 287       <title>Description</title>
 288       <para>Repeatedly executes BODY within a binding of
 289       ARGS on the fields of each row selected by the SQL
 290       query QUERY-EXPRESSION, which may be a string or a
 291       symbolic SQL expression, in DATABASE which defaults to
 292       *DEFAULT-DATABASE*. The values returned by the
 293       execution of BODY are returned. RESULT-TYPES is a list
 294       of symbols which specifies the lisp type for each
 295       field returned by QUERY-EXPRESSION. If RESULT-TYPES is
 296       nil all results are returned as strings whereas the
 297       default value of :auto means that the lisp types are
 298       automatically computed for each field.
 299       </para>
 300     </refsect1>
 301     <refsect1>
 302       <title>Examples</title>
 303       <screen>
 304         <!-- examples -->
 305       </screen>
 306     </refsect1>
 307     <refsect1>
 308       <title>Side Effects</title>
 309       <para>
 310         <!-- side effects -->
 311       </para>
 312     </refsect1>
 313     <refsect1>
 314       <title>Affected by</title>
 315       <para>
 316         <simplelist>
 317           <!-- affected by -->
 318         </simplelist>
 319       </para>
 320     </refsect1>
 321     <refsect1>
 322       <title>Exceptional Situations</title>
 323       <para>
 324         <!-- execeptional situations -->
 325       </para>
 326     </refsect1>
 327     <refsect1>
 328       <title>See Also</title>
 329       <para>
 330         <simplelist>
 331           <!-- see also -->
 332         </simplelist>
 333       </para>
 334     </refsect1>
 335     <refsect1>
 336       <title>Notes</title>
 337       <para>
 338         <!-- notes -->
 339       </para>
 340     </refsect1>
 341   </refentry>
 342
 343   <refentry id="execute-command">
 344     <refnamediv>
 345       <refname>EXECUTE-COMMAND</refname>
 346       <refpurpose><!-- purpose --></refpurpose>
 347       <refclass>Function</refclass>
 348     </refnamediv>
 349     <refsect1>
 350       <title>Syntax</title>
 351       <synopsis>
 352       <function> (EXECUTE-COMMAND EXPRESSION &amp;KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 353     </refsect1>
 354     <refsect1>
 355       <title>Arguments and Values</title>
 356       <variablelist>
 357         <!-- arguments and values -->
 358       </variablelist>
 359     </refsect1>
 360     <refsect1>
 361       <title>Description</title>
 362       <para>Executes the SQL command EXPRESSION, which may be an SQL
 363       expression or a string representing any SQL statement apart
 364       from a query, on the supplied DATABASE which defaults to
 365       *DEFAULT-DATABASE*.
 366       </para>
 367     </refsect1>
 368     <refsect1>
 369       <title>Examples</title>
 370       <screen>
 371         <!-- examples -->
 372       </screen>
 373     </refsect1>
 374     <refsect1>
 375       <title>Side Effects</title>
 376       <para>
 377         <!-- side effects -->
 378       </para>
 379     </refsect1>
 380     <refsect1>
 381       <title>Affected by</title>
 382       <para>
 383         <simplelist>
 384           <!-- affected by -->
 385         </simplelist>
 386       </para>
 387     </refsect1>
 388     <refsect1>
 389       <title>Exceptional Situations</title>
 390       <para>
 391         <!-- execeptional situations -->
 392       </para>
 393     </refsect1>
 394     <refsect1>
 395       <title>See Also</title>
 396       <para>
 397         <simplelist>
 398           <!-- see also -->
 399         </simplelist>
 400       </para>
 401     </refsect1>
 402     <refsect1>
 403       <title>Notes</title>
 404       <para>
 405         <!-- notes -->
 406       </para>
 407     </refsect1>
 408   </refentry>
 409
 410   <refentry id="for-each-row">
 411     <refnamediv>
 412       <refname>FOR-EACH-ROW</refname>
 413       <refpurpose><!-- purpose --></refpurpose>
 414       <refclass>Function</refclass>
 415     </refnamediv>
 416     <refsect1>
 417       <title>Syntax</title>
 418       <synopsis>
 419       <function> (FOR-EACH-ROW &amp;KEY FROM ORDER-BY WHERE DISTINCT LIMIT &amp;REST FIELDS &amp;BODY BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 420     </refsect1>
 421     <refsect1>
 422       <title>Arguments and Values</title>
 423       <variablelist>
 424         <!-- arguments and values -->
 425       </variablelist>
 426     </refsect1>
 427     <refsect1>
 428       <title>Description</title>
 429       <para>
 430         <!-- description -->
 431       </para>
 432     </refsect1>
 433     <refsect1>
 434       <title>Examples</title>
 435       <screen>
 436         <!-- examples -->
 437       </screen>
 438     </refsect1>
 439     <refsect1>
 440       <title>Side Effects</title>
 441       <para>
 442         <!-- side effects -->
 443       </para>
 444     </refsect1>
 445     <refsect1>
 446       <title>Affected by</title>
 447       <para>
 448         <simplelist>
 449           <!-- affected by -->
 450         </simplelist>
 451       </para>
 452     </refsect1>
 453     <refsect1>
 454       <title>Exceptional Situations</title>
 455       <para>
 456         <!-- execeptional situations -->
 457       </para>
 458     </refsect1>
 459     <refsect1>
 460       <title>See Also</title>
 461       <para>
 462         <simplelist>
 463           <!-- see also list here -->
 464         </simplelist>
 465       </para>
 466     </refsect1>
 467     <refsect1>
 468       <title>Notes</title>
 469       <para>
 470         <!-- notes here -->
 471       </para>
 472     </refsect1>
 473   </refentry>
 474
 475   <refentry id="free-prepared-sql">
 476     <refnamediv>
 477       <refname>FREE-PREPARED-SQL</refname>
 478       <refpurpose><!-- purpose --></refpurpose>
 479       <refclass>Function</refclass>
 480     </refnamediv>
 481     <refsect1>
 482       <title>Syntax</title>
 483       <synopsis>
 484       <function> (FREE-PREPARED-SQL PREPARED-STMT) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 485     </refsect1>
 486     <refsect1>
 487       <title>Arguments and Values</title>
 488       <variablelist>
 489         <!-- arguments and values -->
 490       </variablelist>
 491     </refsect1>
 492     <refsect1>
 493       <title>Description</title>
 494       <para>Delete the objects associated with a prepared
 495       statement.
 496       </para>
 497     </refsect1>
 498     <refsect1>
 499       <title>Examples</title>
 500       <screen>
 501         <!-- examples -->
 502       </screen>
 503     </refsect1>
 504     <refsect1>
 505       <title>Side Effects</title>
 506       <para>
 507         <!-- side effects -->
 508       </para>
 509     </refsect1>
 510     <refsect1>
 511       <title>Affected by</title>
 512       <para>
 513         <simplelist>
 514           <!-- affected by -->
 515         </simplelist>
 516       </para>
 517     </refsect1>
 518     <refsect1>
 519       <title>Exceptional Situations</title>
 520       <para>
 521         <!-- execeptional situations -->
 522       </para>
 523     </refsect1>
 524     <refsect1>
 525       <title>See Also</title>
 526       <para>
 527         <simplelist>
 528           <!-- see also -->
 529         </simplelist>
 530       </para>
 531     </refsect1>
 532     <refsect1>
 533       <title>Notes</title>
 534       <para>
 535         <!-- notes -->
 536       </para>
 537     </refsect1>
 538   </refentry>
 539
 540   <refentry id="insert-records">
 541     <refnamediv>
 542       <refname>INSERT-RECORDS</refname>
 543       <refpurpose><!-- purpose --></refpurpose>
 544       <refclass>Function</refclass>
 545     </refnamediv>
 546     <refsect1>
 547       <title>Syntax</title>
 548       <synopsis>
 549       <function> (INSERT-RECORDS &amp;KEY (INTO NIL) (ATTRIBUTES NIL) (VALUES NIL) (AV-PAIRS NIL) (QUERY NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 550     </refsect1>
 551     <refsect1>
 552       <title>Arguments and Values</title>
 553       <variablelist>
 554         <!-- arguments and values -->
 555       </variablelist>
 556     </refsect1>
 557     <refsect1>
 558       <title>Description</title>
 559       <para>Inserts records into the table specified by
 560       INTO in DATABASE which defaults to
 561       *DEFAULT-DATABASE*. There are five ways of specifying
 562       the values inserted into each row. In the first VALUES
 563       contains a list of values to insert and ATTRIBUTES,
 564       AV-PAIRS and QUERY are nil. This can be used when
 565       values are supplied for all attributes in INTO. In the
 566       second, ATTRIBUTES is a list of column names, VALUES
 567       is a corresponding list of values and AV-PAIRS and
 568       QUERY are nil. In the third, ATTRIBUTES, VALUES and
 569       QUERY are nil and AV-PAIRS is an alist of (attribute
 570       value) pairs. In the fourth, VALUES, AV-PAIRS and
 571       ATTRIBUTES are nil and QUERY is a symbolic SQL query
 572       expression in which the selected columns also exist in
 573       INTO. In the fifth method, VALUES and AV-PAIRS are nil
 574       and ATTRIBUTES is a list of column names and QUERY is
 575       a symbolic SQL query expression which returns values
 576       for the specified columns.
 577       </para>
 578     </refsect1>
 579     <refsect1>
 580       <title>Examples</title>
 581       <screen>
 582         <!-- examples -->
 583       </screen>
 584     </refsect1>
 585     <refsect1>
 586       <title>Side Effects</title>
 587       <para>
 588         <!-- side effects -->
 589       </para>
 590     </refsect1>
 591     <refsect1>
 592       <title>Affected by</title>
 593       <para>
 594         <simplelist>
 595           <!-- affected by -->
 596         </simplelist>
 597       </para>
 598     </refsect1>
 599     <refsect1>
 600       <title>Exceptional Situations</title>
 601       <para>
 602         <!-- execeptional situations -->
 603       </para>
 604     </refsect1>
 605     <refsect1>
 606       <title>See Also</title>
 607       <para>
 608         <simplelist>
 609           <!-- see also -->
 610         </simplelist>
 611       </para>
 612     </refsect1>
 613     <refsect1>
 614       <title>Notes</title>
 615       <para>
 616         <!-- notes -->
 617       </para>
 618     </refsect1>
 619   </refentry>
 620
 621     <refentry id="loop-tuples">
 622       <refnamediv>
 623         <refname>LOOP-FOR-AS-TUPLES</refname>
 624         <refpurpose>Iterate over all the tuples of a
 625         query via a loop clause</refpurpose>
 626         <refclass>Loop Clause</refclass>
 627       </refnamediv>
 628       <refsect1>
 629         <title>Compatibility</title>
 630         <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
 631       </refsect1>
 632       <refsect1>
 633         <title>Syntax</title>
 634         <synopsis><replaceable>var</replaceable> [<replaceable>type-spec</replaceable>] being {each | the} {record | records | tuple | tuples} {in | of} <replaceable>query</replaceable> [from <replaceable>database</replaceable>]</synopsis>
 635       </refsect1>
 636       <refsect1>
 637         <title>Arguments and Values</title>
 638         <variablelist>
 639           <varlistentry>
 640             <term><parameter>var</parameter></term>
 641             <listitem>
 642               <para>A <literal>d-var-spec</literal>, as defined in the
 643                 grammar for <function>loop</function>-clauses in the
 644                 ANSI Standard for Common Lisp.  This allows for the
 645                 usual loop-style destructuring.</para>
 646             </listitem>
 647           </varlistentry>
 648           <varlistentry>
 649             <term><parameter>type-spec</parameter></term>
 650             <listitem>
 651               <para>An optional <literal>type-spec</literal> either
 652                 simple or destructured, as defined in the grammar for
 653                 <function>loop</function>-clauses in the ANSI Standard
 654                 for Common Lisp.</para>
 655             </listitem>
 656           </varlistentry>
 657           <varlistentry>
 658             <term><parameter>query</parameter></term>
 659             <listitem>
 660               <para>An <glossterm linkend="gloss-sql-expression">sql
 661                   expression</glossterm> that represents an SQL
 662                 query which is expected to return a (possibly empty)
 663                 result set, where each tuple has as many attributes as
 664                 <parameter>function</parameter> takes arguments.</para>
 665             </listitem>
 666           </varlistentry>
 667           <varlistentry>
 668             <term><parameter>database</parameter></term>
 669             <listitem>
 670               <para>An optional
 671                 <glossterm linkend="gloss-database-object">database
 672                   object</glossterm>. This will default to the value
 673                 of <symbol>*default-database*</symbol>.</para>
 674             </listitem>
 675           </varlistentry>
 676         </variablelist>
 677       </refsect1>
 678       <refsect1>
 679         <title>Description</title>
 680         <para>This clause is an iteration driver for
 681         <function>loop</function>, that binds the given variable
 682           (possibly destructured) to the consecutive tuples (which are
 683           represented as lists of attribute values) in the result set
 684           returned by executing the SQL <parameter>query</parameter>
 685           expression on the <parameter>database</parameter>
 686           specified.</para>
 687       </refsect1>
 688       <refsect1>
 689         <title>Examples</title>
 690         <screen>
 691 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
 692   "My database"
 693 => *MY-DB*
 694 (loop with time-graph = (make-hash-table :test #'equal)
 695       with event-graph = (make-hash-table :test #'equal)
 696       for (time event) being the tuples of "select time,event from log"
 697       from *my-db*
 698       do
 699       (incf (gethash time time-graph 0))
 700       (incf (gethash event event-graph 0))
 701       finally
 702       (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
 703         (format t "~&amp;Time-Graph:~%===========~%")
 704         (maphash #'show-graph time-graph)
 705         (format t "~&amp;~%Event-Graph:~%============~%")
 706         (maphash #'show-graph event-graph))
 707       (return (values time-graph event-graph)))
 708 >> Time-Graph:
 709 >> ===========
 710 >> D                                        => 53000
 711 >> X                                        =>     3
 712 >> test-me                                  =>  3000
 713 >>
 714 >> Event-Graph:
 715 >> ============
 716 >> CLOS Benchmark entry.                    =>  9000
 717 >> Demo Text...                             =>     3
 718 >> doit-text                                =>  3000
 719 >> C    Benchmark entry.                    => 12000
 720 >> CLOS Benchmark entry                     => 32000
 721 => #&lt;EQUAL hash table, 3 entries {48350A1D}>
 722 => #&lt;EQUAL hash table, 5 entries {48350FCD}>
 723         </screen>
 724       </refsect1>
 725       <refsect1>
 726         <title>Side Effects</title>
 727         <para>Whatever effects the execution of the SQL query has
 728           on the underlying database, if any.</para>
 729       </refsect1>
 730       <refsect1>
 731         <title>Affected by</title>
 732         <para>None.</para>
 733       </refsect1>
 734       <refsect1>
 735         <title>Exceptional Situations</title>
 736         <para>If the execution of  the SQL query leads to any
 737           errors, an error of type
 738           <errortype>sql-database-error</errortype> is signalled.</para>
 739         <para>Otherwise, any of the exceptional situations of
 740           <function>loop</function> applies.</para>
 741       </refsect1>
 742       <refsect1>
 743         <title>See Also</title>
 744         <para>
 745         <simplelist>
 746           <member><link linkend="query"><function>query</function></link></member>
 747           <member><link linkend="map-query"><function>map-query</function></link></member>
 748           <member><link linkend="do-query"><function>do-query</function></link></member>
 749         </simplelist>
 750         </para>
 751       </refsect1>
 752       <refsect1>
 753         <title>Notes</title>
 754         <para>None.</para>
 755       </refsect1>
 756     </refentry>
 757
 758     <refentry id="map-query">
 759       <refnamediv>
 760         <refname>MAP-QUERY</refname>
 761         <refpurpose>Map a function over all the tuples from a
 762           query</refpurpose>
 763         <refclass>Function</refclass>
 764       </refnamediv>
 765       <refsect1>
 766         <title>Syntax</title>
 767         <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>
 768       </refsect1>
 769       <refsect1>
 770         <title>Arguments and Values</title>
 771         <variablelist>
 772           <varlistentry>
 773             <term><parameter>output-type-spec</parameter></term>
 774             <listitem>
 775               <para>A sequence type specifier or <symbol>nil</symbol>.</para>
 776             </listitem>
 777           </varlistentry>
 778           <varlistentry>
 779             <term><parameter>function</parameter></term>
 780             <listitem>
 781               <para>A function designator.
 782                 <parameter>function</parameter> takes a single argument which
 783                 is the atom value for a query single with a single column
 784                 or is a list of values for a multi-column query.</para>
 785             </listitem>
 786           </varlistentry>
 787           <varlistentry>
 788             <term><parameter>query-expression</parameter></term>
 789             <listitem>
 790               <para>An <glossterm linkend="gloss-sql-expression">sql
 791                   expression</glossterm> that represents an SQL
 792                 query which is expected to return a (possibly empty)
 793                 result set.</para>
 794             </listitem>
 795           </varlistentry>
 796           <varlistentry>
 797             <term><parameter>database</parameter></term>
 798             <listitem>
 799               <para>A
 800                 <glossterm linkend="gloss-database-object">database
 801                   object</glossterm>. This will default to the value
 802                 of <symbol>*default-database*</symbol>.</para>
 803             </listitem>
 804           </varlistentry>
 805           <varlistentry>
 806             <term><parameter>result-types</parameter></term>
 807             <listitem>
 808               <para>
 809                 A <glossterm linkend="gloss-field-types">field type specifier</glossterm>.
 810                 The default is &nil;. See <link
 811                 linkend="query"><function>query</function></link>
 812                 for the semantics of this argument.
 813               </para>
 814             </listitem>
 815           </varlistentry>
 816           <varlistentry>
 817             <term><returnvalue>result</returnvalue></term>
 818             <listitem>
 819               <para>If <parameter>output-type-spec</parameter> is a
 820                 type specifier other than <symbol>nil</symbol>, then a
 821                 sequence of the type it denotes.  Otherwise
 822                 <symbol>nil</symbol> is returned.</para>
 823             </listitem>
 824           </varlistentry>
 825         </variablelist>
 826       </refsect1>
 827       <refsect1>
 828         <title>Description</title>
 829         <para>Applies <parameter>function</parameter> to the
 830           successive tuples in the result set returned
 831           by executing the SQL
 832           <parameter>query-expression</parameter>.  If the
 833           <parameter>output-type-spec</parameter> is
 834           <symbol>nil</symbol>, then the result of each application
 835           of <parameter>function</parameter> is discarded, and
 836           <function>map-query</function> returns
 837           <symbol>nil</symbol>.  Otherwise the result of each
 838           successive application of <parameter>function</parameter> is
 839           collected in a sequence of type
 840           <parameter>output-type-spec</parameter>, where the jths
 841           element is the result of applying
 842           <parameter>function</parameter> to the attributes of the
 843           jths tuple in the result set.  The collected sequence is the
 844           result of the call to <function>map-query</function>.
 845         </para>
 846         <para>If the <parameter>output-type-spec</parameter> is a
 847           subtype of <type>list</type>, the result will be a
 848           <type>list</type>.</para>
 849         <para>If the <parameter>result-type</parameter> is a subtype
 850           of <type>vector</type>, then if the implementation can
 851           determine the element type specified for the
 852           <parameter>result-type</parameter>, the element type of the
 853           resulting array is the result of
 854           <emphasis>upgrading</emphasis> that element type; or, if the
 855           implementation can determine that the element type is
 856           unspecified (or <symbol>*</symbol>), the element type of the
 857           resulting array is <type>t</type>; otherwise, an error is
 858           signaled.</para>
 859         <para>If RESULT-TYPES is nil all results are returned as
 860         strings whereas the default value of :auto means that the lisp
 861         types are automatically computed for each field.</para>
 862       </refsect1>
 863       <refsect1>
 864         <title>Examples</title>
 865         <screen>
 866 (map-query 'list #'(lambda (tuple)
 867                      (multiple-value-bind (salary name) tuple
 868                        (declare (ignorable name))
 869                        (read-from-string salary)))
 870            "select salary,name from simple where salary > 8000")
 871 => (10000.0 8000.5)
 872
 873 (map-query '(vector double-float)
 874            #'(lambda (tuple)
 875                (multiple-value-bind (salary name) tuple
 876                  (declare (ignorable name))
 877                  (let ((*read-default-float-format* 'double-float))
 878                    (coerce (read-from-string salary) 'double-float))
 879                     "select salary,name from simple where salary > 8000")))
 880 => #(10000.0d0 8000.5d0)
 881 (type-of *)
 882 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
 883
 884 (let (list)
 885   (values (map-query nil #'(lambda (tuple)
 886                              (multiple-value-bind (salary name) tuple
 887                                (push (cons name (read-from-string salary)) list))
 888                      "select salary,name from simple where salary > 8000")
 889           list))
 890 => NIL
 891 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
 892         </screen>
 893       </refsect1>
 894       <refsect1>
 895         <title>Side Effects</title>
 896         <para>Whatever effects the execution of the SQL query has
 897           on the underlying database, if any.</para>
 898       </refsect1>
 899       <refsect1>
 900         <title>Affected by</title>
 901         <para>None.</para>
 902       </refsect1>
 903       <refsect1>
 904         <title>Exceptional Situations</title>
 905         <para>If the execution of  the SQL query leads to any
 906           errors, an error of type
 907           <errortype>sql-database-error</errortype> is signalled.</para>
 908         <para>An error of type <errortype>type-error</errortype> must
 909           be signaled if the <parameter>output-type-spec</parameter> is
 910           not a recognizable subtype of <type>list</type>, not a
 911           recognizable subtype of <type>vector</type>, and not
 912           <symbol>nil</symbol>.</para>
 913         <para>An error of type <errortype>type-error</errortype>
 914           should be signaled if
 915           <parameter>output-type-spec</parameter> specifies the number
 916           of elements and the size of the result set is different from
 917           that number.</para>
 918       </refsect1>
 919       <refsect1>
 920         <title>See Also</title>
 921         <para>
 922         <simplelist>
 923           <member><link linkend="query"><function>query</function></link></member>
 924           <member><link linkend="do-query"><function>do-query</function></link></member>
 925         </simplelist>
 926         </para>
 927       </refsect1>
 928       <refsect1>
 929         <title>Notes</title>
 930         <para>None.</para>
 931       </refsect1>
 932     </refentry>
 933
 934   <refentry id="prepare-sql">
 935     <refnamediv>
 936       <refname>PREPARE-SQL</refname>
 937       <refpurpose><!-- purpose --></refpurpose>
 938       <refclass>Function</refclass>
 939     </refnamediv>
 940     <refsect1>
 941       <title>Syntax</title>
 942       <synopsis>
 943       <function> (PREPARE-SQL SQL-STMT TYPES &amp;KEY (DATABASE *DEFAULT-DATABASE*) (RESULT-TYPES :AUTO) FIELD-NAMES) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
 944     </refsect1>
 945     <refsect1>
 946       <title>Arguments and Values</title>
 947       <variablelist>
 948         <!-- arguments and values -->
 949       </variablelist>
 950     </refsect1>
 951     <refsect1>
 952       <title>Description</title>
 953       <para>Prepares a SQL statement for execution. TYPES
 954       contains a list of types corresponding to the input
 955       parameters. Returns a prepared-statement object.
 956
 957       A type can be
 958       :int
 959       :double
 960       :null
 961       (:string n)
 962
 963       </para>
 964     </refsect1>
 965     <refsect1>
 966       <title>Examples</title>
 967       <screen>
 968         <!-- examples -->
 969       </screen>
 970     </refsect1>
 971     <refsect1>
 972       <title>Side Effects</title>
 973       <para>
 974         <!-- side effects -->
 975       </para>
 976     </refsect1>
 977     <refsect1>
 978       <title>Affected by</title>
 979       <para>
 980         <simplelist>
 981           <!-- affected by -->
 982         </simplelist>
 983       </para>
 984     </refsect1>
 985     <refsect1>
 986       <title>Exceptional Situations</title>
 987       <para>
 988         <!-- execeptional situations -->
 989       </para>
 990     </refsect1>
 991     <refsect1>
 992       <title>See Also</title>
 993       <para>
 994         <simplelist>
 995           <!-- see also -->
 996         </simplelist>
 997       </para>
 998     </refsect1>
 999     <refsect1>
1000       <title>Notes</title>
1001       <para>
1002         <!-- notes -->
1003       </para>
1004     </refsect1>
1005   </refentry>
1006
1007   <refentry id="print-query">
1008     <refnamediv>
1009       <refname>PRINT-QUERY</refname>
1010       <refpurpose><!-- purpose --></refpurpose>
1011       <refclass>Function</refclass>
1012     </refnamediv>
1013     <refsect1>
1014       <title>Syntax</title>
1015       <synopsis>
1016       <function> (PRINT-QUERY QUERY-EXP &amp;KEY TITLES (FORMATS T) (SIZES T) (STREAM T) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1017     </refsect1>
1018     <refsect1>
1019       <title>Arguments and Values</title>
1020       <variablelist>
1021         <!-- arguments and values -->
1022       </variablelist>
1023     </refsect1>
1024     <refsect1>
1025       <title>Description</title>
1026       <para>Prints a tabular report of the results returned by the
1027       SQL query QUERY-EXP, which may be a symbolic SQL expression or
1028       a string, in DATABASE which defaults to
1029       *DEFAULT-DATABASE*. The report is printed onto STREAM which
1030       has a default value of t which means that *STANDARD-OUTPUT* is
1031       used. The TITLE argument, which defaults to nil, allows the
1032       specification of a list of strings to use as column titles in
1033       the tabular output. SIZES accepts a list of column sizes, one
1034       for each column selected by QUERY-EXP, to use in formatting
1035       the tabular report. The default value of t means that minimum
1036       sizes are computed. FORMATS is a list of format strings to be
1037       used for printing each column selected by QUERY-EXP. The
1038       default value of FORMATS is t meaning that ~A is used to
1039       format all columns or ~VA if column sizes are used.
1040       </para>
1041     </refsect1>
1042     <refsect1>
1043       <title>Examples</title>
1044       <screen>
1045         <!-- examples -->
1046       </screen>
1047     </refsect1>
1048     <refsect1>
1049       <title>Side Effects</title>
1050       <para>
1051         <!-- side effects -->
1052       </para>
1053     </refsect1>
1054     <refsect1>
1055       <title>Affected by</title>
1056       <para>
1057         <simplelist>
1058           <!-- affected by -->
1059         </simplelist>
1060       </para>
1061     </refsect1>
1062     <refsect1>
1063       <title>Exceptional Situations</title>
1064       <para>
1065         <!-- execeptional situations -->
1066       </para>
1067     </refsect1>
1068     <refsect1>
1069       <title>See Also</title>
1070       <para>
1071         <simplelist>
1072           <!-- see also -->
1073         </simplelist>
1074       </para>
1075     </refsect1>
1076     <refsect1>
1077       <title>Notes</title>
1078       <para>
1079         <!-- notes -->
1080       </para>
1081     </refsect1>
1082   </refentry>
1083
1084
1085   <refentry id="query">
1086     <refnamediv>
1087       <refname>QUERY</refname>
1088       <refpurpose><!-- purpose --></refpurpose>
1089       <refclass>Function</refclass>
1090     </refnamediv>
1091     <refsect1>
1092       <title>Syntax</title>
1093       <synopsis>
1094       <function> (QUERY QUERY-EXPRESSION &amp;KEY DATABASE RESULT-TYPES FLATP FIELD-NAMES) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1095     </refsect1>
1096     <refsect1>
1097       <title>Arguments and Values</title>
1098       <variablelist>
1099         <!-- arguments and values -->
1100       </variablelist>
1101     </refsect1>
1102     <refsect1>
1103       <title>Description</title>
1104       <para>Executes the SQL query expression QUERY-EXPRESSION,
1105       which may be an SQL expression or a string, on the supplied
1106       DATABASE which defaults to *DEFAULT-DATABASE*. RESULT-TYPES is
1107       a list of symbols which specifies the lisp type for each field
1108       returned by QUERY-EXPRESSION. If RESULT-TYPES is nil all
1109       results are returned as strings whereas the default value of
1110       :auto means that the lisp types are automatically computed for
1111       each field. FIELD-NAMES is t by default which means that the
1112       second value returned is a list of strings representing the
1113       columns selected by QUERY-EXPRESSION. If FIELD-NAMES is nil,
1114       the list of column names is not returned as a second
1115       value. FLATP has a default value of nil which means that the
1116       results are returned as a list of lists. If FLATP is t and
1117       only one result is returned for each record selected by
1118       QUERY-EXPRESSION, the results are returned as elements of a
1119       list.
1120       </para>
1121     </refsect1>
1122     <refsect1>
1123       <title>Examples</title>
1124       <screen>
1125         <!-- examples -->
1126       </screen>
1127     </refsect1>
1128     <refsect1>
1129       <title>Side Effects</title>
1130       <para>
1131         <!-- side effects -->
1132       </para>
1133     </refsect1>
1134     <refsect1>
1135       <title>Affected by</title>
1136       <para>
1137         <simplelist>
1138           <!-- affected by -->
1139         </simplelist>
1140       </para>
1141     </refsect1>
1142     <refsect1>
1143       <title>Exceptional Situations</title>
1144       <para>
1145         <!-- execeptional situations -->
1146       </para>
1147     </refsect1>
1148     <refsect1>
1149       <title>See Also</title>
1150       <para>
1151         <simplelist>
1152           <!-- see also -->
1153         </simplelist>
1154       </para>
1155     </refsect1>
1156     <refsect1>
1157       <title>Notes</title>
1158       <para>
1159         <!-- notes -->
1160       </para>
1161     </refsect1>
1162   </refentry>
1163
1164
1165   <refentry id="run-prepared-sql">
1166     <refnamediv>
1167       <refname>RUN-PREPARED-SQL</refname>
1168       <refpurpose><!-- purpose --></refpurpose>
1169       <refclass>Function</refclass>
1170     </refnamediv>
1171     <refsect1>
1172       <title>Syntax</title>
1173       <synopsis>
1174       <function> (RUN-PREPARED-SQL PREPARED-STMT) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1175     </refsect1>
1176     <refsect1>
1177       <title>Arguments and Values</title>
1178       <variablelist>
1179         <!-- arguments and values -->
1180       </variablelist>
1181     </refsect1>
1182     <refsect1>
1183       <title>Description</title>
1184       <para>Execute the prepared sql statment. All input
1185       parameters must be bound.
1186       </para>
1187     </refsect1>
1188     <refsect1>
1189       <title>Examples</title>
1190       <screen>
1191         <!-- examples -->
1192       </screen>
1193     </refsect1>
1194     <refsect1>
1195       <title>Side Effects</title>
1196       <para>
1197         <!-- side effects -->
1198       </para>
1199     </refsect1>
1200     <refsect1>
1201       <title>Affected by</title>
1202       <para>
1203         <simplelist>
1204           <!-- affected by -->
1205         </simplelist>
1206       </para>
1207     </refsect1>
1208     <refsect1>
1209       <title>Exceptional Situations</title>
1210       <para>
1211         <!-- execeptional situations -->
1212       </para>
1213     </refsect1>
1214     <refsect1>
1215       <title>See Also</title>
1216       <para>
1217         <simplelist>
1218           <!-- see also -->
1219         </simplelist>
1220       </para>
1221     </refsect1>
1222     <refsect1>
1223       <title>Notes</title>
1224       <para>
1225         <!-- notes -->
1226       </para>
1227     </refsect1>
1228   </refentry>
1229
1230   <refentry id="select">
1231     <refnamediv>
1232       <refname>SELECT</refname>
1233       <refpurpose><!-- purpose --></refpurpose>
1234       <refclass>Function</refclass>
1235     </refnamediv>
1236     <refsect1>
1237       <title>Syntax</title>
1238       <synopsis>
1239       <function> (SELECT &amp;REST SELECT-ALL-ARGS) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1240     </refsect1>
1241     <refsect1>
1242       <title>Arguments and Values</title>
1243       <variablelist>
1244         <!-- arguments and values -->
1245       </variablelist>
1246     </refsect1>
1247     <refsect1>
1248       <title>Description</title>
1249       <para>Executes a query on DATABASE, which has a
1250       default value of *DEFAULT-DATABASE*, specified by the
1251       SQL expressions supplied using the remaining arguments
1252       in SELECT-ALL-ARGS. The SELECT argument can be used to
1253       generate queries in both functional and object
1254       oriented contexts.
1255
1256       In the functional case, the required arguments specify
1257       the columns selected by the query and may be symbolic
1258       SQL expressions or strings representing attribute
1259       identifiers. Type modified identifiers indicate that
1260       the values selected from the specified column are
1261       converted to the specified lisp type. The keyword
1262       arguments ALL, DISTINCT, FROM, GROUP-by, HAVING,
1263       ORDER-BY, SET-OPERATION and WHERE are used to specify,
1264       using the symbolic SQL syntax, the corresponding
1265       components of the SQL query generated by the call to
1266       SELECT. RESULT-TYPES is a list of symbols which
1267       specifies the lisp type for each field returned by the
1268       query. If RESULT-TYPES is nil all results are returned
1269       as strings whereas the default value of :auto means
1270       that the lisp types are automatically computed for
1271       each field. FIELD-NAMES is t by default which means
1272       that the second value returned is a list of strings
1273       representing the columns selected by the query. If
1274       FIELD-NAMES is nil, the list of column names is not
1275       returned as a second value.
1276
1277       In the object oriented case, the required arguments to
1278       SELECT are symbols denoting View Classes which specify
1279       the database tables to query. In this case, SELECT
1280       returns a list of View Class instances whose slots are
1281       set from the attribute values of the records in the
1282       specified table. Slot-value is a legal operator which
1283       can be employed as part of the symbolic SQL syntax
1284       used in the WHERE keyword argument to SELECT. REFRESH
1285       is nil by default which means that the View Class
1286       instances returned are retrieved from a cache if an
1287       equivalent call to SELECT has previously been
1288       issued. If REFRESH is true, the View Class instances
1289       returned are updated as necessary from the database
1290       and the generic function INSTANCE-REFRESHED is called
1291       to perform any necessary operations on the updated
1292       instances.
1293
1294       In both object oriented and functional contexts, FLATP
1295       has a default value of nil which means that the
1296       results are returned as a list of lists. If FLATP is t
1297       and only one result is returned for each record
1298       selected in the query, the results are returned as
1299       elements of a list.
1300       </para>
1301     </refsect1>
1302     <refsect1>
1303       <title>Examples</title>
1304       <screen>
1305         <!-- examples -->
1306       </screen>
1307     </refsect1>
1308     <refsect1>
1309       <title>Side Effects</title>
1310       <para>
1311         <!-- side effects -->
1312       </para>
1313     </refsect1>
1314     <refsect1>
1315       <title>Affected by</title>
1316       <para>
1317         <simplelist>
1318           <!-- affected by -->
1319         </simplelist>
1320       </para>
1321     </refsect1>
1322     <refsect1>
1323       <title>Exceptional Situations</title>
1324       <para>
1325         <!-- execeptional situations -->
1326       </para>
1327     </refsect1>
1328     <refsect1>
1329       <title>See Also</title>
1330       <para>
1331         <simplelist>
1332           <!-- see also -->
1333         </simplelist>
1334       </para>
1335     </refsect1>
1336     <refsect1>
1337       <title>Notes</title>
1338       <para>
1339         <!-- notes -->
1340       </para>
1341     </refsect1>
1342   </refentry>
1343
1344
1345
1346   <refentry id="update-records">
1347     <refnamediv>
1348       <refname>UPDATE-RECORDS</refname>
1349       <refpurpose><!-- purpose --></refpurpose>
1350       <refclass>Function</refclass>
1351     </refnamediv>
1352     <refsect1>
1353       <title>Syntax</title>
1354       <synopsis>
1355       <function> (UPDATE-RECORDS TABLE &amp;KEY (ATTRIBUTES NIL) (VALUES NIL) (AV-PAIRS NIL) (WHERE NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1356     </refsect1>
1357     <refsect1>
1358       <title>Arguments and Values</title>
1359       <variablelist>
1360         <!-- arguments and values -->
1361       </variablelist>
1362     </refsect1>
1363     <refsect1>
1364       <title>Description</title>
1365       <para>Updates the attribute values of existing records
1366       satsifying the SQL expression WHERE in the table specified by
1367       TABLE in DATABASE which defaults to *DEFAULT-DATABASE*. There
1368       are three ways of specifying the values to update for each
1369       row. In the first, VALUES contains a list of values to use in
1370       the update and ATTRIBUTES, AV-PAIRS and QUERY are nil. This
1371       can be used when values are supplied for all attributes in
1372       TABLE. In the second, ATTRIBUTES is a list of column names,
1373       VALUES is a corresponding list of values and AV-PAIRS and
1374       QUERY are nil. In the third, ATTRIBUTES, VALUES and QUERY are
1375       nil and AV-PAIRS is an alist of (attribute value) pairs.
1376       </para>
1377     </refsect1>
1378     <refsect1>
1379       <title>Examples</title>
1380       <screen>
1381         <!-- examples -->
1382       </screen>
1383     </refsect1>
1384     <refsect1>
1385       <title>Side Effects</title>
1386       <para>
1387         <!-- side effects -->
1388       </para>
1389     </refsect1>
1390     <refsect1>
1391       <title>Affected by</title>
1392       <para>
1393         <simplelist>
1394           <!-- affected by -->
1395         </simplelist>
1396       </para>
1397     </refsect1>
1398     <refsect1>
1399       <title>Exceptional Situations</title>
1400       <para>
1401         <!-- execeptional situations -->
1402       </para>
1403     </refsect1>
1404     <refsect1>
1405       <title>See Also</title>
1406       <para>
1407         <simplelist>
1408           <!-- see also -->
1409         </simplelist>
1410       </para>
1411     </refsect1>
1412     <refsect1>
1413       <title>Notes</title>
1414       <para>
1415         <!-- notes -->
1416       </para>
1417     </refsect1>
1418   </refentry>
1419
1420
1421
1422 </reference>