 _SrPersist_
 ===========

 _ODBC_
 ======

 SrPersist is an ODBC library for MzScheme and DrScheme.
 Any database management system with an ODBC driver should 
 be usable with SrPersist.

 SrPersist provides a one-to-one mapping of ODBC procedures to 
 Scheme procedures, with some additional utility procedures in Scheme.
 Procedures from ODBC versions 1.0 through 3.51 are supported.   
 Where ODBC expects symbolic constants created through C #define's,
 SrPersist uses Scheme constants, which are checked for validity.
 In many cases, redundant arguments are eliminated.  In many cases,
 the SrPersist version of an ODBC procedure returns a handle, allowing 
 procedures to be composed.

 ODBC procedure names are mapped to Scheme names straightforwardly.
 The initial "SQL" in the name is removed, the characters 
 are made all lowercase, and hyphens are inserted before the location
 of formerly uppercase letters, other than the first following "SQL".  
 For example, the hypothetical ODBC name SQLProcedureName would be 
 mapped to the Scheme name procedure-name.  The exceptions are SQLError
 and SQLExecute, which are mapped to sql-error and sql-execute, to 
 avoid confusion with MzScheme procedures.

 The documentation here may be sufficient to get started with
 SrPersist, but you will certainly want to consult an ODBC reference for 
 more information.  The file tutorial.txt in the SrPersist collection 
 provides some simple examples of how to use SrPersist.

 SrPersist is not
 ----------------

 SrPersist makes the ODBC API available in Scheme, but does not
 support any abstractions beyond it.  Some useful error-checking is 
 performed that is not done when using the C version of the API.
 Serious run-time errors are still possible, such as when a too-small 
 buffer is bound to a column.  

 Francisco Solsona has built a higher-level layer, SchemeQL,
 currently in beta, that uses SrPersist as a substrate.
 A SchemeQL programmer avoids the low-level details 
 of ODBC.  You can download SchemeQL from 
 http://schematics.sourceforge.net/schemeql.html.

 Loading
 -------

 To load SrPersist, use

   (require (lib "srpersist.ss" "srpersist"))

 For Windows, if you get errors when loading, your Windows installation 
 may be missing certain ODBC libraries.  Look for ODBC Data Sources 
 in Windows Control Panel.  If that application is missing, download 
 and install the Microsoft Data Access Components from 
 http://www.microsoft.com/data/.  The download is about 6.5 Mb.

 Overview of ODBC
 ----------------

 ODBC is a standard for allowing application programs to retrieve from 
 and send data to relational databases.  The application program 
 communicates with a Driver Manager using ODBC procedures.  Database
 queries use SQL (Structured Query Language).  The Driver Manager 
 communicates with databases using drivers specific to them.  Therefore, 
 ODBC is a "middleware" standard.  

 How to use this documentation
 -----------------------------

 Because ODBC is very complex, this documentation cannot hope to
 cover all its aspects.  Instead, this documentation describes 
 a Scheme interface to ODBC.  Each ODBC API procedure has a Scheme
 counterpart.  In this documentation, we describe the parameters
 and return values for each procedure, as well as give some indication
 of the purpose of the procedure.  To use ODBC effectively, you will
 need access to an ODBC reference, such as that provided with the
 Microsoft ODBC SDK.

 Overview of ODBC procedures
 ---------------------------

 In the documentation below, we group SrPersist ODBC procedures 
 by topics.  The topics are Exceptions, Handles, Connections, Environments,
 Statements and Parameters, Descriptors, Cursors, Columns and Data
 Retrieval, Metadata, and Errors and Diagnostics.  SrPersist also has 
 its own utility procedures, listed under the heading Utilities below.

 For each procedure, we indicate the ODBC version in which it was 
 introduced.  Therefore, some SrPersist procedures may not be available 
 to your program.  

 Exceptions
 ----------

 Any SrPersist ODBC procedure may raise an exception.  
 SrPersist exceptions correspond to the ODBC SQLRESULT codes, 
 as follows:

  exn-invalid-handle    SQL_INVALID_HANDLE
  exn-error             SQL_ERROR
  exn-still-executing   SQL_STILL_EXECUTING
  exn-need-data         SQL_NEED_DATA
  exn-with-info         SQL_SUCCESS_WITH_INFO
  exn-no-data           SQL_NO_DATA_FOUND (before ODBC 3.0)
  exn-no-data           SQL_NO_DATA (ODBC 3.0 or greater)

 Each of these exceptions is an ordinary Scheme structure
 derived from `struct:exn'.  Only `exn-need-data` and `exn-with-info' 
 contain an extra field, `val' in both cases.  The names of the 
 exception indicate the nature of the problem that has occurred.  
 Each of these exceptions, other than `exn-with-info', indicate an error.
 The exception `exn-error' is a catchall, indicating an unspecified error.
 The exception `exn-with-info' does not indicate an error, rather it 
 indicates that additional information is available about the procedure 
 that generated the exception.  The `val' field of `exn-need-data` or 
 `exn-with-info' instances contains the value returned by the procedure 
 that generated the exception.  In the case of `exn-need-data', depending
 on the ODBC procedure, the contained value may not be meaningful.

 `with-handlers' can be used to handle SrPersist exceptions:

   (with-handlers ([(lambda (exn)
                      (exn-with-info? exn))
                    (lambda (exn) 
                      (printf "Got exn-with-info exception~n")
                      (printf "Value: ~a~n" (exn-with-info-val exn)))])
     ...)		      

 Applications can call sql-error, get-diag-rec, or get-diag-field
 to obtain additional information about an exception that
 has occurred (see the heading "Diagnostics", below).  No additional 
 information is available when the exception is `exn-invalid-handle'.

 If you attempt to use an ODBC procedure which is not available 
 in the ODBC version specified when compiling SrPersist, you
 will get an exn-not-implemented exception.

 Besides these SrPersist-particular exceptions, other kinds of errors 
 may raise exceptions.  For example, passing a value of the
 wrong type to a SrPersist procedure will raise an exception.

 Version information
 -------------------

 SrPersist offers version information to programs:

> (srp-version)

 Returns a string indicating the version of SrPersist.

> (compiled-odbc-version)

 Returns a string indicating the version of ODBC that was 
 specified when SrPersist was compiled.  This version 
 is not necessarily the same as odbc-version, the version
 specified when loading SrPersist.

 Handles
 -------

 ODBC and SrPersist support four kinds of handles.  
 In ODBC itself, all handles are represented as integers,
 making it possible for handle types to be confused.  
 In SrPersist, each handle type has a distinct Scheme 
 type.  An "environment handle" has type `sql-henv'; a
 "connection handle" has type `sql-hdbc'; a "statement handle" has 
 type `sql-hstmt'; a "descriptor handle" has type `sql-hdesc'.

 Further, descriptor handles have an attribute which divides 
 them into subtypes, though this does not show up in their
 Scheme type.  Ordinarily, a descriptor handle is either an 
 Application Parameter Descriptor (attribute APD), an Application 
 Row Descriptor (ARD), an Implementation Parameter Descriptor (IPD), 
 or an Implementation Row Descriptor (IRD).  Most descriptor 
 handles are created by an ODBC driver.  When a descriptor 
 handle is explicitly allocated, it receives the attribute
 EXPLICIT, rather than one of the four attribute values just 
 mentioned.
  
 There are several procedures to allocate fresh handles.

> (alloc-env)

 ODBC 1.0, deprecated in favor of `alloc-handle'.

 Returns a fresh environment handle. 

> (alloc-connect henv) 

 ODBC 1.0, deprecated in favor of `alloc-handle'.

 Returns a fresh connection handle, given `henv', an
 environment handle.

> (alloc-stmt hdbc) 

 ODBC 1.0, deprecated in favor of `alloc-handle'.

 Returns a fresh statement handle, given `hdbc', a 
 connection handle

> (alloc-handle htype [handle])

 ODBC 3.0.

 Returns a fresh handle whose type depends on `htype',
 a Scheme symbol.  If `htype' is 'sql-handle-env, 
 then `handle' must be omitted, and a fresh `environment
 handle' is returned.  If `htype' is 'sql-handle-dbc, 
 then `handle' must be an environment handle, and a fresh 
 `connection handle' is returned.  If `htype' is 'sql-handle-stmt, 
 then `handle' must be a connection handle, and a fresh 
 `statement handle' is returned.  If `htype' is 'sql-handle-desc, 
 then `handle' must be a connection handle, and a fresh 
 `descriptor handle' with attribute EXPLICIT is returned.  
 Any other value of `htype' causes an error.

 Before using `alloc-handle' to create a connection handle, you may 
 need to call `set-env-attr' with 'sql-attr-odbc-version and 
'sql-ov-odbc3 as arguments.

> (free-connect hdbc)

 ODBC 1.0, deprecated in favor of free-handle.

 Frees a connection handle `hdbc', whose value is returned by the 
 procedure.

> (free-env henv)

 ODBC 1.0, deprecated in favor of free-handle.

 Frees an environment handle `henv', whose value is returned by the
 procedure.

> (free-handle handle)

 ODBC 3.0.

 Frees `handle', which may be an environment, connection, statment,
 or descriptor handle.  Returns the value of `handle'.

> (free-stmt hstmt option)

 ODBC 1.0.

 Frees or releases resources for the statement handle `hstmt'.
 The `option' argument may be any of the following symbols, with
 the indicated effects:

  'sql-close        closes the statement cursors, discards pending results  
                    (does not actually free `hstmt')
  'sql-drop         deprecated, effectively (free-handle hstmt) 
  'sql-unbind       releases all column buffers for the statement
  'sql-reset-parms  releases all parameter buffers for the statement

 free-stmt returns the value of `hstmt'.

 Environments
 ------------

> (data-sources henv direction)

 OCBC 1.0.

 For the environment handle `henv', returns a pair of strings
 indicating a data source name and its description.  The
 symbol `direction' is either 'sql-fetch-first, 'sql-fetch-next,
 'sql-fetch-first-user, or 'sql-fetch-first-system.  User data
 sources are visible only to a particular user, while system
 data sources are visible to all users.

> (drivers henv fetch)

 ODBC 2.0.

 For the environment handle `henv', returns a two-element list
 of strings describing an available driver.  The first string 
 identifies the driver and the second string describes attributes
 of the driver.  `fetch' is either 'sql-fetch-first or 
 'sql-fetch-next.  By using repeated calls to drivers with 
 'sql-fetch-next, a program can obtain information about all
 available drivers.  Providing 'sql-fetch-next on the first 
 call to drivers has the same effect as 'sql-fetch-first.

 Please consult an ODBC reference for an information about the 
 keyword/value pairs that appear in the attributes string.   

> (get-env-attr henv attr)

 ODBC 3.0.

 Given an environment handle `henv', returns the value of the
 attribute `attr'.  The possible values for `attr' and the
 resulting return values are:

  attr                           returns
  ----                           -------
  'sql-attr-connection-pooling   'sql-cp-off, or                
                                 'sql-cp-one-per-driver, or
                                 'sql-cp-one-per-henv

  'sql-attr-cp-match             'sql-cp-strict-match, or 
                                 'sql-cp-relaxed-match

  'sql-attr-odbc-version         'sql-ov-odbc3, or
                                 'sql-ov-odbc2

  'sql-attr-output-nts           boolean

 Please see an ODBC reference for more information about the 
 significance of these attributes.

