Unit
IB_Components

Declaration
TIB_Transaction = class(TIB_Component)

Description
This component is designed to encapsulate all of the InterBase API's transaction functionality. It provides all properties, methods and events necessary to have full control over transaction capabilities.

Here are some hints for working with IB Objects transactions:

With IBO there are three aspects of transaction that need to be considered. There is the concept of a physical transaction, a logical transaction and an explicit transaction. Each has its own behavior and in many cases there is overlap between the two. Their behaviors change depending on other factors, like isolation, as well.

Physical Transactions
IBO manages when a physical transaction is started automatically so it is not necessary to explicitely start the physical transaction. The physical transaction is what needs to be kept as short as possible so that the server isn't prevented from doing its garbage collection. It is also where the settings take effect that provide the isolation, lockwait, recversion, etc. This forms the foundation for the logical and explicit transactions.

A long duration physical transaction can eventually lead to severe performance degredation and an eventual server crash if it is left for over a day or so in a moderately active database environment. In a high volume database it could have signs of degredation within a day.

A physical transaction is ended when Commit[Retaining], Rollback[Retaining], Refresh() or Close is called. These are the methods to end a logical unit of work and to end an explicit transaction as well.

IBO has automated features that close the physical transaction for you. This is called OAT (Oldest Active Transaction) Management. As long as you avoid or carefully manage the cases where the OAT management is suspended you will not have any problems with long physical transactions in your applications.

Here are the cases that prevent IBO from automatically advancing the OAT:

1) When you are not using cached updates and you post any change to the database and AutoCommit is false. This flags the transaction as active and the OAT stuff is suspended while a transaction's state is tsActive. You must call Commit[Retaining], Rollback[Retaining], SavePoint or Refresh() to resolve the active state of the transaction and allow the OAT stuff to resume.
2) When you are using PessimisticLocking and you have a record in dssEdit state. The transaction must be held open for the lock to have duration. As soon as the record is posted or cancelled the former rules apply and OAT behavior resumes.
3) When you use the isolation of tiConcurrency. This is because you have told the server that you want a snapshot view of the database. It would corrupt this if physical transactions were to come and go in order to advance the OAT. Each time a new transaction is started with tiConcurrency you get a new view of the database because other user's committed changes become visible.
4) When you have a SELECT statement that will return thousands of rows and you open it but don't fetch all the records. This forces a cursor to be held open on the server because all the records have not been fetched. Actually this situation would eventually be overcome by background fetching that begins taking place in order to free up the cursor. If you set the CommitAction to caInvalidateCursor then it will just get refreshed for you and there won't be a problem. It is generally unadvisable to leave large datasets open where all records are not fetched in.

Be sure to get familiar with the TimeOutProps settings because it is possible there to ensure that the OAT advancement issues can be dealt with.


Logical Transactions
A logical transaction is what is considered the unit of work that the user is performing. IBO will automatically keep track of your logical transaction for you. Use the TransactionIsActive property to determine if you are in an implicit logical transaction.

If AutoCommit is true then this will be limited to the duration of time that a dataset is in an edit state. As soon as it is posted it is auto-committed and the implicit logical transaction is ended.

If AutoCommit is false then it will start from the very time that a dataset is put into an edit state and will remain once the change is posted until the transaction is ended by calling one of the methods to end it. If a dataset is cancelled and no other changes had been posted then the implicit logical transaction will be ended automatically.


Explicit Transactions
Calling the StartTransaction method initiates an explicit transaction. It will remain until one of the methods to end the unit of work is called. SavePoint does not end an explicit transaction. The InTransaction property is used exclusively to tell if you are in an explicit transaction or not. It does not reflect the status of the implicit logical transaction or the underlying physical transaction.

If AutoCommit is set to true then its behavior is suspended during an explicit transaction and all changes posted to the server remain in the transaction rather than being committed immediatly.

NOTE: Setting AutoCommit to true is a way that allows you to not have to worry about taking explicit control of logical transactions. It makes it so that when you post a change to a dataset, execute a DML statement, etc. (which activates the transaction) will generate an immediate SavePoint. Thus, there really isn't a logical transaction to worry about since everything becomes committed on the server the moment it is executed and the transaction is activated.

If AutoCommit is false then you need to call SavePoint, CommitRetaining, Commit, RollbackRetaining, Rollback or Refresh() so that a unit of work is processed. These methods all end the logical transaction whether it is implicite or explicite.

Introduced Public Properties

