SQLFreeHandle 関数

準拠
導入されたバージョン: ODBC 3.0 Standards Compliance: ISO 92

まとめ
SQLFreeHandle は、特定の環境、接続、ステートメント、または記述子ハンドルに関連付けられているリソースを解放します。

構文

  
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 ドライバーでのConnection-Pool認識の開発」を参照してください。

HandleType がこれらの値の 1 つでない場合、SQLFreeHandle はSQL_INVALID_HANDLEを返します。

Handle
[入力]解放するハンドル。

戻り値

SQL_SUCCESS、SQL_ERROR、またはSQL_INVALID_HANDLE。

SQLFreeHandle がSQL_ERRORを返す場合、ハンドルは引き続き有効です。

診断

SQLFreeHandle がSQL_ERRORを返すと、SQLFreeHandle が解放しようとしたが解放できなかったハンドルの診断データ構造から、関連付けられた SQLSTATE 値が取得される場合があります。 次の表に、 SQLFreeHandle によって通常返される SQLSTATE 値の一覧を示し、この関数のコンテキストでそれぞれについて説明します。表記 "(DM)" は、ドライバー マネージャーによって返される SQLSTATEs の説明の前にあります。 特に明記されていない限り、各 SQLSTATE 値に関連付けられている戻りコードはSQL_ERRORされます。

説明

SQLFreeHandle は、次のセクションで説明するように、環境、接続、ステートメント、および記述子のハンドルを解放するために使用されます。 ハンドルに関する一般的な情報については、「 ハンドル」を参照してください。

アプリケーションは、解放された後にハンドルを使用しないでください。ドライバー マネージャーは、関数呼び出しでハンドルの有効性を確認しません。

環境ハンドルの解放

HandleType が SQL_HANDLE_ENV の SQLFreeHandle を呼び出す前に、アプリケーションは環境内で割り当てられているすべての接続に対して、HandleType が SQL_HANDLE_DBC の SQLFreeHandle を呼び出す必要があります。 それ以外の場合、 SQLFreeHandle の呼び出しはSQL_ERRORを返し、環境とアクティブな接続は有効なままです。 詳細については、「環境ハンドル」および「環境ハンドルの割り当て」を参照してください。

環境が共有環境の場合、HandleType が SQL_HANDLE_ENV の SQLFreeHandle を呼び出すアプリケーションは、呼び出し後に環境にアクセスできなくなりますが、環境のリソースは必ずしも解放されるとは限りません。 SQLFreeHandle を呼び出すと、環境の参照カウントがデクリメントされます。 参照カウントは、ドライバー マネージャーによって管理されます。 0 に達しない場合、共有環境は別のコンポーネントによって引き続き使用されているため、解放されません。 参照カウントが 0 に達すると、共有環境のリソースが解放されます。

接続ハンドルの解放

HandleType が SQL_HANDLE_DBC の SQLFreeHandle を呼び出す前に、このハンドル* に接続がある場合、アプリケーションは接続に対して SQLDisconnect を呼び出す必要があります。* それ以外の場合、SQLFreeHandle の呼び出しはSQL_ERRORを返し、接続は有効なままです。

詳細については、「 接続ハンドル と データ ソースまたはドライバーからの切断」を参照してください。

ステートメント ハンドルの解放

HandleType が SQL_HANDLE_STMT の SQLFreeHandle を呼び出すと、HandleType が SQL_HANDLE_STMT の SQLAllocHandle の呼び出しによって割り当てられたすべてのリソースが解放されます。 アプリケーションが SQLFreeHandle を呼び出して保留中の結果を含むステートメントを解放すると、保留中の結果が削除されます。 アプリケーションがステートメント ハンドルを解放すると、ドライバーは、そのハンドルに関連付けられている 4 つの自動的に割り当てられた記述子を解放します。 詳細については、「ステートメント ハンドル」および「ステートメント ハンドルの解放」を参照してください。

SQLDisconnect は、接続で開いているステートメントと記述子を自動的に削除します。

記述子ハンドルの解放

HandleType が SQL_HANDLE_DESC の SQLFreeHandle を呼び出すと、Handle の記述子ハンドルが解放されます。 SQLFreeHandle を呼び出しても、Handle の記述子レコードのポインター フィールド (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR、SQL_DESC_OCTET_LENGTH_PTRを含む) によって参照される可能性があるアプリケーションによって割り当てられたメモリは解放されません。 ポインター フィールドではないフィールドに対してドライバーによって割り当てられたメモリは、ハンドルが解放されると解放されます。 ユーザー割り当て記述子ハンドルが解放されると、解放されたハンドルが関連付けられているすべてのステートメントは、自動的に割り当てられたそれぞれの記述子ハンドルに戻ります。

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;   
   }  
}  

関連する関数

参照

ODBC API リファレンス
ODBC ヘッダー ファイル
ODBC のサンプル プログラム