SQLFreeHandle() - ハンドルを解放する
SQLFreeHandle() は、環境ハンドル、接続ハンドル、 またはステートメント・ハンドルを解放します。
SQLFreeHandle() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
SQLRETURN SQLFreeHandle (SQLSMALLINT HandleType,
SQLHANDLE Handle);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLSMALLINT | HandleType | 入力 | SQLFreeHandle() により解放されるハンドルのタイプを指定します。
以下のいずれかの値を指定する必要があります。
|
| SQLHANDLE | Handle | 入力 | 解放するハンドルの名前を指定します。 |
使用法
SQLFreeHandle() を使用して、環境、接続、およびステートメントのハンドルを解放します。ハンドル解放後は、アプリケーションでそのハンドルを使用することはありません。
- 環境ハンドルの解放
環境ハンドル解放する前に、すべての接続ハンドルを解放する必要があります。 まだ接続ハンドルが残っているときに環境ハンドルを解放しようとする と、SQLFreeHandle() は SQL_ERROR を戻し、その環境とアクティブな接続はすべて有効なまま残ります。
- 接続ハンドルの解放
すべてのステートメント・ハンドルの解放、および接続に対する SQLDisconnect() の呼び出しの両方を 行ってから、その接続用のハンドルを解放する必要があります。まだその接続でステートメント・ハンドルが残っているときに接続ハンドルを解放しようとする と、SQLFreeHandle() は SQL_ERROR を戻し、その接続は有効なまま残ります。
- ステートメント・ハンドルの解放
SQLFreeHandle() を呼び出してステートメント・ハンドルを解放する と、SQL_HANDLE_STMT の HandleType を指定した SQLAllocHandle() への呼び出しで割り振られた すべてのリソースが解放されます。 SQLFreeHandle() を呼び出して、ペンディング結果を持つステートメントを解放すると、これらの結果は削除されます。
SQLDisconnect() は、接続でオープンされているすべてのステートメントを自動的にドロップします。
戻りコード
- SQL_SUCCESS
- SQL_INVALID_HANDLE
- SQL_ERROR
HandleType が有効なタイプではない場合、SQLFreeHandle() は SQL_INVALID_HANDLE を 戻します。SQLFreeHandle() が SQL_ERROR を戻しても、ハンドルは依然として有効です。
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。(SQLFreeHandle() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 08003 | 接続はクローズされています。 | HandleType 引数に SQL_HANDLE_DBC を指定しましたが、関数処理の完了前に Db2® ODBC とデータ・ソース間の通信リンクに障害が発生しました。 |
| HY000 | 一般エラー。 | 具体的な SQLSTATE が存在しないエラーが起こりました。引数 MessageText が指定するバッファーに SQLGetDiagRec() が戻す エラー・メッセージに、このエラーとその原因が記述されています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要な メモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY013 | 予期しないメモリー処理エラーです。 | 引数 HandleType は SQL_HANDLE_STMT ですが、 基礎となるメモリー・オブジェクトをアクセスできないため、関数呼び出しは処理できません。 このエラーは、メモリー不足状態が原因となっている可能性があります。 |
| HY506 | ファイルのクローズ・エラーです。 | 一時ファイルをクローズしようとしているときにエラーが発生しました。 |
例
サンプル・アプリケーション DSN8O3VP、あるいは DSN1110.SDSNSAMP データ・セットのオンラインを参照してください。