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時 ，可以使用SQL_HANDLE_STMT的 HandleType 和 StatementHandle 控制碼 呼叫 SQLGetDiagRec 來取得相關聯的 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。 在擷取所有資料流程參數的資料之前，已呼叫 此選項 設定為 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 （資料指標狀態無效）。
應用程式在釋放語句控制碼之後，不應該使用語句控制碼;驅動程式管理員不會檢查函式呼叫中控制碼的有效性。
範例
免費控制碼是很好的程式設計作法。 不過，為了簡單起見，下列範例不包含釋放配置控制碼的程式碼。 如需如何釋放控制碼的範例，請參閱 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 函式 |