OCI Mark or Unmark Object and Cache Functions

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

Table 17-7 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

OCICacheUnmark()

Purpose

Unmarks all dirty objects in the object cache.

Syntax

sword OCICacheUnmark ( OCIEnv            *env, 
                       OCIError          *err,
                       CONST OCISvcCtx   *svc );

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.

Comments

If a connection is specified, this function unmarks all dirty objects in that connection. Otherwise, all dirty objects in the cache are unmarked.

OCIObjectMarkDelete()

Purpose

Marks a standalone instance as deleted, given a pointer to the instance.

Syntax

sword OCIObjectMarkDelete ( OCIEnv        *env, 
                            OCIError      *err, 
                            dvoid         *instance );

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().
instance (IN): Pointer to the instance. It must be standalone, and if it is an object it must be pinned.

Comments

This function accepts a pointer to a standalone instance and marks the object as deleted. The object is freed according to the following rules:

For Persistent Objects: The object is marked deleted. The memory of the object is not freed. The object is deleted in the server when the object is flushed.
For Transient Objects: The object is marked deleted. The memory of the object is not freed.
For Values: This function frees a value immediately.

Related Functions

OCIObjectMarkDeleteByRef(), OCIObjectGetProperty()

OCIObjectMarkDeleteByRef()

Purpose

Marks an object as deleted, given a reference to the object.

Syntax

sword OCIObjectMarkDeleteByRef ( OCIEnv         *env, 
                                 OCIError       *err, 
                                 OCIRef         *object_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().
object_ref (IN): Reference to the object to be deleted.

Comments

This function accepts a reference to an object, and marks the object designated by object_ref as deleted. The object is marked and freed as follows:

For Persistent Objects

If the object is not loaded, then a temporary object is created and is marked deleted. Otherwise, the object is marked deleted.

The object is deleted in the server when the object is flushed.

For Transient Objects

The object is marked deleted. The object is not freed until it is unpinned.

Related Functions

OCIObjectMarkDelete(), OCIObjectGetProperty()

OCIObjectMarkUpdate()

Purpose

Marks a persistent object as updated, or dirty.

Syntax

sword OCIObjectMarkUpdate ( 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 marks a persistent object as updated, or dirty. The following special rules apply to different types of objects. The dirty status of an object may be checked by calling OCIObjectIsLocked().

For Persistent Objects

This function marks the specified persistent object as updated.

The persistent objects will be written to the server when the object cache is flushed. The object is not locked or flushed by this function. It is an error to update a deleted object.

After an object is marked updated and flushed, this function must be called again to mark the object as updated if it has been dirtied after it is being flushed.

For Transient Objects

This function marks the specified transient object as updated. The transient objects will not be written to the server. It is an error to update a deleted object.

For Values

This function is an no-op for values.

OCIObjectUnmark()

Purpose

Unmarks an object as dirty.

Syntax

sword OCIObjectUnmark ( 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): Pointer to the persistent object. It must be pinned.

Comments

For Persistent Objects and Transient Objects: This function unmarks the specified persistent object as dirty. Changes that are made to the object will not be written to the server. If the object is marked locked, it remains marked locked. The changes that have already made to the object will not be undone implicitly.
For Values: This function is an no-op for values. This means that the function will have no effect if called on a value.

Related Functions

OCIObjectUnmarkByRef()

Purpose

Unmarks an object as dirty, given a REF to the object.

Syntax

sword OCIObjectUnmarkByRef ( OCIEnv      *env, 
                             OCIError    *err,
                             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().
ref (IN): Reference of the object. It must be pinned.

Comments

This function unmarks an object as dirty. This function is identical to OCIObjectUnmark(), except that it takes a REF to the object as an argument.

For Persistent Objects and Transient Objects: This function unmarks the specified persistent object as dirty. Changes that are made to the object will not be written to the server. If the object is marked locked, it remains marked locked. The changes that have already made to the object will not be undone implicitly.
For Values: This function is a no-op for values.

Related Functions

OCIObjectUnmark()