| 仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLFreeHandle() は、特定の環境、接続、またはステートメント・ハンドルと関連したリソースを解放します。
この関数はリソースを解放するための汎用関数です。この関数は、SQLFreeConnect (接続ハンドルの解放用) と SQLFreeEnv() (環境ハンドルの解放 用) に代わる関数です。SQLFreeHandle() は、ステートメント・ハンドルを解放 するための SQLFreeStmt() (SQL_DROP を伴う) に代わる関数でもあります。
構文
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);
関数の引き数
| データ・タイプ | 引き数 | 用途 | 説明 |
|---|---|---|---|
| SQLSMALLINT | HandleType | 入力 | SQLFreeHandle() によって解放されるハンドルのタイプ。
以下のいずれかの値でなければならない。
HandleType が上記のいずれかの値でない場合 、SQLFreeHandle() は SQL_INVALID_HANDLE を戻す。 |
| SQLHANDLE | Handle | 入力 | 解放するハンドルの名前。 |
使用法
SQLFreeHandle() は、環境、接続、およびステートメント用のハンドル解放するために使用します。
アプリケーションではハンドルの解放後にハンドルを使用してはなりません 。DB2 CLI は関数呼び出しにおけるハンドルの妥当性をチェックしません。
環境ハンドルの解放
SQL_HANDLE_ENV の HandleType を指定 して SQLFreeHandle() を呼び出す前に、アプリケーションでは、環境に 割り当てたすべての接続に関して SQL_HANDLE_DBC の HandleType を指定 して SQLFreeHandle() を呼び出す必要があります。そうしないと 、SQLFreeHandle() の呼び出しによって SQL_ERROR が戻され、 この環境とアクティブな接続は有効なまま残ります。
接続ハンドルの解放
SQL_HANDLE_DBC の HandleType を指定 して SQLFreeHandle() を呼び出す前に、アプリケーションでは 接続に関して SQLDisconnect() を呼び出す必要があります。そうしないと 、SQLFreeHandle() の呼び出しによって SQL_ERROR が戻され、 接続は有効のままとなります。
ステートメント・ハンドルの解放
SQL_HANDLE_STMT の HandleType を指定して SQLFreeHandle() を 呼び出すと、SQL_HANDLE_STMT の HandleType を指定 した SQLAllocHandle() への呼び出しによって割り当てられたすべての リソースが解放されます。アプリケーションで SQLFreeHandle() を呼び出して、 保留中の結果を持つステートメントを解放すると、保留中の結果は削除されます。 SQLFreeHandle() の 呼び出し時に保留中の結果がある場合、結果セットは廃棄されます。
SQLDisconnect() は、接続時にオープンされたステートメントをすべて自動的にドロップします。
戻りコード
SQLFreeHandle() が SQL_ERROR を戻した場合は、ハンドルは引き続き有効なままです。
診断
表 61. SQLFreeHandle の SQLSTATE
| SQLSTATE | 説明 | 解説 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。(関数は、SQL_SUCCESS_WITH_INFO を戻す。) |
| 08S01 | 通信リンク障害。 | HandleType 引き数が SQL_HANDLE_DBC であり、DB2 CLI と接続を試みた先の データ・ソース間の通信リンクが、関数の処理完了前に失敗した。 |
| HY000 | 一般エラー。 | エラーは発生したが、特定の SQLSTATE は無い。 SQLGetDiagRec() が *MessageText バッファーに戻したエラー・メッセージが、 エラーとその原因を示しています。 |
| HY001 | メモリーの割り振りの失敗。 | DB2 CLI が、関数の実行または完了のサポートに必要なメモリーを 割り当てることができない。 |
| HY010 | 関数のシーケンス・エラー。 | HandleType 引き数が SQL_HANDLE_ENV であり、少なくとも 1 つの接続が
割り当て状態または接続状態である。HandleType に SQL_HANDLE_ENV を指定
して SQLFreeHandle() を呼び出す前に、接続ごと
に、HandleType に SQL_HANDLE_DBC を指定
して SQLDisconnect() と SQLFreeHandle() を呼び出す必要がある。
HandleType 引き数が SQL_HANDLE_DBC であり、接続に対
して SQLDisconnect() を呼び出す前に、この関数が呼び出される。
HandleType 引き数が SQL_HANDLE_STMT であり、SQLExecute() ま たは SQLExecDirect() がステートメント・ハンドルを使用して 呼び出され、SQL_NEED_DATA が戻された。(DM) SQLFreeHandle() の 呼び出し前に、付随するすべてのハンドルおよび他のリソースが解放されなかった。 |
| HY013 | 予期しないメモリー処理エラー。 | HandleType 引き数は SQL_HANDLE_STMT であるが、 低メモリー状態が原因で基礎となるメモリー・オブジェクトにアクセスできないため、関数呼び出しを処理できない。 |
| HY017 | 自動的に割り当てられた記述子ハンドルの無効な使用。 | Handle 引き数が、自動的に割り振られた記述子または インプリメンテーション記述子用のハンドルに設定されている。 |
制約事項
なし。
関連した解説