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® for i 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 for i 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, you must 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

Parent topic: DB2 for i CLI functions