<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.4//EN" "http://www.gnustep.org/gsdoc-1_0_4.dtd">
<gsdoc base="SQLClient">
  <head>
    <title>SQLClient documentation</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org">
        rfm@gnu.org
      </email>
    </author>
    <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 ([SQLTransaction])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="uint64_t" name="_committed" validity="protected">
          <desc>
            Count of committed transactions <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>
            Duration logging threshold <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="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="_lastConnect" validity="protected">
          <desc>
            Last successful connect <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 completion 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:" class="SQLClient(Caching)">[SQLClient(Caching) -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="NSTimeInterval" name="_lastStart" validity="protected">
          <desc>
            Last op start or connect <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="NSCountedSet*" name="_names" validity="protected">
          <desc>
            Track notification names <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="NSMapTable*" name="_observers" validity="protected">
          <desc>
            Observations of async events <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="SQLClientPool*" name="_pool" validity="protected">
          <desc>
            The pool of the client (or <code>nil</code>) <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="_shouldTrim" validity="protected">
          <desc>
            A flag indicating whether leading and trailing white
            space in values read from the database should
            automatically be removed. <br /> This should
            only be modified by the
            <ref type="method" id="-setShouldTrim:">
              -setShouldTrim:
            </ref>
            method. <br /> Should whitespace be trimmed? <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>
            Returns the maximum number of simultaneous database
            connections permitted (set by
            <ref type="method" id="+setMaxConnections:">
              +setMaxConnections:
            </ref>
            and defaults to 8) for connections outside of
            SQLClientPool instances.
          </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>
            <p>
              Purging does not apply to connections made by
              SQLClientPool instances.
            </p>
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setAbandonFailedConnectionsAfter:</sel>
          <arg type="NSTimeInterval">delay</arg>
          <desc>
            Sets the retry period after which connection attempts
            are abandoned. a <var>delay</var> less than or equal to
            zero means that connection attempts are abandoned
            after the first failure (the
            <ref type="method" id="-connect">
              -connect
            </ref>
            method behaves the same way as the
            <ref type="method" id="-tryConnect">
              -tryConnect
            </ref>
            method).
          </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>
            <p>
              Connections used by SQLClientPool instances
              are not considered by this maximum.
            </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="SQLLiteral*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <p>
              Build an sql query string using the supplied
              arguments to call
              <ref type="method" id="-prepare:args:" class="SQLClient">[SQLClient -prepare:args:]</ref> to build a query and raises an exception if the result is not a simple query string.
            </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 />
              Arguments in the list are automatically quoted
              as necessary, with the behavior for string arguments
              being controlled by the autoquote setting.
            </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:" class="SQLClient(Caching)">[SQLClient(Caching) -cache:simpleQuery:recordType:listType:]</ref> methods.
            </p>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            <p>
              Build an sql query string using the supplied
              arguments to call
              <ref type="method" id="-prepare:with:" class="SQLClient">[SQLClient -prepare:with:]</ref> to build a query and raises an exception if the result is not a simple query string. <br /> 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.
            </p>
<example>
   sql = [db buildQuery: @"SELECT Name FROM {Table} WHERE ID = {ID}"
                   with: values];
 </example>
            <p>
              Arguments in the dictionary are automatically
              quoted as necessary, with the behavior for string
              arguments being controlled by the autoquote
              setting. <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:" class="SQLClient(Caching)">[SQLClient(Caching) -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="uint64_t">
          <sel>committed</sel>
          <desc>
            Returns the number of committed transactions.
          </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. <br /> If the
            connection attempt fails it is repeated until it
            succeds or until the time interval specified by
            <ref type="method" id="+setAbandonFailedConnectionsAfter:">+setAbandonFailedConnectionsAfter:</ref> has passed.
          </desc>
        </method>
        <method type="BOOL">
          <sel>connected</sel>
          <desc>
            Return a flag to say whether a connection to the
            database server is currently live (the value of
            the 'connected' instance variable). <br /> This is
            mostly useful for debug/reporting.
          </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="NSInteger">
          <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 /> Arguments in the list are
            automatically quoted as necessary, with the
            behavior for string arguments being controlled by
            the autoquote setting.
