DB2 Version 9.7 for Linux, UNIX, and Windows

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

Purpose

Specification:

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);  /* 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 on 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);