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.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLExecDirectW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 CLI.

Syntax

SQLRETURN SQLExecDirect (SQLHSTMT      hstmt,
                         SQLCHAR       *szSqlStr,
                         SQLINTEGER    cbSqlStr);

Function arguments

Table 1. SQLExecDirect 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

Table 2. SQLExecDirect SQLSTATEs
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.