SQLFreeHandle 関数

[アーティクル]
05/23/2023

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

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

Note

この関数は、ハンドルを解放するためのジェネリック関数です。 ODBC 2.0 関数 SQLFreeConnect (接続ハンドルを解放する場合) と SQLFreeEnv (環境ハンドルを解放する場合) を置き換えます。 SQLFreeConnect と SQLFreeEnv はどちらも ODBC 3*.x* では非推奨です。 SQLFreeHandle では、ステートメントハンドルを解放するための ODBC 2.0 関数 SQLFreeStmt (SQL_DROP オプション) も置き換えられます。詳細については、「コメント」を参照してください。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 ドライバーでの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されます。

SQLSTATE	エラー	説明
HY000	一般的なエラー	特定の SQLSTATE がなく、実装固有の SQLSTATE が定義されていないエラーが発生しました。 MessageText バッファー内の SQLGetDiagRec* によって返されるエラーメッセージは、エラーとその原因を説明します。
HY001	メモリ割り当てエラー	ドライバーは、関数の実行または完了をサポートするために必要なメモリを割り当てることができませんでした。
HY010	関数シーケンスエラー	(DM) HandleType 引数がSQL_HANDLE_ENVされ、少なくとも 1 つの接続が割り当て済みまたは接続状態でした。 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 に関連付けられているステートメントハンドルの 1 つに対して SQLExecute、SQLExecDirect、または SQLMoreResults が呼び出され、SQL_HANDLE_STMTに設定されているか、SQL_PARAM_DATA_AVAILABLE返SQL_HANDLE_DESC。この関数は、ストリーミングされたすべてのパラメーターのデータが取得される前に呼び出されました。
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 は、次のセクションで説明するように、環境、接続、ステートメント、および記述子のハンドルを解放するために使用されます。ハンドルに関する一般的な情報については、「ハンドル」を参照してください。

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

環境ハンドルの解放

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を含む) によって参照される可能性があるアプリケーションによって割り当てられたメモリは解放されません。ポインターフィールドではないフィールドに対してドライバーによって割り当てられたメモリは、ハンドルが解放されると解放されます。ユーザー割り当て記述子ハンドルが解放されると、解放されたハンドルが関連付けられているすべてのステートメントは、自動的に割り当てられたそれぞれの記述子ハンドルに戻ります。

Note

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 関数

構文

引数

戻り値

診断

説明

環境ハンドルの解放

接続ハンドルの解放

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

記述子ハンドルの解放

コード例

コード

関連する関数

参照

フィードバック

その他のリソース

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