ODBC API

Connecting to Data Sources

SQLAllocEnv

SQLAllocConnect

SQLConnect

SQLDriverConnect
(Level 1 Extension)

SQLBrowseConnect
(Level 2 Extension)

Disconnecting from a Data Source

SQLDisconnect

SQLFreeConnect

SQLFreeEnv

Setting & Retrieving Connection Options

SQLSetConnectOption
(Level 1 Extension)

SQLGetConnectOption
(Level 1 Extension)

SQLSetStmtOption
(Level 1 Extension)

SQLGetStmtOption
(Level 1 Extension)

Obtaining Information about a Driver or Data Source

SQLGetFunctions
(Level 1 Extension)

SQLGetTypeInfo
(Level 1 Extension)

SQLGetInfo
(Level 1 Extension)

SQLDataSources
(Level 2 Extension)

SQLDrivers
(Level 2 Extension)

Preparing SQL Requests to be Executed Multiple Times

SQLAllocStmt

SQLPrepare

SQLBindParameter
(Level 1 Extension)

SQLParamOptions
(Level 2 Extension)

SQLGetCursorName

SQLSetCursorName

SQLSetScrollOptions
(Level 2 Extension)

Submitting SQL Requests

SQLExecute

SQLExecDirect

SQLNativeSQL
(Level 2 Extension)

SQLDescribeParam
(Level 2 Extension)

SQLNumParams
(Level 2 Extension)

SQLParamData
(Level 1 Extension)

SQLPutData
(Level 1 Extension)

Retrieving Results and Information about Results

SQLRowCount

SQLNumResultCols

SQLDescribeCol

SQLColAttributes

SQLBindCol

SQLFetch

SQLExtendedFetch
(Level 2 Extension)

SQLGetData
(Level 1 Extension)

SQLSetPos
(Level 2 Extension)

SQLMoreResults
(Level 2 Extension)

SQLError

Terminating a Statement

SQLFreeStmt

SQLCancel

SQLTransact

Obtaining information about the Data Source's system tables (catalog functions)

SQLColumnPrivileges
(Level 2 Extension)

SQLColumns
(Level 1 Extension)

SQLForeignKeys
(Level 2 Extension)

SQLPrimaryKeys
(Level 2 Extension)

SQLProcedureColumns
(Level 2 Extension)

SQLProcedures
(Level 2 Extension)

SQLSpecialColumns
(Level 1 Extension)

SQLStatistics
(Level 1 Extension)

SQLTablePrivileges
(Level 2 Extension)

SQLTables
(Level 1 Extension)

ODBC C API DEFINITION: SQLSetScrollOptions


Extension Level 2

SQLSetScrollOptions sets options that control the behavior of cursors associated with an hstmt. SQLSetScrollOptions allows the application to specify the type of cursor behavior desired in three areas: concurrency control, sensitivity to changes made by other transactions and rowset size.


Note In ODBC 2.0, SQLSetScrollOptions has been supersceded by the SQL_CURSOR_TYPE, SQL_CONCURRENCY, SQL_KEYSET_SIZE and SQL_ROWSET_SIZE statement options. ODBC 2.0 drivers must support this function for backwards compatibility; ODBC 2.0 applications should only call this function in ODBC 1.0 drivers.

If an application calls SQLSetScrollOptions, a driver must be able to return the values of the aforementioned statement options with SQLGetStmtOptions. For more information, see SQLSetStmtOption.

SyntaxRETCODE SQLSetScrollOptions(hstmt, fConcurrency, crowKeyset, crowRowset)

The SQLSetScrollOptions function accepts the following arguments.

Type

Argument

Use

Description

HSTMThstmtInputStatement handle.
UWORDfConcurrencyInputSpecifies concurrency control for the cursor and must be one of the following values:
SQL_CONCUR_READ_ONLY: Cursor is read-only. No updates are allowed.
SQL_CONCUR_LOCK: Cursor uses the lowest level of locking sufficient to ensure that the row can be updated.
SQL_CONCUR_ROWVER: Cursor uses optimistic concurrency control, comparing row versions, such as SQLBase ROWID or Sybase TIMESTAMP.
SDWORDcrowKeysetInputNumber of rows for which to buffer keys. This value must be greater than or equal to CrowRowset or one of the following values:
SQL_SCROLL_FORWARD_ONLY: The cursor only scrolls forward.
SQL_SCROLL_STATIC: The data in the result set is static.
SQL_SCROLL_KEYSET_DRIVEN: The driver saves and uses the keys for every row in the result set.
SQL_SCROLL_dYNAMIC: The driver sets crowKeyset to the value of crowRowset.
If crowKeyset is a value greater than crowRowset, the value defines the number of rows in the keyset that are to be buffered by the driver. This reflects a mixed scrollable cursor; the cursor is keyset driven within the keyset and dynamic outside of the keyset.
UWORDcrowRowsetInputNumber of rows in a rowset. crowRowset defines the number of rows fetched by each call to SQLExtendedFetch; the number of rows that the application buffers.
ReturnsSQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR or SQL_INVALID_HANDLE
Diagnostics

When SQLSetScrollOptions returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLSetScrollOptions and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATE

Error

Description

