Call Level Interface Guide and Reference

SQLExecute - Execute a Statement

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLExecute() executes a statement, that was successfully prepared using SQLPrepare(), once or multiple times. The statement is executed using the current value of any application variables that were bound to parameter markers by SQLBindParameter(), SQLSetParam() or SQLBindFileToParam()

Syntax

SQLRETURN   SQLExecute       (SQLHSTMT          StatementHandle);  /* hstmt */

Function Arguments

Table 59. SQLExecute Arguments

Data Type Argument Use Description
SQLHSTMT StatementHandle input Statement handle. There must not be an open cursor associated with StatementHandle, see SQLFreeStmt - Free (or Reset) a Statement Handle for more information.

Data Type	Argument	Use	Description
SQLHSTMT	`StatementHandle`	input	Statement handle. There must not be an open cursor associated with StatementHandle, see SQLFreeStmt - Free (or Reset) a Statement Handle for more information.

Usage

The SQL statement string may contain parameter markers. A parameter marker is represented by a "?" character, and is used to indicate a position in the statement where an application supplied value is to be substituted when SQLExecute() is called. This value can be obtained from:

An application variable.
SQLSetParam() or SQLBindParameter() is used to bind the application storage area to the parameter marker.
A LOB value residing at the server referenced by a LOB locator. SQLBindParameter() or SQLSetParam() 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 first transferred to the application before being used as input parameter value for another SQL statement.
A file (within the applications environment) containing a LOB value.
SQLBindFileToParam() is used to bind a file to a LOB parameter marker. When SQLExecDirect() is executed, DB2 CLI will transfer the contents of the file directly to the database server.

All parameters must be bound before calling SQLExecute().

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

A statement executed by SQLExecDirect() cannot be re-executed by calling SQLExecute(); SQLPrepare() must be called first.

If the prepared SQL statement is a query, SQLExecute() will generate a cursor name, and open the cursor. If the application has used SQLSetCursorName() to associate a cursor name with the statement handle, DB2 CLI associates the application generated cursor name with the internally generated one.

To execute a query more than once, the application must close the cursor by calling SQLFreeStmt() with the SQL_CLOSE option. There must not be an open cursor on the statement handle when calling SQLExecute().

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 (using SQLBindCol() or SQLBindFileToCol). Data can also be retrieved by calling SQLGetData() for any column that was not bound.

If the SQL statement is a positioned DELETE or a positioned UPDATE, 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.

If SQLParamOptions() has been called 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. Refer to SQLMoreResults - Determine If There Are More Result Sets for more information.

Return Codes

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 has requested to input data-at-execution parameter values by calling SQLParamData() and SQLPutData().

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

The SQLSTATEs for SQLExecute() include all those for SQLExecDirect() (refer to Table 58.) except for HY009, HY090 and with the addition of the SQLSTATE in the table below.

Table 60. SQLExecute SQLSTATEs

SQLSTATE Description Explanation
HY010 Function sequence error. The specified StatementHandle was not in prepared state. SQLExecute() was called without first calling SQLPrepare().

SQLSTATE	Description	Explanation
HY010	Function sequence error.	The specified `StatementHandle` was not in prepared state. `SQLExecute()` was called without first calling `SQLPrepare()`.

Authorization

None.

CLI Sample tbread.c

(The complete sample tbread.c is also available here .)

 
/* From the CLI sample TBREAD.C */
/* ... */
 
    /* execute the statement for divisionParam = Eastern */
    printf("    Execute the prepared statement for\n");
    printf("        divisionParam = 'Eastern'\n");
    strcpy( divisionParam, "Eastern");
    sqlrc = SQLExecute( hstmt ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);

References

[ Top of Page | Previous Page | Next Page ]