> (set-env-attr henv attr val)

 ODBC 3.0.

 Given an environment handle `henv', sets the value of its associated 
 attribute `attr' to the value `val'.  See `get-env-attr' for the
 available attributes and their valid values.  Returns the value of 
 `henv'.

 Connections
 -----------

 Before an ODBC database may be used, a `connection' between 
 the ODBC driver and database management system needs to be
 established.  Here are the procedures for establishing and 
 managing connections.

> (connect hdbc dbms name password) 

 ODBC 1.0.

 Establishes a connection, given a connection handle `hdbc', and 
 strings for a database server `dbms', a `name' and `password'.
 Returns the value of `hdbc'.

> (browse-connect hdbc connect-string)

 ODBC 1.0.

 Connects to a data source, given a connection handle `hdbc'
 and connection string `connect-string'.  The connection string
 consists of keyword and value pairs.  See `driver-connect'
 for the format of such pairs.  The first time `browse-connect' 
 is called, the connection string must contain either the
 DSN or DRIVER keywords.  `browse-connect' returns a connection string 
 with a sequence of keywords and value pairs.  Those pairs not
 preceded by an asterisk are mandatory in the next call to
 browse-connect.  If the supplied connection string does not 
 contain all needed attributes to make a connection, a `exn-need-data'
 exception is raised, which contains a connection string indicating 
 which attributes are missing. 
 
> (driver-connect hdbc connect-string prompt)

 ODBC 1.0.

 Connects to an ODBC driver, given a connection handle `hdbc',
 the string `connect-string', and the symbol `prompt'.
 The connect-string is a possibly-empty sequence of 
 keyword, attribute pairs:

   keyword=attribute;... 

 where `keyword' is any of 

   DSN       data source
   UID       user id
   PWD       password
   FILEDSN   name of a .dsn file containing a connection string
   DRIVER    driver description
   SAVEFILE  a .dsn file for saving the connection attributes

 or a driver-specific keyword.  DSN and DRIVER are mutually-exclusive.  
 DRIVER is ODBC 2.0, while FILEDSN and SAVEFILE are ODBC 3.0.
 For DRIVER only, the attribute may be surrounded by 
 curly braces {}, useful if the attribute contains a semicolon.
 `prompt' is one of the symbols 

   'sql-driver-prompt              prompt for required information
   'sql-driver-complete            prompt if DSN not in connect-string
   'sql-driver-complete-required   prompt if DSN not in connect-string
   'sql-driver-noprompt            do not prompt for information
 
 driver-connect returns a connection string indicating all the
 keywords and values that were passed to the data source.

> (disconnect hdbc)

 ODBC 1.0.

 Closes the data source connection associated with the connection 
 handle `hdbc'.  Frees any statement and descriptor handles associated 
 with the connection handle.  Returns the value of `hdbc'.

