ori.h

通用的数据库中间库

   DESCRIPTION:
        This function completely unpins an object.  When an object is 
        completely unpinned, it 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
        freed 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. 
 */

/*--------------------------- OCIObjectLock ---------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectLock(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectLock(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectLock - OCI lock a persistent 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 the persistent object 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
   DESCRIPTION:
        This function locks a persistent object at the server. Unlike
        OCIObjectLockNoWait() this function waits if another user currently
        holds a lock on the desired object. This function
        returns an error if:
          1) the object is non-existent.

        This function will return an error for transient objects and values.
        The lock of an object is released at the end of a transaction.

   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. 
*/

/*------------------------ OCIObjectLockNoWait ------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectLockNoWait(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectLockNoWait(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectLockNoWait - OCI lock a persistent object, do not wait for
			       the lock, return error if lock not available
   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 the persistent object 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
   DESCRIPTION:
        This function locks a persistent object at the server. Unlike
        OCIObjectLock() this function will not wait if another user holds
        the lock on the desired object. This function returns an error if:
          1) the object is non-existent.
	  2) the object is currently locked by another user in which
             case this function returns with an error.

        This function will return an error for transient objects and values.
        The lock of an object is released at the end of a transaction.

   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. 
*/

/*--------------------------- OCIObjectMarkUpdate ----------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectMarkUpdate(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectMarkUpdate(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectMarkUpdate - OCI marks an object as updated
   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 the persistent object 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
   DESCRIPTION:
        FOR PERSISTENT OBJECTS:
        This function marks the specified persistent object as updated. The
        persistent objects will be written to the server when the object cache
        is flushed.  The object is not locked or flushed by this function. It
        is an error to update a deleted object.  

        After an object is marked updated and flushed, this function must be
        called again to mark the object as updated if it has been dirtied
        after it is being flushed.

        FOR TRANSIENT OBJECTS:
        This function marks the specified transient object as updated. The
        transient objects will NOT be written to the server. It is an error
        to update a deleted object.

        FOR VALUES:
        It is an no-op for values.

   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. 
 */

/*----------------------------- OCIObjectUnmark -----------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectUnmark(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectUnmark(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectUnmark - OCI unmarks an 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 the persistent object
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
   DESCRIPTION:
        FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
        This function unmarks the specified persistent object as dirty. Changes
        that are made to the object will not be written to the server. If the
        object is marked locked, it remains marked locked.  The changes that
        have already made to the object will not be undone implicitly. 
 
        FOR VALUES:
        It is an no-op for values.
 
   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.
 */

/*----------------------------- OCIObjectUnmarkByRef ------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectUnmarkByRef(/*_ OCIEnv *env, OCIError *err, OCIRef *ref _*/);
#else /* ANSI C */
sword OCIObjectUnmarkByRef(    OCIEnv *env, OCIError *err, OCIRef *ref    );
#endif
/*
   NAME: OCIObjectUnmarkByRef - OCI unmarks an object by Ref
   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().
        ref   (IN) - reference of the object
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
   DESCRIPTION:
        FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
        This function unmarks the specified persistent object as dirty. Changes
        that are made to the object will not be written to the server. If the
        object is marked locked, it remains marked locked.  The changes that
        have already made to the object will not be undone implicitly.
 
        FOR VALUES:
        It is an no-op for values.
 
   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.
 */

/*--------------------------- OCIObjectFree ---------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectFree(/*_ OCIEnv *env, OCIError *err, dvoid *instance, 
                        ub2 flags _*/);
#else /* ANSI C */
sword OCIObjectFree(    OCIEnv *env, OCIError *err, dvoid *instance, 
                        ub2 flags   );
#endif
/*
   NAME: OCIObjectFree - OCI free (and unpin) an 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().
        instance   (IN) - pointer to a standalone instance.
        flags      (IN) - If OCI_OBJECT_FREE_FORCE is set, free the object
                          even if it is pinned or dirty.
                          If OCI_OBJECT_FREE_NONULL is set, the null
                          structure will not be freed. 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The instance to be freed must be standalone.
        - If the instance is a referenceable object, the object must be pinned. 
   DESCRIPTION:
        This function deallocates all the memory allocated for an OTS instance,
        including the null structure.

        FOR PERSISTENT OBJECTS:
        This function will return an error if the client is attempting to free 
        a dirty persistent object that has not been flushed. The client should 
        either flush the persistent object or set the parameter 'flag' to  
        OCI_OBJECT_FREE_FORCE.

        This function will call OCIObjectUnpin() once to check if the object 
        can be completely unpin. If it succeeds, the rest of the function will 
        proceed to free the object.  If it fails, then an error is returned 
        unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE.
 
        Freeing a persistent object in memory will not change the persistent 
        state of that object at the server.  For example, the object will 
        remain locked after the object is freed.

        FOR TRANSIENT OBJECTS:

        This function will call OCIObjectUnpin() once to check if the object 
        can be completely unpin. If it succeeds, the rest of the function will 
        proceed to free the object.  If it fails, then an error is returned 
        unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE. 

        FOR VALUES:
        The memory of the object is freed immediately. 

   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. 
*/

/*------------------------ OCIObjectMarkDeleteByRef --------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectMarkDeleteByRef(/*_ OCIEnv *env,OCIError *err,
                                   OCIRef *object_ref _*/);
#else /* ANSI C */
sword OCIObjectMarkDeleteByRef(    OCIEnv *env, OCIError *err,