SQLCloseCursor() - Close a cursor and discard pending results

SQLCloseCursor() closes a cursor that has been opened on a statement and discards pending results.

ODBC specifications for SQLCloseCursor()

Table 1. SQLCloseCursor() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
3.0 Yes Yes

Syntax

SQLRETURN  SQLCloseCursor (SQLHSTMT          StatementHandle);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLCloseCursor() arguments
Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.

Usage

SQLCloseCursor() closes a cursor that has been opened on a statement and discards pending results. After an application calls SQLCloseCursor(), the application can reopen the cursor by executing a SELECT statement again with the same or different parameter values. When the cursor is reopened, the application uses the same statement handle.

SQLCloseCursor() returns SQLSTATE 24000 (invalid cursor state) if no cursor is open. Calling SQLCloseCursor() is equivalent to calling the ODBC 2.0 function SQLFreeStmt() with fOption argument set to SQL_CLOSE. An exception is that SQLFreeStmt() with SQL_CLOSE has no effect on the application if no cursor is open on the statement, whereas SQLCloseCursor() returns SQLSTATE 24000 (invalid cursor state).

Return codes

After you call SQLCloseCursor(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_INVALID_HANDLE
  • SQL_ERROR

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. SQLCloseCursor() SQLSTATEs
SQLSTATE Description Explanation
01000 Warning. Informational message. (SQLCloseCursor() returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
24000 Invalid cursor state. No cursor is open on the statement handle.
HY000 General error. An error occurred for which no specific SQLSTATE applies. The error message that SQLGetDiagRec() returns in the buffer that the MessageText argument specifies, describes this error and its cause.
HY001 Memory allocation failure. Db2 ODBC is unable to allocate memory that is required execute or complete the function.
HY010 Function sequence error. SQLExecute() or SQLExecDirect() are called on the statement handle and return SQL_NEED_DATA. SQLCloseCursor() is called before data was sent for all data-at-execution parameters or columns. Invoke SQLCancel() to cancel the data-at-execution condition.
HY013 Unexpected memory handling error. Db2 ODBC is unable to access memory that is required to support execution or completion of the function.

Example

The following lines of code close the cursor on statement handle hstmt: 
rc=SQLCloseCursor(hstmt);
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc );