SQLCloseCursor function (CLI) - Close cursor and discard pending results

Closes a cursor that has been opened on a statement and discards pending results.

Specification:

  • CLI 5.0
  • ODBC 3.0
  • ISO CLI

Syntax

SQLRETURN   SQLCloseCursor (SQLHSTMT     StatementHandle);  /* hStmt */

Function arguments

Table 1. 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() can be called before a transaction is completed.

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).

The statement attribute SQL_ATTR_CLOSE_BEHAVIOR can be used to indicate whether or not 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.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. 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 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 is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
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

  /* close the cursor */
    cliRC = SQLCloseCursor(hstmt);