> (get-info hdbc infotype [handle])

 ODBC 1.0.

 Returns information about the data source associated with the 
 connection handle `hdbc'.  The type of the return value depends
 on the symbol `infotype', which indicates the information requested.
 The optional argument `handle' is either a statement handle
 or a descript handle, and may be used only with certain 
 values of `infotype', as described below.

 The significance of the values returned by get-info is beyond the
 scope of this documentation.  Please consult an ODBC reference 
 for further information.

 The permissible values of `infotype' vary by ODBC version.
 Valid values of `infotype' and their return types are:

 infotype                            returns
 --------                            -------

 [ODBC 1.0 or greater]
 'sql-accessible-procedures          boolean
 'sql-accessible-tables              boolean
 'sql-active-connections             unsigned integer
 'sql-active-statements              unsigned integer
 'sql-alter-table                    a list with elements chosen from    
                                      '(sql-at-add-column-collation
                                        sql-at-add-column-default
                                        sql-at-add-column-single
                                        sql-at-add-constraint
                                        sql-at-add-table-constraint
                                        sql-at-constraint-name-definition
                                        sql-at-drop-column-cascade
                                        sql-at-drop-column-default
                                        sql-at-drop-column-restrict
                                        sql-at-drop-table-constraint-cascade
                                        sql-at-drop-table-constraint-restrict
                                        sql-at-set-column-default
                                        sql-at-constraint-initially-deferred
                                        sql-at-constraint-initially-immediate
                                        sql-at-constraint-deferrable
                                        sql-at-constraint-non-deferrable)
 'sql-correlation-name               'sql-cn-none, or 
                                     'sql-cn-different, or 
                                     'sql-cn-any
 'sql-convert-functions              a list with elements chosen from
                                      '(sql-fn-cvt-cast sql-fn-cvt-convert)
 'sql-column-alias                   boolean 
 'sql-concat-null-behavior           'sql-cb-null or
                                     sql-cb-non-null
 'sql-convert-bigint                 a list with elements chosen from
                                      '(sql-cvt-bigint
                                        sql-cvt-binary
                                        sql-cvt-bit
                                        sql-cvt-char
                                        sql-cvt-date
                                        sql-cvt-decimal
                                        sql-cvt-double
                                        sql-cvt-float
                                        sql-cvt-integer
                                        sql-cvt-interval-year-month
                                        sql-cvt-interval-day-time
                                        sql-cvt-longvarbinary
                                        sql-cvt-longvarchar
                                        sql-cvt-numeric
                                        sql-cvt-real
                                        sql-cvt-smallint
                                        sql-cvt-time
                                        sql-cvt-timestamp
                                        sql-cvt-tinyint
                                        sql-cvt-varbinary
                                        sql-cvt-varchar)
 'sql-convert-binary                 same as for 'sql-convert-bigint
 'sql-convert-bit                    same as for 'sql-convert-bigint
 'sql-convert-char                   same as for 'sql-convert-bigint
 'sql-convert-date                   same as for 'sql-convert-bigint 
 'sql-convert-decimal                same as for 'sql-convert-bigint
 'sql-convert-double                 same as for 'sql-convert-bigint
 'sql-convert-float                  same as for 'sql-convert-bigint
 'sql-convert-integer                same as for 'sql-convert-bigint
 'sql-convert-longvarbinary          same as for 'sql-convert-bigint
 'sql-convert-longvarchar            same as for 'sql-convert-bigint
 'sql-convert-real                   same as for 'sql-convert-bigint  
 'sql-convert-numeric                same as for 'sql-convert-bigint
 'sql-convert-smallint               same as for 'sql-convert-bigint
 'sql-convert-time                   same as for 'sql-convert-bigint 
 'sql-convert-timestamp              same as for 'sql-convert-bigint
 'sql-convert-tinyint                same as for 'sql-convert-bigint
 'sql-convert-varbinary              same as for 'sql-convert-bigint
 'sql-convert-varchar                same as for 'sql-convert-bigint
 'sql-cursor-commit-behavior         'sql-cb-delete, or
                                     'sql-cb-close, or
                                     'sql-cb-preserve
 'sql-cursor-rollback-behavior       same as for 'sql-cursor-commit-behavior
 'sql-data-source-name               string
 'sql-data-source-read-only          boolean
 'sql-database-name                  string
 'sql-dbms-name                      string
 'sql-dbms-ver                       string 
 'sql-default-txn-isolation          'sql-txn-read-uncommitted, or 
                                     'sql-txn-read-committed, or
                                     'sql-txn-repeatable-read, or
                                     'sql-txn-serializable
 'sql-driver-hdbc                    connection handle
 'sql-driver-henv                    environment handle
 'sql-driver-hlib                    unsigned integer
 'sql-driver-hstmt                   statement handle; `handle' argument
                                      also a statement handle
 'sql-driver-name                    string  
 'sql-driver-odbc-ver                string 
 'sql-driver-ver                     string
 'sql-expressions-in-orderby         boolean
 'sql-fetch-direction                a list with elements chosen from  
                                      '(sql-fd-fetch-next
                                        sql-fd-fetch-first
                                        sql-fd-fetch-last
                                        sql-fd-fetch-prior
                                        sql-fd-fetch-absolute
                                        sql-fd-fetch-relative
                                        sql-fd-fetch-bookmark)
 'sql-file-usage                     'sql-file-not-supported, or 
                                     'sql-file-table, or
                                     'sql-file-qualifier, or
                                     'sql-file-catalog (ODBC 3.0 or greater)
 'sql-getdata-extensions             a list with elements chosen from  
                                      '(sql-gd-any-column
                                        sql-gd-any-order
                                        sql-gd-block
                                        sql-gd-bound)
 'sql-group-by                       'sql-gb-collate (ODBC 3.0 or greater), or 
                                     'sql-gb-not-supported, or
                                     'sql-gb-group-by-equals-select, or
                                     'sql-gb-group-by-contains-select, or
                                     'sql-gb-no-relation
 'sql-identifier-case                'sql-ic-upper, or
                                     'sql-ic-lower, or 
                                     'sql-ic-sensitive, or
                                     'sql-ic-mixed
 'sql-identifier-quote-char          string 
 'sql-keywords                       string
 'sql-like-escape-clause             boolean
 'sql-lock-types                     a list with elements chosen from  
                                      '(sql-lck-no-change
                                        sql-lck-exclusive
                                        sql-lck-unlock)
 'sql-max-binary-literal-len         unsigned integer
 'sql-max-char-literal-len           unsigned integer
 'sql-max-column-name-len            unsigned integer
 'sql-max-columns-in-group-by        unsigned integer
 'sql-max-columns-in-index           unsigned integer
 'sql-max-columns-in-order-by        unsigned integer
 'sql-max-columns-in-select          unsigned integer
 'sql-max-columns-in-table           unsigned integer
 'sql-max-cursor-name-len            unsigned integer
 'sql-max-index-size                 unsigned integer
 'sql-max-owner-name-len             unsigned integer
 'sql-max-procedure-name-len         unsigned integer
 'sql-max-qualifier-name-len         unsigned integer
 'sql-max-row-size                   unsigned integer 
 'sql-max-row-size-includes-long     boolean
 'sql-max-statement-len              unsigned integer 
 'sql-max-table-name-len             unsigned integer
 'sql-max-tables-in-select           unsigned integer
 'sql-max-user-name-len              unsigned integer 
 'sql-mult-result-sets               boolean
 'sql-multiple-active-txn            boolean
 'sql-need-long-data-len             boolean
 'sql-non-nullable-columns           'sql-nnc-null or 
                                     'sql-nnc-non-null
 'sql-null-collation                 'sql-nc-end, or 
                                     'sql-nc-high, or 
                                     'sql-nc-low, or 
                                     'sql-nc-start
 'sql-numeric-functions              a list with elements chosen from
                                      '(sql-fn-num-abs
                                        sql-fn-num-acos
                                        sql-fn-num-asin
                                        sql-fn-num-atan
                                        sql-fn-num-atan2
                                        sql-fn-num-ceiling
                                        sql-fn-num-cos
                                        sql-fn-num-cot
                                        sql-fn-num-degrees
                                        sql-fn-num-exp
                                        sql-fn-num-floor
                                        sql-fn-num-log
                                        sql-fn-num-log10
                                        sql-fn-num-mod
                                        sql-fn-num-pi
                                        sql-fn-num-power
                                        sql-fn-num-radians
                                        sql-fn-num-rand
					sql-fn-num-round
                                        sql-fn-num-sign
                                        sql-fn-num-sin
                                        sql-fn-num-sqrt
                                        sql-fn-num-tan
                                        sql-fn-num-truncate)
 'sql-odbc-api-conformance           'sql-oac-none, or
                                     'sql-oac-level1, or
                                     'sql-oac-level2
 'sql-odbc-sql-conformance           'sql-osc-minimum, or
                                     'sql-osc-core, or
                                     'sql-osc-extended
 'sql-odbc-sql-opt-ief               boolean
 'sql-odbc-ver                       string     
 'sql-order-by-columns-in-select     boolean
 'sql-outer-joins                    boolean
 'sql-owner-term                     string
 'sql-owner-usage                    a list with elements chosen from
                                      '(sql-ou-dml-statements
                                        sql-ou-procedure-invocation
                                        sql-ou-table-definition
                                        sql-ou-index-definition
                                        sql-ou-privilege-definition)
 'sql-pos-operations                 a list with elements chosen from  
                                      '(sql-pos-position
                                        sql-pos-refresh
                                        sql-pos-update
                                        sql-pos-delete
                                        sql-pos-add)
 'sql-positioned-statements          a list with elements chosen from 
                                      '(sql-ps-positioned-delete
                                        sql-ps-positioned-update
                                        sql-ps-select-for-update)
 'sql-procedure-term                 string
 'sql-procedures                     boolean
 'sql-qualifier-location             'sql-ql-start or 'sql-ql-end
 'sql-qualifier-name-separator       string
 'sql-qualifier-term                 string
 'sql-qualifier-usage                a list with elements chosen from  
                                      '(sql-qu-dml-statements
                                        sql-qu-procedure-invocation
                                        sql-qu-table-definition
                                        sql-qu-index-definition
                                        sql-qu-privilege-definition)
 'sql-quoted-identifier-case         'sql-ic-upper, or 
                                     'sql-ic-lower, or 
                                     'sql-ic-sensitive, or
                                     'sql-ic-mixed
 'sql-row-updates                    boolean 
 'sql-scroll-concurrency             a list with elements chosen from 
                                      '(sql-scco-read-only 
                                        sql-scco-lock
                                        sql-scco-opt-rowver
                                        sql-scco-opt-values)
 'sql-scroll-options                 a list with elements chosen from    
                                      '(sql-so-forward-only
                                        sql-so-static
                                        sql-so-keyset-driven
                                        sql-so-dynamic
                                        sql-so-mixed)
 'sql-search-pattern-escape          string 
 'sql-server-name                    string
 'sql-special-characters             string
 'sql-static-sensitivity             a list with elements chosen from 
                                      '(sql-ss-additions
                                        sql-ss-deletions
                                        sql-ss-updates)
 'sql-string-functions               a list with elements chosen from
                                      '(sql-fn-str-ascii
                                        sql-fn-str-bit-length
                                        sql-fn-str-char
                                        sql-fn-str-char-length
                                        sql-fn-str-character-length
                                        sql-fn-str-concat
                                        sql-fn-str-difference
                                        sql-fn-str-insert
                                        sql-fn-str-lcase
                                        sql-fn-str-left
                                        sql-fn-str-length
                                        sql-fn-str-locate
                                        sql-fn-str-ltrim
                                        sql-fn-str-octet-length
                                        sql-fn-str-position
                                        sql-fn-str-repeat
                                        sql-fn-str-replace
                                        sql-fn-str-right
                                        sql-fn-str-rtrim
                                        sql-fn-str-soundex
                                        sql-fn-str-space
                                        sql-fn-str-substring
                                        sql-fn-str-ucase)
 'sql-subqueries                     a list with elements chosen from    
                                      '(sql-sq-correlated-subqueries
                                        sql-sq-comparison
                                        sql-sq-exists
                                        sql-sq-in
                                        sql-sq-quantified)
 'sql-system-functions               a list with elements chosen from
                                      '(sql-fn-sys-dbname
                                        sql-fn-sys-ifnull
                                        sql-fn-sys-username)
 'sql-table-term                     string
 'sql-timedate-add-intervals         a list with elements chosen from
                                      '(sql-fn-tsi-frac-second
                                        sql-fn-tsi-second
                                        sql-fn-tsi-minute
                                        sql-fn-tsi-hour
                                        sql-fn-tsi-day
                                        sql-fn-tsi-week
                                        sql-fn-tsi-month
                                        sql-fn-tsi-quarter
                                        sql-fn-tsi-year)
 'sql-timedate-diff-intervals        a list with elements chosen from
                                      '(sql-fn-tsi-frac-second
                                        sql-fn-tsi-second
                                        sql-fn-tsi-minute
                                        sql-fn-tsi-hour
                                        sql-fn-tsi-day
                                        sql-fn-tsi-week
                                        sql-fn-tsi-month
                                        sql-fn-tsi-quarter
                                        sql-fn-tsi-year)
 'sql-timedate-functions             a list with elements chosen from
                                      '(sql-fn-td-current-date
                                        sql-fn-td-current-time
                                        sql-fn-td-current-timestamp
                                        sql-fn-td-curdate
                                        sql-fn-td-curtime
                                        sql-fn-td-dayname
                                        sql-fn-td-dayofmonth
                                        sql-fn-td-dayofweek
                                        sql-fn-td-dayofyear
                                        sql-fn-td-extract
                                        sql-fn-td-hour
                                        sql-fn-td-minute
                                        sql-fn-td-month
                                        sql-fn-td-monthname
                                        sql-fn-td-now
                                        sql-fn-td-quarter
                                        sql-fn-td-second
                                        sql-fn-td-timestampadd
                                        sql-fn-td-timestampdiff
                                        sql-fn-td-week
                                        sql-fn-td-year)
 'sql-txn-capable                    'sql-tc-none, or 
                                     'sql-tc-dml, or
                                     'sql-tc-ddl-commit, or
                                     'sql-tc-ddl-ignore, or
                                     'sql-tc-all
 'sql-txn-isolation-option           same as for 'sql-default-txn-isolation
 'sql-union                          a list with elements chosen from    
                                      '(sql-u-union sql-u-union-all)
 'sql-user-name                      string 

 [ODBC 2.0 or greater]:
 'sql-bookmark-persistence         a list with elements chosen from 
                                    '(sql-bp-close sql-bp-delete
			              sql-bp-drop sql-bp-transaction
			              sql-bp-update sql-bp-other-hstmt)

 [ODBC 2.01 or greater]:           
 'sql-oj-capabilities              a list with elements chosen from
                                    '(sql-oj-left
                                      sql-oj-right
                                      sql-oj-full
                                      sql-oj-nested
                                      sql-oj-not-ordered
                                      sql-oj-inner
                                      sql-oj-all-comparison-ops)

 [ODBC 3.0 or greater]:
 'sql-active-environments          unsigned integer
 'sql-aggregate-functions          a list with elements chosen from 
				    '(sql-af-all
                                      sql-af-avg
                                      sql-af-count
                                      sql-af-distinct
                                      sql-af-max
                                      sql-af-min
                                      sql-af-sum)
 'sql-alter-domain                   a list with elements chosen from 
                                      '(sql-ad-add-domain-constraint
                                        sql-ad-add-domain-default
                                        sql-ad-constraint-name-definition
                                        sql-ad-drop-domain-constraint
                                        sql-ad-drop-domain-default
                                        sql-ad-add-constraint-deferrable
                                        sql-ad-add-constraint-non-deferrable
                                        sql-ad-add-constraint-inititally-deferred
                                        sql-ad-add-constraint-initially-immediate)
 'sql-async-mode                   'sql-am-connection, or
	                            'sql-am-statement, or
                                    'sql-am-none  
 'sql-batch-row-count              a list with elements chosen from 
				    '(sql-brc-rolled-up
				      sql-brc-procedures
				      sql-brc-explicit)
 'sql-batch-support                 a list with elements chosen from
				     '(sql-bs-select-explicit
                                       sql-bs-row-count-explicit
                                       sql-bs-select-proc
                                       sql-bs-row-count-proc)
 'sql-catalog-location             'sql-cl-start or 'sql-cl-end
 'sql-catalog-name                 boolean   
 'sql-catalog-name-separator       string
 'sql-catalog-term                 string
 'sql-catalog-usage                a list with elements chosen from 
                                    '(sql-cu-dml-statements
                                      sql-cu-procedure-invocation
                                      sql-cu-table-definition
                                      sql-cu-index-definition
                                      sql-cu-privilege-definition)
 'sql-collation-seq                string
 'sql-convert-interval-year-month  same as for 'sql-convert-bigint
 'sql-convert-interval-day-time    same as for 'sql-convert-bigint
 'sql-convert-interval-year-month  same as for 'sql-convert-bigint
 'sql-create-assertion             a list with elements chosen from  
                                    '(sql-ca-create-assertion
                                      sql-ca-constraint-initially-deferred
                                      sql-ca-constraint-initially-immediate
                                      sql-ca-constraint-deferrable
                                      sql-ca-constraint-non-deferrable)
 'sql-create-character-set         a list with elements chosen from  
                                    '(sql-ccs-create-character-set
                                      sql-ccs-collate-clause
                                      sql-ccs-limited-collation)
 'sql-create-collation             a list with elements chosen from  
                                    '(sql-ccol-create-collation)
 'sql-create-domain                a list with elements chosen from  
                                    '(sql-cdo-create-domain
                                      sql-cdo-constraint-name-definition
                                      sql-cdo-default
                                      sql-cdo-constraint
                                      sql-cdo-collation
                                      sql-cdo-constraint-initially-deferred
                                      sql-cdo-constraint-initially-immediate
                                      sql-cdo-constraint-deferrable
                                      sql-cdo-constraint-non-deferrable)
 'sql-create-schema                a list with elements chosen from  
                                    '(sql-cs-create-schema
                                      sql-cs-authorization
                                      sql-cs-default-character-set)
 'sql-create-table                 a list with elements chosen from  
                                    '(sql-ct-create-table
                                      sql-ct-table-constraint
                                      sql-ct-constraint-name-definition
                                      sql-ct-commit-preserve
                                      sql-ct-commit-delete
                                      sql-ct-global-temporary
                                      sql-ct-local-temporary
                                      sql-ct-column-constraint
                                      sql-ct-column-default
                                      sql-ct-column-collation
                                      sql-ct-constraint-initially-deferred
                                      sql-ct-constraint-initially-immediate
                                      sql-ct-constraint-deferrable
                                      sql-ct-constraint-non-deferrable)
 'sql-create-translation           a list with elements chosen from  
                                    '(sql-ctr-create-translation)
 'sql-create-view                  a list with elements chosen from  
                                    '(sql-cv-create-view
                                      sql-cv-check-option
                                      sql-cv-cascaded
                                      sql-cv-local)
 'sql-datetime-literals            a list with elements chosen from
                                    '(sql-dl-sql92-date
                                      sql-dl-sql92-time
                                      sql-dl-sql92-timestamp
                                      sql-dl-sql92-interval-year
                                      sql-dl-sql92-interval-month
                                      sql-dl-sql92-interval-day
                                      sql-dl-sql92-interval-hour
                                      sql-dl-sql92-interval-minute
                                      sql-dl-sql92-interval-second
                                      sql-dl-sql92-interval-year-to-month
                                      sql-dl-sql92-interval-day-to-hour
                                      sql-dl-sql92-interval-day-to-minute
                                      sql-dl-sql92-interval-day-to-second
                                      sql-dl-sql92-interval-hour-to-minute
                                      sql-dl-sql92-interval-hour-to-second
                                      sql-dl-sql92-interval-minute-to-second)
 'sql-ddl-index                      'sql-di-create-index or 
                                     'sql-di-drop-index
 'sql-describe-parameter           boolean
 'sql-dm-ver                       string
 'sql-driver-hdesc                 descriptor handle; `handle' argument
                                     also a descriptor handle 
 'sql-drop-assertion               a list with elements chosen from  
                                    '(sql-da-drop-assertion)
 'sql-drop-character-set           a list with elements chosen from  
                                    '(sql-dcs-drop-character-set)
 'sql-drop-collation               a list with elements chosen from  
                                    '(sql-dc-drop-collation)
 'sql-drop-domain                  a list with elements chosen from  
                                    '(sql-dd-drop-domain
                                      sql-dd-cascade
                                      sql-dd-restrict)
 'sql-drop-schema                  a list with elements chosen from  
                                    '(sql-ds-drop-schema
                                      sql-ds-cascade
                                      sql-ds-restrict)
 'sql-drop-table                   a list with elements chosen from 
				    '(sql-dt-drop-table
                                      sql-dt-cascade
                                      sql-dt-restrict)
 'sql-drop-translation             a list with elements chosen from  
                                    '(sql-dtr-drop-translation)
 'sql-drop-view                    a list with elements chosen from  
	                            '(sql-dv-drop-view
                                      sql-dv-cascade
                                      sql-dv-restrict)
 'sql-cursor-sensitivity           'sql-insensitive, or 
                                   'sql-unspecified, or 
                                   'sql-sensitive
 'sql-dynamic-cursor-attributes1   a list with elements chosen from
				     '(sql-ca1-next sql-ca1-absolute
                                       sql-ca1-relative sql-ca1-bookmark
                                       sql-ca1-lock-exclusive 
                                       sql-ca1-lock-no-change
                                       sql-ca1-lock-unlock sql-ca1-pos-position
                                       sql-ca1-pos-update sql-ca1-pos-delete
                                       sql-ca1-pos-refresh 
                                       sql-ca1-positioned-update
                                       sql-ca1-positioned-delete
                                       sql-ca1-select-for-update
                                       sql-ca1-bulk-add
                                       sql-ca1-bulk-update-by-bookmark
                                       sql-ca1-bulk-delete-by-bookmark
                                       sql-ca1-bulk-fetch-by-bookmark)
 'sql-dynamic-cursor-attributes2   a list with elements chosen from 
				     '(sql_ca2_read_only_concurrency
				       sql_ca2_lock_concurrency
	                               sql_ca2_opt_rowver_concurrency
                                       sql_ca2_opt_values_concurrency
                                       sql_ca2_sensitivity_additions
                                       sql_ca2_sensitivity_deletions
                                       sql_ca2_sensitivity_updates
                                       sql_ca2_max_rows_select
                                       sql_ca2_max_rows_insert
                                       sql_ca2_max_rows_delete
                                       sql_ca2_max_rows_update
                                       sql_ca2_max_rows_catalog
                                       sql_ca2_max_rows_affects_all
                                       sql_ca2_crc_exact
                                       sql_ca2_crc_approximate
                                       sql_ca2_simulate_non_unique
                                       sql_ca2_simulate_try_unique
                                       sql_ca2_simulate_unique)
 'sql-forward-only-cursor-attributes1 
                                   same as for 'sql-keyset-cursor-attributes1  
 'sql-forward-only-cursor-attributes2 
                                   same as for 'sql-keyset-cursor-attributes2  
 'sql-index-keywords                 a list with elements chosen from  
                                      '(sql-ik-asc sql-ik-desc)
 'sql-info-schema-views            a list with elements chosen from      
				    '(sql-isv-assertions 
                                      sql-isv-character-sets
				      sql-isv-check-constraints 
                                      sql-isv-collations
				      sql-isv-column-domain-usage
                                      sql-isv-column-privileges 
                                      sql-isv-columns
                                      sql-isv-constraint-column-usage
                                      sql-isv-constraint-table-usage
                                      sql-isv-domain-constraints
                                      sql-isv-domains 
                                      sql-isv-key-column-usage
				      sql-isv-referential-constraints
				      sql-isv-schemata 
                                      sql-isv-sql-languages
				      sql-isv-table-constraints 
				      sql-isv-table-privileges
                                      sql-isv-tables sql-isv-translations
				      sql-isv-usage-privileges 
                                      sql-isv-view-column-usage
                                      sql-isv-view-table-usage)
 'sql-insert-statement             a list with elements chosen from  
				    '(sql-is-insert-literals
                                      sql-is-insert-searched
                                      sql-is-select-into)
 'sql-integrity                    boolean
 'sql-keyset-cursor-attributes1    same as for 'sql-dynamic-cursor-attributes1
 'sql-keyset-cursor-attributes2    same as for 'sql-dynamic-cursor-attributes2
 'sql-max-async-concurrent-statements unsigned integer
 'sql-max-catalog-name-len         unsigned integer
 'sql-max-concurrent-activities    unsigned integer
 'sql-max-driver-connections       unsigned integer
 'sql-max-identifier-len           unsigned integer  
 'sql-max-schema-name-len          unsigned integer
 'sql-odbc-interface-conformance   'sql-oic-core, or
                                   'sql-oic-level1, or
                                   'sql-oic-level2 
 'sql-param-array-row-counts       'sql-parc-batch or 'sql-parc-no-batch
 'sql-param-array-selects          'sql-pas-batch, or 'sql-pas-no-batch, or
                                   'sql-pas-no-select
 'sql-schema-term                  string
 'sql-schema-usage                 a list with elements chosen from  
                                    '(sql-su-dml-statements
                                      sql-su-procedure-invocation
                                      sql-su-table-definition
                                      sql-su-index-definition
                                      sql-su-privilege-definition)
 'sql-sql-conformance              'sql-sc-sql92-entry, or 
                                   'sql-sc-fips127-2-transitional, or
                                   'sql-sc-sql92-full, or
                                   'sql-sc-sql92-intermediate, or
 'sql-sql92-datetime-functions     a list with elements chosen from  
                                    '(sql-sdf-current-date
                                      sql-sdf-current-time
                                      sql-sdf-current-timestamp)
 'sql-sql92-foreign-key-delete-rule
                                   a list with elements chosen from  
                                    '(sql-sfkd-cascade
                                      sql-sfkd-no-action
                                      sql-sfkd-set-default
                                      sql-sfkd-set-null)
 'sql-sql92-foreign-key-update-rule
                                   a list with elements chosen from  
                                    '(sql-sfku-cascade
                                      sql-sfku-no-action
                                      sql-sfku-set-default
                                      sql-sfku-set-null)
 'sql-sql92-grant                  a list with elements chosen from  
                                    '(sql-sg-delete-table
                                      sql-sg-insert-column
                                      sql-sg-insert-table
                                      sql-sg-references-table
                                      sql-sg-references-column
                                      sql-sg-select-table
                                      sql-sg-update-column
                                      sql-sg-update-table
                                      sql-sg-usage-on-domain
                                      sql-sg-usage-on-character-set
                                      sql-sg-usage-on-collation
                                      sql-sg-usage-on-translation
                                      sql-sg-with-grant-option)
 'sql-sql92-numeric-value-functions
                                   a list with elements chosen from  
                                      '(sql-snvf-bit-length
                                        sql-snvf-char-length
                                        sql-snvf-character-length
                                        sql-snvf-extract
                                        sql-snvf-octet-length
                                        sql-snvf-position)
 'sql-sql92-predicates             a list with elements chosen from  
                                    '(sql-sp-between
                                      sql-sp-comparison
                                      sql-sp-exists
                                      sql-sp-in
                                      sql-sp-isnotnull
                                      sql-sp-isnull
                                      sql-sp-like
                                      sql-sp-match-full
                                      sql-sp-match-partial
                                      sql-sp-match-unique-full
                                      sql-sp-match-unique-partial
                                      sql-sp-overlaps
                                      sql-sp-quantified-comparison
                                      sql-sp-unique)
 'sql-sql92-relational-join-operations 
                                   a list with elements chosen from  
                                    '(sql-srjo-corresponding-clause
                                      sql-srjo-cross-join
                                      sql-srjo-except-join
                                      sql-srjo-full-outer-join
                                      sql-srjo-inner-join
                                      sql-srjo-intersect-join
                                      sql-srjo-left-outer-join
                                      sql-srjo-natural-join
                                      sql-srjo-right-outer-join
                                      sql-srjo-union-join)
 'sql-sql92-revoke                 a list with elements chosen from  
                                    '(sql-sr-cascade
                                      sql-sr-delete-table
                                      sql-sr-grant-option-for
                                      sql-sr-insert-column
                                      sql-sr-insert-table
                                      sql-sr-references-column
                                      sql-sr-references-table
                                      sql-sr-restrict
                                      sql-sr-select-table
                                      sql-sr-update-column
                                      sql-sr-update-table
                                      sql-sr-usage-on-domain
                                      sql-sr-usage-on-character-set
                                      sql-sr-usage-on-collation
                                      sql-sr-usage-on-translation)
 'sql-sql92-row-value-constructor  a list with elements chosen from  
                                    '(sql-srvc-value-expression
                                      sql-srvc-null
                                      sql-srvc-default
                                      sql-srvc-row-subquery)
 'sql-sql92-string-functions       a list with elements chosen from  
                                    '(sql-ssf-convert
                                      sql-ssf-lower
                                      sql-ssf-upper
                                      sql-ssf-substring
                                      sql-ssf-translate
                                      sql-ssf-trim-both
                                      sql-ssf-trim-leading
                                      sql-ssf-trim-trailing)
 'sql-sql92-value-expressions      a list with elements chosen from  
                                    '(sql-sve-case
                                      sql-sve-cast
                                      sql-sve-coalesce
                                      sql-sve-nullif)
 'sql-standard-cli-conformance     a list with elements chosen from 
                                    '(sql-scc-xopen-cli-version1 
                                      sql-scc-iso92-cli)
 'sql-static-cursor-attributes1    same as for 'sql-dynamic-cursor-attributes1  
 'sql-static-cursor-attributes2    same as for 'sql-dynamic-cursor-attributes2
 'sql-xopen-cli-year               string

