DAL provides you with transaction support for the drivers which support it. At the moment of writing only the postgres driver supports transactions.
You start a transaction with the startTransaction function. This will instruct the driver to start a new transaction and you can execute the queries for it. When the transaction is succesfully started you'll receive true. If there was any error you receive false and the error handler has set the error message. If you try to start a transaction when one is already running you'll receive an error.
boolean startTransaction(void);
A running transaction can be committed with commitTransaction. This function will instruct the driver to commit the running transaction. If the commit fails for some reason you'll receive false and the error handler will process the error message.
boolean commitTransaction(void);
With the function abortTransaction a transaction can be aborted. The function will instruct the driver to abort the complete transaction. If for some reason the abort fails you'll receive false and the error handler will process the error message.
boolean abortTransaction(void);
It is possible to fake the transaction functions. In this way you can build a system which is transaction aware on a DBMS that doesn't support transactions. Here's how it works. First you call enableFakeTransactions. After this you can use the transaction functions just as you are used to with a system that supports transactions. However the transactions aren't sent to the dbdriver. DAL keeps administration of the transactions, so if you make a mistake with them DAL informs you about it. The only thing that doesn't happen is the executing part of the transactions on the database. With disableFakeTransactions you can disbale this behavior. Standard it disabled.
A little note of warning, when you are using transaction and you forget to either commit or abort a transaction before destroying dal the transaction get's aborted automagicly. DAL will give you a warning, which you problably only see if you are using a custom error handler, about the fact that a transaction was still running.
Sometimes a query goes nuts inside a transaction and produces an error from the backend. When this happens DAL sees it and takes some action on this. The default behaviour of DAL is to abort the transaction and block any query send to DAL until it sees a commit or abort. DAL does this because when one query inside a transaction goes nuts problably the transaction isn't valid anymore and should be aborted. Some DBMS' do the same, postgreSQL by example stay's in abort state after a failure of a query inside a transaction.
You can alter this behaviour via the configuration of DAL. Two variables are used for this: blockTransAfterError and onErrorAbort. When setting these variables to true (default setting) you get the behaviour as stated above. The onErrorAbort variable controls the action taken on the error when inside a transaction (aborting the transaction) while the blockTransAfterError specifies if all following queries should be blocked. By blocked i mean they don't get send to the backend.
Below you'll find a table which specifies DAL behaviour according to the transaction error settings
| blockTransAfterError | onErrorAbort | Result |
|---|---|---|
| 0 | 0 | When an error occurs DAL takes no action and leaves it up to you. |
| 1 | 0 | When an error occurs DAL refuses all queries after the error until a commit or abort is received. |
| 0 | 1 | When an error occurs DAL aborts the running transaction and executes all queries after the error OUTSIDE the borders of a transaction. |
| 1 | 1 | When an error occurs DAL aborts the running transaction and refuses all queries until a commit or abort is received. |