Applying Updates

From RAD Studio
Jump to: navigation, search

Go Up to Updating Records

Changes made to the client dataset's local copy of data are not sent to the database server (or XML document) until the client application calls the ApplyUpdates method. ApplyUpdates takes the changes in the change log, and sends them as a data packet (called Delta) to the provider. (Note that, when using most client datasets, the provider is internal to the client dataset.)

ApplyUpdates takes a single parameter, MaxErrors, which indicates the maximum number of errors that the provider should tolerate before aborting the update process. If MaxErrors is 0, then as soon as an update error occurs, the entire update process is terminated. No changes are written to the database, and the client dataset's change log remains intact. If MaxErrors is -1, any number of errors is tolerated, and the change log contains all records that could not be successfully applied. If MaxErrors is a positive value, and more errors occur than are permitted by MaxErrors, all updates are aborted. If fewer errors occur than specified by MaxErrors, all records successfully applied are automatically cleared from the client dataset's change log.

ApplyUpdates returns the number of actual errors encountered, which is always less than or equal to MaxErrors plus one. This return value indicates the number of records that could not be written to the database.

The client dataset's ApplyUpdates method does the following:

  • It indirectly calls the provider's ApplyUpdates method. The provider's ApplyUpdates method writes the updates to the database, source dataset, or XML document and attempts to correct any errors it encounters. Records that it cannot apply because of error conditions are sent back to the client dataset.
  • The client dataset 's ApplyUpdates method then attempts to reconcile these problem records by calling the Reconcile method. Reconcile is an error-handling routine that calls the OnReconcileError event handler. You must code the OnReconcileError event handler to correct errors. For details about using OnReconcileError, see Reconciling Update Errors.
  • Finally, Reconcile removes successfully applied changes from the change log and updates Data to reflect the newly updated records. When Reconcile completes, ApplyUpdates reports the number of errors that occurred.

Warning: In some cases, the provider can't determine how to apply updates (for example, when applying updates from a stored procedure or multi-table join). Client datasets and provider components generate events that let you handle these situations. See Intervening as Updates Are Applied for details.

Tip: If the provider is on a stateless application server, you may want to communicate with it about persistent state information before or after you apply updates. TClientDataSet receives a BeforeApplyUpdates event before the updates are sent, which lets you send persistent state information to the server. After the updates are applied (but before the reconcile process), TClientDataSet receives an AfterApplyUpdates event where you can respond to any persistent state information returned by the application server.

See Also