ODBC API

Connecting to Data Sources

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: SQLCancel

Core

SQLCancel cancels processing on an hstmt.

Syntax

RETCODE SQLCancel(hstmt)

The SQLCancel function accepts the following argument.

Type	Argument	Use	Description
HDBC	hstmt	Input	Statement handle

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR or SQL_INVALID_HANDLE

Diagnostics

When SQLCancel 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 SQLCancel 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
01000	General warning	Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
70100	Operation aborted	The data source was unable to process the cancel request.
IM001	Driver does not support this function	(DM) The driver associated with the hstmt does not support the function.
S1000	General error	An 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.
S1001	Memory 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.

Comments

SQLCancel can cancel the following types of processing on an hstmt:

A function running asynchronously on an hstmt
A function on an hstmt that needs data
A function runnign on the hstmt on another thread

If an application calls SQLCancel when no processing is being done on the hstmt, SQLCancel has the same effect as SQLFreeStmt with the SQL_CLOSE option; this behavior is defined only for completeness and appliations should call SQLFreeStmt to close cursors.

Canceling Asynchronous Processing

After an application calls a function asynchronously, it calls the function repeatedly to determine whether it has finished processing. If the funtion is still procesing, it returns SQL_STILL_EXECUTING. If the function has finished processing, it returns a different code.

After any call to the funtion that returns SQL_STILL_EXECUTING, an application can call SQLCancel to cancel the function. If the cancel requested is successful, the driver returns SQL_SUCCESS. This message does not indicate that the funtion was actually canceled; it indicates that the cancel request was processed. When or if the function is actually canceled is driver- and data-source-dependent. The appliation must continue to call the original funtion until the return code is not SQL_STILL_EXECUTING. If the function was successfully canceled, the return code is SQL_ERROR with SQLSTATE S1008 (Operation canceled). If the function completed its normal processing, the return code is SQL_SUCCESS or SQL_SUCCESS_WITH_INFO if the function succeeded or SQL_ERROR and SQLSTATE other than S1008 (Operation canceled) if the funtion failed.

Canceling Functions that Need Data

After SQLExecute or SQLExecDirect return SQL_NEED_DATA and before data ahs been sent for all data-at-execution parameters, an appliation can call SQLCancel to cancel the statement execution. After the statement has been canceled, the application can call SQLExecute or SQLExecDirect again. For more information, see SQLBindParameter.

After SQLSetPos returns SQL_NEED_DATA and before data has been sent for all data-at-execution columns, an application can call SQLCancel to cancel the operation. After the operation has been canceled, the appliation can call SQLSetPos again; canceling does not affect the cursor state or the current cursor position. For more information, see SQLSetPos.

Canceling Functions in a Multithreaded Application

In a multithreaded appliation, the appliation can cancel a function that is runnign synchronously on an hstmt. To cancel the function, the application calls SQLCancel with the same hstmt as that used by the target function, but on a different thread. As in canceling a funtion running asynchronously, the return code of the SQLCancel only indicates whether the driver processed the request successfully. The return code of the original function indicates whether it completed normally or was canceled.

Code Example

Related Functions

For information about...	See...
Assigning storage for a parameter	SQLBindParameter
Executing an SQL statement	SQLExecDirect
Executing a prepared SQL statement	SQLExecute
Freeing a statement handle	SQLFreeStmt
Positioning the cursor in a rowset	SQLSetPos (extension)
Returning the next parameter to send data for	SQLParamData (extension)
Sending parameter data at execution	SQLPutData (extension)

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows Server useable by your network's Linux, Macintosh and Windows systems. Three years in the making, ODBC Router has saved its customers millions of dollars in DLL installation and ODBC 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 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.

ODBC or JDBC?

JDBC drivers launch a CPU-intensive virtual machine in the background on your machine, which is bad for shared servers and for battery powered laptops 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!