符合性
引進版本：ODBC 1.0 標準合規性：ISO 92
總結
SQLFreeStmt 會停止與特定語句相關的處理，關閉與該語句相關的任何未開啟游標，丟棄待處理結果，或選擇性地釋放與該語句 handle 相關的所有資源。
Syntax
SQLRETURN SQLFreeStmt(
SQLHSTMT StatementHandle,
SQLUSMALLINT Option);
論點
StatementHandle
[輸入]語句 handle
選項
[輸入]以下選項之一：
SQL_ 關閉：關閉與 StatementHandle 相關的游標（若已定義），並丟棄所有待處理結果。 應用程式之後可以透過再次執行 SELECT 語句，並以相同或不同的參數值重新開啟這個游標。 若游標未開啟，此選項對應用程式無效。 也可以呼叫 SQLCloseCursor 來關閉游標。 更多資訊請參見 關閉游標。
SQL_DROP：此選項已被棄用。 呼叫 SQLFreeStmt 並設定 Option of 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。
Diagnostics
當 SQLFreeStmt 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可以透過呼叫 SQLGetDiagRec 並設定 HandleType 為 SQL_HANDLE_STMT 和 Handle 為StatementHandle 來取得相應的 SQLSTATE 值。 下表列出 SQLFreeStmt 通常回傳的 SQLSTATE 值，並在此函式情境下說明每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。 除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。
| SQLSTATE | 錯誤 | 說明 |
|---|---|---|
| 01000 | 一般警告 | 驅動程式特定的資訊訊息。 （函式會傳回SQL_SUCCESS_WITH_INFO。） |
| HY000 | 一般誤差 | 發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 *MessageText 緩衝區中 SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。 |
| HY001 | 記憶體配置錯誤 | 驅動程式無法配置支援執行或完成函式所需的記憶體。 |
| HY010 | 函式順序錯誤 | （DM） 已針對與 StatementHandle 相關聯的連接句柄呼叫異步執行函式。 當呼叫 SQLFreeStmt 時，這個非同步函式仍在執行中。 （DM） 已針對 StatementHandle 呼叫 SQLExecute、SQLExecDirect 或 SQLMoreResults，並傳回SQL_PARAM_DATA_AVAILABLE。 此函式在 Option 設定為 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 相關聯的驅動程式不支援 函式。 |
評論
使用SQL_CLOSE選項呼叫 SQLFreeStmt 等同於呼叫 SQLCloseCursor，但若該語句上沒有開啟游標，則以 SQL_CLOSE 呼叫 SQLFreeStmt 不會影響應用程式。 若未開啟游標，呼叫 SQLCloseCursor 會回傳 SQLSTATE 24000（游標狀態無效）。
應用程式在解救後不應使用語句句柄;驅動程式管理器不會在函式呼叫中檢查句柄的有效性。
Example
釋放句柄是一種良好的程式設計實踐。 然而，為了簡化起見，以下範例不包含釋放已配置的句柄的程式碼。 關於如何釋放句柄的範例，請參見 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 函式 |