SQLFreeStmt 函数
一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
摘要
SQLFreeStmt 停止与特定语句关联的处理，关闭与语句关联的任何打开游标，放弃挂起的结果，或者（可选）释放与语句句柄关联的所有资源。
语法
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
参数
StatementHandle
[输入]语句句柄
选项
[输入]以下选项之一：
SQL_ CLOSE：关闭与 StatementHandle (关联的游标（如果) 定义）并放弃所有挂起的结果。 应用程序稍后可以通过使用相同或不同的参数值再次执行 SELECT 语句来重新打开此游标。 如果未打开游标，则此选项对应用程序不起作用。 还可以调用 SQLCloseCursor 来关闭游标。 有关详细信息，请参阅 关闭光标。
SQL_DROP：此选项已弃用。 SQL_DROP 选项对 SQLFreeStmt 的调用在驱动程序管理器中映射到 SQLFreeHandle。
SQL_UNBIND：将 ARD 的SQL_DESC_COUNT字段设置为 0，为给定的 StatementHandle 释放 SQLBindCol 绑定的所有列缓冲区。 这不会取消绑定书签列;为此，书签列的 ARD 的SQL_DESC_DATA_PTR字段设置为 NULL。 请注意，如果在由多个语句共享的显式分配的描述符上执行此操作，该操作将影响共享该描述符的所有语句的绑定。 有关详细信息，请参阅 基本) (检索结果概述 。
SQL_RESET_PARAMS：将 APD 的SQL_DESC_COUNT字段设置为 0，释放 SQLBindParameter 为给定 StatementHandle 设置的所有参数缓冲区。 如果在由多个语句共享的显式分配的描述符上执行此操作，则此操作将影响共享该描述符的所有语句的绑定。 有关详细信息，请参阅 绑定参数。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLFreeStmt 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle of StatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLFreeStmt 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLFreeStmt 时，此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流参数的数据之前，调用此函数时 Option 设置为 SQL_RESET_PARAMS。 (DM) 为 StatementHandle 调用了异步执行的函数，并在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回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 关联的驱动程序不支持 函数。 |
注释
使用 SQL_CLOSE 选项调用 SQLFreeStmt 等效于调用 SQLCloseCursor，不同之处在于，如果语句上没有打开游标，则具有 SQL_CLOSE 的 SQLFreeStmt 不会影响应用程序。 如果未打开游标，则调用 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 函数 |