一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
总结
SQLFreeStmt 停止与特定语句相关的处理，关闭与该语句关联的任何开放光标，丢弃待处理结果，或可选地释放与语句句柄相关的所有资源。
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
Arguments
StatementHandle
[输入]语句柄
选项
[输入]以下选项之一：
SQL_ 关闭：关闭与 StatementHandle 关联的光标（如果定义了），并丢弃所有待处理的结果。 应用程序可以稍后通过再次执行相同或不同参数值的 SELECT 语句来重新打开该光标。 如果没有打开光标，这个选项对应用程序没有影响。 也可以调用 SQLCloseCursor 来关闭光标。 更多信息请参见 关闭光标。
SQL_DROP：该选项已被弃用。 调用 SQLFreeStmt 时， 选项为 SQL_DROP 会在驱动程序管理器中映射到 SQLFreeHandle。
SQL_UNBIND：将ARD的SQL_DESC_COUNT字段设为0，释放所有由 SQLBindCol 绑定的列缓冲区，针对给定 的StatementHandle。 这不会解除书签栏的绑定;为此，ARD 中书签列的SQL_DESC_DATA_PTR字段设置为 NULL。 注意，如果该操作对一个显式分配的描述符执行，且该描述符被多个语句共享，该操作将影响所有共享该描述符语句的绑定。 更多信息请参见检索结果概述（基础版）。
SQL_RESET_PARAMS：将APD的SQL_DESC_COUNT字段设为0，释放 SQLBindParameter 为给定 StatementHandle设置的所有参数缓冲区。 如果该操作对一个显式分配且被多个语句共享的描述符执行，则该操作会影响所有共享该描述符语句的绑定。 更多信息请参见 绑定参数。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。
诊断
当 SQLFreeStmt 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT 和 StatementHandle 的 Handle，获得相应的 SQLSTATE 值。 下表列出了 SQLFreeStmt 通常返回的SQLSTATE值，并在此函数的上下文中解释每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 当调用 SQLFreeStmt 时，这个异步函数仍在运行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式参数数据 之前，该 函数在选项设置为SQL_RESET_PARAMS时调用。 （DM） 为 StatementHandle 调用异步执行函数，并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY092 | 选项类型超出范围 | （DM） 参数 Option 指定的值并非： SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 StatementHandle 关联的驱动程序不支持该函数。 |
Comments
使用SQL_CLOSE选项调用 SQLFreeStmt 等同于调用 SQLCloseCursor，但如果语句上没有打开光标， SQLFreeStmt SQL_CLOSE不会影响应用程序。 如果没有打开光标，调用 SQLCloseCursor 返回 SQLSTATE 24000（光标状态无效）。
应用程序在语句被释放后不应使用该句柄;驱动程序管理器不会在函数调用中检查句柄的有效性。
示例
释放句柄是一个很好的编程实践。 但为简化起见，以下示例不包含释放已分配句柄的代码。 关于如何释放句柄的示例，请参见 SQLFreeHandle 函数。
// 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);
}
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 分配手柄 | SQLAllocHandle 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 关闭光标 | SQLCloseCursor 函数 |
| 释放手柄 | SQLFreeHandle 函数 |
| 设置游标名称 | SQLSetCursorName 函数 |