Core subroutine
Request a commit or rollback for all current transactions.
call EDSTransact(HENV_IV, HDBC_IV, TYPE_IV)
•HENV_IV An input integer value indicating the environment handle associated with your application.
•HDBC_IV An input integer value indicating the database connection handle associated with the transaction.
•TYPE_IV An input integer value indicating EDS_COMMIT or EDS_ROLLBACK.
Description
If HDBC_IV is EDS_NULL_HDBC, and HENV_IV is the valid environment handle, then the Driver Manager will attempt to commit or roll back transactions on all connection handles that are in a connected state. The Driver Manager calls EDSTransact in the driver associated with each connection handle. The Driver Manager will return EDS_SUCCESS only if it receives EDS_SUCCESS for each connection handle. If the Driver Manager receives EDS_ERROR on one or more connection handles, it will return EDS_ERROR to your application. To determine which connection(s) failed during the commit or rollback operation, your application can call EDSError for each connection handle. Note that the Driver Manager does not simulate a global transaction across all connection handles, and therefore does not guarantee two-phase commit protocols are being used.
If HDBC_IV is a valid connection handle, HENV_IV is ignored and the Driver Manager calls EDSTransact in the driver for the connection handle.
If HDBC_IV is EDS_NULL_HDBC and HENV_IV is EDS_NULL_HENV, EDSTransact return EDS_INVALID_HANDLE.
If TYPE_IV is EDS_COMMIT, EDSTransact issues a commit request for all active operations on any statement handle associated with an affected connection handle. If TYPE_IV is EDS_ROLLBACK, EDSTransact issues a rollback request for all active operations on any statement handle associated with an affected connection handle. If no transactions are active, EDSTransact returns EDS_SUCCESS with no effect on any data sources.
If the driver is in manual commit mode (by calling EDSSetConnectOption with the EDS_AUTOCOMMIT option set to zero), a new transaction is implicitly started when the driver connects to the data source or after any commit or rollback transaction.
To determine how transaction operations affect cursors, your application can call EDSGetInfo with the EDS_CURSOR_ROLLBACK_BEHAVIOR and EDS_CURSOR_COMMIT_BEHAVIOR options.
If the EDS_CURSOR_ROLLBACK_BEHAVIOR or EDS_CURSOR_COMMIT_BEHAVIOR value equals zero, EDSTransact closes and deletes all open cursors associated with the connection handle and discards all pending results. EDSTransact leaves statement handles in an allocated state; your application can reuse them for subsequent SQL requests or can call EDSFreeStmt to deallocate them.
If the EDS_CURSOR_ROLLBACK_BEHAVIOR or EDS_CURSOR_COMMIT_BEHAVIOR value equals one, EDSTransact closes all open cursors associated with the connection handle. EDSTransact leaves statement handles in a prepared state; you can use the statement handles to call EDSExecute without first calling EDSPrepare.
If the EDS_CURSOR_ROLLBACK_BEHAVIOR or EDS_CURSOR_COMMIT_BEHAVIOR value equals two, EDSTransact does not affect open cursors associated with the connection handle. Cursors remain at the row they pointed to prior to the call to EDSTransact.
For drivers and data sources that support transactions, calling EDSTransact with either EDS_COMMIT or EDS_ROLLBACK when no transaction is active will return EDS_SUCCESS (indicating that there is no work to be committed or rolled back) and have no effect on the data source.
Drivers or data sources that do not support transactions (EDSGetInfo OPTION_IV parameter EDS_TXN_CAPABLE is 0) are, effectively, always in auto-commit mode. Therefore, calling EDSTransact with EDS_COMMIT will return EDS_SUCCESS. However, calling EDSTransact with EDS_ROLLBACK will result in SQLSTATE S1C00 (driver not capable), indicating that a rollback can never be performed.
EDSTransact can also request that a commit or rollback operation be performed for all connections associated with the environment handle.
Return Value
EDSTransact returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSTransact returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSTransact.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
08003 |
Connection not open |
The connection handle was not in a connected state. |
08007 |
Connection failure during transaction |
The connection associated with the connection handle failed during the execution of the function and it cannot be determined whether the requested COMMIT or ROLLBACK occurred before the failure. |
IM001 |
Driver does not support this function |
The driver associated with the connection handle does not support the function. |
S1000 |
General error |
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate the memory required to support execution or completion of the function. |
S1010 |
Function sequence error |
An asynchronously executing function was called for a statement handle associated with the connection handle and was still executing when EDSTransact was called. |
S1012 |
Invalid transaction operation code |
The value specified for the argument TYPE_IV was neither EDS_COMMIT nor EDS_ROLLBACK. |
S1C00 |
Driver not capable |
The driver or data source does not support the ROLLBACK operation. |
See Also
EDSFreeStmt closes a cursor.
