SQLFreeStmt--Free (or reset) a statement handle

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLFreeStmt() ends processing on the statement referenced by the statement handle. Use this function to:

SQLFreeStmt() is called after executing an SQL statement and processing the results.

Syntax 

SQLRETURN   SQLFreeStmt      (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLUSMALLINT      Option);           /* fOption */

Function arguments

Table 62. SQLFreeStmt arguments

Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.
SQLUSMALLINT Option input Option that specifies the manner of freeing the statement handle. The option must have one of the following values: SQL_DROP or SQL_RESET_PARAMS.

Usage

SQLFreeStmt() can be called with the following options:

SQL_DROP
DB2 CLI resources associated with the input statement handle are freed, and the handle is invalidated. All pending results are discarded.

This option is replaced with a call to SQLFreeHandle() with the HandleType set to SQL_HANDLE_STMT.

Recommendation: Although this version of DB2 CLI continues to support this option, use SQLFreeHandle() in your DB2 CLI programs so that they conform to the latest standards.

SQL_RESET_PARAMS
Releases all parameter buffers set by SQLBindParameter() for the StatementHandle.

Alternatively you can drop the statement handle and allocate a new one.

Return codes

SQL_SUCCESS_WITH_INFO is not returned if Option is set to SQL_DROP, because there would be no statement handle to use when SQLError() is called.

Diagnostics

Table 63. SQLFreeStmt SQLSTATEs

SQLSTATE Description Explanation
40003 08S01 Communication link failure. The communication link between the application and data source failed before the function completed.
58004 Unexpected system failure. Unrecoverable system error.
HY001 Memory allocation failure. DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY092 Option type out of range. The value specified for the argument Option is not SQL_DROP or SQL_RESET_PARAMS.

Restrictions

None.

Related reference