adjustObjectCachePriority

adjustObjectCachePriority(obj:   Object;
                          delta: Integer): Boolean;

The adjustObjectCachePriority method of the Process class changes, through the delta parameter, how long an object, specified by the obj parameter, is to be retained in object cache. If the object is in cache, true is returned to indicate that the retention of the object in cache has been changed. If the object is not in cache or is being updated by another process, false is returned.

The value of the delta parameter effectively changes the number of lives in cache of the object specified by the obj parameter. The number of lives for an object in cache is one (1) through 255. A positive value for the delta parameter increases the number of lives up to the upper limit of 255, and a negative value decreases the number of lives to the lower limit of zero (0) lives, at which point the object is removed from cache.

When an object in cache is not used for the specified amount of time, it becomes a candidate to be removed from cache. Its number of lives is examined. If it is equal to one (1), the object is removed from cache. If it is greater than one (1), the number of lives is decremented and instead of being removed from cache, the object is treated as if it had just been accessed. This results in it being retained longer in cache, instead of being removed. Conversely, when the number of lives for an object is set to zero (0), it is removed from cache.

When an object is removed, its subobjects are also removed, including string large objects (slobs) and binary large objects (blobs) but not exclusive collections, which must be removed separately.

The adjustObjectCachePriority method is a variation of the setObjectCachePriority method that enables you to adjust the number of lives relative to the current value, rather than specify the exact number of lives.

The number of lives an object has applies only while the object is in cache. When an object is first loaded into cache, it is assigned one life only. Lives are not recorded for objects that are not in cache.

You can use the adjustObjectCachePriority method with persistent and transient objects; that is, it applies to persistent and transient object caches. With transient objects, a process can affect only shared transient objects and its own non-shared transient objects.

A process must use its own Process instance as the method receiver. Using any other Process instance causes a 1265 exception (Environmental object operation is out of scope for process) to be raised.

In the following method, an application decrements the number of lives each object in a collection; that is, reduces the number of lives by one (1) on an individual basis.

foreach cust in root.allCusts do
    totalSales := totalSales + cust.purchases;
    process.adjustObjectCachePriority(cust, -1);
endforeach;