5.5.2 Rules for Working with TableRefPtr and Internal Cache

                                I.      Select() TableRefPtr
Every Select(), Clean() or Clean(ThisTable) deletes the existing Select() TableRefPtr. Additionaly, the Select() call executed on a table stores a new instance of the Select() TableRefPtr!

Therefore, the following rules apply:

Þ    For Select calls on a table use the notation from Picture 8: A Simple Select Query on a Table. The local assignment using a parameter does not affect the Select() TableRefPtr, because it is merely a copy.

Þ    If you use the Select() TableRefPtr (out of performance reasons), you should never store the pointer locally, but request it every time by calling the GetCurrentSelected() method

Þ    If you iterate through the result of a Select() TableRefPtr, be careful not to perform another Select() on the same table inside the loop, as this will cause the previous pointer to be overwritten, leading to unpredictable results

                             II.      Update() TableRefPtr
Every Clean(), Clean(ThisTable), Cancel(), Save() and Save(ThisTable) deletes the existing Update() TableRefPtr. Several Update() calls on the same table append the data to the existing Update() TableRefPtr.

Calling Save(EN_DBSAVE_NO_CLEAN) does not clear the Update() TableRefPtr, but requires another Clean() call from the caller.

Therefore, the following rules apply:

Þ    Never use a locally stored Update() TableRefPtr after a Save(), Clean() or Cancel().

Þ    Always take the current Update() TableRefPtr using GetCurrentUpdated()

                           III.      Delete() TableRefPtr
Every Clean(), Clean(ThisTable), Cancel(), Save() and Save(ThisTable) deletes the existing Delete() TableRefPtr. Several Delete() calls on the same table append the data to the existing Delete() TableRefPtr.

Therefore, the following rules apply:

Þ    Never use a locally stored Delete() TableRefPtr after a Save(), Clean() or Cancel().

Þ    Always take the current Delete() TableRefPtr using GetCurrentDeleted().

                          IV.      Insert() TableRefPtr
Every Clean(), Clean(ThisTable), Cancel(), Save() and Save(ThisTable) deletes the existing Insert() TableRefPtr. Several Insert() calls on the same table have the same effect as calling  GetCurrentInserted().

Calling Save(EN_DBSAVE_NO_CLEAN) does not clear the Insert() TableRefPtr, but requires another Clean() call from the caller.
This feature is particulary useful when reading out the primary keys which were automatically generated during a Save call.

Therefore, the following rules apply:

Þ    Never use a locally stored Insert() TableRefPtr after a Save(), Clean() or Cancel().

Þ    Always take the current Insert() TableRefPtr using GetCurrentInserted() or Insert().

                             V.      FK_[Field]() und PK_[Table_Field]() Navigation Cache
Based on the processed entity, the DBAction Code Generator automatically generates methods to easily retrieve the referenced/matching data (as type safe objects like items or collections) from the related entities. The purpose of these so called “navigation functions” is to avoid the repeated creation and execution of Select SQL statements and use a single method call instead, having the results (the instances of the item classes and containers) magaged internally by the cplusDBAction. The rules defined above (I-IV) also apply in this situation.

Methods like Clean(), Cancel(), CleanCache() or Save() can lead to the cleaning of the cache. The navigation methods will repopulate the cache if used with the parameter “Force Read Cache”. Caching can be temporarily or permanently enabled or disabled using the following methods: Enable/DisablePKCache(), Enable/DisableFKCache(), Enable/DisableGlobalPKCache() and Enable/DisableGlobalFKCache().
 

Related Topics

5.5 Data Organization and Memory Management