_SrPersist_ =========== _ODBC_ ====== SrPersist is an ODBC library for Racket and DrRacket. 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 Racket 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 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, statement, 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-no-prompt 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 descriptor 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-initially-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 permissible 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 permissible 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 number `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