OCICacheFlush()

Purpose

Flushes modified persistent objects to the server

Syntax

sword OCICacheFlush ( OCIEnv              *env, 
                      OCIError            *err, 
                      CONST OCISvcCtx     *svc, 
                      dvoid               *context,
                      OCIRef              *(*get)
                                          ( dvoid   *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 an 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 signalled. 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.

This function incurs at most one network round-trip.

Related Functions

OCIObjectFlush()