+++ /dev/null
-<?xml version='1.0' ?> <!-- -*- DocBook -*- -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
-%myents;
-]>
-
-<reference>
- <title><symbol>CLSQL</symbol></title>
- <partintro>
- <para>This part gives a reference to all the symbols exported
- from the package <symbol>CLSQL-SYS</symbol>, which are also
- re-exported from the package <symbol>CLSQL</symbol>. These
- symbols constitute the normal user-interface of
- &clsql;.</para>
- </partintro>
- <!-- Conditions -->
- <refentry id="clsql-condition">
- <refnamediv>
- <refname>CLSQL-CONDITION</refname>
- <refpurpose>the super-type of all
- &clsql;-specific
- conditions</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This is the super-type of all
- &clsql;-specific conditions
- defined by &clsql;, or any of it's
- database-specific interfaces. There are no defined
- initialization arguments nor any accessors.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-error">
- <refnamediv>
- <refname>CLSQL-ERROR</refname>
- <refpurpose>the super-type of all
- &clsql;-specific
- errors</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This is the super-type of all
- &clsql;-specific conditions that
- represent errors, as defined by
- &clsql;, or any of it's
- database-specific interfaces. There are no defined
- initialization arguments nor any accessors.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-simple-error">
- <refnamediv>
- <refname>CLSQL-SIMPLE-ERROR</refname>
- <refpurpose>Unspecific simple
- &clsql; errors</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-simple-error</errortype></member>
- <member><errortype>simple-condition</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition is used in all instances of errors, where
- there exists no &clsql;-specific
- condition that is more specific. The valid initialization
- arguments and accessors are the same as for
- <errortype>simple-condition</errortype>.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-warning">
- <refnamediv>
- <refname>CLSQL-WARNING</refname>
- <refpurpose>the super-type of all
- &clsql;-specific
- warnings</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-warning</errortype></member>
- <member><errortype>warning</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This is the super-type of all
- &clsql;-specific conditions that
- represent warnings, as defined by
- &clsql;, or any of it's
- database-specific interfaces. There are no defined
- initialization arguments nor any accessors.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-simple-warning">
- <refnamediv>
- <refname>CLSQL-SIMPLE-WARNING</refname>
- <refpurpose>Unspecific simple
- &clsql; warnings</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-simple-warning</errortype></member>
- <member><errortype>simple-condition</errortype></member>
- <member><errortype>clsql-warning</errortype></member>
- <member><errortype>warning</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition is used in all instances of warnings,
- where there exists no
- &clsql;-specific condition that is
- more specific. The valid initialization arguments and
- accessors are the same as for
- <errortype>simple-condition</errortype>.</para>
- </refsect1>
- </refentry>
- <!-- Specifc Conditions -->
- <refentry id="clsql-invalid-spec-error">
- <refnamediv>
- <refname>CLSQL-INVALID-SPEC-ERROR</refname>
- <refpurpose>condition representing errors because of invalid
- connection specifications</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-invalid-spec-error</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition represents errors that occur because the
- user supplies an invalid connection specification to either
- <function>database-name-from-spec</function> or
- <function>connect</function>. The following initialization
- arguments and accessors exist:</para>
- <segmentedlist>
- <segtitle>Initarg</segtitle>
- <segtitle>Accessor</segtitle>
- <segtitle>Description</segtitle>
- <seglistitem>
- <seg><symbol>:connection-spec</symbol></seg>
- <seg><function>clsql-invalid-spec-error-connection-spec</function></seg>
- <seg>The invalid connection specification used.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:database-type</symbol></seg>
- <seg><function>clsql-invalid-spec-error-database-type</function></seg>
- <seg>The Database type used in the attempt.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:template</symbol></seg>
- <seg><function>clsql-invalid-spec-error-template</function></seg>
- <seg>An argument describing the template that a valid
- connection specification must match for this database type.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- </refentry>
- <refentry id="clsql-connect-error">
- <refnamediv>
- <refname>CLSQL-CONNECT-ERROR</refname>
- <refpurpose>condition representing errors during
- connection</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-connect-error</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition represents errors that occur while trying
- to connect to a database. The following initialization
- arguments and accessors exist:</para>
- <segmentedlist>
- <segtitle>Initarg</segtitle>
- <segtitle>Accessor</segtitle>
- <segtitle>Description</segtitle>
- <seglistitem>
- <seg><symbol>:database-type</symbol></seg>
- <seg><function>clsql-connect-error-database-type</function></seg>
- <seg>Database type for the connection attempt</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:connection-spec</symbol></seg>
- <seg><function>clsql-connect-error-connection-spec</function></seg>
- <seg>The connection specification used in the
- connection attempt.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:errno</symbol></seg>
- <seg><function>clsql-connect-error-errno</function></seg>
- <seg>The numeric or symbolic error specification
- returned by the database back-end. The values and
- semantics of this are interface specific.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:error</symbol></seg>
- <seg><function>clsql-connect-error-error</function></seg>
- <seg>A string describing the problem that occurred,
- possibly one returned by the database back-end.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- </refentry>
- <refentry id="clsql-sql-error">
- <refnamediv>
- <refname>CLSQL-SQL-ERROR</refname>
- <refpurpose>condition representing errors during query or
- command execution</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-sql-error</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition represents errors that occur while
- executing SQL statements, either as part of query operations
- or command execution, either explicitly or implicitly, as
- caused e.g. by <function>with-transaction</function>.
- The following initialization arguments and accessors exist:</para>
- <segmentedlist>
- <segtitle>Initarg</segtitle>
- <segtitle>Accessor</segtitle>
- <segtitle>Description</segtitle>
- <seglistitem>
- <seg><symbol>:database</symbol></seg>
- <seg><function>clsql-sql-error-database</function></seg>
- <seg>The database object that was involved in the
- incident.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:expression</symbol></seg>
- <seg><function>clsql-sql-error-expression</function></seg>
- <seg>The SQL expression whose execution caused the error.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:errno</symbol></seg>
- <seg><function>clsql-sql-error-errno</function></seg>
- <seg>The numeric or symbolic error specification
- returned by the database back-end. The values and
- semantics of this are interface specific.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:error</symbol></seg>
- <seg><function>clsql-sql-error-error</function></seg>
- <seg>A string describing the problem that occurred,
- possibly one returned by the database back-end.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- </refentry>
- <refentry id="clsql-exists-condition">
- <refnamediv>
- <refname>CLSQL-EXISTS-CONDITION</refname>
- <refpurpose>condition indicating situations arising because of
- existing connections</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-exists-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition is the super-type of all conditions which
- represents problems that occur during calls to
- <function>connect</function>, if a connection to the
- database exists already. Depending on the value of
- <parameter>if-exists</parameter> to the call of
- <function>connect</function>, either a warning, an error or
- no condition at all is signalled. If a warning or error is
- signalled, either
- <errortype>clsql-exists-warning</errortype> or
- <errortype>clsql-exists-error</errortype> is signalled,
- which are subtypes of
- <errortype>clsql-exists-condition</errortype> and
- <errortype>clsql-warning</errortype> or
- <errortype>clsql-error</errortype>.
- <errortype>clsql-exists-condition</errortype> is never
- signalled itself.</para>
- <para>
- The following initialization arguments and accessors exist:</para>
- <segmentedlist>
- <segtitle>Initarg</segtitle>
- <segtitle>Accessor</segtitle>
- <segtitle>Description</segtitle>
- <seglistitem>
- <seg><symbol>:old-db</symbol></seg>
- <seg><function>clsql-exists-condition-old-db</function></seg>
- <seg>The database object that represents the existing
- connection. This slot is always filled.</seg>
- </seglistitem>
- <seglistitem>
- <seg><symbol>:new-db</symbol></seg>
- <seg><function>clsql-exists-condition-new-db</function></seg>
- <seg>The database object that will be used and returned by
- this call to connect, if execution continues normally.
- This can be either <symbol>nil</symbol>, indicating that
- a new database object is to be created on continuation,
- or a database object representing the newly created
- continuation, or the same database object as
- <symbol>old-db</symbol>, indicating that the existing
- database object will be reused. This slot is always
- filled and defaults to <symbol>nil</symbol>.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- </refentry>
- <refentry id="clsql-exists-warning">
- <refnamediv>
- <refname>CLSQL-EXISTS-WARNING</refname>
- <refpurpose>condition representing warnings arising because of
- existing connections</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-exists-warning</errortype></member>
- <member><errortype>clsql-exists-condition</errortype></member>
- <member><errortype>clsql-warning</errortype></member>
- <member><errortype>warning</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition is a subtype of
- <errortype>clsql-exists-condition</errortype>, and is
- signalled during calls to <function>connect</function> when
- there is an existing connection, and
- <parameter>if-exists</parameter> is either
- <symbol>:warn-new</symbol> or <symbol>:warn-old</symbol>.
- In the former case, <symbol>new-db</symbol> will be the
- newly created database object, in the latter case it will be
- the existing old database object.</para>
- <para>
- The initialization arguments and accessors are the same as
- for <errortype>clsql-exists-condition</errortype>.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-exists-error">
- <refnamediv>
- <refname>CLSQL-EXISTS-ERROR</refname>
- <refpurpose>condition representing errors arising because of
- existing connections</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-exists-error</errortype></member>
- <member><errortype>clsql-exists-condition</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition is a subtype of
- <errortype>clsql-exists-condition</errortype>, and is
- signalled during calls to <function>connect</function> when
- there is an existing connection, and
- <parameter>if-exists</parameter> is <symbol>:error</symbol>.
- In this case, <symbol>new-db</symbol> will be
- <symbol>nil</symbol>, indicating that the database object to
- be returned by <function>connect</function> depends on user
- action in continuing from this correctable error.</para>
- <para>
- The initialization arguments and accessors are the same as
- for <errortype>clsql-exists-condition</errortype>.</para>
- </refsect1>
- </refentry>
- <refentry id="clsql-closed-error">
- <refnamediv>
- <refname>CLSQL-CLOSED-ERROR</refname>
- <refpurpose>condition representing errors because the database
- has already been closed</refpurpose>
- <refclass>Condition Type</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><errortype>clsql-closed-error</errortype></member>
- <member><errortype>clsql-error</errortype></member>
- <member><errortype>error</errortype></member>
- <member><errortype>serious-condition</errortype></member>
- <member><errortype>clsql-condition</errortype></member>
- <member><errortype>condition</errortype></member>
- <member><errortype>t</errortype></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This condition represents errors that occur because the
- user invokes an operation on the given database object,
- although the database is invalid because
- <function>disconnect</function> has already been called on
- this database object.</para>
- <para>Functions which signal this error when called with a
- closed database will usually provide a
- <symbol>continue</symbol> restart, that will just return nil
- from the function.</para>
- <para>
- The following initialization arguments and accessors exist:</para>
- <segmentedlist>
- <segtitle>Initarg</segtitle>
- <segtitle>Accessor</segtitle>
- <segtitle>Description</segtitle>
- <seglistitem>
- <seg><symbol>:database</symbol></seg>
- <seg><function>clsql-closed-error-database</function></seg>
- <seg>The database object that was involved in the
- incident.</seg>
- </seglistitem>
- </segmentedlist>
- </refsect1>
- </refentry>
-
- <!-- Database Types -->
- <refentry id="default-database-type">
- <refnamediv>
- <refname>*DEFAULT-DATABASE-TYPE*</refname>
- <refpurpose>The default database type to use</refpurpose>
- <refclass>Variable</refclass>
- </refnamediv>
- <refsect1>
- <title>Value Type</title>
- <para>Any keyword representing a valid database back-end of
- &clsql;, or
- <symbol>nil</symbol>.</para>
- </refsect1>
- <refsect1>
- <title>Initial Value</title>
- <para><symbol>nil</symbol></para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>The value of this variable is used in calls to
- <function>initialize-database-type</function> and
- <function>connect</function> as the default
- value of the <parameter>database-type</parameter>
- parameter.</para>
- <caution>
- <para>If the value of this variable is <symbol>nil</symbol>,
- then all calls to
- <function>initialize-database-type</function> or
- <function>connect</function> will have to specify the
- <parameter>database-type</parameter> to use, or a
- general-purpose error will be signalled.</para>
- </caution>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(setf *default-database-type* :mysql)
-=> :mysql
-(initialize-database-type)
-=> t
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="initialized-database-types">
- <refnamediv>
- <refname>*INITIALIZED-DATABASE-TYPES*</refname>
- <refpurpose>List of all initialized database types</refpurpose>
- <refclass>Variable</refclass>
- </refnamediv>
- <refsect1>
- <title>Value Type</title>
- <para>A list of all initialized database types, each of which
- represented by it's corresponding keyword.</para>
- </refsect1>
- <refsect1>
- <title>Initial Value</title>
- <para><symbol>nil</symbol></para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This variable is updated whenever
- <function>initialize-database-type</function> is called for a
- database type which hasn't already been initialized before,
- as determined by this variable. In that case the keyword
- representing the database type is pushed onto the list
- stored in
- <symbol>*INITIALIZED-DATABASE-TYPES*</symbol>.</para>
- <caution>
- <para>Attempts to modify the value of this variable will
- result in undefined behaviour.</para>
- </caution>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(setf *default-database-type* :mysql)
-=> :mysql
-(initialize-database-type)
-=> t
-*initialized-database-types*
-=> (:MYSQL)
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>
- <simplelist>
- <member><function>initialize-database-type</function></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>Direct access to this variable is primarily provided
- because of compatibility with Harlequin's <application>Common
- SQL</application>.</para>
- </refsect1>
- </refentry>
- <refentry id="initialize-database-type">
- <refnamediv>
- <refname>INITIALIZE-DATABASE-TYPE</refname>
- <refpurpose>Initializes a database type</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>initialize-database-type</function> &key <replaceable>database-type</replaceable> => <returnvalue>result</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>database-type</parameter></term>
- <listitem>
- <para>The database type to initialize, i.e. a keyword
- symbol denoting a known database back-end. Defaults to
- the value of
- <symbol>*default-database-type*</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>result</returnvalue></term>
- <listitem>
- <para>Either <symbol>nil</symbol> if the initialization
- attempt fails, or <symbol>t</symbol> otherwise.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>If the back-end specified by
- <parameter>database-type</parameter> has not already been
- initialized, as seen from
- <symbol>*initialized-database-types*</symbol>, an attempt is
- made to initialize the database. If this attempt succeeds,
- or the back-end has already been initialized, the function
- returns t, and places the keyword denoting the database type
- onto the list stored in
- <symbol>*initialized-database-types*</symbol>, if not
- already present.</para>
- <para>If initialization fails, the function returns
- <symbol>nil</symbol>, and/or signals an error of type
- <errortype>clsql-error</errortype>. The kind of action
- taken depends on the back-end and the cause of the
- problem.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-*initialized-database-types*
-=> NIL
-(setf *default-database-type* :mysql)
-=> :MYSQL
-(initialize-database-type)
->> Compiling LAMBDA (#:G897 #:G898 #:G901 #:G902):
->> Compiling Top-Level Form:
->>
-=> T
-*initialized-database-types*
-=> (:MYSQL)
-(initialize-database-type)
-=> T
-*initialized-database-types*
-=> (:MYSQL)
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>The database back-end corresponding to the database type
- specified is initialized, unless it has already been
- initialized. This can involve any number of other side
- effects, as determined by the back-end implementation (like
- e.g. loading of foreign code, calling of foreign code,
- networking operations, etc.). If initialization is
- attempted and succeeds, the
- <parameter>database-type</parameter> is pushed onto the list
- stored in
- <symbol>*initialized-database-types*</symbol>.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>
- <simplelist>
- <member><symbol>*default-database-type*</symbol></member>
- <member><symbol>*initialized-database-types*</symbol></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If an error is encountered during the initialization
- attempt, the back-end may signal errors of kind
- <errortype>clsql-error</errortype>.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <!-- Databases Connection and Disconnection -->
- <refentry id="connect-if-exists">
- <refnamediv>
- <refname>*CONNECT-IF-EXISTS*</refname>
- <refpurpose>Default value for the
- <parameter>if-exists</parameter> parameter of
- <function>connect</function>.</refpurpose>
- <refclass>Variable</refclass>
- </refnamediv>
- <refsect1>
- <title>Value Type</title>
- <para>A valid argument to the <parameter>if-exists</parameter>
- parameter of <function>connect</function>, i.e. one of
- <simplelist type="inline">
- <member><symbol>:new</symbol></member>
- <member><symbol>:warn-new</symbol></member>
- <member><symbol>:error</symbol></member>
- <member><symbol>:warn-old</symbol></member>
- <member><symbol>:old</symbol></member>
- </simplelist>.
- </para>
- </refsect1>
- <refsect1>
- <title>Initial Value</title>
- <para><symbol>:error</symbol></para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>The value of this variable is used in calls to
- <function>connect</function> as the default
- value of the <parameter>if-exists</parameter>
- parameter. See <link
- linkend="connect"><function>connect</function></link> for
- the semantics of the valid values for this variable.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link
- linkend="connect"><function>connect</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="connected-databases">
- <refnamediv>
- <refname>CONNECTED-DATABASES</refname>
- <refpurpose>Return the list of active database
- objects.</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>connected-databases</function> => <returnvalue>databases</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><returnvalue>databases</returnvalue></term>
- <listitem>
- <para>The list of active database objects.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This function returns the list of active database
- objects, i.e. all those database objects created by calls to
- <function>connect</function>, which have not been closed by
- calling <function>disconnect</function> on them.</para>
- <caution>
- <para>The consequences of modifying the list returned by
- <function>connected-databases</function> are
- undefined.</para>
- </caution>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(connected-databases)
-=> NIL
-(connect '(nil "template1" "dent" nil) :database-type :postgresql)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
-(connected-databases)
-=> (#<CLSQL-MYSQL:MYSQL-DATABASE {4830C5AD}>
- #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
-(disconnect)
-=> T
-(connected-databases)
-=> (#<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {4830BC65}>)
-(disconnect)
-=> T
-(connected-databases)
-=> NIL
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>
- <simplelist>
- <member><function>connect</function></member>
- <member><function>disconnect</function></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="default-database">
- <refnamediv>
- <refname>*DEFAULT-DATABASE*</refname>
- <refpurpose>The default database object to use</refpurpose>
- <refclass>Variable</refclass>
- </refnamediv>
- <refsect1>
- <title>Value Type</title>
- <para>Any object of type <type>database</type>, or nil to
- indicate no default database.</para>
- </refsect1>
- <refsect1>
- <title>Initial Value</title>
- <para><symbol>nil</symbol></para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>Any function or macro in
- &clsql; that operates on a
- database uses the value of this variable as the default
- value for it's <parameter>database</parameter>
- parameter.</para>
- <para>The value of this parameter is changed by calls to
- <function>connect</function>, which sets
- <symbol>*default-database*</symbol> to the database object
- it returns. It is also changed by calls to
- <function>disconnect</function>, when the database object
- being disconnected is the same as the value of
- <symbol>*default-database*</symbol>. In this case
- <function>disconnect</function> sets
- <symbol>*default-database*</symbol> to the first database
- that remains in the list of active databases as returned by
- <function>connected-databases</function>, or
- <symbol>nil</symbol> if no further active databases
- exist.</para>
- <para>The user may change <symbol>*default-database*</symbol>
- at any time to a valid value of his choice.</para>
- <caution>
- <para>If the value of <symbol>*default-database*</symbol> is
- <symbol>nil</symbol>, then all calls to
- &clsql; functions on databases
- must provide a suitable <parameter>database</parameter>
- parameter, or an error will be signalled.</para>
- </caution>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(connected-databases)
-=> NIL
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
-(connect '(nil "template1" "dent" nil) :database-type :postgresql)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql :if-exists :new)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
-*default-database*
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48387265}>
-(disconnect)
-=> T
-*default-database*
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {483868FD}>
-(disconnect)
-=> T
-*default-database*
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48385F55}>
-(disconnect)
-=> T
-*default-database*
-=> NIL
-(connected-databases)
-=> NIL
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>
- <simplelist>
- <member><link linkend="connect"><function>connect</function></link></member>
- <member><link linkend="disconnect"><function>disconnect</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <note>
- <para>This variable is intended to facilitate working with
- &clsql; in an interactive
- fashion at the top-level loop, and because of this,
- <function>connect</function> and
- <function>disconnect</function> provide some fairly
- complex behaviour to keep
- <symbol>*default-database*</symbol> set to useful values.
- Programmatic use of &clsql;
- should never depend on the value of
- <symbol>*default-database*</symbol> and should provide
- correct database objects via the
- <parameter>database</parameter> parameter to functions
- called.</para>
- </note>
- </refsect1>
- </refentry>
- <!-- Classes -->
- <refentry id="database">
- <refnamediv>
- <refname>DATABASE</refname>
- <refpurpose>The super-type of all
- &clsql; databases</refpurpose>
- <refclass>Class</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><type>database</type></member>
- <member><type>standard-object</type></member>
- <member><type>t</type></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This class is the superclass of all
- &clsql; databases. The different
- database back-ends derive subclasses of this class to
- implement their databases. No instances of this class are
- ever created by &clsql;.</para>
- </refsect1>
- </refentry>
- <refentry id="closed-database">
- <refnamediv>
- <refname>CLOSED-DATABASE</refname>
- <refpurpose>The class representing all closed
- &clsql; databases</refpurpose>
- <refclass>Class</refclass>
- </refnamediv>
- <refsect1>
- <title>Class Precedence List</title>
- <para>
- <simplelist type="inline">
- <member><type>closed-database</type></member>
- <member><type>standard-object</type></member>
- <member><type>t</type></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>&clsql; <type>database</type>
- instances are changed to this class via
- <function>change-class</function> after they are closed via
- <function>disconnect</function>. All functions and generic
- functions that take database objects as arguments will
- signal errors of type
- <errortype>clsql-closed-error</errortype> when they are
- called on instances of <type>closed-database</type>, with
- the exception of <function>database-name</function>, which
- will continue to work as for instances of
- <type>database</type>.</para>
- </refsect1>
- </refentry>
- <!-- Functions -->
- <refentry id="database-name">
- <refnamediv>
- <refname>DATABASE-NAME</refname>
- <refpurpose>Get the name of a database object</refpurpose>
- <refclass>Generic Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>database-name</function> <replaceable>database</replaceable> => <returnvalue>name</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A database object, either of type
- <type>database</type> or of type
- <type>closed-database</type>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>name</returnvalue></term>
- <listitem>
- <para>A string describing the identity of the database
- to which this database object is connected to.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This function returns the database name of the given
- database. The database name is a string which somehow
- describes the identity of the database to which this
- database object is or has been connected. The database name
- of a database object is determined at
- <function>connect</function> time, when a call to
- <function>database-name-from-spec</function> derives the
- database name from the connection specification passed to
- <function>connect</function> in the
- <parameter>connection-spec</parameter> parameter.</para>
- <para>The database name is used via
- <function>find-database</function> in
- <function>connect</function> to determine whether database
- connections to the specified database exist already.</para>
- <para>Usually the database name string will include
- indications of the host, database name, user, or port that
- where used during the connection attempt. The only
- important thing is that this string shall try to identify
- the database at the other end of the connection. Connection
- specifications parts like passwords and credentials shall
- not be used as part of the database name.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
-=> "dent/newesim/dent"
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
-(database-name *default-database*)
-=> "dent/newesim/dent"
-
-(database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
-=> "/template1/dent"
-(connect '(nil "template1" "dent" nil) :database-type :postgresql)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-(database-name *default-database*)
-=> "/template1/dent"
-
-(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
-=> "www.pmsf.de/template1/dent"
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>
- <simplelist>
- <member><link linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>Will signal an error if the object passed as the
- <parameter>database</parameter> parameter is neither of type
- <type>database</type> nor of type
- <type>closed-database</type>.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link
- linkend="connect"><function>connect</function></link></member>
- <member><link
- linkend="find-database"><function>find-database</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="find-database">
- <refnamediv>
- <refname>FIND-DATABASE</refname>
- <refpurpose>Locate a database object through it's
- name.</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>find-database</function> <replaceable>database</replaceable> &optional <replaceable>errorp</replaceable> => <returnvalue>result</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A database object or a string, denoting a database
- name.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>errorp</parameter></term>
- <listitem>
- <para>A generalized boolean. Defaults to
- <symbol>t</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>result</returnvalue></term>
- <listitem>
- <para>Either a database object, or, if
- <parameter>errorp</parameter> is <symbol>nil</symbol>,
- possibly <symbol>nil</symbol>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para><function>find-database</function> locates an active
- database object given the specification in
- <parameter>database</parameter>. If
- <parameter>database</parameter> is an object of type
- <type>database</type>, <function>find-database</function>
- returns this. Otherwise it will search the active databases
- as indicated by the list returned by
- <function>connected-databases</function> for a database
- whose name (as returned by
- <function>database-name</function> is equal as per
- <function>string=</function> to the string passed as
- <parameter>database</parameter>. If it succeeds, it returns
- the first database found.</para>
- <para>If it fails to find a matching database, it will signal
- an error of type <errortype>clsql-error</errortype> if
- <parameter>errorp</parameter> is true. If
- <parameter>errorp</parameter> is <symbol>nil</symbol>, it
- will return <symbol>nil</symbol> instead.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
-=> "dent/newesim/dent"
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
-(database-name *default-database*)
-=> "dent/newesim/dent"
-
-(database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
-=> "/template1/dent"
-(connect '(nil "template1" "dent" nil) :database-type :postgresql)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-(database-name *default-database*)
-=> "/template1/dent"
-
-(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
-=> "www.pmsf.de/template1/dent"
-
-(find-database "dent/newesim/dent")
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
-(find-database "/template1/dent")
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-(find-database "www.pmsf.de/template1/dent" nil)
-=> NIL
-(find-database **)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>
- <simplelist>
- <member><link linkend="connected-databases"><function>connected-databases</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>Will signal an error of type
- <errortype>clsql-error</errortype> if no matching database
- can be found, and <parameter>errorp</parameter> is true.
- Will signal an error if the value of
- <parameter>database</parameter> is neither an object of type
- <type>database</type> nor a string.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link
- linkend="database-name"><function>database-name</function></link></member>
- <member><link
- linkend="database-name-from-spec"><function>database-name-from-spec</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
-
- <refentry id="connect">
- <refnamediv>
- <refname>CONNECT</refname>
- <refpurpose>create a connection to a database</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>connect</function> <replaceable>connection-spec</replaceable> &key <replaceable>if-exists</replaceable> <replaceable>database-type</replaceable> <replaceable>pool</replaceable> => <returnvalue>database</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>connection-spec</parameter></term>
- <listitem>
- <para>A connection specification</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>if-exists</parameter></term>
- <listitem>
- <para>This indicates the action to take if a connection
- to the same database exists already. See below for the
- legal values and actions. It defaults to the value of
- <symbol>*connect-if-exists*</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database-type</parameter></term>
- <listitem>
- <para>A database type specifier, i.e. a keyword.
- This defaults to the value of
- <symbol>*default-database-type*</symbol></para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>pool</parameter></term>
- <listitem>
- <para>A boolean flag. If &t;, acquire connection from a
- pool of open connections. If the pool is empty, a new
- connection is created. The default is &nil;.
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>database</returnvalue></term>
- <listitem>
- <para>The database object representing the connection.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This function takes a connection specification and
- a database type and creates a connection to the database
- specified by those. The type and structure of the
- connection specification depend on the database type.</para>
- <para>The parameter <parameter>if-exists</parameter> specifies
- what to do if a connection to the database specified exists
- already, which is checked by calling
- <function>find-database</function> on the database name
- returned by <function>database-name-from-spec</function>
- when called with the <parameter>connection-spec</parameter>
- and <parameter>database-type</parameter> parameters. The
- possible values of <parameter>if-exists</parameter> are:
- <variablelist>
- <varlistentry>
- <term><symbol>:new</symbol></term>
- <listitem>
- <para>Go ahead and create a new connection.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>:warn-new</symbol></term>
- <listitem>
- <para>This is just like <symbol>:new</symbol>, but
- also signals a warning of type
- <errortype>clsql-exists-warning</errortype>,
- indicating the old and newly created
- databases.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>:error</symbol></term>
- <listitem>
- <para>This will cause <function>connect</function> to
- signal a correctable error of type
- <errortype>clsql-exists-error</errortype>. The
- user may choose to proceed, either by indicating
- that a new connection shall be created, via the
- restart <symbol>create-new</symbol>, or by
- indicating that the existing connection shall be
- used, via the restart
- <symbol>use-old</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>:old</symbol></term>
- <listitem>
- <para>This will cause <function>connect</function> to
- use an old connection if one exists.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><symbol>:warn-old</symbol></term>
- <listitem>
- <para>This is just like <symbol>:old</symbol>, but
- also signals a warning of type
- <errortype>clsql-exists-warning</errortype>,
- indicating the old database used, via the slots
- <symbol>old-db</symbol> and
- <symbol>new-db</symbol></para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- <para>The database name of the returned database object will
- be the same under <function>string=</function> as that which
- would be returned by a call to
- <function>database-name-from-spec</function> with the given
- <parameter>connection-spec</parameter> and
- <parameter>database-type</parameter> parameters.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
-=> "dent/newesim/dent"
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}>
-(database-name *)
-=> "dent/newesim/dent"
-
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
->> In call to CONNECT:
->> There is an existing connection #<CLSQL-MYSQL:MYSQL-DATABASE {48036F6D}> to database dent/newesim/dent.
->>
->> Restarts:
->> 0: [CREATE-NEW] Create a new connection.
->> 1: [USE-OLD ] Use the existing connection.
->> 2: [ABORT ] Return to Top-Level.
->>
->> Debug (type H for help)
->>
->> (CONNECT ("dent" "newesim" "dent" "dent") :IF-EXISTS NIL :DATABASE-TYPE ...)
->> Source:
->> ; File: /prj/CLSQL/sql/sql.cl
->> (RESTART-CASE (ERROR 'CLSQL-EXISTS-ERROR :OLD-DB OLD-DB)
->> (CREATE-NEW NIL :REPORT "Create a new connection."
->> (SETQ RESULT #))
->> (USE-OLD NIL :REPORT "Use the existing connection."
->> (SETQ RESULT OLD-DB)))
->> 0] 0
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {480451F5}>
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>A database connection is established, and the resultant
- database object is registered, so as to appear in the list
- returned by <function>connected-databases</function>.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>
- <simplelist>
- <member><symbol>*default-database-type*</symbol></member>
- <member><symbol>*connect-if-exists*</symbol></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the connection specification is not syntactically or
- semantically correct for the given database type, an error
- of type <errortype>clsql-invalid-spec-error</errortype> is
- signalled. If during the connection attempt an error is
- detected (e.g. because of permission problems, network
- trouble or any other cause), an error of type
- <errortype>clsql-connect-error</errortype> is
- signalled.</para>
- <para>If a connection to the database specified by
- <parameter>connection-spec</parameter> exists already,
- conditions are signalled according to the
- <parameter>if-exists</parameter> parameter, as described
- above.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><function>connected-databases</function></member>
- <member><link linkend="disconnect"><function>disconnect</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
-
- <refentry id="disconnect">
- <refnamediv>
- <refname>DISCONNECT</refname>
- <refpurpose>close a database connection</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>disconnect</function> &key <replaceable>database</replaceable> <replaceable>pool</replaceable> => <returnvalue>t</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>pool</parameter></term>
- <listitem>
- <para>A boolean flag indicating whether to put the database into a
-pool of opened databases. If &t;, rather than terminating the database connection, the
-connection is left open and the connection is placed into a pool of connections. Subsequent
-calls to <link linkend="connect"><function>connect</function></link> can then reuse this connection.
-The default is &nil;.
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>The database to disconnect, which defaults to the
- database indicated by
- <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This function takes a <type>database</type> object as
- returned by <function>connect</function>, and closes the
- connection. The class of the object passed is changed to
- <type>closed-database</type> after the disconnection
- succeeds, thereby preventing further use of the object as
- an argument to &clsql; functions,
- with the exception of <function>database-name</function>.
- If the user does pass a closed database object to any other
- &clsql; function, an error of type
- <errortype>clsql-closed-error</errortype> is
- signalled.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(disconnect :database (find-database "dent/newesim/dent"))
-=> T
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>The database connection is closed, and the database
- object is removed from the list of connected databases as
- returned by <function>connected-databases</function>.</para>
- <para>The class of the database object is changed to
- <type>closed-database</type>.</para>
- <para>If the database object passed is the same under
- <function>eq</function> as the value of
- <symbol>*default-database*</symbol>, then
- <symbol>*default-database*</symbol> is set to the first
- remaining database from
- <function>connected-databases</function> or to nil if no
- further active database exists.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>
- <simplelist>
- <member><symbol>*default-database*</symbol></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If during the disconnection attempt an error is
- detected (e.g. because of network trouble or any other
- cause), an error of type <errortype>clsql-error</errortype>
- might be signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="connect"><function>connect</function></link></member>
- <member><link linkend="connect"><function>closed-database</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
-
- <refentry id="disconnect-pooled">
- <refnamediv>
- <refname>DISCONNECT-POOLED</refname>
- <refpurpose>closes all pooled database connections</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>disconnect-pool</function> => <returnvalue>t</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This function disconnects all database connections
- that have been placed into the pool. Connections are placed
- in the pool by calling
- <link linkend="disconnect"><function>disconnection</function></link>.
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(disconnect-pool)
-=> T
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Database connections will be closed and entries in the pool are removed.
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>
- <simplelist>
- <member><function>disconnect</function></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If during the disconnection attempt an error is
- detected (e.g. because of network trouble or any other
- cause), an error of type <errortype>clsql-error</errortype>
- might be signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="connect"><function>connect</function></link></member>
- <member><link linkend="connect"><function>closed-database</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
-
- <refentry id="database-name-from-spec">
- <refnamediv>
- <refname>DATABASE-NAME-FROM-SPEC</refname>
- <refpurpose>Return the database name string corresponding to
- the given connection specification.</refpurpose>
- <refclass>Generic Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis>
- <function>database-name-from-spec</function> <replaceable>connection-spec</replaceable> <replaceable>database-type</replaceable> => <returnvalue>name</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>connection-spec</parameter></term>
- <listitem>
- <para>A connection specification, whose structure and
- interpretation are dependent on the
- <parameter>database-type</parameter>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database-type</parameter></term>
- <listitem>
- <para>A database type specifier, i.e. a keyword.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>name</returnvalue></term>
- <listitem>
- <para>A string denoting a database name.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This generic function takes a connection specification
- and a database type and returns the database name of the
- database object that would be created had
- <function>connect</function> been called with the given
- connection specification and database types.</para>
- <para>This function is useful in determining a database name
- from the connection specification, since the way the
- connection specification is converted into a database name
- is dependent on the database type.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(database-name-from-spec '("dent" "newesim" "dent" "dent") :mysql)
-=> "dent/newesim/dent"
-(connect '("dent" "newesim" "dent" "dent") :database-type :mysql)
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {48391DCD}>
-(database-name *default-database*)
-=> "dent/newesim/dent"
-
-(database-name-from-spec '(nil "template1" "dent" nil) :postgresql)
-=> "/template1/dent"
-(connect '(nil "template1" "dent" nil) :database-type :postgresql)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-(database-name *default-database*)
-=> "/template1/dent"
-
-(database-name-from-spec '("www.pmsf.de" "template1" "dent" nil) :postgresql)
-=> "www.pmsf.de/template1/dent"
-
-(find-database "dent/newesim/dent")
-=> #<CLSQL-MYSQL:MYSQL-DATABASE {484E91C5}>
-(find-database "/template1/dent")
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
-(find-database "www.pmsf.de/template1/dent" nil)
-=> NIL
-(find-database **)
-=> #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {48392D2D}>
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the value of <parameter>connection-spec</parameter>
- is not a valid connection specification for the given
- database type, an error of type
- <errortype>clsql-invalid-spec-error</errortype> might be
- signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="connect"><function>connect</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <!-- Querying Operations -->
- <refentry id="execute-command">
- <refnamediv>
- <refname>EXECUTE-COMMAND</refname>
- <refpurpose>Execute an SQL command which returns no
- values.</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>execute-command</function> <replaceable>sql-expression</replaceable> &key <replaceable>database</replaceable> => <returnvalue>t</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>sql-expression</parameter></term>
- <listitem>
- <para>An <glossterm linkend="gloss-sql-expression">sql
- expression</glossterm> that represents an SQL
- statement which will return no values.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A
- <glossterm linkend="gloss-database-object">database
- object</glossterm>. This will default to the value
- of <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This will execute the command given by
- <parameter>sql-expression</parameter> in the
- <parameter>database</parameter> specified. If the execution
- succeeds it will return <symbol>t</symbol>, otherwise an
- error of type <errortype>clsql-sql-error</errortype> will
- be signalled.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(execute-command "create table eventlog (time char(30),event char(70))")
-=> T
-
-(execute-command "create table eventlog (time char(30),event char(70))")
->>
->> While accessing database #<CLSQL-POSTGRESQL:POSTGRESQL-DATABASE {480B2B6D}>
->> with expression "create table eventlog (time char(30),event char(70))":
->> Error NIL: ERROR: amcreate: eventlog relation already exists
->> has occurred.
->>
->> Restarts:
->> 0: [ABORT] Return to Top-Level.
->>
->> Debug (type H for help)
->>
->> (CLSQL-POSTGRESQL::|(PCL::FAST-METHOD DATABASE-EXECUTE-COMMAND (T POSTGRESQL-DATABASE))|
->> #<unused-arg>
->> #<unused-arg>
->> #<unavailable-arg>
->> #<unavailable-arg>)
->> Source: (ERROR 'CLSQL-SQL-ERROR :DATABASE DATABASE :EXPRESSION ...)
->> 0] 0
-
-(execute-command "drop table eventlog")
-=> T
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Whatever effects the execution of the SQL statement has
- on the underlying database, if any.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the execution of the SQL statement leads to any
- errors, an error of type
- <errortype>clsql-sql-error</errortype> is signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="query"><function>query</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="query">
- <refnamediv>
- <refname>QUERY</refname>
- <refpurpose>Execute an SQL query and return the tuples as a
- list</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>query</function> <replaceable>query-expression</replaceable> &key <replaceable>database</replaceable> <replaceable>types</replaceable> => <returnvalue>result</returnvalue></synopsis>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>query-expression</parameter></term>
- <listitem>
- <para>An <glossterm linkend="gloss-sql-expression">sql
- expression</glossterm> that represents an SQL
- query which is expected to return a (possibly empty)
- result set.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A
- <glossterm linkend="gloss-database-object">database
- object</glossterm>. This will default to the value
- of <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>types</parameter></term>
- <listitem>
- <para>A
- <glossterm linkend="gloss-field-types">field type
- specififier</glossterm>. The default is &nil;.
- </para>
- <para>
- The purpose of this argument is cause &clsql; to
- import SQL numeric fields into numeric Lisp objects
- rather than strings. This reduces the cost of
- allocating a temporary string and the &clsql; users'
- inconvenience of converting number strings into number
- objects.
- </para>
- <para>
- A value of <symbol>:auto</symbol> causes &clsql;
- to automatically convert SQL fields into a
- numeric format where applicable. The default value of
- &nil; causes all fields to be returned as strings
- regardless of the SQL type. Otherwise a list is expected
- which has a element for each field that specifies the
- conversion. If the list is shorter than the number
- of fields, the a value of <symbol>t</symbol> is
- assumed for the field. If the list is longer than
- the number of fields, the extra elements are
- ignored.
- <simplelist type="vert">
- <member><symbol>:int</symbol> Field is imported as a
- signed integer, from 8-bits to 64-bits depending
- upon the field type.
- </member>
- <member><symbol>:double</symbol> Field is imported as a
- double-float number.
- </member>
- <member><symbol>t</symbol> Field is imported as a
- string.
- </member>
- </simplelist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>result</returnvalue></term>
- <listitem>
- <para>A list representing the result set obtained. For
- each tuple in the result set, there is an element in
- this list, which is itself a list of all the attribute
- values in the tuple.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This will execute the query given by
- <parameter>query-expression</parameter> in the
- <parameter>database</parameter> specified. If the execution
- succeeds it will return the result set returned by the
- database, otherwise an error of type
- <errortype>clsql-sql-error</errortype> will
- be signalled.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(execute-command "create table simple (name char(50), salary numeric(10,2))")
-=> T
-(execute-command "insert into simple values ('Mai, Pierre',10000)")
-=> T
-(execute-command "insert into simple values ('Hacker, Random J.',8000.50)")
-=> T
-(query "select * from simple")
-=> (("Mai, Pierre" "10000.00") ("Hacker, Random J." "8000.50"))
-(query "select salary from simple")
-=> (("10000.00") ("8000.50"))
-(query "select salary from simple where salary > 10000")
-=> NIL
-(query "select salary,name from simple where salary > 10000")
-=> NIL
-(query "select salary,name from simple where salary > 9000")
-=> (("10000.00" "Mai, Pierre"))
-(query "select salary,name from simple where salary > 8000")
-=> (("10000.00" "Mai, Pierre") ("8000.50" "Hacker, Random J."))
-
-;; MySQL-specific:
-(query "show tables")
-=> (("demo") ("log") ("newlog") ("simple") ("spacetrial"))
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Whatever effects the execution of the SQL query has
- on the underlying database, if any.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the execution of the SQL query leads to any
- errors, an error of type
- <errortype>clsql-sql-error</errortype> is signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="execute-command"><function>execute-command</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <!-- Iteration -->
- <refentry id="map-query">
- <refnamediv>
- <refname>MAP-QUERY</refname>
- <refpurpose>Map a function over all the tuples from a
- query</refpurpose>
- <refclass>Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <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>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>output-type-spec</parameter></term>
- <listitem>
- <para>A sequence type specifier or <symbol>nil</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>function</parameter></term>
- <listitem>
- <para>A function designator.
- <parameter>function</parameter> must take as many
- arguments as are attributes in the result set returned
- by executing the SQL
- <parameter>query-expression</parameter>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>query-expression</parameter></term>
- <listitem>
- <para>An <glossterm linkend="gloss-sql-expression">sql
- expression</glossterm> that represents an SQL
- query which is expected to return a (possibly empty)
- result set, where each tuple has as many attributes as
- <parameter>function</parameter> takes arguments.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A
- <glossterm linkend="gloss-database-object">database
- object</glossterm>. This will default to the value
- of <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>types</parameter></term>
- <listitem>
- <para>
- A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
- The default is &nil;. See <link
- linkend="query"><function>query</function></link>
- for the semantics of this argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>result</returnvalue></term>
- <listitem>
- <para>If <parameter>output-type-spec</parameter> is a
- type specifier other than <symbol>nil</symbol>, then a
- sequence of the type it denotes. Otherwise
- <symbol>nil</symbol> is returned.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>Applies <parameter>function</parameter> to the
- attributes of successive tuples in the result set returned
- by executing the SQL
- <parameter>query-expression</parameter>. If the
- <parameter>output-type-spec</parameter> is
- <symbol>nil</symbol>, then the result of each application
- of <parameter>function</parameter> is discarded, and
- <function>map-query</function> returns
- <symbol>nil</symbol>. Otherwise the result of each
- successive application of <parameter>function</parameter> is
- collected in a sequence of type
- <parameter>output-type-spec</parameter>, where the jths
- element is the result of applying
- <parameter>function</parameter> to the attributes of the
- jths tuple in the result set. The collected sequence is the
- result of the call to <function>map-query</function>.
- </para>
- <para>If the <parameter>output-type-spec</parameter> is a
- subtype of <type>list</type>, the result will be a
- <type>list</type>.</para>
- <para>If the <parameter>result-type</parameter> is a subtype
- of <type>vector</type>, then if the implementation can
- determine the element type specified for the
- <parameter>result-type</parameter>, the element type of the
- resulting array is the result of
- <emphasis>upgrading</emphasis> that element type; or, if the
- implementation can determine that the element type is
- unspecified (or <symbol>*</symbol>), the element type of the
- resulting array is <type>t</type>; otherwise, an error is
- signaled.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(map-query 'list #'(lambda (salary name)
- (declare (ignorable name))
- (read-from-string salary))
- "select salary,name from simple where salary > 8000")
-=> (10000.0 8000.5)
-
-(map-query '(vector double-float)
- #'(lambda (salary name)
- (declare (ignorable name))
- (let ((*read-default-float-format* 'double-float))
- (coerce (read-from-string salary) 'double-float))
- "select salary,name from simple where salary > 8000"))
-=> #(10000.0d0 8000.5d0)
-(type-of *)
-=> (SIMPLE-ARRAY DOUBLE-FLOAT (2))
-
-(let (list)
- (values (map-query nil #'(lambda (salary name)
- (push (cons name (read-from-string salary)) list))
- "select salary,name from simple where salary > 8000")
- list))
-=> NIL
-=> (("Hacker, Random J." . 8000.5) ("Mai, Pierre" . 10000.0))
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Whatever effects the execution of the SQL query has
- on the underlying database, if any.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the execution of the SQL query leads to any
- errors, an error of type
- <errortype>clsql-sql-error</errortype> is signalled.</para>
- <para>An error of type <errortype>type-error</errortype> must
- be signaled if the <parameter>output-type-spec</parameter> is
- not a recognizable subtype of <type>list</type>, not a
- recognizable subtype of <type>vector</type>, and not
- <symbol>nil</symbol>.</para>
- <para>An error of type <errortype>type-error</errortype>
- should be signaled if
- <parameter>output-type-spec</parameter> specifies the number
- of elements and the size of the result set is different from
- that number.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="query"><function>query</function></link></member>
- <member><link linkend="do-query"><function>do-query</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="do-query">
- <refnamediv>
- <refname>DO-QUERY</refname>
- <refpurpose>Iterate over all the tuples of a
- query</refpurpose>
- <refclass>Macro</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <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>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>args</parameter></term>
- <listitem>
- <para>A list of variable names.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>query-expression</parameter></term>
- <listitem>
- <para>An <glossterm linkend="gloss-sql-expression">sql
- expression</glossterm> that represents an SQL
- query which is expected to return a (possibly empty)
- result set, where each tuple has as many attributes as
- <parameter>function</parameter> takes arguments.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>A
- <glossterm linkend="gloss-database-object">database
- object</glossterm>. This will default to
- <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>types</parameter></term>
- <listitem>
- <para>
- A <glossterm linkend="gloss-field-types">field type specififier</glossterm>.
- The default is &nil;. See <link
- linkend="query"><function>query</function></link>
- for the semantics of this argument.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>body</parameter></term>
- <listitem>
- <para>A body of Lisp code, like in a
- <function>destructuring-bind</function> form.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>Executes the <parameter>body</parameter> of code
- repeatedly with the variable names in
- <parameter>args</parameter> bound to the attributes of each
- tuple in the result set returned by executing the SQL
- <parameter>query-expression</parameter> on the
- <parameter>database</parameter> specified.</para>
- <para>The body of code is executed in a block named
- <symbol>nil</symbol> which may be returned from prematurely
- via <function>return</function> or
- <function>return-from</function>. In this case the result
- of evaluating the <function>do-query</function> form will be
- the one supplied to <function>return</function> or
- <function>return-from</function>. Otherwise the result will
- be <symbol>nil</symbol>.</para>
- <para>The body of code appears also is if wrapped in a
- <function>destructuring-bind</function> form, thus allowing
- declarations at the start of the body, especially those
- pertaining to the bindings of the variables named in
- <parameter>args</parameter>.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(do-query ((salary name) "select salary,name from simple")
- (format t "~30A gets $~2,5$~%" name (read-from-string salary)))
->> Mai, Pierre gets $10000.00
->> Hacker, Random J. gets $08000.50
-=> NIL
-
-(do-query ((salary name) "select salary,name from simple")
- (return (cons salary name)))
-=> ("10000.00" . "Mai, Pierre")
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Whatever effects the execution of the SQL query has
- on the underlying database, if any.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the execution of the SQL query leads to any
- errors, an error of type
- <errortype>clsql-sql-error</errortype> is signalled.</para>
- <para>If the number of variable names in
- <parameter>args</parameter> and the number of attributes in
- the tuples in the result set don't match up, an error is
- signalled.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="query"><function>query</function></link></member>
- <member><link linkend="map-query"><function>map-query</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- <refentry id="loop-tuples">
- <refnamediv>
- <refname>LOOP-FOR-AS-TUPLES</refname>
- <refpurpose>Iterate over all the tuples of a
- query via a loop clause</refpurpose>
- <refclass>Loop Clause</refclass>
- </refnamediv>
- <refsect1>
- <title>Compatibility</title>
- <caution><para><function>loop-for-as-tuples</function> only works with &cmucl;.</para></caution>
- </refsect1>
- <refsect1>
- <title>Syntax</title>
- <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>
- </refsect1>
- <refsect1>
- <title>Arguments and Values</title>
- <variablelist>
- <varlistentry>
- <term><parameter>var</parameter></term>
- <listitem>
- <para>A <literal>d-var-spec</literal>, as defined in the
- grammar for <function>loop</function>-clauses in the
- ANSI Standard for Common Lisp. This allows for the
- usual loop-style destructuring.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>type-spec</parameter></term>
- <listitem>
- <para>An optional <literal>type-spec</literal> either
- simple or destructured, as defined in the grammar for
- <function>loop</function>-clauses in the ANSI Standard
- for Common Lisp.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>query</parameter></term>
- <listitem>
- <para>An <glossterm linkend="gloss-sql-expression">sql
- expression</glossterm> that represents an SQL
- query which is expected to return a (possibly empty)
- result set, where each tuple has as many attributes as
- <parameter>function</parameter> takes arguments.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>database</parameter></term>
- <listitem>
- <para>An optional
- <glossterm linkend="gloss-database-object">database
- object</glossterm>. This will default to the value
- of <symbol>*default-database*</symbol>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This clause is an iteration driver for
- <function>loop</function>, that binds the given variable
- (possibly destructured) to the consecutive tuples (which are
- represented as lists of attribute values) in the result set
- returned by executing the SQL <parameter>query</parameter>
- expression on the <parameter>database</parameter>
- specified.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <programlisting>
-(defvar *my-db* (connect '("dent" "newesim" "dent" "dent"))
- "My database"
-=> *MY-DB*
-(loop with time-graph = (make-hash-table :test #'equal)
- with event-graph = (make-hash-table :test #'equal)
- for (time event) being the tuples of "select time,event from log"
- from *my-db*
- do
- (incf (gethash time time-graph 0))
- (incf (gethash event event-graph 0))
- finally
- (flet ((show-graph (k v) (format t "~40A => ~5D~%" k v)))
- (format t "~&Time-Graph:~%===========~%")
- (maphash #'show-graph time-graph)
- (format t "~&~%Event-Graph:~%============~%")
- (maphash #'show-graph event-graph))
- (return (values time-graph event-graph)))
->> Time-Graph:
->> ===========
->> D => 53000
->> X => 3
->> test-me => 3000
->>
->> Event-Graph:
->> ============
->> CLOS Benchmark entry. => 9000
->> Demo Text... => 3
->> doit-text => 3000
->> C Benchmark entry. => 12000
->> CLOS Benchmark entry => 32000
-=> #<EQUAL hash table, 3 entries {48350A1D}>
-=> #<EQUAL hash table, 5 entries {48350FCD}>
- </programlisting>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>Whatever effects the execution of the SQL query has
- on the underlying database, if any.</para>
- </refsect1>
- <refsect1>
- <title>Affected by</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>If the execution of the SQL query leads to any
- errors, an error of type
- <errortype>clsql-sql-error</errortype> is signalled.</para>
- <para>Otherwise, any of the exceptional situations of
- <function>loop</function> applies.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link linkend="query"><function>query</function></link></member>
- <member><link linkend="map-query"><function>map-query</function></link></member>
- <member><link linkend="do-query"><function>do-query</function></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- </reference>