<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN" "http://www.gnustep.org/gsdoc-1_0_3.dtd">
<gsdoc base="SQLClient">
  <head>
    <title>SQLClient documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <version>32005</version>
    <date>2011-02-07 15:42:58 +0000 (Mon, 07 Feb 2011)</date>
    <copy>2004 Free Software Foundation, Inc.</copy>
  </head>
  <body>
    <front><contents /></front>
    <chapter>
      <heading>The SQLClient library</heading>
      <section>
        <heading>What is the SQLClient library?</heading>
        <p>
          The SQLClient library is designed to provide a simple
          interface to SQL databases for GNUstep
          applications. It does not attempt the sort of
          abstraction provided by the much more
          sophisticated GDL2 library, but rather allows
          applications to directly execute SQL queries and
          statements.
        </p>
        <p>
          SQLClient provides for the Objective-C programmer
          much the same thing that JDBC provides for the Java
          programmer (though SQLClient is a bit faster,
          easier to use, and easier to add new database backends
          for than JDBC).
        </p>
        <p>
          The major features of the SQLClient library are -
        </p>
        <list>
          <item>
            Simple API for executing queries and statements... a
            variable length sequence of comma separated
            strings and other objects (NSNumber, NSDate,
            NSData) are concatenated into a single SQL
            statement and executed.
          </item>
          <item>
            Simple API
            <ref type="class" id="SQLTransaction">SQLTransaction</ref>
              )for combining multiple SQL statements into a single
              transaction which can be used to minimise
              client-server interactions to get the best
              possible performance from your database.
            </item>
            <item>
              Supports multiple sumultaneous named connections
              to a database server in a thread-safe manner. <br />
            </item>
            <item>
              Supports multiple simultaneous connections to
              different database servers with backend driver
              bundles loaded for different database engines.
              Clear, simple subclassing of the abstract base
              class to enable easy implementation of new backend
              bundles.
            </item>
            <item>
              Configuration for all connections held in
              one place and referenced by connection name for ease
              of configuration control. Changes via NSUserDefaults
              can even allow reconfiguration of client instances
              within a running application.
            </item>
            <item>
              Thread safe operation... The base class supports
              locking such that a single instance can be shared
              between multiple threads.
            </item>
            <item>
              Support for standalone web applications... eg to
              allow data to be added to the database by people
              posting web forms to the application.
            </item>
            <item>
              Supports notification of connection to and
              disconnection from the database server.
            </item>
          </list>
        </section>
        <section>
          <heading>
            What backend bundles are available?
          </heading>
          <p>
            Current backend bundles are -
          </p>
          <list>
            <item>
              ECPG - a bundle using the embedded SQL interface for
              postgres. <br /> This is based on a similar
              code which was in production use for over eighteen
              months, so it should be reliable, but
              inefficient.
            </item>
            <item>
              Postgres - a bundle using the libpq native
              interface for postgres. <br /> This is the
              preferred backend as it allows 'SELECT FOR
              UPDATE', which the ECPG backend cannot support
              due to limitations in the postgres implementation of
              cursors. The code is now well tested and known
              to be efficient.
            </item>
            <item>
              MySQL - a bundle using the mysqlclient library for
              *recent* MySQL. <br /> I don't use MySQL... but
              the test program ran successfully with a vanilla
              install of the MySQL packages for recent Debian
              unstable.
            </item>
            <item>
              SQLite - a bundle using the sqlite3 library which
              supports an SQL-like API for direct access to a
              database file (rather than acting as a client of
              a database server process). <br /> Not as functional as
              the other backends (doesn't support dates for
              instance), but good enough for many purposes
              and very 'lightweight'. See http://www.sqlite.org
            </item>
            <item>
              Oracle - a bundle using embedded SQL for Oracle.
              <br /> Completely untested... may even need some
              work to compile... but this *is* based on code which
              was working about a year ago. <br /> No support for
              BLOBs yet.
            </item>
          </list>
        </section>
        <section>
          <heading>
            Where can you get it? How can you install it?
          </heading>
          <p>
            The SQLClient library is currently only available via
            CVS from the GNUstep CVS repository. <br /> See
            &lt;https://savannah.gnu.org/cvs/?group=gnustep&gt;
            <br /> You need to check out
            <code>gnustep/dev-libs/SQLClient</code>
          </p>
          <p>
            To build this library you must have a basic GNUstep
            environment set up...
          </p>
          <list>
            <item>
              The gnustep-make package must have been built and
              installed.
            </item>
            <item>
              The gnustep-base package must have been built and
              installed.
            </item>
            <item>
              The Performance library (from the dev-libs area in
              GNUstep CVS) must have been built and installed.
            </item>
            <item>
              If this environment is in place, all you should need
              to do is run 'make' to configure and build the
              library, 'make install' to install it.
            </item>
            <item>Then you can run the test programs.</item>
            <item>
              Your most likely problems are that the configure
              script may not detect the database libraries you
              want... Please figure out how to modify
              <code>configure.ac</code> so that it will detect
              the required headers and libraries on your system,
              and supply na patch.
            </item>
            <item>
              Once the library is installed, you can include the
              header file
              <code>&lt;SQLClient/SQLClient.h%gt;</code> and
              link your programs with the <code>SQLClient</code>
              library to use it.
            </item>
          </list>
          <p>
            Bug reports, patches, and contributions (eg a backend
            bundle for a new database) should be entered on the
            GNUstep project page
            &lt;http://savannah.gnu.org/projects/gnustep&gt;
            and the bug reporting page
            &lt;http://savannah.gnu.org/bugs/?group=gnustep&gt;
          </p>
        </section>
      </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient class
      </heading>
      <class name="SQLClient" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          <p>
            The SQLClient class encapsulates dynamic SQL access to
            relational database systems. A shared instance
            of the class is used for each database (as identified by
            the name of the database), and the number of
            simultanous database connections is managed
            too.
          </p>
          <p>
            SQLClient is an abstract base class... when you
            create an instance of it, you are actually creating
            an instance of a concrete subclass whose implementation
            is loaded from a bundle.
          </p>
        </desc>
        <ivariable type="GSCache*" name="_cache" validity="protected">
          <desc>
            The cache for query results <br /> <em>Warning</em> the
            underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSThread*" name="_cacheThread" validity="protected">
          <desc>
            Thread for cache queries <br /> <em>Warning</em> the
            underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_client" validity="protected">
          <desc>
            Identifier within backend <br />
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="unsigned int" name="_connectFails" validity="protected">
          <desc>
            The count of connection failures <br />
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_database" validity="protected">
          <desc>
            The configured database name/host <br />
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="unsigned int" name="_debugging" validity="protected">
          <desc>
            The current debugging level <br /> <em>Warning</em> the
            underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSTimeInterval" name="_duration" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="void*" name="_extra" validity="protected">
          <desc>
            Allow for extensions by allocating memory and
            pointing to it from the _extra ivar. That way we
            can avoid binary incompatibility between minor
            releases. <br /> <em>Warning</em> the underscore
            at the start of the name of this instance variable
            indicates that, even though it is not technically
            <em>private</em>, it is intended for internal use
            within the package, and you should not use the
            variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_inTransaction" validity="protected">
          <desc>
            A flag indicating whether this instance is currently
            within a transaction. This variable must
            <em>only</em> be set by the
            <ref type="method" id="-begin">
              -begin
            </ref>
            , <ref type="method" id="-commit">-commit</ref> or
            <ref type="method" id="-rollback">
              -rollback
            </ref>
            methods. <br /> Are we inside a transaction?
            <br /> <em>Warning</em> the underscore at the start
            of the name of this instance variable indicates that,
            even though it is not technically <em>private</em>, it
            is intended for internal use within the package, and you
            should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSTimeInterval" name="_lastOperation" validity="protected">
          <desc>
            Timestamp of last operation. <br /> Maintained by
            <ref type="method" id="-simpleExecute:">
              -simpleExecute:
            </ref>
            <ref type="method" id="-simpleQuery:recordType:listType:">
              -simpleQuery:recordType:listType:
            </ref>
            and
            <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> Also set for a failed connection attempt, but not reported by the <ref type="method" id="-lastOperation">-lastOperation</ref> method in that case. <br /> <em>Warning</em> the underscore at the start of the name of this instance variable indicates that, even though it is not technically <em>private</em>, it is intended for internal use within the package, and you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_name" validity="protected">
          <desc>
            Unique identifier for instance <br />
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_password" validity="protected">
          <desc>
            The configured password <br /> <em>Warning</em> the
            underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSMutableArray*" name="_statements" validity="protected">
          <desc>
            Uncommitted statements <br /> <em>Warning</em>
            the underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSString*" name="_user" validity="protected">
          <desc>
            The configured user <br /> <em>Warning</em> the
            underscore at the start of the name of this
            instance variable indicates that, even though it
            is not technically <em>private</em>, it is intended for
            internal use within the package, and you should
            not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="connected" validity="protected">
          <desc>
            A flag indicating whether this instance is currently
            connected to the backend database server. This
            variable must <em>only</em> be set by the
            <ref type="method" id="-backendConnect">
              -backendConnect
            </ref>
            or
            <ref type="method" id="-backendDisconnect">
              -backendDisconnect
            </ref>
            methods.
          </desc>
        </ivariable>
        <ivariable type="void*" name="extra" validity="protected">
          <desc>
            For subclass specific data
          </desc>
        </ivariable>
        <ivariable type="NSRecursiveLock*" name="lock" validity="protected">
          <desc>
            Maintain thread-safety
          </desc>
        </ivariable>
        <method type="NSArray*" factory="yes">
          <sel>allClients</sel>
          <desc>
            Returns an array containing all the SQLClient
            instances.
          </desc>
        </method>
        <method type="SQLClient*" factory="yes">
          <sel>clientWithConfiguration:</sel>
          <arg type="NSDictionary*">config</arg>
          <sel>name:</sel>
          <arg type="NSString*">reference</arg>
          <desc>
            Return an existing SQLClient instance (using
            +existingClient:) if possible, or creates
            one, initialises it using
            <ref type="method" id="-initWithConfiguration:name:">
              -initWithConfiguration:name:
            </ref>
            , and returns the new instance (autoreleased). <br />
            Returns <code>nil</code> on failure.
          </desc>
        </method>
        <method type="SQLClient*" factory="yes">
          <sel>existingClient:</sel>
          <arg type="NSString*">reference</arg>
          <desc>
            Return an existing SQLClient instance for the
            specified name if one exists, otherwise returns
            <code>nil</code>.
          </desc>
        </method>
        <method type="unsigned int" factory="yes">
          <sel>maxConnections</sel>
          <desc>
            Return the maximum number of simultaneous database
            connections permitted (set by
            <ref type="method" id="+setMaxConnections:">
              +setMaxConnections:
            </ref>
            and defaults to 8)
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>purgeConnections:</sel>
          <arg type="NSDate*">since</arg>
          <desc>
            <p>
              Use this method to reduce the number of database
              connections currently active so that it is
              less than the limit set by the
              <ref type="method" id="+setMaxConnections:">
                +setMaxConnections:
              </ref>
              method. This mechanism is used internally by the
              class to ensure that, when it is about to open a
              new connection, the limit is not exceeded.
            </p>
            <p>
              If <var>since</var> is not <code>nil</code>, then any
              connection which has not been used more
              recently than that date is disconnected anyway.
              <br /> You can (and probably should) use this
              periodically to purge idle connections, but
              you can also pass a date in the future to close all
              connections.
            </p>
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setMaxConnections:</sel>
          <arg type="unsigned int">c</arg>
          <desc>
            <p>
              Set the maximum number of simultaneous database
              connections permitted (defaults to 8 and may
              not be set less than 1).
            </p>
            <p>
              This value is used by the
              <ref type="method" id="+purgeConnections:">
                +purgeConnections:
              </ref>
              method to determine how many connections should be
              disconnected when it is called.
            </p>
          </desc>
        </method>
        <method type="void">
          <sel>begin</sel>
          <desc>
            Start a transaction for this database client. <br />
            You <strong>must</strong> match this with either a
            <ref type="method" id="-commit">
              -commit
            </ref>
            or a <ref type="method" id="-rollback">-rollback</ref>.
            <br />
            <p>
              Normally, if you execute an SQL statement
              without using this method first, the
              <em>autocommit</em> feature is employed, and the
              statement takes effect immediately. Use of this
              method permits you to execute several statements
              in sequence, and only have them take effect (as a
              single operation) when you call the
              <ref type="method" id="-commit">
                -commit
              </ref>
              method.
            </p>
            <p>
              NB. You must <strong>not</strong> execute an SQL
              statement which would start a transaction
              directly... use only this method.
            </p>
            <p>
              Where possible, consider using the
              <ref type="class" id="SQLTransaction">SQLTransaction</ref>class rather than calling <ref type="method" id="-begin">-begin</ref> <ref type="method" id="-commit">-commit</ref> or <ref type="method" id="-rollback">-rollback</ref> yourself.</p>
          </desc>
        </method>
        <method type="NSString*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <p>
              Build an sql query string using the supplied
              arguments.
            </p>
            <p>
              This method has at least one argument, the string
              starting the query to be executed (which must
              have the prefix 'select ').
            </p>
            <p>
              Additional arguments are a <code>nil</code>
              terminated list which also be strings, and
              these are appended to the statement. <br /> Any
              string arguments are assumed to have been quoted
              appropriately already, but non-string
              arguments are automatically quoted using the
              <ref type="method" id="-quote:">
                -quote:
              </ref>
              method.
            </p>
