SQLFreeHandle 函式
一致性
引進版本：ODBC 3.0 標準合規性：ISO 92
摘要
SQLFreeHandle 釋放與特定環境、連接、語句或描述元句柄相關聯的資源。
注意
此函式是釋放句柄的泛型函式。 它會取代 SQLFreeConnect SQLFreeConnect 的 ODBC 2.0 函式（用於釋放連接句柄），並 SQLFreeEnv（用於釋放環境句柄）。 SQLFreeConnect 和 SQLFreeEnv 在 ODBC 3*.x* 中都已被取代。 SQLFreeHandle 也會取代 ODBC 2.0 函式 SQLFreeStmt（使用 SQL_DROP Option），以釋放語句句柄。 如需詳細資訊，請參閱。如需當 ODBC 3*.x* 應用程式使用 ODBC 2*.x* 驅動程式時，Driver Manager 會將此函式對應至哪些功能的詳細資訊，請參閱 對應取代函式以取得應用程式回溯相容性。
語法
SQLRETURN SQLFreeHandle(
SQLSMALLINT HandleType,
SQLHANDLE Handle);
參數
HandleType
[輸入]SQLFreeHandle釋放的句柄類型。 必須是下列其中一個值：
SQL_HANDLE_DBC
SQL_HANDLE_DBC_INFO_TOKEN
SQL_HANDLE_DESC
SQL_HANDLE_ENV
SQL_HANDLE_STMT
SQL_HANDLE_DBC_INFO_TOKEN句柄只能由驅動程式管理員和驅動程式使用。 應用程式不應該使用此句柄類型。 如需SQL_HANDLE_DBC_INFO_TOKEN的詳細資訊，請參閱在 ODBC 驅動程式中
如果 HandleType 不是其中一個值，SQLFreeHandle 會傳回SQL_INVALID_HANDLE。
句柄
[輸入]要釋放的句柄。
返回
SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。
如果 SQLFreeHandle 傳回SQL_ERROR，句柄仍然有效。
診斷
評論
SQLFreeHandle 可用來釋放環境、連線、語句和描述項的句柄，如下列各節所述。 如需句柄的一般資訊，請參閱 句柄。
應用程式在釋放后不應使用句柄;驅動程式管理員不會檢查函數調用中句柄的有效性。
釋放環境句柄
在呼叫具有 SQL_HANDLE_ENV
如果環境是共用環境，則呼叫 sqlFreeHandle 的應用程式，HandleType SQL_HANDLE_ENV 在呼叫之後就不再具有環境的存取權，但環境的資源不一定可以釋放。 SQLFreeHandle 的呼叫 會遞減環境的參考計數。 驅動程式管理員會維護參考計數。 如果它未達到零，則不會釋放共用環境，因為它仍由另一個元件使用。 如果參考計數達到零，則會釋放共用環境的資源。
釋放連接句柄
在呼叫具有 SQL_HANDLE_DBC HandleTypeSQLFreeHandle 之前，如果此句柄上有連線，應用程式必須呼叫 SQLDisconnect，否則，SQLFreeHandle 傳回SQL_ERROR且連線仍然有效。
如需詳細資訊，請參閱 連接句柄 和 與數據源或驅動程式中斷連線。
釋放語句句柄
使用
請注意，SQLDisconnect 會自動卸除連線上開啟的任何語句和描述項。
釋放描述元句柄
SQLFreeHandle 的呼叫，HandleType 的 SQL_HANDLE_DESC會釋放 Handle中的描述元句柄。 對 SQLFreeHandle
注意
ODBC 2*.x* 驅動程式不支持釋放描述元句柄，就像它們不支援配置描述元句柄一樣。
請注意，SQLDisconnect 會自動卸除連線上開啟的任何語句和描述項。 當應用程式釋放語句句柄時，驅動程式會釋放與該句柄相關聯的所有自動產生的描述元。
如需描述項目的詳細資訊，請參閱 描述元。
程式代碼範例
如需其他程式代碼範例，請參閱 SQLBrowseConnect 和 SQLConnect。
法典
// SQLFreeHandle.cpp
// compile with: user32.lib odbc32.lib
#include <windows.h>
#include <sqlext.h>
#include <stdio.h>
int main() {
SQLRETURN retCode;
HWND desktopHandle = GetDesktopWindow(); // desktop's window handle
SQLCHAR connStrbuffer[1024];
SQLSMALLINT connStrBufferLen;
// Initialize the environment, connection, statement handles.
SQLHENV henv = NULL; // Environment
SQLHDBC hdbc = NULL; // Connection handle
SQLHSTMT hstmt = NULL; // Statement handle
// Allocate the environment.
retCode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
// Set environment attributes.
retCode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, -1);
// Allocate the connection.
retCode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
// Set the login timeout.
retCode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)10, 0);
// Let the user select the data source and connect to the database.
retCode = SQLDriverConnect(hdbc, desktopHandle, (SQLCHAR *)"Driver={SQL Server}", SQL_NTS, connStrbuffer, 1025, &connStrBufferLen, SQL_DRIVER_PROMPT);
retCode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
// Free handles, and disconnect.
if (hstmt) {
SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
hstmt = NULL;
}
if (hdbc) {
SQLDisconnect(hdbc);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
hdbc = NULL;
}
if (henv) {
SQLFreeHandle(SQL_HANDLE_ENV, henv);
henv = NULL;
}
}
相關函式
| 如需相關信息 | 看 |
|---|---|
| 配置句柄 | SQLAllocHandle 函式 |
| 取消語句處理 | SQLCancel 函式 |
| 設定數據指標名稱 | SQLSetCursorName 函式 |