SQLExecDirect - Execute a statement directly
SQLExecDirect()
directly runs the specified
SQL statement. The statement can only be processed once. Also, the
connected database server must be able to prepare the statement.
Syntax
SQLRETURN SQLExecDirect (SQLHSTMT hstmt,
SQLCHAR *szSqlStr,
SQLINTEGER cbSqlStr);
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. |
SQLCHAR * | szSqlStr | Input | SQL statement string. The connected database server must be able to prepare the statement. |
SQLINTEGER | cbSqlStr | Input | Length of contents of szSqlStr argument. The length must be set to either the exact length of the statement, or if the statement is null-terminated, set to SQL_NTS. |
Usage
The SQL statement cannot be a COMMIT
or ROLLBACK. Instead, SQLTransact()
must be called
to issue COMMIT or ROLLBACK. For more information about supported
SQL statements refer to Table 1.
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 SQLExecDirect()
is called. SQLBindParam()
binds
(or associates) an application variable to each parameter marker,
to indicate if any data conversion should be performed at the time
the data is transferred. All parameters must be bound before calling SQLExecDirect()
.
If the SQL statement is a SELECT, SQLExecDirect()
generates
a cursor name, and open 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 one.
To
retrieve a row from the result set generated by a SELECT statement,
call SQLFetch()
after SQLExecDirect()
returns
successfully.
If the SQL statement is a Positioned DELETE or a Positioned UPDATE, the cursor referenced by the statement must be positioned on a row. Additionally the SQL statement must be defined on a separate statement handle under the same connection handle.
There must not be an open cursor on the statement 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
SQLSTATE | Description | Explanation |
---|---|---|
HY001 | Memory allocation failure | The driver is unable to allocate memory required to support the processing or completion of the function. |
HY009 | Argument value | The argument szSqlStr is a
null pointer. The argument cbSqlStr is less than 1, but not equal to SQL_NTS. |
HY010 | Function sequence error | Either no connection or there is an open cursor for this statement handle. |
HY013 * | Memory management problem | The driver is unable to access memory required to support the processing or completion of the function. |
HY021 | Internal descriptor | 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 SQLFetch - Fetch next row.