<example>
   sql = [db buildQuery: @"SELECT Name FROM ", table, nil];
 </example>
            <p>
              Upon error, an exception is raised.
            </p>
            <p>
              The method returns a string containing sql suitable
              for passing to the
              <ref type="method" id="-simpleQuery:recordType:listType:">-simpleQuery:recordType:listType:</ref> or <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> methods.
            </p>
          </desc>
        </method>
        <method type="NSString*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            Takes the query statement and substitutes in
            <var>values</var> from the dictionary where markup of
            the format {key} is found. <br /> Returns the resulting
            query string.
<example>
   sql = [db buildQuery: @"SELECT Name FROM {Table} WHERE ID = {ID}"
                   with: values];
 </example>
            <p>
              Any non-string <var>values</var> in the dictionary
              will be replaced by the results of the
              <ref type="method" id="-quote:">
                -quote:
              </ref>
              method. <br /> The markup format may also be
              {key?default} where <em>default</em> is a
              string to be used if there is no value for the
              <em>key</em> in the dictionary.
            </p>
            <p>
              The method returns a string containing sql suitable
              for passing to the
              <ref type="method" id="-simpleQuery:recordType:listType:">-simpleQuery:recordType:listType:</ref> or <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> methods.
            </p>
          </desc>
        </method>
        <method type="NSString*">
          <sel>clientName</sel>
          <desc>
            Return the client name for this instance. <br />
            Normally this is useful only for
            debugging/reporting purposes, but if
            you are using multiple instances of this class in your
            application, and you are using embedded SQL,
            you will need to use this method to fetch the
            client/connection name and store its
            C-string representation in a variable
            'connectionName' declared to the sql
            preprocessor, so you can then have statements
            of the form - 'exec sql at :connectionName...'.
          </desc>
        </method>
        <method type="void">
          <sel>commit</sel>
          <desc>
            Complete a transaction for this database client.
            <br /> This <strong>must</strong> match an earlier
            <ref type="method" id="-begin">
              -begin
            </ref>
            .
            <p>
              NB. You must <strong>not</strong> execute an SQL
              statement which would commit or rollback a
              transaction directly... use only this method
              or the
              <ref type="method" id="-rollback">
                -rollback
              </ref>
              method.
            </p>
            <p>
              Where possible, consider using the
              <ref type="class" id="SQLTransaction">SQLTransaction</ref>class rather than calling <ref type="method" id="-begin">-begin</ref> <ref type="method" id="-commit">-commit</ref> or <ref type="method" id="-rollback">-rollback</ref> yourself.</p>
          </desc>
        </method>
        <method type="BOOL">
          <sel>connect</sel>
          <desc>
            If the <em>connected</em> instance variable is
            <code>NO</code>, this method calls
            <ref type="method" id="-backendConnect">
              -backendConnect
            </ref>
            to ensure that there is a connection to the database
            server established. Returns the result. <br />
            Performs any necessary locking for thread safety.
            <br /> This method also counts the number of
            consecutive failed connection attempts. A delay
            is enforced between each connection attempt, with the
            length of the delay growing with each failure. This
            ensures that applications which fail to deal with
            connection failures, and just keep trying to
            reconnect, will not overload the system/server.
            <br /> The maximum delay is 30 seconds, so when the
            database server is restarted, the application can
            reconnect reasonably quickly.
          </desc>
        </method>
        <method type="BOOL">
          <sel>connected</sel>
          <desc>
            Return a flag to say whether a connection to the
            database server is currently live. This is mostly
            useful for debug/reporting, but is used internally
            to keep track of active connections.
          </desc>
        </method>
        <method type="NSString*">
          <sel>database</sel>
          <desc>
            Return the database name for this instance (or
            <code>nil</code>).
          </desc>
        </method>
        <method type="void">
          <sel>disconnect</sel>
          <desc>
            If the <em>connected</em> instance variable is
            <code>YES</code>, this method calls
            <ref type="method" id="-backendDisconnect">
              -backendDisconnect
            </ref>
            to ensure that the connection to the database server is
            dropped. <br /> Performs any necessary locking for
            thread safety.
          </desc>
        </method>
        <method type="void">
          <sel>execute:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Perform arbitrary operation
            <em>which does not return any value.</em> <br /> This
            arguments to this method are a <code>nil</code>
            terminated list which are concatenated in the
            manner of the
            <ref type="method" id="-query:,...">
              -query:,...
            </ref>
            method. <br /> Any string arguments are assumed to
            have been quoted appropriately already, but non-string
            arguments are automatically quoted using the
            <ref type="method" id="-quote:">
              -quote:
            </ref>
            method.
