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


Core

SQLFreeConnect releases a connection handle and frees all memory associated with the handle.

SyntaxRETCODE SQLFreeConnect(hdbc)

The SQLFreeConnect function accepts the following argument.

Type

Argument

Use

Description

HDBChdbcInputConnection handle
ReturnsSQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR or SQL_INVALID_HANDLE
Diagnostics

When SQLFreeConnect 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 SQLFreeConnect 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.)
08S01Communication link failureThe communication link between the driver and the data source to which the driver was connected failed before the function completed processing.
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.
S1010Function sequence error(DM) The function was called prior to calling SQLDisconnect for the hdbc.
Comments

Prior to calling SQLFreeConnect, an application must call SQLDisconnect for the hdbc. Otherwise, SQLFreeConnect returns SQL_ERROR and the hdbc remains valid. Note that SQLDisconnect automatically drops any hstmts open on the hdbc.

Code Example

See SQLBrowseConnect and SQLConnect.

Related Functions
For information about

See

Allocating a connection handleSQLAllocConnect
Connecting to a data sourceSQLConnect
Disconnecting from a data sourceSQLDisconnect
Connecting to a data source using a connection string or dialog boxSQLDriverConnect (extension)
Freeing an environment handleSQLFreeEnv
Freeing a statement handleSQLFreeStmt

ODBC Router

ODBC Router transparently makes all ODBC drivers on a central Windows instance usable by your network's iPhone/iPod, iPad, Linux, Mac and Windows systems.

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 to that data source. ..no more walking your customers through the process of adding data sources to the 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.

OLEDB?

OLEDB is Windows-only and Microsoft is aligning with ODBC now and phasing out support for OLEDB

XML/REST

XML is good for passing infrequent configuration files (such as during app installation or provisioning) or among computers with power cords and air conditioning, for example, when merging records between a customer service and a billing system. Some of the top database vendors developed "convenience methods" to facilitate this use, but many developers who came of age in the layoff-induced knowledge vaccuum that formed after the dot-com bubble misunderstood the true purpose of XML and severely underestimated the amount of procesing required to handle a format that was intended only for information interchange between disparate systems. The computer vendors themselves did not help the situation as this worked perfectly to their benefit.

Predictably, many junior dot-com developers built REST-based database front-ends that exchange database transactions using XML in near-real-time with AJAX based JavaScript apps downloaded to their users' browsers with the result of database servers everywhere "falling over" at a far fewer number of concurrent database transactions than they should, leading their engineers down a deep rabbit hole towards replication, multi-system management and even regression to 1970s (CPU starved) solutions like NOSQL, the whole while being cheered on by server/hosting salespeople and others on the Internet falling into the same trap. Fortunately, the era of such XML/AJAX apps is rapidly drawing to a close as the world shifts to mobile apps and whose battery constraints and community feedback resist such abuse.

NOTE: By creating ODBC data sources with ODBC Router, your apps will enjoy native speed and database independent connections from Java/C/C++/C#/ObjC or PHP/PERL/Python/Ruby/BASIC on Linux, Macintosh and Windows. Using ODBC Router with a Mac is an especially good idea because database vendors have not kept their Mac drivers in sync with Windows and the third-party Mac drivers qualify as unstable hacks.

JDBC?

JDBC was an attempt to marry Java with ODBC by a couple of now defunct companies. The legacy lives on..but JDBC is not on iPhone where most relevant application development is taking place. Some non-AugSoft Mac ODBC drivers that support connection to ORACLE are known to internally launch the CPU/RAM-intensive Java virtual machine in the background on the customer's machine (without telling the user) though Apple has deprecated Java for Mac OS X. Virtual machines may be okay for embedded devices but they are not efficient for battery powered laptops and smartphones. For the same reason, they don't allow web servers to reach their maximum potential or good performance on many entry level devices (that typically have Atom chips, slow busses and hard drives). In a compiled environment, Java developers may use the operating system's native ODBC support from within the standard 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;

ODBC 3.x?

Even in 2011, most ODBC drivers are ODBC 1.x and 2.x because the ODBC Driver Manager translates between 3.x and 2.x and 1.x so there's little incentive for most drivers to be rewritten. Therefore, if you don't need 16-bit UNICODE, it's a bad idea to use ODBC 3.x API calls (due to the overhead of translating the calls back to ODBC 1.x or 2.x). That said, 16-bit UNICODE is a Good Thing and there are today at least three databases that natively support it now, so look for 3.x to be here soon. In the mean time, ODBC 2.x and ODBCrouter automatically do Latin code page translations (so special characters in Latin-based languages like German, Spanish, etc.. all work fine) and VARCHAR data containing UNICODE may be exchanged with double-width SQL_BINARY variables using ODBC 2.x.

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 E-Mail and On-Call support options in seven timezones based in the USA.

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