ori.h

通用的数据库中间库

/*---------------------------------------------------------------------------*/
/*                       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.
        if operation suceeds, return OCI_SUCCESS. 
        if operation fails, return OCI_ERROR. 
 */

/*---------------------------- OCIObjectPinCountReset -----------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectPinCountReset(/*_ OCIEnv *env,OCIError *err,dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectPinCountReset(    OCIEnv *env, OCIError *err, dvoid *object   );
#endif
/*
   NAME: OCIObjectPinCountReset - OCI resets the pin count of 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.