> (get-functions hdbc fn)

 ODBC 1.0.

 For the driver that supports the connection indicated by the connection
 handle `hdbc', get-functions indicates whether the function or set 
 of functions denoted by the symbol `fn' is supported by the driver.

 For ODBC 2.0 or later, `fn' may be 'sql-api-all-functions.  
 In that case, get-functions returns a list of two-element lists in which 
 the first element is a symbol indicating a function name, and
 the second element is #t if the driver supports the function,
 otherwise #f.  The function names in the list are those below indicated 
 as ODBC 2.0 or earlier.

 For ODBC 3.0 or greater, `fn' may be 'sql-api-odbc3-all-functions.  
 In that case, get-functions returns a list of two-element lists in which 
 the first element is a symbol indicating a function name, and
 the second element is #t if the driver supports the function,
 otherwise #f.  The function names in the list include those from ODBC 3.0, 
 and those from ODBC 2.0 and earlier.

 `fn' may also be one of the symbols in the following list of functions.
 In this case, get-functions returns #t if the function is supported,
 #f otherwise.
  
 [ODBC 2.0 and earlier]
 'sql-api-sqlbindcol
 'sql-api-sqlcancel
 'sql-api-sqlconnect
 'sql-api-sqlgetfunctions
 'sql-api-sqlgetinfo
 'sql-api-sqldatasources
 'sql-api-sqldescribecol
 'sql-api-sqlgettypeinfo
 'sql-api-sqldisconnect
 'sql-api-sqlnumresultcols
 'sql-api-sqldrivers
 'sql-api-sqlparamdata
 'sql-api-sqlprepare
 'sql-api-sqlexecdirect
 'sql-api-sqlputdata
 'sql-api-sqlexecute
 'sql-api-sqlrowcount
 'sql-api-sqlfetch
 'sql-api-sqlsetcursorname
 'sql-api-sqlfreestmt
 'sql-api-sqlgetcursorname
 'sql-api-sqlgetdata
 'sql-api-sqlcolumns
 'sql-api-sqlstatistics
 'sql-api-sqlspecialcolumns
 'sql-api-sqltables
 'sql-api-sqlbindparameter
 'sql-api-sqlnativesql
 'sql-api-sqlbrowseconnect
 'sql-api-sqlnumparams
 'sql-api-sqlprimarykeys
 'sql-api-sqlcolumnprivileges
 'sql-api-sqlprocedurecolumns
 'sql-api-sqldescribeparam
 'sql-api-sqlprocedures
 'sql-api-sqldriverconnect
 'sql-api-sqlsetpos
 'sql-api-sqlforeignkeys
 'sql-api-sqltableprivileges
 'sql-api-sqlmoreresults

 [ODBC 3.0]
 'sql-api-sqlallochandle
 'sql-api-sqlgetdescfield
 'sql-api-sqlgetdescrec
 'sql-api-sqlgetdiagfield
 'sql-api-sqlclosecursor
 'sql-api-sqlgetdiagrec
 'sql-api-sqlcolattribute
 'sql-api-sqlgetenvattr
 'sql-api-sqlcopydesc
 'sql-api-sqlgetstmtattr
 'sql-api-sqlendtran
 'sql-api-sqlsetconnectattr
 'sql-api-sqlfetchscroll
 'sql-api-sqlfreehandle
 'sql-api-sqlgetconnectattr
 'sql-api-sqlsetdescfield
 'sql-api-sqlsetdescrec
 'sql-api-sqlsetenvattr
 'sql-api-sqlsetstmtattr
 'sql-api-sqlbulkoperations

> (get-connect-attr hdbc attr)

 ODBC 3.0. 

 For the connection handle `hdbc', returns the value of an attribute 
 given by the symbol `attr'.  The permissible values of `attr' and
 the corresponding ranges of return values are:

  'sql-attr-access-mode        'sql-mode-read-only, 'sql-mode-read-write
  'sql-attr-async-enable       'sql-async-enable-off, 'sql-async-enable-on
  'sql-attr-autocommit         'sql-autocommit-off, 'sql-autocommit-on
  'sql-attr-auto-ipd           boolean
  'sql-attr-connection-dead    'sql-cd-true, 'sql-cd-false
  'sql-attr-connection-timeout exact integer
  'sql-attr-current-catalog    string
  'sql-attr-login-timeout      exact integer
  'sql-attr-metadata-id        boolean
  'sql-attr-odbc-cursors       'sql-cur-use-if-needed, 
                               'sql-cur-use-odbc, 
                               'sql-cur-use-driver
  'sql-attr-packet-size        exact integer
  'sql-attr-quiet-mode         exact integer
  'sql-attr-trace              exact integer  
  'sql-attr-tracefile          string 
  'sql-attr-translate-lib      string
  'sql-attr-translate-option   exact intger
  'sql-attr-txn-isolation      'sql-txn-read-uncommitted, 
                               'sql-txn-read-committed, 
                               'sql-txn-repeatable-read, 
			       'sql-txn-serializable

 See an ODBC reference for the significance of these connection attributes.
 Driver-specific attributes are not supported.

