SQLCloseCursor() - カーソルをクローズし、ペンディング結果を廃棄する
SQLCloseCursor() は、ステートメントでオープンされたカーソルをクローズし、ペンディング結果を廃棄します。
SQLCloseCursor() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 3.0 | あり | あり |
構文
SQLRETURN SQLCloseCursor (SQLHSTMT StatementHandle);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| 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 値ごとに、 その記述と説明を一覧で記載してあります。
| 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 );