setObjectCachePriority

setObjectCachePriority(obj:      Object;
                       priority: Integer);

The setObjectCachePriority method of the Process class specifies, through the priority parameter, how long an object, specified by the obj parameter, is to be retained in persistent or transient object cache. The greater the value of the priority parameter, the longer an object remains in the object cache.

The priority parameter effectively gives an object a number of lives in cache. When an object in cache has not been used for the specified length of time, it becomes a candidate to be removed from cache. Its number of lives is examined. If equal to one (1), the object is removed from cache. If 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.

The range of values for the priority parameter is zero (0) through 255. A negative value is treated as (0), and a value greater than 255 is treated as 255.

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.

If the value of the priority parameter is greater than zero (0), the setObjectCachePriority method loads the object into cache if it is not already present, before setting the number of lives. For values greater than one (1), this results in an extension to the length of time the object is retained in cache.

If the value of the priority parameter is zero (0), the setObjectCachePriority method removes the object from cache immediately, if it is currently in cache. If it is not in cache, the method has no effect. 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, as shown in the following example.

/* remove obj1 from cache as well as its slobs and blobs, 
   but not its // exclusive collections */
process.setObjectCachePriority(obj1, 0);
/* remove the exclusive collection obj2.allObj3s from cache 
and any of its collection blocks */
process.setObjectCachePriority(obj2.allObj3s, 0);

You can use the setObjectCachePriority method with persistent and transient objects; that is, it applies to persistent and transient object caches. With transient objects, a process can only affect 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 code fragment, a report application iterates a collection and accesses objects in the collection once only. The setObjectCachePriority method is used to remove each object from cache immediately after it has been accessed.

foreach cust in root.allCusts do
    totalSales := totalSales + cust.purchases;
    process.setObjectCachePriority(cust, 0);
endforeach;