Skip to content

Commit 3138fc1

Browse files
committed
docs: ODBC documentation improvements for UUF items
Addressed 5 User Feedback items with 2 actual fixes and 3 verified resolutions: Fix 1: Added SQLBulkOperations to deferred buffers table - Customer reported missing SQLBulkOperations reference - Added to 'Used by' column for deferred input buffers - File: docs/odbc/reference/develop-app/deferred-buffers.md Fix 2: Documented statement handle positioning after SQLExecDirect - Customer requested explicit documentation of cursor positioning behavior - Added paragraph explaining handle positioned before first row after successful execution - File: docs/odbc/reference/syntax/sqlexecdirect-function.md Verified Already Resolved (3 items): - UUF #323305: sysjobhistory duplicate column already fixed - UUF #431658: OLE DB 'system32C3' typo already fixed - UUF #515248: Python package terminology already correct Additional improvements: - Applied Microsoft Writing Style Guide (second person, contractions, active voice) - Added H2 'Deferred buffer types' section for TOC generation - Added/updated Related content sections (replaced 'See Also') - Updated ms.date to 01/27/2026 AB#238870 AB#237448 AB#323305 AB#431658 AB#515248
1 parent 8c532ff commit 3138fc1

2 files changed

Lines changed: 27 additions & 16 deletions

File tree

docs/odbc/reference/develop-app/deferred-buffers.md

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "Deferred Buffers"
33
description: "Deferred Buffers"
44
author: David-Engel
55
ms.author: davidengel
6-
ms.date: "01/19/2017"
6+
ms.date: "01/27/2026"
77
ms.service: sql
88
ms.subservice: connectivity
99
ms.topic: concept-article
@@ -12,13 +12,22 @@ helpviewer_keywords:
1212
- "deferred buffers [ODBC]"
1313
---
1414
# Deferred Buffers
15-
A *deferred buffer* is one whose value is used at some time *after* it is specified in a function call. For example, **SQLBindParameter** is used to associate, or *bind,* a data buffer with a parameter in a SQL statement. The application specifies the number of the parameter and passes the address, byte length, and type of the buffer. The driver saves this information but does not examine the contents of the buffer. Later, when the application executes the statement, the driver retrieves the information and uses it to retrieve the parameter data and send it to the data source. Therefore, the input of data in the buffer is deferred. Because deferred buffers are specified in one function and used in another, it is an application programming error to free a deferred buffer while the driver still expects it to exist; for more information, see [Allocating and Freeing Buffers](../../../odbc/reference/develop-app/allocating-and-freeing-buffers.md), later in this section.
15+
16+
A *deferred buffer* is one whose value is used at some time *after* you specify it in a function call. For example, you use **SQLBindParameter** to associate, or *bind,* a data buffer with a parameter in a SQL statement. You specify the number of the parameter and pass the address, byte length, and type of the buffer. The driver saves this information but doesn't examine the contents of the buffer. Later, when you execute the statement, the driver retrieves the information and uses it to retrieve the parameter data and send it to the data source. Therefore, the input of data in the buffer is deferred. Because deferred buffers are specified in one function and used in another, it's an application programming error to free a deferred buffer while the driver still expects it to exist. For more information, see [Allocating and Freeing Buffers](../../../odbc/reference/develop-app/allocating-and-freeing-buffers.md), later in this section.
1617

17-
Both input and output buffers can be deferred. The following table summarizes the uses of deferred buffers. Note that deferred buffers bound to result set columns are specified with **SQLBindCol**, and deferred buffers bound to SQL statement parameters are specified with **SQLBindParameter**.
18+
## Deferred buffer types
19+
20+
Both input and output buffers can be deferred. The following table summarizes the uses of deferred buffers. Note that deferred buffers bound to result set columns are specified with **SQLBindCol**, and deferred buffers bound to SQL statement parameters are specified with **SQLBindParameter**.
1821

