A statement handle (HSTMT) can be in one of five states:

Prior to allocating a statement, your application must establish a successful connection.

The following table lists the next valid state for each core command when called from a given state. Notes are listed on the following page. InvHndl indicates an INVALID_HANDLE return code.

1Allocation functions should never be called for already-allocated handles, as the driver will lose any information associated with the handle and the handle will return to the allocated state (S1).

2Occurs when the executed statement created a result set. For example, a SELECT statement may create a result set.

3Occurs when the executed statement did not create a result set. For example, a CREATE TABLE statement does not create a result set.

4Transition for all HSTMTS allocated with EDSAllocStmt for the same HDBC.

5EDSDisconnect returns a SQLSTATE of 25000 (Invalid transaction state) if there is an incomplete transaction on an HSTMT associated with the HDBC.

6The HSTMT indicated by the cursor in “UPDATE WHERE CURRENT OF cursor” or “DELETE WHERE CURRENT OF cursor” must be in state S4, or the EDSExecute or EDSExecDirect function returns EDS_ERROR with an SQLSTATE of 24000 (Invalid cursor state). Following the positioned UPDATE or DELETE, the positioned HSTMT is left in state S4.

7If the SQL statement associated with the HSTMT contains parameters, and one or more of the parameters have not been set, the driver returns EDS_ERROR with a SQLSTATE of 07001 (Wrong number of parameters).

8This transition is legal only if there are no open cursors on the HSTMT. Any SELECT statement executed on the HSTMT—or any function that returns a result set on an HSTMT, such as EDSColumns—must be followed by a call to EDSFreeStmt with the EDS_CLOSE option specified. Otherwise, a driver returns EDS_ERROR with an SQLSTATE of 24000 (Invalid cursor state).

9Transition for EDS_NO_DATA_FOUND.

10Transition for an executed statement that was not a SELECT statement. EDSFetch returns EDS_ERROR with an SQLSTATE of 24000 (Invalid cursor state).

11Transition for Option equal to EDS_CLOSE.

12Perform the transition if the query was not executed with EDSExecute. (In other words, the query was executed by EDSExecDirect or a catalog function.)

13Perform the transition if the query was executed with EDSExecute.

14Transition for Option equal to EDS_DROP.

15Transition for Option equal to EDS_UNBIND or EDS_RESET_PARAMS.

16Case where EDSSetCursorName has not been called.

17Case where EDSSetCursorName has been called.

18The HSTMT indicated by cursor in WHERE CURRENT OF cursor must be in state S3 or S4 for EDSPrepare. After EDSPrepare the HSTMT remains in the same state.

19Transition where EDSPrepare is called for an HSTMT that is already in the S2 state and EDSPrepare fails for a reason other than validation (in other words, it returns an SQLSTATE other than IM001, 24000, S1009, or S1090).

20Number of rows returned for INSERT, UPDATE, and DELETE statements if available; otherwise, a driver returns -1 for row count indicating number of rows not available or EDSRowCount is undefined for the SQL statement.

21Resetting parameters has no effect on the already-executed statement.

22Transitions for data sources that can retain cursor state across transaction boundaries. For more information, refer to EDSGetInfo options EDS_COMMIT_CURSOR_BEHAVIOR and EDS_ROLLBACK_CURSOR_BEHAVIOR.

 

The following table lists the next valid state for each Extended command when called from a given state. Notes are listed on the following page. InvHndl indicates an INVALID_HANDLE return code.

 

1This transition is legal only if there are no open cursors on the HSTMT. Any SELECT statement executed on the HSTMT—or any function that returns a result set on an HSTMT, such as EDSColumns—must be followed by a call to EDSFreeStmt with the EDS_CLOSE option specified. Otherwise, a driver returns EDS_ERROR with an SQLSTATE of 24000 (Invalid cursor state).

2Transition for EDS_NO_DATA_FOUND.

3Occurs when the executed statement did not create a result set. For example, a CREATE TABLE statement does not create a result set.

4After calling EDSMoreResults, the state transition will depend on the state associated with the next EDS statement in the batch. If EDSMoreResults returns EDS_NO_DATA_FOUND, the state transition will be to S1 or S2 depending on whether EDSExecDirect or EDSExecute, respectively, were used to execute the EDS statement(s).

5The statement is fully in state S3 only after EDSParamData returns EDS_SUCCESS. In between the time that EDSExecute or EDSExecDirect returns EDS_NEED_DATA and EDSParamData returns EDS_SUCCESS, EDSParamData and EDSPutData may be called multiple times. However, it is valid to call EDSParamData only in one of the following sequences: after a call to EDSExecute or EDSExecDirect that returns EDS_NEED_DATA, or following a call to EDSPutData. Otherwise EDSParamData returns EDS_ERROR with an SQLSTATE of S1010 (Function sequence error). If EDSParamData is called after it returns EDS_SUCCESS, the driver returns EDS_ERROR with an SQLSTATE of S1DE0 (No data at execution values pending).

6The statement is fully in state S3 only after EDSParamData returns EDS_SUCCESS. In between the time that EDSExecute or EDSExecDirect returns EDS_NEED_DATA and EDSParamData returns EDS_SUCCESS, EDSParamData and EDSPutData may be called multiple times. However, it is valid to call EDSPutData only in one of the following sequences: after a call to EDSParamData that returns EDS_NEED_DATA, or following a successful call to EDSPutData. Otherwise, EDSPutData returns EDS_ERROR with a SQLSTATE of S1DE0 (No data at execution values pending).