ODBC API implementation details

Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Open Database Connectivity (ODBC) is a Microsoft Win32 API that enables applications to access data in ODBC-compliant data sources. This article explains how ODBC processes function calls, manages handles, interacts with drivers, and provides diagnostics. It gives developers a clearer understanding of how ODBC operates between applications, the Driver Manager, and database drivers.

The SQL Server Native Client ODBC driver reference doesn't document every ODBC function. It only documents those functions with parameters or behaviors unique to the SQL Server Native Client ODBC driver.

The SQL Server Native Client ODBC driver complies with the ODBC 3.51 specification. For full reference material, download the Microsoft Data Access Components SDK from the Data Access and Storage Developer Center or view the ODBC Programmer's Reference.

How the ODBC API works

ODBC provides a standardized interface between applications and database drivers. When your application calls an ODBC function, the call passes through several layers before reaching the data source. Understanding this architecture helps you write more efficient code and troubleshoot connectivity problems.

ODBC handle model

ODBC uses four hierarchical handle types to manage state:

Handle type	Purpose
Environment (HENV)	Global ODBC settings and versioning
Connection (HDBC)	Represents a connection to a specific data source
Statement (HSTMT)	Manages SQL statements, parameters, and result sets
Descriptor (HDESC)	Stores metadata for parameters and columns

Driver manager and driver interaction

1. The application makes an ODBC API call.
2. The Driver Manager validates parameters and dispatches the call.
3. The driver interacts with the data source.
4. Results flow back through the Driver Manager to the application.

Function call lifecycle

1. Allocate handles.
2. Set environment or connection attributes.
3. Connect to a data source.
4. Prepare or execute SQL statements.
5. Bind parameters or result columns.
6. Fetch rows.
7. Free handles.

Diagnostics and error handling

Use the following diagnostic functions:

• SQLGetDiagRec
• SQLGetDiagField

Diagnostics might apply to environment, connection, or statement handles.

Unicode vs. ANSI calls

ODBC provides two types of functions:

• ANSI functions like SQLExecDirectA
• Unicode functions like SQLExecDirectW

Use Unicode APIs for modern applications.

Threading and pooling

• Thread safety depends on how the application configures the driver and Driver Manager.
• To reduce connection overhead, enable connection pooling at either level.

ODBC API reference

The following sections group the ODBC API functions by task. Each entry links to the detailed reference page for the SQL Server Native Client driver.

Connection and data source

Use these functions to establish, configure, and manage connections to SQL Server.

Function	Description
SQLConnect	Establish a connection to a data source using a DSN, user ID, and password
SQLDriverConnect	Connect using a connection string with driver-specific keywords
SQLBrowseConnect	Discover connection attributes interactively to build a connection string
SQLConfigDataSource	Create, modify, or delete data source names (DSNs) programmatically
SQLDrivers	List all installed ODBC drivers and their attributes
SQLGetConnectAttr	Retrieve the current value of a connection attribute
SQLSetConnectAttr	Configure connection behavior such as timeouts and transaction isolation

Execute SQL statements

Use these functions to prepare, execute, and manage SQL statements.

Function	Description
SQLExecDirect	Execute a SQL statement immediately without preparation
SQLExecute	Execute a previously prepared SQL statement
SQLCancel	Cancel an in-progress statement execution
SQLNativeSql	Translate ODBC SQL syntax to the driver's native SQL dialect
SQLEndTran	Commit or roll back a transaction on a connection or environment

Bind parameters and columns

Use these functions to bind application variables to SQL parameters and result set columns.

Function	Description
SQLBindParameter	Bind an application buffer to a SQL statement parameter marker
SQLBindCol	Bind an application buffer to a result set column
SQLParamData	Get the next parameter that needs data during data-at-execution operations
SQLPutData	Send parameter data in chunks during statement execution
SQLDescribeParam	Retrieve the data type and size of a parameter marker
SQLNumParams	Count the number of parameters in a prepared statement

Fetch and process results

Use these functions to retrieve data from result sets and process query results.

Function	Description
SQLFetch	Fetch the next rowset of data and return bound column values
SQLFetchScroll	Fetch a rowset at an absolute or relative position in the result set
SQLGetData	Retrieve data for a single unbound column or large data in chunks
SQLMoreResults	Move to the next result set when a statement returns multiple results
SQLRowCount	Get the number of rows affected by INSERT, UPDATE, or DELETE statements
SQLCloseCursor	Close the cursor and discard pending results
SQLGetCursorName	Retrieve the name associated with a statement's cursor

Discover schema and metadata

Use these functions to query database schema information such as tables, columns, and keys.

Function	Description
SQLTables	List tables, views, and other table-like objects in the data source
SQLColumns	List columns and their attributes for specified tables
SQLPrimaryKeys	Retrieve the primary key columns for a table
SQLForeignKeys	List foreign keys for a table or foreign keys in other tables that reference it
SQLSpecialColumns	Identify columns that uniquely identify a row or update automatically
SQLStatistics	Retrieve index information and table statistics
SQLProcedures	List stored procedures available in the data source
SQLProcedureColumns	Describe input/output parameters and result columns for stored procedures

Column and result set metadata

Use these functions to examine the structure of result sets and column attributes.

Function	Description
SQLDescribeCol	Get the column name, type, size, and nullability for a result column
SQLColAttribute	Retrieve a specific attribute of a result set column
SQLNumResultCols	Count the number of columns in a result set
SQLGetTypeInfo	List the SQL data types supported by the data source

Privileges and security

Use these functions to retrieve permission information for database objects.

Function	Description
SQLTablePrivileges	List privileges granted on tables in the data source
SQLColumnPrivileges	List privileges granted on specific columns of a table

Environment and statement attributes

Use these functions to configure ODBC environment and statement behavior.

Function	Description
SQLSetEnvAttr	Set environment attributes such as ODBC version and connection pooling
SQLGetStmtAttr	Retrieve the current value of a statement attribute
SQLSetStmtAttr	Configure statement behavior such as cursor type and query timeout

Descriptors

Use these functions to directly manipulate descriptor records for advanced parameter and column handling.

Function	Description
SQLGetDescField	Retrieve a single field from a descriptor record
SQLSetDescField	Set a single field in a descriptor record
SQLSetDescRec	Set multiple fields in a descriptor record with a single call

Diagnostics and driver information

Use these functions to retrieve error information and query driver capabilities.

Function	Description
SQLGetDiagField	Retrieve a diagnostic field from an environment, connection, or statement
SQLGetInfo	Get general information about the driver and data source capabilities
SQLGetFunctions	Determine which ODBC functions the driver supports

Resource cleanup

Use these functions to release handles and free resources.

Function	Description
SQLFreeHandle	Release an environment, connection, statement, or descriptor handle
SQLFreeStmt	Free statement resources, close cursors, or unbind parameters and columns

Related content

• SQL Server Native Client (ODBC) Reference