Icon Transactions

While datasets can be updated without using transactions, doing so causes all updates to be completely bound to the dataset in the Elevate Web Builder application and unable to ever leave that context (apart from being saved to local storage). Using transactions allows all updates to a dataset to be logged so that the updates can then be sent to the web server application and reflected in an actual database. This is especially important when a dataset is being loaded from a table or query result set present in a database accessible from the web server application.

All transaction properties, methods, and events are contained with the TDatabase component in the WebData unit. The AutoTransactions property is True, by default, and controls whether transactions are automatically started and committed/rolled back as the datasets are updated. Please see the Updating DataSets topic to see how the automatic transactions interact with the various dataset insert, update, and delete operations. The methods for starting, committing, and rolling back transactions are the StartTransaction, Commit, and Rollback methods. Transactions in Elevate Web Builder can be nested, so the TDatabase InTransaction and TransactionLevel properties reflect whether a transaction is active and at what level, respectively. If the TransactionLevel property is -1, then no transactions are active.

Starting a Transaction
Use the TDatabase StartTransaction method to start a transaction. This will increment the current transaction level. All row inserts, updates, and deletes taking place in any owned datasets will be automatically logged as part of the current transaction.

Warning If you attempt to close a dataset using the TDataSet Close method while there are operations logged for the current transaction, an exception will be raised.

Committing a Transaction
Use the Commit method to commit the current transaction. This will:
  • Fire the BeforeCommit event handler, if one is defined. To prevent the commit from occurring, return False as the result in the event handler.


  • If the current transaction level, as reflected by the TDatabase TransactionLevel property, is 0, create a web server POST request and send it to the web server application, with the transaction data included as the POST content in JSON format. To see the JSON format used for the transactions, please see the JSON Reference topic.


  • If the current transaction level is greater than 0, then append all operations in the current transaction to the next lower transaction.


  • Decrement the current transaction level. If the transaction level is -1, then the TDatabase InTransaction property is set to False.


  • If a POST request was not sent to the web server because the current transaction being committed was nested, then immediately fire the AfterCommit event handler, if one is defined.


  • If a POST request was sent to the web server and was not successful due to an exception or the web server application returning an HTTP result code other than 200 (OK), the OnCommitError event will be fired and will include the error message. If an event handler is not defined for the OnCommitError event, then an exception will be raised with the error message. If a commit fails for any reason, then the transaction being committed is placed in a pending requests queue. This is also true for general database requests such as load requests. This queue ensures that the database requests can be retried and, when retried, are sent to the web server in the order in which they occurred. You can see if there are any pending database requests by examining the TDatabase NumPendingRequests property. If the NumPendingRequests property is greater than 0, then there are commit and/or dataset load requests that need to be retried at some point. Use the TDatabase RetryPendingRequests method to retry any pending database requests, and the TDatabase CancelPendingRequests method to cancel any pending database requests.


  • If a POST request was sent to the web server and was successful, then fire the AfterCommit event handler, if one is defined.
Commit POST Requests
The TDatabase component uses the following properties to construct the POST request to the web server when committing a transaction:
  • TDatabase BaseURL
    This property defaults to 'datasets', but can be changed to any value that you wish. Please note that it is best to use a relative URL path here so that all requests will be made relative to the URL from which the application was loaded.


  • TDatabase DatabaseName
    This property defaults to the same value as the TDatabase component's Name property, but is automatically populated for you if you use the drag-and-drop method of creating a TDatabase at design-time. This property can be changed to any value that you wish, and is simply used to identify the database via a URL parameter used for the web server request.


  • TDatabase Params
    This property is a string list (TStrings) of "name=value" pairs that represents the URL parameters for all web server requests for the database. These parameters are strictly application-specific and are not used by by the TDatabase component.
As an example, consider a typical transaction commit. In such a case, the relative URL that will be used for the web server POST request would be:

databases?method=commit&database=Production

If the application was loaded from 'http://localhost', then the complete URL used for the web server POST request would be:

http://localhost/databases?method=commit&database=Production

Now consider a transaction commit where the BaseURL property is set to 'databases/transact.php'. In such a case, the relative URL that will be used for the web server POST request would be:

databases/transact.php?method=commit&database=Production

If the application was loaded from 'http://localhost', then the complete URL used for the web server POST request would be:

http://localhost/databases/transact.php?method=commit&database=Production

Rolling Back a Transaction
Use the Rollback method to roll back the current transaction. This will:
  • Fire the BeforeRollback event handler, if one is defined. To prevent the rollback from occurring, return False as the result in the event handler.


  • Undo all operations that have taken place in the current transaction. If there are any exceptions during this process, the OnRollbackError event will be fired and will include the error message. If an event handler is not defined for the OnRollbackError event, then an exception will be raised with the error message.

    Information It is highly unlikely that an exception will ever be raised when a transaction is being rolled back, but it is possible that a catastrophic browser error could cause such an exception.

  • Decrement the current transaction level. If the transaction level is -1, then the TDatabase InTransaction property is set to False.


  • Fire the AfterRollback event handler, if one is defined.
The following example starts a transaction, deletes all rows, and then commits the transaction.:

begin
   Database.StartTransaction;
   with Products do
      begin
      while (RowCount > 0) do
         Delete;
      end;
   Database.Commit;
end;

Information If you attempt to call the TDatabase Commit or Rollback methods when there are no active transactions (InTransaction property is False), then an exception will be raised.
Image