<example>
   [db execute: @"UPDATE ", table, @" SET Name = ",
     myName, " WHERE ID = ", myId, nil];
 </example>
          </desc>
        </method>
        <method type="void">
          <sel>execute:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            Takes the statement and substitutes in
            <var>values</var> from the dictionary where markup of
            the format {key} is found. <br /> Passes the result to
            the
            <ref type="method" id="-execute:,...">
              -execute:,...
            </ref>
            method.
<example>
   [db execute: @"UPDATE {Table} SET Name = {Name} WHERE ID = {ID}"
          with: values];
 </example>
            Any non-string <var>values</var> in the dictionary will
            be replaced by the results of the
            <ref type="method" id="-quote:">
              -quote:
            </ref>
            method. <br /> The markup format may also be
            {key?default} where <em>default</em> is a
            string to be used if there is no value for the
            <em>key</em> in the dictionary.
          </desc>
        </method>
        <method type="id">
          <sel>initWithConfiguration:</sel>
          <arg type="NSDictionary*">config</arg>
          <desc>
            Calls
            <ref type="method" id="-initWithConfiguration:name:">
              -initWithConfiguration:name:
            </ref>
            passing a <code>nil</code> reference name.
          </desc>
        </method>
        <method type="id">
          <sel>initWithConfiguration:</sel>
          <arg type="NSDictionary*">config</arg>
          <sel>name:</sel>
          <arg type="NSString*">reference</arg>
          <desc>
            Initialise using the supplied configuration, or
            if that is <code>nil</code>, try to use values from
            NSUserDefaults (and automatically update
            when the defaults change). <br /> Uses the
            <var>reference</var> name to determine configuration
            information... and if a <code>nil</code> name
            is supplied, defaults to the value of SQLClientName in
            the configuration dictionary (or in the standard user
            defaults). If there is no value for
            SQLClientName, uses the string 'Database'.
            <br /> If a SQLClient instance already exists with
            the name used for this instance, the receiver is
            deallocated and the existing instance is
            retained and returned... there may only ever be
            one instance for a particular <var>reference</var>
            name. <br /> <br /> The <var>config</var> argument
            (or the SQLClientReferences user default) is a
            dictionary with names as keys and dictionaries
            as its values. Configuration entries from the dictionary
            corresponding to the database client are used
            if possible, general entries are used otherwise. <br />
            Database... is the name of the database to use, if
            it is missing then 'Database' may be used instead.
            <br /> User... is the name of the database user to
            use, if it is missing then 'User' may be used instead.
            <br /> Password... is the name of the database user
            password, if it is missing then 'Password' may be
            used instead. <br /> missing then 'Password' may be
            used instead. <br /> ServerType... is the name of the
            backend server to be used... by convention the name
            of a bundle containing the interface to that backend. If
            this is missing then 'Postgres' is used. <br />
          </desc>
        </method>
        <method type="BOOL">
          <sel>isInTransaction</sel>
          <desc>
            Return the state of the flag indicating whether the
            library thinks a transaction is in progress. This
            flag is normally maintained by
            <ref type="method" id="-begin">
              -begin
            </ref>
            , <ref type="method" id="-commit">-commit</ref>, and
            <ref type="method" id="-rollback">
              -rollback
            </ref>
            .
          </desc>
        </method>
        <method type="NSDate*">
          <sel>lastOperation</sel>
          <desc>
            Returns the date/time stamp of the last database
            operation performed by the receiver, or
            <code>nil</code> if no operation has ever been done
            by it. <br /> Simply connecting to or disconnecting from
            the databsse does not count as an operation.
          </desc>
        </method>
        <method type="NSString*">
          <sel>name</sel>
          <desc>
            Return the database reference name for this instance
            (or <code>nil</code>).
          </desc>
        </method>
        <method type="NSString*">
          <sel>password</sel>
          <desc>
            Return the database password for this instance (or
            <code>nil</code>).
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <p>
              Perform arbitrary query
              <em>which returns values.</em>
            </p>
            <p>
              This method handles its arguments in the same way as
              the
              <ref type="method" id="-buildQuery:,...">
                -buildQuery:,...
              </ref>
              method and returns the result of the query.
            </p>
<example>
   result = [db query: @"SELECT Name FROM ", table, nil];
 </example>
            <p>
              Upon error, an exception is raised.
            </p>
            <p>
              The query returns an array of records (each of which
              is represented by an SQLRecord object).
            </p>
            <p>
              Each SQLRecord object contains one or more fields,
              in the order in which they occurred in the query.
              Fields may also be retrieved by name.
            </p>
            <p>
              NULL field items are returned as NSNull objects.
            </p>
            <p>
              Most other field items are returned as NSString
              objects.
            </p>
            <p>
              Date and timestamp field items are returned as
              NSDate objects.
            </p>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            Takes the query statement and substitutes in
            <var>values</var> from the dictionary (in the same
            manner as the
            <ref type="method" id="-buildQuery:with:">
              -buildQuery:with:
            </ref>
            method) then executes the query and returns the
            response. <br />
