# SQL I/O Recording

&clsql; provides a facility for recording SQL commands sent to and/or results returned from the underlying RDBMS to user sprecified streams. This is useful for monitoring &clsql; activity and for debugging applications.

This section documents the functions provided for enabling and disabling SQL recording as well as for manipulating the streams on to which SQL commands and results are recorded.

START-SQL-RECORDING

START-SQL-RECORDING

Start recording SQL commands or results.

Function

### Syntax

          start-sql-recording &key type database =>

### Arguments and Values

`type`

- One of the following keyword symbols: :commands, :results or :both, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

### Description

Starts recording of SQL commands sent to and/or results returned from `database` which defaults to *default-database*. The SQL is output on one or more broadcast streams, initially just *standard-output*, and the functions `add-sql-stream` and `delete-sql-stream` may be used to add or delete command or result recording streams. The default value of `type` is :commands which means that SQL commands sent to `database` are recorded. If `type` is :results then SQL results returned from `database` are recorded. Both commands and results may be recorded by passing `type` value of :both.

### Examples

    (start-sql-recording :type :both)
    =>
    (select [last-name] :from [employee]
                        :where [= [emplid] 1]
                        :field-names nil
                        :flatp t)
    ;; 2004-07-02 16:42:12 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
    ;; 2004-07-02 16:42:12 dent/test/dent <= (Lenin)
    => ("Lenin")

### Side Effects

The command and result recording broadcast streams associated with `database` are reinitialised with only *standard-output* as their component streams.

### Affected by

None.

### Exceptional Situations

None.

### See Also

- `stop-sql-recording`
- `sql-recording-p`
- `sql-stream`
- `add-sql-stream`
- `delete-sql-stream`
- `list-sql-streams`

### Notes

None.

STOP-SQL-RECORDING

STOP-SQL-RECORDING

Stop recording SQL commands or results.

Function

### Syntax

          stop-sql-recording &key type database =>

### Arguments and Values

`type`

- One of the following keyword symbols: :commands, :results or :both, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

### Description

Stops recording of SQL commands sent to and/or results returned from `database` which defaults to *default-database*. The default value of `type` is :commands which means that SQL commands sent to `database` will no longer be recorded. If `type` is :results then SQL results returned from `database` will no longer be recorded. Recording may be stopped for both commands and results by passing `type` value of :both.

### Examples

    (start-sql-recording :type :both)
    =>
    (select [last-name] :from [employee]
                           :where [= [emplid] 1]
                           :field-names nil
                           :flatp t)
    ;; 2004-07-02 16:42:12 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
    ;; 2004-07-02 16:42:12 dent/test/dent <= (Lenin)
    => ("Lenin")
    (stop-sql-recording :type :results)
    =>
    (select [last-name] :from [employee]
                           :where [= [emplid] 1]
                           :field-names nil
                           :flatp t)
    ;; 2004-07-02 16:44:11 dent/test/dent => SELECT last_name FROM employee WHERE (emplid = 1)
    => ("Lenin")

### Side Effects

The command and result recording broadcast streams associated with `database` are reinitialised to &nil;.

### Affected by

None.

### Exceptional Situations

None.

### See Also

- `start-sql-recording`
- `sql-recording-p`

### Notes

None.

SQL-RECORDING-P

SQL-RECORDING-P

Tests whether SQL commands or results are being recorded.

Function

### Syntax

          sql-recording-p &key type database => result

### Arguments and Values

`type`

- One of the following keyword symbols: :commands, :results, :both or :either defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

`result`

- A Boolean.

### Description

Predicate to test whether the SQL recording specified by `type` is currently enabled for `database` which defaults to *default-database*. `type` may be one of :commands, :results, :both or :either, defaulting to :commands, otherwise &nil; is returned.

### Examples

    (start-sql-recording :type :commands)
    =>
    (sql-recording-p :type :commands)
    => T
    (sql-recording-p :type :both)
    => NIL
    (sql-recording-p :type :either)
    => T

### Side Effects

None.

### Affected by

- `start-sql-recording`
- `stop-sql-recording`

### Exceptional Situations

None.

### See Also

- `start-sql-recording`
- `stop-sql-recording`

### Notes

The :both and :either values for the `type` keyword argument are &clsql; extensions.

SQL-STREAM

SQL-STREAM

Returns the broadcast stream used for recording SQL commands or results.

Function

### Syntax

          sql-stream &key type database => result

### Arguments and Values

`type`

- One of the following keyword symbols: :commands or :results, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

`result`

- A broadcast stream or &nil;.

### Description

Returns the broadcast stream used for recording SQL commands sent to or results returned from `database` which defaults to *default-database*. `type` must be one of :commands or :results, defaulting to :commands, and determines whether the stream returned is that used for recording SQL commands or results.

### Examples

    (start-sql-recording :type :commands)
    =>
    (sql-stream :type :commands)
    => #<Broadcast Stream>
    (sql-stream :type :results)
    => NIL

