Call Level Interface Guide and Reference

SQLCloseCursor - Close Cursor and Discard Pending Results

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 31. SQLCloseCursor Arguments

Data Type Argument Use Description
SQLHSTMT StatementHandle input Statement handle

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:

the "WITH RELEASE" clause of the "CLOSE statement" in the SQL Reference
the "CLOSE CURSOR WITH RELEASE" section in the Administration Guide

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

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.

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.

CLI Sample dtlob.c

(The complete sample dtlob.c is also available here .)

 
/* From the CLI sample dtlob.c */
/* ... */
 
    /* bind the file-parameter
    /* close the cursor */
    sqlrc = SQLCloseCursor( hstmt ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc); 
    
/* ... */
    
    /* close the cursor */
    sqlrc = SQLCloseCursor( hstmt ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);

References

[ Top of Page | Previous Page | Next Page ]