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">
8 <!-- Functional Data Manipulation Language -->
9 <reference id="ref-fdml">
10 <title>Functional Data Manipulation Language (FDML)</title>
17 <refentry id="cache-table-queries-default">
19 <refname>*CACHE-TABLE-QUERIES-DEFAULT*</refname>
20 <refpurpose><!-- purpose --></refpurpose>
21 <refclass>Variable</refclass>
24 <title>Value Type</title>
30 <title>Initial Value</title>
31 <para><symbol>nil</symbol></para>
34 <title>Description</title>
38 <title>Examples</title>
44 <title>Affected By</title>
48 <title>See Also</title>
59 <refentry id="bind-parameter">
61 <refname>BIND-PARAMETER</refname>
62 <refpurpose><!-- purpose --></refpurpose>
63 <refclass>Function</refclass>
68 <function> (BIND-PARAMETER PREPARED-STMT POSITION VALUE) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
71 <title>Arguments and Values</title>
73 <!-- arguments and values -->
77 <title>Description</title>
78 <para>Sets the value of a parameter in a prepared statement.
82 <title>Examples</title>
88 <title>Side Effects</title>
94 <title>Affected by</title>
102 <title>Exceptional Situations</title>
104 <!-- execeptional situations -->
108 <title>See Also</title>
123 <refentry id="cache-table-queries">
125 <refname>CACHE-TABLE-QUERIES</refname>
126 <refpurpose><!-- purpose --></refpurpose>
127 <refclass>Function</refclass>
130 <title>Syntax</title>
132 <function> (CACHE-TABLE-QUERIES TABLE &KEY (ACTION NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
135 <title>Arguments and Values</title>
137 <!-- arguments and values -->
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
159 <title>Examples</title>
165 <title>Side Effects</title>
167 <!-- side effects -->
171 <title>Affected by</title>
179 <title>Exceptional Situations</title>
181 <!-- execeptional situations -->
185 <title>See Also</title>
201 <refentry id="delete-records">
203 <refname>DELETE-RECORDS</refname>
204 <refpurpose><!-- purpose --></refpurpose>
205 <refclass>Function</refclass>
208 <title>Syntax</title>
210 <function> (DELETE-RECORDS &KEY (FROM NIL) (WHERE NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
213 <title>Arguments and Values</title>
215 <!-- arguments and values -->
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
227 <title>Examples</title>
233 <title>Side Effects</title>
235 <!-- side effects -->
239 <title>Affected by</title>
247 <title>Exceptional Situations</title>
249 <!-- execeptional situations -->
253 <title>See Also</title>
269 <refentry id="do-query">
271 <refname>DO-QUERY</refname>
272 <refpurpose><!-- purpose --></refpurpose>
273 <refclass>Function</refclass>
276 <title>Syntax</title>
278 <function> (DO-QUERY &KEY (DATABASE '*DEFAULT-DATABASE*) (RESULT-TYPES :AUTO) &REST QUERY-EXPRESSION &BODY BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
281 <title>Arguments and Values</title>
283 <!-- arguments and values -->
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.
302 <title>Examples</title>
308 <title>Side Effects</title>
310 <!-- side effects -->
314 <title>Affected by</title>
322 <title>Exceptional Situations</title>
324 <!-- execeptional situations -->
328 <title>See Also</title>
343 <refentry id="execute-command">
345 <refname>EXECUTE-COMMAND</refname>
346 <refpurpose><!-- purpose --></refpurpose>
347 <refclass>Function</refclass>
350 <title>Syntax</title>
352 <function> (EXECUTE-COMMAND EXPRESSION &KEY DATABASE) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
355 <title>Arguments and Values</title>
357 <!-- arguments and values -->
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
369 <title>Examples</title>
375 <title>Side Effects</title>
377 <!-- side effects -->
381 <title>Affected by</title>
389 <title>Exceptional Situations</title>
391 <!-- execeptional situations -->
395 <title>See Also</title>
410 <refentry id="for-each-row">
412 <refname>FOR-EACH-ROW</refname>
413 <refpurpose><!-- purpose --></refpurpose>
414 <refclass>Function</refclass>
417 <title>Syntax</title>
419 <function> (FOR-EACH-ROW &KEY FROM ORDER-BY WHERE DISTINCT LIMIT &REST FIELDS &BODY BODY) [macro]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
422 <title>Arguments and Values</title>
424 <!-- arguments and values -->
428 <title>Description</title>
434 <title>Examples</title>
440 <title>Side Effects</title>
442 <!-- side effects -->
446 <title>Affected by</title>
454 <title>Exceptional Situations</title>
456 <!-- execeptional situations -->
460 <title>See Also</title>
463 <!-- see also list here -->
475 <refentry id="free-prepared-sql">
477 <refname>FREE-PREPARED-SQL</refname>
478 <refpurpose><!-- purpose --></refpurpose>
479 <refclass>Function</refclass>
482 <title>Syntax</title>
484 <function> (FREE-PREPARED-SQL PREPARED-STMT) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
487 <title>Arguments and Values</title>
489 <!-- arguments and values -->
493 <title>Description</title>
494 <para>Delete the objects associated with a prepared
499 <title>Examples</title>
505 <title>Side Effects</title>
507 <!-- side effects -->
511 <title>Affected by</title>
519 <title>Exceptional Situations</title>
521 <!-- execeptional situations -->
525 <title>See Also</title>
540 <refentry id="insert-records">
542 <refname>INSERT-RECORDS</refname>
543 <refpurpose><!-- purpose --></refpurpose>
544 <refclass>Function</refclass>
547 <title>Syntax</title>
549 <function> (INSERT-RECORDS &KEY (INTO NIL) (ATTRIBUTES NIL) (VALUES NIL) (AV-PAIRS NIL) (QUERY NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
552 <title>Arguments and Values</title>
554 <!-- arguments and values -->
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.
580 <title>Examples</title>
586 <title>Side Effects</title>
588 <!-- side effects -->
592 <title>Affected by</title>
600 <title>Exceptional Situations</title>
602 <!-- execeptional situations -->
606 <title>See Also</title>
621 <refentry id="loop-tuples">
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>
629 <title>Compatibility</title>
630 <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
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>
637 <title>Arguments and Values</title>
640 <term><parameter>var</parameter></term>
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>
649 <term><parameter>type-spec</parameter></term>
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>
658 <term><parameter>query</parameter></term>
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>
668 <term><parameter>database</parameter></term>
671 <glossterm linkend="gloss-database-object">database
672 object</glossterm>. This will default to the value
673 of <symbol>*default-database*</symbol>.</para>
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>
689 <title>Examples</title>
691 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
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"
699 (incf (gethash time time-graph 0))
700 (incf (gethash event event-graph 0))
702 (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
703 (format t "~&Time-Graph:~%===========~%")
704 (maphash #'show-graph time-graph)
705 (format t "~&~%Event-Graph:~%============~%")
706 (maphash #'show-graph event-graph))
707 (return (values time-graph event-graph)))
716 >> CLOS Benchmark entry. => 9000
719 >> C Benchmark entry. => 12000
720 >> CLOS Benchmark entry => 32000
721 => #<EQUAL hash table, 3 entries {48350A1D}>
722 => #<EQUAL hash table, 5 entries {48350FCD}>
726 <title>Side Effects</title>
727 <para>Whatever effects the execution of the SQL query has
728 on the underlying database, if any.</para>
731 <title>Affected by</title>
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>
743 <title>See Also</title>
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>
758 <refentry id="map-query">
760 <refname>MAP-QUERY</refname>
761 <refpurpose>Map a function over all the tuples from a
763 <refclass>Function</refclass>
766 <title>Syntax</title>
767 <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>result-types</replaceable> => <returnvalue>result</returnvalue></synopsis>
770 <title>Arguments and Values</title>
773 <term><parameter>output-type-spec</parameter></term>
775 <para>A sequence type specifier or <symbol>nil</symbol>.</para>
779 <term><parameter>function</parameter></term>
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>
788 <term><parameter>query-expression</parameter></term>
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)
797 <term><parameter>database</parameter></term>
800 <glossterm linkend="gloss-database-object">database
801 object</glossterm>. This will default to the value
802 of <symbol>*default-database*</symbol>.</para>
806 <term><parameter>result-types</parameter></term>
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.
817 <term><returnvalue>result</returnvalue></term>
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>
828 <title>Description</title>
829 <para>Applies <parameter>function</parameter> to the
830 successive tuples in the result set returned
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>.
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
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>
864 <title>Examples</title>
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")
873 (map-query '(vector double-float)
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)
882 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
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")
891 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
895 <title>Side Effects</title>
896 <para>Whatever effects the execution of the SQL query has
897 on the underlying database, if any.</para>
900 <title>Affected by</title>
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
920 <title>See Also</title>
923 <member><link linkend="query"><function>query</function></link></member>
924 <member><link linkend="do-query"><function>do-query</function></link></member>
934 <refentry id="prepare-sql">
936 <refname>PREPARE-SQL</refname>
937 <refpurpose><!-- purpose --></refpurpose>
938 <refclass>Function</refclass>
941 <title>Syntax</title>
943 <function> (PREPARE-SQL SQL-STMT TYPES &KEY (DATABASE *DEFAULT-DATABASE*) (RESULT-TYPES :AUTO) FIELD-NAMES) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
946 <title>Arguments and Values</title>
948 <!-- arguments and values -->
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.
966 <title>Examples</title>
972 <title>Side Effects</title>
974 <!-- side effects -->
978 <title>Affected by</title>
986 <title>Exceptional Situations</title>
988 <!-- execeptional situations -->
992 <title>See Also</title>
1000 <title>Notes</title>
1007 <refentry id="print-query">
1009 <refname>PRINT-QUERY</refname>
1010 <refpurpose><!-- purpose --></refpurpose>
1011 <refclass>Function</refclass>
1014 <title>Syntax</title>
1016 <function> (PRINT-QUERY QUERY-EXP &KEY TITLES (FORMATS T) (SIZES T) (STREAM T) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1019 <title>Arguments and Values</title>
1021 <!-- arguments and values -->
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.
1043 <title>Examples</title>
1049 <title>Side Effects</title>
1051 <!-- side effects -->
1055 <title>Affected by</title>
1058 <!-- affected by -->
1063 <title>Exceptional Situations</title>
1065 <!-- execeptional situations -->
1069 <title>See Also</title>
1077 <title>Notes</title>
1085 <refentry id="query">
1087 <refname>QUERY</refname>
1088 <refpurpose><!-- purpose --></refpurpose>
1089 <refclass>Function</refclass>
1092 <title>Syntax</title>
1094 <function> (QUERY QUERY-EXPRESSION &KEY DATABASE RESULT-TYPES FLATP FIELD-NAMES) [generic]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1097 <title>Arguments and Values</title>
1099 <!-- arguments and values -->
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
1123 <title>Examples</title>
1129 <title>Side Effects</title>
1131 <!-- side effects -->
1135 <title>Affected by</title>
1138 <!-- affected by -->
1143 <title>Exceptional Situations</title>
1145 <!-- execeptional situations -->
1149 <title>See Also</title>
1157 <title>Notes</title>
1165 <refentry id="run-prepared-sql">
1167 <refname>RUN-PREPARED-SQL</refname>
1168 <refpurpose><!-- purpose --></refpurpose>
1169 <refclass>Function</refclass>
1172 <title>Syntax</title>
1174 <function> (RUN-PREPARED-SQL PREPARED-STMT) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1177 <title>Arguments and Values</title>
1179 <!-- arguments and values -->
1183 <title>Description</title>
1184 <para>Execute the prepared sql statment. All input
1185 parameters must be bound.
1189 <title>Examples</title>
1195 <title>Side Effects</title>
1197 <!-- side effects -->
1201 <title>Affected by</title>
1204 <!-- affected by -->
1209 <title>Exceptional Situations</title>
1211 <!-- execeptional situations -->
1215 <title>See Also</title>
1223 <title>Notes</title>
1230 <refentry id="select">
1232 <refname>SELECT</refname>
1233 <refpurpose><!-- purpose --></refpurpose>
1234 <refclass>Function</refclass>
1237 <title>Syntax</title>
1239 <function> (SELECT &REST SELECT-ALL-ARGS) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1242 <title>Arguments and Values</title>
1244 <!-- arguments and values -->
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
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.
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
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
1303 <title>Examples</title>
1309 <title>Side Effects</title>
1311 <!-- side effects -->
1315 <title>Affected by</title>
1318 <!-- affected by -->
1323 <title>Exceptional Situations</title>
1325 <!-- execeptional situations -->
1329 <title>See Also</title>
1337 <title>Notes</title>
1346 <refentry id="update-records">
1348 <refname>UPDATE-RECORDS</refname>
1349 <refpurpose><!-- purpose --></refpurpose>
1350 <refclass>Function</refclass>
1353 <title>Syntax</title>
1355 <function> (UPDATE-RECORDS TABLE &KEY (ATTRIBUTES NIL) (VALUES NIL) (AV-PAIRS NIL) (WHERE NIL) (DATABASE *DEFAULT-DATABASE*)) [function]</function> => <returnvalue><!-- result --></returnvalue></synopsis>
1358 <title>Arguments and Values</title>
1360 <!-- arguments and values -->
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.
1379 <title>Examples</title>
1385 <title>Side Effects</title>
1387 <!-- side effects -->
1391 <title>Affected by</title>
1394 <!-- affected by -->
1399 <title>Exceptional Situations</title>
1401 <!-- execeptional situations -->
1405 <title>See Also</title>
1413 <title>Notes</title>