> (get-connect-option hdbc option) 

 ODBC 1.0, deprecated in favor of get-connect-attr. 

 For a connection handle `hdbc', returns the value of the 
 connection option specified by the symbol `option'.  
 The permisible values of `option' are 

  'sql-access-mode 
  'sql-autocommit 
  'sql-login-timeout
  'sql-opt-trace    
  'sql-opt-tracefile
  'sql-translate-dll
  'sql-translate-option
  'sql-txn-isolation
  'sql-current-qualifier
  'sql-odbc-cursors
  'sql-quiet-mode 
  'sql-packet-size

 The return values are as for `get-connect-attr' for the corresponding
 attributes.  In that procedure, the corresponding attributes have `-attr-' 
 in their symbols.

> (set-connect-attr hdbc attr val)

 ODBC 3.0.

 For a connection handle `hdbc', sets the attribute indicated by the 
 symbol `attr' to be `val'.  The type of `val' depends on `attr', 
 as follows:

  'sql-attr-access-mode        'sql-mode-read-only, 'sql-mode-read-write
  'sql-attr-async-enable       'sql-async-enable-off, 'sql-async-enable-on
  'sql-attr-autocommit         'sql-autocommit-off, 'sql-autocommit-on
  'sql-attr-connection-timeout exact integer
  'sql-attr-current-catalog    string
  'sql-attr-login-timeout      exact integer
  'sql-attr-metadata-id        boolean
  'sql-attr-odbc-cursors       'sql-cur-use-if-needed, 
                               'sql-cur-use-odbc, 
                               'sql-cur-use-driver
  'sql-attr-packet-size        exact integer
  'sql-attr-quiet-mode         exact integer
  'sql-attr-trace              exact integer  
  'sql-attr-tracefile          string 
  'sql-attr-translate-lib      string
  'sql-attr-translate-option   exact intger
  'sql-attr-txn-isolation      'sql-txn-read-uncommitted, 
                               'sql-txn-read-committed, 
                               'sql-txn-repeatable-read, 
			       'sql-txn-serializable

 Returns the value of `hdbc'.

 Note that some connection attributes listed in the documentation
 for `get-connect-attr' are not settable.  The type boolean 
 above indicates that any Scheme value other than #f is
 interpreted as true.

 See an ODBC reference for the significance of these connection attributes.
 Driver-specific attributes are not supported.

> (set-connect-option hdbc option val) 

 ODBC 1.0, deprecated in favor of set-connect-attr. 

 For a connection handle `hdbc', sets the option indicated by the 
 symbol `option' to be `val'.  The type of `val' depends on `attr'.
 The permisible values of `option' are: 

  'sql-access-mode 
  'sql-autocommit 
  'sql-login-timeout
  'sql-opt-trace    
  'sql-opt-tracefile
  'sql-translate-dll
  'sql-translate-option
  'sql-txn-isolation
  'sql-current-qualifier
  'sql-odbc-cursors
  'sql-quiet-mode 
  'sql-packet-size

 The type of `val' depends on `option', in the same way as corresponding
 attributes in `set-connect-attr'.  The corresponding attributes in that
 procedure have `-attr-' in their symbols.


 Statements and Parameters
 -------------------------

> (prepare hstmt sql)

 ODBC 1.0.

 Compiles the SQL statement given by the string `sql' for the 
 statement handle `hstmt'.  Returns the value of `hstmt'.  Once 
 an SQL statement has been compiled for a statement handle, 
 `sql-execute' can be called as many times as desired using that handle.
 
> (sql-execute hstmt)

 ODBC 1.0.

 Executes the SQL statement associated with the statement handle 
 `hstmt'.  The SQL statement must have been compiled using
 `sql-prepare'.  When a statement executes, its parameters,
 indicated by ?'s in the SQL text, are replaced by the values
 bound to those parameters.  See `bind-parameter' and `bind-param'.
 The value of `hstmt' is returned.

> (exec-direct hstmt sql)

 ODBC 1.0.

 Compiles and executes the SQL statement `sql', a string, and 
 associates that statement with the statement handle `hstmt'.  
 When a statement executes, its parameters, indicated by ?'s in 
 the SQL text, are replaced by the values bound to those parameters. 
 See `bind-parameter' and `bind-param'.  The value of `hstmt' is
 returned.

> (native-sql hdbc sql)

 ODBC 1.0.

 Given a connection handle `hdbc' and an SQL statement `sql', returns 
 a string indicating the SQL that would be passed to the
 data source associated with the handle.

> (param-data hstmt)

 ODBC 1.0.

 Returns the sql-buffer that is bound to the statement handle 
 `hstmt'.  If no such buffer exists, an error occurs.

> (put-data hstmt buff)

 ODBC 1.0.

 Given the statement handle `hstmt' and an sql-buffer `buff',
 sends the buffer data to either 1) the parameter associated
 with the statement, or 2) the column associated with the
 statement, for use with bulk-operations or set-pos.  Returns the
 value of `hstmt'.

> (cancel hstmt)

 ODBC 1.0.

 Terminates processing of the statement given by the statement handle
 `hstmt'.  Returns the value of `hstmt'.

> (end-tran handle action)

 ODBC 3.0.

 Requests a commit or rollback for all transactions associated with 
 `handle', which may be either an environment handle or a 
 connection handle.  `action' is one of the symbols 
 'sql-commit or 'sql-rollback.  Returns the value of `handle'.

> (transact henv hdbc action)

 ODBC 1.0, deprecated in favor of end-tran.

 Requests a commit or rollback for all transactions associated with 
 either the environment handle `henv' or the connection handle `hdbc'. 
 `action' is one of the symbols 'sql-commit or 'sql-rollback.
 If `hdbc' is the symbol 'sql-null-hdbc, the action is performed
 for the environment handle; otherwise, it is performed for the
 connection handle.  Returns void.

> (num-params hstmt)

 ODBC 1.0.

 Returns the number of parameters (placeholders indicated by a ?)
 in the SQL associated with the statement handle `hstmt'.
 The `prepare' procedure must be called before calling this 
 procedure.

> (bind-parameter hstmt num param-type sql-type col-size buff ind [digits])

 ODBC 2.0.

 Associates the sql-buffer `buff' with the parameter (a placeholder 
 indicated by ? in an SQL statement) denoted by the statement 
 handle `hstmt' and positive integer `num'.  The param-type is
 one of the symbols 'sql-param-input, 'sql-param-output, or
 'sql-param-input-output.  `sql-type' is an SQL data type.
 `col-size' is the number of bytes to be sent from the buffer 
 to the parameter, or, if `sql-data-type' is any of 'sql-decimal,
 'sql-numeric, 'sql-float, 'sql-real, or 'sql-double, the number of
 digits of precision used.  `ind' is an sql-indicator. The optional 
 argument `digits' indicates the number of digits to the right of the 
 decimal point, and is used if `sql-data-type' is 'sql-decimal, 
 'sql-numeric, 'sql-time, 'sql-timestamp, 'sql-type-time, 
 'sql-type-timestamp, 'sql-interval-second,  'sql-interval-day-to-second,  
 'sql-interval-hour-to-second, or 'sql-interval-minute-to-second.
 Returns the value of `hstmt'.

 The `prepare' procedure must be called before calling `bind-parameter'.

> (param-options hstmt numrows)

 ODBC 1.0, deprecated in favor of set-stmt-attr.

 For the statement handle `hstmt', indicates to the ODBC driver the 
 number of rows associated with each parameter.  `numrows' is 
 an exact positive integer.  Returns the current row number.

> (describe-param hstmt pos)

 ODBC 1.0.

 For the statement handle `hstmt', returns information about the
 parameter at position `pos', a positive exact integer.  The
 returned information is a list consisting of

	- a symbol indicating an SQL data type, 
	- an exact integer that denotes, depending on the data type, 
           either the number of bytes expected by a data source for 
	   the parameter, or the precision associated with the data type
	- an exact integer denoting the number of trailing decimal digits 
           expected in the column or expression associated with the parameter
	- a symbol indicating the parameter may be associated with
	   NULLs, either 'sql-no-nulls, 'sql-nullable, or
           'sql-nullable-unknown.

> (bind-param hstmt num sql-type col-size buff ind [digits])

 ODBC 3.0, deprecated in favor of bind-parameter.

 Associates the sql-buffer `buff' with the parameter (a placeholder 
 indicated by ? in an SQL statement) denoted by the statement 
 handle `hstmt' and positive integer `num'. The arguments are as 
 for the same-named arguments of procedure `bind-parameter'; some arguments
 are omitted for `bind-param'.  Note that `bind-param' always 
 assumes an input parameter, unlike `bind-parameter', which takes 
 an argument to indicate the parameter type.  Returns the value 
 of `hstmt'.

> (set-param hstmt num sql-type buff ind)

 ODBC 1.0, deprecated in favor of bind-parameter.

 Associates the sql-buffer `buff' with the parameter (a placeholder 
 indicated by ? in an SQL statement) denoted by the statement 
 handle `hstmt' and positive integer `num'.  `sql-type' is an SQL 
 data type.  `ind' is an sql-indicator.  Returns the value of 
 `hstmt'. 

> (get-stmt-attr hstmt attr)

 ODBC 3.0.

 For the statement handle `hstmt', returns the value of its 
 associated attribute `attr'.  The statement handle attributes 
 and their possible values are:

   attr                               returns      
   ----                               ------- 
   'sql-attr-app-param-desc           an APD descriptor handle
   'sql-attr-app-row-desc             an ARD descriptor handle
   'sql-attr-async-enable             'sql-async-enable-off, or
                                      'sql-async-enable-on
   'sql-attr-concurrency              'sql-concur-read-only, or
                                      'sql-concur-lock, or
                                      'sql-concur-rowver, or
                                      'sql-concur-values
   'sql-attr-cursor-scrollable        'sql-nonscrollable, or
                                      'sql-scrollable
   'sql-attr-cursor-sensitivity       'sql-insensitive, or
                                      'sql-sensitive, or
                                      'sql-unspecified
   'sql-attr-cursor-type              'sql-cursor-forward-only, or
                                      'sql-cursor-static, or
                                      'sql-cursor-keyset-driven, or
                                      'sql-cursor-dynamic
   'sql-attr-enable-auto-ipd          boolean
   'sql-attr-fetch-bookmark-ptr       unsigned integer
   'sql-attr-imp-param-desc           an IPD descriptor handle
   'sql-attr-imp-row-desc             an IRD descriptor handle
   'sql-attr-keyset-size              unsigned integer
   'sql-attr-max-length               unsigned integer
   'sql-attr-max-rows                 unsigned integer
   'sql-attr-metadata-id              boolean
   'sql-attr-noscan                   'sql-noscan-off, or
                                      'sql-noscan-on
   'sql-attr-param-bind-offset-ptr    sql-boxed-uint 
   'sql-attr-param-bind-type          'sql-param-bind-by-column, or
                                      unsigned integer
   'sql-attr-param-operation-ptr      sql-op-parms (see read-op-parms, below)
   'sql-attr-param-status-ptr         row-status (see below)
   'sql-attr-params-processed-ptr     sql-boxed-uint
   'sql-attr-paramset-size            unsigned integer
   'sql-attr-query-timeout            unsigned integer  
   'sql-attr-retrieve-data            'sql-rd-on, or
                                      'sql-rd-off
   'sql-attr-row-array-size           unsigned integer
   'sql-attr-row-bind-offset-ptr      sql-boxed-uint 
   'sql-attr-row-bind-type            'sql-bind-by-column, or
                                      unsigned integer
   'sql-attr-row-number               unsigned integer
   'sql-attr-row-operation-ptr        op-parms (see read-op-parms, below)
   'sql-attr-row-status-ptr           row-status (see read-row-status, below)
   'sql-attr-rows-fetched-ptr         sql-boxed-uint
   'sql-attr-simulate-cursor          'sql-sc-non-unique, or
                                      'sql-sc-try-unique, or
                                      'sql-sc-unique
   'sql-attr-use-bookmarks            'sql-ub-off, or
                                      'sql-ub-variable, or
                                      'sql-ub-on 

 See an ODBC reference for information about the significance of
 these attributes.  The type `sql-boxed-uint' is a Scheme representation
 of a pointer value.  See `make-boxed-uint' and `read-boxed-uint', below.
 An instance of the type `sql-op-parms' is a value that encapsulates an 
 array whose elements are either 'sql-param-proceed or
 'sql-param-ignore.  See `read-op-parms', below.  An instance
 of the type `sql-row-status' encapsulates an array, one element for 
 each parameter in the statement, each with one of the values:

     'sql-param-success 
     'sql-param-success-with-info
     'sql-param-error
     'sql-param-unused
     'sql-param-diag-unavilable

> (get-stmt-option hstmt option)

 ODBC 1.0, deprecated in favor of get-stmt-attr.

 For the statement handle `hstmt', returns the value of its 
 associated `option'.  The statement handle options 
 and their return values are:

   option                             returns      
   ------                             ------- 
   'sql-async-enable                  'sql-async-enable-off, or
                                      'sql-async-enable-on
   'sql-bind-type                     'sql-param-bind-by-column, or
                                      unsigned integer
   'sql-concurrency                   'sql-concur-read-only, or
                                      'sql-concur-lock, or
                                      'sql-concur-rowver, or
                                      'sql-concur-values
   'sql-cursor-type                   'sql-cursor-forward-only, or
                                      'sql-cursor-static, or
                                      'sql-cursor-keyset-driven, or
                                      'sql-cursor-dynamic
   'sql-keyset-size                   unsigned integer
   'sql-max-length                    unsigned integer
   'sql-max-rows                      unsigned integer
   'sql-noscan                        'sql-noscan-off, or
                                      'sql-noscan-on
   'sql-query-timeout                 unsigned integer  
   'sql-retrieve-data                 'sql-rd-on, or
                                      'sql-rd-off
   'sql-rowset-size                   unsigned integer
   'sql-simulate-cursor               'sql-sc-non-unique, or
                                      'sql-sc-try-unique, or
                                      'sql-sc-unique
   'sql-use-bookmarks                 'sql-ub-off, or
                                      'sql-ub-variable, or
                                      'sql-ub-on 

 See an ODBC reference for the significance of these options.

> (set-stmt-attr hstmt attr val)
  
 ODBC 3.0.

 For the statement handle `hstmt', sets its associated attribute `attr'
 to the value `val'.  See `get-stmt-attr' for attributes and 
 their possible values.  Returns the value of `hstmt'. 

> (set-stmt-option hstmt attr val)
  
 ODBC 1.0, deprecated in favor of set-stmt-attr.

 For the statement handle `hstmt', sets its associated `option'
 to the value `val'.  See `get-stmt-option' for options and 
 their possible values.  Returns the value of `hstmt'.

 Descriptors
 -----------

> (copy-desc hdesc-src hdesc-target)

 ODBC 3.0.

 Copies information from descriptor handle `hdesc-src' to
 descriptor handle `hdesc-target'.  Returns the value of 
 `hdesc-src'.

