SQLExecute - Execute a statement

SQLExecute() runs a statement that was successfully prepared using SQLPrepare() once or multiple times. The statement is processed with the current values of any application variables that were bound to parameter markers by SQLBindParam().

Syntax

SQLRETURN SQLExecute (SQLHSTMT     hstmt);

Function arguments

Table 1. SQLExecute arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle. There must not be an open cursor associated with hstmt, see SQLFreeStmt - Free (or reset) a statement handle for more information.

Usage

The SQL statement string might contain parameter markers. A parameter marker is represented by a "?" character, and indicates a position in the statement where the value of an application variable is to be substituted, when SQLExecute() is called. SQLBindParam() is used to bind (or associate) an application variable to each parameter marker, and to indicate if any data conversion should be performed at the time the data is transferred. All parameters must be bound before calling SQLExecute().

As soon as the application has processed the results from the SQLExecute() call, it can process the statement again with new (or the same) values in the application variables.

A statement processed by SQLExecDirect() cannot be reprocessed by calling SQLExecute(); SQLPrepare() must be called first.

If the prepared SQL statement is a SELECT, SQLExecute() generates a cursor name, and opens the cursor. If the application has used SQLSetCursorName() to associate a cursor name with the statement handle, DB2® for i CLI associates the application generated cursor name with the internally generated cursor name.

To process a SELECT statement more than once, the application must close the cursor by calling call SQLFreeStmt() with the SQL_CLOSE option. There must not be an open cursor on the statement handle when calling SQLExecute().

To retrieve a row from the result set generated by a SELECT statement, call SQLFetch() after SQLExecute() returns successfully.

If the SQL statement is a positioned DELETE or a positioned UPDATE statement, the cursor referenced by the statement must be positioned on a row at the time SQLExecute() is called, and must be defined on a separate statement handle under the same connection handle.

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NO_DATA_FOUND

SQL_NO_DATA_FOUND is returned if the SQL statement is a Searched UPDATE or Searched DELETE and no rows satisfy the search condition.

Diagnostics

The SQLSTATEs for SQLExecute() include all those for SQLExecDirect() (see Table 2) except for HY009, and with the addition of the SQLSTATEs in the following table.

Table 2. SQLExecute SQLSTATEs
SQLSTATE	Description	Explanation
HY009	Statement option is not valid	Attributes associated with the statement being executed are not valid.
HY010	Function sequence error	The specified hstmt is not in prepared state. `SQLExecute()` is called without first calling `SQLPrepare`.
HY021	Internal descriptor that is not valid	The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.
Note: There are many other SQLSTATE values that can be generated by the Database Management System (DBMS), on processing of the statement.

Example

Refer to the example in SQLPrepare - Prepare a statement