Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10779-01 |
|
|
View PDF |
This section describes the OCI flush or refresh functions.
Function/Page | Purpose |
---|---|
Flush modified persistent objects in cache to server | |
Refresh pinned persistent objects | |
Flush a modified persistent object to the server | |
Refresh a persistent object |
Flushes modified persistent objects to the server
sword OCICacheFlush ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, dvoid *context, OCIRef *(*get) ( dvoid *context, ub1 *last ), OCIRef **ref );
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate()
and OCIInitialize()
for more information.
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()
.
OCI service context.
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.
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.
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.
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.
Refreshes all pinned persistent objects in the cache.
sword OCICacheRefresh ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIRefreshOpt option, dvoid *context, OCIRef *(*get)(dvoid *context), OCIRef **ref );
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate()
and OCIInitialize()
for more information.
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()
.
OCI service context.
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.
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.
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.
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
).
This function refreshes all pinned persistent objects and all unpinned persistent objects are freed from the object cache.
See Also:
For more information about refreshing, see the description of |
Flushes a modified persistent object to the server.
sword OCIObjectFlush ( OCIEnv *env, OCIError *err, dvoid *object );
The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate()
and OCIInitialize() for more information.
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()
.
A pointer to the persistent object. The object must be pinned before this call.
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.
See Also:
For more information on LOB functions, see"LOB Functions" . |
OCIObjectPin()
, OCICacheFlush()
Refreshes a persistent object from the most current database snapshot.
sword OCIObjectRefresh ( OCIEnv *env, OCIError *err, dvoid *object );
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate()
and OCIInitialize()
for more information.
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()
.
A pointer to the persistent object, which must already be pinned.
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.
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.