<example>
   result = [db query: @"SELECT Name FROM {Table} WHERE ID = {ID}"
                 with: values];
 </example>
            Any non-string <var>values</var> in the dictionary will
            be replaced by the results of the
            <ref type="method" id="-quote:">
              -quote:
            </ref>
            method. <br /> The markup format may also be
            {key?default} where <em>default</em> is a
            string to be used if there is no value for the
            <em>key</em> in the dictionary.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quote:</sel>
          <arg type="id">obj</arg>
          <desc>
            Convert an object to a string suitable for use in
            an SQL query. <br /> Normally the
            <ref type="method" id="-execute:,...">
              -execute:,...
            </ref>
            , and
            <ref type="method" id="-query:,...">
              -query:,...
            </ref>
            methods will call this method automatically for
            everything apart from string objects. <br />
            Strings have to be handled specially, because they
            are used both for parts of the SQL command, and as
            values (where they need to be quoted). So where you
            need to pass a string value which needs quoting, you
            must call this method explicitly. <br /> Subclasses
            may override this method to provide appropriate quoting
            for types of object which need database backend
            specific quoting conventions. However, the defalt
            implementation should be OK for most cases.
            <br /> This method makes use of
            <ref type="method" id="-quoteString:">
              -quoteString:
            </ref>
            to quote literal strings. <br /> The base class
            implementation formats NSDate objects as
            <br /> YYYY-MM-DD hh:mm:ss.mmm ?ZZZZ <br /> NSData
            objects are not quoted... they must not appear in
            queries, and where used for insert/update
            operations, they need to be passed to the
            <ref type="method" id="-backendExecute:">
              -backendExecute:
            </ref>
            method unchanged. <br /> For a <code>nil</code>
            object, we return NULL. <br /> For a number, we
            simply convert directly to a string. <br /> For a
            date, we convert to the text format used by the
            database, and add leading and trailing quotes.
            <br /> For a data object, we don't quote... the
            other parts of the code need to know they have an
            NSData object and pass it on unchanged to the
            <ref type="method" id="-backendExecute:">
              -backendExecute:
            </ref>
            method. <br /> Just in case an NSNull subclass has
            been created by someone. The normal NSNull instance
            should have been handled earlier. <br /> For an
            NSArray or NSSet, we produce a bracketed list of
            the (quoted) objects in the array. <br /> For any other
            type of data, we just produce a quoted string
            representation of the objects description.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteBigInteger:</sel>
          <arg type="int64_t">i</arg>
          <desc>
            Convert a big (64 bit) integer to a string suitable
            for use in an SQL query.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteCString:</sel>
          <arg type="const char*">s</arg>
          <desc>
            Convert a 'C' string to a string suitable for use
            in an SQL query by using
            <ref type="method" id="-quoteString:">
              -quoteString:
            </ref>
            to convert it to a literal string format. <br /> NB. a
            null pointer is treated as an empty string.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteChar:</sel>
          <arg type="char">c</arg>
          <desc>
            Convert a single character to a string suitable for
            use in an SQL query by using
            <ref type="method" id="-quoteString:">
              -quoteString:
            </ref>
            to convert it to a literal string format. <br /> NB. a
            nul character is not allowed and will cause an
            exception.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteFloat:</sel>
          <arg type="float">f</arg>
          <desc>
            Convert a <strong>float</strong> to a string
            suitable for use in an SQL query.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteInteger:</sel>
          <arg type="int">i</arg>
          <desc>
            Convert an integer to a string suitable for use in
            an SQL query.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quoteString:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Convert a string to a form suitable for use as a
            string literal in an SQL query. <br /> Subclasses
            may override this for non-standard literal string
            quoting conventions.
          </desc>
        </method>
        <method type="NSString*">
          <sel>quotef:</sel>
          <arg type="NSString*">fmt</arg>
          <vararg />
          <desc>
            Produce a quoted string from the supplied arguments
            (printf style).
          </desc>
        </method>
        <method type="void">
          <sel>rollback</sel>
          <desc>
            Revert a transaction for this database client.
            <br /> If there is no transaction in progress, this
            method does nothing. <br />
            <p>
              NB. You must <strong>not</strong> execute an SQL
              statement which would commit or rollback a
              transaction directly... use only this method
              or the
              <ref type="method" id="-rollback">
                -rollback
              </ref>
              method.
            </p>
            <p>
              Where possible, consider using the
              <ref type="class" id="SQLTransaction">SQLTransaction</ref>class rather than calling <ref type="method" id="-begin">-begin</ref> <ref type="method" id="-commit">-commit</ref> or <ref type="method" id="-rollback">-rollback</ref> yourself.</p>
          </desc>
        </method>
        <method type="void">
          <sel>setDatabase:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the database host/name for this object. <br /> This
            is called automatically to configure the connection...
            you normally shouldn't need to call it yourself.
          </desc>
        </method>
        <method type="void">
          <sel>setName:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the database reference name for this object. This
            is used to differentiate between multiple connections to
            the database. <br /> This is called automatically to
            configure the connection... you normally
            shouldn't need to call it yourself. <br /> NB.
            attempts to change the name of an instance to that
            of an existing instance are ignored.
          </desc>
        </method>
        <method type="void">
          <sel>setPassword:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the database password for this object. <br /> This
            is called automatically to configure the connection...
            you normally shouldn't need to call it yourself.
          </desc>
        </method>
        <method type="void">
          <sel>setUser:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the database user for this object. <br /> This is
            called automatically to configure the connection...
            you normally shouldn't need to call it yourself.
          </desc>
        </method>
        <method type="void">
          <sel>simpleExecute:</sel>
          <arg type="NSArray*">info</arg>
          <desc>
            Calls
            <ref type="method" id="-backendExecute:">
              -backendExecute:
            </ref>
            in a safe manner. <br /> Handles locking. <br />
            Maintains
            <ref type="method" id="-lastOperation">
              -lastOperation
            </ref>
            date.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>simpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <desc>
            Calls
            <ref type="method" id="-simpleQuery:recordType:listType:">
              -simpleQuery:recordType:listType:
            </ref>
            with the default record class and default array class.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>simpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>recordType:</sel>
          <arg type="id">rtype</arg>
          <sel>listType:</sel>
          <arg type="id">ltype</arg>
          <desc>
            Calls
            <ref type="method" id="-backendQuery:recordType:listType:">-backendQuery:recordType:listType:</ref> in a safe manner. <br /> Handles locking. <br /> Maintains <ref type="method" id="-lastOperation">-lastOperation</ref> date. <br /> The value of <var>rtype</var> must respond to the <ref type="method" id="+newWithValues:keys:count:" class="SQLRecord">[SQLRecord +newWithValues:keys:count:]</ref> method. <br /> If <var>rtype</var> is <code>nil</code> then the
            <ref type="class" id="SQLRecord">SQLRecord</ref>
              class is used. <br /> The value of <var>ltype</var>
              must respond to the
              <ref type="method" id="+alloc" class="NSObject">
                [NSObject +alloc]
              </ref>
              method to produce a container which must repond to
              the
              <ref type="method" id="-initWithCapacity:" class="NSMutableArray">[NSMutableArray -initWithCapacity:]</ref> method to initialise itsself and the <ref type="method" id="-addObject:" class="NSMutableArray">[NSMutableArray -addObject:]</ref> method to add records to the list. <br /> If <var>ltype</var> is <code>nil</code> then the
              <ref type="class" id="NSMutableArray">NSMutableArray</ref>
                class is used. <br />
          </desc>
        </method>
        <method type="NSString*">
          <sel>user</sel>
          <desc>
            Return the database user for this instance (or
            <code>nil</code>).
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLRecord class
      </heading>
      <class name="SQLRecord" super="NSArray">
        <declared>SQLClient.h</declared>
        <desc>
          <p>
            An enhanced array to represent a record returned from a
            query. You should <em>NOT</em> try to create
            instances of this class except via the
            <ref type="method" id="+newWithValues:keys:count:">
              +newWithValues:keys:count:
            </ref>
            method.
          </p>
          <p>
            SQLRecord is the abstract base class of a class
            cluster. If you wish to subclass it you must
            implement the primitive methods
            <ref type="method" id="+newWithValues:keys:count:">
              +newWithValues:keys:count:
            </ref>
            <ref type="method" id="-count">
              -count
            </ref>
            <ref type="method" id="-keyAtIndex:">
              -keyAtIndex:
            </ref>
            <ref type="method" id="-objectAtIndex:">
              -objectAtIndex:
            </ref>
            and
            <ref type="method" id="-replaceObjectAtIndex:withObject:">
              -replaceObjectAtIndex:withObject:
            </ref>
          </p>
          <p>
            NB. You do not need to use SQLRecord (or a subclass of
            it), all you actually need to supply is a class which
            responds to the
            <ref type="method" id="+newWithValues:keys:count:">
              +newWithValues:keys:count:
            </ref>
            method that the system uses to create new records...
            none of the other methods of the SQLRecord class are
            used internally by the SQLClient system.
          </p>
        </desc>
        <method type="id" factory="yes">
          <sel>newWithValues:</sel>
          <arg type="id*">v</arg>
          <sel>keys:</sel>
          <arg type="NSString**">k</arg>
          <sel>count:</sel>
          <arg type="unsigned int">c</arg>
          <desc>
            Create a new SQLRecord containing the specified
            fields. <br /> NB. The values and keys are
            <em>retained</em> by the record rather than being
            copied. <br /> A <code>nil</code> value is
            represented by [NSNull null]. <br /> Keys must
            be unique string values (case insensitive comparison).
          </desc>
        </method>
        <method type="NSArray*">
          <sel>allKeys</sel>
          <desc>
            Returns an array containing the names of all the
            fields in the record.
          </desc>
        </method>
        <method type="unsigned">
          <sel>count</sel>
          <desc>
            Returns the number of items in the record. <br />
            Subclasses must implement this method.
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>dictionary</sel>
          <desc>
            Return the record as a mutable dictionary with the
            keys as the record field names standardised to be
            lowercase strings.
          </desc>
        </method>
        <method type="void">
          <sel>getKeys:</sel>
          <arg type="id*">buf</arg>
          <desc>
            Optimised mechanism for retrieving all keys in
            order.
          </desc>
        </method>
        <method type="void">
          <sel>getObjects:</sel>
          <arg type="id*">buf</arg>
          <desc>
            Optimised mechanism for retrieving all objects.
          </desc>
        </method>
        <method type="NSString*" override="subclass">
          <sel>keyAtIndex:</sel>
          <arg type="unsigned">index</arg>
          <desc>
            Returns the key at the specified indes. <br />
          </desc>
        </method>
        <method type="id" override="subclass">
          <sel>objectAtIndex:</sel>
          <arg type="unsigned">index</arg>
          <desc>
            Returns the object at the specified indes. <br />
          </desc>
        </method>
        <method type="id">
          <sel>objectForKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Returns the value of the named field. <br /> The
            field name is case insensitive.
          </desc>
        </method>
        <method type="void">
          <sel>replaceObjectAtIndex:</sel>
          <arg type="unsigned">index</arg>
          <sel>withObject:</sel>
          <arg type="id">anObject</arg>
          <desc>
            Replaces the value at the specified
            <var>index</var>. <br /> Subclasses must implement
            this method.
          </desc>
        </method>
        <method type="void">
          <sel>setObject:</sel>
          <arg type="id">anObject</arg>
          <sel>forKey:</sel>
          <arg type="NSString*">aKey</arg>
          <desc>
            Replaces the value of the named field. <br /> The
            field name is case insensitive. <br /> NB. You must
            be careful not to change the contents of a record which
            has been cached (unless you are sure you really want
            to), as you will be changing the contents of the
            cache, not just a private copy.
          </desc>
        </method>
        <method type="unsigned">
          <sel>sizeInBytes:</sel>
          <arg type="NSMutableSet*">exclude</arg>
          <desc>
            Return approximate size of this record in bytes.
            <br /> The <var>exclude</var> set is used to specify
            objects to <var>exclude</var> from the calculation
            (to prevent recursion etc).
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLTransaction class
      </heading>
      <class name="SQLTransaction" super="NSObject">
        <declared>SQLClient.h</declared>
        <conform>NSCopying</conform>
        <desc>
          The SQLTransaction transaction class provides a
          convenient mechanism for grouping together a
          series of SQL statements to be executed as a single
          transaction. It avoids the need for handling
          begin/commit, and should be as efficient as
          reasonably possible. <br /> You obtain an instance
          by calling
          <ref type="method" id="-transaction" class="SQLClient">
            [SQLClient -transaction]
          </ref>
          , add SQL statements to it using the
          <ref type="method" id="-add:,...">
            -add:,...
          </ref>
          and/or
          <ref type="method" id="-add:with:">
            -add:with:
          </ref>
          methods, and then use the
          <ref type="method" id="-execute">
            -execute
          </ref>
          method to perform all the statements as a single
          operation. <br /> Any exception is caught and
          re-raised in the
          <ref type="method" id="-execute">
            -execute
          </ref>
          method after any tidying up to leave the database in a
          consistent state. <br /> NB. This class is not in
          itsself thread-safe, though the underlying database
          operations should be. If you have multiple
          threads, you should create multiple SQLTransaction
          instances, at least one per thread.
        </desc>
        <ivariable type="BOOL" name="_batch" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="unsigned int" name="_count" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="SQLClient*" name="_db" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="NSMutableArray*" name="_info" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <ivariable type="BOOL" name="_stop" validity="protected">
          <desc>
            <em>Warning</em> the underscore at the start of the
            name of this instance variable indicates that, even
            though it is not technically <em>private</em>, it is
            intended for internal use within the package, and
            you should not use the variable in other code.
          </desc>
        </ivariable>
        <method type="void">
          <sel>add:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Adds an SQL statement to the transaction. This is
            similar to
            <ref type="method" id="-execute:,..." class="SQLClient">
              [SQLClient -execute:,...]
            </ref>
            but does not cause any database operation until
            <ref type="method" id="-execute">
              -execute
            </ref>
            is called, so it will not raise a database exception.
          </desc>
        </method>
        <method type="void">
          <sel>add:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            Adds an SQL statement to the transaction. This is
            similar to
            <ref type="method" id="-execute:with:" class="SQLClient">
              [SQLClient -execute:with:]
            </ref>
            but does not cause any database operation until
            <ref type="method" id="-execute">
              -execute
            </ref>
            is called, so it will not raise a database exception.
          </desc>
        </method>
        <method type="void">
          <sel>append:</sel>
          <arg type="SQLTransaction*">other</arg>
          <desc>
            Appends a copy of the <var>other</var> transaction
            to the receiver. <br /> This provides a convenient way
            of merging transactions which have been built by
            different code modules, in order to have them all
            executed together in a single operation (for
            efficiency etc). <br /> This does not alter the
            <var>other</var> transaction, so if the execution of
            a group of merged transactions fails, it is then possible
            to attempt to commit the individual transactions
            separately. <br /> NB. All transactions
            appended must be using the same database
            connection (SQLClient instance).
          </desc>
        </method>
        <method type="id">
          <sel>copyWithZone:</sel>
          <arg type="NSZone*">z</arg>
          <desc>
            Make a copy of the receiver.
          </desc>
        </method>
        <method type="unsigned">
          <sel>count</sel>
          <desc>
            Returns the number of individual statements ond/r
            subsidiary transactions which have been added to
            the receiver. For a count of the total number of
            statements, use the
            <ref type="method" id="-totalCount">
              -totalCount
            </ref>
            method.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>db</sel>
          <desc>
            Returns the database client with which this
            instance operates. <br /> This client is retained
            by the transaction.
          </desc>
        </method>
        <method type="void">
          <sel>execute</sel>
          <desc>
            <p>
              Performs any statements added to the transaction
              as a single operation. If any problem occurs, an
              NSException is raised, but the database
              connection is left in a consistent state and a
              partially completed operation is rolled back.
            </p>
            <p>
              NB. If the database is not already in a transaction,
              this implicitly calls the
              <ref type="method" id="-begin">
                -begin
              </ref>
              method to start the transaction before executing
              the statements. <br /> The method always commits the
              transaction, even if the transaction was
              begun earlier rather than in
              <ref type="method" id="-execute">
                -execute
              </ref>
              . <br /> This behavior allows you to call
              <ref type="method" id="-begin" class="SQLClient">
                [SQLClient -begin]
              </ref>
              , then run one or more queries, build up a transaction
              based upon the query results, and then
              <ref type="method" id="-execute">
                -execute
              </ref>
              that transaction, causing the entire process to be
              commited as a single transaction.
            </p>
          </desc>
        </method>
        <method type="unsigned">
          <sel>executeBatch</sel>
          <desc>
            Convenience method which calls
            <ref type="method" id="-executeBatchReturningFailures:logExceptions:">-executeBatchReturningFailures:logExceptions:</ref> with a <code>nil</code> failures argument and exception logging off.
          </desc>
        </method>
        <method type="unsigned">
          <sel>executeBatchReturningFailures:</sel>
          <arg type="SQLTransaction*">failures</arg>
          <sel>logExceptions:</sel>
          <arg type="BOOL">log</arg>
          <desc>
            <p>
              This is similar to the
              <ref type="method" id="-execute">
                -execute
              </ref>
              method, but may allow partial execution of the
              transaction if appropriate:
            </p>
            <p>
              If the transaction was created using the
              <ref type="method" id="-batch:" class="SQLClient">
                [SQLClient -batch:]
              </ref>
              method and the transaction as a whole fails,
              individual statements are retried. <br /> The
              stopOnFailure flag for the batch creation
              indicates whether the retries are stopped at
              the first statement to fail, or continue (skipping
              any failed statements).
            </p>
            <p>
              If the transaction has had transactions appended to
              it, those subsidiary transactions may succeed or fail
              atomically depending on their individual
              attributes.
            </p>
            <p>
              If the transaction was not created using
              <ref type="method" id="-batch:" class="SQLClient">
                [SQLClient -batch:]
              </ref>
              , then calling this method is equivalent to calling the
              <ref type="method" id="-execute">
                -execute
              </ref>
              method.
            </p>
            <p>
              If any statements/transactions in the batch fail, they
              are added to the transaction supplied in the
              <var>failures</var> parameter (if it's not
              <code>nil</code>) so that you can retry them
              later. <br /> NB. statements/transactions which
              are not executed at all (because the batch is set to
              stop on the first failure) are <em>also</em> added
              to the <var>failures</var> transaction.
            </p>
            <p>
              If the <var>log</var> argument is <code>YES</code>,
              then any exceptions encountered when executing the
              batch are logged using the
              <ref type="method" id="-debug:,..." class="SQLClient">
                [SQLClient -debug:,...]
              </ref>
              method, even if debug logging is not enabled with
              <ref type="method" id="-setDebugging:" class="SQLClient">[SQLClient -setDebugging:]</ref>.
            </p>
            The method returns the number of statements which
            actually succeeded.
          </desc>
        </method>
        <method type="void">
          <sel>insertTransaction:</sel>
          <arg type="SQLTransaction*">trn</arg>
          <sel>atIndex:</sel>
          <arg type="unsigned">index</arg>
          <desc>
            Insert <var>trn</var> at the index'th position in
            the receiver. <br /> The transaction <var>trn</var>
            must be non-empty and must use the same database
            client as the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>removeTransactionAtIndex:</sel>
          <arg type="unsigned">index</arg>
          <desc>
            Remove the index'th transaction or statement from
            the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>reset</sel>
          <desc>
            Resets the transaction, removing all previously
            added statements. This allows the transaction object
            to be re-used for multiple transactions.
          </desc>
        </method>
        <method type="unsigned">
          <sel>totalCount</sel>
          <desc>
            Returns the total count of statements in this
            transaction including those in any subsidiary
            transactions. For a count of the statements
            and/or transactions directly added to the receiver,
            use the <ref type="method" id="-count">-count</ref>
            method.
          </desc>
        </method>
        <method type="SQLTransaction*">
          <sel>transactionAtIndex:</sel>
          <arg type="unsigned">index</arg>
          <desc>
            Return an autoreleased copy of the index'th
            transaction or statement added to the receiver.
            <br /> Since the returned transaction contains a
            copy of the statement/transaction in the receiver, you
            can modify it without effecting the original.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient(Caching)
        category
      </heading>
      <category name="Caching" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category provides methods for caching the results
          of queries in order to reduce the number of client-server
          trips and the database load produced by an application
          which needs update its information from the database
          frequently.
        </desc>
        <method type="GSCache*">
          <sel>cache</sel>
          <desc>
            Returns the cache used by the receiver for storing
            the results of requests made through it. Creates a new
            cache if necessary.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Calls
            <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> with the default record class, array class, and with a query string formed from <var>stmt</var> and the following values (if any).
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            Calls
            <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> with the default record class array class and with a query string formed from <var>stmt</var> and <var>values</var>.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>simpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <desc>
            Calls
            <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> with the default record class and array class.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>simpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>recordType:</sel>
          <arg type="id">rtype</arg>
          <sel>listType:</sel>
          <arg type="id">ltype</arg>
          <desc>
            If the result of the query is already cached and has not
            expired, return it. Otherwise, perform the query
            and cache the result giving it the specified lifetime
            in <var>seconds</var>. <br /> If <var>seconds</var> is
            negative, the query is performed irrespective of
            whether it is already cached, and its absolute
            value is used to set the lifetime of the results.
            <br /> If <var>seconds</var> is zero, the cache for
            this query is emptied. <br /> Handles locking. <br />
            Maintains
            <ref type="method" id="-lastOperation">
              -lastOperation
            </ref>
            date. <br /> The value of <var>rtype</var> must
            respond to the
            <ref type="method" id="+newWithValues:keys:count:" class="SQLRecord">[SQLRecord +newWithValues:keys:count:]</ref> method. <br /> If <var>rtype</var> is <code>nil</code> then the
            <ref type="class" id="SQLRecord">SQLRecord</ref>
              class is used. <br /> The value of <var>ltype</var>
              must respond to the
              <ref type="method" id="+alloc" class="NSObject">
                [NSObject +alloc]
              </ref>
              method to produce a container which must repond to
              the
              <ref type="method" id="-initWithCapacity:" class="NSMutableArray">[NSMutableArray -initWithCapacity:]</ref> method to initialise itsself and the <ref type="method" id="-addObject:" class="NSMutableArray">[NSMutableArray -addObject:]</ref> method to add records to the list. <br /> If <var>ltype</var> is <code>nil</code> then the
              <ref type="class" id="NSMutableArray">NSMutableArray</ref>
                class is used. <br /> The list produced by this
                argument is used as the return value of this
                method. <br /> If a cache thread has been set
                using the
                <ref type="method" id="-setCacheThread:">
                  -setCacheThread:
                </ref>
                method, and the
                <ref type="method" id="-cache:simpleQuery:recordType:listType:">-cache:simpleQuery:recordType:listType:</ref> method is called from a thread other than the cache thread, then any query to retrieve uncached data will be performed in the cache thread, and for cached (but expired) data, the old (expired) results may be returned... in which case an asynchronous query to update the cache will be executed as soon as possible in the cache thread.
          </desc>
        </method>
        <method type="void">
          <sel>setCache:</sel>
          <arg type="GSCache*">aCache</arg>
          <desc>
            Sets the cache to be used by the receiver for storing
            the results of requests made through it. <br /> If
            <var>aCache</var> is <code>nil</code>, the current
            cache is released, and a new cache will be
            automatically created as soon as there is a
            need to cache anything.
          </desc>
        </method>
        <method type="void">
          <sel>setCacheThread:</sel>
          <arg type="NSThread*">aThread</arg>
          <desc>
            Sets the thread to be used to retrieve data to
            populate the cache. <br /> All cached queries will
            be performed in this thread (if non-nil). <br /> The
            setting of a thread for the cache also implies that
            expired items in the cache may not be removed when
            they are queried from another thread, rather they can
            be kept (if they are not <em>too</em> old) and an
            asynchronous query to update them will be run
            on the cache thread. <br /> The rule is that, if the
            item's age is more than twice its nominal lifetime,
            it will be retrieved immediately, otherwise it will be
            retrieved asynchrnonously. <br /> Currently this
            may only be the main thread or <code>nil</code>. Any
            attempt to set another thread will use the main
            thread instead.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient(Convenience)
        category
      </heading>
      <category name="Convenience" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category contains convenience methods including
          those for frequently performed database operations...
          message logging etc.
        </desc>
        <method type="SQLTransaction*">
          <sel>batch:</sel>
          <arg type="BOOL">stopOnFailure</arg>
          <desc>
            Returns a transaction object configured to handle
            batching and execute part of a batch of statements
            if execution of the whole using the
            <ref type="method" id="-executeBatch" class="SQLTransaction">[SQLTransaction -executeBatch]</ref> method fails. <br /> If <var>stopOnFailure</var> is <code>YES</code> than execution of the transaction will stop with the first statement to fail, otherwise it will execute all the statements it can, skipping any failed statements.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>columns:</sel>
          <arg type="NSMutableArray*">records</arg>
          <desc>
            Convenience method to deal with the results of
            a query converting the normal array of <var>records</var>
            into an array of record columns. Each column in the
            array is an array containing all the values from that
            column.
          </desc>
        </method>
        <method type="SQLRecord*">
          <sel>queryRecord:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Executes a query (like the
            <ref type="method" id="-query:,...">
              -query:,...
            </ref>
            method) and checks the result (raising an exception
            if the query did not contain a single record) and
            returns the resulting record.
          </desc>
        </method>
        <method type="NSString*">
          <sel>queryString:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Executes a query (like the
            <ref type="method" id="-query:,...">
              -query:,...
            </ref>
            method) and checks the result. <br /> Raises an
            exception if the query did not contain a single
            record, or if the record did not contain a single
            field. <br /> Returns the resulting field as a
            <em>string</em>.
          </desc>
        </method>
        <method type="void">
          <sel>singletons:</sel>
          <arg type="NSMutableArray*">records</arg>
          <desc>
            Convenience method to deal with the results of
            a query where each record contains a single field... it
            converts the array of <var>records</var> returned
            by the query to an array containing the fields.
          </desc>
        </method>
        <method type="SQLTransaction*">
          <sel>transaction</sel>
          <desc>
            Creates and returns an autoreleased SQLTransaction
            instance which will use the receiver as the
            database connection to perform transactions.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient(Logging)
        category
      </heading>
      <category name="Logging" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category porovides basic methods for logging debug
          information.
        </desc>
        <method type="unsigned int" factory="yes">
          <sel>debugging</sel>
          <desc>
            Return the class-wide debugging level, which is
            inherited by all newly created instances.
          </desc>
        </method>
        <method type="NSTimeInterval" factory="yes">
          <sel>durationLogging</sel>
          <desc>
            Return the class-wide duration logging threshold,
            which is inherited by all newly created instances.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setDebugging:</sel>
          <arg type="unsigned int">level</arg>
          <desc>
            Set the debugging <var>level</var> to be inherited by
            all new instances. <br /> See
            <ref type="method" id="-setDebugging:" class="SQLClient(Logging)">[SQLClient(Logging) -setDebugging:]</ref> for controlling an individual instance of the class.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setDurationLogging:</sel>
          <arg type="NSTimeInterval">threshold</arg>
          <desc>
            Set the duration logging <var>threshold</var> to be
            inherited by new instances. <br /> See
            <ref type="method" id="-setDurationLogging:" class="SQLClient(Logging)">[SQLClient(Logging) -setDurationLogging:]</ref> for controlling an individual instance of the class.
          </desc>
        </method>
        <method type="void">
          <sel>debug:</sel>
          <arg type="NSString*">fmt</arg>
          <vararg />
          <desc>
            The default implementation calls NSLogv to log a debug
            message. <br /> Override this in a category to
            provide more sophisticated logging.
          </desc>
        </method>
        <method type="unsigned int">
          <sel>debugging</sel>
          <desc>
            Return the current debugging level. <br /> A level
            of zero (default) means that no debug output is
            produced, except for that concerned with logging
            the database transactions taking over a certain amount
            of time (see the
            <ref type="method" id="-setDurationLogging:">
              -setDurationLogging:
            </ref>
            method).
          </desc>
        </method>
        <method type="NSTimeInterval">
          <sel>durationLogging</sel>
          <desc>
            Returns the threshold above which queries and
            statements taking a <strong>long</strong> time
            to execute are logged. A negative value (default)
            indicates that this logging is disabled. A value
            of zero means that all statements are logged.
          </desc>
        </method>
        <method type="void">
          <sel>setDebugging:</sel>
          <arg type="unsigned int">level</arg>
          <desc>
            Set the debugging <var>level</var> of this instance...
            overrides the default <var>level</var> inherited
            from the class.
          </desc>
        </method>
        <method type="void">
          <sel>setDurationLogging:</sel>
          <arg type="NSTimeInterval">threshold</arg>
          <desc>
            Set a <var>threshold</var> above which queries and
            statements taking a <strong>long</strong> time
            to execute are logged. A negative value (default)
            disables this logging. A value of zero logs all
            statements.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient(Subclass)
        category
      </heading>
      <category name="Subclass" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category contains the methods which a subclass
          <em>must</em> override to provide a working instance,
          and helper methods for the backend implementations.
          <br /> Application programmers should <em>not</em>
          call the backend methods directly. <br />
          <p>
            When subclassing to produce a backend driver bundle,
            please be aware that the subclass must <em>NOT</em>
            introduce additional instance variables. Instead
            the <em>extra</em> instance variable is provided for
            use as a pointer to subclass specific data.
          </p>
        </desc>
        <method type="BOOL" override="subclass">
          <sel>backendConnect</sel>
          <desc>
            Attempts to establish a connection to the database
            server. <br /> Returns a flag to indicate whether
            the connection has been established. <br /> If a
            connection was already established, returns
            <code>YES</code> and does nothing. <br /> You should
            not need to use this method normally, as it is called
            for you automatically when necessary. <br />
            <p>
              Subclasses <strong>must</strong> implement
              this method to establish a connection to the
              database server process (and initialise the
              <em>extra</em> instance variable if necessary),
              setting the <em>connected</em> instance variable
              to indicate the state of the object.
            </p>
            <p>
              This method must call
              <ref type="method" id="+purgeConnections:">
                +purgeConnections:
              </ref>
              to ensure that there is a free slot for the new
              connection.
            </p>
            <p>
              Application code must <em>not</em> call this
              method directly, it is for internal use only. The
              <ref type="method" id="-connect">
                -connect
              </ref>
              method calls this method if the <em>connected</em>
              instance variable is <code>NO</code>.
            </p>
          </desc>
        </method>
        <method type="void" override="subclass">
          <sel>backendDisconnect</sel>
          <desc>
            Disconnect from the database unless already
            disconnected. <br />
            <p>
              This method is called automatically when the
              receiver is deallocated or reconfigured, and may
              also be called automatically when there are too many
              database connections active.
            </p>
            <p>
              If the receiver is an instance of a subclass which
              uses the <em>extra</em> instance variable, it
              <strong>must</strong> clear that variable in the
              <ref type="method" id="-backendDisconnect">
                -backendDisconnect
              </ref>
              method, because a reconfiguration may cause the
              class of the receiver to change.
            </p>
            <p>
              This method must set the <em>connected</em> instance
              variable to <code>NO</code>.
            </p>
            <p>
              Application code must <em>not</em> call this
              method directly, it is for internal use only. The
              <ref type="method" id="-disconnect">
                -disconnect
              </ref>
              method calls this method if the <em>connected</em>
              instance variable is <code>YES</code>.
            </p>
          </desc>
        </method>
        <method type="void" override="subclass">
          <sel>backendExecute:</sel>
          <arg type="NSArray*">info</arg>
          <desc>
            Perform arbitrary operation
            <em>which does not return any value.</em> <br /> This
            method has a single argument, an array containing
            the string representing the statement to be executed as
            its first object, and an optional sequence of data
            objects following it. <br />