> (get-desc-rec hdesc recnum)

 ODBC 3.0.

 Given a descriptor handle `hdesc' and record number 
 `recnum', a positive exact integer, returns a list 
 of values pertaining to the descriptor record.  The first
 element of that list is a string, the name of the parameter or column 
 associated with the descriptor record; the second element
 is a symbol indicating a concise SQL data type (see SQL data
 types, below); the third element is a symbol that indicates an 
 interval subtype for the types 'sql-datetime or 'sql-interval, 
 otherwise 'no-subtype; the fourth element is an exact integer 
 indicating the byte length of the parameter or column; the fifth 
 element is an exact integer indicating the number of digits of 
 precision for the parameter or column (only relevant for numeric data 
 types); the sixth element is an exact integer indicating the number of
 digits to the right of the decimal point used for data in the
 column or parameter; while the seventh element is one of 
 'sql-no-nulls, 'sql-nullable, or 'sql-nullable-unknown, indicating
 whether the parameter or column may have NULL values.

> (set-desc-rec hdesc recnum type subtype length precision scale buff len ind)

 ODBC 3.0.

 For the descriptor record denoted by the descriptor handle `hdesc' and
 positive exact integer `recnum', sets its associated information.
 `type' is a symbol indicating a concise SQL or C data type (see SQL data
 types, below); `subtype' is a symbol indicating a subtype for the types 
 'sql-datetime or 'sql-interval, or it may be 'no-subtype; 
 `len' is an sql-length (see make-length and read-length, below), which 
 should be initialized to the desired length of the column or parameter 
 associated with the descriptor record; `ind' is an sql-indicator
 (see Indicators, below).  Returns the value of `hdesc'.

> (get-desc-field hdesc recnum field)

 ODBC 3.0.

 For the descriptor handle `hdesc', returns the value of a field
 in the descriptor record with index `recnum', an integer. `field' is a 
 symbol indicating the field within that record.

 Valid values of `field' and their return types are listed below.
 Please consult an ODBC reference for the significance of these
 fields.

 field                                    returns
 -----                                    -------
 'sql-desc-alloc-type                     integer
 'sql-desc-array-size                     unsigned integer
 'sql-desc-array-status-ptr               array status indicator
 'sql-desc-bind-offset-ptr                binding offset
 'sql-desc-bind-type                      integer
 'sql-desc-count                          integer
 'sql-desc-rows-processed-ptr             rows-processed
 'sql-desc-auto-unique-value              integer
 'sql-desc-base-column-name               string 
 'sql-desc-case-sensitive                 boolean
 'sql-desc-concise-type                   SQL data type 
 'sql-desc-base-table-name                string
 'sql-desc-catalog-name                   string
 'sql-desc-data-ptr                       sql-buffer 
 'sql-desc-datetime-interval-code         'sql-code-date, or 
                                          'sql-code-time, or
                                          'sql-code-timestamp, or
                                          'sql-code-day, or
                                          'sql-code-day-to-hour, or
                                          'sql-code-day-to-minute, or
                                          'sql-code-day-to-second, or
                                          'sql-code-hour, or
                                          'sql-code-hour-to-minute, or
                                          'sql-code-hour-to-second, or 
                                          'sql-code-minute, or
                                          'sql-code-minute-to-second, or
                                          'sql-code-month, or
                                          'sql-code-second, or
                                          'sql-code-year, or
                                          'sql-code-year-to-month
 'sql-desc-datetime-interval-precision    integer
 'sql-desc-display-size                   integer 
 'sql-desc-fixed-prec-scale               boolean
 'sql-desc-indicator-ptr                  sql-indicator
 'sql-desc-label                          string
 'sql-desc-length                         unsigned length
 'sql-desc-literal-prefix                 string
 'sql-desc-literal-suffix                 string
 'sql-desc-local-type-name                string
 'sql-desc-name                           string
 'sql-desc-nullable                       'sql-nullable, or 
                                          'sql-no-nulls, or 
                                          'sql-nullable-unknown
 'sql-desc-num-prec-radix                 integer
 'sql-desc-octet-length                   integer
 'sql-desc-octet-length-ptr               octet-length
 'sql-desc-parameter-type                 'sql-param-input, or 
                                          'sql-param-output, or 
                                          'sql-param-input-output
 'sql-desc-precision                      integer
 'sql-desc-rowver                         boolean
 'sql-desc-scale                          integer
 'sql-desc-schema-name                    string
 'sql-desc-searchable                     for ODBC 3.0 or greater:
                                          'sql-pred-char, or 
                                          'sql-pred-basic, or 
                                          'sql-pred-none, or 
					  'sql-pred-searchable 
                                          for earlier versions:
                                          'sql-all-except-like, or
                                          'sql-like-only, or 
					  'sql-searchable, or 
                                          'sql-unsearchable
 'sql-desc-table-name                     string
 'sql-desc-type                           SQL data type (except intervals)
 'sql-desc-type-name                      string
 'sql-desc-unnamed                        'sql-named or 'sql-unnamed
 'sql-desc-unsigned                       boolean
 'sql-desc-updatable                      'sql-attr-readonly, or
                                          'sql-attr-write, or
                                          'sql-attr-readwrite-unknown

> (set-desc-field hdesc recnum field val)
  
 ODBC 3.0.

 For the descriptor handle `hdesc', sets the field indicated 
 by the symbol `field' in the record with index `recnum', an integer, 
 to the value `val'.  See get-desc-field for valid values of 
 `field' and corresponding types for `val'.  Returns the value of 
 `hdesc'.

 Cursors
 -------

> (get-cursor-name hstmt)

  ODBC 1.0.

  Returns a string naming the cursor associated with the statement 
  handle `hstmt'.

> (set-cursor-name hstmt name)

  ODBC 1.0.

  Assigns the string `name' as the name of the cursor associated with 
  the statement handle `hstmt'.  Returns the value of `hstmt'.

> (close-cursor hstmt)

  ODBC 3.0.

  Closes the cursor associated with the statement handle `hstmt',
  discarding any pending results.  Returns the value of `hstmt'.

 Columns and data retrieval
 -------------------------------

 Data in a relational database is organized into tables consisting
 of rows and columns.  A column corresponds to a field in the
 database.  A row is an individual data record. 

> (num-result-cols hstmt)

 ODBC 1.0.

 Returns the number of data columns in the data set associated with
 the statement handle `hstmt'.

> (describe-col hstmt colnum)

 ODBC 1.0.

 Given the statement handle `hstmt' and the exact integer `colnum', 
 indicating a column number, returns a list of information describing
 a column in a data set.  The first element in the list is a 
 string giving the name of the column; the second element is a 
 symbol indicating its SQL data type (see SQL data types, below);
 the third element is the maximum byte length of data for the 
 column; the fourth element is either the number of digits to the right
 of the decimal point, for relevant data types (see SQL data types), 
 otherwise 0; the fifth element is a symbol indicating whether the column 
 accepts NULL entries, either 'sql-no-nulls, 'sql-nullable, or
 'sql-nullable-unknown.

> (col-attribute hstmt colnum attr)

 ODBC 3.0.

 Given the statement handle `hstmt', an exact integer `colnum', 
 indicating a column number, and the symbol `attr', indicating a
 column attribute, returns the value of the column attribute.
 Columns are numbered starting at 1.  The attributes and their 
 associated types are

   attr                             returns
   ----                             -------
   'sql-desc-count                  integer
   'sql-desc-auto-unique-value      boolean
   'sql-desc-base-column-name       string
   'sql-desc-base-table-name        string
   'sql-desc-case-sensitive         boolean
   'sql-desc-catalog-name           string
   'sql-desc-concise-type           SQL data type 
   'sql-desc-data-ptr               sql-buffer
   'sql-desc-display-size           integer
   'sql-desc-fixed-prec-scale       boolean
   'sql-desc-label                  string
   'sql-desc-length                 integer
   'sql-desc-literal-prefix         string
   'sql-desc-literal-suffix         string
   'sql-desc-local-type-name        string
   'sql-desc-name                   string
   'sql-desc-nullable               'sql-nullable, or
                                    'sql-no-nulls, or
                                    'sql-nullable-unknown 
   'sql-desc-num-prec-radix         integer
   'sql-desc-octet-length           integer
   'sql-desc-precision              integer
   'sql-desc-scale                  integer 
   'sql-desc-schema-name            string
   'sql-desc-searchable             ODBC 3.0 or greater:
                                    'sql-pred-char, or
                                    'sql-pred-basic, or
                                    'sql-pred-none, or
                                    'sql-pred-searchable
	                            earlier versions of ODBC:
                                    'sql-like-only, or
                                    'sql-all-except-like, or
                                    'sql-searchable, or 
                                    'sql-unsearchable
   'sql-desc-table-name             string
   'sql-desc-type                   concise SQL data type 
   'sql-desc-type-name              string
   'sql-desc-unnamed                'sql-named, or
                                    'sql-unnamed  
   'sql-desc-unsigned               boolean 
   'sql-desc-updatable              'sql-attr-readonly, or
                                    'sql-attr-write, or
                                    'sql-attr-readwrite-unknown

> (col-attributes hstmt colnum attr)

 ODBC 1.0, deprecated in favor of col-attribute.

 Given the statement handle `hstmt', an exact integer `colnum', 
 indicating a column number, and the symbol `attr', indicating a
 column attribute, returns the value of the column attribute.
 Columns are numbered starting at 1.  The attributes and their 
 associated types are

   attr                             returns
   ----                             -------
   'sql-column-count                integer
   'sql-column-name                 string
   'sql-column-type                 SQL data type 
   'sql-column-length               integer 
   'sql-column-precision            integer
   'sql-column-scale                integer
   'sql-column-display-size         integer
   'sql-column-nullable             'sql-no-nulls, or
                                    'sql-nullable
   'sql-column-unsigned             boolean
   'sql-column-money                boolean
   'sql-column-updatable            'sql-attr-readonly, or
                                    'sql-attr-write, or
                                    'sql-attr-readwrite-unknown 
   'sql-column-auto-increment       boolean
   'sql-column-case-sensitive       boolean
   'sql-column-searchable           'sql-searchable, or
                                    'sql-like-only, or
                                    'sql-all-except-like, or
                                    'sql-unsearchable   
   'sql-column-type-name            string 
   'sql-column-table-name           string
   'sql-column-owner-name           string
   'sql-column-qualifier-name       string 
   'sql-column-label                string

> (bind-col hstmt colnum buff ind)

 ODBC 1.0.

 Associates the sql-buffer `buff' and sql-indicator `ind' 
 with a column of data denoted by the statement handle `hstmt'
 and column numer `colnum', an integer.  Returns the value 
 of `hstmt'.  
 
> (fetch hstmt)

 ODBC 1.0.

 Retrieves data in the current row of the data set for 
 the statement handle `hstmt' into the sql-buffers
 bound to the data set's columns, and sets the columns' 
 associated sql-indicator's.  Returns the value of `hstmt'.
 For columns without bound sql-buffers, `get-data' can be used 
 to retrieve data following a `fetch'.  

