Applying Cached Updates
Go Up to Using Cached Updates
When a dataset is in cached update mode, changes to data are not actually written to the database until your application explicitly calls methods that apply those changes. Normally an application applies updates in response to user input, such as through a button or menu item.
- Important: To apply updates to a set of records retrieved by a SQL query that does not return a live result set, you must use a
TIBUpdateSQLobject to specify how to perform the updates. For updates to joins (queries involving two or more tables), you must provide oneTIBUpdateSQLobject for each table involved, and you must use theOnUpdateRecordevent handler to invoke these objects to perform the updates. For more information, see Updating a Read-only Result Set. For more information about creating and using anOnUpdateRecordevent handler, see Creating an OnUpdateRecord Event Handler.
Applying updates is a two-phase process that should occur in the context of a transaction component to enable your application to recover gracefully from errors.
When applying updates under transaction control, the following events take place:
- A database transaction starts.
- Cached updates are written to the database (phase 1). If you provide it, an
OnUpdateRecordevent is triggered once for each record written to the database. If an error occurs when a record is applied to the database, theOnUpdateErrorevent is triggered if you provide one.
If the database write is unsuccessful:
- Database changes are rolled back, ending the database transaction.
- Cached updates are not committed, leaving them intact in the internal cache buffer.
If the database write is successful:
- Database changes are committed, ending the database transaction.
- Cached updates are committed, clearing the internal cache buffer (phase 2).
The two-phased approach to applying cached updates allows for effective error recovery, especially when updating multiple datasets (for example, the datasets associated with a master/detail form). For more information about handling update errors that occur when applying cached updates, see Handling Cached Update Errors.
There are actually two ways to apply updates. To apply updates for a specified set of datasets associated with a database component, call the database component’s ApplyUpdates method. To apply updates for a single dataset, call the dataset’s ApplyUpdates and Commit methods. These choices, and their strengths, are described in the following sections.