1922
|Buffer use|Type|Specified with|Used by|
2023
|----------------|----------|--------------------|-------------|
2124
|Sending data for input parameters|Deferred input|**SQLBindParameter**|**SQLExecute**<br /> **SQLExecDirect**|
22-
|Sending data to update or insert a row in a result set|Deferred input|**SQLBindCol**|**SQLSetPos**|
25+
|Sending data to update or insert a row in a result set|Deferred input|**SQLBindCol**|**SQLSetPos**<br /> **SQLBulkOperations**|
2326
|Returning data for output and input/output parameters|Deferred output|**SQLBindParameter**|**SQLExecute**<br /> **SQLExecDirect**|
2427
|Returning result set data|Deferred output|**SQLBindCol**|**SQLFetch**<br /> **SQLFetchScroll SQLSetPos**|
28+
29+
## Related content
30+
31+
- [Allocating and Freeing Buffers](../../../odbc/reference/develop-app/allocating-and-freeing-buffers.md)
32+
- [Data Buffer Address](../../../odbc/reference/develop-app/data-buffer-address.md)
33+
- [Binding Parameters ODBC](../../../odbc/reference/develop-app/binding-parameters-odbc.md)

docs/odbc/reference/syntax/sqlexecdirect-function.md

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: "SQLExecDirect Function"
33
description: "SQLExecDirect Function"
44
author: David-Engel
55
ms.author: davidengel
6-
ms.date: "01/19/2017"
6+
ms.date: "01/27/2026"
77
ms.service: sql
88
ms.subservice: connectivity
99
ms.topic: reference
@@ -108,26 +108,28 @@ SQLRETURN SQLExecDirect(
108108
|IM018|**SQLCompleteAsync** has not been called to complete the previous asynchronous operation on this handle.|If the previous function call on the handle returns SQL_STILL_EXECUTING and if notification mode is enabled, **SQLCompleteAsync** must be called on the handle to do post-processing and complete the operation.|
109109
110110
## Comments
111-
The application calls **SQLExecDirect** to send a SQL statement to the data source. For more information about direct execution, see [Direct Execution](../../../odbc/reference/develop-app/direct-execution-odbc.md). The driver modifies the statement to use the form of SQL used by the data source and then submits it to the data source. In particular, the driver modifies the escape sequences used to define certain features in SQL. For the syntax of escape sequences, see [Escape Sequences in ODBC](../../../odbc/reference/develop-app/escape-sequences-in-odbc.md).
111+
You call **SQLExecDirect** to send a SQL statement to the data source. For more information about direct execution, see [Direct Execution](../../../odbc/reference/develop-app/direct-execution-odbc.md). The driver modifies the statement to use the form of SQL that the data source uses and then submits it to the data source. In particular, the driver modifies the escape sequences used to define certain features in SQL. For the syntax of escape sequences, see [Escape Sequences in ODBC](../../../odbc/reference/develop-app/escape-sequences-in-odbc.md).
112112
113-
The application can include one or more parameter markers in the SQL statement. To include a parameter marker, the application embeds a question mark (?) into the SQL statement at the appropriate position. For information about parameters, see [Statement Parameters](../../../odbc/reference/develop-app/statement-parameters.md).
113+
You can include one or more parameter markers in the SQL statement. To include a parameter marker, embed a question mark (?) into the SQL statement at the appropriate position. For information about parameters, see [Statement Parameters](../../../odbc/reference/develop-app/statement-parameters.md).
114114
115-
If the SQL statement is a **SELECT** statement and if the application called **SQLSetCursorName** to associate a cursor with a statement, then the driver uses the specified cursor. Otherwise, the driver generates a cursor name.
115+
After a successful call to **SQLExecDirect** that returns a result set (such as from a **SELECT** statement), the statement handle is positioned before the first row of the result set. You can then call **SQLFetch** or **SQLFetchScroll** to retrieve rows, or call **SQLRowCount** to determine the number of affected rows for **INSERT**, **UPDATE**, or **DELETE** statements.
116116
117-
If the data source is in manual-commit mode (requiring explicit transaction initiation) and a transaction has not already been initiated, the driver initiates a transaction before it sends the SQL statement. For more information, see [Manual-Commit Mode](../../../odbc/reference/develop-app/manual-commit-mode.md).
117+
If the SQL statement is a **SELECT** statement and you called **SQLSetCursorName** to associate a cursor with a statement, the driver uses the specified cursor. Otherwise, the driver generates a cursor name.
118118
119-
If an application uses **SQLExecDirect** to submit a **COMMIT** or **ROLLBACK** statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, an application calls **SQLEndTran**.
119+
If the data source is in manual-commit mode (requiring explicit transaction initiation) and a transaction hasn't already been initiated, the driver initiates a transaction before it sends the SQL statement. For more information, see [Manual-Commit Mode](../../../odbc/reference/develop-app/manual-commit-mode.md).
120120
121-
If **SQLExecDirect** encounters a data-at-execution parameter, it returns SQL_NEED_DATA. The application sends the data using **SQLParamData** and **SQLPutData**. See [SQLBindParameter](../../../odbc/reference/syntax/sqlbindparameter-function.md), [SQLParamData](../../../odbc/reference/syntax/sqlparamdata-function.md), [SQLPutData](../../../odbc/reference/syntax/sqlputdata-function.md), and [Sending Long Data](../../../odbc/reference/develop-app/sending-long-data.md).
121+
If you use **SQLExecDirect** to submit a **COMMIT** or **ROLLBACK** statement, it won't be interoperable between DBMS products. To commit or roll back a transaction, call **SQLEndTran**.
122122
123-
If **SQLExecDirect** executes a searched update, insert, or delete statement that does not affect any rows at the data source, the call to **SQLExecDirect** returns SQL_NO_DATA.
123+
If **SQLExecDirect** encounters a data-at-execution parameter, it returns SQL_NEED_DATA. Send the data using **SQLParamData** and **SQLPutData**. See [SQLBindParameter](../../../odbc/reference/syntax/sqlbindparameter-function.md), [SQLParamData](../../../odbc/reference/syntax/sqlparamdata-function.md), [SQLPutData](../../../odbc/reference/syntax/sqlputdata-function.md), and [Sending Long Data](../../../odbc/reference/develop-app/sending-long-data.md).
124124
125-
If the value of the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1 and the SQL statement contains at least one parameter marker, **SQLExecDirect** will execute the SQL statement once for each set of parameter values from the arrays pointed to by the *ParameterValuePointer* argument in the call to **SQLBindParameter**. For more information, see [Arrays of Parameter Values](../../../odbc/reference/develop-app/arrays-of-parameter-values.md).
125+
If **SQLExecDirect** executes a searched update, insert, or delete statement that doesn't affect any rows at the data source, the call to **SQLExecDirect** returns SQL_NO_DATA.
126126
127-
If bookmarks are turned on and a query is executed that cannot support bookmarks, the driver should attempt to coerce the environment to one that supports bookmarks by changing an attribute value and returning SQLSTATE 01S02 (Option value changed). If the attribute cannot be changed, the driver should return SQLSTATE HY024 (Invalid attribute value).
127+
If the value of the SQL_ATTR_PARAMSET_SIZE statement attribute is greater than 1 and the SQL statement contains at least one parameter marker, **SQLExecDirect** executes the SQL statement once for each set of parameter values from the arrays pointed to by the *ParameterValuePointer* argument in the call to **SQLBindParameter**. For more information, see [Arrays of Parameter Values](../../../odbc/reference/develop-app/arrays-of-parameter-values.md).
128+
129+
If bookmarks are turned on and a query is executed that can't support bookmarks, the driver should attempt to coerce the environment to one that supports bookmarks by changing an attribute value and returning SQLSTATE 01S02 (Option value changed). If the attribute can't be changed, the driver should return SQLSTATE HY024 (Invalid attribute value).
128130
129131
> [!NOTE]
130-
> When using connection pooling, an application must not execute SQL statements that change the database or the context of the database, such as the **USE** _database_ statement in SQL Server, which changes the catalog used by a data source.
132+
> When using connection pooling, don't execute SQL statements that change the database or the context of the database, such as the **USE** _database_ statement in SQL Server, which changes the catalog used by a data source.
131133
132134
## Code Example
133135
See [SQLBindCol](../../../odbc/reference/syntax/sqlbindcol-function.md), [SQLGetData](../../../odbc/reference/syntax/sqlgetdata-function.md), and [Sample ODBC Program](../../../odbc/reference/sample-odbc-program.md).
@@ -150,6 +152,6 @@ SQLRETURN SQLExecDirect(
150152
|Setting a cursor name|[SQLSetCursorName Function](../../../odbc/reference/syntax/sqlsetcursorname-function.md)|
151153
|Setting a statement attribute|[SQLSetStmtAttr Function](../../../odbc/reference/syntax/sqlsetstmtattr-function.md)|
152154
153-
## See Also
155+
## Related content
154156
[ODBC API Reference](../../../odbc/reference/syntax/odbc-api-reference.md)
155157
[ODBC Header Files](../../../odbc/reference/install/odbc-header-files.md)

0 commit comments

Comments
 (0)