OCI Flush or Refresh Functions

This section describes the OCI flush or refresh functions.

Table 18-5 Flush or Refresh Functions

Function/Page	Purpose
OCICacheFlush()	Flush modified persistent objects in cache to server
OCICacheRefresh()	Refresh pinned persistent objects
OCIObjectFlush()	Flush a modified persistent object to the server
OCIObjectRefresh()	Refresh a persistent object

OCICacheFlush()

Purpose

Flushes modified persistent objects to the server

Syntax

sword OCICacheFlush ( OCIEnv              *env, 
                      OCIError            *err, 
                      const OCISvcCtx     *svc, 
                      void                *context,
                      OCIRef              *(*get)
                                          ( void    *context,
                                            ub1     *last ), 
                      OCIRef              **ref );

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().

svc (IN)

OCI service context.

context (IN) [optional]

Specifies a user context that is an argument to the client callback function get. This parameter is set to NULL if there is no user context.

get (IN) [optional]

A client-defined function which acts an iterator to retrieve a batch of dirty objects that need to be flushed. If the function is not NULL, this function will be called to get a reference of a dirty object. This is repeated until a NULL reference is returned by the client function or the parameter last is set to TRUE. The parameter context is passed to get() for each invocation of the client function. This parameter should be NULL if user callback is not given. If the object that is returned by the client function is not a dirtied persistent object, the object is ignored.

All the objects that are returned from the client function must be newed or pinned using the same service context, otherwise an error is signaled. Note that the cache flushes the returned objects in the order in which they were marked dirty.

If this parameter is passed as NULL (for example, no client-defined function is provided), then all dirty persistent objects for the given service context are flushed in the order in which they were dirtied.

ref (OUT) [optional]

If there is an error in flushing the objects (*ref) will point to the object that is causing the error. If ref is NULL, then the object will not be returned. If *ref is NULL, then a reference will be allocated and set to point to the object. If *ref is not NULL, then the reference of the object is copied into the given space. If the error is not caused by any of the dirtied object, the given REF is initialized to be a NULL reference (OCIRefIsNull(*ref) is TRUE).

The REF is allocated for session duration (OCI_DURATION_SESSION). The application can free the allocated REF using the OCIObjectFree() function.

Comments

This function flushes the modified persistent objects from the object cache to the server. The objects are flushed in the order that they are newed or marked updated or deleted.

OCICacheRefresh()

Purpose

Refreshes all pinned persistent objects in the cache.

Syntax

sword OCICacheRefresh ( OCIEnv            *env, 
                       OCIError           *err, 
                       const OCISvcCtx    *svc,
                       OCIRefreshOpt      option, 
                       void               *context,
                       OCIRef             *(*get)(void  *context), 
                       OCIRef             **ref );

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().
svc (IN): OCI service context.
option (IN) [optional]: If OCI_REFRESH_LOADED is specified, all objects that are loaded within the transaction are refreshed. If the option is OCI_REFRESH_LOADED and the parameter get is not NULL, this function will ignore the parameter.
context (IN) [optional]: Specifies a user context that is an argument to the client callback function get. This parameter is set to NULL if there is no user context.
get (IN) [optional]: A client-defined function which acts an iterator to retrieve a batch of objects that need to be refreshed. If the function is not NULL, this function will be called to get a reference of an object. If the reference is not NULL, then the object will be refreshed. These steps are repeated until a NULL reference is returned by this function. The parameter context is passed to get() for each invocation of the client function. This parameter should be NULL if user callback is not given.
ref (OUT) [optional]: If there is an error in refreshing the objects, (*ref) will point to the object that is causing the error. If ref is NULL, then the object will not be returned. If *ref is NULL, then a reference will be allocated and set to point to the object. If *ref is not NULL, then the reference of the object is copied into the given space. If the error is not caused by any of the object, the given ref is initialized to be a NULL reference (OCIRefIsNull(*ref) is TRUE).

Comments

This function refreshes all pinned persistent objects and all unpinned persistent objects are freed from the object cache.

OCIObjectFlush()

Purpose

Flushes a modified persistent object to the server.

Syntax

sword OCIObjectFlush ( OCIEnv        *env,
                       OCIError      *err,
                       void          *object );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode. See the descriptions 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. The object must be pinned before this call.

Comments

This function flushes a modified persistent object to the server. An exclusive lock is obtained implicitly for the object when it is flushed. When the object is written to the server, triggers may be fired. This function returns an error for transient objects and values, and for unmodified persistent objects.

Objects can be modified by triggers at the server. To keep objects in the cache consistent with the database, an application can free or refresh objects in the cache.

If the object to flush contains an internal LOB attribute and the LOB attribute was modified due to an OCIObjectCopy(), OCILobAssign(), or OCILobLocatorAssign() or by assigning another LOB locator to it, then the flush makes a copy of the LOB value that existed in the source LOB at the time of the assignment or copy of the internal LOB locator or object.

OCIObjectRefresh()

Purpose

Refreshes a persistent object from the most current database snapshot.

Syntax

sword OCIObjectRefresh ( OCIEnv        *env, 
                         OCIError      *err, 
                         void          *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:

Table 18-6 Object Status After Refresh

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()