OCIObjectRefresh()

Purpose

Refreshes a persistent object from the most current database snapshot.

Syntax

sword OCIObjectRefresh ( OCIEnv        *env, 
                         OCIError      *err, 
                         dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object, which must already be pinned.

Comments

This function refreshes an object with data retrieved from the latest snapshot in the server. An object should be refreshed when the objects in the object cache are inconsistent with the objects at the server.

Note: When an object is flushed to the server, triggers can be fired to modify more objects in the server. The same objects (modified by the triggers) in the object cache become out-of-date, and must be refreshed before they can be locked or flushed. This occurs when the user issues a SQL statement or PL/SQL procedure to modify any object in the server.

Caution: Modifications made to objects (dirty objects) since the last flush are lost if unmarked objects are refreshed by this function.

The various meta-attribute flags and durations of an object are modified after being refreshed:

Object Attribute	Status After Refresh
existent	set to appropriate value
pinned	unchanged
allocation duration	unchanged
pin duration	unchanged

The object that is refreshed will be replaced-in-place. When an object is replaced-in-place, the top-level memory of the object will be reused so that new data can be loaded into the same memory address. The top level memory of the null indicator structure is also reused. Unlike the top-level memory chunk, the secondary memory chunks will be freed and reallocated.

You should be careful when writing functionality that holds on to a pointer to the secondary memory chunk, such as assigning the address of a secondary memory to a local variable, because this pointer can become invalid after the object is refreshed.

This function does nothing for transient objects or values.

Related Functions

OCICacheRefresh()

OCI Mark or Unmark Object and Cache Functions

This section describe the OCI mark or unmark Object and Cache functions.

Table 17-3 Mark or Unmark Object and Cache Functions

Function/Page	Purpose
OCICacheUnmark()	Unmarks objects in the cache
OCIObjectMarkDelete()	Mark an object deleted / delete a value instance
OCIObjectMarkDeleteByRef()	Mark an object deleted given a ref
OCIObjectMarkUpdate()	Mark an object as updated/dirty
OCIObjectUnmark()	Unmarks an object
OCIObjectUnmarkByRef()	Unmarks an object, given a ref to it