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 <!-- SQL I/0 Recording -->
10 <reference id="ref-recording">
11 <title>SQL I/O Recording</title>
14 &clsql; provides a facility for recording SQL commands sent to
15 and/or results returned from the underlying RDBMS to user
16 sprecified streams. This is useful for monitoring &clsql;
17 activity and for debugging applications.
20 This section documents the functions provided for enabling and
21 disabling SQL recording as well as for manipulating the streams
22 on to which SQL commands and results are recorded.
26 <refentry id="start-sql-recording">
28 <refentrytitle>START-SQL-RECORDING</refentrytitle>
31 <refname>START-SQL-RECORDING</refname>
32 <refpurpose>Start recording SQL commands or results.</refpurpose>
33 <refclass>Function</refclass>
38 <function>start-sql-recording</function> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
41 <title>Arguments and Values</title>
44 <term><parameter>type</parameter></term>
47 One of the following keyword symbols:
48 <symbol>:commands</symbol>, <symbol>:results</symbol> or
49 <symbol>:both</symbol>, defaulting to
50 <symbol>:commands</symbol>.
53 </varlistentry> <varlistentry>
54 <term><parameter>database</parameter></term>
57 <glossterm linkend="gloss-database-object">database
58 object</glossterm>. This will default to
59 <symbol>*default-database*</symbol>.</para>
65 <title>Description</title>
66 <para>Starts recording of SQL commands sent to and/or results
67 returned from <parameter>database</parameter> which defaults to
68 <symbol>*default-database*</symbol>. The SQL is output on one or
69 more broadcast streams, initially just
70 <symbol>*standard-output*</symbol>, and the functions
71 <function>add-sql-stream</function> and
72 <function>delete-sql-stream</function> may be used to add or
73 delete command or result recording streams. The default value of
74 <parameter>type</parameter> is <symbol>:commands</symbol> which
75 means that SQL commands sent to <parameter>database</parameter>
76 are recorded. If <parameter>type</parameter> is
77 <symbol>:results</symbol> then SQL results returned from
78 <parameter>database</parameter> are recorded. Both commands and
79 results may be recorded by passing <parameter>type</parameter>
80 value of <symbol>:both</symbol>.
84 <title>Examples</title>
86 (start-sql-recording :type :both)
88 (select [last-name] :from [employee]
92 ;; 2004-07-02 16:42:12 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
93 ;; 2004-07-02 16:42:12 dent/test/dent <= (Lenin)
98 <title>Side Effects</title>
100 The command and result recording broadcast streams associated
101 with <parameter>database</parameter> are reinitialised with
102 only <symbol>*standard-output*</symbol> as their component
107 <title>Affected by</title>
113 <title>Exceptional Situations</title>
119 <title>See Also</title>
121 <member><link linkend="stop-sql-recording"><function>stop-sql-recording</function></link></member>
122 <member><link linkend="sql-recording-p"><function>sql-recording-p</function></link></member>
123 <member><link linkend="sql-stream"><function>sql-stream</function></link></member>
124 <member><link linkend="add-sql-stream"><function>add-sql-stream</function></link></member>
125 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>
126 <member><link linkend="list-sql-streams"><function>list-sql-streams</function></link></member>
137 <refentry id="stop-sql-recording">
139 <refentrytitle>STOP-SQL-RECORDING</refentrytitle>
142 <refname>STOP-SQL-RECORDING</refname>
143 <refpurpose>Stop recording SQL commands or results.</refpurpose>
144 <refclass>Function</refclass>
147 <title>Syntax</title>
149 <function>stop-sql-recording</function> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue></returnvalue></synopsis>
152 <title>Arguments and Values</title>
155 <term><parameter>type</parameter></term>
158 One of the following keyword symbols:
159 <symbol>:commands</symbol>, <symbol>:results</symbol> or
160 <symbol>:both</symbol>, defaulting to
161 <symbol>:commands</symbol>.
164 </varlistentry> <varlistentry>
165 <term><parameter>database</parameter></term>
168 <glossterm linkend="gloss-database-object">database
169 object</glossterm>. This will default to
170 <symbol>*default-database*</symbol>.</para>
176 <title>Description</title>
177 <para>Stops recording of SQL commands sent to and/or results
178 returned from <parameter>database</parameter> which defaults to
179 <symbol>*default-database*</symbol>. The default value of
180 <parameter>type</parameter> is <symbol>:commands</symbol> which
181 means that SQL commands sent to <parameter>database</parameter>
182 will no longer be recorded. If <parameter>type</parameter> is
183 <symbol>:results</symbol> then SQL results returned from
184 <parameter>database</parameter> will no longer be
185 recorded. Recording may be stopped for both commands and results
186 by passing <parameter>type</parameter> value of
187 <symbol>:both</symbol>.
191 <title>Examples</title>
193 (start-sql-recording :type :both)
195 (select [last-name] :from [employee]
196 :where [= [emplid] 1]
199 ;; 2004-07-02 16:42:12 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
200 ;; 2004-07-02 16:42:12 dent/test/dent <= (Lenin)
202 (stop-sql-recording :type :results)
204 (select [last-name] :from [employee]
205 :where [= [emplid] 1]
208 ;; 2004-07-02 16:44:11 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
213 <title>Side Effects</title>
215 The command and result recording broadcast streams associated
216 with <parameter>database</parameter> are reinitialised to
221 <title>Affected by</title>
227 <title>Exceptional Situations</title>
233 <title>See Also</title>
235 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
236 <member><link linkend="sql-recording-p"><function>sql-recording-p</function></link></member>
247 <refentry id="sql-recording-p">
249 <refentrytitle>SQL-RECORDING-P</refentrytitle>
252 <refname>SQL-RECORDING-P</refname>
253 <refpurpose>Tests whether SQL commands or results are being recorded.</refpurpose>
254 <refclass>Function</refclass>
257 <title>Syntax</title>
259 <function>sql-recording-p</function> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
262 <title>Arguments and Values</title>
265 <term><parameter>type</parameter></term>
268 One of the following keyword symbols:
269 <symbol>:commands</symbol>, <symbol>:results</symbol>,
270 <symbol>:both</symbol> or <symbol>:either</symbol>
271 defaulting to <symbol>:commands</symbol>.
276 <term><parameter>database</parameter></term>
279 <glossterm linkend="gloss-database-object">database
280 object</glossterm>. This will default to
281 <symbol>*default-database*</symbol>.</para>
285 <term><parameter>result</parameter></term>
295 <title>Description</title>
296 <para>Predicate to test whether the SQL recording specified by
297 <parameter>type</parameter> is currently enabled for
298 <parameter>database</parameter> which defaults to
299 <symbol>*default-database*</symbol>.
300 <parameter>type</parameter> may be one of
301 <symbol>:commands</symbol>, <symbol>:results</symbol>,
302 <symbol>:both</symbol> or <symbol>:either</symbol>, defaulting
303 to <symbol>:commands</symbol>, otherwise &nil; is returned.
307 <title>Examples</title>
309 (start-sql-recording :type :commands)
311 (sql-recording-p :type :commands)
313 (sql-recording-p :type :both)
315 (sql-recording-p :type :either)
320 <title>Side Effects</title>
326 <title>Affected by</title>
328 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
329 <member><link linkend="stop-sql-recording"><function>stop-sql-recording</function></link></member>
333 <title>Exceptional Situations</title>
339 <title>See Also</title>
341 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
342 <member><link linkend="stop-sql-recording"><function>stop-sql-recording</function></link></member>
348 The <symbol>:both</symbol> and <symbol>:either</symbol> values
349 for the <parameter>type</parameter> keyword argument are
355 <refentry id="sql-stream">
357 <refentrytitle>SQL-STREAM</refentrytitle>
360 <refname>SQL-STREAM</refname>
361 <refpurpose>Returns the broadcast stream used for recording SQL commands or results.</refpurpose>
362 <refclass>Function</refclass>
365 <title>Syntax</title>
367 <function>sql-stream</function> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
370 <title>Arguments and Values</title>
373 <term><parameter>type</parameter></term>
376 One of the following keyword symbols:
377 <symbol>:commands</symbol> or <symbol>:results</symbol>,
378 defaulting to <symbol>:commands</symbol>.
381 </varlistentry> <varlistentry>
382 <term><parameter>database</parameter></term>
385 <glossterm linkend="gloss-database-object">database
386 object</glossterm>. This will default to
387 <symbol>*default-database*</symbol>.</para>
391 <term><parameter>result</parameter></term>
394 A broadcast stream or &nil;.
401 <title>Description</title>
402 <para>Returns the broadcast stream used for recording SQL
403 commands sent to or results returned from
404 <parameter>database</parameter> which defaults to
405 <symbol>*default-database*</symbol>. <parameter>type</parameter>
406 must be one of <symbol>:commands</symbol> or
407 <symbol>:results</symbol>, defaulting to
408 <symbol>:commands</symbol>, and determines whether the stream
409 returned is that used for recording SQL commands or results.
413 <title>Examples</title>
415 (start-sql-recording :type :commands)
417 (sql-stream :type :commands)
418 => #<Broadcast Stream>
419 (sql-stream :type :results)
424 <title>Side Effects</title>
430 <title>Affected by</title>
436 <title>Exceptional Situations</title>
438 An error is signalled if <parameter>type</parameter> is not
439 one of <symbol>:commands</symbol> or
440 <symbol>:results</symbol>.
444 <title>See Also</title>
446 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
447 <member><link linkend="add-sql-stream"><function>add-sql-stream</function></link></member>
448 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>
449 <member><link linkend="list-sql-streams"><function>list-sql-streams</function></link></member>
460 <refentry id="add-sql-stream">
462 <refentrytitle>ADD-SQL-STREAM</refentrytitle>
465 <refname>ADD-SQL-STREAM</refname>
466 <refpurpose>Add a component to the broadcast streams used for recording SQL commands or results.</refpurpose>
467 <refclass>Function</refclass>
470 <title>Syntax</title>
472 <function>add-sql-stream</function> <replaceable>stream</replaceable> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
475 <title>Arguments and Values</title>
478 <term><parameter>stream</parameter></term>
486 <term><parameter>type</parameter></term>
489 One of the following keyword symbols:
490 <symbol>:commands</symbol>, <symbol>:results</symbol> or
491 <symbol>:both</symbol>, defaulting to
492 <symbol>:commands</symbol>.
497 <term><parameter>database</parameter></term>
500 <glossterm linkend="gloss-database-object">database
501 object</glossterm>. This will default to
502 <symbol>*default-database*</symbol>.</para>
506 <term><parameter>result</parameter></term>
516 <title>Description</title>
517 <para>Adds the supplied stream <parameter>stream</parameter> (or
518 &t; for <symbol>*standard-output*</symbol>) as a component of
519 the recording broadcast stream for the SQL recording type
520 specified by <parameter>type</parameter> on
521 <parameter>database</parameter> which defaults to
522 <symbol>*default-database*</symbol>. <parameter>type</parameter>
523 must be one of <symbol>:commands</symbol>,
524 <symbol>:results</symbol>, or <symbol>:both</symbol>, defaulting
525 to <symbol>:commands</symbol>, depending on whether the stream
526 is to be added for recording SQL commands, results or both.
530 <title>Examples</title>
532 (start-sql-recording :type :commands)
534 (with-output-to-string (s)
535 (add-sql-stream s :type :commands)
536 (print-query [select [emplid] [first-name] [last-name] [email] :from [employee]]
539 ;; 2004-07-02 17:38:45 dent/test/dent => SELECT emplid,first_name,last_name,email FROM employee
541 ";; 2004-07-02 17:38:45 dent/test/dent => SELECT emplid,first_name,last_name,email FROM employee
542 1 Vladimir Lenin lenin@soviet.org
543 2 Josef Stalin stalin@soviet.org
544 3 Leon Trotsky trotsky@soviet.org
545 4 Nikita Kruschev kruschev@soviet.org
546 5 Leonid Brezhnev brezhnev@soviet.org
547 6 Yuri Andropov andropov@soviet.org
548 7 Konstantin Chernenko chernenko@soviet.org
549 8 Mikhail Gorbachev gorbachev@soviet.org
550 9 Boris Yeltsin yeltsin@soviet.org
551 10 Vladimir Putin putin@soviet.org "
555 <title>Side Effects</title>
557 The specified broadcast stream(s) associated with
558 <parameter>database</parameter> are modified.
562 <title>Affected by</title>
568 <title>Exceptional Situations</title>
574 <title>See Also</title>
576 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
577 <member><link linkend="sql-stream"><function>sql-stream</function></link></member>
578 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>
579 <member><link linkend="list-sql-streams"><function>list-sql-streams</function></link></member>
590 <refentry id="delete-sql-stream">
592 <refentrytitle>DELETE-SQL-STREAM</refentrytitle>
595 <refname>DELETE-SQL-STREAM</refname>
596 <refpurpose>Remove a component from the broadcast streams used for recording SQL commands or results.</refpurpose>
597 <refclass>Function</refclass>
600 <title>Syntax</title>
602 <function>delete-sql-stream</function> <replaceable>stream</replaceable> &KEY <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
605 <title>Arguments and Values</title>
608 <term><parameter>stream</parameter></term>
616 <term><parameter>stream</parameter></term>
624 <term><parameter>type</parameter></term>
627 One of the following keyword symbols:
628 <symbol>:commands</symbol>, <symbol>:results</symbol> or
629 <symbol>:both</symbol>, defaulting to
630 <symbol>:commands</symbol>.
635 <term><parameter>database</parameter></term>
638 <glossterm linkend="gloss-database-object">database
639 object</glossterm>. This will default to
640 <symbol>*default-database*</symbol>.</para>
644 <term><parameter>result</parameter></term>
654 <title>Description</title>
655 <para>Removes the supplied stream <parameter>stream</parameter>
656 from the recording broadcast stream for the SQL recording type
657 specified by <parameter>type</parameter> on
658 <parameter>database</parameter> which defaults to
659 <symbol>*default-database*</symbol>. <parameter>type</parameter>
660 must be one of <symbol>:commands</symbol>,
661 <symbol>:results</symbol>, or <symbol>:both</symbol>, defaulting
662 to <symbol>:commands</symbol>, depending on whether the stream
663 is to be added for recording SQL commands, results or both.
667 <title>Examples</title>
669 (list-sql-streams :type :both)
670 => (#<Stream for descriptor 7> #<Stream for descriptor 7>)
671 (delete-sql-stream *standard-output* :type :results)
672 => #<Stream for descriptor 7>
673 (list-sql-streams :type :both)
674 => (#<Stream for descriptor 7>)
678 <title>Side Effects</title>
680 The specified broadcast stream(s) associated with
681 <parameter>database</parameter> are modified.
685 <title>Affected by</title>
691 <title>Exceptional Situations</title>
697 <title>See Also</title>
699 <member><link linkend="start-sql-recording"><function>start-sql-recording</function></link></member>
700 <member><link linkend="stop-sql-recording"><function>stop-sql-recording</function></link></member>
701 <member><link linkend="sql-recording-p"><function>sql-recording-p</function></link></member>
702 <member><link linkend="sql-stream"><function>sql-stream</function></link></member>
703 <member><link linkend="add-sql-stream"><function>add-sql-stream</function></link></member>
704 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>
705 <member><link linkend="list-sql-streams"><function>list-sql-streams</function></link></member>
716 <refentry id="list-sql-streams">
718 <refentrytitle>LIST-SQL-STREAMS</refentrytitle>
721 <refname>LIST-SQL-STREAMS</refname>
722 <refpurpose>List the components of the broadcast streams used for recording SQL commands or results.</refpurpose>
723 <refclass>Function</refclass>
726 <title>Syntax</title>
728 <function>list-sql-streams</function> &key <replaceable>type</replaceable> <replaceable>database</replaceable> => <returnvalue>result</returnvalue></synopsis>
731 <title>Arguments and Values</title>
734 <term><parameter>type</parameter></term>
737 One of the following keyword symbols:
738 <symbol>:commands</symbol>, <symbol>:results</symbol> or
739 <symbol>:both</symbol>, defaulting to
740 <symbol>:commands</symbol>.
745 <term><parameter>database</parameter></term>
748 <glossterm linkend="gloss-database-object">database
749 object</glossterm>. This will default to
750 <symbol>*default-database*</symbol>.</para>
754 <term><parameter>result</parameter></term>
764 <title>Description</title>
765 <para>Returns the list of component streams for the broadcast
766 stream recording SQL commands sent to and/or results returned
767 from <parameter>database</parameter> which defaults to
768 <symbol>*default-database*</symbol>. <parameter>type</parameter>
769 must be one of <symbol>:commands</symbol>,
770 <symbol>:results</symbol>, or <symbol>:both</symbol>, defaulting
771 to <symbol>:commands</symbol>, and determines whether the listed
772 streams contain those recording SQL commands, results or both.
776 <title>Examples</title>
778 (list-sql-streams :type :both)
780 (start-sql-recording :type :both)
782 (list-sql-streams :type :both)
783 => (#<Stream for descriptor 7> #<Stream for descriptor 7>)
787 <title>Side Effects</title>
793 <title>Affected by</title>
796 <member><link linkend="add-sql-stream"><function>add-sql-stream</function></link></member>
797 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>
802 <title>Exceptional Situations</title>
804 An error is signalled if <parameter>type</parameter> is passed
805 a value other than <symbol>:commands</symbol>,
806 <symbol>:results</symbol> or <symbol>:both</symbol>.
810 <title>See Also</title>
812 <member><link linkend="sql-stream"><function>sql-stream</function></link></member>
813 <member><link linkend="add-sql-stream"><function>add-sql-stream</function></link></member>
814 <member><link linkend="delete-sql-stream"><function>delete-sql-stream</function></link></member>