+##############################################################################
# FILE IDENTIFICATION
#
# Name: Makefile
#
# CVS Id: $Id$
#
-# This file, part of CLSQL, is Copyright (c) 2002 by Kevin M. Rosenberg
+# This file, part of CLSQL, is Copyright (c) 2002-2003 by Kevin M. Rosenberg
#
# CLSQL users are granted the rights to distribute and use this software
# as governed by the terms of the Lisp Lesser GNU Public License
# (http://opensource.franz.com/preamble.html), also known as the LLGPL.
+##############################################################################
-# System variable to select catalog file
-SYSTEM=debian
-# SYSTEM=redhat
-
-# Nothing to configure beyond this point
-
-CATALOG=catalog.$(SYSTEM)
-
-# Custom DSSSL's
-DSSSL_HTML=../dsssl/html/docbook.dsl
-DSSSL_PRINT=dsssl/print/docbook.dsl
-
-DOCFILE_BASE_DEFAULT=clsql
-DOCFILE_EXT_DEFAULT=sgml
+OS:=debian
+DOCFILE_BASE_DEFAULT:=clsql
+DOCFILE_EXT_DEFAULT:=xml
# Standard docfile processing
DOCFILE_EXT=${DOCFILE_EXT_DEFAULT}
endif
-DOCFILE=${DOCFILE_BASE}.${DOCFILE_EXT}
-TEXFILE=${DOCFILE_BASE}.tex
-PDFFILE=${DOCFILE_BASE}.pdf
-PSFILE=${DOCFILE_BASE}.ps
-DVIFILE=${DOCFILE_BASE}.dvi
-TMPFILES=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log
-DOCFILES=$(shell echo *.sgml)
+DOCFILE:=${DOCFILE_BASE}.${DOCFILE_EXT}
+FOFILE:=${DOCFILE_BASE}.fo
+PDFFILE:=${DOCFILE_BASE}.pdf
+PSFILE:=${DOCFILE_BASE}.ps
+DVIFILE:=${DOCFILE_BASE}.dvi
+TXTFILE:=${DOCFILE_BASE}.txt
+TMPFILES:=${DOCFILE_BASE}.aux ${DOCFILE_BASE}.out ${DOCFILE_BASE}.log
+DOCFILES:=$(shell echo *.xml *.xsl)
+
+CATALOG:=`pwd`/catalog-${OS}.xml
+CHECK:=XML_CATALOG_FILES="$(CATALOG)" xmllint --noout --xinclude --postvalid $(DOCFILE) || exit 1
.PHONY: all
all: html pdf
.PHONY: doc
doc: html pdf
-CHECK=nsgmls -s -C ${CATALOG} || exit 1
-
.PHONY: check
check:
@$(CHECK)
.PHONY: html
html: html.tar.gz
-html.tar.gz: $(DOCFILES) Makefile
- @$(CHECK)
- @( rm -rf html ; mkdir html; cd html ; jade -t sgml -c ../${CATALOG} -d ${DSSSL_HTML} ../${DOCFILE} > /dev/null; cp book1.html index.html; cd ..; GZIP='-9' tar czf html.tar.gz html)
+html.tar.gz: $(DOCFILES) Makefile
+ @rm -rf html
+ @mkdir html
+ @XML_CATALOG_FILES="$(CATALOG)" xsltproc --xinclude --output html/ html.xsl $(DOCFILE)
+ @GZIP='-9' tar czf html.tar.gz html
-.PHONY: tex
-tex: ${TEXFILE}
+.PHONY: fo
+fo: ${FOFILE}
-${TEXFILE}: ${DOCFILES}
- @$(CHECK)
- @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null
+${FOFILE}: $(DOCFILES) Makefile
+ @XML_CATALOG_FILES="$(CATALOG)" xsltproc --xinclude --output $(FOFILE) fo.xsl $(DOCFILE)
.PHONY: pdf
pdf: ${PDFFILE}
-${PDFFILE}: ${DOCFILES}
- @jade -t tex -c ${CATALOG} -d ${DSSSL_PRINT} ${DOCFILE} > /dev/null
- @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null
- @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null
- @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null
- @pdfjadetex -interaction=batchmode '\pdfcompresslevel=9' '\input ${TEXFILE}' > /dev/null
+${PDFFILE}: ${FOFILE}
+ @fop $(FOFILE) -pdf $(PDFFILE) > /dev/null
.PHONY: dvi
dvi: ${DVIFILE}
-${DVIFILE}: ${TEXFILE}
- @jadetex ${TEXFILE} > /dev/null
- @jadetex ${TEXFILE} > /dev/null
- @jadetex ${TEXFILE} > /dev/null
- @jadetex ${TEXFILE} > /dev/null
-
.PHONY: ps
ps: ${PSFILE}
-${PSFILE}: ${DVIFILE}
- @dvips -o ${PSFILE} ${DVIFILE} > /dev/null
+${PSFILE}: ${FOFILE}
+ @fop $(FOFILE) -ps $(PSFILE) > /dev/null
+
+
+.PHONY: txt
+txt: ${TXTFILE}
+
+${TXTFILE}: ${FOFILE}
+ @fop $(FOFILE) -txt $(TXTFILE) > /dev/null
.PHONY: clean
clean:
- @rm -f *~ *.bak *.orig \#*\# .\#* *.log
+ @rm -f *~ *.bak *.orig \#*\# .\#* texput.log
@rm -rf html ${PSFILE}
- @rm -f ${TMPFILES}
- @rm -f ${DVIFILE} ${TEXFILE}
+ @rm -f ${TMPFILES} ${FOFILE}
+ @rm -f ${DVIFILE} ${TXTFILE}
.PHONY: distclean
distclean: clean
+++ /dev/null
-<!-- -*- DocBook -*- -->
-
- <appendix>
- <title>Database Back-ends</title>
-
- <sect1>
- <title>MySQL</title>
- <sect2>
- <title>Libraries</title>
- <para>The MySQL back-end needs access to the MySQL C
- client library (<filename>libmysqlclient.so</filename>).
- The location of this library is specified via
- <symbol>*mysql-so-load-path*</symbol>, which defaults
- to <filename>/usr/lib/libmysqlclient.so</filename>.
- Additional flags to <application>ld</application> needed for
- linking are specified via
- <symbol>*mysql-so-libraries*</symbol>,
- which defaults to <symbol>("-lc")</symbol>.</para>
- </sect2>
- <sect2>
- <title>Initialization</title>
- <para>Use
- <programlisting>(mk:load-system :clsql-mysql)</programlisting>
- to load the MySQL back-end. The database type for the MySQL
- back-end is <symbol>:mysql</symbol>.</para>
- </sect2>
- <sect2>
- <title>Connection Specification</title>
- <sect3>
- <title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
- </sect3>
- <sect3>
- <title>Description of connection-spec</title>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem>
- <para>String representing the hostname or IP address
- the MySQL server resides on, or <symbol>nil</symbol>
- to indicate the localhost.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>db</parameter></term>
- <listitem>
- <para>String representing the name of the database on
- the server to connect to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>user</parameter></term>
- <listitem>
- <para>String representing the user name to use for
- authentication, or <symbol>nil</symbol> to use the
- current Unix user ID.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>password</parameter></term>
- <listitem>
- <para>String representing the unencrypted password to
- use for authentication, or <symbol>nil</symbol> if
- the authentication record has an empty password
- field.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>AODBC</title>
- <sect2>
- <title>Libraries</title>
- <para>The AODBC back-end requires access to the ODBC interface
- of &acl;.</para>
- </sect2>
- <sect2>
- <title>Initialization</title>
- <para>Use
- <programlisting>(mk:load-system :clsql-aodbc)</programlisting>
- to load the MySQL back-end. The database type for the AODBC
- back-end is <symbol>:aodbc</symbol>.</para>
- </sect2>
- <sect2>
- <title>Connection Specification</title>
- <sect3>
- <title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
- </sect3>
- <sect3>
- <title>Description of connection-spec</title>
- <variablelist>
- <varlistentry>
- <term><parameter>dsn</parameter></term>
- <listitem>
- <para>String representing the ODBC data source name.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>user</parameter></term>
- <listitem>
- <para>String representing the user name to use for
- authentication.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>password</parameter></term>
- <listitem>
- <para>String representing the unencrypted password to
- use for authentication.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>PostgreSQL</title>
- <sect2>
- <title>Libraries</title>
- <para>The PostgreSQL back-end needs access to the PostgreSQL C
- client library (<filename>libpq.so</filename>). The
- location of this library is specified via
- <symbol>*postgresql-so-load-path*</symbol>, which defaults
- to <filename>/usr/lib/libpq.so</filename>. Additional flags
- to <application>ld</application> needed for linking are
- specified via <symbol>*postgresql-so-libraries*</symbol>,
- which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
- </sect2>
- <sect2>
- <title>Initialization</title>
- <para>Use
- <programlisting>(mk:load-system :clsql-postgresql)</programlisting>
- to load the PostgreSQL back-end. The database type for the
- PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
- </sect2>
- <sect2>
- <title>Connection Specification</title>
- <sect3>
- <title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
- </sect3>
- <sect3>
- <title>Description of connection-spec</title>
- <para>For every parameter in the connection-spec,
- <symbol>nil</symbol> indicates that the PostgreSQL default
- environment variables (see PostgreSQL documentation) will
- be used, or if those are unset, the compiled-in defaults
- of the C client library are used.</para>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem>
- <para>String representing the hostname or IP address
- the PostgreSQL server resides on. Use the empty
- string to indicate a connection to localhost via
- Unix-Domain sockets instead of TCP/IP.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>db</parameter></term>
- <listitem>
- <para>String representing the name of the database on
- the server to connect to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>user</parameter></term>
- <listitem>
- <para>String representing the user name to use for
- authentication.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>password</parameter></term>
- <listitem>
- <para>String representing the unencrypted password to
- use for authentication.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>port</parameter></term>
- <listitem>
- <para>String representing the port to use for
- communication with the PostgreSQL server.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>options</parameter></term>
- <listitem>
- <para>String representing further runtime options for
- the PostgreSQL server.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>tty</parameter></term>
- <listitem>
- <para>String representing the tty or file to use for
- debugging messages from the PostgreSQL server.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>PostgreSQL Socket</title>
- <sect2>
- <title>Libraries</title>
- <para>The PostgreSQL Socket back-end needs
- <emphasis>no</emphasis> access to the PostgreSQL C
- client library, since it communicates directly with the
- PostgreSQL server using the published frontend/backend
- protocol, version 2.0. This eases installation and makes it
- possible to dump CMU CL images containing CLSQL and this
- backend, contrary to backends which require FFI code.</para>
- </sect2>
- <sect2>
- <title>Initialization</title>
- <para>Use
- <programlisting>(mk:load-system :clsql-postgresql-socket)</programlisting>
- to load the PostgreSQL Socket back-end. The database type for the
- PostgreSQL Socket back-end is
- <symbol>:postgresql-socket</symbol>.</para>
- </sect2>
- <sect2>
- <title>Connection Specification</title>
- <sect3>
- <title>Syntax of connection-spec</title>
- <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
- </sect3>
- <sect3>
- <title>Description of connection-spec</title>
- <variablelist>
- <varlistentry>
- <term><parameter>host</parameter></term>
- <listitem>
- <para>If this is a string, it represents the hostname or
- IP address the PostgreSQL server resides on. In
- this case communication with the server proceeds via
- a TCP connection to the given host and port.</para>
- <para>
- If this is a pathname, then it is assumed to name the
- directory that contains the server's Unix-Domain
- sockets. The full name to the socket is then
- constructed from this and the port number passed,
- and communication will proceed via a connection to
- this unix-domain socket.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>db</parameter></term>
- <listitem>
- <para>String representing the name of the database on
- the server to connect to.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>user</parameter></term>
- <listitem>
- <para>String representing the user name to use for
- authentication.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>password</parameter></term>
- <listitem>
- <para>String representing the unencrypted password to
- use for authentication. This can be the empty
- string if no password is required for
- authentication.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>port</parameter></term>
- <listitem>
- <para>Integer representing the port to use for
- communication with the PostgreSQL server. This
- defaults to 5432.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>options</parameter></term>
- <listitem>
- <para>String representing further runtime options for
- the PostgreSQL server.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><parameter>tty</parameter></term>
- <listitem>
- <para>String representing the tty or file to use for
- debugging messages from the PostgreSQL server.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect3>
- </sect2>
- </sect1>
- </appendix>
--- /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;
+]>
+
+<appendix id="appendix">
+ <title>Database Back-ends</title>
+
+ <sect1 id="mysql">
+ <title>MySQL</title>
+ <sect2>
+ <title>Libraries</title>
+ <para>The MySQL back-end needs access to the MySQL C
+ client library (<filename>libmysqlclient.so</filename>).
+ The location of this library is specified
+ via <symbol>*mysql-so-load-path*</symbol>, which defaults
+ to <filename>/usr/lib/libmysqlclient.so</filename>.
+ Additional flags to <application>ld</application> needed for
+ linking are specified via <symbol>*mysql-so-libraries*</symbol>,
+ which defaults to <symbol>("-lc")</symbol>.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Initialization</title>
+ <para>Use
+ <programlisting>(mk:load-system :clsql-mysql)</programlisting>
+ to load the MySQL back-end. The database type for the MySQL
+ back-end is <symbol>:mysql</symbol>.</para>
+ </sect2>
+ <sect2>
+ <title>Connection Specification</title>
+ <sect3>
+ <title>Syntax of connection-spec</title>
+ <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+ </sect3>
+ <sect3>
+ <title>Description of connection-spec</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem>
+ <para>String representing the hostname or IP address
+ the MySQL server resides on, or <symbol>nil</symbol>
+ to indicate the localhost.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>db</parameter></term>
+ <listitem>
+ <para>String representing the name of the database on
+ the server to connect to.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user</parameter></term>
+ <listitem>
+ <para>String representing the user name to use for
+ authentication, or <symbol>nil</symbol> to use the
+ current Unix user ID.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>String representing the unencrypted password to
+ use for authentication, or <symbol>nil</symbol> if
+ the authentication record has an empty password
+ field.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="postgresql">
+ <title>PostgreSQL</title>
+ <sect2>
+ <title>Libraries</title>
+ <para>The PostgreSQL back-end needs access to the PostgreSQL C
+ client library (<filename>libpq.so</filename>). The
+ location of this library is specified via
+ <symbol>*postgresql-so-load-path*</symbol>, which defaults
+ to <filename>/usr/lib/libpq.so</filename>. Additional flags
+ to <application>ld</application> needed for linking are
+ specified via <symbol>*postgresql-so-libraries*</symbol>,
+ which defaults to <symbol>("-lcrypt" "-lc")</symbol>.</para>
+ </sect2>
+ <sect2>
+ <title>Initialization</title>
+ <para>Use
+ <programlisting>(mk:load-system :clsql-postgresql)</programlisting>
+ to load the PostgreSQL back-end. The database type for the
+ PostgreSQL back-end is <symbol>:postgresql</symbol>.</para>
+ </sect2>
+ <sect2>
+ <title>Connection Specification</title>
+ <sect3>
+ <title>Syntax of connection-spec</title>
+ <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
+ </sect3>
+ <sect3>
+ <title>Description of connection-spec</title>
+ <para>For every parameter in the connection-spec,
+ <symbol>nil</symbol> indicates that the PostgreSQL default
+ environment variables (see PostgreSQL documentation) will
+ be used, or if those are unset, the compiled-in defaults
+ of the C client library are used.</para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem>
+ <para>String representing the hostname or IP address
+ the PostgreSQL server resides on. Use the empty
+ string to indicate a connection to localhost via
+ Unix-Domain sockets instead of TCP/IP.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>db</parameter></term>
+ <listitem>
+ <para>String representing the name of the database on
+ the server to connect to.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user</parameter></term>
+ <listitem>
+ <para>String representing the user name to use for
+ authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>String representing the unencrypted password to
+ use for authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>port</parameter></term>
+ <listitem>
+ <para>String representing the port to use for
+ communication with the PostgreSQL server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>options</parameter></term>
+ <listitem>
+ <para>String representing further runtime options for
+ the PostgreSQL server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>tty</parameter></term>
+ <listitem>
+ <para>String representing the tty or file to use for
+ debugging messages from the PostgreSQL server.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="postgresql-socket">
+ <title>PostgreSQL Socket</title>
+ <sect2>
+ <title>Libraries</title>
+ <para>The PostgreSQL Socket back-end needs
+ <emphasis>no</emphasis> access to the PostgreSQL C
+ client library, since it communicates directly with the
+ PostgreSQL server using the published frontend/backend
+ protocol, version 2.0. This eases installation and makes it
+ possible to dump CMU CL images containing CLSQL and this
+ backend, contrary to backends which require FFI code.</para>
+ </sect2>
+ <sect2>
+ <title>Initialization</title>
+ <para>Use
+ <programlisting>(mk:load-system :clsql-postgresql-socket)</programlisting>
+ to load the PostgreSQL Socket back-end. The database type for the
+ PostgreSQL Socket back-end is
+ <symbol>:postgresql-socket</symbol>.</para>
+ </sect2>
+ <sect2>
+ <title>Connection Specification</title>
+ <sect3>
+ <title>Syntax of connection-spec</title>
+ <synopsis>(<replaceable>host</replaceable> <replaceable>db</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable> &optional <replaceable>port</replaceable> <replaceable>options</replaceable> <replaceable>tty</replaceable>)</synopsis>
+ </sect3>
+ <sect3>
+ <title>Description of connection-spec</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>host</parameter></term>
+ <listitem>
+ <para>If this is a string, it represents the hostname or
+ IP address the PostgreSQL server resides on. In
+ this case communication with the server proceeds via
+ a TCP connection to the given host and port.</para>
+ <para>
+ If this is a pathname, then it is assumed to name the
+ directory that contains the server's Unix-Domain
+ sockets. The full name to the socket is then
+ constructed from this and the port number passed,
+ and communication will proceed via a connection to
+ this unix-domain socket.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>db</parameter></term>
+ <listitem>
+ <para>String representing the name of the database on
+ the server to connect to.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user</parameter></term>
+ <listitem>
+ <para>String representing the user name to use for
+ authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>String representing the unencrypted password to
+ use for authentication. This can be the empty
+ string if no password is required for
+ authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>port</parameter></term>
+ <listitem>
+ <para>Integer representing the port to use for
+ communication with the PostgreSQL server. This
+ defaults to 5432.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>options</parameter></term>
+ <listitem>
+ <para>String representing further runtime options for
+ the PostgreSQL server.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>tty</parameter></term>
+ <listitem>
+ <para>String representing the tty or file to use for
+ debugging messages from the PostgreSQL server.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="aodbc">
+ <title>AODBC</title>
+ <sect2>
+ <title>Libraries</title>
+ <para>The AODBC back-end requires access to the ODBC interface
+ of &acl;.</para>
+ </sect2>
+ <sect2>
+ <title>Initialization</title>
+ <para>Use
+ <programlisting>(mk:load-system :clsql-aodbc)</programlisting>
+ to load the MySQL back-end. The database type for the AODBC
+ back-end is <symbol>:aodbc</symbol>.</para>
+ </sect2>
+ <sect2>
+ <title>Connection Specification</title>
+ <sect3>
+ <title>Syntax of connection-spec</title>
+ <synopsis>(<replaceable>dsn</replaceable> <replaceable>user</replaceable> <replaceable>password</replaceable>)</synopsis>
+ </sect3>
+ <sect3>
+ <title>Description of connection-spec</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>dsn</parameter></term>
+ <listitem>
+ <para>String representing the ODBC data source name.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user</parameter></term>
+ <listitem>
+ <para>String representing the user name to use for
+ authentication.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>password</parameter></term>
+ <listitem>
+ <para>String representing the unencrypted password to
+ use for authentication.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ </appendix>
+++ /dev/null
-<!-- -*- DocBook -*- -->
-
-<bookinfo>
- <title>&clsql; Users' Guide</title>
- <authorgroup>
- <author>
- <firstname>Kevin</firstname>
- <othername>M.</othername>
- <surname>Rosenberg</surname>
- <affiliation><jobtitle>Maintainer of CLSQL</jobtitle></affiliation>
- </author>
- <author>
- <firstname>Pierre</firstname>
- <othername>R.</othername>
- <surname>Mai</surname>
- <affiliation><jobtitle>Author of Original MaiSQL Code</jobtitle></affiliation>
- </author>
- </authorgroup>
- <printhistory>
- <simpara>$Date$</simpara>
- <simpara>$Id$</simpara>
- </printhistory>
- <legalnotice>
- <itemizedlist>
- <listitem>
- <para>&clsql; is Copyright © 2002-2003 by Kevin M. Rosenberg and
- Copyright © 1999-2001 by Pierre R. Mai.</para>
- </listitem>
- <listitem>
- <para><application>Allegro CL</application>® is a registered
- trademark of Franz Inc.</para>
- </listitem>
- <listitem>
- <para><application>Common SQL</application>,
- <application>LispWorks</application> and
- <application>Xanalys</application> are trademarks or
- registered trademarks of Xanalys Inc.</para>
- </listitem>
- <listitem>
- <para><application>Microsoft
- Windows</application>® is a registered trademark of
- Microsoft Inc.</para>
- </listitem>
- <listitem>
- <para>Other brand or
- product names are the registered trademarks or trademarks of
- their respective holders.</para>
- </listitem>
- </itemizedlist>
- </legalnotice>
-</bookinfo>
--- /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;
+]>
+
+<bookinfo>
+ <title>&clsql; Users' Guide</title>
+ <authorgroup>
+ <author>
+ <firstname>Kevin</firstname>
+ <othername>M.</othername>
+ <surname>Rosenberg</surname>
+ <affiliation><jobtitle>Maintainer of CLSQL</jobtitle></affiliation>
+ </author>
+ <author>
+ <firstname>Pierre</firstname>
+ <othername>R.</othername>
+ <surname>Mai</surname>
+ <affiliation><jobtitle>Author of Original MaiSQL Code</jobtitle></affiliation>
+ </author>
+ </authorgroup>
+ <printhistory>
+ <simpara>$Date$</simpara>
+ <simpara>$Id$</simpara>
+ </printhistory>
+ <legalnotice>
+ <itemizedlist>
+ <listitem>
+ <para>&clsql; is Copyright © 2002-2003 by Kevin M. Rosenberg and
+ Copyright © 1999-2001 by Pierre R. Mai.</para>
+ </listitem>
+ <listitem>
+ <para><application>Allegro CL</application>® is a registered
+ trademark of Franz Inc.</para>
+ </listitem>
+ <listitem>
+ <para><application>Common SQL</application>,
+ <application>LispWorks</application> and
+ <application>Xanalys</application> are trademarks or
+ registered trademarks of Xanalys Inc.</para>
+ </listitem>
+ <listitem>
+ <para><application>Microsoft
+ Windows</application>® is a registered trademark of
+ Microsoft Inc.</para>
+ </listitem>
+ <listitem>
+ <para>Other brand or
+ product names are the registered trademarks or trademarks of
+ their respective holders.</para>
+ </listitem>
+ </itemizedlist>
+ </legalnotice>
+</bookinfo>
--- /dev/null
+<?xml version="1.0" ?>
+<!DOCTYPE catalog
+ PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
+ "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+
+ <!-- The directory DTD and stylesheet files are installed under -->
+ <group xml:base="file:///usr/share/sgml/docbook/" >
+
+ <!-- Resolve DTD URL system ID to local file -->
+ <rewriteSystem
+ systemIdStartString="http://www.oasis-open.org/docbook/xml/4.2/"
+ rewritePrefix="dtd/xml/4.2/" />
+ <!-- Resolve stylesheet URL to local file -->
+ <rewriteURI
+ uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
+ rewritePrefix="stylesheet/xsl/nwalsh/" />
+
+ <!-- Resolve DTD PUBLIC identifiers -->
+ <nextCatalog catalog="dtd/xml/4.2/catalog.xml" />
+
+ <!-- To resolve simple DTD SYSTEM identifiers. -->
+ <!-- Note: this does not work with Java resolver -->
+ <!-- classes in Saxon or Xalan -->
+ <system
+ systemId="docbook.dtd"
+ uri="dtd/xml/4.2/xml/docbookx.dtd" />
+
+ <!-- To resolve short stylesheet references -->
+ <uri
+ name="docbook.xsl"
+ uri="stylesheet/xsl/nwalsh/html/docbook.xsl" />
+ <uri
+ name="chunk.xsl"
+ uri="stylesheet/xsl/nwalsh/html/chunk.xsl" />
+ <uri
+ name="fo-docbook.xsl"
+ uri="stylesheet/xsl/nwalsh/fo/docbook.xsl" />
+
+ </group>
+
+</catalog>
+++ /dev/null
-CATALOG /etc/sgml/docbook.cat
-CATALOG /etc/sgml/docbook-dsssl.cat
-DOCUMENT clsql.sgml
+++ /dev/null
-CATALOG sgml-docbook-4.1.cat
-DOCUMENT clsql.sgml
+++ /dev/null
-<!-- -*- DocBook -*- -->
-
-<!DOCTYPE BOOK PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
-<!ENTITY defsystem "<application>Defsystem</application>">
-<!ENTITY asdf "<application>ASDF</application>">
-<!ENTITY clocc "<application><emphasis>CLOCC</emphasis></application>">
-<!ENTITY cclan "<application><emphasis>CCLAN</emphasis></application>">
-<!ENTITY uffi "<application><emphasis>UFFI</emphasis></application>">
-<!ENTITY ffi "<emphasis>FFI</emphasis>">
-<!ENTITY clsql "<application><emphasis>CLSQL</emphasis></application>">
-<!ENTITY maisql "<application><emphasis>MaiSQL</emphasis></application>">
-<!ENTITY sql "<application>SQL</application>">
-<!ENTITY mysql "<application>MySQL</application>">
-<!ENTITY postgresql "<application>PostgreSQL</application>">
-<!ENTITY aodbc "<application>AODBC</application>">
-<!ENTITY cmucl "<application>CMUCL</application>">
-<!ENTITY scl "<application>SCL</application>">
-<!ENTITY md5 "<application>MD5</application>">
-<!ENTITY sbcl "<application>SBCL</application>">
-<!ENTITY openmcl "<application>OpenMCL</application>">
-<!ENTITY lw "<application>Lispworks</application>">
-<!ENTITY acl "<application>AllegroCL</application>">
-<!ENTITY cl "<application>ANSI Common Lisp</application>">
-<!ENTITY t "<symbol>T</symbol>">
-<!ENTITY nil "<symbol>NIL</symbol>">
-<!ENTITY null "<constant>NULL</constant>">
-<!ENTITY c "<symbol>C</symbol>">
-<!ENTITY defsystem "<application>defsystem</application>">
-<!ENTITY bookinfo SYSTEM "bookinfo.sgml">
-<!ENTITY preface SYSTEM "preface.sgml">
-<!ENTITY intro SYSTEM "intro.sgml">
-<!ENTITY ref SYSTEM "ref.sgml">
-<!ENTITY appendix SYSTEM "appendix.sgml">
-<!ENTITY glossary SYSTEM "glossary.sgml">
-]>
-
-<book>
-&bookinfo;
-&preface;
-&intro;
-&ref;
-&appendix;
-&glossary;
-</book>
--- /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;
+]>
+
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="bookinfo.xml" />
+ <xi:include href="preface.xml" />
+ <xi:include href="intro.xml" />
+ <xi:include href="ref_clsql.xml" />
+ <xi:include href="ref_clsql_sys.xml" />
+ <xi:include href="appendix.xml" />
+ <xi:include href="glossary.xml" />
+</book>
+
+
+++ /dev/null
-These stylesheets are written and Copyright (c) 1999-2002 by Pierre
-R. Mai.
-
-He has graciously placed them in the public domain without
-restrictions.
+++ /dev/null
-<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
-<!ENTITY docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL>
-]>
-
- <style-sheet>
- <style-specification use="docbook">
- <style-specification-body>
-(element envar ($mono-seq$))
-(element symbol ($mono-seq$))
-(element type ($mono-seq$))
-(element errortype ($mono-seq$))
-(element returnvalue ($italic-mono-seq$))
-(define (book-titlepage-recto-elements)
- (list (normalize "title")
- (normalize "subtitle")
- (normalize "graphic")
- (normalize "corpauthor")
- (normalize "authorgroup")
- (normalize "author")
- (normalize "editor")
- (normalize "printhistory")
- (normalize "copyright")
- (normalize "abstract")
- (normalize "legalnotice")))
-(define %use-id-as-filename% #t)
-(define use-output-dir #t)
-</style-specification-body>
-</style-specification>
-<external-specification id="docbook" document="docbook">
-</style-sheet>
+++ /dev/null
-<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
-<!ENTITY docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL>
-]>
-
-<style-sheet>
-<style-specification use="docbook">
-<style-specification-body>
-(element envar ($mono-seq$))
-(element symbol ($mono-seq$))
-(element type ($mono-seq$))
-(element errortype ($mono-seq$))
-(element returnvalue ($italic-mono-seq$))
-(define (book-titlepage-verso-elements)
- (list (normalize "title")
- (normalize "subtitle")
- (normalize "corpauthor")
- (normalize "authorgroup")
- (normalize "author")
- (normalize "editor")
- (normalize "edition")
- (normalize "pubdate")
- (normalize "printhistory")
- (normalize "copyright")
- (normalize "abstract")
- (normalize "legalnotice")
- (normalize "revhistory")))
-</style-specification-body>
-</style-specification>
-<external-specification id="docbook" document="docbook">
-</style-sheet>
--- /dev/null
+<?xml version="1.0" encoding="iso-8859-1" ?>
+
+<!ENTITY defsystem "<application>Defsystem</application>">
+<!ENTITY asdf "<application>ASDF</application>">
+<!ENTITY clocc "<application><emphasis>CLOCC</emphasis></application>">
+<!ENTITY cclan "<application><emphasis>CCLAN</emphasis></application>">
+<!ENTITY uffi "<application><emphasis>UFFI</emphasis></application>">
+<!ENTITY ffi "<emphasis>FFI</emphasis>">
+<!ENTITY clsql "<application><emphasis>CLSQL</emphasis></application>">
+<!ENTITY maisql "<application><emphasis>MaiSQL</emphasis></application>">
+<!ENTITY sql "<application>SQL</application>">
+<!ENTITY mysql "<application>MySQL</application>">
+<!ENTITY postgresql "<application>PostgreSQL</application>">
+<!ENTITY aodbc "<application>AODBC</application>">
+<!ENTITY cmucl "<application>CMUCL</application>">
+<!ENTITY scl "<application>SCL</application>">
+<!ENTITY md5 "<application>MD5</application>">
+<!ENTITY sbcl "<application>SBCL</application>">
+<!ENTITY openmcl "<application>OpenMCL</application>">
+<!ENTITY lw "<application>Lispworks</application>">
+<!ENTITY acl "<application>AllegroCL</application>">
+<!ENTITY cl "<application>ANSI Common Lisp</application>">
+<!ENTITY t "<symbol>T</symbol>">
+<!ENTITY nil "<symbol>NIL</symbol>">
+<!ENTITY null "<constant>NULL</constant>">
+<!ENTITY c "<symbol>C</symbol>">
+<!ENTITY defsystem "<application>defsystem</application>">
+
+
+
--- /dev/null
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:import href="fo-docbook.xsl"/>
+
+</xsl:stylesheet>
+
+++ /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;
-]>
-
-<glossary>
- <note>
- <para>This glossary is still very thinly populated, and not all
- references in the main text have been properly linked and
- coordinated with this glossary. This will hopefully change in
- future revisions.
- </para>
- </note>
- <glossentry>
- <glossterm>Active database</glossterm>
- <glosssee otherterm="gloss-database-object">
- </glossentry>
- <glossentry>
- <glossterm>Connection</glossterm>
- <glosssee otherterm="gloss-database-object">
- </glossentry>
- <glossentry>
- <glossterm>Closed Database</glossterm>
- <glossdef>
- <para>
- An object of type <type>closed-database</type>. This is
- in contrast to the terms connection, database, active
- database or <glossterm
- linkend="gloss-database-object">database object</glossterm>
- which don't include objects which are closed database.
- </para>
- </glossdef>
- </glossentry>
- <glossentry>
- <glossterm>database</glossterm>
- <glosssee otherterm="gloss-database-object">
- </glossentry>
- <glossentry id="gloss-ffi">
- <glossterm>Foreign Function Interface
- (<acronym>FFI</acronym>)
- </glossterm>
- <glossdef>
- <para>
- An interface from Common Lisp to a external library which
- contains compiled functions written in other programming
- languages, typically C.
- </para>
- </glossdef>
- </glossentry>
- <glossentry id="gloss-database-object">
- <glossterm>Database Object</glossterm>
- <glossdef>
- <para>An object of type <type>database</type>.</para>
- </glossdef>
- </glossentry>
- <glossentry id="gloss-field-types">
- <glossterm>Field Types Specifier</glossterm>
- <glossdef>
- <para>A value that specifies the type of each field in a query.</para>
- </glossdef>
- </glossentry>
- <glossentry id="gloss-sql">
- <glossterm>Structured Query Language
- (<acronym>SQL</acronym>)
- </glossterm>
- <glossdef>
- <para>
- An ANSI standard language for storing and retrieving data
- in a relational database.
- </para>
- </glossdef>
- </glossentry>
- <glossentry id="gloss-sql-expression">
- <glossterm>SQL Expression</glossterm>
- <glossdef>
- <para>Either a string containing a valid SQL statement, or
- an object of type <type>sql-expression</type><note>
- <para>This has not been implemented yet, so only strings
- are valid SQL expressions for the moment.</para>
- </note>
- </para>
- </glossdef>
- </glossentry>
-</glossary>
-
--- /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;
+]>
+
+<glossary id="glossary">
+ <note>
+ <para>This glossary is still very thinly populated, and not all
+ references in the main text have been properly linked and
+ coordinated with this glossary. This will hopefully change in
+ future revisions.
+ </para>
+ </note>
+ <glossentry>
+ <glossterm>Active database</glossterm>
+ <glosssee otherterm="gloss-database-object" />
+ </glossentry>
+ <glossentry>
+ <glossterm>Connection</glossterm>
+ <glosssee otherterm="gloss-database-object" />
+ </glossentry>
+ <glossentry>
+ <glossterm>Closed Database</glossterm>
+ <glossdef>
+ <para>
+ An object of type <type>closed-database</type>. This is
+ in contrast to the terms connection, database, active
+ database or <glossterm
+ linkend="gloss-database-object">database object</glossterm>
+ which don't include objects which are closed database.
+ </para>
+ </glossdef>
+ </glossentry>
+ <glossentry>
+ <glossterm>database</glossterm>
+ <glosssee otherterm="gloss-database-object" />
+ </glossentry>
+ <glossentry id="gloss-ffi">
+ <glossterm>Foreign Function Interface
+ (<acronym>FFI</acronym>)
+ </glossterm>
+ <glossdef>
+ <para>
+ An interface from Common Lisp to a external library which
+ contains compiled functions written in other programming
+ languages, typically C.
+ </para>
+ </glossdef>
+ </glossentry>
+ <glossentry id="gloss-database-object">
+ <glossterm>Database Object</glossterm>
+ <glossdef>
+ <para>An object of type <type>database</type>.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry id="gloss-field-types">
+ <glossterm>Field Types Specifier</glossterm>
+ <glossdef>
+ <para>A value that specifies the type of each field in a query.</para>
+ </glossdef>
+ </glossentry>
+ <glossentry id="gloss-sql">
+ <glossterm>Structured Query Language
+ (<acronym>SQL</acronym>)
+ </glossterm>
+ <glossdef>
+ <para>
+ An ANSI standard language for storing and retrieving data
+ in a relational database.
+ </para>
+ </glossdef>
+ </glossentry>
+ <glossentry id="gloss-sql-expression">
+ <glossterm>SQL Expression</glossterm>
+ <glossdef>
+ <para>Either a string containing a valid SQL statement, or
+ an object of type <type>sql-expression</type>.
+ <note>
+ <para>This has not been implemented yet, so only strings
+ are valid SQL expressions for the moment.
+ </para>
+ </note>
+ </para>
+ </glossdef>
+ </glossentry>
+</glossary>
+
--- /dev/null
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version="1.0">
+
+<xsl:import href="chunk.xsl"/>
+<xsl:param name="use.id.as.filename" select="1"/>
+
+</xsl:stylesheet>
+
+++ /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;
-]>
-
-<chapter id="introduction">
- <title>Introduction</title>
-
- <sect1>
- <title>Purpose</title>
- <para>&clsql; is a Common Lisp interface to <glossterm
-linkend="gloss-sql">SQL</glossterm> databases. A number of Common
-Lisp implementations and SQL databases are supported.The general
-structure of &clsql; is based on the
-<application>CommonSQL</application> package by Xanalys.</para>
- </sect1>
-
- <sect1>
- <title>History</title>
- <para>
- &clsql; is written by Kevin M. Rosenberg and based substantially
-on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
-are:
-<itemizedlist>
-<listitem>
-<para>port from the &cmucl; FFI to &uffi;.</para>
-</listitem>
-<listitem>
-<para>new &acl; ODBC interface back-end.</para>
-</listitem>
-<listitem>
-<para>compatibility layer for &cmucl; specific code.</para>
-</listitem>
-<listitem>
-<para>much improved robustness for the &mysql; back-end.</para>
-</listitem>
-<listitem>
-<para>improved system loading.</para>
-</listitem>
-<listitem>
-<para>improved packages and symbol export.</para>
-</listitem>
-<listitem>
-<para>transaction support.</para>
-</listitem>
-</itemizedlist>
- </para>
- </sect1>
-
- <sect1>
- <title>Prerequisites</title>
-
- <sect2>
- <title>&defsystem;</title>
- <para> &clsql; uses &asdf; to compile and load its
-components. &asdf; is included in the <ulink
-url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
- </para>
- </sect2>
-
- <sect2>
- <title>&uffi;</title>
- <para>&clsql; uses <ulink
-url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
-as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
-linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
-implementations.</para>
-
-<para>You can download &uffi; from its FTP <ulink
-url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
-are zip files for Microsoft Windows systems and gzipped tar files for
-other systems.</para>
- </sect2>
-
- <sect2>
- <title>&md5;</title>
- <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
- <ulink url="ftp://clsql.b9.com/">md5</ulink> module. If you plan to use
- this interface please download the md5 module from ftp://clsql.b9.com </para>
- <sect2>
- <title>Supported Common Lisp Implementation</title>
- <para>
-The implementations that support &clsql; is governed by the supported
-implementations of &uffi;. The following implementations are supported:
- </para>
- <itemizedlist mark="opencircle">
- <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
- <listitem><para>&lw; v4.2 on Debian Linux and Microsoft Windows XP.</para></listitem>
- <listitem><para>&cmucl; 18d on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
- <listitem><para>&sbcl; 0.7.14 on Debian Linux.</para></listitem>
- <listitem><para>&scl; 1.1 on Debian Linux.</para></listitem>
- <listitem><para>&openmcl; 0.13 on Debian Linux PowerPC.</para></listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Supported &sql; Implementation</title>
- <para>
- Currently, &clsql; supports the following databases:
- </para>
- <itemizedlist mark="opencircle">
- <listitem><para>&mysql; v3.23.51.</para></listitem>
- <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
- <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
- </itemizedlist>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Installation</title>
-
- <sect2>
- <title>Ensure &defsystem; is loaded</title>
- <para>
- Simply load the file <filename>defsystem.lisp</filename>.
- <programlisting>
-(load "defsystem.lisp")
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Build &c; helper libraries</title>
- <para>&clsql; uses functions that require 64-bit integer
-parameters and return values. The &ffi; in most &clsql;
-implementations do not support 64-bit integers. Thus, C helper
-libraries are required to break these 64-bit integers into two compatible
-32-bit integers.</para>
-
-<para>Makefiles for Microsoft Windows and GNU/Solaris systems
-are supplied to build the libraries. Since many Microsoft Windows
-users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
-files for Microsoft Windows are supplied with the distribution.</para>
-
-<para>To build the libraries on a GNU or Solaris, use the shell and
-change to the root directory of &clsql;. You may need to edit the file
-<filename>interfaces/mysql/Makefile</filename> to specify the location of your
-MySQL installation. The default Makefiles are setup for shared library
-linking on Linux. If you are using FreeBSD or Solaris, you will need
-to change the linker setting as instructed in the Makefile.
-Then, you can give the command
-<programlisting>
-make libs
-</programlisting>
-in the root directory of &clsql; to build the libraries
-<filename>interfaces/mysql/clsql-mysql.so</filename> and
-<filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
-</para>
- </sect2>
-
- <sect2>
- <title>Load &uffi;</title>
- <para>
- Unzip or untar the &uffi; distribution which creates a directory
-for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
-You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the &uffi; files reside in the
-<filename>/usr/share/lisp/uffi/</filename> directory.
- <programlisting>
-(push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
-(asdf:oos 'asdf:load-op :uffi)
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>Load &md5; module</title>
- <para>
- If you plan to use the clsql-postgresql-socket interface, you must load the md5 module.
- Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
- Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
- You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the cl-md5 files reside in the
- <filename>/usr/share/lisp/cl-md5/</filename> directory.
- <programlisting>
-(push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
-(asdf:oos 'asdf:load-op :md5)
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Load &clsql; modules</title>
- <para>
- Unzip or untar the &clsql; distribution which creates a directory
-for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
-You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the &clsql; files reside in the
-<filename>/usr/share/lisp/clsql/</filename> directory. You need to load, at a minimum,
-the main <symbol>:clsql</symbol> system and at least one interface system.
- <programlisting>
-(push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
-(asdf:oos 'asdf:load-op :clsql-base) ; base clsql package
-(asdf:oos 'asdf:load-op :clsql-mysql) ; MySQL interface
-(asdf:oos 'asdf:load-op :clsql-postgresql) ; PostgreSQL interface
-(asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
-(asdf:oos 'asdf:load-op :clsql-aodbc) ; Allegro ODBC interface
-(asdf:oos 'asdf:load-op :clsql) ; main clsql package
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Run test suite</title>
- <para>
- After loading &clsql;, you can execute the test program in
-the directory <filename>./test-suite</filename>. The test file,
-<filename>tester-clsql</filename>
-has instructions for creating a <filename>test.config</filename>.
-After creating that file, simple load the test file with Lisp
-and the tests should automatically execute.
- </para>
- </sect2>
-
- </sect1>
-
-</chapter>
--- /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;
+]>
+
+<chapter id="introduction">
+ <title>Introduction</title>
+
+ <sect1 id="purpose">
+ <title>Purpose</title>
+ <para>&clsql; is a Common Lisp interface to <glossterm
+ linkend="gloss-sql">SQL</glossterm> databases. A number of Common
+ Lisp implementations and SQL databases are supported. The general
+ structure of &clsql; is based on the
+ <application>CommonSQL</application>
+ package by Xanalys.
+ </para>
+ </sect1>
+
+ <sect1 id="history">
+ <title>History</title>
+ <para>
+ &clsql; is written by Kevin M. Rosenberg and based substantially
+ on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
+ are:
+ <itemizedlist>
+ <listitem>
+ <para>Optimized loading of integer and floating-point fields.</para>
+ </listitem>
+ <listitem>
+ <para>port from the &cmucl; FFI to &uffi;.</para>
+ </listitem>
+ <listitem>
+ <para>new &acl; ODBC interface back-end.</para>
+ </listitem>
+ <listitem>
+ <para>compatibility layer for &cmucl; specific code.</para>
+ </listitem>
+ <listitem>
+ <para>much improved robustness for the &mysql; back-end.</para>
+ </listitem>
+ <listitem>
+ <para>improved system loading.</para>
+ </listitem>
+ <listitem>
+ <para>improved packages and symbol export.</para>
+ </listitem>
+ <listitem>
+ <para>transaction support.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="prerequisites">
+ <title>Prerequisites</title>
+
+ <sect2>
+ <title>&defsystem;</title>
+ <para> &clsql; uses &asdf; to compile and load its
+ components. &asdf; is included in the <ulink
+ url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>&uffi;</title>
+ <para>&clsql; uses <ulink
+ url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
+ as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
+ linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
+ implementations.
+ </para>
+
+ <para>You can download &uffi; from its FTP <ulink
+ url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
+ are zip files for Microsoft Windows systems and gzipped tar files for
+ other systems.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>&md5;</title>
+ <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
+ <ulink url="ftp://clsql.b9.com/">md5</ulink>
+ module. If you plan to use
+ this interface please download the md5 module from ftp://clsql.b9.com.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Supported Common Lisp Implementation</title>
+ <para>
+ The implementations that support &clsql; is governed by the supported
+ implementations of &uffi;. The following implementations are supported:
+ </para>
+ <itemizedlist mark="opencircle">
+ <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
+ <listitem><para>&lw; v4.3 on Debian Linux and Microsoft Windows XP.</para></listitem>
+ <listitem><para>&cmucl; 18e on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
+ <listitem><para>&sbcl; 0.8.5 on Debian Linux.</para></listitem>
+ <listitem><para>&scl; 1.2 on Debian Linux.</para></listitem>
+ <listitem><para>&openmcl; 0.14 on Debian Linux PowerPC.</para></listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Supported &sql; Implementation</title>
+ <para>
+ Currently, &clsql; supports the following databases:
+ </para>
+ <itemizedlist mark="opencircle">
+ <listitem><para>&mysql; v3.23.51.</para></listitem>
+ <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
+ <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
+ </itemizedlist>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="installation">
+ <title>Installation</title>
+
+ <sect2>
+ <title>Ensure &defsystem; is loaded</title>
+ <para>
+ Simply load the file <filename>defsystem.lisp</filename>.
+ <programlisting>
+(load "defsystem.lisp")
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Build &c; helper libraries</title>
+ <para>&clsql; uses functions that require 64-bit integer
+ parameters and return values. The &ffi; in most &clsql;
+ implementations do not support 64-bit integers. Thus, C helper
+ libraries are required to break these 64-bit integers into two compatible
+ 32-bit integers.
+ </para>
+
+ <para>Makefiles for Microsoft Windows and GNU/Solaris systems
+ are supplied to build the libraries. Since many Microsoft Windows
+ users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
+ files for Microsoft Windows are supplied with the distribution.
+ </para>
+
+ <para>To build the libraries on a GNU or Solaris, use the shell and
+ change to the root directory of &clsql;. You may need to edit the file
+ <filename>interfaces/mysql/Makefile</filename>
+ to specify the location of your
+ MySQL installation. The default Makefiles are setup for shared library
+ linking on Linux. If you are using FreeBSD or Solaris, you will need
+ to change the linker setting as instructed in the Makefile.
+ Then, you can give the command
+ <programlisting>
+make libs
+ </programlisting>
+ in the root directory of &clsql; to build the libraries
+ <filename>interfaces/mysql/clsql-mysql.so</filename>
+ and <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Load &uffi;</title>
+ <para>
+ Unzip or untar the &uffi; distribution which creates a directory
+ for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
+ You can do that by pushing the pathname of the directory onto this variable.
+ The following example code assumes the &uffi; files reside in the
+ <filename>/usr/share/lisp/uffi/</filename>
+ directory.
+ <programlisting>
+(push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
+(asdf:oos 'asdf:load-op :uffi)
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Load &md5; module</title>
+ <para>
+ If you plan to use the clsql-postgresql-socket interface, you must load the md5 module.
+ Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
+ Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
+ You can do that by pushing the pathname of the directory onto this variable.
+ The following example code assumes the cl-md5 files reside in the
+ <filename>/usr/share/lisp/cl-md5/</filename>
+ directory.
+ <programlisting>
+(push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
+(asdf:oos 'asdf:load-op :md5)
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Load &clsql; modules</title>
+ <para>
+ Unzip or untar the &clsql; distribution which creates a directory
+ for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
+ You can do that by pushing the pathname of the directory onto this variable.
+ The following example code assumes the &clsql; files reside in the
+ <filename>/usr/share/lisp/clsql/</filename>
+ directory. You need to load, at a minimum,
+ the main <symbol>:clsql</symbol> system and at least one interface system.
+ <programlisting>
+(push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
+(asdf:oos 'asdf:load-op :clsql-base) ; base clsql package
+(asdf:oos 'asdf:load-op :clsql-mysql) ; MySQL interface
+(asdf:oos 'asdf:load-op :clsql-postgresql) ; PostgreSQL interface
+(asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
+(asdf:oos 'asdf:load-op :clsql-aodbc) ; Allegro ODBC interface
+(asdf:oos 'asdf:load-op :clsql) ; main clsql package
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Run test suite</title>
+ <para>
+ After loading &clsql;, you can execute the test program in
+ the directory <filename>./test-suite</filename>. The test file,
+ <filename>tester-clsql</filename>
+ has instructions for creating a <filename>test.config</filename>.
+ After creating that file, simple load the test file with Lisp
+ and the tests should automatically execute.
+ </para>
+ </sect2>
+
+ </sect1>
+
+</chapter>
+++ /dev/null
-<!-- -*- DocBook -*- -->
-
- <preface>
- <title>Preface</title>
- <para>This guide provides reference
- to the features of &clsql;. The first
- chapter provides an introduction to &clsql; and installation
- instructions.
- Following that chapter is the reference section for all user
- accessible symbols of &clsql; with examples of usage,
- followed by the reference section for all accessible symbols of
- the database back-end interface. At the end there you will find
- a glossary of commonly used terms with their
- definitions.</para>
- </preface>
--- /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;
+]>
+
+<preface id="preface">
+ <title>Preface</title>
+ <para>This guide provides reference
+ to the features of &clsql;. The first
+ chapter provides an introduction to &clsql; and installation
+ instructions.
+ Following that chapter is the reference section for all user
+ accessible symbols of &clsql; with examples of usage,
+ followed by the reference section for all accessible symbols of
+ the database back-end interface. At the end there you will find
+ a glossary of commonly used terms with their
+ definitions.
+ </para>
+</preface>
+++ /dev/null
-<!-- -*- DocBook -*- -->
-
- <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>
-
- <reference>
- <title><symbol>CLSQL-SYS</symbol></title>
- <partintro>
- <para>This part gives a reference to all the symbols exported
- from the package <symbol>CLSQL-SYS</symbol>, which are not also
- exported from <symbol>CLSQL</symbol>. These symbols are part of
- the interface for database back-ends, but not part of the normal
- user-interface of &clsql;.</para>
- </partintro>
- <refentry id="database-initialize-database-type">
- <refnamediv>
- <refname>DATABASE-INITIALIZE-DATABASE-TYPE</refname>
- <refpurpose>Back-end part of <link
- linkend="initialize-database-type"><function>initialize-database-type</function></link>.</refpurpose>
- <refclass>Generic Function</refclass>
- </refnamediv>
- <refsect1>
- <title>Syntax</title>
- <synopsis><function>database-initialize-database-type</function> <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>A keyword indicating the database type to
- initialize.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><returnvalue>result</returnvalue></term>
- <listitem>
- <para>Either <symbol>t</symbol> if the initialization
- succeeds or <symbol>nil</symbol> if it fails.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1>
- <title>Description</title>
- <para>This generic function implements the main part of the
- database type initialization performed by
- <function>initialize-database-type</function>. After
- <function>initialize-database-type</function> has checked
- that the given database type has not been initialized
- before, as indicated by
- <symbol>*initialized-database-types*</symbol>, it will call
- this function with the database type as it's sole
- parameter. Database back-ends are required to define a
- method on this generic function which is specialized via an
- eql-specializer to the keyword representing their database
- type.</para>
- <para>Database back-ends shall indicate successful
- initialization by returning <symbol>t</symbol> from their
- method, and <symbol>nil</symbol> otherwise. Methods for
- this generic function are allowed to signal errors of type
- <errortype>clsql-error</errortype> or subtypes thereof.
- They may also signal other types of conditions, if
- appropriate, but have to document this.</para>
- </refsect1>
- <refsect1>
- <title>Examples</title>
- <para></para>
- </refsect1>
- <refsect1>
- <title>Side Effects</title>
- <para>All necessary side effects to initialize the database
- instance.</para>
- </refsect1>
- <refsect1>
- <title>Affected By</title>
- <para>None.</para>
- </refsect1>
- <refsect1>
- <title>Exceptional Situations</title>
- <para>Conditions of type <errortype>clsql-error</errortype>
- or other conditions may be signalled, depending on the
- database back-end.</para>
- </refsect1>
- <refsect1>
- <title>See Also</title>
- <para>
- <simplelist>
- <member><link
- linkend="initialize-database-type"><function>initialize-database-type</function></link></member>
- <member><link linkend="initialized-database-types"><symbol>*initialized-database-types*</symbol></link></member>
- </simplelist>
- </para>
- </refsect1>
- <refsect1>
- <title>Notes</title>
- <para>None.</para>
- </refsect1>
- </refentry>
- </reference>
+++ /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>
--- /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 id="clsql">
+ <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;.
+ </para>
+ </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;.
+ </para>
+ </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>.
+ </para>
+ </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.
+ </para>
+ </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>
projects / clsql.git / commitdiff