SQLExecDirect function (CLI) - Execute a statement directly

Purpose

SQLExecDirect() directly executes the specified SQL statement or XQuery expression using the current values of the parameter marker variables if any parameters exist in the statement. The statement or expression can only be executed once.

For XQuery expressions, you cannot specify parameter markers in the expression itself. You can, however, use the XMLQUERY function to bind parameter markers to XQuery variables. The values of the bound parameter markers will then be passed to the XQuery expression specified in XMLQUERY for execution.

Syntax

SQLRETURN   SQLExecDirect (
               SQLHSTMT          StatementHandle,         /* hstmt */
               SQLCHAR           *StatementText,          /* szSqlStr */
               SQLINTEGER        TextLength);             /* cbSqlStr */

Function arguments

Usage

If the SQL statement text contains vendor escape clause sequences, CLI will first modify the SQL statement text to the appropriate DB2-specific format before submitting it for preparation and execution. If the application does not generate SQL statements that contain vendor escape clause sequences, then it should set the SQL_ATTR_NOSCAN statement attribute to SQL_NOSCAN_ON at the connection level so that CLI does not perform a scan for vendor escape clauses.

The SQL statement can be COMMIT or ROLLBACK if it is called using SQLExecDirect(). Doing so yields the same result as calling SQLEndTran() on the current connection handle.

The SQL statement string can contain parameter markers, however all parameters must be bound before calling SQLExecDirect().

If the SQL statement is a query, or StatementText is an XQuery expression, SQLExecDirect() will generate a cursor name, and open the cursor. If the application has used SQLSetCursorName() to associate a cursor name with the statement handle, CLI associates the application generated cursor name with the internally generated one.

If a result set is generated, SQLFetch() or SQLFetchScroll() will retrieve the next row (or rows) of data into bound variables, LOB locators, or LOB file references.

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

There must not already be an open cursor on the statement handle.

If SQLSetStmtAttr() has been called with the SQL_ATTR_PARAMSET_SIZE attribute to specify that an array of input parameter values has been bound to each parameter marker, then the application needs 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), then SQLMoreResults() should be used to advance to the next result set once processing on the current result set is complete.

Return codes

SQL_NEED_DATA is returned when the application has requested to input data-at-execute parameter values by setting the *StrLen_or_IndPtr value specified during SQLBindParameter() to SQL_DATA_AT_EXEC for one or more parameters.

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

Restrictions

None.

Example

  /* directly execute a statement - end the COMPOUND statement */
  cliRC = SQLExecDirect(hstmt, (SQLCHAR *)"SELECT * FROM ORG", SQL_NTS);