You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -3,7 +3,7 @@ title: "ODBC API Implementation Details"
3
3
description: "ODBC API Implementation Details"
4
4
author: markingmyname
5
5
ms.author: maghan
6
-
ms.date: "03/16/2017"
6
+
ms.date: 01/26/2026
7
7
ms.service: sql
8
8
ms.subservice: native-client
9
9
ms.topic: "reference"
@@ -13,118 +13,203 @@ helpviewer_keywords:
13
13
- "ODBC, SQL Server-specific behaviors"
14
14
- "functions [ODBC]"
15
15
---
16
-
# ODBC API Implementation Details
17
-
[!INCLUDE[SQL Server Azure SQL Database Synapse Analytics PDW](../../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]
18
-
19
-
Open Database Connectivity (ODBC) is a Microsoft Win32 application programming interface used by applications to access data in ODBC data sources.
20
-
21
-
The [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] Native Client ODBC driver reference does not document all of the ODBC function calls. Only those functions that have driver-specific parameters or behaviors when used with the [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] Native Client ODBC driver are discussed.
22
-
23
-
The [!INCLUDE[ssNoVersion](../../includes/ssnoversion-md.md)] Native Client ODBC driver complies with the ODBC 3.51 specification. For a comprehensive reference of ODBC 3.51, download the Microsoft Data Access Components SDK from the [Data Access and Storage Developer Center](https://go.microsoft.com/fwlink?linkid=4173), or view the [ODBC Programmer's Reference](../../odbc/reference/odbc-programmer-s-reference.md) online.
[SQL Server Native Client (ODBC) Reference](../native-client/odbc/sql-server-native-client-odbc.md)
129
-
[Building Applications with SQL Server Native Client](../../relational-databases/native-client/applications/building-applications-with-sql-server-native-client.md)
130
-
16
+
17
+
# ODBC API implementation details
18
+
19
+
[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics PDW](../../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)]
20
+
21
+
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.
22
+
23
+
The [!INCLUDE [ssNoVersion](../../includes/ssnoversion-md.md)] 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](../../includes/ssnoversion-md.md)] Native Client ODBC driver.
24
+
25
+
The [!INCLUDE [ssNoVersion](../../includes/ssnoversion-md.md)] 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](https://go.microsoft.com/fwlink?linkid=4173) or view the [ODBC Programmer's Reference](../../odbc/reference/odbc-programmer-s-reference.md).
26
+
27
+
## How the ODBC API works
28
+
29
+
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.
30
+
31
+
### ODBC handle model
32
+
33
+
ODBC uses four hierarchical handle types to manage state:
34
+
35
+
| Handle type | Purpose |
36
+
| --- | --- |
37
+
|**Environment (HENV)**| Global ODBC settings and versioning |
38
+
|**Connection (HDBC)**| Represents a connection to a specific data source |
39
+
|**Statement (HSTMT)**| Manages SQL statements, parameters, and result sets |
40
+
|**Descriptor (HDESC)**| Stores metadata for parameters and columns |
41
+
42
+
### Driver manager and driver interaction
43
+
44
+
1. The application makes an ODBC API call.
45
+
1. The **Driver Manager** validates parameters and dispatches the call.
46
+
1. The **driver** interacts with the data source.
47
+
1. Results flow back through the Driver Manager to the application.
48
+
49
+
### Function call lifecycle
50
+
51
+
1. Allocate handles.
52
+
1. Set environment or connection attributes.
53
+
1. Connect to a data source.
54
+
1. Prepare or execute SQL statements.
55
+
1. Bind parameters or result columns.
56
+
1. Fetch rows.
57
+
1. Free handles.
58
+
59
+
### Diagnostics and error handling
60
+
61
+
Use the following diagnostic functions:
62
+
63
+
-`SQLGetDiagRec`
64
+
-`SQLGetDiagField`
65
+
66
+
Diagnostics might apply to environment, connection, or statement handles.
67
+
68
+
### Unicode vs. ANSI calls
69
+
70
+
ODBC provides two types of functions:
71
+
72
+
-**ANSI functions** like `SQLExecDirectA`
73
+
-**Unicode functions** like `SQLExecDirectW`
74
+
75
+
Use Unicode APIs for modern applications.
76
+
77
+
### Threading and pooling
78
+
79
+
- Thread safety depends on how the application configures the driver and Driver Manager.
80
+
- To reduce connection overhead, enable connection pooling at either level.
81
+
82
+
## ODBC API reference
83
+
84
+
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.
85
+
86
+
### Connection and data source
87
+
88
+
Use these functions to establish, configure, and manage connections to SQL Server.
89
+
90
+
| Function | Description |
91
+
| --- | --- |
92
+
|[SQLConnect](sqlconnect.md)| Establish a connection to a data source using a DSN, user ID, and password |
93
+
|[SQLDriverConnect](sqldriverconnect.md)| Connect using a connection string with driver-specific keywords |
94
+
|[SQLBrowseConnect](sqlbrowseconnect.md)| Discover connection attributes interactively to build a connection string |
95
+
|[SQLConfigDataSource](sqlconfigdatasource.md)| Create, modify, or delete data source names (DSNs) programmatically |
96
+
|[SQLDrivers](sqldrivers.md)| List all installed ODBC drivers and their attributes |
97
+
|[SQLGetConnectAttr](sqlgetconnectattr.md)| Retrieve the current value of a connection attribute |
98
+
|[SQLSetConnectAttr](sqlsetconnectattr.md)| Configure connection behavior such as timeouts and transaction isolation |
99
+
100
+
### Execute SQL statements
101
+
102
+
Use these functions to prepare, execute, and manage SQL statements.
103
+
104
+
| Function | Description |
105
+
| --- | --- |
106
+
|[SQLExecDirect](sqlexecdirect.md)| Execute a SQL statement immediately without preparation |
107
+
|[SQLExecute](sqlexecute.md)| Execute a previously prepared SQL statement |
108
+
|[SQLCancel](sqlcancel.md)| Cancel an in-progress statement execution |
109
+
|[SQLNativeSql](sqlnativesql.md)| Translate ODBC SQL syntax to the driver's native SQL dialect |
110
+
|[SQLEndTran](sqlendtran.md)| Commit or roll back a transaction on a connection or environment |
111
+
112
+
### Bind parameters and columns
113
+
114
+
Use these functions to bind application variables to SQL parameters and result set columns.
115
+
116
+
| Function | Description |
117
+
| --- | --- |
118
+
|[SQLBindParameter](sqlbindparameter.md)| Bind an application buffer to a SQL statement parameter marker |
119
+
|[SQLBindCol](sqlbindcol.md)| Bind an application buffer to a result set column |
120
+
|[SQLParamData](sqlparamdata.md)| Get the next parameter that needs data during data-at-execution operations |
121
+
|[SQLPutData](sqlputdata.md)| Send parameter data in chunks during statement execution |
122
+
|[SQLDescribeParam](sqldescribeparam.md)| Retrieve the data type and size of a parameter marker |
123
+
|[SQLNumParams](sqlnumparams.md)| Count the number of parameters in a prepared statement |
124
+
125
+
### Fetch and process results
126
+
127
+
Use these functions to retrieve data from result sets and process query results.
128
+
129
+
| Function | Description |
130
+
| --- | --- |
131
+
|[SQLFetch](sqlfetch.md)| Fetch the next rowset of data and return bound column values |
132
+
|[SQLFetchScroll](sqlfetchscroll.md)| Fetch a rowset at an absolute or relative position in the result set |
133
+
|[SQLGetData](sqlgetdata.md)| Retrieve data for a single unbound column or large data in chunks |
134
+
|[SQLMoreResults](sqlmoreresults.md)| Move to the next result set when a statement returns multiple results |
135
+
|[SQLRowCount](sqlrowcount.md)| Get the number of rows affected by INSERT, UPDATE, or DELETE statements |
136
+
|[SQLCloseCursor](sqlclosecursor.md)| Close the cursor and discard pending results |
137
+
|[SQLGetCursorName](sqlgetcursorname.md)| Retrieve the name associated with a statement's cursor |
138
+
139
+
### Discover schema and metadata
140
+
141
+
Use these functions to query database schema information such as tables, columns, and keys.
142
+
143
+
| Function | Description |
144
+
| --- | --- |
145
+
|[SQLTables](sqltables.md)| List tables, views, and other table-like objects in the data source |
146
+
|[SQLColumns](sqlcolumns.md)| List columns and their attributes for specified tables |
147
+
|[SQLPrimaryKeys](sqlprimarykeys.md)| Retrieve the primary key columns for a table |
148
+
|[SQLForeignKeys](sqlforeignkeys.md)| List foreign keys for a table or foreign keys in other tables that reference it |
149
+
|[SQLSpecialColumns](sqlspecialcolumns.md)| Identify columns that uniquely identify a row or update automatically |
150
+
|[SQLStatistics](sqlstatistics.md)| Retrieve index information and table statistics |
151
+
|[SQLProcedures](sqlprocedures.md)| List stored procedures available in the data source |
152
+
|[SQLProcedureColumns](sqlprocedurecolumns.md)| Describe input/output parameters and result columns for stored procedures |
153
+
154
+
### Column and result set metadata
155
+
156
+
Use these functions to examine the structure of result sets and column attributes.
157
+
158
+
| Function | Description |
159
+
| --- | --- |
160
+
|[SQLDescribeCol](sqldescribecol.md)| Get the column name, type, size, and nullability for a result column |
161
+
|[SQLColAttribute](sqlcolattribute.md)| Retrieve a specific attribute of a result set column |
162
+
|[SQLNumResultCols](sqlnumresultcols.md)| Count the number of columns in a result set |
163
+
|[SQLGetTypeInfo](sqlgettypeinfo.md)| List the SQL data types supported by the data source |
164
+
165
+
### Privileges and security
166
+
167
+
Use these functions to retrieve permission information for database objects.
168
+
169
+
| Function | Description |
170
+
| --- | --- |
171
+
|[SQLTablePrivileges](sqltableprivileges.md)| List privileges granted on tables in the data source |
172
+
|[SQLColumnPrivileges](sqlcolumnprivileges.md)| List privileges granted on specific columns of a table |
173
+
174
+
### Environment and statement attributes
175
+
176
+
Use these functions to configure ODBC environment and statement behavior.
177
+
178
+
| Function | Description |
179
+
| --- | --- |
180
+
|[SQLSetEnvAttr](sqlsetenvattr.md)| Set environment attributes such as ODBC version and connection pooling |
181
+
|[SQLGetStmtAttr](sqlgetstmtattr.md)| Retrieve the current value of a statement attribute |
182
+
|[SQLSetStmtAttr](sqlsetstmtattr.md)| Configure statement behavior such as cursor type and query timeout |
183
+
184
+
### Descriptors
185
+
186
+
Use these functions to directly manipulate descriptor records for advanced parameter and column handling.
187
+
188
+
| Function | Description |
189
+
| --- | --- |
190
+
|[SQLGetDescField](sqlgetdescfield.md)| Retrieve a single field from a descriptor record |
191
+
|[SQLSetDescField](sqlsetdescfield.md)| Set a single field in a descriptor record |
192
+
|[SQLSetDescRec](sqlsetdescrec.md)| Set multiple fields in a descriptor record with a single call |
193
+
194
+
### Diagnostics and driver information
195
+
196
+
Use these functions to retrieve error information and query driver capabilities.
197
+
198
+
| Function | Description |
199
+
| --- | --- |
200
+
|[SQLGetDiagField](sqlgetdiagfield.md)| Retrieve a diagnostic field from an environment, connection, or statement |
201
+
|[SQLGetInfo](sqlgetinfo.md)| Get general information about the driver and data source capabilities |
202
+
|[SQLGetFunctions](sqlgetfunctions.md)| Determine which ODBC functions the driver supports |
203
+
204
+
### Resource cleanup
205
+
206
+
Use these functions to release handles and free resources.
207
+
208
+
| Function | Description |
209
+
| --- | --- |
210
+
|[SQLFreeHandle](sqlfreehandle.md)| Release an environment, connection, statement, or descriptor handle |
211
+
|[SQLFreeStmt](sqlfreestmt.md)| Free statement resources, close cursors, or unbind parameters and columns |
212
+
213
+
## Related content
214
+
215
+
-[SQL Server Native Client (ODBC) Reference](../native-client/odbc/sql-server-native-client-odbc.md)
0 commit comments