|
1 | 1 | --- |
2 | | -title: "ODBC API Implementation Details" |
3 | | -description: "ODBC API Implementation Details" |
4 | | -author: markingmyname |
5 | | -ms.author: maghan |
6 | | -ms.date: "03/16/2017" |
| 2 | +title: ODBC API Implementation Details |
| 3 | +description: Learn how the ODBC API processes function calls, manages handles, interacts with drivers, and controls diagnostics in SQL Server and Azure SQL products. |
| 4 | +author: your-alias-here |
| 5 | +ms.author: your-msauthor |
| 6 | +ms.reviewer: maghan |
| 7 | +ms.date: 01/26/2026 |
7 | 8 | ms.service: sql |
8 | | -ms.subservice: native-client |
9 | | -ms.topic: "reference" |
10 | | -helpviewer_keywords: |
11 | | - - "ODBC, functions" |
12 | | - - "SQL Server Native Client ODBC driver, SQL Server-specific behaviors" |
13 | | - - "ODBC, SQL Server-specific behaviors" |
14 | | - - "functions [ODBC]" |
| 9 | +ms.subservice: connectivity |
| 10 | +ms.topic: reference |
15 | 11 | --- |
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. |
24 | | - |
25 | | -## In This Section |
26 | | - |
27 | | -- [SQLBindCol](../../relational-databases/native-client-odbc-api/sqlbindcol.md) |
28 | | - |
29 | | -- [SQLBindParameter](../../relational-databases/native-client-odbc-api/sqlbindparameter.md) |
30 | | - |
31 | | -- [SQLBrowseConnect](../../relational-databases/native-client-odbc-api/sqlbrowseconnect.md) |
32 | | - |
33 | | -- [SQLCancel](../../relational-databases/native-client-odbc-api/sqlcancel.md) |
34 | | - |
35 | | -- [SQLCloseCursor](../../relational-databases/native-client-odbc-api/sqlclosecursor.md) |
36 | | - |
37 | | -- [SQLColAttribute](../../relational-databases/native-client-odbc-api/sqlcolattribute.md) |
38 | | - |
39 | | -- [SQLColumnPrivileges](../../relational-databases/native-client-odbc-api/sqlcolumnprivileges.md) |
40 | | - |
41 | | -- [SQLColumns](../../relational-databases/native-client-odbc-api/sqlcolumns.md) |
42 | | - |
43 | | -- [SQLConfigDataSource](../../relational-databases/native-client-odbc-api/sqlconfigdatasource.md) |
44 | | - |
45 | | -- [SQLConnect](../../relational-databases/native-client-odbc-api/sqlconnect.md) |
46 | | - |
47 | | -- [SQLDescribeCol](../../relational-databases/native-client-odbc-api/sqldescribecol.md) |
48 | | - |
49 | | -- [SQLDescribeParam](../../relational-databases/native-client-odbc-api/sqldescribeparam.md) |
50 | | - |
51 | | -- [SQLDriverConnect](../../relational-databases/native-client-odbc-api/sqldriverconnect.md) |
52 | | - |
53 | | -- [SQLDrivers](../../relational-databases/native-client-odbc-api/sqldrivers.md) |
54 | | - |
55 | | -- [SQLEndTran](../../relational-databases/native-client-odbc-api/sqlendtran.md) |
56 | | - |
57 | | -- [SQLExecDirect](../../relational-databases/native-client-odbc-api/sqlexecdirect.md) |
58 | | - |
59 | | -- [SQLExecute](../../relational-databases/native-client-odbc-api/sqlexecute.md) |
60 | | - |
61 | | -- [SQLFetch](../../relational-databases/native-client-odbc-api/sqlfetch.md) |
62 | | - |
63 | | -- [SQLFetchScroll](../../relational-databases/native-client-odbc-api/sqlfetchscroll.md) |
64 | | - |
65 | | -- [SQLForeignKeys](../../relational-databases/native-client-odbc-api/sqlforeignkeys.md) |
66 | | - |
67 | | -- [SQLFreeHandle](../../relational-databases/native-client-odbc-api/sqlfreehandle.md) |
68 | | - |
69 | | -- [SQLFreeStmt](../../relational-databases/native-client-odbc-api/sqlfreestmt.md) |
70 | | - |
71 | | -- [SQLGetConnectAttr](../../relational-databases/native-client-odbc-api/sqlgetconnectattr.md) |
72 | | - |
73 | | -- [SQLGetCursorName](../../relational-databases/native-client-odbc-api/sqlgetcursorname.md) |
74 | | - |
75 | | -- [SQLGetData](../../relational-databases/native-client-odbc-api/sqlgetdata.md) |
76 | | - |
77 | | -- [SQLGetDescField](../../relational-databases/native-client-odbc-api/sqlgetdescfield.md) |
78 | | - |
79 | | -- [SQLGetDiagField](../../relational-databases/native-client-odbc-api/sqlgetdiagfield.md) |
80 | | - |
81 | | -- [SQLGetFunctions](../../relational-databases/native-client-odbc-api/sqlgetfunctions.md) |
82 | | - |
83 | | -- [SQLGetInfo](../../relational-databases/native-client-odbc-api/sqlgetinfo.md) |
84 | | - |
85 | | -- [SQLGetStmtAttr](../../relational-databases/native-client-odbc-api/sqlgetstmtattr.md) |
86 | | - |
87 | | -- [SQLGetTypeInfo](../../relational-databases/native-client-odbc-api/sqlgettypeinfo.md) |
88 | | - |
89 | | -- [SQLMoreResults](../../relational-databases/native-client-odbc-api/sqlmoreresults.md) |
90 | | - |
91 | | -- [SQLNativeSql](../../relational-databases/native-client-odbc-api/sqlnativesql.md) |
92 | | - |
93 | | -- [SQLNumParams](../../relational-databases/native-client-odbc-api/sqlnumparams.md) |
94 | | - |
95 | | -- [SQLNumResultCols](../../relational-databases/native-client-odbc-api/sqlnumresultcols.md) |
96 | | - |
97 | | -- [SQLParamData](../../relational-databases/native-client-odbc-api/sqlparamdata.md) |
98 | | - |
99 | | -- [SQLPrimaryKeys](../../relational-databases/native-client-odbc-api/sqlprimarykeys.md) |
100 | | - |
101 | | -- [SQLProcedureColumns](../../relational-databases/native-client-odbc-api/sqlprocedurecolumns.md) |
102 | | - |
103 | | -- [SQLProcedures](../../relational-databases/native-client-odbc-api/sqlprocedures.md) |
104 | | - |
105 | | -- [SQLPutData](../../relational-databases/native-client-odbc-api/sqlputdata.md) |
106 | | - |
107 | | -- [SQLRowCount](../../relational-databases/native-client-odbc-api/sqlrowcount.md) |
108 | | - |
109 | | -- [SQLSetConnectAttr](../../relational-databases/native-client-odbc-api/sqlsetconnectattr.md) |
110 | | - |
111 | | -- [SQLSetDescField](../../relational-databases/native-client-odbc-api/sqlsetdescfield.md) |
112 | | - |
113 | | -- [SQLSetDescRec](../../relational-databases/native-client-odbc-api/sqlsetdescrec.md) |
114 | | - |
115 | | -- [SQLSetEnvAttr](../../relational-databases/native-client-odbc-api/sqlsetenvattr.md) |
116 | | - |
117 | | -- [SQLSetStmtAttr](../../relational-databases/native-client-odbc-api/sqlsetstmtattr.md) |
118 | | - |
119 | | -- [SQLSpecialColumns](../../relational-databases/native-client-odbc-api/sqlspecialcolumns.md) |
120 | | - |
121 | | -- [SQLStatistics](../../relational-databases/native-client-odbc-api/sqlstatistics.md) |
122 | | - |
123 | | -- [SQLTablePrivileges](../../relational-databases/native-client-odbc-api/sqltableprivileges.md) |
124 | | - |
125 | | -- [SQLTables](../../relational-databases/native-client-odbc-api/sqltables.md) |
126 | | - |
127 | | -## See Also |
128 | | - [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 | | - |
| 12 | + |
| 13 | +# ODBC API implementation details |
| 14 | + |
| 15 | +[!INCLUDE [SQL Server Azure SQL Database Synapse Analytics PDW](../../includes/applies-to-version/sql-asdb-asdbmi-asa-pdw.md)] |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +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). |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## How the ODBC API works |
| 26 | + |
| 27 | +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. |
| 28 | + |
| 29 | +### ODBC handle model |
| 30 | + |
| 31 | +ODBC uses four hierarchical handle types to manage state: |
| 32 | + |
| 33 | +| Handle type | Purpose | |
| 34 | +| --- | --- | |
| 35 | +| **Environment (HENV)** | Global ODBC settings and versioning. | |
| 36 | +| **Connection (HDBC)** | Represents a connection to a specific data source. | |
| 37 | +| **Statement (HSTMT)** | Manages SQL statements, parameters, and result sets. | |
| 38 | +| **Descriptor (HDESC)** | Stores metadata for parameters and columns. | |
| 39 | + |
| 40 | +### Driver manager and driver interaction |
| 41 | + |
| 42 | +1. The application makes an ODBC API call. |
| 43 | +1. The **Driver Manager** validates parameters and dispatches the call. |
| 44 | +1. The **driver** interacts with the data source. |
| 45 | +1. Results flow back through the Driver Manager to the application. |
| 46 | + |
| 47 | +### Function call lifecycle |
| 48 | + |
| 49 | +1. Allocate handles. |
| 50 | +1. Set environment or connection attributes. |
| 51 | +1. Connect to a data source. |
| 52 | +1. Prepare or execute SQL statements. |
| 53 | +1. Bind parameters or result columns. |
| 54 | +1. Fetch rows. |
| 55 | +1. Free handles. |
| 56 | + |
| 57 | +### Diagnostics and error handling |
| 58 | + |
| 59 | +Use the following diagnostic functions: |
| 60 | + |
| 61 | +- `SQLGetDiagRec` |
| 62 | +- `SQLGetDiagField` |
| 63 | + |
| 64 | +Diagnostics might apply to environment, connection, or statement handles. |
| 65 | + |
| 66 | +### Unicode vs. ANSI calls |
| 67 | + |
| 68 | +ODBC provides two types of functions: |
| 69 | + |
| 70 | +- **ANSI functions** like `SQLExecDirectA` |
| 71 | +- **Unicode functions** like `SQLExecDirectW` |
| 72 | + |
| 73 | +Use Unicode APIs for modern applications. |
| 74 | + |
| 75 | +### Threading and pooling |
| 76 | + |
| 77 | +- Thread safety depends on how the application configures the driver and Driver Manager. |
| 78 | +- You can enable connection pooling at either level to reduce connection overhead. |
| 79 | + |
| 80 | +--- |
| 81 | + |
| 82 | +# ODBC API reference (table layout) |
| 83 | + |
| 84 | +The following table lists the available ODBC API functions documented for the SQL Server Native Client driver. Each entry links to its corresponding detailed reference page. |
| 85 | + |
| 86 | +| Function | Description | |
| 87 | +| --- | --- | |
| 88 | +| [SQLBindCol](../../relational-databases/native-client-odbc-api/sqlbindcol.md) | Bind application variables to result columns. | |
| 89 | +| [SQLBindParameter](../../relational-databases/native-client-odbc-api/sqlbindparameter.md) | Bind application variables to SQL statement parameters. | |
| 90 | +| [SQLBrowseConnect](../../relational-databases/native-client-odbc-api/sqlbrowseconnect.md) | Build connection strings interactively. | |
| 91 | +| [SQLCancel](../../relational-databases/native-client-odbc-api/sqlcancel.md) | Cancel statement execution. | |
| 92 | +| [SQLCloseCursor](../../relational-databases/native-client-odbc-api/sqlclosecursor.md) | Close an open cursor. | |
| 93 | +| [SQLColAttribute](../../relational-databases/native-client-odbc-api/sqlcolattribute.md) | Retrieve column metadata. | |
| 94 | +| [SQLColumnPrivileges](../../relational-databases/native-client-odbc-api/sqlcolumnprivileges.md) | Retrieve privileges for table columns. | |
| 95 | +| [SQLColumns](../../relational-databases/native-client-odbc-api/sqlcolumns.md) | Retrieve column metadata for tables. | |
| 96 | +| [SQLConfigDataSource](../../relational-databases/native-client-odbc-api/sqlconfigdatasource.md) | Configure DSNs. | |
| 97 | +| [SQLConnect](../../relational-databases/native-client-odbc-api/sqlconnect.md) | Connect to a data source. | |
| 98 | +| [SQLDescribeCol](../../relational-databases/native-client-odbc-api/sqldescribecol.md) | Retrieve column descriptions. | |
| 99 | +| [SQLDescribeParam](../../relational-databases/native-client-odbc-api/sqldescribeparam.md) | Retrieve SQL parameter metadata. | |
| 100 | +| [SQLDriverConnect](../../relational-databases/native-client-odbc-api/sqldriverconnect.md) | Connect using a full or partial connection string. | |
| 101 | +| [SQLDrivers](../../relational-databases/native-client-odbc-api/sqldrivers.md) | Enumerate installed ODBC drivers. | |
| 102 | +| [SQLEndTran](../../relational-databases/native-client-odbc-api/sqlendtran.md) | Commit or roll back transactions. | |
| 103 | +| [SQLExecDirect](../../relational-databases/native-client-odbc-api/sqlexecdirect.md) | Execute SQL directly. | |
| 104 | +| [SQLExecute](../../relational-databases/native-client-odbc-api/sqlexecute.md) | Execute prepared SQL statements. | |
| 105 | +| [SQLFetch](../../relational-databases/native-client-odbc-api/sqlfetch.md) | Fetch result rows sequentially. | |
| 106 | +| [SQLFetchScroll](../../relational-databases/native-client-odbc-api/sqlfetchscroll.md) | Fetch rows using scrollable cursors. | |
| 107 | +| [SQLForeignKeys](../../relational-databases/native-client-odbc-api/sqlforeignkeys.md) | Retrieve foreign key information. | |
| 108 | +| [SQLFreeHandle](../../relational-databases/native-client-odbc-api/sqlfreehandle.md) | Free an ODBC handle. | |
| 109 | +| [SQLFreeStmt](../../relational-databases/native-client-odbc-api/sqlfreestmt.md) | Free resources associated with a statement. | |
| 110 | +| [SQLGetConnectAttr](../../relational-databases/native-client-odbc-api/sqlgetconnectattr.md) | Retrieve connection attributes. | |
| 111 | +| [SQLGetCursorName](../../relational-databases/native-client-odbc-api/sqlgetcursorname.md) | Retrieve the name of a cursor. | |
| 112 | +| [SQLGetData](../../relational-databases/native-client-odbc-api/sqlgetdata.md) | Retrieve data for a result column. | |
| 113 | +| [SQLGetDescField](../../relational-databases/native-client-odbc-api/sqlgetdescfield.md) | Retrieve descriptor fields. | |
| 114 | +| [SQLGetDiagField](../../relational-databases/native-client-odbc-api/sqlgetdiagfield.md) | Retrieve detailed diagnostic information. | |
| 115 | +| [SQLGetFunctions](../../relational-databases/native-client-odbc-api/sqlgetfunctions.md) | Determine which functions a driver supports. | |
| 116 | +| [SQLGetInfo](../../relational-databases/native-client-odbc-api/sqlgetinfo.md) | Retrieve driver-specific information. | |
| 117 | +| [SQLGetStmtAttr](../../relational-databases/native-client-odbc-api/sqlgetstmtattr.md) | Retrieve statement attributes. | |
| 118 | +| [SQLGetTypeInfo](../../relational-databases/native-client-odbc-api/sqlgettypeinfo.md) | Retrieve supported SQL data types. | |
| 119 | +| [SQLMoreResults](../../relational-databases/native-client-odbc-api/sqlmoreresults.md) | Process multiple result sets. | |
| 120 | +| [SQLNativeSql](../../relational-databases/native-client-odbc-api/sqlnativesql.md) | Convert SQL statements to the driver's native SQL dialect. | |
| 121 | +| [SQLNumParams](../../relational-databases/native-client-odbc-api/sqlnumparams.md) | Return the number of parameters in a prepared statement. | |
| 122 | +| [SQLNumResultCols](../../relational-databases/native-client-odbc-api/sqlnumresultcols.md) | Return the number of result columns. | |
| 123 | +| [SQLParamData](../../relational-databases/native-client-odbc-api/sqlparamdata.md) | Retrieve next parameter in a data-at-execution operation. | |
| 124 | +| [SQLPrimaryKeys](../../relational-databases/native-client-odbc-api/sqlprimarykeys.md) | Retrieve primary key information. | |
| 125 | +| [SQLProcedureColumns](../../relational-databases/native-client-odbc-api/sqlprocedurecolumns.md) | Retrieve stored procedure parameter metadata. | |
| 126 | +| [SQLProcedures](../../relational-databases/native-client-odbc-api/sqlprocedures.md) | Retrieve stored procedure metadata. | |
| 127 | +| [SQLPutData](../../relational-databases/native-client-odbc-api/sqlputdata.md) | Send parameter data at execution time. | |
| 128 | +| [SQLRowCount](../../relational-databases/native-client-odbc-api/sqlrowcount.md) | Retrieve number of rows affected by a statement. | |
| 129 | +| [SQLSetConnectAttr](../../relational-databases/native-client-odbc-api/sqlsetconnectattr.md) | Set connection attributes. | |
| 130 | +| [SQLSetDescField](../../relational-databases/native-client-odbc-api/sqlsetdescfield.md) | Set descriptor fields. | |
| 131 | +| [SQLSetDescRec](../../relational-databases/native-client-odbc-api/sqlsetdescrec.md) | Set descriptor records. | |
| 132 | +| [SQLSetEnvAttr](../../relational-databases/native-client-odbc-api/sqlsetenvattr.md) | Set environment attributes. | |
| 133 | +| [SQLSetStmtAttr](../../relational-databases/native-client-odbc-api/sqlsetstmtattr.md) | Set statement attributes. | |
| 134 | +| [SQLSpecialColumns](../../relational-databases/native-client-odbc-api/sqlspecialcolumns.md) | Retrieve special column information. | |
| 135 | +| [SQLStatistics](../../relational-databases/native-client-odbc-api/sqlstatistics.md) | Retrieve index and statistic information. | |
| 136 | +| [SQLTablePrivileges](../../relational-databases/native-client-odbc-api/sqltableprivileges.md) | Retrieve table privilege information. | |
| 137 | +| [SQLTables](../../relational-databases/native-client-odbc-api/sqltables.md) | Retrieve table metadata. | |
| 138 | + |
| 139 | +--- |
| 140 | + |
| 141 | +## Related content |
| 142 | + |
| 143 | +- [SQL Server Native Client (ODBC) Reference](../native-client/odbc/sql-server-native-client-odbc.md) |
0 commit comments