OCIObjectPin()

Purpose

Pin a referenceable object.

Syntax

sword OCIObjectPin ( OCIEnv              *env, 
                     OCIError            *err, 
                     OCIRef              *object_ref,
                     OCIComplexObject    *corhdl,
                     OCIPinOpt           pin_option, 
                     OCIDuration         pin_duration, 
                     OCILockOpt          lock_option,
                     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_ref (IN)

The reference to the object.

corhdl (IN)

Handle for complex object retrieval.

pin_option (IN)

Used to specify the copy of the object that is to be retrieved.

pin_duration (IN)

The duration of which the object is being accessed by a client. The object is implicitly unpinned at the end of the pin duration. If OCI_DURATION_NULL is passed, there is no pin promotion if the object is already loaded into the cache. If the object is not yet loaded, then the pin duration is set to OCI_DURATION_DEFAULT in the case of OCI_DURATION_NULL.

lock_option (IN)

Lock option (for example, exclusive). If a lock option is specified, the object is locked in the server. Note, the lock status of an object can also be retrieved by calling OCIObjectIsLocked(). Valid values include:

object (OUT)

The pointer to the pinned object.

Comments

This function pins a referenceable object instance given the object reference. The process of pinning serves two purposes:

• locate an object given its reference. This is done by the object cache which keeps track of the objects in the object cache.
• notify the object cache that a persistent object is being in use such that the persistent object cannot be aged out. Since a persistent object can be loaded from the server whenever is needed, the memory utilization can be increased if a completely unpinned persistent object can be freed (aged out), even before the allocation duration is expired. An object can be pinned many times. A pinned object will remain in memory until it is completely unpinned.

  See Also: See OCIObjectUnpin().

For Persistent Objects

When pinning a persistent object, if it is not in the cache, the object will be fetched from the persistent store. The allocation duration of the object is session. If the object is already in the cache, it is returned to the client. The object will be locked in the server if a lock option is specified.

This function will return an error for a non-existent object.

A pin option is used to specify the copy of the object that is to be retrieved:

• If pin_option is OCI_PIN_ANY (pin any), then if the object is already in the object cache, return this object. Otherwise, the object is retrieved from the database. In this case, it is the same as OCI_PIN_LATEST. This option is useful when the client knows that he has the exclusive access to the data in a session.
• If pin_option is OCI_PIN_LATEST (pin latest), if the object is not locked, it is retrieved from the database. If the object is cached, it is refreshed with the latest version. See OCIObjectRefresh() for more information about refreshing. If the object is already pinned in the cache and marked dirty, then a pointer to that object is returned. The object will not be refreshed from the database.
• If pin_option is OCI_PIN_RECENT (pin recent), if the object is loaded into the cache in the current transaction, the object is returned. If the object is not loaded in the current transaction, the object is refreshed from the server.

For Transient Objects

This function will return an error if the transient object has already been freed. This function does not return an error if an exclusive lock is specified in the lock option.

Related Functions

OCIObjectUnpin(), OCIObjectPinCountReset()