SQLCloseCursor() - カーソルをクローズし、ペンディング結果を廃棄する

SQLCloseCursor() は、ステートメントでオープンされたカーソルをクローズし、ペンディング結果を廃棄します。

SQLCloseCursor() の ODBC 仕様

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

構文

SQLRETURN  SQLCloseCursor (SQLHSTMT          StatementHandle);

関数の引数

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

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

使用法

SQLCloseCursor() は、ステートメントでオープンされたカーソルをクローズし、ペンディング結果を廃棄します。 アプリケーションは SQLCloseCursor() を呼び出した後、同じパラメーター値または異なるパラメーター値を使用して、再度 SELECT ステートメントを実行することにより、 カーソルを再オープンすることができます。カーソルが再オープンされた場合、アプリケーションは同じステートメント・ハンドル を使用します。

オープンされているカーソルがない場合、SQLCloseCursor() は SQLSTATE 24000 (カーソル状態が無効) を戻します。SQLCloseCursor() の呼び出しは、引数 fOption を SQL_CLOSE に 設定した ODBC 2.0 の関数 SQLFreeStmt() の呼び出しに相当します。 例外として、ステートメントでカーソルがオープンになっていない場合は、SQL_CLOSE を 用いた SQLFreeStmt() は効果がありません。 それに対して、SQLCloseCursor() は SQLSTATE 24000 (カーソル状態が無効) を戻します。

戻りコード

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

診断

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

表 3. SQLCloseCursor() の SQLSTATE
SQLSTATE 説明 説明
01000 警告。 通知メッセージ。(SQLCloseCursor() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。)
24000 カーソル状態が無効です。 ステートメント・ハンドルでカーソルがオープンされていません。
HY000 一般エラー。 具体的な SQLSTATE が適用されないエラーが起こりました。 引数 MessageText が指定するバッファーに SQLGetDiagRec() が戻す エラー・メッセージに、このエラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2® ODBC は、関数を実行し、完了するために必要なメモリーを割り振ることができません。
HY010 関数シーケンス・エラーが発生しました。 ステートメント・ハンドルで SQLExecute() または SQLExecDirect() が 呼び出され、SQL_NEED_DATA が戻されました。SQLCloseCursor() が、すべての実行時データ・ パラメーターまたは列にデータが送られる前に呼び出されました。 実行時データ条件を取り消すには、SQLCancel() を呼び出してください。
HY013 予期しないメモリー処理エラーです。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーをアクセスできません。

例

次のコード行によって、ステートメント・ハンドル hstmt でカーソルが クローズされます。
rc=SQLCloseCursor(hstmt);
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc );