SQLExecute() - Execute a statement

SQLExecute() executes a statement, which you successfully prepared with SQLPrepare(), once or multiple times. When you execute a statement with SQLExecute(), the current value of any application variables that are bound to parameter markers in that statement are used.

ODBC specifications for SQLExecute()

Table 1. SQLExecute() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 Yes Yes

Syntax

SQLRETURN   SQLExecute       (SQLHSTMT          hstmt);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLExecute() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle. No open cursor can be associated with the statement handle; seeSQLFreeStmt() for more information.

Usage

Use SQLExecute() to execute an SQL statement that you prepared with SQLPrepare(). You can include parameter markers in this SQL statement. Parameter markers are question mark characters (?) that you place in the SQL statement string. When you call SQLExecute() to execute a statement that contains parameter markers, each of these markers is replaced with the contents of a host variable.

You must use SQLBindParameter() to associate all parameter markers in the statement string to an application-supplied values before you call SQLExecute(). This value can be obtained from one of the following sources:
  • An application variable.

    SQLBindParameter() is used to bind the application storage area to the parameter marker.

  • A LOB value residing at the server that is referenced by a LOB locator.

    SQLBindParameter() is used to bind a LOB locator to a parameter marker. The actual value of the LOB is kept at the server and does not need to be transferred to the application before being used as the input parameter value for another SQL statement.

You must bind all parameters before you call SQLExecute().

After the application processes the results from the SQLExecute() call, it can execute the statement again with new (or the same) parameter values.

A statement that is executed by SQLExecDirect() cannot be re-executed by calling SQLExecute(); you must call SQLPrepare() before executing a statement with SQLExecute().

If the prepared SQL statement is a query, SQLExecute() generates a cursor name, and opens the cursor. If the application uses SQLSetCursorName() to associate a cursor name with the statement handle, Db2 ODBC associates the application-generated cursor name with the internally generated one.

To execute a query more than once, you must close the cursor by calling SQLFreeStmt() with thefOption argument set to SQL_CLOSE. No open cursor can exist on the statement handle when calling SQLExecute().

If a result set is generated, SQLFetch() or SQLExtendedFetch() retrieves the next row or rows of data into bound variables or LOB locators. You can also retrieve data by calling SQLGetData() for any column that was not bound.

If the SQL statement is a positioned DELETE or a positioned UPDATE, you must position the cursor that the statement references on a row at the time SQLExecute() is called, and define the cursor on a separate statement handle under the same connection handle.

If you call SQLSetStmtAttr() to specify that an array of input parameter values is bound to each parameter marker, you need to call SQLExecDirect() only once to process the entire array of input parameter values. If the executed statement returns multiple result sets (one for each set of input parameters), call SQLMoreResults() to advance to the next result set when processing on the current result set is complete.

Return codes

After you call SQLExecute(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NEED_DATA
  • SQL_NO_DATA_FOUND

SQL_NEED_DATA is returned when the application requests data-at-execution parameter values. You call SQLParamData() and SQLPutData() to supply these values to SQLExecute().

SQL_SUCCESS is returned if the SQL statement is a searched UPDATE or searched DELETE and no rows satisfy the search condition. Use SQLRowCount() to determine the number of rows in a table that were affected by an UPDATE, INSERT, DELETE, or MERGE statement executed on the table, or on a view of the table.

Diagnostics

The SQLSTATEs that SQLExecute() returns include all the SQLSTATEs that SQLExecDirect() can generate, except for HY009, HY014, and HY090, and with the addition of HY010.

The following table lists and describes the additional SQLSTATE that SQLExecute() can return.

Table 3. SQLExecute() SQLSTATEs
SQLSTATE Description Explanation
HY010 Function sequence error. SQLExecute() is called on a statement prior to SQLPrepare().

Example

Refer to SQLPrepare() for a related example.