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
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_NEED_DATA
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
SQLExecute()
include
all those for SQLExecDirect()
(see Table 2) except for HY009,
and with the addition of the SQLSTATEs in the following table.
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