CLI の手引きおよび解説書

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

目的


仕様: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLFreeStmt() は、ステートメント・ハンドルで参照されているステートメントに関する処理を終了します。以下の目的でこの関数を使用します。

SQL ステートメントを実行して結果を処理した後、SQLFreeStmt() を呼び出します。

構文

SQLRETURN   SQLFreeStmt      (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLUSMALLINT      Option);           /* fOption */

関数引き数

表 88. SQLFreeStmt 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル
SQLUSMALLINT Option 入力 ステートメント・ハンドルの解放の仕方を指定するオプション。このオプションは、以下の値のうちの 1 つでなければなりません。
  • SQL_CLOSE
  • SQL_DROP
  • SQL_UNBIND
  • SQL_RESET_PARAMS

使用法

以下のオプションを指定して SQLFreeStmt() を呼び出すことができます。

SQL_CLOSE
ステートメント・ハンドル (StatementHandle) に関連したカーソル (存在する場合) がクローズされ、保留状態の結果がすべて廃棄されます。アプリケーションは、StatementHandle にバインドされているアプリケーション変数 (存在する場合) と同じ値または別の値を指定して SQLExecute() を呼び出して、カーソルを再オープンします。ステートメント・ハンドルが除去されるか、次の SQLSetCursorName() 呼び出しが成功するまで、カーソル名が保持されます。カーソルがステートメント・ハンドルに関連付けされていない場合、このオプションは無効です (警告またはエラーが生成されません)。

SQLCloseCursor() を使用してカーソルをクローズすることもできます。

SQL_DROP
入力ステートメント・ハンドルに関連した DB2 CLI 資源が解放され、ハンドルが無効にされます。オープン・カーソル (存在する場合) がクローズされ、保留状態の結果がすべて廃棄されます。

このオプションは、SQL_HANDLE_STMT の HandleType セットを使用する SQLFreeHandle() 呼び出しと置き換えられました。このバージョンの DB2 CLI でも引き続きこのオプションをサポートしていますが、 SQLFreeHandle() の使用を DB2 CLI プログラムから開始するなら最新の規格に適合できるため、この方法をお勧めします。

SQL_UNBIND
ARD の SQL_DESC_COUNT フィールドを 0 に設定し、指定されている StatementHandleSQLBindCol() または SQLBindFileToCol() によってバインドされている列バッファーをすべて解放します。これは、ブックマーク列をアンバインドすることはありません。これを行うには、そのブックマーク列の ARD の SQL_DESC_DATA_PTR フィールドを NULL に設定します。この操作が複数のステートメントによって共用されている明示的に割り当てられた記述子で実行される場合、その操作は記述子を共用するステートメントすべてのバインドに影響することに注意してください。

SQL_RESET_PARAMS
APD の SQL_DESC_COUNT フィールドを 0 に設定し、指定されている StatementHandleSQLBindParameter() または SQLBindFileToParam() によって設定されているパラメーター・バッファーをすべて解放します。この操作が複数のステートメントによって共用されている明示的に割り当てられた記述子で実行される場合、その操作は記述子を共用するステートメントすべてのバインドに影響することに注意してください。

SQLFreeStmt() は LOB ロケーターには無効で、 FREE LOCATOR ステートメントを指定して SQLExecDirect() を呼び出し、ロケーターを解放します。 LOB の使用法の詳細については、ラージ・オブジェクトの使用を参照してください。

照会、カタログ関数、または SQLGetTypeInfo() に関連付けられているステートメント・ハンドルが次のようになっているときに、ステートメントを再使用して別のステートメントを実行する方法を示します。

別の方法として、ステートメント・ハンドルを除去し、新しいステートメント・ハンドルを割り振ることができます。

戻りコード

Option を SQL_DROP に設定したときに SQL_SUCCESS_WITH_INFO が返されない理由は、 SQLError() を呼び出すときに使用するステートメント・ハンドルがないことが考えられます。

診断

表 89. SQLFreeStmt SQLSTATE
SQLSTATE 説明 解説
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
58004 予期しないシステム障害です。 回復不能システム・エラー。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY010 関数の順序エラーです。 実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。
HY092 オプション・タイプが範囲外です。 引き数 Option に指定された値は、SQL_CLOSE、 SQL_DROP、SQL_UNBIND、または SQL_RESET_PARAMS のどれでもありませんでした。
HY506 ファイルのクローズ・エラーが起きました。 一時ファイルをクローズしようとしているときにエラーが発生しました。

許可

なし。

CLI サンプル utilcli.c

(ここで完全サンプル utilcli.c を使用することもできます 。)

/* From the CLI sample utilcli.c */
/* ... */
    sqlrc = SQLFreeStmt( hstmt, SQL_UNBIND ) ;
    rc = HandleInfoPrint( SQL_HANDLE_STMT, hstmt,
                          sqlrc, __LINE__, __FILE__);
    if( rc != 0) return(1) ;    
    
/* ... */
    sqlrc = SQLFreeStmt( hstmt, SQL_CLOSE ) ;
    rc = HandleInfoPrint( SQL_HANDLE_STMT, hstmt,
                          sqlrc, __LINE__, __FILE__);
    if( rc != 0) return(1) ;
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]