|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
OCI Navigational and Type Functions, 29 of 36
Pin a referenceable object.
sword OCIObjectPin ( OCIEnv *env, OCIError *err, OCIRef *object_ref, OCIComplexObject *corhdl, OCIPinOpt pin_option, OCIDuration pin_duration, OCILockOpt lock_option, dvoid **object );
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
The reference to the object.
Handle for complex object retrieval.
Used to specify the copy of the object that is to be retrieved.
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 (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:
For information about the
The pointer to the pinned object.
This function pins a referenceable object instance given the object reference. The process of pinning serves two purposes:
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:
pin_optionis 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.
pin_optionis 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.
pin_optionis 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.
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.