> (get-data hstmt colnum buff ind)

 Retrieves data in the current row of the data set for 
 the column denoted by the statement handle `hstmt' 
 and column number `colnum', an integer, into the sql-buffer 
 `buff' and sets the sql-indicator `ind'.  Returns the value of 
 `hstmt'. `get-data' allows column data to be retrieved without 
 binding columns to buffers.

> (fetch-scroll hstmt orient [rownum])

 ODBC 3.0.

 Fetches multiple rows of data in a data set associated with
 the statement handle `hstmt'.  `orient' indicates which rows
 to fetch, and may be one of the symbols 

   'sql-fetch-first              first rowset 
   'sql-fetch-next               next rowset
   'sql-fetch-prior              previous rowset
   'sql-fetch-last               last rowset 
   'sql-fetch-absolute   *       rowset starting at `rownum'
   'sql-fetch-relative   *       rowset relative to current,
                                  using `rownum' (may be negative)
   'sql-fetch-bookmark   *       rowset relative to 
                                  'sql-attr-fetch-bookmark-ptr
                                  statement attribute

 The `rownum' parameter must be supplied when `orient' is one
 of those marked with `*' above.  fetch-scroll returns the value of 
 `hstmt'.  The size of rowsets is specified by the 
 'sql-attr-row-array-size statement attribute (see 
 `get-stmt-attr' and `set-stmt-attr').  See an ODBC reference for more 
 information on using rowsets.

> (set-scroll-options hstmt concurrency keyset size)

 ODBC 1.0, deprecated in favor of get-info and set-stmt-attr.

 Sets cursor scrolling options for the statement handle 
 `hstmt'.  `concurrency' is one of

   'sql-concur-read-only      updates and deletes not permitted
   'sql-concur-lock           updates and deletes permitted
   'sql-concur-rowver         compares row versions for concurrency 
                                control
   'sql-concur-values         compares values for concurrency control

 `keyset' is one of

   'sql-scroll-forward-only   only forward scrolling
   'sql-scroll-static         no scrolling
   'sql-scroll-keyset-driven  cursor uses keys for scrolling
   'sql-scroll-dynamic        use `size' parameter for keyset size

 `size', a nonnegative exact integer, gives the size of 
 rowsets when using `extended-fetch'.  Returns the value of `hstmt'.

> (extended-fetch hstmt orientation [rownum])

 ODBC 1.0, deprecated in favor of fetch-scroll.

 Retrieves a rowset from a result data set for the statement handle
 `hstmt' and returns a row-status value (see Row Status, below).
 `orientation' indicates which rowset is to be retrieved, one of

   'sql-fetch-first      first rowset in the data set
   'sql-fetch-next       next rowset in the data set
   'sql-fetch-prior      prior rowset in the data set
   'sql-fetch-last       last rowset in the data set
   'sql-fetch-absolute * fetches the rowset starting at the row
                           given by `rownum'
   'sql-fetch-relative * fetches the rowset `rownum' rows from
                           the start row of the current rowset
   'sql-fetch-bookmark * fetches the rowset, interpreting 
                           `rownum' as a bookmark

 The `rownum' argument is an integer, which may be negative.  
 It must be provided if `orientation' is one of those marked
 with `*' above.

> (more-results hstmt)

 ODBC 1.0.

 Retrieves the next data set for the statement handle `hstmt', whose
 value is returned by the procedure.  `more-results', which moves between 
 data sets, is distinguished from procedures such as `fetch', which return 
 results within data sets.  

> (set-pos hstmt rownum operation lock)

 ODBC 1.0.

 Sets a cursor position for the statement handle `hstmt'
 and updates the data source.  `rownum', a nonnegative exact 
 integer, specifies the ordinal position of the row within the 
 current rowset where `operation' is to occur.  A value of 0 
 indicates that the operation is to occur on every row in the
 rowset.
 
`operation' is one of 

   'sql-position   positions the cursor at the indicated row
   'sql-refresh    refreshes data in buffers associated with
                     the rowset indicated by `rownum'
   'sql-add        a new row is added to the data source (but see below)
   'sql-update     data in buffers is used to update the rowset
   'sql-delete     deletes the indicated row from the data source

 `set-pos' with 'sql-add is deprecated in favor of `bulk-operations' 
 with 'sql-add.
 
 `lock' indicates the lock status for the row or rows after the
 operation is performed, one of

   'sql-lock-no-change   use lock status before operation performed
   'sql-lock-exclusive   no other application or connection can
                           access
   'sql-lock-unlock      no lock restrictions on access 

 set-pos returns the value of `hstmt'.

> (bulk-operations hstmt operation)

 ODBC 3.0.

 Performs bulk inserts and bulk bookmark operations on the data source
 associated with the statement handle `hstmt'. `operation' may
 be one of

   'sql-add                  adds new rows
   'sql-update-by-bookmark   updates rows identified by a bookmark
   'sql-delete-by-bookmark   deletes rows identified by a bookmark
   'sql-fetch-by-bookmark    retrieves rows identified by a bookmark

 Returns the value of `hstmt'. 

 The details of using bulk-operations are beyond the scope of this
 documentation.  Consult an ODBC reference for more information.

> (row-count hstmt)

 ODBC 1.0.

 For the data source associated with the statement handle `hstmt', 
 returns the number of rows affected by the most recent INSERT, 
 UPDATE, or DELETE operation.

 Metadata
 --------

> (column-privileges hstmt catalog schema table column)

 ODBC 1.0.

 Creates a result data set describing column privileges in the current 
 data source.  There are at least eight columns in the resulting data set; a
 driver may add columns.  The contents of those columns are beyond the scope 
 of this documentation; consult an ODBC reference for details.
 
 `hstmt' is a statement handle, and its value is returned by the 
 procedure.  `catalog', `schema', `table', and `column' are strings.  
 `column' may contain an underscore "_" indicating a single-character 
 wildcard, or a percent sign "%", which matches zero or more characters.

> (columns hstmt catalog schema table column)

 ODBC 1.0. 

 Creates a result data set describing columns in the current data source.
 There are at least eighteen columns in the resulting data set; a
 driver may add columns.  The contents of those columns are beyond the scope 
 of this documentation; consult an ODBC reference for details.
 
 `hstmt' is a statement handle, whose value is returned by the procedure. 
 `catalog', `schema', `table', and `column' are strings.  `table' and 
 `column' may contain an underscore "_" indicating a single-character 
 wildcard, or a percent sign "%", which matches zero or more characters.

> (foreign-keys hstmt catalog schema table fk-catalog fk-schema fk-table)

 ODBC 1.0.

 Creates a result data set containing foreign key information for the
 specified table. There are fourteen ODBC-defined columns in the resulting 
 data set; a driver may add columns. The contents of those columns are beyond 
 the scope of this documentation; consult an ODBC reference for details.
 
 `hstmt' is a statement handle; its value is returned by the procedure.
 `catalog', `schema', `table', `fk-catalog', `fk-schema', and `fk-table' 
 are all strings.  `catalog', `schema', and `table' specify a table 
 containing a primary key, while  `fk-catalog', `fk-schema', and `fk-table' 
 specify a table containing a foreign key.

> (get-type-info hstmt type)

 ODBC 1.0.

 Given a statement handle `hstmt' and a symbol `type' indicating an 
 SQL data type (see SQL data types, below), creates a result data set 
 describing support for that data type in the current data source.
 Returns the value of `hstmt'.  There are at least nineteen columns in 
 the resulting data set; a driver may add columns.  The contents of 
 those columns are beyond the scope of this documentation; consult an
 ODBC reference for details.

> (primary-keys hstmt catalog schema table)

 ODBC 1.0.

 Creates a result data set containing the column names that make up the 
 primary  key for a table.  There are up to six ODBC-defined columns in 
 the resulting data set; a driver may add columns.  The contents of those 
 columns are beyond the scope of this documentation; consult an ODBC 
 reference for details.
 
 `hstmt' is a statement handle; its value is returned by the procedure.  
 `catalog', `schema', and `table' are strings.

> (procedure-columns hstmt catalog schema name column)

 ODBC 1.0.

 Creates a result data set containing the input and output parameters and
 columns associated with registered procedures in the current data source.
 There are nineteen ODBC-defined columns in the resulting data set; a 
 driver may add columns.  The contents of those columns are beyond the 
 scope of this documentation; consult an ODBC reference for details.

 `hstmt' is a statement handle; its value is returned by the procedure.  
 `catalog', `schema', `name', and `column' are strings.  `name' indicates 
 a procedure name, while `column' is a column name.  `schema', `name', and 
 `column' may contain an underscore "_" indicating a single-character 
 wildcard, or a percent sign "%", which matches zero or more characters.

> (procedures hstmt catalog schema name)

 ODBC 1.0.

 Creates a result data set containing the registered procedure names in the
 current data source.  There are eight ODBC-defined columns in the 
 resulting data set; a driver may add columns.  The contents of those 
 columns are beyond the scope of this documentation; consult an ODBC 
 reference for details.
 
 `hstmt' is a statement handle; its value is returned by the procedure.  
 `catalog', `schema', and `name' are strings.  `name' indicates a procedure 
 name.  Both `schema' and `name' may contain an underscore "_" indicating 
 a single-character wildcard, or a percent sign "%", which matches zero or 
 more characters.

