While datasets can be updated without using transactions, doing so causes all updates to be merged into the in-memory rows in the dataset in the client or server application and unable to be committed to a physical database accessible to the web server. Using transactions allows all updates to a dataset to be logged so that the updates can then be committed to the web server and reflected in a physical database.

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 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.

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, commit the transaction on the web server.



• 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 the transaction level is greater than -1, then immediately fire the AfterCommit event handler, if one is defined.



• If the transaction level is -1, wait for a result from the transaction commit operation on the web server. If the transaction commit was not successful due to the web server returning an HTTP status 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 access requests such as dataset 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 the transaction commit was successful, then fire the AfterCommit event handler, if one is defined.

Transaction Commit Properties

---

The TDatabase component uses the following properties when committing a transaction:

• TDatabase BaseURL
  This public property is a read-only, calculated property that returns the concatenation of the TServerSession BaseURL and DatabasesResource properties of the server session referenced in the ActiveServerSession property with the TDatabase DatabaseName property:
  
  

  <TServerSession.BaseURL>/<TServerSession.DatabasesResource>/<TDatabase.DatabaseName>

  
  This property is used by a TDatabase instance in client applications to build the URL used for the server request to the web server. This property is not used in server applications, and is unavailable.



• 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 is used to identify the database in database access requests and must match the name of an existing database defined on the web server.



• TDatabase Params
  This property is a string list (TStrings) of "name=value" pairs that represents any application-specific parameters to be used with all dataset commands executed for the database. Please see the Web Server Database Access topic for more information on how dataset commands are defined and how they use input parameters.

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.
  
   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 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;