Client Dataset: Working with Data Packets and Applying Updates

In the previous articles, we talked about how the Client Dataset can be used to retrieve records by using the Dataset Provider component and how the various methods of specifying data should be retrieved or posted. We have discussed how this component along with the dataset provider or an XML provider can be used for different software development architectures. But we have not devoted much time to how the actual data transaction occurs and how to work with packet data, one of the most powerful features of client dataset/dataset provider components. 

Applying Updates

As I already discussed in the first article, the changes made to records in the dataset are stored in the delta data store of the client dataset component. In other words, all changes are cached locally. To post those changes to the data source you can call the ApplyUpdates method, and to discard them you can call the client dataset's CancelUpdates method. The CancelUpdates method discards the data in the change log and reverts to the original values that are stored in the data property of the client dataset. This method also restores the deleted values and removes newly inserted values from the dataset.

You can ascertain the number of modified records in the Delta by using the ChangeCount property of the client dataset. So, if the ChangeCount property returns a zero, you do not need to apply updates to the server.

To save changes to the database server or an XML document using an external provider, call the ApplyUpdates method. When the ApplyUpdates method is called, the client dataset converts the data in delta to data packets and sends them across to the dataset provider. It also calls the provider's ApplyUpdates method to write changes to the database by generating SQL statements.

ApplyUpdates (MaxErrors: Integer): Integer; virtual;

How the updates are applied on the database server depends on the parameter passed with the ApplyUpdates method. The MaxError parameter allows you to specify the number of errors you are willing to tolerate. The client dataset will attempt to update all records unless the number of errors encountered exceeds this number, in which case it will roll back the entire transaction.

If you do not want to allow any error, pass 0 as the max error parameter. Doing so will ensure that the transaction is roll backed even if a single error occurs. The records are sent back and the change log remains unchanged. However, if you have specified the max error parameter as -1, the transaction will be carried out regardless of the number of errors generated.

After the transaction is carried out successfully, applied records are removed from the change log and the conflicting records are left. The records left in the change log can be reconciled by handling the OnReconcileError event. This event and the  OnUpdateError event are generated when the client dataset is unable to resolve modified data to the server. You should always handle update errors, even if it is to discard values that cannot be updated.

Delphi 2006 makes reconciling update errors easy by including a Reconcile Error Dialog module in its object repository, which can be added to your project to allow the user to resolve data in case of an error. To add the Reconcile Error Dialog to your project, click on the menu item File|New|Other. The New Items dialog comes up. Expand the Delphi Projects folder icon in the treeview under Items Category. A number of sub-folders appear. Select the folder labeled Delphi Files. The modules available under this category are listed on the right pane of the window. Select " Reconcile Error Dialog " and click OK. The module will be automatically added to your project (Add RecError.pas to your uses clause). The only thing you need to do is add the HandleReconcileError method from the OnReconcileError event of the TClientDataSet component.