SQLFreeStmt - Free (or reset) a statement handle

 

SQLFreeStmt() ends processing on the statement that is referenced by the statement handle.

You can use this function to complete the following tasks:

• Close a cursor.

• Reset parameters.

• Unbind columns from variables.

• Drop the statement handle and free the DB2^® UDB CLI resources associated with the statement handle.

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

 

Syntax

SQLRETURN SQLFreeStmt (SQLHSTMT       hstmt,
                       SQLSMALLINT    fOption);

 

Function arguments

Table 1. SQLFreeStmt arguments

Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle
SQLSMALLINT	fOption	Input	Option specifying the manner of freeing the statement handle. The option must have one of the following values: SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS

 

Usage

SQLFreeStmt() can be called with the following options:

• SQL_CLOSE

  The cursor (if any) associated with the statement handle (hstmt) is closed and all pending results are discarded. The application can reopen the cursor by calling SQLExecute() with the same or different values in the application variables (if any) that are bound to hstmt. The cursor name is retained until the statement handle is dropped or the next successful SQLSetCursorName() call. If no cursor has been associated with the statement handle, this option has no effect (no warning or error is generated).

• SQL_DROP

  DB2 UDB CLI resources associated with the input statement handle are freed, and the handle is invalidated. The open cursor, if any, is closed and all pending results are discarded.

• SQL_UNBIND

  All the columns bound by previous SQLBindCol() calls on this statement handle are released (the association between application variables or file references and result set columns is broken).

• SQL_RESET_PARAMS

  All the parameters set by previous SQLBindParam() calls on this statement handle are released. The association between application variables or file references and parameter markers in the SQL statement of the statement handle is broken.

To reuse a statement handle to run a different statement and if the previous statement:

• Was a SELECT, close the cursor.

• Used a different number or type of parameters, the parameters must be reset.

• Used a different number or type of column bindings, the columns must be unbound.

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

 

Return codes

• SQL_SUCCESS

• SQL_SUCCESS_WITH_INFO

• SQL_ERROR

• SQL_IN_HANDLE

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

 

Diagnostics

Table 2. SQLFreeStmt SQLSTATEs

SQLSTATE	Description	Explanation
40003 *	Statement completion unknown	The communication link between the CLI and the data source fails before the function completes processing.
58004	System error	Unrecoverable system error.
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	The value specified for the argument fOption is not SQL_CLOSE, SQL_DROP, SQL_UNBIND, or SQL_RESET_PARAMS.
HY021	Internal descriptor that is not valid	The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.

 

Example

Refer to the example in SQLFetch - Fetch next row.

 

References

• SQLAllocStmt - Allocate a statement handle

• SQLBindCol - Bind a column to an application variable

• SQLFetch - Fetch next row

• SQLFreeConnect - Free connection handle

• SQLSetParam - Set parameter

 

Parent topic:

DB2 UDB CLI functions