> (table-privileges hstmt catalog schema table)

 ODBC 1.0.

 Creates a result data set describing tables in the system catalog.
 Such a data set consists of at least seven string columns, consisting of
 a catalog name, a schema name, a table name, the grantor of
 table privileges, the grantee, the name of the privilege, and
 a string indicating whether the grantee may transfer the privilege.  
 Valid privilege names are "SELECT", "INSERT", "UPDATE", and "DELETE". 
 The seventh column is either "YES", "NO", or a NULL.  Drivers may
 add additional columns.

 `hstmt' is a statement handle; its value is returned by the procedure.

 `catalog', `schema', and `table' are strings to be matched when
 searching the system catalog.  An underscore "_" indicates a 
 single-character wildcard; a percent sign "%" matches zero or more
 characters.

> (tables hstmt catalog schema table table-type)

 ODBC 1.0.

 Creates a result data set giving information about the tables 
 in the database system catalog.  Such a data set may be 
 processed as ordinary data.  The result data set has at least five 
 string columns, consisting of the catalog name, schema name, table
 name, table type, and descriptive remarks.  Drivers may add additional
 columns.  

 `hstmt' is a statement handle, and its value is returned by the
 procedure.

 `catalog', `schema', `table', and `table-type' are strings 
 to be matched when searching the system catalog.  `catalog' and
 `schema' may be empty strings for unnamed catalogs and schemas.
 In `catalog', `schema', and `table', an underscore "_" may be used 
 as a single-character wildcard, while a percent sign "%" may be 
 used to match zero or more arbitrary characters.

 The following remarks apply only to ODBC 3.0 or greater:

 `catalog' may also be the symbol 'sql-all-catalogs.  In that case, 
 if `schema' and `table' are empty strings, the result data set consists 
 of valid catalog names (the other columns are NULL's).

 `schema' may also be the symbol 'sql-all-schemas.  In that case, if 
 `catalog' and `table' are empty strings, the result data set
 consists of valid schema names (the other columns are NULL's).

 `table-type' may also be the symbol 'sql-all-table-types.  In that case,
 if `catalog', `schema, and `table' are empty strings, the result data set
 consists of valid table type names (the other columns are NULL's).

 End of ODBC 3.0-or-greater-specific remarks.

 Other factors may affect the result data set.  Please consult an
 ODBC reference for more details.

> (special-columns hstmt rowid catalog schema table scope nullable)

 ODBC 1.0.

 Creates a result data set describing primary key information in a 
 given table.  There may be up to eight ODBC-defined columns in the 
 resulting data set; a driver may add columns.  The contents of those 
 columns are beyond the scope of this documentation; consult an ODBC 
 reference for details.
 
 `hstmt' is a statement handle, and its value is returned by the
 procedure. `rowid' is either 'sql-best-rowid, indicating that the
 result data set contains a column or columns that uniquely identify 
 a row in a table; or 'sql-rowver, indicating that the result data set 
 contains those columns that are automatically updated when a row value 
 is updated by a transaction.  `catalog', `schema', and `table' are 
 strings.  `scope' is either 'sql-scope-currow, indicating that the primary 
 key sought is for the current row, or 'sql-scope-transaction, indicating 
 that the primary key applies to the current transaction. `nullable' is 
 either 'sql-no-nulls, which excludes columns in the result data set that 
 may contain NULL, or 'sql-nullable, which allows such columns.

> (statistics hstmt catalog schema table index-type accuracy)

 ODBC 1.0.

 Creates a result data set describing statistics about a table and its
 indexes.  There are thirteen ODBC-defined columns in the resulting data 
 set; a driver may add columns.  The contents of those columns are beyond 
 the scope of this documentation; consult an ODBC reference for details.
 
 `hstmt' is a statement handle, and its value is returned by the
 procedure.  `catalog', `schema', and `table'  are strings. 
 `index-type' is either 'sql-index-unique, indicating that only unique 
 indexes are to be considered, or 'sql-index-all, indicating that all 
 indexes are to be considered.  `accuracy' is either 'sql-quick, indicating 
 that readily-available but perhaps stale data may be used when generating 
 the data set, or 'sql-ensure, indicating that only up-to-date data is used.

 Errors and Diagnostics
 ----------------------

> (get-diag-field handle recnum field) 

 ODBC 3.0.

 Returns the value of an individual field of a diagnostic header 
 record or status record.  The type of the value depends on the field.

 `handle' may be an environment handle, connection handle, statement 
 handle, or descriptor handle.  `recnum' is a positive integer indicating 
 which record contains the field.  `field' is a symbol, as listed below.

 Please consult an ODBC reference for information on the significance 
 of individual fields.  The valid values for `field' and their corresponding 
 return types are:

 field                                  returns
 -----                                  -------
 'sql-diag-dynamic-function             string
 'sql-diag-connection-name              string
 'sql-diag-class-origin                 string
 'sql-diag-message-text                 string
 'sql-diag-server-name                  string
 'sql-diag-sqlstate                     string 
 'sql-diag-subclass-origin              string  
 'sql-diag-cursor-row-count             integer 
 'sql-diag-dynamic-function-code        integer
 'sql-diag-number                       integer
 'sql-diag-row-count                    integer
 'sql-diag-column-number                'sql-no-column-number, or 
                                        'sql-column-number-unknown, or
                                        integer 
 'sql-diag-native                       integer
 'sql-diag-row-number                   'sql-no-row-number, or 
                                        'sql-row-number-unknown, or
                                        integer 
 'sql-diag-returncode                   'sql-success, or 
                                        'sql-no-data, or
                                        'sql-invalid-handle, or
                                        'sql-error, or
                                        'sql-need-data, or
                                        'sql-success-with-info

> (get-diag-rec handle recnum) 
 
 ODBC 3.0.

 Returns a three-element list that describes the last ODBC error, 
 as indicated by the exn-error, exn-with-info, or exn-no-data
 exceptions.

 The first element of the list is a five-character string indicating
 an SQL state.  The second element of the list is an integer 
 indicating an error code specific to the data source.  The third 
 element is a string describing the error.  See an ODBC reference 
 for more information on SQL states.

 `handle' may be an environment handle, connection handle, statement 
 handle, or descriptor handle.  `recnum' is a positive integer 
 indicating a status record index.
 
> (sql-error henv hdbc hstmt)

 ODBC 1.0, deprecated in favor of get-diag-rec.

 Returns a three-element list that describes the last ODBC error, 
 as indicated by the exn-error, exn-with-info, or exn-no-data
 exceptions.

 The first element of the list is a five-character string indicating
 an SQL state.  The second element of the list is an integer 
 indicating an error code specific to the data source.  The third 
 element is a string describing the error.  See an ODBC reference 
 for more information on SQL states.

 `henv' is an environment handle. `hdbc' is ordinarily a connection 
 handle, and `hstmt' is ordinarily a statement handle.  For information 
 about `henv', pass the symbol 'sql-null-hdbc for `hdbc' and the
 symbol 'sql-null-hstmt for `hstmt'.  For information about `hdbc',
 when it is a connection handle, pass 'sql-null-hstmt for `hstmt'.

 Utilities
 ---------

> (make-indicator [n])  

 Creates an sql-indicator.  `n' is a positive exact integer, which
 defaults to 1.  A larger `n' may be used to create an sql-indicator 
 representing an array of ODBC indicators.

> (free-indicator! sql-indicator)

 Allows the Scheme garbage collector to reclaim the memory used by 
 the indicator `sql-indicator'.  If the indicator is subsequently 
 accessed by the ODBC driver, unpredictable effects may occur.

> (read-indicator sql-indicator [index])

 Given an sql-indicator, returns its stored value or values.  
 The optional parameter `index' is an index into the array of ODBC indicators 
 represented by `sql-indicator'. If `index' is omitted, all the values 
 associated with the sql-indicator are returned in a list.  The 
 possible values are 'sql-no-total, 'sql-null-data, 'sql-nts, 
 'sql-column-ignore, 'sql-data-at-exec, a pair consisting of 
 'sql-len-data-at-exec and an integer, or an integer.
 
 Please consult an ODBC reference for the significance of these 
 values.

> (set-indicator! sql-indicator val [n])

 Stores a value in an sql-indicator.  The optional parameter `n' is 
 an index into the array of ODBC indicators represented by `sql-indicator'.
 The default value of `n' is 0.  The possible values of `val' are 
 'sql-no-total, 'sql-null-data, 'sql-nts, 'sql-column-ignore, 
 'sql-data-at-exec, a pair consisting of 'sql-len-data-at-exec and 
 an integer, or an integer.
 
 Please consult an ODBC reference for the significance of these 
 values.

> (make-length)

 Creates an sql-length. 

> (free-length! sql-length)

 Allows the Scheme garbage collector to reclaim the memory used by 
 the length `sql-length'.  If the length is subsequently accessed by 
 the ODBC driver, unpredictable effects may occur.

> (read-length an-sql-length)

 Given an sql-length, returns its stored value, which is
 an integer.

> (make-buffer c-type [num-elts]) 

 Creates an sql-buffer.  The `c-type' parameter is either
  - a symbol denoting a C data type (see "C data types", below), or
  - a pair consisting of 'sql-c-char or 'sql-c-wchar, and a 
      positive exact integer indicating a string width
 The optional parameter `num-elts' is a positive exact integer 
 indicating the number of buffer elements (default = 1).  If `ctype' is 
 'sql-c-char or 'sql-c-wchar (not in a pair), the string width 
 defaults to 1.

 It is the responsibility of the programmer to make sure that 
 buffers bound to columns have the correct type and adequate 
 size for the column.  If a column has the incorrect type or 
 is too small, unpredictable effects may occur.

> (free-buffer! sql-buffer)

 Allows the Scheme garbage collector to reclaim the memory used by 
 the buffer `sql-buffer'.  If the buffer is subsequently accessed by 
 the ODBC driver, unpredictable effects may occur.

> (read-buffer sql-buffer [index]) 

 Returns the contents of an sql-buffer.  `index' is a zero-based index
 into the buffer.  If `index' is omitted, the entire buffer contents 
 are returned, in a form appropriate to the type of data contained
 in the buffer.  For most C data types, the buffer is read as a 
 list; for buffers containing 'sql-c-binary, 'sql-c-varbookmark, 
 and 'sql-c-bit elements, the buffer is read as a string.  If `index' 
 is given, an individual element of the buffer is returned.   In the 
 case of 'sql-c-wchar, an error occurs if the segment of the buffer 
 to be read contains a character not representable as an ordinary 
 character.  

 SrPersist provides no guarantees that a buffer contains valid data.

> (write-buffer! sql-buffer val [n]) 

 Updates the contents of an sql-buffer.  The type of `val' 
 depends on the C type used to create the buffer. The `n' parameter
 is a nonnegative exact integer used to indicate an offset in the
 buffer; the default is 0.

> (make-row-status [num-rows])

 Creates a new row status value.  The optional `num-rows' parameter
 indicates how many rows the row-status-value represents.  The default
 is 1.

> (read-row-status sql-row-status [index])

 Given a row status value, returns a symbol or list of symbols from 
 '(sql-row-deleted sql-row-error sql-row-success sql-row-updated).
 If the optional argument `index', a nonnegative exact integer, is
 omitted, a list is returned.  If provided, `index' is interpreted 
 as a zero-based index into an array of row status values, and a 
 single symbol is returned.

> (free-row-status! sql-row-status)

 Allows the Scheme garbage collector to reclaim the memory used by 
 the row status `sql-row-status'.  If the row status is subsequently 
 accessed by the ODBC driver, unpredictable effects may occur.

> (read-op-parms an-sql-op-parms)

 Available when compiled for ODBC 3.0 or greater.
 
 Given an sql-op-parms value, returns a list, each element of which 
 is either 'sql-param-proceed or 'sql-param-ignore.

> (make-boxed-uint unum)

 Given an exact nonnegative number, returns an sql-boxed-uint.

> (read-boxed-uint an-sql-boxed-uint)

 Given an sql-boxed-uint, returns an unsigned integer value.

> (free-boxed-uint an-sql-boxed-uint)

 Allows the Scheme garbage collector to reclaim the memory used by 
 an sql-boxed-uint.

 SQL data types
 --------------

 Data stored in data sources have SQL data types.  In contrast, 
 data in sql-buffer's have C data types.

 The significance of most of these types should be clear.  Consult
 an ODBC reference for more details.

 'sql-char
 'sql-varchar
 'sql-longvarchar
 'sql-wchar
 'sql-wvarchar
 'sql-wlongvarchar
 'sql-date
 'sql-time
 'sql-timestamp
 'sql-decimal
 'sql-numeric
 'sql-smallint
 'sql-integer
 'sql-real
 'sql-float
 'sql-double
 'sql-bit
 'sql-tinyint
 'sql-bigint
 'sql-binary
 'sql-varbinary
 'sql-longvarbinary
 'sql-interval-year
 'sql-interval-year-to-month
 'sql-interval-hour
 'sql-interval-minute
 'sql-interval-day-to-hour
 'sql-interval-day-to-minute
 'sql-interval-day-to-second
 'sql-interval-hour-to-minute
 'sql-interval-hour-to-second
 'sql-interval-minute-to-second

 [ODBC 3.0 and greater]
 'sql-type-date
 'sql-type-time
 'sql-type-timestamp

 [ODBC 3.5 and greater]
 'sql-guid

 C data types
 ------------

 Data in sql-buffer's have C data types.  In contrast, data stored in 
 data sources have SQL data types.

 The significance of most of these types should be clear.  Consult
 an ODBC reference for more details.

 'sql-c-char
 'sql-c-wchar
 'sql-c-long
 'sql-c-short
 'sql-c-float
 'sql-c-double
 'sql-c-date
 'sql-c-time
 'sql-c-timestamp
 'sql-c-binary
 'sql-c-bit
 'sql-c-tinyint
 'sql-c-slong
 'sql-c-sshort
 'sql-c-stinyint
 'sql-c-ulong
 'sql-c-ushort
 'sql-c-utinyint
 'sql-c-bookmark

 [ODBC 3.0 or greater]
 'sql-c-numeric
 'sql-c-type-timestamp
 'sql-c-type-date
 'sql-c-type-time
 'sql-c-interval-year
 'sql-c-interval-month
 'sql-c-interval-day
 'sql-c-interval-hour
 'sql-c-interval-minute
 'sql-c-interval-second
 'sql-c-interval-year-to-month
 'sql-c-interval-day-to-hour
 'sql-c-interval-day-to-minute
 'sql-c-interval-day-to-second
 'sql-c-interval-hour-to-minute
 'sql-c-interval-hour-to-second
 'sql-c-interval-minute-to-second
 'sql-c-sbigint
 'sql-c-ubigint
 'sql-c-varbookmark

  [ODBC 3.5 or greater]
 'sql-c-guid



