SQLFreeHandle() - ハンドルを解放する

SQLFreeHandle() は、環境ハンドル、接続ハンドル、 またはステートメント・ハンドルを解放します。

SQLFreeHandle() の ODBC 仕様

表 1. SQLFreeHandle() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
3.0 あり あり

構文

SQLRETURN  SQLFreeHandle     (SQLSMALLINT       HandleType,
                              SQLHANDLE         Handle);

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLFreeHandle() の引数
データ・タイプ 引数 使用法 説明
SQLSMALLINT HandleType 入力 SQLFreeHandle() により解放されるハンドルのタイプを指定します。 以下のいずれかの値を指定する必要があります。
  • SQL_HANDLE_ENV -- 環境ハンドルの解放
  • SQL_HANDLE_DBC -- 接続ハンドルの解放
  • SQL_HANDLE_STMT -- ステートメント・ハンドルの解放
SQLHANDLE Handle 入力 解放するハンドルの名前を指定します。

使用法

SQLFreeHandle() を使用して、環境、接続、およびステートメントのハンドルを解放します。ハンドル解放後は、アプリケーションでそのハンドルを使用することはありません。

  • 環境ハンドルの解放

    環境ハンドル解放する前に、すべての接続ハンドルを解放する必要があります。 まだ接続ハンドルが残っているときに環境ハンドルを解放しようとする と、SQLFreeHandle() は SQL_ERROR を戻し、その環境とアクティブな接続はすべて有効なまま残ります。

  • 接続ハンドルの解放

    すべてのステートメント・ハンドルの解放、および接続に対する SQLDisconnect() の呼び出しの両方を 行ってから、その接続用のハンドルを解放する必要があります。まだその接続でステートメント・ハンドルが残っているときに接続ハンドルを解放しようとする と、SQLFreeHandle() は SQL_ERROR を戻し、その接続は有効なまま残ります。

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

    SQLFreeHandle() を呼び出してステートメント・ハンドルを解放する と、SQL_HANDLE_STMT の HandleType を指定した SQLAllocHandle() への呼び出しで割り振られた すべてのリソースが解放されます。 SQLFreeHandle() を呼び出して、ペンディング結果を持つステートメントを解放すると、これらの結果は削除されます。

SQLDisconnect() は、接続でオープンされているすべてのステートメントを自動的にドロップします。

戻りコード

SQLFreeHandle() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_INVALID_HANDLE
  • SQL_ERROR

HandleType が有効なタイプではない場合、SQLFreeHandle() は SQL_INVALID_HANDLE を 戻します。SQLFreeHandle() が SQL_ERROR を戻しても、ハンドルは依然として有効です。

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLFreeHandle() の 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 が戻されます。
  • 引数 HandleType が SQL_HANDLE_ENV であり、かつ少なくとも 1 つの接続が 割り振り済み、または接続済みの状態の場合は、SQLDisconnect() および SQLFreeHandle() を 呼び出して各接続を切断および解放してから、環境ハンドルを解放する必要があります。 引数 HandleType が SQL_HANDLE_DBC の場合は、その接続上の全ステートメント・ハンドル を解放および切断してから、接続ハンドルを解放する必要があります。
  • 引数 HandleType が SQL_HANDLE_STMT を指定している場合は、SQLExecute() また は SQLExecDirect() がステートメント・ハンドルを用いて呼び出され、SQL_NEED_DATA を戻します。この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に 呼び出されます。 ステートメント・ハンドルを解放するには、SQLCancel() を出す必要があります。
HY013 予期しないメモリー処理エラーです。 引数 HandleType は SQL_HANDLE_STMT ですが、 基礎となるメモリー・オブジェクトをアクセスできないため、関数呼び出しは処理できません。 このエラーは、メモリー不足状態が原因となっている可能性があります。
HY506 ファイルのクローズ・エラーです。 一時ファイルをクローズしようとしているときにエラーが発生しました。

例

サンプル・アプリケーション DSN8O3VP、あるいは DSN1110.SDSNSAMP データ・セットのオンラインを参照してください。