OCIObjectUnpin()

Purpose

Unpins an object.

Syntax

sword OCIObjectUnpin ( 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 an object, which must already be pinned.

Comments

There is a pin count associated with each object which is incremented whenever an object is pinned. When the pin count of the object is zero, the object is said to be completely unpinned. An unpinned object can be freed implicitly by the OCI at any time without error.

This function unpins an object. An object is completely unpinned when any of the following is true:

1. The object's pin count reaches zero (i.e., it is unpinned a total of N times after being pinned a total of N times).
2. It is the end of the object's pin duration.
3. The function OCIObjectPinCountReset() is called on the object.

When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error.

The following rules apply for unpinning different types of objects:

For Persistent Objects

When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed.

For Transient Objects

The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly deleted by calling OCIObjectFree().

For Values

This function returns an error for values.

Related Functions

OCIObjectPin(), OCIObjectPinCountReset()

OCI Type Information Accessor Functions

This section describes the OCI type information accessor functions.

Table 17-7 Type Information Accessor Functions

Function/Page	Purpose
OCITypeArrayByName()	Get an array of TDOs given an array of object names
OCITypeArrayByRef()	Get an array of TDOs given an array of object references
OCITypeByName()	Get a TDO given an object name
OCITypeByRef()	Get a TDO given an object reference