<example>
   [db backendExecute: [NSArray arrayWithObject:
     @"UPDATE MyTable SET Name = 'The name' WHERE ID = 123"]];
 </example>
            <p>
              The backend implementation is required to perform the
              SQL statement using the supplied NSData objects at
              the points in the statement marked by the
              <code>'?'''?'</code> sequence. The marker
              saequences are inserted into the statement at
              an earlier stage by the
              <ref type="method" id="-execute:,...">
                -execute:,...
              </ref>
              and
              <ref type="method" id="-execute:with:">
                -execute:with:
              </ref>
              methods.
            </p>
            <p>
              This method should lock the instance using the
              <em>lock</em> instance variable for the duration of
              the operation, and unlock it afterwards.
            </p>
            <p>
              NB. callers (other than the
              <ref type="method" id="-begin">
                -begin
              </ref>
              , <ref type="method" id="-commit">-commit</ref>, and
              <ref type="method" id="-rollback">
                -rollback
              </ref>
              methods) should not pass any statement to this
              method which would cause a transaction to begin or
              end.
            </p>
            <p>
              Application code must <em>not</em> call this
              method directly, it is for internal use only.
            </p>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>backendQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <desc>
            Calls
            <ref type="method" id="-backendQuery:recordType:listType:">-backendQuery:recordType:listType:</ref> with the default record class and array class.
          </desc>
        </method>
        <method type="NSMutableArray*" override="subclass">
          <sel>backendQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>recordType:</sel>
          <arg type="id">rtype</arg>
          <sel>listType:</sel>
          <arg type="id">ltype</arg>
          <desc>
            <p>
              Perform arbitrary query
              <em>which returns values.</em>
            </p>
