📄 ori.h
字号:
#define OCIObjectRefresh oriorfs
#define OCIObjectPinTable oriogtb
#define OCIObjectGetPrimaryKeyTypeRef oriogpf
#define OCIObjectMakeObjectRef oriomrf
#define OCIObjectNew orionew
#define OCIObjectPin oriopin
#define OCIObjectFree oriofre
#define OCIObjectArrayPin orioapn
#define OCIObjectIsDirty oriodrt
#define OCIObjectIsDirtied oriodrd
#define OCIObjectIsLoaded orioldd
#define OCICacheFlush oricfls
#define OCICacheRefresh oricrfs
#endif /* SLSHORTNAME */
/*---------------------------------------------------------------------------*/
/* PUBLIC TYPES AND CONSTANTS */
/*---------------------------------------------------------------------------*/
/* Also see oro.h. */
/*---------------------------------------------------------------------------*/
/* PUBLIC FUNCTIONS */
/*---------------------------------------------------------------------------*/
/*---------------------------------------------------------------------------*/
/* OBJECT/INSTANCE OPERATIONS */
/*---------------------------------------------------------------------------*/
/*--------------------------- OCIObjectNew ----------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectNew(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
OCITypeCode typecode, OCIType *tdo, dvoid *table,
OCIDuration duration, boolean value,
dvoid **instance _*/);
#else /* ANSI C */
sword OCIObjectNew( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
OCITypeCode typecode, OCIType *tdo, dvoid *table,
OCIDuration duration, boolean value,
dvoid **instance );
#endif
/*
NAME: OCIObjectNew - OCI new (create) a standalone instance
PARAMETERS:
env (IN/OUT) - OCI environment handle initialized in object mode
err (IN/OUT) - error handle. If there is an error, it is
recorded in 'err' and this function returns OCI_ERROR.
The error recorded in 'err' can be retrieved by calling
OCIErrorGet().
svc (IN) - OCI service handle.
typecode (IN) - the typecode of the type of the instance.
tdo (IN, optional) - pointer to the type descriptor object. The
TDO describes the type of the instance that is to be
created. Refer to OCITypeByName() for obtaining a TDO.
The TDO is required for creating a named type (e.g. an
object or a collection).
table (IN, optional) - pointer to a table object which specifies a
table in the server. This parameter can be set to NULL
if no table is given. See the description below to find
out how the table object and the TDO are used together
to determine the kind of instances (persistent,
transient, value) to be created. Also see
OCIObjectPinTable() for retrieving a table object.
duration (IN) - this is an overloaded parameter. The use of this
parameter is based on the kind of the instance that is
to be created.
a) persistent object. This parameter specifies the
pin duration.
b) transient object. This parameter specififes the
allocation duration and pin duration.
c) value. This parameter specifies the allocation
duration.
value (IN) - specifies whether the created object is a value.
If TRUE, then a value is created. Otherwise, a
referenceable object is created. If the instance is
not an object, then this parameter is ignored.
instance (OUT) - address of the newly created instance
REQUIRES:
- a valid OCI environment handle must be given.
DESCRIPTION:
This function creates a new instance of the type specified by the
typecode or the TDO. Based on the parameters 'typecode' (or 'tdo'),
'value' and 'table', different kinds of instances can be created:
The parameter 'table' is not NULL?
yes no
----------------------------------------------------------------
| object type (value=TRUE) | value | value |
----------------------------------------------------------------
| object type (value=FALSE) | persistent obj | transient obj |
type ----------------------------------------------------------------
| built-in type | value | value |
----------------------------------------------------------------
| collection type | value | value |
----------------------------------------------------------------
This function allocates the top level memory chunk of an OTS instance.
The attributes in the top level memory are initialized (e.g. an
attribute of varchar2 is initialized to a vstring of 0 length).
If the instance is an object, the object is marked existed but is
atomically null.
FOR PERSISTENT OBJECTS:
The object is marked dirty and existed. The allocation duration for
the object is session. The object is pinned and the pin duration is
specified by the given parameter 'duration'.
FOR TRANSIENT OBJECTS:
The object is pinned. The allocation duration and the pin duration are
specified by the given parameter 'duration'.
FOR VALUES:
The allocation duration is specified by the given parameter 'duration'.
RETURNS:
if environment handle or error handle is null, return
OCI_INVALID_HANDLE.
if operation suceeds, return OCI_SUCCESS.
if operation fails, return OCI_ERROR.
*/
/*--------------------------- OCIObjectPin ----------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectPin(/*_ OCIEnv *env, OCIError *err, OCIRef *object_ref,
OCIComplexObject *corhdl, OCIPinOpt pin_option,
OCIDuration pin_duration, OCILockOpt lock_option,
dvoid **object _*/);
#else /* ANSI C */
sword OCIObjectPin( OCIEnv *env, OCIError *err, OCIRef *object_ref,
OCIComplexObject *corhdl, OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock_option, dvoid **object );
#endif
/*
NAME: OCIObjectPin - OCI pin a referenceable object
PARAMETERS:
env (IN/OUT) - OCI environment handle initialized in object mode
err (IN/OUT) - error handle. If there is an error, it is
recorded in 'err' and this function returns
OCI_ERROR. The error recorded in 'err' can be
retrieved by calling OCIErrorGet().
object_ref (IN) - the reference to the object.
corhdl (IN) - handle for complex object retrieval.
pin_option (IN) - See description below.
pin_duration (IN) - The duration of which the object is being accesed
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.
lock_option (IN) - lock option (e.g., exclusive). If a lock option
is specified, the object is locked in the server.
See 'oro.h' for description about lock option.
object (OUT) - the pointer to the pinned object.
REQUIRES:
- a valid OCI environment handle must be given.
DESCRIPTION:
This function pins a referenceable object instance given the object
reference. The process of pinning serves three purposes:
1) locate an object given its reference. This is done by the object
cache which keeps track of the objects in the object heap.
2) notify the object cache that an object is being in use. An object
can be pinned many times. A pinned object will remain in memory
until it is completely unpinned (see OCIObjectUnpin()).
3) 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.
Also see OCIObjectUnpin() for more information about unpinning.
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:
1) If option is OCI_PIN_ANY (pin any), if the object is already
in the environment heap, return this object. Otherwise, the object
is retrieved from the database. This option is useful when the
client knows that he has the exclusive access to the data in a
session.
2) If option is OCI_PIN_LATEST (pin latest), if the object is
not cached, 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.
3) If 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.
RETURNS:
if environment handle or error handle is null, return
OCI_INVALID_HANDLE.
if operation suceeds, return OCI_SUCCESS.
if operation fails, return OCI_ERROR.
*/
/*------------------------------ OCIObjectUnpin -----------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectUnpin(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectUnpin( OCIEnv *env, OCIError *err, dvoid *object );
#endif
/*
NAME: OCIObjectUnpin - OCI unpin a referenceable object
PARAMETERS:
env (IN/OUT) - OCI environment handle initialized in object mode
err (IN/OUT) - error handle. If there is an error, it is
recorded in 'err' and this function returns OCI_ERROR.
The error recorded in 'err' can be retrieved by
calling OCIErrorGet().
object (IN) - pointer to an object
REQUIRES:
- a valid OCI environment handle must be given.
- The specified object must be pinned.
DESCRIPTION:
This function unpins an object. An object is completely unpinned when
1) the object was unpinned N times after it has been pinned N times
(by calling OCIObjectPin()).
2) it is the end of the pin duration
3) the function OCIObjectPinCountReset() is called
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 without error.
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 VALUE:
This function will return an error for value.
RETURNS:
if environment handle or error handle is null, return
OCI_INVALID_HANDLE.
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -