SQLFreeHandle 函式

發行項
08/21/2023

一致性
引進版本：ODBC 3.0 標準合規性：ISO 92

摘要
SQLFreeHandle 釋出與特定環境、連接、語句或描述元控制碼相關聯的資源。

注意

此函式是釋放控制碼的泛型函式。它會取代 ODBC 2.0 函式 SQLFreeConnect （用於釋放連接控制碼）和 SQLFreeEnv （用於釋放環境控制碼）。 SQLFreeConnect 和 SQLFreeEnv 在 ODBC 3*.x* 中都已被取代。 SQLFreeHandle 也會將 ODBC 2.0 函式 SQLFreeStmt 取代為釋放語句控制碼的 SQL_DROP Option 。如需詳細資訊，請參閱。如需 Driver Manager 在 ODBC 3*.x* 應用程式使用 ODBC 2*.x* 驅動程式時將此函式對應至哪些資訊，請參閱對應應用程式回溯相容性的取代函式。

語法

  
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。

Handle
[輸入]要釋放的控制碼。

傳回

SQL_SUCCESS、SQL_ERROR或SQL_INVALID_HANDLE。

如果 SQLFreeHandle 傳回SQL_ERROR，控制碼仍然有效。

診斷

當 SQLFreeHandle 傳回SQL_ERROR時 ，可能會從 SQLFreeHandle 嘗試釋放但無法釋放之控制碼 的診斷資料結構取得相關聯的 SQLSTATE 值。下表列出 SQLFreeHandle 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法「（DM）」在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	描述
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中* SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001	記憶體配置錯誤	驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010	函式順序錯誤	（DM） HandleType 引數已SQL_HANDLE_ENV，且至少有一個連線處於已配置或線上狀態。您必須針對每個連線呼叫具有 handleType SQL_HANDLE_DBC 的 SQLDisconnect 和 SQLFreeHandle ，才能呼叫具有 SQL_HANDLE_ENV HandleType 的 SQLFreeHandle 。（DM） HandleType 引數已SQL_HANDLE_DBC，並在呼叫 SQLDisconnect 以進行連線之前呼叫函式。（DM） HandleType 引數已SQL_HANDLE_DBC。使用 Handle 呼叫非同步執行的函式，而且呼叫此函式時，函式仍在執行中。（DM） HandleType 引數已SQL_HANDLE_STMT。使用語句控制碼呼叫 SQLExecute 、 SQLExecDirect 、 SQLBulkOperations 或 SQLSetPos ，並傳回SQL_NEED_DATA。在針對所有資料執行中參數或資料行傳送資料之前，會呼叫此函式。（DM） HandleType 引數已SQL_HANDLE_STMT。在語句控制碼或相關聯的連接控制碼上呼叫非同步執行的函式，而且呼叫此函式時，函式仍在執行中。（DM） HandleType 引數已SQL_HANDLE_DESC。在相關聯的連接控制碼上呼叫非同步執行函式;和函式在呼叫此函式時仍在執行。（DM）呼叫 SQLFreeHandle 之前，所有子公司控制碼和其他資源均未釋出。（DM） *已針對與 Handle 和 HandleType* 相關聯的其中一個語句控制碼呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults** ，該控制碼已設定為SQL_HANDLE_STMT或SQL_HANDLE_DESC傳回SQL_PARAM_DATA_AVAILABLE。在擷取所有資料流程參數的資料之前，會呼叫此函式。
HY013	記憶體管理錯誤	HandleType 引數SQL_HANDLE_STMT或SQL_HANDLE_DESC，因此無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體狀況低。
HY017	自動設定描述元控制碼的使用無效。	（DM） Handle 引數已設定為自動設定的描述元的控制碼。
HY117	連線因為未知的交易狀態而暫停。只允許中斷連線和唯讀函式。	（DM）如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。
HYT01	已超過連線逾時	在資料來源回應要求之前，連線逾時期限已過期。連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。
IM001	驅動程式不支援此函式	（DM） HandleType 引數已SQL_HANDLE_DESC，而驅動程式是 ODBC 2.x 驅動程式。（DM） HandleType 引數已SQL_HANDLE_STMT，而且驅動程式不是有效的 ODBC 驅動程式。

註解

SQLFreeHandle 可用來釋放環境、連接、語句和描述項的控制碼，如下列各節所述。如需控制碼的一般資訊，請參閱控制碼。

應用程式在釋放後不應使用控制碼;驅動程式管理員不會檢查函式呼叫中控制碼的有效性。

釋放環境控制碼

在呼叫 具有 SQL_HANDLE_ENV HandleType 的 SQLFreeHandle 之前，應用程式必須針對環境中配置的所有連線呼叫具有 SQL_HANDLE_DBC HandleType 的 SQLFreeHandle 。否則，對 SQLFreeHandle 的呼叫會傳回SQL_ERROR，而且環境與任何作用中連線仍然有效。如需詳細資訊，請參閱環境控制碼和配置環境控制碼。

如果環境是共用環境，則呼叫 SQLFreeHandle 且 具有 HandleType 的應用程式SQL_HANDLE_ENV在呼叫之後就不再具有環境的存取權，但環境的資源不一定會釋出。對 SQLFreeHandle 的呼叫 會遞減環境的參考計數。驅動程式管理員會維護參考計數。如果它未達到零，則不會釋放共用環境，因為它仍由另一個元件使用。如果參考計數達到零，則會釋放共用環境的資源。

釋放連接控制碼

在呼叫具有 SQL_HANDLE_DBC HandleType 的 SQLFreeHandle 之前，如果此 handle*上有連線，應用程式必須呼叫 SQLDisconnect 。*否則，對 SQLFreeHandle 的呼叫 會傳回SQL_ERROR且連線仍然有效。

如需詳細資訊，請參閱連接控制碼和中斷與資料來源或驅動程式的連線。

釋放陳述式控制代碼

使用 handleType SQL_HANDLE_STMT呼叫 SQLFreeHandle 會釋放呼叫 SQLAllocHandle 且具有 handleType SQL_HANDLE_STMT 的所有資源。當應用程式呼叫 SQLFreeHandle 以釋放具有暫止結果的語句時，會刪除擱置的結果。當應用程式釋放語句控制碼時，驅動程式會釋放與該控制碼相關聯的四個自動設定的描述元。如需詳細資訊，請參閱語句控制碼和釋放語句控制碼。

請注意， SQLDisconnect 會自動卸載連線上開啟的任何語句和描述項。

釋放描述元控制碼

使用 HandleType 的 SQLFreeHandle 呼叫，SQL_HANDLE_DESC釋放 Handle 中的 描述元控制碼 。 對 SQLFreeHandle 的呼叫不會釋放應用程式所配置的任何記憶體，這些記憶體可能由指標欄位參考（包括控制碼 的任何描述項記錄 SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR）。當釋放控制碼時，驅動程式配置給不是指標欄位的欄位所配置的記憶體。釋放使用者配置的描述元控制碼時，釋放控制碼的所有語句都已與還原成各自自動設定的描述元控制碼相關聯。

注意

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 函式
取消語句處理	SQLCance Functionl
設定資料指標名稱	SQLSetCursorName 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔
 ODBC 程式範例

SQLFreeHandle 函式

語法

引數

傳回

診斷

註解

釋放環境控制碼

釋放連接控制碼

釋放陳述式控制代碼

釋放描述元控制碼

程式碼範例

代碼

另請參閱

意見反應

意見反應

其他資源

SQLFreeHandle 函式

語法

引數

傳回

診斷

註解

釋放環境控制碼

釋放連接控制碼

釋放陳述式控制代碼

釋放描述元控制碼

程式碼範例

代碼

相關函數

另請參閱

意見反應

意見反應

其他資源