CLI の手引きおよび解説書

SQLCloseCursor - カーソルをクローズして保留の結果を廃棄する

目的


仕様: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLCloseCursor() は、ステートメントにオープンしていたカーソルをクローズして、保留の結果を廃棄します。

構文

SQLRETURN   SQLCloseCursor   (SQLHSTMT          StatementHandle);

関数引き数

表 31. SQLCloseCursor 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル

使用法

アプリケーションが SQLCloseCursor() を呼び出した後で、アプリケーションは、 SELECT ステートメントを同じかまたは異なるパラメーター値で再実行することにより、カーソルを再オープンすることができます。

カーソルがオープンしていない場合、 SQLCloseCursor() は SQLSTATE 24000 (無効なカーソル状態) を返します。 SQLCloseCursor() 呼び出しは、 SQL_CLOSE オプションを指定した SQLFreeStmt() の呼び出しと同等ですが、例外としては、SQL_CLOSE を指定した SQLFreeStmt() では、カーソルがステートメントにオープンしておらず、 SQLCloseCursor() が SQLSTATE 24000 (無効なカーソル状態) を返すときは、アプリケーションに対して効果がないことです。

読み取りロックの解放

接続属性 SQL_ATTR_CLOSE_BEHAVIOR は、カーソルがクローズする時、カーソルの操作時に獲得された読み取りロックの解放を DB2 CLI に試行させるかどうかを指示するために使用できます。

SQL_ATTR_CLOSE_BEHAVIOR を SQL_CC_RELEASE に設定すると、データベース・マネージャーは、そのカーソルに保持されていたすべての読み取りロックがあれば、その解放を試行します。読み取りロックは、IS、S、および U 表ロックと、S、NS、および U 行ロックです。

接続属性については、SQLSetConnectAttr - 接続属性を設定する、特に SQL_ATTR_CLOSE_BEHAVIOR 接続属性を参照してください。読み取りロックの解放については、以下の資料を参照してください。

戻りコード

診断

表 32. SQLCloseCursor SQLSTATE
SQLSTATE 説明 解説
01000 通常の警告 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。)
24000 カーソル状態が無効です。 StatementHandle でカーソルがオープンしていませんでした。 (これが返されるのは、DB2 CLI バージョン 5 またはそれ以降の場合だけです。)
HY000 一般的なエラーです。 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。
HY010 関数の順序エラーです。 StatementHandle の非同期実行関数が呼び出され、この関数が呼び出された時点でまだ実行中でした。

StatementHandle のために SQLExecute() または SQLExecDirect() が呼び出され、 SQL_NEED_DATA が戻されました。データがすべての実行時データ・パラメーターまたは列用に送られる前に、この関数が呼び出されました。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。

制約

なし。

CLI サンプル dtlob.c

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

/* From the CLI sample dtlob.c */
/* ... */
    /* bind the file-parameter
    /* close the cursor */
    sqlrc = SQLCloseCursor( hstmt ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc); 
    
/* ... */
    
    /* close the cursor */
    sqlrc = SQLCloseCursor( hstmt ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);    
    
 

参照


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