01000General warningDriver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
IM001Driver does not support this function(DM) The driver specified by the data source name does not support the function.
S1000General errorAn error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause.
S1001Memory allocation failure(DM) The Driver Manager was unable to allocate memory for the connection handle. The driver was unable to allocate memory for the connection handle.
S1010Function sequence error(DM) An asynchronously executing function (not this one) was called for the hstmt and was still executing when this function was called.
(DM) SQLExecute, SQLExecDirect or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
S1107Row value out of range(DM) The value specified for the argument crowKeyset was less than 1, but was not equal to
SQL_SCROLL_FORWARD_ONLY,
SQL_SCROLL_STATIC,
SQL_SCROLL_KEYSET_DRIVEN,
SQL_SCROLL_DYNAMIC.
(DM) The value specified for the argument crowKeyset is greater than 0, but less than crowRowset.
S1108Concurrency option out of range(DM) The value specified for the argument fConcurrency was not equal to
SQL_CONCUR_READ_ONLY,
SQL_CONCUR_LOCK,
SQL_CONCUR_ROWVER, or
SQL_CONCUR_VALUES.
S1C00Driver not capableThe driver or data source does not support the concurrency control option specified in the argument fConcurrency.
The driver does not support the cursor model specified in the argument crowKeyset.
Comments

If an application calls SQLSetScrollOptions for an hstmt, it must do so before it calls SQLPrepare or SQLExecDirect or creating a result set with a catalog function.

The application must specify a buffer in a call to SQLBindCol that is large enough to hold the number of rows specified in crowRowset.

If the application does not call SQLSetScrollOption, crowRowset has a default value of 1, crowKeyset has a default value of SQL_SCROLL_FORWARD_ONLY, and fConcurrency equals SQL_CONCUR_READ_ONLY.

Code Example(future)
Related Functions
For information about

See

Assigning storage for a column in a result setSQLBindCol
Fetching a block of data or scrolling through a result setSQLExtendedFetch (extension)
Positioning the cursor in a rowsetSQLSetPos (extension)
Setting a statement optionSQLSetStmtOption

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows Server useable by your network's iPhone/iPod, iPad, Linux, Mac and Windows systems. Years in the making here in the USA, ODBC Router has saved its customers millions of dollars in DLL installations and support costs for less than the price of a new PC and a few minutes installation time. ODBC Router provides a low cost, turnkey database network with enterprise class IT support.

Ditching the ODBC Administrator Control Panel:

By linking your application with the free ODBC Router client-side SDK instead of the ODBC Driver Manager, the need for your end-users to deal with driver installation or an ODBC Control Panel is gone! We even provide a setup function your code may call to display a "network browser" that enables your customer to "find" their ODBC Router server on the network, then "choose" the exact database they want to work with and finally return to your application with a fully-formed ODBC connection-string that may be stored and passed back to SQLConnect or SQLDriverConnect anytime your user wants to initiate a connection that data source. No more walking your customers through the process of adding data sources to ODBC Control Panel or, in the case of non-Windows computers, no need to worry about whether or not a compatible third-party ODBC Driver Manager has been installed for use with your code. (Remember that ODBC Router supports iPhone/iPod, iPad, Mac OS 9, Mac OS X, Linux and Windows.) If there ever are any client-side ODBC support issues, AugSoft can handle them directly with the customer freeing you to focus on the application.

JDBC?

JDBC-in-ODBC drivers (like some 'actual' ODBC drivers, lol) launch a CPU-intensive virtual machine in the background on your machine, which is bad for battery powered laptops, high-volume web servers or entry level desktops (that typically have slow busses and drives). As the world shifted to laptops and shared servers, the whole "virtual machine" concept became a support nightmare and so these days good Java apps are compiled to run as native (not emulated) code. Java developers may use the operating system's native ODBC support from within the JDBC class library using the sun.jdbc.odbc.JdbcOdbcDriver driver with a URL as shown below.

jdbc:odbc:dsn[;key=value]*

Example:

jdbc:odbc:finance;UID=cfo;

IT techs may then complete the database connection on the Customer's machine using ODBC Router or the database vendor's official ODBC driver.

NOTE: By creating ODBC data sources with ODBC Router, your apps will enjoy native speed and database independent connections from either Java/C/C++/C#/ObjC or PHP/PERL/Python/Ruby/BASIC on Linux, Macintosh and Windows. Also be aware that using ODBC Router with the Mac platform is an especially good idea because database vendors have not kept their Mac drivers in sync with Windows and there are actual third-party vendors who wrap freeware and JDBC drivers inside of ODBC "shells" without warning their customers! This problem is of great concern to developers because fake drivers almost always fly past the IT guys who test with speed deamon desktops, but fail the enterprise when user laptops and iMacs take too long to run queries or slowly corrupt the database when they do. IT guys often chalk this up to "network problems" leaving users with poison drivers to avoid their database. ODBC Router addresses this issue by enabling official vendor supported Windows ODBC drivers (on a Windows Server) to be accessed from all platforms, network wide.

ODBC 3.x?

It's not here yet. Even in 2010, most ODBC drivers are ODBC 1.x and 2.x. The ODBC Driver Manager translates between 3.x and 2.x or 2.x and 1.x ODBC calls. Therefore, if you don't need UNICODE, it's a bad idea to use ODBC 3.x API calls. That said, UNICODE is a Good Thing and there are actually at least three databases that natively support it now, so look for 3.x to be here soon.

Need ODBC API Help?

We really know ODBC and we routinely provide code-level ODBC help to our customers. Our low cost ODBC Router systems are available now at our online store and if your site buys them, you may open a ticket to ask ODBC development questions --we offer both E-Mail and On-Call support options in seven of the G8's timezones! Be sure to test your ODBC Router and ask for any needed installation help before purchase because we aren't Fry's --no refunds please, our prices are too low for such nonsense and we're too busy supporting real Customers!

© Copyright 1990-2010, August Software, USA. All Rights Reserved.