### Side Effects

None.

### Affected by

None.

### Exceptional Situations

An error is signalled if `type` is not one of :commands or :results.

### See Also

- `start-sql-recording`
- `add-sql-stream`
- `delete-sql-stream`
- `list-sql-streams`

### Notes

None.

ADD-SQL-STREAM

ADD-SQL-STREAM

Add a component to the broadcast streams used for recording SQL commands or results.

Function

### Syntax

          add-sql-stream stream &key type database => result

### Arguments and Values

`stream`

- A stream or &t;.

`type`

- One of the following keyword symbols: :commands, :results or :both, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

`result`

- The added stream.

### Description

Adds the supplied stream `stream` (or &t; for *standard-output*) as a component of the recording broadcast stream for the SQL recording type specified by `type` on `database` which defaults to *default-database*. `type` must be one of :commands, :results, or :both, defaulting to :commands, depending on whether the stream is to be added for recording SQL commands, results or both.

### Examples

    (start-sql-recording :type :commands)
    =>
    (with-output-to-string (s)
      (add-sql-stream s :type :commands)
      (print-query [select [emplid] [first-name] [last-name] [email] :from [employee]]
                   :stream s))

    ;; 2004-07-02 17:38:45 dent/test/dent => SELECT emplid,first_name,last_name,email FROM employee
    =>
    ";; 2004-07-02 17:38:45 dent/test/dent => SELECT emplid,first_name,last_name,email FROM employee
    1  Vladimir   Lenin     lenin@soviet.org
    2  Josef      Stalin    stalin@soviet.org
    3  Leon       Trotsky   trotsky@soviet.org
    4  Nikita     Kruschev  kruschev@soviet.org
    5  Leonid     Brezhnev  brezhnev@soviet.org
    6  Yuri       Andropov  andropov@soviet.org
    7  Konstantin Chernenko chernenko@soviet.org
    8  Mikhail    Gorbachev gorbachev@soviet.org
    9  Boris      Yeltsin   yeltsin@soviet.org
    10 Vladimir   Putin     putin@soviet.org     "

### Side Effects

The specified broadcast stream(s) associated with `database` are modified.

### Affected by

None.

### Exceptional Situations

None.

### See Also

- `start-sql-recording`
- `sql-stream`
- `delete-sql-stream`
- `list-sql-streams`

### Notes

None.

DELETE-SQL-STREAM

DELETE-SQL-STREAM

Remove a component from the broadcast streams used for recording SQL commands or results.

Function

### Syntax

          delete-sql-stream stream &KEY type database => result

### Arguments and Values

`stream`

- A stream or &t;.

`stream`

- A stream or &t;.

`type`

- One of the following keyword symbols: :commands, :results or :both, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

`result`

- The added stream.

### Description

Removes the supplied stream `stream` from the recording broadcast stream for the SQL recording type specified by `type` on `database` which defaults to *default-database*. `type` must be one of :commands, :results, or :both, defaulting to :commands, depending on whether the stream is to be added for recording SQL commands, results or both.

### Examples

    (list-sql-streams :type :both)
    => (#<Stream for descriptor 7> #<Stream for descriptor 7>)
    (delete-sql-stream *standard-output* :type :results)
    => #<Stream for descriptor 7>
    (list-sql-streams :type :both)
    => (#<Stream for descriptor 7>)

### Side Effects

The specified broadcast stream(s) associated with `database` are modified.

### Affected by

None.

### Exceptional Situations

None.

### See Also

- `start-sql-recording`
- `stop-sql-recording`
- `sql-recording-p`
- `sql-stream`
- `add-sql-stream`
- `delete-sql-stream`
- `list-sql-streams`

### Notes

None.

LIST-SQL-STREAMS

LIST-SQL-STREAMS

List the components of the broadcast streams used for recording SQL commands or results.

Function

### Syntax

          list-sql-streams &key type database => result

### Arguments and Values

`type`

- One of the following keyword symbols: :commands, :results or :both, defaulting to :commands.

`database`

- A database object. This will default to *default-database*.

`result`

- A list.

### Description

Returns the list of component streams for the broadcast stream recording SQL commands sent to and/or results returned from `database` which defaults to *default-database*. `type` must be one of :commands, :results, or :both, defaulting to :commands, and determines whether the listed streams contain those recording SQL commands, results or both.

### Examples

    (list-sql-streams :type :both)
    => NIL
    (start-sql-recording :type :both)
    =>
    (list-sql-streams :type :both)
    => (#<Stream for descriptor 7> #<Stream for descriptor 7>)

### Side Effects

None.

### Affected by

- `add-sql-stream`
- `delete-sql-stream`

### Exceptional Situations

An error is signalled if `type` is passed a value other than :commands, :results or :both.

### See Also

- `sql-stream`
- `add-sql-stream`
- `delete-sql-stream`

### Notes

None.