SQLFreeStmt 函数SQLFreeStmt Function

Conformance
引入的版本:ODBC 1.0 标准符合性:ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

摘要Summary
SQLFreeStmt停止与特定语句关联的处理、关闭与该语句关联的任何打开的游标、放弃挂起的结果, 或者, 还可以释放与该语句句柄关联的所有资源。SQLFreeStmt stops processing associated with a specific statement, closes any open cursors associated with the statement, discards pending results, or, optionally, frees all resources associated with the statement handle.

语法Syntax

  
SQLRETURN SQLFreeStmt(  
     SQLHSTMT       StatementHandle,  
     SQLUSMALLINT   Option);  

参数Arguments

StatementHandleStatementHandle
送语句句柄[Input] Statement handle

选项Option
送以下选项之一:[Input] One of the following options:

关闭 SQL_:关闭与StatementHandle关联的游标 (如果已定义), 并放弃所有挂起的结果。SQL_ CLOSE: Closes the cursor associated with StatementHandle (if one was defined) and discards all pending results. 稍后, 应用程序可以使用相同或不同的参数值再次执行SELECT语句来重新打开此游标。The application can reopen this cursor later by executing a SELECT statement again with the same or different parameter values. 如果没有打开的游标, 则此选项不会影响应用程序。If no cursor is open, this option has no effect for the application. 还可以调用SQLCloseCursor以关闭游标。SQLCloseCursor can also be called to close a cursor. 有关详细信息, 请参阅关闭光标For more information, see Closing the Cursor.

SQL_DROP:已弃用此选项。SQL_DROP: This option is deprecated. 使用 SQL_DROP选项SQLFreeStmt调用将在驱动程序管理器中映射到SQLFreeHandleA call to SQLFreeStmt with an Option of SQL_DROP is mapped in the Driver Manager to SQLFreeHandle.

SQL_UNBIND:将 ARD 的 SQL_DESC_COUNT 字段设置为 0, 并释放SQLBindCol为给定StatementHandle绑定的所有列缓冲区。SQL_UNBIND: Sets the SQL_DESC_COUNT field of the ARD to 0, releasing all column buffers bound by SQLBindCol for the given StatementHandle. 这不取消绑定书签列;为此, "书签" 列的 "SQL_DESC_DATA_PTR" 字段设置为 NULL。This does not unbind the bookmark column; to do that, the SQL_DESC_DATA_PTR field of the ARD for the bookmark column is set to NULL. 请注意, 如果在由多个语句共享的显式分配的描述符上执行此操作, 则该操作将影响所有共享描述符的语句的绑定。Notice that if this operation is performed on an explicitly allocated descriptor that is shared by more than one statement, the operation will affect the bindings of all statements that share the descriptor. 有关详细信息, 请参阅检索结果概述 (基本)For more information, see Overview of Retrieving Results (Basic).

SQL_RESET_PARAMS:将 APD 的 SQL_DESC_COUNT 字段设置为 0, 释放SQLBindParameter为给定的StatementHandle设置的所有参数缓冲区。SQL_RESET_PARAMS: Sets the SQL_DESC_COUNT field of the APD to 0, releasing all parameter buffers set by SQLBindParameter for the given StatementHandle. 如果在由多个语句共享的显式分配的描述符上执行此操作, 此操作将影响共享该描述符的所有语句的绑定。If this operation is performed on an explicitly allocated descriptor that is shared by more than one statement, this operation will affect the bindings of all the statements that share the descriptor. 有关详细信息, 请参阅绑定参数For more information, see Binding Parameters.

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLFreeStmt返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时, 可以通过使用SQLGetDiagRec 的 HandleTypeSQL_HANDLE_STMT句柄调用StatementHandle来获取关联的 SQLSTATE 值。When SQLFreeStmt returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常由SQLFreeStmt返回的 SQLSTATE 值, 并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values typically returned by SQLFreeStmt and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 除非另有说明, 否则与每个 SQLSTATE 值相关联的返回代码为 SQL_ERROR。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE ErrorError 描述Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
HY000HY000 一般错误General error 发生了一个错误, 该错误没有特定的 SQLSTATE, 没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. MessageText 缓冲区中的 SQLGetDiagRec返回的错误消息描述了错误及其原因。 *The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 驱动程序无法分配支持执行或完成此函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY010HY010 函数序列错误Function sequence error (DM) 为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLFreeStmt时仍在执行此异步函数。This asynchronous function was still executing when SQLFreeStmt was called.

