SQLFreeStmt() - ステートメント・ハンドルを解放 (またはリセット) する

SQLFreeStmt() は、ステートメント・ハンドルが参照しているステートメントの処理を終了します。これを使用して、カーソルをクローズするか、ステートメント・ハンドルをドロップして、ステートメント・ハンドルに関連付けられた Db2® ODBC リソースを解放します。SQLFreeStmt() は、SQL ステートメントを実行して結果を処理した後に呼び出します。

SQLFreeStmt() の ODBC 仕様

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

構文

SQLRETURN   SQLFreeStmt      (SQLHSTMT          hstmt,
                              SQLUSMALLINT      fOption);

関数の引数

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

表 2. SQLFreeStmt() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 停止させるステートメントを参照しているステートメント・ハンドルを 指定します。
SQLUSMALLINT fOption 入力 以下の値は、ステートメント・ハンドルを解放する方法を指定します。
  • SQL_UNBIND
  • SQL_RESET_PARAMS
  • SQL_CLOSE
  • SQL_DROP (「使用すべきでない」)

これらの値の詳細については、使用法を参照してください。

使用法

SQLFreeStmt() を呼び出す場合は、引数 fOption を以下のいずれか のオプションに設定します。SQLFreeStmt() は、これらのオプションのいずれが指定されたかによって 、異なるアクションを実行します。
SQL_UNBIND
このステートメント・ハンドルに関する直前の SQLBindCol() 呼び出しでバインドされたすべての列が解放されます (アプリケーション変数またはファイル参照と結果セットの列との間 の関連が切断されます)。
SQL_RESET_PARAMS
直前の SQLBindParameter() 呼び出しがこのステートメント・ハンドル上に 設定したすべてのパラメーターは、解放されます。 (アプリケーション変数またはファイル参照と、ステートメント・ハンドルに対する SQL ステートメントでの パラメーター・マーカー間の関連は切断されます。)
SQL_CLOSE
ステートメント・ハンドルに関連したカーソル (存在する場合) がクローズされ、 すべてのペンディング結果は、廃棄されます。 ステートメント・ハンドルにバインドされている アプリケーション変数 (存在する場合) で、同じ値または異なる値を 指定して SQLExecute() または SQLExecDirect() を呼び出すことによって、 カーソルを再オープンすることができます。カーソル名は、ステートメント・ハンドルがドロップされるか、次の SQLSetCursorName() 呼び出しが成功するまで、保持されます。 カーソルがステートメント・ハンドルに関連付けられていない場合は、 このオプションは無効です。 (カーソルが存在しない場合、警告またはエラーは生成されません。)

また、ODBC 3.0 API SQLCloseCursor() を呼び出して、カーソルをクローズすることもできます。

SQL_DROP (「使用すべきでない」)
ODBC 3.0 では、SQL_HANDLE_STMT に設定した HandleType を 指定して SQLFreeHandle() を使用すると、SQLFreeStmt() の SQL_DROP オプションを置き換えます。

Db2 ODBC は後方互換性のために SQL_DROP をサポートしていますが、 アプリケーションでは現行の ODBC 3.0 の関数を使用してください。

SQLFreeStmt() は LOB ロケーターには影響しません。ロケーターを解放するには、FREE LOCATOR ステートメントを用いて、SQLExecDirect() を呼び 出します。

ステートメント・ハンドルでステートメントを実行したあと、そのハンドルを 再使用して、別のステートメントを実行することができます。 以下の状態の場合は、ステートメント・ハンドルを再使用する前に、追加のアクションが必要です。
  • 再使用するステートメント・ハンドルがカタログ関数または SQLGetTypeInfo() に関連して いる場合、そのハンドルのカーソルをクローズする必要があります。
  • 最初にバインドしたものとは異なる番号または異なるパラメーターのタイプで、 ステートメント・ハンドルを再使用する場合は、そのハンドルでのパラメーターをリセット しておく必要があります。
  • 最初にバインドしたものとは異なる番号または異なる列のタイプで、 ステートメント・ハンドルを再使用する場合は、元の列をアンバインドしておく 必要があります。
あるいは、ステートメント・ハンドルをドロップし、新しい ステートメント・ハンドルを割り当てることもできます。

戻りコード

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

fOption を SQL_DROP に設定した場合には SQL_SUCCESS_WITH_INFO が 戻されません。これは、SQLGetDiagRec() 呼び出し時に使用する ステートメント・ハンドルが使用可能でないためです。

診断

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

表 3. SQLFreeStmt() の SQLSTATE
SQLSTATE 説明 説明
08S01 通信リンクに障害が起きました。 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。
58004 予期しないシステム障害です。 リカバリー不能なシステム・エラーです。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。)
HY092 オプションのタイプが範囲外です。 引数 fOption に指定された値が、以下のいずれかの値ではありません。
  • SQL_CLOSE
  • SQL_DROP
  • SQL_UNBIND
  • SQL_RESET_PARAMS

例

関連例については、SQLFetch() を参照してください。