====== IBPP::Transaction ====== The IBPP::Transaction Interface represents a transaction (!). Along with IBPP::[[Database]] and IBPP::[[Statement]], it is the core of IBPP. You need at least one instance of each to do anything against the data stored in a database. ===== Definition ===== See the file ibpp.h for an up-to-date definition of the interface. Lookup the ITransaction class. Like the other building blocks of IBPP, the actual interface class is a pure virtual class (here named IBPP::ITransaction). This is the closest thing in C++ to a pure interface concept. The real working object 'behind' (IBPP internals) is derived from this 'contract' class. As long as the signature of this ITransaction class does not change, your code is binary compatible with IBPP, even if internal details of the real work-class behind have changed. As with other IBPP building blocks, you cannot instantiate this class by yourself (due to its pure virtual methods). You also can't derive your own class from this one, due to the protected constructor and destructor. You have to get an instance from IBPP through the corresponding Factory function call. ===== TransactionFactory ===== Transaction TransactionFactory(Database db, TAM am = amWrite, TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) The TransactionFactory is used to build and get access to a Transaction object. Thanks to its default arguments, you can really easily setup the most common transaction models of Firebird : a write transaction, in complete isolation mode (concurrency), waiting on lock resolutions, and without any other special attributes. ==== TAM : Transaction Access Modes ==== The TAM enumeration offers amWrite and amRead constants to define the type of transaction (for writing/reading or for reading). ==== TIL : Transaction Isolation Level ==== The TIL enumeration offers ilConcurrency, ilReadDirty, ilReadCommitted, ilConsistency constants to define the type of transaction isolation level. ==== TLR : Transaction Lock Resolution ==== The TLR enumeration offers lrWait and lrNoWait constants to define the type of transaction lock resolution to apply. ==== TFF : Transaction Factory Flags ==== The TFF enumeration offers tfIgnoreLimbo, tfAutoCommit, tfNoAutoUndo constants to apply advanced transaction configuration options to the transaction object. This is an advanced topic and should make sure to read related documentation material of Firebird before using these techniques (which are most often absolutely not required, nor generally recommended). ===== Multi-databases transactions ===== This is often named 'distributed two-phases commit' transactions. Though often tied to a single [[database]] attachment, a transaction can really span two or more [[database]] attachments. Queries and updates can be issued against all those databases, separately, and then the work committed once for all the databases, in an all-or-nothing way accross all the databases. To support this behaviour, IBPP offers the AttachDatabase method, to add one or multiple databases to an existing transaction object. ===== Methods ===== ==== void Start() ==== Starts the transaction, as defined by the parameters used in the TransactionFactory call. ==== bool Started() ==== Returns true if the Transaction object is currently started (and not yet rollbacked or committed). ==== void Commit ==== Commit the started transaction. Its state becomes Started() == false. ==== void CommitRetain ==== Commit the started transaction, retaining it. This means the work up here is committed but the transaction context is still live (Started() == true). ==== void Rollback() ==== Rollbacks the transaction, undoing its work. Its state becomes Started() == false. ==== void AddReservation(Database db, const std::string& table, TTR tr) ==== Permits to add a table reservation request to a transaction object, before calling Start(). When reserving a table, you need to specify its name and a table reservation mode. See the TTR enumeration below. === TTR : Transaction Table Reservation === The TTR enumeration offers trSharedWrite, trSharedRead, trProtectedWrite, trProtectedRead constants to define the type of table reservation to add to the transaction object. This is an advanced topic and should make sure to read related documentation material of Firebird before using these techniques (which are most often absolutely not required, nor generally recommended). ==== void AttachDatabase(Database db, TAM am = amWrite, TIL il = ilConcurrency, TLR lr = lrWait, TFF flags = TFF(0)) = 0) ==== Used to 'attach' an additional existing and connected database object to this transaction object. Setting up multi-databases transactions is that simple. ==== void DetachDatabase(Database db) ==== Used to detach a database from a multi-databases transaction. You can only do so when the transaction is not started.