(DM) 为StatementHandle调用了SQLExecuteSQLExecDirectSQLMoreResults , 并返回了 SQL_PARAM_DATA_AVAILABLE。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 在为所有流式处理参数检索数据之前, 通过将选项设置为 SQL_RESET_PARAMS 来调用此函数。This function was called with Option set to SQL_RESET_PARAMS before data was retrieved for all streamed parameters.

(DM) 为StatementHandle调用了异步执行的函数, 并且在调用此函数时仍在执行该函数。(DM) An asynchronously executing function was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSETPOS调用了StatementHandle并返回了 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前, 将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.
HY013HY013 内存管理错误Memory management error 未能处理函数调用, 原因可能是由于内存不足而无法访问基础内存对象。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY092HY092 选项类型超出范围Option type out of range (DM) 为参数选项指定的值不是:(DM) The value specified for the argument Option was not:

SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMSSQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS
HYT01HYT01 连接超时已过期Connection timeout expired 连接超时期限在数据源响应请求之前过期。The connection timeout period expired before the data source responded to the request. 连接超时期限通过SQLSetConnectAttr、SQL_ATTR_CONNECTION_TIMEOUT 设置。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此功能Driver does not support this function (DM) 与StatementHandle关联的驱动程序不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.

注释Comments

与 SQL_CLOSE 选项一起调用SQLFreeStmt等效于调用SQLCloseCursor, 只不过带有 SQL_CLOSE 的SQLFreeStmt在语句上没有打开的游标时不会影响应用程序。Calling SQLFreeStmt with the SQL_CLOSE option is equivalent to calling SQLCloseCursor, except that SQLFreeStmt with SQL_CLOSE does not affect the application if no cursor is open on the statement. 如果没有打开的游标, 则调用SQLCloseCursor将返回 SQLSTATE 24000 (无效的游标状态)。If no cursor is open, a call to SQLCloseCursor returns SQLSTATE 24000 (Invalid cursor state).

应用程序在释放后不应使用语句句柄;驱动程序管理器不会检查函数调用中的句柄的有效性。An application should not use a statement handle after it has been freed; the Driver Manager does not check the validity of a handle in a function call.

示例Example

自由句柄是一种很好的编程做法。It is a good programming practice to free handles. 但是, 为简单起见, 下面的示例不包含用于释放已分配的句柄的代码。However, for simplicity, the following sample does not include code that frees allocated handles. 有关如何释放句柄的示例, 请参阅SQLFreeHandle 函数For an example of how to free handles, see SQLFreeHandle Function.

// SQLFreeStmt.cpp  
// compile with: user32.lib odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   // declare and initialize the environment, connection, statement handles  
   SQLHENV henv = NULL;   // Environment     
   SQLHDBC hdbc = NULL;   // Connection handle  
   SQLHSTMT hstmt = NULL;   // Statement handle  
  
   SQLRETURN retCode;  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
   SQLCHAR connStrbuffer[1024];  
   SQLSMALLINT connStrBufferLen;  
   retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);  
   retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
   retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);  
   retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1024 + 1, &connStrBufferLen, SQL_DRIVER_PROMPT);  
   retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retCode = SQLFreeStmt(hstmt, SQL_CLOSE);  
   retCode = SQLFreeStmt(hstmt, SQL_UNBIND);  
   retCode = SQLFreeStmt(hstmt, SQL_RESET_PARAMS);  
}  
有关信息For information about 请参阅See
分配句柄Allocating a handle SQLAllocHandle 函数SQLAllocHandle Function
正在取消语句处理Canceling statement processing SQLCancel 函数SQLCancel Function
关闭游标Closing a cursor SQLCloseCursor 函数SQLCloseCursor Function
释放句柄Freeing a handle SQLFreeHandle 函数SQLFreeHandle Function
设置游标名称Setting a cursor name SQLSetCursorName 函数SQLSetCursorName Function

请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files