ActivateCount	This is the number of times in the transaction that Activate has been called.
AnnounceFocus	Determines whether or not this transaction should announce that it has recieved focus.
AutoCommit	This property is an IBO behavioral property and does not map to any specific feature of the InterBase API.
CachedUpdatePendingCount	Number of datasets associated to this transaction that need to apply CachedUpdates.
CanPause	Find out if the transaction can be paused.
ConfirmCancelPrompt	This message is here for convenience in making generic base class forms provide customizable feedback to the user.
ConfirmClosePrompt	This message is used in the dialog that accompanies the CloseWithConfirm and EndWithConfirm methods.
ConnectionCount	Number of connections associted with this transaction.
ConnectionIndex	Index reference of a connection that may be associated to the transaction.
Connections	Indexed reference to the connections associated with this transaction.
DatasetCount	Number of datasets associated with this transaction.
Datasets	Indexed reference to the datasets associated with this transaction.
IB_Connection	This property determins the primary connection this transaction will be..
IB_Connection1	This property determins the first additional connection this transaction will be started on.
IB_Connection2	This property determins the second additional connection this transaction will be started on.
InTransaction	This property tells whether an explicite logical transaction is in progress.
Isolation	Determines the isolation level of the transaction.
IsPaused	Is the transaction currently paused?
IsPauseDisabled	Has Pause been disabled?
IsPausePending	Is the transaction currently in the process of being paused?
LastStarted	The datetime when the transaction was last started.
LastStoppped	The datetime when the transaction was last stopped (committed or rolledback).
LockWait	When there is a conflict or deadlock condition this determines if an error should be immediatly returned or if it should wait until the uncommitted changes are resolved.
PdbHandles	Indexed reference to the pointers to the connections associated with this transaction.
PostPendingCount	Number of datasets associated to this transaction that NeedToPost.
PtrHandle	Pointer to the native API transaction handle.
ReadOnly	Makes this transaction ReadOnly at the API level.
RecVersion	This property only takes affect when Isolation is set to tiCommitted.
ServerAutoCommit	Use the native AutoCommit mode of InterBase.
Started	Returns whether or not a transaction has been physically started.
StartedDateTime	This is the datetime value of when this transaction was started.
StatementCount	Number of statements associated with this transaction.
Statements	Indexed reference to the statements associated with this transaction.
TimeActive	Reports the amount of time the transaction has been active, that is, the difference between now and the LastStarted time IF the transaction is currently active.
TimeoutProps
TransactionIsActive	This property tells whether or not there is a change posted or pending to post for the transaction.
TransactionLinkCount	Number of transactionLink components that reference this transaction.
TransactionLinks	Array of TransactionLink objects.
TransactionState	Current state of the transaction.
trHandle	Native API transaction handle.

Introduced Public Methods

Activate	Some statements may process an alteration to data or metadata that IBO is not smart enough to detect.
AddConnection	This method adds a new connection to use for a multi-database transaction.
AddDMLCacheItem	This method is used to add a DML cache item to the list so that when the transaction is committed it will announce these changes to other transactions in the same connection that have an isolation of tiCommitted.
ApplyUpdates	This method is used in order to apply updates for selected datasets in a specified order.
BeginCachedUpdatePendingNotify	This method will increment that flag that determines if event notifications should be sent to the OnCachedUpdatePendingChanged events of the transaction links.
BeginPostPendingNotify	This method will increment that flag that determines if event notifications should be sent to the OnPostPendingChanged events of the transaction links.
CancelAll	All datasets that are associated to this transaction will be cancelled.
CancelUpdates	This method is used in order to cancel updates for selected datasets in a specified order.
ChangeIsolation	This method permits the transaction Isolation property to be changed even while the transaction is active.
CheckOAT	This method is used in order to control the mechanisms to keep the OAT advancing.
Close	This method causes a transaction to end and depending on the value of AutoCommit the transaction is ended with a Commit or Rollback.
CloseWithConfirm	This method is great for a UI when a physical transaction needs to be resolved and user input is desired.
Commit	This method causes a commit and the current transaction is totally ended, both the logical and physical aspects of the transaction.
CommitRetaining	This method causes a post of all datasets in an edit state and then makes all posted changes in the transaction committed on the server.
Create
Destroy
DisablePause	Call this to disable pause processing - usually to prevent a long running report or procedure being interrupted by a call to Pause.
EnablePause	See DisablePause for details.
EndCachedUpdatePendingNotify	This method will deccrement that flag that determines if event notifications should be sent to the OnCachedUpdatePendingChanged events of the transaction links.
EndPostPendingNotify	This method will deccrement that flag that determines if event notifications should be sent to the OnPostPendingChanged events of the transaction links.
EndWithConfirm	This method is great for a UI when a transaction needs to be resolved and the user input is desired.
Pause	Call Pause( true ) to commit a transaction without notifying any datasets that the transaction has stopped.
PostAll	All datasets that are associated to this transaction will be posted.
Refresh	This method causes a transaction-wide refresh of all buffered datasets.
RemoveConnection	This method removes a connection from the list of connections to span.
Resume	See description for Pause function.
Rollback	This method causes a rollback and the current transaction to be ended, both the physical and logical aspects.
RollbackRetaining	This method performs a rollback but the datasets are not all closed.
SavePoint	This method is the saem as CommitRetaining except that it does not require the datasets of the transaction to all be posted first.
SetFocus	This method causes the transaction to be the focused transaction for the session.
StartTransaction	This method starts what I call an explicite logical transaction.
UpdateStatus	This method announces the event that all transaction links should update their status.

Introduced Public Events

AfterCommit	General transaction event notification.
AfterCommitRetaining	General transaction event notification.
AfterEnd	General transaction event notification.
AfterRollback	General transaction event notification.
AfterRollbackRetaining	General transaction event notification.
AfterStart	General transaction event notification.
BeforeCommit	General transaction event notification.
BeforeCommitRetaining	General transaction event notification.
BeforeEnd	General transaction event notification.
BeforeRollback	General transaction event notification.
BeforeRollbackRetaining	General transaction event notification.
BeforeStart	General transaction event notification.
OnCustomizeTPB	This event allows direct alteration of the TPB (Transaction Parameter Buffer) that is passed to the API call in order to start a transaction.
OnGainFocus	General transaction event notification.
OnGetCanPause	Called to allow developer override of whether a transaction can be paused.
OnLoseFocus	General transaction event notification.
OnPauseChanged	Notification of when the transaction is paused or resumed.
OnSessionTimer	By default the session produces a continual series of timer notifications in order to serve as the backbone to timing related issues in IBO.
OnTimeoutPromptUser	Use this event to hook in your customized behavior to resolve a transaction that needs the user's cooperation in order to end it.