OnCustomizeTPB Event

Applies to
TIB_Transaction

Declaration
TIB_CustomizeTPBEvent = Procedure(Sender: TIB_Transaction; AConnection: TIB_Connection; var BufInd: longint; var Buffer: pchar ) of object;

Description
This event allows direct alteration of the TPB (Transaction Parameter Buffer) that is passed to the API call in order to start a transaction.

In the case of a transaction that spans more than one database it is possible to customize the TPB that is associated to each of the databases as well as the base TPB that will by default be a part of the TPB for all of the databases.

AConnection will provide the reference to the IB_Connection for which the TPB will be applied. If it is nil then customizations will be applied to all of the connections.

Here is a thread I made that may shed some additional light on the subject:

First of all, SET TRANSACTION RESERVING .. is an embedded SQL statement that is processed by GPRE into the appropriate API call with the transaction parameter block configured with the specified settings.

So, what we will need to do is configure the TPB (transaction parameter block) to use the functionality that the RESERVING clause gives by adding on the TPB items and information that will deliver this behavior.

Using the TIB_Transaction.OnCustomizeTPB event it is possible to override and clarify what is being sent to the API in the TPB. In your case you will need to add a byte code telling that you want to reserve some resources (isc_tpb_lock_write) and then a list of those resources ( a length indicator and table name ) and and then an item telling what protection level to assign (isc_tpb_protected). The API guide tells how to set up the TPB and explains all of the different options available. You may need to repeat this for each table that you want to reserve.

If your transaction is across multiple connections then you will have two flavors of OnCustomizeTPB triggered. In the first one that triggers you will get a nil for the Connection which means that any alterations (additions) to the TPB will be applied to all of the TPB's of the TEB array. (A TPB is generated for each connection involved in the transaction.) Then, for each connection, another invocation of the OnCustomizeTPB is triggered so that database specific TPB alterations can be put in place.

When the TPB is being interpreted the last setting wins. Thus, it is posible to override any previous TPB items and force the transaction to take on a certain behavior specific to a given connection just by adding what you want at the end of the TPB specific to the database.

I have provided a helper method to assist in cramming information into a TPB. Please look in the source at the API_Start method and use the same approach when constructing the TPB in the event code that you write. It makes things much cleaner and easier.