Skip to content

odbc-api-implementation-details.md

Latest commit

 

History

History
215 lines (154 loc) · 10.3 KB

odbc-api-implementation-details.md

File metadata and controls

215 lines (154 loc) · 10.3 KB
title ODBC API Implementation Details
description ODBC API Implementation Details
author markingmyname
ms.author maghan
ms.date 01/26/2026
ms.service sql
ms.subservice native-client
ms.topic reference
helpviewer_keywords
ODBC, functions
SQL Server Native Client ODBC driver, SQL Server-specific behaviors
ODBC, SQL Server-specific behaviors
functions [ODBC]

ODBC API implementation details

[!INCLUDE SQL Server Azure SQL Database Synapse Analytics 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 [!INCLUDE ssNoVersion] Native Client ODBC driver reference doesn't document every ODBC function. It only documents those functions with parameters or behaviors unique to the [!INCLUDE ssNoVersion] Native Client ODBC driver.

The [!INCLUDE ssNoVersion] 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