仕様: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLCloseCursor() は、ステートメントにオープンしていたカーソルをクローズして、保留の結果を廃棄します。
構文
SQLRETURN SQLCloseCursor (SQLHSTMT StatementHandle);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
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 接続属性を参照してください。読み取りロックの解放については、以下の資料を参照してください。
戻りコード
診断
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 は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
制約
なし。
(ここで完全サンプル 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);
参照