<example>
   [db execute: @"UPDATE ", table, @" SET Name = ",
     myName, " WHERE ID = ", myId, nil];
 </example>
            Where the database backend support it, this method
            returns the count of the number of rows to which
            the operation applied. Otherwise this returns -1.
          </desc>
        </method>
        <method type="NSInteger">
          <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>
            Arguments in the dictionary are automatically
            quoted as necessary, with the behavior for string
            arguments being controlled by the autoquote
            setting. <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. <br /> Where the
            database backend support it, this method returns
            the count of the number of rows to which the operation
            applied. Otherwise this returns -1.
          </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>
            Calls
            <ref type="method" id="-initWithConfiguration:name:pool:">
              -initWithConfiguration:name:pool:
            </ref>
            passing <code>NO</code> to say the client is not in
            a pool.
          </desc>
        </method>
        <method type="id">
          <sel>initWithConfiguration:</sel>
          <arg type="NSDictionary*">config</arg>
          <sel>name:</sel>
          <arg type="NSString*">reference</arg>
          <sel>pool:</sel>
          <arg type="SQLClientPool*">pool</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 <var>pool</var> is <code>nil</code> and 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 which is not in a
            <var>pool</var>. <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 /> 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 /> The
            database name may be of the format
            'name@host:port' when you wish to connect
            to a database on a different host over the network.
          </desc>
        </method>
        <method type="BOOL">
          <sel>isEqual:</sel>
          <arg type="id">other</arg>
          <desc>
            Two clients are considered equal if they refer to the
            same database and are logged in as the same database
            user using the same protocol. These are the general
            criteria for transactions to be compatoible so
            that an SQLTransaction object generated by one client
            can be used by the <var>other</var>.
          </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>lastConnect</sel>
          <desc>
            Returns the date/time stamp of the last database
            connection established by the receiver, or
            <code>nil</code> if no connection has ever been
            established.
          </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="BOOL">
          <sel>lockBeforeDate:</sel>
          <arg type="NSDate*">limit</arg>
          <desc>
            This grabs the receiver for use by the current thread.
            <br /> If <var>limit</var> is <code>nil</code> or in
            the past, makes a single immediate attempt. <br />
            Returns <code>NO</code> if it fails to obtain a
            lock by the specified date. <br /> Must be matched by
            an <ref type="method" id="-unlock">-unlock</ref> if it
            succeeds.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>longestIdle:</sel>
          <arg type="SQLClient*">other</arg>
          <desc>
            Compares the receiver with the <var>other</var>
            client to see which one has been inactive but
            connected for longest (if they are connected) and
            returns that instance. <br /> If neither is idle
            but connected, the method returns <code>nil</code>.
            <br /> In a tie, the method returns the
            <var>other</var> instance.
          </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="SQLClientPool*">
          <sel>pool</sel>
          <desc>
            Return the pool to which the receiver belongs, or
            <code>nil</code> if it is not part of a connection
            pool.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            Calls
            <ref type="method" id="-prepare:args:" class="SQLClient">
              [SQLClient -prepare:args:]
            </ref>
            where the argument list needs to be a
            <code>nil</code> terminated list of objects.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>args:</sel>
          <arg type="va_list">args</arg>
          <desc>
            This is the method used to convert a query or
            statement to a standard form used internally by
            other methods. <br /> This works to build an sql
            string by quoting any non-literal objects according
            to the autoquote setting, and concatenating the
            resulting strings in a <code>nil</code>
            terminated list. <br /> Returns an array
            containing the statement as the first object and
            any NSData objects following. The NSData objects appear
            in the statement strings as the marker sequence -
            <code>'?'''?'</code> <br /> If the returned array
            contains a single object, that object is a simple
            SQL query/statement.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            This method is like
            <ref type="method" id="-prepare:args:" class="SQLClient">
              [SQLClient -prepare:args:]
            </ref>
            but takes a dictionary of <var>values</var> to be
            substituted into the sql string.
          </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>
              Timestamp field items (a date and time) are
              returned as NSDate objects. If the database
              contains no timezone information, the local
              timezone is used.
            </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="SQLLiteral*">
          <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 />
            Subclasses may override this method to provide
            appropriate quoting for types of object which
            need database backend specific quoting conventions.
            However, the default implementation should be OK
            for most cases: <br /> This method makes use of
            <ref type="method" id="-quoteString:">
              -quoteString:
            </ref>
            to quote strings. <br /> It formats NSDate objects as
            YYYY-MM-DD hh:mm:ss.mmm ?ZZZZ. <br /> For
            NSNumber objects it simply uses their string
            descriptions. <br /> For NSNull and
            <code>nil</code> the method returns NULL. <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 /> NSArray and NSSet objects
            are quoted as sets containing the quoted elements from
            the collection. If you want to use SQL arrays (and your
            database backend supports it) you must explicitly
            use the
            <ref type="method" id="-quoteArray:">
              -quoteArray:
            </ref>
            method to convert an NSArray to a literal database
            array representation. <br /> Other classes are not
            supported unless they implement the
            <ref type="method" id="-quoteForSQLClient:">
              -quoteForSQLClient:
            </ref>
            method to return a non-nil literal string value.
            <br /> Attempts to quote an object of an unsupported
            class (one where the method returns <code>nil</code>)
            will cause an NSInvalidArgumentException.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteArray:</sel>
          <arg type="NSArray*">a</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableString*">
          <sel>quoteArray:</sel>
          <arg type="NSArray*">a</arg>
          <sel>toString:</sel>
          <arg type="NSMutableString*">s</arg>
          <sel>quotingStrings:</sel>
          <arg type="BOOL">q</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteArraySafe:</sel>
          <arg type="NSArray*">a</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <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="SQLLiteral*">
          <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="SQLLiteral*">
          <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="SQLLiteral*">
          <sel>quoteFloat:</sel>
          <arg type="double">f</arg>
          <desc>
            Convert a <strong>float</strong> to a string
            suitable for use in an SQL query.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <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="SQLLiteral*">
          <sel>quoteName:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Convert a string to a form suitable for use as a
            case sensitive table or column name in an SQL query.
            This uses the <strong>double</strong> quotes character
            rather than single quotes. <br />
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteSet:</sel>
          <arg type="id">obj</arg>
          <desc>
            Quotes the values in any collection (responds to
            -objectEnumerator) as a set (bracketed
            list of values) for use in an SQL query.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <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="SQLLiteral*">
          <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>setClientName:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the client name for this client. <br /> If this is
            not set (or is set to nul) a globally unique string is
            used. <br /> NB. Setting the name may not be
            reflected in the database server until the client
            disconnects and reconnects.
          </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>setOptions:</sel>
          <arg type="NSDictionary*">o</arg>
          <desc>
            Sets any backend specific parameters for the database
            connection. The base class implementation does
            nothing; subclasses are expected to store any
            optional configuration information that they wish
            to use themselves. <br /> This is called automatically
            to configure the connection... you normally shouldn't
            need to call it yourself.
          </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>setShouldTrim:</sel>
          <arg type="BOOL">aFlag</arg>
          <desc>
            Sets an internal flag to indicate whether leading and
            trailing white space characters should be removed
            from values retrieved from the database by the
            receiver.
          </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="NSInteger">
          <sel>simpleExecute:</sel>
          <arg type="id">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. <br /> Returns the result of the
            <ref type="method" id="-backendExecute:">
              -backendExecute:
            </ref>
            method call. <br /> Accepts a mutable array argument
            (as produced by the prepare methods) or a simple SQL
            statement (a string), otherwise raises an
            exception.
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>simpleQuery:</sel>
          <arg type="SQLLitArg*">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="SQLLitArg*">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 /> This library provides a few
                helper classes to provide alternative values for
                <var>rtype</var> and <var>ltype</var>.
          </desc>
        </method>
        <method type="BOOL">
          <sel>tryConnect</sel>
          <desc>
            If there is no database connection, attempts to
            establish one. <br /> This does not do automatic
            retries on connection failure. <br /> Returns the
            current connection status.
          </desc>
        </method>
        <method type="void">
          <sel>unlock</sel>
          <desc>
            Releases a lock previously obtained using
            <ref type="method" id="-lockBeforeDate:">
              -lockBeforeDate:
            </ref>
          </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 SQLClientPool class
      </heading>
      <class name="SQLClientPool" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          <p>
            An SQLClientPool instance may be used to create/control
            a pool of client objects. Code may obtain autoreleased
            proxies to the clients from the pool and use them
            safe in the knowledge that they won't be used anywhere
            else... as soon as the client would be deallocated, it
            is returned to the pool.
          </p>
          <p>
            All clients in the pool share the same cache object, so
            query results cached by one client will be available
            to other clients in the pool.
          </p>
          <p>
            As a convenience, an SQLClientPool instance acts as a
            proxy for the clients it contains, so you may (where
            it makes sense) send the same messages to a pool that
            you would send to an individual client, and the pool
            will temporarily allocate one of its clients to handle
            it. <br /> In this case the client will be returned to
            the pool immediately after the message has been handled
            (and subsequent messages may go to a different
            client), so you can't change settings or send any
            other method which would be required to be followed
            up by another message to the same client.
          </p>
          <p>
            NB. Any client provided from a pool should be returned
            to the pool as soon as reasonably possible (and if left
            idle will have its connection to the server closed
            anyway) so that it can be used by other threads. If
            you want a permenantly open database connection you
            should use a normal SQLClient instance, not one from
            a pool. You must not call
            <ref type="method" id="-addObserver:selector:name:">
              -addObserver:selector:name:
            </ref>
            on a client from a pool.
          </p>
        </desc>
        <ivariable type="NSDictionary*" name="_config" validity="protected">
          <desc>
            The pool configuration object <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="_delayWaits" validity="protected">
          <desc>
            Time waiting for provisions <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="uint64_t" name="_delayed" validity="protected">
          <desc>
            Count of delayed provisions <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>
            Duration logging threshold <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="_failWaits" validity="protected">
          <desc>
            Time waiting for timewouts <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="uint64_t" name="_failed" validity="protected">
          <desc>
            Count of timed out provisions <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="uint64_t" name="_immediate" validity="protected">
          <desc>
            Immediate client provisions <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="SQLClientPoolItem*" name="_items" validity="protected">
          <desc>
            The items in the pool <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="NSConditionLock*" name="_lock" validity="protected">
          <desc>
            Controls access to items <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="_longest" validity="protected">
          <desc>
            Count of longest delay <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="int" name="_max" validity="protected">
          <desc>
            Maximum connection count <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="int" name="_min" validity="protected">
          <desc>
            Minimum connection count <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>
            The pool configuration name <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="_purgeAll" validity="protected">
          <desc>
            Age to purge all connections <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="_purgeMin" validity="protected">
          <desc>
            Age to purge excess connections <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>
        <method type="int">
          <sel>availableConnections</sel>
          <desc>
            Returns the count of currently available
            connections in the pool.
          </desc>
        </method>
        <method type="SQLTransaction*">
          <sel>batch:</sel>
          <arg type="BOOL">stopOnFailure</arg>
          <desc>
            Creates and returns an autoreleased SQLTransaction
            instance which will use the receiver as the
            database connection to perform transactions.
          </desc>
        </method>
        <method type="GSCache*">
          <sel>cache</sel>
          <desc>
            Returns the cache used by clients in the pool for
            storing the results of requests made through them.
            Creates a new cache if necessary.
          </desc>
        </method>
        <method type="uint64_t">
          <sel>committed</sel>
          <desc>
            Returns the number of committed transactions.
          </desc>
        </method>
        <method type="id">
          <sel>initWithConfiguration:</sel>
          <arg type="NSDictionary*">config</arg>
          <sel>name:</sel>
          <arg type="NSString*">reference</arg>
          <sel>max:</sel>
          <arg type="int">maxConnections</arg>
          <sel>min:</sel>
          <arg type="int">minConnections</arg>
          <desc>
            Creates a pool of clients using a single client
            configuration. <br /> Calls
            <ref type="method" id="-initWithConfiguration:name:pool:">
              -initWithConfiguration:name:pool:
            </ref>
            (passing <code>NO</code> to say the client is not
            in a pool) to create each client. <br /> The value of
            <var>maxConnections</var> is the size of the pool (ie
            the number of clients created) and thus the maximum
            number of concurrent connections to the database
            server. <br /> The value of
            <var>minConnections</var> is the minimum number of
            connected clients normally expected to be in the
            pool. The pool tries to ensure that it doesn't
            contain more than this number of idle connected
            clients.
          </desc>
        </method>
        <method type="NSString*">
          <sel>longDescription</sel>
          <desc>
            Returns a <strong>long</strong> description of the
            pool including statistics, status, and the description
            of a sample client.
          </desc>
        </method>
        <method type="int">
          <sel>maxConnections</sel>
          <desc>
            Return the maximum number of database connections in
            the pool.
          </desc>
        </method>
        <method type="int">
          <sel>minConnections</sel>
          <desc>
            Return the minimum number of database connections in
            the pool.
          </desc>
        </method>
        <method type="NSString*">
          <sel>name</sel>
          <desc>
            Returns the name of the database configuration for
            the connections in the pool.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>provideClient</sel>
          <desc>
            Fetches an (autoreleased) client from the pool.
            <br /> This method blocks indefinitely waiting for a
            client to become available in the pool. <br /> Calls
            <ref type="method" id="-provideClientBeforeDate:exclusive:">-provideClientBeforeDate:exclusive:</ref> for a date in the distant future and for a non-exclusive client.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>provideClientBeforeDate:</sel>
          <arg type="NSDate*">when</arg>
          <desc>
            Fetches an (autoreleased) client from the pool.
            <br /> Calls
            <ref type="method" id="-provideClientBeforeDate:exclusive:">-provideClientBeforeDate:exclusive:</ref> for a non-exclusive client.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>provideClientBeforeDate:</sel>
          <arg type="NSDate*">when</arg>
          <sel>exclusive:</sel>
          <arg type="BOOL">isLocal</arg>
          <desc>
            Fetches an (autoreleased) client from the pool.
            <br /> If no client is or becomes available before
            the specified date then the method returns
            <code>nil</code>. <br /> If <var>when</var> is
            <code>nil</code> then a date in the distant future
            is used so that the method will effectively wait forever
            to get a client. <br /> If <var>isLocal</var> is
            <code>YES</code>, this method provides a client
            which will not be used elsewhere in the same thread
            until/unless the calling code returns it to
            the pool. Otherwise (<var>isLocal</var> is
            <code>NO</code>), the client may be used by other
            code in the same thread. <br /> NB. Any client
            provided using this method should be returned to
            the pool as soon as reasonably possible (and if left
            idle will have its connection to the server closed
            anyway) so that it can be used by other threads. If
            you want a permenantly open database connection you
            should use a normal SQLClient instance, not one from
            a pool.
          </desc>
        </method>
        <method type="SQLClient*">
          <sel>provideClientExclusive</sel>
          <desc>
            Fetches an (autoreleased) client from the pool.
            <br /> This method blocks indefinitely waiting for a
            client to become available in the pool. <br /> Calls
            <ref type="method" id="-provideClientBeforeDate:exclusive:">-provideClientBeforeDate:exclusive:</ref> for a date in the distant future and for an exclusive client.
          </desc>
        </method>
        <method type="void">
          <sel>purge</sel>
          <desc>
            Disconnects the least recently active unused
            database clients in the pool, but only while there
            are more than the minimum number of clients currently
            connected to the database, and only if the client
            has been idle for at least ten seconds.
          </desc>
        </method>
        <method type="void">
          <sel>setCache:</sel>
          <arg type="GSCache*">aCache</arg>
          <desc>
            Sets the cache for all the clients in the pool.
          </desc>
        </method>
        <method type="void">
          <sel>setCacheThread:</sel>
          <arg type="NSThread*">aThread</arg>
          <desc>
            Sets the cache thread for all the clients in the pool.
          </desc>
        </method>
        <method type="void">
          <sel>setClientName:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            Set the client name for all the client connections in
            the pool. <br /> If the argument is not
            <code>nil</code>, the name of each client in the
            pool is set to the argument with a suffix of '(x)'
            where x is the number of the client within the pool,
            otherwise (<code>nil</code> argument) each client
            is allocated a globally unique string as its name.
            <br /> NB. This setting does not apply to new
            connections added when the pool maximum size is
            increased.
          </desc>
        </method>
        <method type="void">
          <sel>setDebugging:</sel>
          <arg type="unsigned int">level</arg>
          <desc>
            Set the debugging <var>level</var> for all clients in
            the pool.
          </desc>
        </method>
        <method type="void">
          <sel>setDurationLogging:</sel>
          <arg type="NSTimeInterval">threshold</arg>
          <desc>
            Set the duration logging <var>threshold</var> for all
            clients in the pool.
          </desc>
        </method>
        <method type="void">
          <sel>setMax:</sel>
          <arg type="int">maxConnections</arg>
          <sel>min:</sel>
          <arg type="int">minConnections</arg>
          <desc>
            Sets the pool size limits (number of connections we
            try to maintain). <br /> The value of
            <var>maxConnections</var> is the size of the pool (ie
            the number of clients created) and thus the maximum
            number of concurrent connections to the database
            server. <br /> The value of
            <var>minConnections</var> is the minimum number of
            connected clients normally expected to be in the
            pool. The pool tries to ensure that it contains at
            least this number of connected clients. <br /> The
            value of <var>maxConnections</var> must be greater
            than or equal to that of <var>minConnections</var> and
            may not be greater than 100. The value of
            <var>minConnections</var> must be less than or equal
            to that of <var>maxConnections</var> and may not be less
            than 1.
          </desc>
        </method>
        <method type="void">
          <sel>setPurgeAll:</sel>
          <arg type="int">allSeconds</arg>
          <sel>min:</sel>
          <arg type="int">minSeconds</arg>
          <desc>
            Sets the ages (in seconds) after which idle
            connections are closed in the
            <ref type="method" id="-purge">
              -purge
            </ref>
            method. Where there are excess connections (more
            than the minimum configured connection count) in the
            pool, <var>minSeconds</var> is used, otherwise
            <var>allSeconds</var> is used.
          </desc>
        </method>
        <method type="NSString*">
          <sel>statistics</sel>
          <desc>
            Returns a string describing the usage of the pool.
          </desc>
        </method>
        <method type="NSString*">
          <sel>status</sel>
          <desc>
            Returns a string describing the status of the pool.
          </desc>
        </method>
        <method type="BOOL">
          <sel>swallowClient:</sel>
          <arg type="SQLClient*">client</arg>
          <desc>
            Puts the <var>client</var> back in the pool. This
            happens automatically when a <var>client</var> from
            a pool would normally be deallocated so you don't
            generally need to do it. <br /> Returns
            <code>YES</code> if the supplied <var>client</var>
            was from the pool, <code>NO</code> otherwise.
          </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>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLDictionaryBuilder
        class
      </heading>
      <class name="SQLDictionaryBuilder" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <ivariable type="NSMutableDictionary*" name="content" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <method type="void">
          <sel>addObject:</sel>
          <arg type="id">anObject</arg>
          <desc>
            No need to do anything... the object will already have
            been added by the
            <ref type="method" id="-newWithValues:keys:count:">
              -newWithValues:keys:count:
            </ref>
            method.
          </desc>
        </method>
        <method type="id">
          <sel>alloc</sel>
          <desc>
            When a container is supposed to be allocated, we just
            return the receiver (which will then quietly ignore
            <ref type="method" id="-addObject:">
              -addObject:
            </ref>
            messages).
          </desc>
        </method>
        <method type="NSMutableDictionary*">
          <sel>content</sel>
          <desc>
            Returns the content dictionary for the receiver.
          </desc>
        </method>
        <method type="id">
          <sel>initWithCapacity:</sel>
          <arg type="NSUInteger">capacity</arg>
          <desc>
            Creates a new content dictionary... this method
            will be called automatically by the SQLClient object
            when it performs a query, so there is no need to call
            it at any other time.
          </desc>
        </method>
        <method type="id">
          <sel>mutableCopyWithZone:</sel>
          <arg type="NSZone*">aZone</arg>
          <desc>
            Makes a mutable copy of the content dictionary
            (called when a caching query uses this helper to
            produce the cached collection).
          </desc>
        </method>
        <method type="id">
          <sel>newWithValues:</sel>
          <arg type="id*">values</arg>
          <sel>keys:</sel>
          <arg type="NSString**">keys</arg>
          <sel>count:</sel>
          <arg type="unsigned int">count</arg>
          <desc>
            This is the main workhorse of the class... it is
            called once for every record read from the database,
            and is responsible for adding that record to the
            content dictionary. The default implementation,
            instead of creating an object to hold the supplied
            record data, uses the two fields from the record as
            a key-value pair to add to the content dictionary, and
            returns <code>nil</code> as the record object. It's
            OK to return a <code>nil</code> object since we ignore
            the
            <ref type="method" id="-addObject:">
              -addObject:
            </ref>
            argument.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLLiteral class
      </heading>
      <class name="SQLLiteral" super="NSString">
        <declared>SQLClient.h</declared>
        <desc>
          The SQLLiteral subclass of NSString is used to tell
          <ref type="method" id="-prepare:args:" class="SQLClient">
            [SQLClient -prepare:args:]
          </ref>
          and
          <ref type="method" id="-prepare:with:" class="SQLClient">
            [SQLClient -prepare:with:]
          </ref>
          methods that a string is to be treated as a literal
          which should not be quoted when it is used as part of
          an SQL query or statement. <br /> You should enable
          compile time checking of string types by defining the
          SQLCLIENT_COMPILE_TIME_QUOTE_CHECK
          preprocessor macro before including this header.
          When compile time checking is in place, the methods
          which expect a query or statement to be provided as a
          single string will be declared as taking an SQLLiteral
          argument rather than an NSString. The compiler will
          then complain about passing arguments of the wrong type.
          <br /> NB. The runtime checking for literal strings
          actually uses different classes not the SQLLiteral
          class. In fact this class declaration is only used for
          compile time checking and you should not expect
          runtime checks to actually ever see an instance of
          this class.
        </desc>
      </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="SQLRecordKeys*">k</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 /> This
            constructor will be used for subsequent records
            after the first in a query iff the first record
            created returns a non-nil result when sent the
            <ref type="method" id="-keys">
              -keys
            </ref>
            method.
          </desc>
        </method>
        <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="NSUInteger">
          <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="NSUInteger">index</arg>
          <desc>
            Returns the key at the specified <var>index</var>.
            <br />
          </desc>
        </method>
        <method type="SQLRecordKeys*">
          <sel>keys</sel>
          <desc>
            Returns the keys used by this record. The abstract
            class returns <code>nil</code>, so subclasses should
            override if they wish to make use of the
            <ref type="method" id="+newWithValues:keys:">
              +newWithValues:keys:
            </ref>
            method.
          </desc>
        </method>
        <method type="id" override="subclass">
          <sel>objectAtIndex:</sel>
          <arg type="NSUInteger">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="NSUInteger">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="NSUInteger">
          <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 SQLRecordKeys class
      </heading>
      <class name="SQLRecordKeys" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          This class is used to hold key information for a set of
          SQLRecord objects produced by a single query.
        </desc>
        <ivariable type="NSUInteger" name="bytes" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <ivariable type="NSUInteger" name="count" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <ivariable type="NSMapTable*" name="low" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <ivariable type="NSMapTable*" name="map" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <ivariable type="NSArray*" name="order" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <method type="NSUInteger">
          <sel>count</sel>
          <desc>
            Returns the number of keys in the receiver.
          </desc>
        </method>
        <method type="NSUInteger">
          <sel>indexForKey:</sel>
          <arg type="NSString*">key</arg>
          <desc>
            Returns the index of the object with the specified
            <var>key</var>, or NSNotFound if there is no such
            <var>key</var>.
          </desc>
        </method>
        <method type="id">
          <sel>initWithKeys:</sel>
          <arg type="NSString**">keys</arg>
          <sel>count:</sel>
          <arg type="NSUInteger">c</arg>
          <desc>
            Initialiser
          </desc>
        </method>
        <method type="NSArray*">
          <sel>order</sel>
          <desc>
            Returns an array containing the record field names
            in order.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLSetBuilder class
      </heading>
      <class name="SQLSetBuilder" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <ivariable type="NSUInteger" name="added" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <ivariable type="NSCountedSet*" name="content" validity="protected">
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </ivariable>
        <method type="void">
          <sel>addObject:</sel>
          <arg type="id">anObject</arg>
          <desc>
            No need to do anything... the object will already have
            been added by the
            <ref type="method" id="-newWithValues:keys:count:">
              -newWithValues:keys:count:
            </ref>
            method.
          </desc>
        </method>
        <method type="NSUInteger">
          <sel>added</sel>
          <desc>
            Returns the number of objects actually added to the
            counted set.
          </desc>
        </method>
        <method type="id">
          <sel>alloc</sel>
          <desc>
            When a container is supposed to be allocated, we just
            return the receiver (which will then quietly ignore
            <ref type="method" id="-addObject:">
              -addObject:
            </ref>
            messages).
          </desc>
        </method>
        <method type="NSCountedSet*">
          <sel>content</sel>
          <desc>
            Returns the counted set for the receiver.
          </desc>
        </method>
        <method type="id">
          <sel>initWithCapacity:</sel>
          <arg type="NSUInteger">capacity</arg>
          <desc>
            Creates a new content set... this method will be
            called automatically by the SQLClient object when it
            performs a query, so there is no need to call it
            at any other time.
          </desc>
        </method>
        <method type="id">
          <sel>mutableCopyWithZone:</sel>
          <arg type="NSZone*">aZone</arg>
          <desc>
            Makes a mutable copy of the content dictionary
            (called when a caching query uses this helper to
            produce the cached collection).
          </desc>
        </method>
        <method type="id">
          <sel>newWithValues:</sel>
          <arg type="id*">values</arg>
          <sel>keys:</sel>
          <arg type="NSString**">keys</arg>
          <sel>count:</sel>
          <arg type="unsigned int">count</arg>
          <desc>
            This is the main workhorse of the class... it is
            called once for every record read from the database,
            and is responsible for adding that record to the
            content set. The default implementation, instead of
            creating an object to hold the supplied record
            data, uses the singe field from the record to add to
            the content set, and returns <code>nil</code> as the
            record object. It's OK to return a <code>nil</code>
            object since we ignore the
            <ref type="method" id="-addObject:">
              -addObject:
            </ref>
            argument.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLSingletonBuilder
        class
      </heading>
      <class name="SQLSingletonBuilder" super="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          <em>Description forthcoming.</em>
        </desc>
        <method type="id">
          <sel>newWithValues:</sel>
          <arg type="id*">values</arg>
          <sel>keys:</sel>
          <arg type="NSString**">keys</arg>
          <sel>count:</sel>
          <arg type="unsigned int">count</arg>
          <desc>
            <em>Description forthcoming.</em>
          </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(Convenience)">[SQLClient(Convenience) -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.
        </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="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="NSRecursiveLock*" name="_lock" 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="id" name="_owner" 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="_reset" 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>addPrepared:</sel>
          <arg type="NSArray*">statement</arg>
          <desc>
            Adds a prepared <var>statement</var>.
          </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/SQLClientPool 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="NSUInteger">
          <sel>count</sel>
          <desc>
            Returns the number of individual statements and/or
            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="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(Convenience)">[SQLClient(Convenience) -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(Convenience)">[SQLClient(Convenience) -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(Logging)">[SQLClient(Logging) -debug:,...]</ref> method, even if debug logging is not enabled with <ref type="method" id="-setDebugging:" class="SQLClient(Logging)">[SQLClient(Logging) -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/pool as the receiver.
          </desc>
        </method>
        <method type="void">
          <sel>lock</sel>
          <desc>
            Explicitly obtains the transaction lock so that
            multiple methods may be called without another
            thread interfering. Each call to this method must be
            matched by a call to the
            <ref type="method" id="-unlock">
              -unlock
            </ref>
            method.
          </desc>
        </method>
        <method type="id">
          <sel>owner</sel>
          <desc>
            Returns the database client with which this
            instance operates. <br /> This client is retained
            by the transaction. <br /> If the transaction was
            created by/for an SQLClientPool, this method
            returns that pool rather than an individual client.
          </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. See also the
            <ref type="method" id="-setResetOnExecute:">
              -setResetOnExecute:
            </ref>
            method.
          </desc>
        </method>
        <method type="BOOL">
          <sel>setResetOnExecute:</sel>
          <arg type="BOOL">aFlag</arg>
          <desc>
            Configures the transaction to be reset
            automatically whenever it is successfully
            executed. Normally transaction execution leaves
            all the statements in the transaction after execution.
            <br /> Returns the previous setting.
          </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>
        <method type="void">
          <sel>unlock</sel>
          <desc>
            Explicitly unlocks the thransaction. This should
            only be called by code which has previously called the
            <ref type="method" id="-lock">
              -lock
            </ref>
            method.
          </desc>
        </method>
      </class>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the NSObject(SQLClient)
        category
      </heading>
      <category name="SQLClient" class="NSObject">
        <declared>SQLClient.h</declared>
        <desc>
          This category is to extend NSObject with SQL oriented
          helper methods.
        </desc>
        <method type="BOOL">
          <sel>isNull</sel>
          <desc>
            Trivial method to test a field in a record returned
            from the database to see if it is a NULL. This is
            equivalent to <br /> (receiver == [NSNull null]
            ? <code>YES</code> : <code>NO</code>) <br />
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteBigInteger</sel>
          <desc>
            If the receiver can be represented as a 64bit integer,
            return the string literal representation as used in
            SQL, otherwise raise exception.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteBigNatural</sel>
          <desc>
            If the receiver can be represented as a 64bit
            non-negative integer, return the string
            literal representation as used in SQL, otherwise
            raise exception.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteBigPositive</sel>
          <desc>
            If the receiver can be represented as a 64bit positive
            (not zero) integer, return the string literal
            representation as used in SQL, otherwise
            raise exception.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteForSQLClient:</sel>
          <arg type="SQLClient*">db</arg>
          <desc>
            Classes may override this method to provide a value
            for use as part of an SQL query or statement. The
            method is used internally when quoting objects.
            <br /> The <var>db</var> argument may be examined to
            enable a class to support different quoting for
            different database backends, but an
            implementation must at least support quoting
            appropriate for standard SQL. <br /> The
            default NSObject implementation simply returns
            <code>nil</code>, which means that the object may
            not be used in an SQL query/statement.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteInteger</sel>
          <desc>
            If the receiver can be represented as a 32bit integer,
            return the string literal representation as used in
            SQL, otherwise raise exception.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteNatural</sel>
          <desc>
            If the receiver can be represented as a 32bit
            non-negative integer, return the string
            literal representation as used in SQL, otherwise
            raise exception.
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quotePositive</sel>
          <desc>
            If the receiver can be represented as a 32bit positive
            (not zero) integer, return the string literal
            representation as used in SQL, otherwise
            raise exception.
          </desc>
        </method>
      </category>
    </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:" class="SQLClient(Caching)">[SQLClient(Caching) -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:" class="SQLClient(Caching)">[SQLClient(Caching) -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="SQLLitArg*">stmt</arg>
          <desc>
            Calls
            <ref type="method" id="-cache:simpleQuery:recordType:listType:" class="SQLClient(Caching)">[SQLClient(Caching) -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="SQLLitArg*">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 an autoreleased mutable copy.
            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, the <ref type="method" id="-addObject:" class="NSMutableArray">[NSMutableArray -addObject:]</ref> method to add records to the list, and the <ref type="method" id="-count" class="NSMutableArray">[NSMutableArray -count]</ref> method to return the number of records added. <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 /> NB. cache lookups for the
                instance created from <var>ltype</var> will be
                provided by sending
                <ref type="method" id="-mutableCopy">
                  -mutableCopy
                </ref>
                and autorelease messages to the original instance.
                <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:" class="SQLClient(Caching)">[SQLClient(Caching) -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="NSMutableArray*">
          <sel>cacheCheckSimpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <desc>
            Returns an autoreleased mutable copy of the cached
            object corresponding to the supplied query/statement
            (or <code>nil</code> if no such object is cached).
          </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 asynchronously. <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="NSMutableArray*" factory="yes">
          <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="void" factory="yes">
          <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. <br />
            NB. This does not check that the contents of the
            <var>records</var> array are actually instances of
            <ref type="class" id="SQLRecord">SQLRecord</ref>
              , so you must ensure you don't call it more than once
              on the same array (something that may happen if you
              retrieve the array using a cache based query).
          </desc>
        </method>
        <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>
            The same as the
            <ref type="method" id="+columns:" class="SQLClient(Convenience)">[SQLClient(Convenience) +columns:]</ref> method.
          </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>
            The same as the
            <ref type="method" id="+singletons:" class="SQLClient(Convenience)">[SQLClient(Convenience) +singletons:]</ref> method.
          </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. <br /> Do NOT
            override with code which can be slow or which
            calls (directly or indirectly) any SQLCLient methods,
            since this method will be used inside locked regions
            of the SQLClient code and you could cause deadlocks or
            <strong>long</strong> delays to other threads
            using the class.
          </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(Notifications) category
      </heading>
      <category name="Notifications" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category contains methods for asynchronous
          notification of events via the database (for
          those database backends which support it: currently
          only PostgreSQL).
        </desc>
        <method type="void">
          <sel>addObserver:</sel>
          <arg type="id">anObserver</arg>
          <sel>selector:</sel>
          <arg type="SEL">aSelector</arg>
          <sel>name:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Adds <var>anObserver</var> to receive notifications
            when the backend database server sends an asynchronous
            event identified by the specified <var>name</var>
            (which must be a valid database identifier). <br />
            When a notification (NSNotification instance) is
            received by the method specified by
            <var>aSelector</var>, its <em>object</em> will be the
            SQLClient instance to which <var>anObserver</var>
            was added and its userInfo dictionary will contain the
            key 'Local' and possibly the key 'Payload'. <br /> If
            the 'Local' value is the boolean <code>YES</code>, the
            notification originated as an action by this
            SQLClient instance. <br /> If the 'Payload' value
            is not <code>nil</code>, then it is a string providing
            extra information about the notification. <br />
            Notifications are posted asynchronously using
            the default notification queue for the thread which
            receives them (or the main thread if the receiving
            thread run loop is not active), so they should be
            delivered to the observer after the database
            statement in which they were detected has
            completed. However, delivery of the notification
            could still occur inside a transaction if the
            <ref type="method" id="-begin">
              -begin
            </ref>
            and <ref type="method" id="-commit">-commit</ref>
            statements are used. For this reason, observing
            code may want to use the
            <ref type="method" id="-lockBeforeDate:">
              -lockBeforeDate:
            </ref>
            <ref type="method" id="-isInTransaction">
              -isInTransaction
            </ref>
            and <ref type="method" id="-unlock">-unlock</ref>
            methods to ensure that they don't interfere with
            ongoing transactions. <br /> For observation of
            notifications to be immediately effective,
            the instance must be connected to the database (and
            remain connected), so you can't call this method on
            a client from a pool, and you should make sure that you
            don't close the client connection (or if you do, that
            you make sure to re-open it in order to start receiving
            notifications again). <br /> Each observer,
            may only have one observation set up for a particular
            <var>name</var>. If an attempt is made to add a
            second observation for the same <var>name</var> it
            will be silently ignored.
          </desc>
        </method>
        <method type="void">
          <sel>postNotificationName:</sel>
          <arg type="NSString*">name</arg>
          <sel>payload:</sel>
          <arg type="NSString*">more</arg>
          <desc>
            Posts a notification via the database. The
            <var>name</var> is an SQL identifier (for which
            observers may have registered) and the extra
            payload information may be <code>nil</code> if not
            required.
          </desc>
        </method>
        <method type="void">
          <sel>removeObserver:</sel>
          <arg type="id">anObserver</arg>
          <sel>name:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Removes <var>anObserver</var> as an observer for
            asynchronous notifications from the database
            server. <br /> If <var>name</var> is omitted, the
            observer will be removed for all names. <br /> If
            <var>anObserver</var> is <code>nil</code>, the
            removal will be performed for all current observers
            (and if both <var>name</var> and <var>anObserver</var>
            are <code>nil</code>, then all observations are
            removed). <br /> Any attempt to remove a non
            existent observation is silently ignored.
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>
        Software documentation for the SQLClient(Quote)
        category
      </heading>
      <category name="Quote" class="SQLClient">
        <declared>SQLClient.h</declared>
        <desc>
          This category encapsulates methods used to control
          automatic quoting of non-literal strings. <br />
          The point of this feature is to help prevent SQL
          injection attacks on your software (where you read
          in something from some UI, and use that data in creating a
          database query/statement, and an attacker might try
          to fool your code into doing something bad to the
          database). <br /> When autoquote is turned on, the
          methods to build queries/statements
          ([SQLClient-prepare:args:] and
          <ref type="method" id="-prepare:with:" class="SQLClient">
            [SQLClient -prepare:with:]
          </ref>
          and other methods based on those) will perform a runtime
          check for strings in the arguments list they are given,
          and will automatically quote any string which is not
          considered a literal. <br /> The types of literal
          string are:
          <deflist>
            <term>compiler literal</term>
            <desc>
              A string literal in your source code of the form
              @&quot;text&quot;, generated by the
              compiler. <br /> The rationale is that if it's
              a literal constant in the source code, the programmer
              should know (and be able to clearly see) that it's
              properly quoted for the context in which it is
              used.
            </desc>
            <term>copy literal</term>
            <desc>
              A string of a special class which has been produced by
              calling one of the quote methods, or by calling
              the
              <ref type="function" id="SQLClientCopyLiteral">
                SQLClientCopyLiteral()
              </ref>
              ,
              <ref type="function" id="SQLClientMakeLiteral">
                SQLClientMakeLiteral()
              </ref>
              , or
              <ref type="function" id="SQLClientNewLiteral">
                SQLClientNewLiteral()
              </ref>
              functions to make a copy of a string to be
              treated as a literal.
            </desc>
            <term>proxy literal</term>
            <desc>
              A string of a special class which has been produced by
              calling the
              <ref type="function" id="SQLClientProxyLiteral">
                SQLClientProxyLiteral()
              </ref>
              function to wrap an existing string to mark it
              to be treated as a literal. This should only be used
              as a performance tweak when a programmer has built a
              very large SQL statement, and copying it would hurt
              performance.
            </desc>
          </deflist>
          NB. column values in the results of a database query are
          not returned as literals unless they are NULL or come
          from a column whose actual type is a form of number or
          boolean (since booleans and numbers do not need any
          form of quoting in an SQL query/statement).
        </desc>
        <method type="BOOL" factory="yes">
          <sel>autoquote</sel>
          <desc>
            Returns a BOOL saying whether autoquote is on or
            off.
          </desc>
        </method>
        <method type="BOOL" factory="yes">
          <sel>autoquoteWarning</sel>
          <desc>
            Returns a BOOL saying whether autoquote warnings
            are on or off.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setAutoquote:</sel>
          <arg type="BOOL">aFlag</arg>
          <desc>
            Turns autoquote on/off for the process. <br /> When
            autoquote is on, the arguments to the
            <ref type="method" id="-prepare:args:" class="SQLClient">
              [SQLClient -prepare:args:]
            </ref>
            method (and therefore all methods that use it) are
            automatically quoted unless they are literal
            strings. <br /> The purpose of autoquoting is to
            help prevent SQL injection attacks on your software;
            it helps ensure that only strings you really want to use
            literally are embedded in the SQL without
            quoting.
          </desc>
        </method>
        <method type="void" factory="yes">
          <sel>setAutoquoteWarning:</sel>
          <arg type="BOOL">aFlag</arg>
          <desc>
            Turns autoquote warning on/off for the process.
            <br /> When autoquote warning is on, an
            <ref type="function" id="NSLog">
              NSLog()
            </ref>
            warning is generated whenever the arguments to the
            <ref type="method" id="-prepare:args:" class="SQLClient">
              [SQLClient -prepare:args:]
            </ref>
            method (and therefore all methods that use it) are
            automatically quoted (or would be if
            autoquote was turned on). <br /> Turn this on
            when using software which you expect to migrate to
            using autoquote.
          </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="NSInteger" 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>
              Callers 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>
            <p>
              Where the database backend support it, this method
              returns the count of the number of rows to which
              the operation applied. Otherwise this returns -1.
            </p>
          </desc>
        </method>
        <method type="void" override="subclass">
          <sel>backendListen:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Called to enable asynchronous notification of
            database events using the specified
            <var>name</var> (which must be a valid identifier
            consisting of ascii letters, digits, and
            underscore characters, starting with a letter).
            <br /> Repeated calls to list on the same
            <var>name</var> should be treated as a single call.
            <br /> The backend is responsible for implicitly
            unlistening when a connection is closed. <br />
            There is a default implementation which does nothing
            ... for backends which don't support asynchronous
            notifications. <br /> If a backend
            <em>does</em> support asynchronous notifications, it
            should do so by posting NSNotification instances to
            the main thread [NSNotificationQueue defaultQueue] with
            the posting style NSPostASAP (to post asynchronously)
            and using the SQLClient instance as the notification
            object and supplying any payload as a string using
            the 'Payload' key in the NSNotification userInfo
            dictionary. The userInfo dictionary should also
            contain a boolean (NSNumber) value, using the
            'Local' key, to indicate whether the notification
            was sent by the current SQLClient instance or by some
            other client/
          </desc>
        </method>
        <method type="void" override="subclass">
          <sel>backendNotify:</sel>
          <arg type="NSString*">name</arg>
          <sel>payload:</sel>
          <arg type="NSString*">more</arg>
          <desc>
            The backend should implement this to send asynchronous
            notifications to anything listening for them.
            The <var>name</var> of the notification is an SQL
            identifier used for listening for the
            asynchronous data. <br /> The payload string
            may be <code>nil</code> if no additional information is
            needed in the notification.
          </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>
              Callers 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 instance to store records. The
              instance must implement
              <ref type="method" id="-initWithCapacity:" class="NSMutableArray">[NSMutableArray -initWithCapacity:]</ref> to initialise itsself, <ref type="method" id="-addObject:" class="NSMutableArray">[NSMutableArray -addObject:]</ref> to allow the backend to add records to it, and <ref type="method" id="-count">-count</ref> to return the number of records added. <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="void" override="subclass">
          <sel>backendUnlisten:</sel>
          <arg type="NSString*">name</arg>
          <desc>
            Called to disable asynchronous notification of
            database events using the specified
            <var>name</var>. This has no effect if the
            <var>name</var> has not been used in an earlier call
            to
            <ref type="method" id="-backendListen:">
              -backendListen:
            </ref>
            , or if the <var>name</var> has already been unlistened
            since the last call to listen. on it. <br /> There is
            a default implementation which does nothing... for
            backends which don't support asynchronous
            notifications.
          </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>
        Software documentation for the
        SQLClientPool(Convenience) category
      </heading>
      <category name="Convenience" class="SQLClientPool">
        <declared>SQLClient.h</declared>
        <desc>
          This category lists the convenience methods provided by
          a pool instance for proxying messages to a one-off client
          instance in the pool. <br /> The behavior of each
          method is, of course, as documentf for instances of
          the
          <ref type="class" id="SQLClient">SQLClient</ref>
            class.
        </desc>
        <method type="SQLLiteral*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>buildQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </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>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>simpleQuery:</sel>
          <arg type="SQLLitArg*">stmt</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cache:</sel>
          <arg type="int">seconds</arg>
          <sel>simpleQuery:</sel>
          <arg type="SQLLitArg*">stmt</arg>
          <sel>recordType:</sel>
          <arg type="id">rtype</arg>
          <sel>listType:</sel>
          <arg type="id">ltype</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>cacheCheckSimpleQuery:</sel>
          <arg type="NSString*">stmt</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>columns:</sel>
          <arg type="NSMutableArray*">records</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSInteger">
          <sel>execute:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSInteger">
          <sel>execute:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLClientPool*">
          <sel>pool</sel>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>args:</sel>
          <arg type="va_list">args</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>prepare:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>query:</sel>
          <arg type="NSString*">stmt</arg>
          <sel>with:</sel>
          <arg type="NSDictionary*">values</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLRecord*">
          <sel>queryRecord:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSString*">
          <sel>queryString:</sel>
          <arg type="NSString*">stmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quote:</sel>
          <arg type="id">obj</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteArray:</sel>
          <arg type="NSArray*">a</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableString*">
          <sel>quoteArray:</sel>
          <arg type="NSArray*">a</arg>
          <sel>toString:</sel>
          <arg type="NSMutableString*">s</arg>
          <sel>quotingStrings:</sel>
          <arg type="BOOL">_q</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteArraySafe:</sel>
          <arg type="NSArray*">a</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteBigInteger:</sel>
          <arg type="int64_t">i</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteCString:</sel>
          <arg type="const char*">s</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteChar:</sel>
          <arg type="char">c</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteFloat:</sel>
          <arg type="double">f</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteInteger:</sel>
          <arg type="int">i</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteName:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteSet:</sel>
          <arg type="id">obj</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quoteString:</sel>
          <arg type="NSString*">s</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="SQLLiteral*">
          <sel>quotef:</sel>
          <arg type="NSString*">fmt</arg>
          <vararg />
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSInteger">
          <sel>simpleExecute:</sel>
          <arg type="NSArray*">info</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>simpleQuery:</sel>
          <arg type="SQLLitArg*">stmt</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="NSMutableArray*">
          <sel>simpleQuery:</sel>
          <arg type="SQLLitArg*">stmt</arg>
          <sel>recordType:</sel>
          <arg type="id">rtype</arg>
          <sel>listType:</sel>
          <arg type="id">ltype</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
        <method type="void">
          <sel>singletons:</sel>
          <arg type="NSMutableArray*">records</arg>
          <desc>
            <em>Description forthcoming.</em>
          </desc>
        </method>
      </category>
    </chapter>
    <chapter>
      <heading>SQLClient types</heading>
      <p></p>
      <type type="struct _SQLClientPoolItem" name="SQLClientPoolItem">
        <desc>
          <em>Description forthcoming.</em>
        </desc>
      </type>
    </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="SQLLiteral*" name="SQLClientCopyLiteral">
        <arg type="NSString*">aString</arg>
        <desc>
          Creates and returns a copy of <var>aString</var> as a
          literal, whether or not <var>aString</var> is
          already a literal string.
        </desc>
      </function>
      <function type="BOOL" name="SQLClientIsLiteral">
        <arg type="NSString*">aString</arg>
        <desc>
          Function to test an object to see if it is
          considered to be a literal string by SQLClient.
          Use this rather than trying to chewck the class hierarchy
          (which is not reliable).
        </desc>
      </function>
      <function type="SQLLiteral*" name="SQLClientMakeLiteral">
        <arg type="NSString*">aString</arg>
        <desc>
          Returns a literal string version of
          <var>aString</var>. <br /> A literal is an instance of
          the literal string class produced by the compiler or the
          SQLString class (which subclasses it). <br /> If
          <var>aString</var> is already a literal string, this
          method returns it unchanged, otherwise the returned
          value is an autoreleased newly created copy of the
          argument.
        </desc>
      </function>
      <function type="SQLLiteral*" name="SQLClientNewLiteral">
        <arg type="const char*">bytes</arg>
        <arg type="unsigned int">count</arg>
        <desc>
          Function to create an SQL literal (string which
          won't be autoquoted) from a UTF8 or ASCII C string
          whose length (not including any nul terminator) is the
          specified <var>count</var>.
        </desc>
      </function>
      <function type="SQLLiteral*" name="SQLClientProxyLiteral">
        <arg type="NSString*">aString</arg>
        <desc>
          Creates and returns an autoreleased proxy to
          <var>aString</var>, recording the fact that the
          programmer considers the string to be a valid
          literal (ie one that doesn't need to be quoted when
          used as part of an SQL statement or query). The original
          string is retained by the object returned. <br /> Use
          this when <var>aString</var> is large and the overheads
          of the
          <ref type="function" id="SQLClientCopyLiteral">
            SQLClientCopyLiteral()
          </ref>
          or
          <ref type="function" id="SQLClientMakeLiteral">
            SQLClientMakeLiteral()
          </ref>
          functions would be too high. <br /> NB.
          Manipulation of proxy objects is inefficient...
          you should leave creation of the proxy to the last moment
          before passing it to a method which would otherwise
          autoquote your string.
        </desc>
      </function>
      <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>
      <function type="NSString*" name="SQLClientUnProxyLiteral">
        <arg type="id">aString</arg>
        <desc>
          Returns the original string which was previously
          wrapped by a call to
          <ref type="function" id="SQLClientProxyLiteral">
            SQLClientProxyLiteral()
          </ref>
          . If <var>aString</var> is not an SQLLiteral proxy, this
          returns <var>aString</var>.
        </desc>
      </function>
    </chapter>
  </body>
</gsdoc>
