Purpose
| Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLCloseCursor() closes a cursor that has been opened on a statement, and discards pending results.
Syntax
SQLRETURN SQLCloseCursor (SQLHSTMT StatementHandle);
Function Arguments
Table 28. SQLCloseCursor Arguments
| Data Type | Argument | Use | Description |
|---|---|---|---|
| SQLHSTMT | StatementHandle | input | Statement handle |
Usage
After an application calls SQLCloseCursor(), the application can reopen the cursor later by executing a SELECT statement again with the same or different parameter values.
SQLCloseCursor() returns SQLSTATE 24000 (Invalid cursor state) if no cursor is open. Calling SQLCloseCursor() is equivalent to calling SQLFreeStmt() with the SQL_CLOSE option, with the exception that SQLFreeStmt() with SQL_CLOSE has no effect on the application if no cursor is open on the statement, while SQLCloseCursor() returns SQLSTATE 24000 (Invalid cursor state).
Return Codes
Diagnostics
Table 29. SQLCloseCursor SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | General warning | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 24000 | Invalid cursor state. | No cursor was open on the StatementHandle. (This is returned only by DB2 CLI Version 5 or later.) |
| HY000 | General error. | An error occurred for which there was no specific SQLSTATE. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
| HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory required to support execution or completion of the function. |
| HY010 | Function sequence error. | An asynchronously executing function was called for the
StatementHandle and was still executing when this function was
called.
SQLExecute() or SQLExecDirect() was called for the StatementHandle and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. |
| HY013 | Unexpected memory handling error. | DB2 CLI was unable to access memory required to support execution or completion of the function. |
Restrictions
None.
Example
See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.
References