Using cached updates with tables, views, and query result sets is accomplished through the BeginCachedUpdates, and ApplyCachedUpdates, and CancelCachedUpdates methods of the TEDBTable, TEDBQuery, TEDBScript, and TEDBStoredProc components. In addition, the CachingUpdates property can be used to find out when cached updates are in effect for a dataset.

Using cached updates permits an application to copy all existing rows in a given table, view, or query result set to a temporary table that is then used for any inserts, updates, or deletes. Once all updates are complete, the application may then call the ApplyCachedUpdates method to apply all updates to the source table or query result set, or the CancelCachedUpdates method to cancel all updates and revert the table or query result set to its original state prior to the cached updates. The rows that are included in the cached updates can be controlled by setting a range or filter on the source table or query result set prior to calling the BeginCachedUpdates method. Please see the Setting Ranges on Tables and Setting Filters on Tables,Views, and Query Result Sets topics for more information.


Beginning Cached Updates

---

To begin cached updates, you must call the BeginCachedUpdates method. When using either a TEDBTable, TEDBQuery, TEDBStoredProc, or TEDBScript component, the table, view, or query result set must be opened (Active property is set to True) or an exception will be raised.


Applying Cached Updates

---

To apply any cached updates to the source table, view, or query result set, you must call the ApplyCachedUpdates method. This method will apply any updates that were made to the temporary table used for the cached updates to the source table, view, or query result set. Only rows that were inserted, updated, or deleted are processed, so the result is the same as calling the CancelCachedUpdates method if no rows were inserted, updated, or deleted while cached updates were enabled. You can examine the CachingUpdates property to determine whether cached udpdates are in effect before trying to apply any cached updates.

A transaction is not required around the ApplyCachedUpdates method call in order to make it atomic. The ApplyCachedUpdates method is always executed as an atomic unit of work.

Reconciling Errors

---

Cached updates are handled in an optimistic manner, which means that ElevateDB does not hold any locks on the rows that are held in the cache while the cached updates are in effect. Subsequently, it is possible that another session has changed some or all of the rows that were cached and updated or deleted in the cache. When the cached updates are then applied using the ApplyCachedUpdates method, an error message will be raised and it is possible that only a portion of the cached updates will be applied to the source table, view, or query result set. To avoid this, you can define an ERROR trigger on the underlying table being updated. For more information on ERROR triggers, please see the CREATE TRIGGER topic in the ElevateDB SQL Manual.


Filters, Ranges, and Master-Detail Links

---

Most of the operations that can be performed on a TEDBTable, TEDBQuery, TEDBScript, or TEDBStoredProc component behave the same regardless of whether cached updates are active or not. This includes the following operations:

Navigating Tables, Views, and Query Result Sets
Searching and Sorting Tables, Views, and Query Result Sets
Inserting, Updating, and Deleting Rows

However, certain states of the table, view, or query result set are not carried over to the cached updates temporary table. These include:

Filters
Ranges
Master-Detail Links

All of these states are reset for the cached updates temporary table. You may apply new filters, ranges, and/or master-detail links on the cached updates temporary table if you wish, but they will not apply to the base table nor will they affect the base table's state with respect to filters, ranges, or master-detail links. After the cached updates are applied or cancelled, all of these states are set back to what they were prior to the cached updates being active.

Refreshing During Cached Updates

---

If you call the TEDBTable, TEDBQuery, TEDBStoredProc, or TEDBScript Refresh method while cached updates are active, then the current contents of the cached updates temporary table will be discarded and replaced with the latest data from the base table. Cached updates will remain in effect after the Refresh is complete.