1 <!-- -*- DocBook -*- -->
4 <title><symbol>CLSQL</symbol></title>
6 <para>This part gives a reference to all the symbols exported
7 from the package <symbol>CLSQL-SYS</symbol>, which are also
8 re-exported from the package <symbol>CLSQL</symbol>. These
9 symbols constitute the normal user-interface of
13 <refentry id="maisql-condition">
15 <refname>CLSQL-CONDITION</refname>
16 <refpurpose>the super-type of all
18 conditions</refpurpose>
19 <refclass>Condition Type</refclass>
22 <title>Class Precedence List</title>
24 <simplelist type="inline">
25 <member><errortype>maisql-condition</errortype></member>
26 <member><errortype>condition</errortype></member>
27 <member><errortype>t</errortype></member>
32 <title>Description</title>
33 <para>This is the super-type of all
34 &clsql;-specific conditions
35 defined by &clsql;, or any of it's
36 database-specific interfaces. There are no defined
37 initialization arguments nor any accessors.</para>
40 <refentry id="maisql-error">
42 <refname>CLSQL-ERROR</refname>
43 <refpurpose>the super-type of all
46 <refclass>Condition Type</refclass>
49 <title>Class Precedence List</title>
51 <simplelist type="inline">
52 <member><errortype>maisql-error</errortype></member>
53 <member><errortype>error</errortype></member>
54 <member><errortype>serious-condition</errortype></member>
55 <member><errortype>maisql-condition</errortype></member>
56 <member><errortype>condition</errortype></member>
57 <member><errortype>t</errortype></member>
62 <title>Description</title>
63 <para>This is the super-type of all
64 &clsql;-specific conditions that
65 represent errors, as defined by
66 &clsql;, or any of it's
67 database-specific interfaces. There are no defined
68 initialization arguments nor any accessors.</para>
71 <refentry id="maisql-simple-error">
73 <refname>CLSQL-SIMPLE-ERROR</refname>
74 <refpurpose>Unspecific simple
75 &clsql; errors</refpurpose>
76 <refclass>Condition Type</refclass>
79 <title>Class Precedence List</title>
81 <simplelist type="inline">
82 <member><errortype>maisql-simple-error</errortype></member>
83 <member><errortype>simple-condition</errortype></member>
84 <member><errortype>maisql-error</errortype></member>
85 <member><errortype>error</errortype></member>
86 <member><errortype>serious-condition</errortype></member>
87 <member><errortype>maisql-condition</errortype></member>
88 <member><errortype>condition</errortype></member>
89 <member><errortype>t</errortype></member>
94 <title>Description</title>
95 <para>This condition is used in all instances of errors, where
96 there exists no &clsql;-specific
97 condition that is more specific. The valid initialization
98 arguments and accessors are the same as for
99 <errortype>simple-condition</errortype>.</para>
102 <refentry id="maisql-warning">
104 <refname>CLSQL-WARNING</refname>
105 <refpurpose>the super-type of all
107 warnings</refpurpose>
108 <refclass>Condition Type</refclass>
111 <title>Class Precedence List</title>
113 <simplelist type="inline">
114 <member><errortype>maisql-warning</errortype></member>
115 <member><errortype>warning</errortype></member>
116 <member><errortype>maisql-condition</errortype></member>
117 <member><errortype>condition</errortype></member>
118 <member><errortype>t</errortype></member>
123 <title>Description</title>
124 <para>This is the super-type of all
125 &clsql;-specific conditions that
126 represent warnings, as defined by
127 &clsql;, or any of it's
128 database-specific interfaces. There are no defined
129 initialization arguments nor any accessors.</para>
132 <refentry id="maisql-simple-warning">
134 <refname>CLSQL-SIMPLE-WARNING</refname>
135 <refpurpose>Unspecific simple
136 &clsql; warnings</refpurpose>
137 <refclass>Condition Type</refclass>
140 <title>Class Precedence List</title>
142 <simplelist type="inline">
143 <member><errortype>maisql-simple-warning</errortype></member>
144 <member><errortype>simple-condition</errortype></member>
145 <member><errortype>maisql-warning</errortype></member>
146 <member><errortype>warning</errortype></member>
147 <member><errortype>maisql-condition</errortype></member>
148 <member><errortype>condition</errortype></member>
149 <member><errortype>t</errortype></member>
154 <title>Description</title>
155 <para>This condition is used in all instances of warnings,
156 where there exists no
157 &clsql;-specific condition that is
158 more specific. The valid initialization arguments and
159 accessors are the same as for
160 <errortype>simple-condition</errortype>.</para>
163 <!-- Specifc Conditions -->
164 <refentry id="maisql-invalid-spec-error">
166 <refname>CLSQL-INVALID-SPEC-ERROR</refname>
167 <refpurpose>condition representing errors because of invalid
168 connection specifications</refpurpose>
169 <refclass>Condition Type</refclass>
172 <title>Class Precedence List</title>
174 <simplelist type="inline">
175 <member><errortype>maisql-invalid-spec-error</errortype></member>
176 <member><errortype>maisql-error</errortype></member>
177 <member><errortype>error</errortype></member>
178 <member><errortype>serious-condition</errortype></member>
179 <member><errortype>maisql-condition</errortype></member>
180 <member><errortype>condition</errortype></member>
181 <member><errortype>t</errortype></member>
186 <title>Description</title>
187 <para>This condition represents errors that occur because the
188 user supplies an invalid connection specification to either
189 <function>database-name-from-spec</function> or
190 <function>connect</function>. The following initialization
191 arguments and accessors exist:</para>
193 <segtitle>Initarg</segtitle>
194 <segtitle>Accessor</segtitle>
195 <segtitle>Description</segtitle>
197 <seg><symbol>:connection-spec</symbol></seg>
198 <seg><function>maisql-invalid-spec-error-connection-spec</function></seg>
199 <seg>The invalid connection specification used.</seg>
202 <seg><symbol>:database-type</symbol></seg>
203 <seg><function>maisql-invalid-spec-error-database-type</function></seg>
204 <seg>The Database type used in the attempt.</seg>
207 <seg><symbol>:template</symbol></seg>
208 <seg><function>maisql-invalid-spec-error-template</function></seg>
209 <seg>An argument describing the template that a valid
210 connection specification must match for this database type.</seg>
215 <refentry id="maisql-connect-error">
217 <refname>CLSQL-CONNECT-ERROR</refname>
218 <refpurpose>condition representing errors during
219 connection</refpurpose>
220 <refclass>Condition Type</refclass>
223 <title>Class Precedence List</title>
225 <simplelist type="inline">
226 <member><errortype>maisql-connect-error</errortype></member>
227 <member><errortype>maisql-error</errortype></member>
228 <member><errortype>error</errortype></member>
229 <member><errortype>serious-condition</errortype></member>
230 <member><errortype>maisql-condition</errortype></member>
231 <member><errortype>condition</errortype></member>
232 <member><errortype>t</errortype></member>
237 <title>Description</title>
238 <para>This condition represents errors that occur while trying
239 to connect to a database. The following initialization
240 arguments and accessors exist:</para>
242 <segtitle>Initarg</segtitle>
243 <segtitle>Accessor</segtitle>
244 <segtitle>Description</segtitle>
246 <seg><symbol>:database-type</symbol></seg>
247 <seg><function>maisql-connect-error-database-type</function></seg>
248 <seg>Database type for the connection attempt</seg>
251 <seg><symbol>:connection-spec</symbol></seg>
252 <seg><function>maisql-connect-error-connection-spec</function></seg>
253 <seg>The connection specification used in the
254 connection attempt.</seg>
257 <seg><symbol>:errno</symbol></seg>
258 <seg><function>maisql-connect-error-errno</function></seg>
259 <seg>The numeric or symbolic error specification
260 returned by the database back-end. The values and
261 semantics of this are interface specific.</seg>
264 <seg><symbol>:error</symbol></seg>
265 <seg><function>maisql-connect-error-error</function></seg>
266 <seg>A string describing the problem that occurred,
267 possibly one returned by the database back-end.</seg>
272 <refentry id="maisql-sql-error">
274 <refname>CLSQL-SQL-ERROR</refname>
275 <refpurpose>condition representing errors during query or
276 command execution</refpurpose>
277 <refclass>Condition Type</refclass>
280 <title>Class Precedence List</title>
282 <simplelist type="inline">
283 <member><errortype>maisql-sql-error</errortype></member>
284 <member><errortype>maisql-error</errortype></member>
285 <member><errortype>error</errortype></member>
286 <member><errortype>serious-condition</errortype></member>
287 <member><errortype>maisql-condition</errortype></member>
288 <member><errortype>condition</errortype></member>
289 <member><errortype>t</errortype></member>
294 <title>Description</title>
295 <para>This condition represents errors that occur while
296 executing SQL statements, either as part of query operations
297 or command execution, either explicitly or implicitly, as
298 caused e.g. by <function>with-transaction</function>.
299 The following initialization arguments and accessors exist:</para>
301 <segtitle>Initarg</segtitle>
302 <segtitle>Accessor</segtitle>
303 <segtitle>Description</segtitle>
305 <seg><symbol>:database</symbol></seg>
306 <seg><function>maisql-sql-error-database</function></seg>
307 <seg>The database object that was involved in the
311 <seg><symbol>:expression</symbol></seg>
312 <seg><function>maisql-sql-error-expression</function></seg>
313 <seg>The SQL expression whose execution caused the error.</seg>
316 <seg><symbol>:errno</symbol></seg>
317 <seg><function>maisql-sql-error-errno</function></seg>
318 <seg>The numeric or symbolic error specification
319 returned by the database back-end. The values and
320 semantics of this are interface specific.</seg>
323 <seg><symbol>:error</symbol></seg>
324 <seg><function>maisql-sql-error-error</function></seg>
325 <seg>A string describing the problem that occurred,
326 possibly one returned by the database back-end.</seg>
331 <refentry id="maisql-exists-condition">
333 <refname>CLSQL-EXISTS-CONDITION</refname>
334 <refpurpose>condition indicating situations arising because of
335 existing connections</refpurpose>
336 <refclass>Condition Type</refclass>
339 <title>Class Precedence List</title>
341 <simplelist type="inline">
342 <member><errortype>maisql-exists-condition</errortype></member>
343 <member><errortype>maisql-condition</errortype></member>
344 <member><errortype>condition</errortype></member>
345 <member><errortype>t</errortype></member>
350 <title>Description</title>
351 <para>This condition is the super-type of all conditions which
352 represents problems that occur during calls to
353 <function>connect</function>, if a connection to the
354 database exists already. Depending on the value of
355 <parameter>if-exists</parameter> to the call of
356 <function>connect</function>, either a warning, an error or
357 no condition at all is signalled. If a warning or error is
359 <errortype>maisql-exists-warning</errortype> or
360 <errortype>maisql-exists-error</errortype> is signalled,
361 which are subtypes of
362 <errortype>maisql-exists-condition</errortype> and
363 <errortype>maisql-warning</errortype> or
364 <errortype>maisql-error</errortype>.
365 <errortype>maisql-exists-condition</errortype> is never
366 signalled itself.</para>
368 The following initialization arguments and accessors exist:</para>
370 <segtitle>Initarg</segtitle>
371 <segtitle>Accessor</segtitle>
372 <segtitle>Description</segtitle>
374 <seg><symbol>:old-db</symbol></seg>
375 <seg><function>maisql-exists-condition-old-db</function></seg>
376 <seg>The database object that represents the existing
377 connection. This slot is always filled.</seg>
380 <seg><symbol>:new-db</symbol></seg>
381 <seg><function>maisql-exists-condition-new-db</function></seg>
382 <seg>The database object that will be used and returned by
383 this call to connect, if execution continues normally.
384 This can be either <symbol>nil</symbol>, indicating that
385 a new database object is to be created on continuation,
386 or a database object representing the newly created
387 continuation, or the same database object as
388 <symbol>old-db</symbol>, indicating that the existing
389 database object will be reused. This slot is always
390 filled and defaults to <symbol>nil</symbol>.</seg>
395 <refentry id="maisql-exists-warning">
397 <refname>CLSQL-EXISTS-WARNING</refname>
398 <refpurpose>condition representing warnings arising because of
399 existing connections</refpurpose>
400 <refclass>Condition Type</refclass>
403 <title>Class Precedence List</title>
405 <simplelist type="inline">
406 <member><errortype>maisql-exists-warning</errortype></member>
407 <member><errortype>maisql-exists-condition</errortype></member>
408 <member><errortype>maisql-warning</errortype></member>
409 <member><errortype>warning</errortype></member>
410 <member><errortype>maisql-condition</errortype></member>
411 <member><errortype>condition</errortype></member>
412 <member><errortype>t</errortype></member>
417 <title>Description</title>
418 <para>This condition is a subtype of
419 <errortype>maisql-exists-condition</errortype>, and is
420 signalled during calls to <function>connect</function> when
421 there is an existing connection, and
422 <parameter>if-exists</parameter> is either
423 <symbol>:warn-new</symbol> or <symbol>:warn-old</symbol>.
424 In the former case, <symbol>new-db</symbol> will be the
425 newly created database object, in the latter case it will be
426 the existing old database object.</para>
428 The initialization arguments and accessors are the same as
429 for <errortype>maisql-exists-condition</errortype>.</para>
432 <refentry id="maisql-exists-error">
434 <refname>CLSQL-EXISTS-ERROR</refname>
435 <refpurpose>condition representing errors arising because of
436 existing connections</refpurpose>
437 <refclass>Condition Type</refclass>
440 <title>Class Precedence List</title>
442 <simplelist type="inline">
443 <member><errortype>maisql-exists-error</errortype></member>
444 <member><errortype>maisql-exists-condition</errortype></member>
445 <member><errortype>maisql-error</errortype></member>
446 <member><errortype>error</errortype></member>
447 <member><errortype>serious-condition</errortype></member>
448 <member><errortype>maisql-condition</errortype></member>
449 <member><errortype>condition</errortype></member>
450 <member><errortype>t</errortype></member>
455 <title>Description</title>
456 <para>This condition is a subtype of
457 <errortype>maisql-exists-condition</errortype>, and is
458 signalled during calls to <function>connect</function> when
459 there is an existing connection, and
460 <parameter>if-exists</parameter> is <symbol>:error</symbol>.
461 In this case, <symbol>new-db</symbol> will be
462 <symbol>nil</symbol>, indicating that the database object to
463 be returned by <function>connect</function> depends on user
464 action in continuing from this correctable error.</para>
466 The initialization arguments and accessors are the same as
467 for <errortype>maisql-exists-condition</errortype>.</para>
470 <refentry id="maisql-closed-error">
472 <refname>CLSQL-CLOSED-ERROR</refname>
473 <refpurpose>condition representing errors because the database
474 has already been closed</refpurpose>
475 <refclass>Condition Type</refclass>
478 <title>Class Precedence List</title>
480 <simplelist type="inline">
481 <member><errortype>maisql-closed-error</errortype></member>
482 <member><errortype>maisql-error</errortype></member>
483 <member><errortype>error</errortype></member>
484 <member><errortype>serious-condition</errortype></member>
485 <member><errortype>maisql-condition</errortype></member>
486 <member><errortype>condition</errortype></member>
487 <member><errortype>t</errortype></member>
492 <title>Description</title>
493 <para>This condition represents errors that occur because the
494 user invokes an operation on the given database object,
495 although the database is invalid because
496 <function>disconnect</function> has already been called on
497 this database object.</para>
498 <para>Functions which signal this error when called with a
499 closed database will usually provide a
500 <symbol>continue</symbol> restart, that will just return nil
501 from the function.</para>
503 The following initialization arguments and accessors exist:</para>
505 <segtitle>Initarg</segtitle>
506 <segtitle>Accessor</segtitle>
507 <segtitle>Description</segtitle>
509 <seg><symbol>:database</symbol></seg>
510 <seg><function>maisql-closed-error-database</function></seg>
511 <seg>The database object that was involved in the
518 <!-- Database Types -->
519 <refentry id="default-database-type">
521 <refname>*DEFAULT-DATABASE-TYPE*</refname>
522 <refpurpose>The default database type to use</refpurpose>
523 <refclass>Variable</refclass>
526 <title>Value Type</title>
527 <para>Any keyword representing a valid database back-end of
529 <symbol>nil</symbol>.</para>
532 <title>Initial Value</title>
533 <para><symbol>nil</symbol></para>
536 <title>Description</title>
537 <para>The value of this variable is used in calls to
538 <function>initialize-database-type</function> and
539 <function>connect</function> as the default
540 value of the <parameter>database-type</parameter>
543 <para>If the value of this variable is <symbol>nil</symbol>,
545 <function>initialize-database-type</function> or
546 <function>connect</function> will have to specify the
547 <parameter>database-type</parameter> to use, or a
548 general-purpose error will be signalled.</para>
552 <title>Examples</title>
554 (setf *default-database-type* :mysql)
556 (initialize-database-type)
561 <title>Affected By</title>
565 <title>See Also</title>
573 <refentry id="initialized-database-types">
575 <refname>*INITIALIZED-DATABASE-TYPES*</refname>
576 <refpurpose>List of all initialized database types</refpurpose>
577 <refclass>Variable</refclass>
580 <title>Value Type</title>
581 <para>A list of all initialized database types, each of which
582 represented by it's corresponding keyword.</para>
585 <title>Initial Value</title>
586 <para><symbol>nil</symbol></para>
589 <title>Description</title>
590 <para>This variable is updated whenever
591 <function>initialize-database-type</function> is called for a
592 database type which hasn't already been initialized before,
593 as determined by this variable. In that case the keyword
594 representing the database type is pushed onto the list
596 <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
598 <para>Attempts to modify the value of this variable will
599 result in undefined behaviour.</para>
603 <title>Examples</title>
605 (setf *default-database-type* :mysql)
607 (initialize-database-type)
609 *initialized-database-types*
614 <title>Affected By</title>
617 <member><function>initialize-database-type</function></member>
622 <title>See Also</title>
627 <para>Direct access to this variable is primarily provided
628 because of compatibility with Harlequin's <application>Common
629 SQL</application>.</para>
632 <refentry id="initialize-database-type">
634 <refname>INITIALIZE-DATABASE-TYPE</refname>
635 <refpurpose>Initializes a database type</refpurpose>
636 <refclass>Function</refclass>
639 <title>Syntax</title>
640 <synopsis><function>initialize-database-type</function> &key <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
643 <title>Arguments and Values</title>
646 <term><parameter>database-type</parameter></term>
648 <para>The database type to initialize, i.e. a keyword
649 symbol denoting a known database back-end. Defaults to
651 <symbol>*default-database-type*</symbol>.</para>
655 <term><returnvalue>result</returnvalue></term>
657 <para>Either <symbol>nil</symbol> if the initialization
658 attempt fails, or <symbol>t</symbol> otherwise.</para>
664 <title>Description</title>
665 <para>If the back-end specified by
666 <parameter>database-type</parameter> has not already been
667 initialized, as seen from
668 <symbol>*initialized-database-types*</symbol>, an attempt is
669 made to initialize the database. If this attempt succeeds,
670 or the back-end has already been initialized, the function
671 returns t, and places the keyword denoting the database type
672 onto the list stored in
673 <symbol>*initialized-database-types*</symbol>, if not
674 already present.</para>
675 <para>If initialization fails, the function returns
676 <symbol>nil</symbol>, and/or signals an error of type
677 <errortype>maisql-error</errortype>. The kind of action
678 taken depends on the back-end and the cause of the
682 <title>Examples</title>
684 *initialized-database-types*
686 (setf *default-database-type* :mysql)
688 (initialize-database-type)
689 >> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
690 >> Compiling Top-Level Form:
693 *initialized-database-types*
695 (initialize-database-type)
697 *initialized-database-types*
702 <title>Side Effects</title>
703 <para>The database back-end corresponding to the database type
704 specified is initialized, unless it has already been
705 initialized. This can involve any number of other side
706 effects, as determined by the back-end implementation (like
707 e.g. loading of foreign code, calling of foreign code,
708 networking operations, etc.). If initialization is
709 attempted and succeeds, the
710 <parameter>database-type</parameter> is pushed onto the list
712 <symbol>*initialized-database-types*</symbol>.</para>
715 <title>Affected by</title>
718 <member><symbol>*default-database-type*</symbol></member>
719 <member><symbol>*initialized-database-types*</symbol></member>
724 <title>Exceptional Situations</title>
725 <para>If an error is encountered during the initialization
726 attempt, the back-end may signal errors of kind
727 <errortype>maisql-error</errortype>.</para>
730 <title>See Also</title>
738 <!-- Databases Connection and Disconnection -->
739 <refentry id="connect-if-exists">
741 <refname>*CONNECT-IF-EXISTS*</refname>
742 <refpurpose>Default value for the
743 <parameter>if-exists</parameter> parameter of
744 <function>connect</function>.</refpurpose>
745 <refclass>Variable</refclass>
748 <title>Value Type</title>
749 <para>A valid argument to the <parameter>if-exists</parameter>
750 parameter of <function>connect</function>, i.e. one of
751 <simplelist type="inline">
752 <member><symbol>:new</symbol></member>
753 <member><symbol>:warn-new</symbol></member>
754 <member><symbol>:error</symbol></member>
755 <member><symbol>:warn-old</symbol></member>
756 <member><symbol>:old</symbol></member>
761 <title>Initial Value</title>
762 <para><symbol>:error</symbol></para>
765 <title>Description</title>
766 <para>The value of this variable is used in calls to
767 <function>connect</function> as the default
768 value of the <parameter>if-exists</parameter>
770 linkend="connect"><function>connect</function></link> for
771 the semantics of the valid values for this variable.</para>
774 <title>Examples</title>
778 <title>Affected By</title>
782 <title>See Also</title>
786 linkend="connect"><function>connect</function></link></member>
795 <refentry id="connected-databases">
797 <refname>CONNECTED-DATABASES</refname>
798 <refpurpose>Return the list of active database
799 objects.</refpurpose>
800 <refclass>Function</refclass>
803 <title>Syntax</title>
804 <synopsis><function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
807 <title>Arguments and Values</title>
810 <term><returnvalue>databases</returnvalue></term>
812 <para>The list of active database objects.</para>
818 <title>Description</title>
819 <para>This function returns the list of active database
820 objects, i.e. all those database objects created by calls to
821 <function>connect</function>, which have not been closed by
822 calling <function>disconnect</function> on them.</para>
824 <para>The consequences of modifying the list returned by
825 <function>connected-databases</function> are
830 <title>Examples</title>
832 (connected-databases)
834 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
835 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
836 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
837 => #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
838 (connected-databases)
839 => (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
840 #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
843 (connected-databases)
844 => (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
847 (connected-databases)
852 <title>Side Effects</title>
856 <title>Affected By</title>
859 <member><function>connect</function></member>
860 <member><function>disconnect</function></member>
865 <title>Exceptional Situations</title>
869 <title>See Also</title>
877 <refentry id="default-database">
879 <refname>*DEFAULT-DATABASE*</refname>
880 <refpurpose>The default database object to use</refpurpose>
881 <refclass>Variable</refclass>
884 <title>Value Type</title>
885 <para>Any object of type <type>database</type>, or nil to
886 indicate no default database.</para>
889 <title>Initial Value</title>
890 <para><symbol>nil</symbol></para>
893 <title>Description</title>
894 <para>Any function or macro in
895 &clsql; that operates on a
896 database uses the value of this variable as the default
897 value for it's <parameter>database</parameter>
899 <para>The value of this parameter is changed by calls to
900 <function>connect</function>, which sets
901 <symbol>*default-database*</symbol> to the database object
902 it returns. It is also changed by calls to
903 <function>disconnect</function>, when the database object
904 being disconnected is the same as the value of
905 <symbol>*default-database*</symbol>. In this case
906 <function>disconnect</function> sets
907 <symbol>*default-database*</symbol> to the first database
908 that remains in the list of active databases as returned by
909 <function>connected-databases</function>, or
910 <symbol>nil</symbol> if no further active databases
912 <para>The user may change <symbol>*default-database*</symbol>
913 at any time to a valid value of his choice.</para>
915 <para>If the value of <symbol>*default-database*</symbol> is
916 <symbol>nil</symbol>, then all calls to
917 &clsql; functions on databases
918 must provide a suitable <parameter>database</parameter>
919 parameter, or an error will be signalled.</para>
923 <title>Examples</title>
925 (connected-databases)
927 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
928 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
929 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
930 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
931 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
932 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
934 => #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
938 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
942 => #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
947 (connected-databases)
952 <title>Affected By</title>
955 <member><link linkend="connect"><function>connect</function></link></member>
956 <member><link linkend="disconnect"><function>disconnect</function></link></member>
961 <title>See Also</title>
964 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
971 <para>This variable is intended to facilitate working with
972 &clsql; in an interactive
973 fashion at the top-level loop, and because of this,
974 <function>connect</function> and
975 <function>disconnect</function> provide some fairly
976 complex behaviour to keep
977 <symbol>*default-database*</symbol> set to useful values.
978 Programmatic use of &clsql;
979 should never depend on the value of
980 <symbol>*default-database*</symbol> and should provide
981 correct database objects via the
982 <parameter>database</parameter> parameter to functions
988 <refentry id="database">
990 <refname>DATABASE</refname>
991 <refpurpose>The super-type of all
992 &clsql; databases</refpurpose>
993 <refclass>Class</refclass>
996 <title>Class Precedence List</title>
998 <simplelist type="inline">
999 <member><type>database</type></member>
1000 <member><type>standard-object</type></member>
1001 <member><type>t</type></member>
1006 <title>Description</title>
1007 <para>This class is the superclass of all
1008 &clsql; databases. The different
1009 database back-ends derive subclasses of this class to
1010 implement their databases. No instances of this class are
1011 ever created by &clsql;.</para>
1014 <refentry id="closed-database">
1016 <refname>CLOSED-DATABASE</refname>
1017 <refpurpose>The class representing all closed
1018 &clsql; databases</refpurpose>
1019 <refclass>Class</refclass>
1022 <title>Class Precedence List</title>
1024 <simplelist type="inline">
1025 <member><type>closed-database</type></member>
1026 <member><type>standard-object</type></member>
1027 <member><type>t</type></member>
1032 <title>Description</title>
1033 <para>&clsql; <type>database</type>
1034 instances are changed to this class via
1035 <function>change-class</function> after they are closed via
1036 <function>disconnect</function>. All functions and generic
1037 functions that take database objects as arguments will
1038 signal errors of type
1039 <errortype>maisql-closed-error</errortype> when they are
1040 called on instances of <type>closed-database</type>, with
1041 the exception of <function>database-name</function>, which
1042 will continue to work as for instances of
1043 <type>database</type>.</para>
1047 <refentry id="database-name">
1049 <refname>DATABASE-NAME</refname>
1050 <refpurpose>Get the name of a database object</refpurpose>
1051 <refclass>Generic Function</refclass>
1054 <title>Syntax</title>
1055 <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
1058 <title>Arguments and Values</title>
1061 <term><parameter>database</parameter></term>
1063 <para>A database object, either of type
1064 <type>database</type> or of type
1065 <type>closed-database</type>.</para>
1069 <term><returnvalue>name</returnvalue></term>
1071 <para>A string describing the identity of the database
1072 to which this database object is connected to.</para>
1078 <title>Description</title>
1079 <para>This function returns the database name of the given
1080 database. The database name is a string which somehow
1081 describes the identity of the database to which this
1082 database object is or has been connected. The database name
1083 of a database object is determined at
1084 <function>connect</function> time, when a call to
1085 <function>database-name-from-spec</function> derives the
1086 database name from the connection specification passed to
1087 <function>connect</function> in the
1088 <parameter>connection-spec</parameter> parameter.</para>
1089 <para>The database name is used via
1090 <function>find-database</function> in
1091 <function>connect</function> to determine whether database
1092 connections to the specified database exist already.</para>
1093 <para>Usually the database name string will include
1094 indications of the host, database name, user, or port that
1095 where used during the connection attempt. The only
1096 important thing is that this string shall try to identify
1097 the database at the other end of the connection. Connection
1098 specifications parts like passwords and credentials shall
1099 not be used as part of the database name.</para>
1102 <title>Examples</title>
1104 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1105 => "dent/newesim/dent"
1106 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1107 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1108 (database-name *default-database*)
1109 => "dent/newesim/dent"
1111 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1112 => "/template1/dent"
1113 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1114 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1115 (database-name *default-database*)
1116 => "/template1/dent"
1118 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1119 => "www.pmsf.de/template1/dent"
1123 <title>Side Effects</title>
1127 <title>Affected By</title>
1130 <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1135 <title>Exceptional Situations</title>
1136 <para>Will signal an error if the object passed as the
1137 <parameter>database</parameter> parameter is neither of type
1138 <type>database</type> nor of type
1139 <type>closed-database</type>.</para>
1142 <title>See Also</title>
1146 linkend="connect"><function>connect</function></link></member>
1148 linkend="find-database"><function>find-database</function></link></member>
1153 <title>Notes</title>
1157 <refentry id="find-database">
1159 <refname>FIND-DATABASE</refname>
1160 <refpurpose>Locate a database object through it's
1162 <refclass>Function</refclass>
1165 <title>Syntax</title>
1166 <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
1169 <title>Arguments and Values</title>
1172 <term><parameter>database</parameter></term>
1174 <para>A database object or a string, denoting a database
1179 <term><parameter>errorp</parameter></term>
1181 <para>A generalized boolean. Defaults to
1182 <symbol>t</symbol>.</para>
1186 <term><returnvalue>result</returnvalue></term>
1188 <para>Either a database object, or, if
1189 <parameter>errorp</parameter> is <symbol>nil</symbol>,
1190 possibly <symbol>nil</symbol>.</para>
1196 <title>Description</title>
1197 <para><function>find-database</function> locates an active
1198 database object given the specification in
1199 <parameter>database</parameter>. If
1200 <parameter>database</parameter> is an object of type
1201 <type>database</type>, <function>find-database</function>
1202 returns this. Otherwise it will search the active databases
1203 as indicated by the list returned by
1204 <function>connected-databases</function> for a database
1205 whose name (as returned by
1206 <function>database-name</function> is equal as per
1207 <function>string=</function> to the string passed as
1208 <parameter>database</parameter>. If it succeeds, it returns
1209 the first database found.</para>
1210 <para>If it fails to find a matching database, it will signal
1211 an error of type <errortype>maisql-error</errortype> if
1212 <parameter>errorp</parameter> is true. If
1213 <parameter>errorp</parameter> is <symbol>nil</symbol>, it
1214 will return <symbol>nil</symbol> instead.</para>
1217 <title>Examples</title>
1219 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1220 => "dent/newesim/dent"
1221 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1222 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1223 (database-name *default-database*)
1224 => "dent/newesim/dent"
1226 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1227 => "/template1/dent"
1228 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1229 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1230 (database-name *default-database*)
1231 => "/template1/dent"
1233 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1234 => "www.pmsf.de/template1/dent"
1236 (find-database "dent/newesim/dent")
1237 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1238 (find-database "/template1/dent")
1239 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1240 (find-database "www.pmsf.de/template1/dent" nil)
1243 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1247 <title>Side Effects</title>
1251 <title>Affected By</title>
1254 <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
1259 <title>Exceptional Situations</title>
1260 <para>Will signal an error of type
1261 <errortype>maisql-error</errortype> if no matching database
1262 can be found, and <parameter>errorp</parameter> is true.
1263 Will signal an error if the value of
1264 <parameter>database</parameter> is neither an object of type
1265 <type>database</type> nor a string.</para>
1268 <title>See Also</title>
1272 linkend="database-name"><function>database-name</function></link></member>
1274 linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
1279 <title>Notes</title>
1283 <refentry id="connect">
1285 <refname>CONNECT</refname>
1286 <refpurpose>create a connection to a database</refpurpose>
1287 <refclass>Function</refclass>
1290 <title>Syntax</title>
1291 <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> => <returnvalue>database</returnvalue></synopsis>
1294 <title>Arguments and Values</title>
1297 <term><parameter>connection-spec</parameter></term>
1299 <para>A connection specification</para>
1303 <term><parameter>if-exists</parameter></term>
1305 <para>This indicates the action to take if a connection
1306 to the same database exists already. See below for the
1307 legal values and actions. It defaults to the value of
1308 <symbol>*connect-if-exists*</symbol>.</para>
1312 <term><parameter>database-type</parameter></term>
1314 <para>A database type specifier, i.e. a keyword.
1315 This defaults to the value of
1316 <symbol>*default-database-type*</symbol></para>
1320 <term><returnvalue>database</returnvalue></term>
1322 <para>The database object representing the connection.</para>
1328 <title>Description</title>
1329 <para>This function takes a connection specification and
1330 a database type and creates a connection to the database
1331 specified by those. The type and structure of the
1332 connection specification depend on the database type.</para>
1333 <para>The parameter <parameter>if-exists</parameter> specifies
1334 what to do if a connection to the database specified exists
1335 already, which is checked by calling
1336 <function>find-database</function> on the database name
1337 returned by <function>database-name-from-spec</function>
1338 when called with the <parameter>connection-spec</parameter>
1339 and <parameter>database-type</parameter> parameters. The
1340 possible values of <parameter>if-exists</parameter> are:
1343 <term><symbol>:new</symbol></term>
1345 <para>Go ahead and create a new connection.</para>
1349 <term><symbol>:warn-new</symbol></term>
1351 <para>This is just like <symbol>:new</symbol>, but
1352 also signals a warning of type
1353 <errortype>maisql-exists-warning</errortype>,
1354 indicating the old and newly created
1359 <term><symbol>:error</symbol></term>
1361 <para>This will cause <function>connect</function> to
1362 signal a correctable error of type
1363 <errortype>maisql-exists-error</errortype>. The
1364 user may choose to proceed, either by indicating
1365 that a new connection shall be created, via the
1366 restart <symbol>create-new</symbol>, or by
1367 indicating that the existing connection shall be
1368 used, via the restart
1369 <symbol>use-old</symbol>.</para>
1373 <term><symbol>:old</symbol></term>
1375 <para>This will cause <function>connect</function> to
1376 use an old connection if one exists.</para>
1380 <term><symbol>:warn-old</symbol></term>
1382 <para>This is just like <symbol>:old</symbol>, but
1383 also signals a warning of type
1384 <errortype>maisql-exists-warning</errortype>,
1385 indicating the old database used, via the slots
1386 <symbol>old-db</symbol> and
1387 <symbol>new-db</symbol></para>
1392 <para>The database name of the returned database object will
1393 be the same under <function>string=</function> as that which
1394 would be returned by a call to
1395 <function>database-name-from-spec</function> with the given
1396 <parameter>connection-spec</parameter> and
1397 <parameter>database-type</parameter> parameters.</para>
1400 <title>Examples</title>
1402 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1403 => "dent/newesim/dent"
1404 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1405 => #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
1407 => "dent/newesim/dent"
1409 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1410 >> In call to CONNECT:
1411 >> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
1414 >> 0: [CREATE-NEW] Create a new connection.
1415 >> 1: [USE-OLD ] Use the existing connection.
1416 >> 2: [ABORT ] Return to Top-Level.
1418 >> Debug (type H for help)
1420 >> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
1422 >> ; File: /prj/CLSQL/sql/sql.cl
1423 >> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
1424 >> (CREATE-NEW NIL :REPORT "Create a new connection."
1426 >> (USE-OLD NIL :REPORT "Use the existing connection."
1427 >> (SETQ RESULT OLD-DB)))
1429 => #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
1433 <title>Side Effects</title>
1434 <para>A database connection is established, and the resultant
1435 database object is registered, so as to appear in the list
1436 returned by <function>connected-databases</function>.</para>
1439 <title>Affected by</title>
1442 <member><symbol>*default-database-type*</symbol></member>
1443 <member><symbol>*connect-if-exists*</symbol></member>
1448 <title>Exceptional Situations</title>
1449 <para>If the connection specification is not syntactically or
1450 semantically correct for the given database type, an error
1451 of type <errortype>maisql-invalid-spec-error</errortype> is
1452 signalled. If during the connection attempt an error is
1453 detected (e.g. because of permission problems, network
1454 trouble or any other cause), an error of type
1455 <errortype>maisql-connect-error</errortype> is
1457 <para>If a connection to the database specified by
1458 <parameter>connection-spec</parameter> exists already,
1459 conditions are signalled according to the
1460 <parameter>if-exists</parameter> parameter, as described
1464 <title>See Also</title>
1467 <member><function>connected-databases</function></member>
1468 <member><link linkend="disconnect"><function>disconnect</function></link></member>
1473 <title>Notes</title>
1477 <refentry id="disconnect">
1479 <refname>DISCONNECT</refname>
1480 <refpurpose>close a database connection</refpurpose>
1481 <refclass>Function</refclass>
1484 <title>Syntax</title>
1485 <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1488 <title>Arguments and Values</title>
1491 <term><parameter>database</parameter></term>
1493 <para>The database to disconnect, which defaults to the
1494 database indicated by
1495 <symbol>*default-database*</symbol>.</para>
1501 <title>Description</title>
1502 <para>This function takes a <type>database</type> object as
1503 returned by <function>connect</function>, and closes the
1504 connection. The class of the object passed is changed to
1505 <type>closed-database</type> after the disconnection
1506 succeeds, thereby preventing further use of the object as
1507 an argument to &clsql; functions,
1508 with the exception of <function>database-name</function>.
1509 If the user does pass a closed database object to any other
1510 &clsql; function, an error of type
1511 <errortype>maisql-closed-error</errortype> is
1515 <title>Examples</title>
1517 (disconnect :database (find-database "dent/newesim/dent"))
1522 <title>Side Effects</title>
1523 <para>The database connection is closed, and the database
1524 object is removed from the list of connected databases as
1525 returned by <function>connected-databases</function>.</para>
1526 <para>The class of the database object is changed to
1527 <type>closed-database</type>.</para>
1528 <para>If the database object passed is the same under
1529 <function>eq</function> as the value of
1530 <symbol>*default-database*</symbol>, then
1531 <symbol>*default-database*</symbol> is set to the first
1532 remaining database from
1533 <function>connected-databases</function> or to nil if no
1534 further active database exists.</para>
1537 <title>Affected by</title>
1540 <member><symbol>*default-database*</symbol></member>
1545 <title>Exceptional Situations</title>
1546 <para>If during the disconnection attempt an error is
1547 detected (e.g. because of network trouble or any other
1548 cause), an error of type <errortype>maisql-error</errortype>
1549 might be signalled.</para>
1552 <title>See Also</title>
1555 <member><link linkend="connect"><function>connect</function></link></member>
1556 <member><link linkend="connect"><function>closed-database</function></link></member>
1561 <title>Notes</title>
1565 <refentry id="database-name-from-spec">
1567 <refname>DATABASE-NAME-FROM-SPEC</refname>
1568 <refpurpose>Return the database name string corresponding to
1569 the given connection specification.</refpurpose>
1570 <refclass>Generic Function</refclass>
1573 <title>Syntax</title>
1575 <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
1578 <title>Arguments and Values</title>
1581 <term><parameter>connection-spec</parameter></term>
1583 <para>A connection specification, whose structure and
1584 interpretation are dependent on the
1585 <parameter>database-type</parameter>.</para>
1589 <term><parameter>database-type</parameter></term>
1591 <para>A database type specifier, i.e. a keyword.</para>
1595 <term><returnvalue>name</returnvalue></term>
1597 <para>A string denoting a database name.</para>
1603 <title>Description</title>
1604 <para>This generic function takes a connection specification
1605 and a database type and returns the database name of the
1606 database object that would be created had
1607 <function>connect</function> been called with the given
1608 connection specification and database types.</para>
1609 <para>This function is useful in determining a database name
1610 from the connection specification, since the way the
1611 connection specification is converted into a database name
1612 is dependent on the database type.</para>
1615 <title>Examples</title>
1617 (database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
1618 => "dent/newesim/dent"
1619 (connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
1620 => #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
1621 (database-name *default-database*)
1622 => "dent/newesim/dent"
1624 (database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
1625 => "/template1/dent"
1626 (connect '(nil "template1" "dent" nil) :database-type :postgresql)
1627 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1628 (database-name *default-database*)
1629 => "/template1/dent"
1631 (database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
1632 => "www.pmsf.de/template1/dent"
1634 (find-database "dent/newesim/dent")
1635 => #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
1636 (find-database "/template1/dent")
1637 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1638 (find-database "www.pmsf.de/template1/dent" nil)
1641 => #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
1645 <title>Side Effects</title>
1649 <title>Affected by</title>
1653 <title>Exceptional Situations</title>
1654 <para>If the value of <parameter>connection-spec</parameter>
1655 is not a valid connection specification for the given
1656 database type, an error of type
1657 <errortype>maisql-invalid-spec-error</errortype> might be
1661 <title>See Also</title>
1664 <member><link linkend="connect"><function>connect</function></link></member>
1669 <title>Notes</title>
1673 <!-- Querying Operations -->
1674 <refentry id="execute-command">
1676 <refname>EXECUTE-COMMAND</refname>
1677 <refpurpose>Execute an SQL command which returns no
1678 values.</refpurpose>
1679 <refclass>Function</refclass>
1682 <title>Syntax</title>
1683 <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
1686 <title>Arguments and Values</title>
1689 <term><parameter>sql-expression</parameter></term>
1691 <para>An <glossterm linkend="gloss-sql-expression">sql
1692 expression</glossterm> that represents an SQL
1693 statement which will return no values.</para>
1697 <term><parameter>database</parameter></term>
1700 <glossterm linkend="gloss-database-object">database
1701 object</glossterm>. This will default to the value
1702 of <symbol>*default-database*</symbol>.</para>
1708 <title>Description</title>
1709 <para>This will execute the command given by
1710 <parameter>sql-expression</parameter> in the
1711 <parameter>database</parameter> specified. If the execution
1712 succeeds it will return <symbol>t</symbol>, otherwise an
1713 error of type <errortype>maisql-sql-error</errortype> will
1714 be signalled.</para>
1717 <title>Examples</title>
1719 (execute-command "create table eventlog (time char(30),event char(70))")
1722 (execute-command "create table eventlog (time char(30),event char(70))")
1724 >> While accessing database #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
1725 >> with expression "create table eventlog (time char(30),event char(70))":
1726 >> Error NIL: ERROR: amcreate: eventlog relation already exists
1730 >> 0: [ABORT] Return to Top-Level.
1732 >> Debug (type H for help)
1734 >> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
1737 >> #<unavailable-arg>
1738 >> #<unavailable-arg>)
1739 >> Source: (ERROR 'CLSQL-SQL-ERROR :DATABASE DATABASE :EXPRESSION ...)
1742 (execute-command "drop table eventlog")
1747 <title>Side Effects</title>
1748 <para>Whatever effects the execution of the SQL statement has
1749 on the underlying database, if any.</para>
1752 <title>Affected by</title>
1756 <title>Exceptional Situations</title>
1757 <para>If the execution of the SQL statement leads to any
1758 errors, an error of type
1759 <errortype>maisql-sql-error</errortype> is signalled.</para>
1762 <title>See Also</title>
1765 <member><link linkend="query"><function>query</function></link></member>
1770 <title>Notes</title>
1774 <refentry id="query">
1776 <refname>QUERY</refname>
1777 <refpurpose>Execute an SQL query and return the tuples as a
1779 <refclass>Function</refclass>
1782 <title>Syntax</title>
1783 <synopsis><function>query</function> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
1786 <title>Arguments and Values</title>
1789 <term><parameter>query-expression</parameter></term>
1791 <para>An <glossterm linkend="gloss-sql-expression">sql
1792 expression</glossterm> that represents an SQL
1793 query which is expected to return a (possibly empty)
1798 <term><parameter>database</parameter></term>
1801 <glossterm linkend="gloss-database-object">database
1802 object</glossterm>. This will default to the value
1803 of <symbol>*default-database*</symbol>.</para>
1807 <term><parameter>types</parameter></term>
1810 <glossterm linkend="gloss-field-types">field type
1811 specififier</glossterm>. The default is &nil;.
1814 The purpose of this argument is cause &clsql; to
1815 import SQL numeric fields into numeric Lisp objects
1816 rather than strings. This reduces the cost of
1817 allocating a temporary string and the &clsql; users'
1818 inconvenience of converting number strings into number
1822 A value of <symbol>:auto</symbol> causes &clsql;
1823 to automatically convert SQL fields into a
1824 numeric format where applicable. The default value of
1825 &nil; causes all fields to be returned as strings
1826 regardless of the SQL type. Otherwise a list is expected
1827 which has a element for each field that specifies the
1828 conversion. If the list is shorter than the number
1829 of fields, the a value of <symbol>t</symbol> is
1830 assumed for the field. If the list is longer than
1831 the number of fields, the extra elements are
1833 <simplelist type="vert">
1834 <member><symbol>:int</symbol> Field is imported as a
1835 32-bit signed integer.
1837 <member><symbol>:longlong</symbol> Field is imported as a
1838 64-bit signed integer.
1840 <member><symbol>:double</symbol> Field is imported as a
1841 double-float number.
1843 <member><symbol>t</symbol> Field is imported as a
1851 <term><returnvalue>result</returnvalue></term>
1853 <para>A list representing the result set obtained. For
1854 each tuple in the result set, there is an element in
1855 this list, which is itself a list of all the attribute
1856 values in the tuple.</para>
1862 <title>Description</title>
1863 <para>This will execute the query given by
1864 <parameter>query-expression</parameter> in the
1865 <parameter>database</parameter> specified. If the execution
1866 succeeds it will return the result set returned by the
1867 database, otherwise an error of type
1868 <errortype>maisql-sql-error</errortype> will
1869 be signalled.</para>
1872 <title>Examples</title>
1874 (execute-command "create table simple (name char(50), salary numeric(10,2))")
1876 (execute-command "insert into simple values ('Mai, Pierre',10000)")
1878 (execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
1880 (query "select * from simple")
1881 => (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
1882 (query "select salary from simple")
1883 => (("10000.00") ("8000.50"))
1884 (query "select salary from simple where salary > 10000")
1886 (query "select salary,name from simple where salary > 10000")
1888 (query "select salary,name from simple where salary > 9000")
1889 => (("10000.00" "Mai, Pierre"))
1890 (query "select salary,name from simple where salary > 8000")
1891 => (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
1894 (query "show tables")
1895 => (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
1899 <title>Side Effects</title>
1900 <para>Whatever effects the execution of the SQL query has
1901 on the underlying database, if any.</para>
1904 <title>Affected by</title>
1908 <title>Exceptional Situations</title>
1909 <para>If the execution of the SQL query leads to any
1910 errors, an error of type
1911 <errortype>maisql-sql-error</errortype> is signalled.</para>
1914 <title>See Also</title>
1917 <member><link linkend="execute-command"><function>execute-command</function></link></member>
1922 <title>Notes</title>
1927 <refentry id="map-query">
1929 <refname>MAP-QUERY</refname>
1930 <refpurpose>Map a function over all the tuples from a
1932 <refclass>Function</refclass>
1935 <title>Syntax</title>
1936 <synopsis><function>map-query</function> <replaceable>output-type-spec</replaceable> <replaceable>function</replaceable> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
1939 <title>Arguments and Values</title>
1942 <term><parameter>output-type-spec</parameter></term>
1944 <para>A sequence type specifier or <symbol>nil</symbol>.</para>
1948 <term><parameter>function</parameter></term>
1950 <para>A function designator.
1951 <parameter>function</parameter> must take as many
1952 arguments as are attributes in the result set returned
1953 by executing the SQL
1954 <parameter>query-expression</parameter>.</para>
1958 <term><parameter>query-expression</parameter></term>
1960 <para>An <glossterm linkend="gloss-sql-expression">sql
1961 expression</glossterm> that represents an SQL
1962 query which is expected to return a (possibly empty)
1963 result set, where each tuple has as many attributes as
1964 <parameter>function</parameter> takes arguments.</para>
1968 <term><parameter>database</parameter></term>
1971 <glossterm linkend="gloss-database-object">database
1972 object</glossterm>. This will default to the value
1973 of <symbol>*default-database*</symbol>.</para>
1977 <term><parameter>types</parameter></term>
1980 A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
1981 The default is &nil;. See <link
1982 linkend="query"><function>query</function></link>
1983 for the semantics of this argument.
1988 <term><returnvalue>result</returnvalue></term>
1990 <para>If <parameter>output-type-spec</parameter> is a
1991 type specifier other than <symbol>nil</symbol>, then a
1992 sequence of the type it denotes. Otherwise
1993 <symbol>nil</symbol> is returned.</para>
1999 <title>Description</title>
2000 <para>Applies <parameter>function</parameter> to the
2001 attributes of successive tuples in the result set returned
2002 by executing the SQL
2003 <parameter>query-expression</parameter>. If the
2004 <parameter>output-type-spec</parameter> is
2005 <symbol>nil</symbol>, then the result of each application
2006 of <parameter>function</parameter> is discarded, and
2007 <function>map-query</function> returns
2008 <symbol>nil</symbol>. Otherwise the result of each
2009 successive application of <parameter>function</parameter> is
2010 collected in a sequence of type
2011 <parameter>output-type-spec</parameter>, where the jths
2012 element is the result of applying
2013 <parameter>function</parameter> to the attributes of the
2014 jths tuple in the result set. The collected sequence is the
2015 result of the call to <function>map-query</function>.
2017 <para>If the <parameter>output-type-spec</parameter> is a
2018 subtype of <type>list</type>, the result will be a
2019 <type>list</type>.</para>
2020 <para>If the <parameter>result-type</parameter> is a subtype
2021 of <type>vector</type>, then if the implementation can
2022 determine the element type specified for the
2023 <parameter>result-type</parameter>, the element type of the
2024 resulting array is the result of
2025 <emphasis>upgrading</emphasis> that element type; or, if the
2026 implementation can determine that the element type is
2027 unspecified (or <symbol>*</symbol>), the element type of the
2028 resulting array is <type>t</type>; otherwise, an error is
2032 <title>Examples</title>
2034 (map-query 'list #'(lambda (salary name)
2035 (declare (ignorable name))
2036 (read-from-string salary))
2037 "select salary,name from simple where salary > 8000")
2040 (map-query '(vector double-float)
2041 #'(lambda (salary name)
2042 (declare (ignorable name))
2043 (let ((*read-default-float-format* 'double-float))
2044 (coerce (read-from-string salary) 'double-float))
2045 "select salary,name from simple where salary > 8000"))
2046 => #(10000.0d0 8000.5d0)
2048 => (SIMPLE-ARRAY DOUBLE-FLOAT (2))
2051 (values (map-query nil #'(lambda (salary name)
2052 (push (cons name (read-from-string salary)) list))
2053 "select salary,name from simple where salary > 8000")
2056 => (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
2060 <title>Side Effects</title>
2061 <para>Whatever effects the execution of the SQL query has
2062 on the underlying database, if any.</para>
2065 <title>Affected by</title>
2069 <title>Exceptional Situations</title>
2070 <para>If the execution of the SQL query leads to any
2071 errors, an error of type
2072 <errortype>maisql-sql-error</errortype> is signalled.</para>
2073 <para>An error of type <errortype>type-error</errortype> must
2074 be signaled if the <parameter>output-type-spec</parameter> is
2075 not a recognizable subtype of <type>list</type>, not a
2076 recognizable subtype of <type>vector</type>, and not
2077 <symbol>nil</symbol>.</para>
2078 <para>An error of type <errortype>type-error</errortype>
2079 should be signaled if
2080 <parameter>output-type-spec</parameter> specifies the number
2081 of elements and the size of the result set is different from
2085 <title>See Also</title>
2088 <member><link linkend="query"><function>query</function></link></member>
2089 <member><link linkend="do-query"><function>do-query</function></link></member>
2094 <title>Notes</title>
2098 <refentry id="do-query">
2100 <refname>DO-QUERY</refname>
2101 <refpurpose>Iterate over all the tuples of a
2103 <refclass>Macro</refclass>
2106 <title>Syntax</title>
2107 <synopsis><function>do-query</function> ((&rest <replaceable>args</replaceable>) <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable>) &body <replaceable>body</replaceable> => <returnvalue>nil</returnvalue></synopsis>
2110 <title>Arguments and Values</title>
2113 <term><parameter>args</parameter></term>
2115 <para>A list of variable names.</para>
2119 <term><parameter>query-expression</parameter></term>
2121 <para>An <glossterm linkend="gloss-sql-expression">sql
2122 expression</glossterm> that represents an SQL
2123 query which is expected to return a (possibly empty)
2124 result set, where each tuple has as many attributes as
2125 <parameter>function</parameter> takes arguments.</para>
2129 <term><parameter>database</parameter></term>
2132 <glossterm linkend="gloss-database-object">database
2133 object</glossterm>. This will default to
2134 <symbol>*default-database*</symbol>.</para>
2138 <term><parameter>types</parameter></term>
2141 A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
2142 The default is &nil;. See <link
2143 linkend="query"><function>query</function></link>
2144 for the semantics of this argument.
2149 <term><parameter>body</parameter></term>
2151 <para>A body of Lisp code, like in a
2152 <function>destructuring-bind</function> form.</para>
2158 <title>Description</title>
2159 <para>Executes the <parameter>body</parameter> of code
2160 repeatedly with the variable names in
2161 <parameter>args</parameter> bound to the attributes of each
2162 tuple in the result set returned by executing the SQL
2163 <parameter>query-expression</parameter> on the
2164 <parameter>database</parameter> specified.</para>
2165 <para>The body of code is executed in a block named
2166 <symbol>nil</symbol> which may be returned from prematurely
2167 via <function>return</function> or
2168 <function>return-from</function>. In this case the result
2169 of evaluating the <function>do-query</function> form will be
2170 the one supplied to <function>return</function> or
2171 <function>return-from</function>. Otherwise the result will
2172 be <symbol>nil</symbol>.</para>
2173 <para>The body of code appears also is if wrapped in a
2174 <function>destructuring-bind</function> form, thus allowing
2175 declarations at the start of the body, especially those
2176 pertaining to the bindings of the variables named in
2177 <parameter>args</parameter>.</para>
2180 <title>Examples</title>
2182 (do-query ((salary name) "select salary,name from simple")
2183 (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
2184 >> Mai, Pierre gets $10000.00
2185 >> Hacker, Random J. gets $08000.50
2188 (do-query ((salary name) "select salary,name from simple")
2189 (return (cons salary name)))
2190 => ("10000.00" . "Mai, Pierre")
2194 <title>Side Effects</title>
2195 <para>Whatever effects the execution of the SQL query has
2196 on the underlying database, if any.</para>
2199 <title>Affected by</title>
2203 <title>Exceptional Situations</title>
2204 <para>If the execution of the SQL query leads to any
2205 errors, an error of type
2206 <errortype>maisql-sql-error</errortype> is signalled.</para>
2207 <para>If the number of variable names in
2208 <parameter>args</parameter> and the number of attributes in
2209 the tuples in the result set don't match up, an error is
2213 <title>See Also</title>
2216 <member><link linkend="query"><function>query</function></link></member>
2217 <member><link linkend="map-query"><function>map-query</function></link></member>
2222 <title>Notes</title>
2226 <refentry id="loop-tuples">
2228 <refname>LOOP-FOR-AS-TUPLES</refname>
2229 <refpurpose>Iterate over all the tuples of a
2230 query via a loop clause</refpurpose>
2231 <refclass>Loop Clause</refclass>
2234 <title>Compatibility</title>
2235 <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
2238 <title>Syntax</title>
2239 <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>
2242 <title>Arguments and Values</title>
2245 <term><parameter>var</parameter></term>
2247 <para>A <literal>d-var-spec</literal>, as defined in the
2248 grammar for <function>loop</function>-clauses in the
2249 ANSI Standard for Common Lisp. This allows for the
2250 usual loop-style destructuring.</para>
2254 <term><parameter>type-spec</parameter></term>
2256 <para>An optional <literal>type-spec</literal> either
2257 simple or destructured, as defined in the grammar for
2258 <function>loop</function>-clauses in the ANSI Standard
2259 for Common Lisp.</para>
2263 <term><parameter>query</parameter></term>
2265 <para>An <glossterm linkend="gloss-sql-expression">sql
2266 expression</glossterm> that represents an SQL
2267 query which is expected to return a (possibly empty)
2268 result set, where each tuple has as many attributes as
2269 <parameter>function</parameter> takes arguments.</para>
2273 <term><parameter>database</parameter></term>
2276 <glossterm linkend="gloss-database-object">database
2277 object</glossterm>. This will default to the value
2278 of <symbol>*default-database*</symbol>.</para>
2284 <title>Description</title>
2285 <para>This clause is an iteration driver for
2286 <function>loop</function>, that binds the given variable
2287 (possibly destructured) to the consecutive tuples (which are
2288 represented as lists of attribute values) in the result set
2289 returned by executing the SQL <parameter>query</parameter>
2290 expression on the <parameter>database</parameter>
2294 <title>Examples</title>
2296 (defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
2299 (loop with time-graph = (make-hash-table :test #'equal)
2300 with event-graph = (make-hash-table :test #'equal)
2301 for (time event) being the tuples of "select time,event from log"
2304 (incf (gethash time time-graph 0))
2305 (incf (gethash event event-graph 0))
2307 (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
2308 (format t "~&Time-Graph:~%===========~%")
2309 (maphash #'show-graph time-graph)
2310 (format t "~&~%Event-Graph:~%============~%")
2311 (maphash #'show-graph event-graph))
2312 (return (values time-graph event-graph)))
2321 >> CLOS Benchmark entry. => 9000
2322 >> Demo Text... => 3
2323 >> doit-text => 3000
2324 >> C Benchmark entry. => 12000
2325 >> CLOS Benchmark entry => 32000
2326 => #<EQUAL hash table, 3 entries {48350A1D}>
2327 => #<EQUAL hash table, 5 entries {48350FCD}>
2331 <title>Side Effects</title>
2332 <para>Whatever effects the execution of the SQL query has
2333 on the underlying database, if any.</para>
2336 <title>Affected by</title>
2340 <title>Exceptional Situations</title>
2341 <para>If the execution of the SQL query leads to any
2342 errors, an error of type
2343 <errortype>maisql-sql-error</errortype> is signalled.</para>
2344 <para>Otherwise, any of the exceptional situations of
2345 <function>loop</function> applies.</para>
2348 <title>See Also</title>
2351 <member><link linkend="query"><function>query</function></link></member>
2352 <member><link linkend="map-query"><function>map-query</function></link></member>
2353 <member><link linkend="do-query"><function>do-query</function></link></member>
2358 <title>Notes</title>
2365 <title><symbol>CLSQL-SYS</symbol></title>
2367 <para>This part gives a reference to all the symbols exported
2368 from the package <symbol>CLSQL-SYS</symbol>, which are not also
2369 exported from <symbol>CLSQL</symbol>. These symbols are part of
2370 the interface for database back-ends, but not part of the normal
2371 user-interface of &clsql;.</para>
2373 <refentry id="database-initialize-database-type">
2375 <refname>DATABASE-INITIALIZE-DATABASE-TYPE</refname>
2376 <refpurpose>Back-end part of <link
2377 linkend="initialize-database-type"><function>initialize-database-type</function></link>.</refpurpose>
2378 <refclass>Generic Function</refclass>
2381 <title>Syntax</title>
2382 <synopsis><function>database-initialize-database-type</function> <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
2385 <title>Arguments and Values</title>
2388 <term><parameter>database-type</parameter></term>
2390 <para>A keyword indicating the database type to
2395 <term><returnvalue>result</returnvalue></term>
2397 <para>Either <symbol>t</symbol> if the initialization
2398 succeeds or <symbol>nil</symbol> if it fails.</para>
2404 <title>Description</title>
2405 <para>This generic function implements the main part of the
2406 database type initialization performed by
2407 <function>initialize-database-type</function>. After
2408 <function>initialize-database-type</function> has checked
2409 that the given database type has not been initialized
2410 before, as indicated by
2411 <symbol>*initialized-database-types*</symbol>, it will call
2412 this function with the database type as it's sole
2413 parameter. Database back-ends are required to define a
2414 method on this generic function which is specialized via an
2415 eql-specializer to the keyword representing their database
2417 <para>Database back-ends shall indicate successful
2418 initialization by returning <symbol>t</symbol> from their
2419 method, and <symbol>nil</symbol> otherwise. Methods for
2420 this generic function are allowed to signal errors of type
2421 <errortype>maisql-error</errortype> or subtypes thereof.
2422 They may also signal other types of conditions, if
2423 appropriate, but have to document this.</para>
2426 <title>Examples</title>
2430 <title>Side Effects</title>
2431 <para>All necessary side effects to initialize the database
2435 <title>Affected By</title>
2439 <title>Exceptional Situations</title>
2440 <para>Conditions of type <errortype>maisql-error</errortype>
2441 or other conditions may be signalled, depending on the
2442 database back-end.</para>
2445 <title>See Also</title>
2449 linkend="initialize-database-type"><function>initialize-database-type</function></link></member>
2450 <member><link linkend="initialized-database-types"><symbol>*initialized-database-types*</symbol></link></member>
2455 <title>Notes</title>