<example>
   result = [db backendQuery: @"SELECT Name FROM Table"
                  recordType: [SQLRecord class]]
                    listType: [NSMutableArray class]];
 </example>
            <p>
              Upon error, an exception is raised.
            </p>
            <p>
              The query returns an array of records (each of which
              is represented by an SQLRecord object).
            </p>
            <p>
              Each SQLRecord object contains one or more fields,
              in the order in which they occurred in the query.
              Fields may also be retrieved by name.
            </p>
            <p>
              NULL field items are returned as NSNull objects.
            </p>
            <p>
              This method should lock the instance using the
              <em>lock</em> instance variable for the duration of
              the operation, and unlock it afterwards.
            </p>
            <p>
              Application code must <em>not</em> call this
              method directly, it is for internal use only.
            </p>
            <p>
              The <var>rtype</var> argument specifies an object to
              be used to create the records produced by the query.
              <br /> This is provided as a performance
              optimisation when you want to store data
              directly into a special class of your own.
              <br /> The object must respond to the [SQLRecord
              +newWithValues:keys:count:]
              method to produce a new record initialised with
              the supplied data.
            </p>
            <p>
              The <var>ltype</var> argument specifies an object to
              be used to create objects to store the records
              produced by the query. <br /> The should be a
              subclass of NSMutableArray. It must at least
              implement the
              <ref type="method" id="+alloc" class="NSObject">
                [NSObject +alloc]
              </ref>
              method to create an instnce to store records. The
              instance must implement
              <ref type="method" id="-initWithCapacity:" class="NSMutableArray">[NSMutableArray -initWithCapacity:]</ref> to initialise itsself and <ref type="method" id="-addObject:" class="NSMutableArray">[NSMutableArray -addObject:]</ref> to allow the backend to add records to it. <br /> For caching to work, it must be possible to make a mutable copy of the instance using the mutableCopy method.
            </p>
          </desc>
        </method>
        <method type="unsigned" override="subclass">
          <sel>copyEscapedBLOB:</sel>
          <arg type="NSData*">blob</arg>
          <sel>into:</sel>
          <arg type="void*">buf</arg>
          <desc>
            This method is <em>only</em> for the use of the
            <ref type="method" id="-insertBLOBs:intoStatement:length:withMarker:length:giving:">-insertBLOBs:intoStatement:length:withMarker:length:giving:</ref> method. <br /> Subclasses which need to insert binary data into a statement must implement this method to copy the escaped data into place and return the number of bytes actually copied.
          </desc>
        </method>
        <method type="const void*">
          <sel>insertBLOBs:</sel>
          <arg type="NSArray*">blobs</arg>
          <sel>intoStatement:</sel>
          <arg type="const void*">statement</arg>
          <sel>length:</sel>
          <arg type="unsigned">sLength</arg>
          <sel>withMarker:</sel>
          <arg type="const void*">marker</arg>
          <sel>length:</sel>
          <arg type="unsigned">mLength</arg>
          <sel>giving:</sel>
          <arg type="unsigned*">result</arg>
          <desc>
            <p>
              This method is a convenience method provided for
              subclasses which need to insert escaped binary
              data into an SQL <var>statement</var> before sending
              the <var>statement</var> to a backend server process.
              This method makes use of the
              <ref type="method" id="-copyEscapedBLOB:into:">
                -copyEscapedBLOB:into:
              </ref>
              and
              <ref type="method" id="-lengthOfEscapedBLOB:">
                -lengthOfEscapedBLOB:
              </ref>
              methods, which <em>must</em> be implemented by
              the subclass.
            </p>
            <p>
              The <var>blobs</var> array is an array containing the
              original SQL <var>statement</var> string (unused
              by this method) followed by the data items to be
              inserted.
            </p>
            <p>
              The <var>statement</var> and <var>sLength</var>
              arguments specify the datastream to be copied
              and into which the BLOBs are to be inserted.
            </p>
            <p>
              The <var>marker</var> and <var>mLength</var>
              arguments specify the sequence of
              <var>marker</var> bytes in the <var>statement</var>
              which indicate a position for insertion of an
              escaped BLOB.
            </p>
            <p>
              The method returns either the original
              <var>statement</var> or a copy containing the
              escaped BLOBs. The length of the returned data is
              stored in <var>result</var>.
            </p>
          </desc>
        </method>
        <method type="unsigned" override="subclass">
          <sel>lengthOfEscapedBLOB:</sel>
          <arg type="NSData*">blob</arg>
          <desc>
            This method is <em>only</em> for the use of the
            <ref type="method" id="-insertBLOBs:intoStatement:length:withMarker:length:giving:">-insertBLOBs:intoStatement:length:withMarker:length:giving:</ref> method. <br /> Subclasses which need to insert binary data into a statement must implement this method to return the length of the escaped bytestream which will be inserted.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>SQLClient constants</heading>
      <p></p>
      <constant type="NSString* const" name="SQLClientDidConnectNotification">
        <desc>
          Notification sent when an instance becomes
          connected to the database server. The notification
          object is the instance connected.
        </desc>
      </constant>
      <constant type="NSString* const" name="SQLClientDidDisconnectNotification">
        <desc>
          Notification sent when an instance becomes
          disconnected from the database server. The
          notification object is the instance
          disconnected.
        </desc>
      </constant>
    </chapter>
    <chapter>
      <heading>SQLClient variables</heading>
      <p></p>
      <variable type="NSString*" name="SQLConnectionException">
        <desc>
          Exception for when a connection to the server is
          lost.
        </desc>
      </variable>
      <variable type="NSString*" name="SQLEmptyException">
        <desc>
          Exception for when a query is supposed to return
          data and doesn't.
        </desc>
      </variable>
      <variable type="NSString*" name="SQLException">
        <desc>
          Exception raised when an error with the remote
          database server occurs.
        </desc>
      </variable>
      <variable type="NSString*" name="SQLUniqueException">
        <desc>
          Exception for when an insert/update would break the
          uniqueness of a field or index.
        </desc>
      </variable>
    </chapter>
    <chapter>
      <heading>SQLClient functions</heading>
      <p></p>
      <function type="NSTimeInterval" name="SQLClientTimeLast">
        <desc>
          Returns the timestamp of the most recent call to
          <ref type="function" id="SQLClientTimeNow">
            SQLClientTimeNow()
          </ref>
          .
        </desc>
      </function>
      <function type="NSTimeInterval" name="SQLClientTimeNow">
        <desc>
          Convenience function to provide timing
          information quickly. <br /> This returns the
          current date/time, and stores the value for use by
          the
          <ref type="function" id="SQLClientTimeLast">
            SQLClientTimeLast()
          </ref>
          function.
        </desc>
      </function>
      <function type="NSTimeInterval" name="SQLClientTimeStart">
        <desc>
          This returns the timestamp from which any of the
          SQLClient classes was first used or
          <ref type="function" id="SQLClientTimeNow">
            SQLClientTimeNow()
          </ref>
          was first called (whichever came first).
        </desc>
      </function>
      <function type="unsigned int" name="SQLClientTimeTick">
        <desc>
          A convenience method to return the current clock 'tick'...
          which is the current second based on the time we
          started. This does <em>not</em> check the current
          time, but relies on
          <ref type="function" id="SQLClientTimeLast">
            SQLClientTimeLast()
          </ref>
          returning an up to date value (so if you need an
          accurate tick, you should ensure that
          <ref type="function" id="SQLClientTimeNow">
            SQLClientTimeNow()
          </ref>
          is called at least once a second). <br /> The returned
          value is always greater than zero, and is basically
          calculated as (SQLClientTimeLast() -
          <ref type="function" id="SQLClientTimeStart">
            SQLClientTimeStart()
          </ref>
          + 1). <br /> In the event that the system clock is reset
          into the past, the value of
          <ref type="function" id="SQLClientTimeStart">
            SQLClientTimeStart()
          </ref>
          is automatically adjusted to ensure that the result of a
          call to
          <ref type="function" id="SQLClientTimeTick">
            SQLClientTimeTick()
          </ref>
          is never less than the result of any earlier call to the
          function.
        </desc>
      </function>
    </chapter>
  </body>
</gsdoc>
