| 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 31. 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).
Releasing Read Locks
The connection attribute SQL_ATTR_CLOSE_BEHAVIOR can be used to indicate whether or not DB2 CLI should attempt to release read locks acquired during a cursor's operation when the cursor is closed.
If SQL_ATTR_CLOSE_BEHAVIOR is set to SQL_CC_RELEASE then the database manager will attempt to release all read locks (if any) that have been held for the cursor. Read locks are IS, S, and U table locks as well as S, NS, and U row locks.
For more information on connection attributes see SQLSetConnectAttr - Set Connection Attributes, specifically SQL_ATTR_CLOSE_BEHAVIOR Connection Attribute. For more information on releasing read locks see:
Return Codes
Diagnostics
Table 32. 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