OCIObjectFree()

Purpose

Frees and unpins an object instance.

Syntax

sword OCIObjectFree ( OCIEnv          *env, 
                      OCIError        *err, 
                      dvoid           *instance, 
                      ub2             flags );

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 a standalone instance. If it is an object, it must be pinned.

flags (IN)

If OCI_OBJECTFREE_FORCE is passed, free the object even if it is pinned or dirty. If OCI_OBJECTFREE_NONULL is passed, the null structure is not freed.

Comments

This function deallocates all the memory allocated for an object instance, including the null structure. The following rules apply for different instance types:

For Persistent Objects

This function returns an error if the client is attempting to free a dirty persistent object that has not been flushed. The client should either flush the persistent object, unmark it, or set the parameter flags to OCI_OBJECTFREE_FORCE.

This function calls OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function proceeds to free the object. If it fails, then an error is returned unless the parameter flags is set to OCI_OBJECTFREE_FORCE.

Freeing a persistent object in memory does not change the persistent state of that object at the server. For example, the object remains locked after the object is freed.

For Transient Objects

This function will call OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function will proceed to free the object. If it fails, then an error is returned unless the parameter flags is set to OCI_OBJECTFREE_FORCE.

For Values

The memory of the object is freed immediately.

Related Functions

OCICacheFree()