ori.h

将对Oracle数据库读写操作的OCI进行封装。不但具有普通数据的读取操作

        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, 
                                   OCIRef *object_ref);
#endif
/*
   NAME: OCIObjectMarkDeleteByRef - OCI "delete" (and unpin) an object given
                                    a reference
   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) - ref of the object to be deleted

   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        This function marks the object designated by 'object_ref' as deleted.

        FOR PERSISTENT OBJECTS:
        If the object is not loaded, then a temporary object is created and is 
        marked deleted. Otherwise, the object is marked deleted.  

        The object is deleted in the server when the object is flushed.

        FOR TRANSIENT OBJECTS:
        The object is marked deleted.  The object is not freed until it is
        unpinned.

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

/*--------------------------- OCIObjectMarkDelete ---------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectMarkDelete(/*_ OCIEnv *env, OCIError *err, dvoid *instance _*/);
#else /* ANSI C */
sword OCIObjectMarkDelete(    OCIEnv *env, OCIError *err, dvoid *instance    );
#endif
/*
   NAME: OCIObjectMarkDelete - OCI "delete" an instance given a Pointer 
   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 the instance 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The instance must be standalone.
        - If the instance is a referenceable object, then it must be pinned.
   DESCRIPTION:

        FOR PERSISTENT OBJECTS:
        The object is marked deleted.  The memory of the object is not freed.
        The object is deleted in the server when the object is flushed.

        FOR TRANSIENT OBJECTS:
        The object is marked deleted.  The memory of the object is not freed.

        FOR VALUES: 
        This function frees a value 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. 
 */

/*---------------------------- OCIObjectFlush -------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectFlush(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectFlush(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectFlush - OCI flush 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 flushes a modified persistent object to the server.
        An exclusive lock is obtained implicitly for the object when flushed.

        When the object is written to the server, triggers may be fired.
        Objects can be modified by the triggers at the server.  To keep the  
        objects in the object cache being coherent with the database, the
        clients can free or refresh the objects in the cache. 

        This function will return an error for transient objects and 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. 
 */

/*------------------------ OCIObjectRefresh ---------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectRefresh(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
#else /* ANSI C */
sword OCIObjectRefresh(    OCIEnv *env, OCIError *err, dvoid *object    );
#endif
/*
   NAME: OCIObjectRefresh - OCI refresh 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 refreshes an unmarked object with data retrieved from the
        latest snapshot in the server. An object should be refreshed when the 
        objects in the cache are inconsistent with the objects at 
        the server:
        1) When an object is flushed to the server, triggers can be fired to
           modify more objects in the server.  The same objects (modified by 
           the triggers) in the object cache become obsolete.
        2) When the user issues a SQL or executes a PL/SQL procedure to modify
           any object in the server, the same object in the cache becomes
           obsolete.

        The object that is refreshed will be 'replaced-in-place'. When an
        object is 'replaced-in-place', the top level memory of the object will 
        be reused so that new data can be loaded into the same memory address. 
        The top level memory of the null structre is also reused. Unlike the
        top level memory chunk, the secondary memory chunks may be resized and
        reallocated.  The client should be careful when holding onto a pointer 
        to the secondary memory chunk (e.g. assigning the address of a 
        secondary memory to a local variable), since this pointer can become 
        invalid after the object is refreshed.

        The object state will be modified as followed after being refreshed: 
          - existent : set to appropriate value
          - pinned   : unchanged 
          - allocation duration : unchanged 
          - pin duration : unchanged 
        
        This function is an no-op for transient objects or 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. 
 */

/*---------------------------- OCIObjectCopy --------------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectCopy(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, 
                        dvoid *source, dvoid *null_source,
                        dvoid *target, dvoid *null_target, OCIType *tdo, 
                        OCIDuration duration, ub1 option _*/);
#else /* ANSI C */
sword OCIObjectCopy(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, 
                        dvoid *source, dvoid *null_source,
                        dvoid *target, dvoid *null_target, OCIType *tdo, 
                        OCIDuration duration, ub1 option    );
#endif
/*
   NAME: OCIObjectCopy - OCI copy one instance to another
   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 context handle
        source      (IN) - pointer to the source instance 
        null_source (IN) - pointer to the null structure of the source
        target      (IN) - pointer to the target instance
        null_target (IN) - pointer to the null structure of the target 
        tdo         (IN) - the TDO for both source and target
        duration    (IN) - allocation duration of the target memory
        option      (IN) - specify the copy option:
                        OROOCOSFN - Set Reference to Null. All references
                        in the source will not be copied to the target. The
                        references in the target are set to null. 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - If source or target is referenceable, it must be pinned.
        - The target or the containing instance of the target must be already
          be instantiated (e.g. created by OCIObjectNew()).
        - The source and target instances must be of the same type. If the
          source and target are located in a different databases, then the
          same type must exist in both databases.
   DESCRIPTION:
        This function copies the contents of the 'source' instance to the
        'target' instance. This function performs a deep-copy such that the 
        data that is copied/duplicated include:
        a) all the top level attributes (see the exceptions below)
        b) all the secondary memory (of the source) that is reachable from the
           top level attributes.
        c) the null structure of the instance

        Memory is allocated with the specified allocation duration. 

        Certain data items are not copied: 
        a) If the option OCI_OBJECTCOPY_NOREF is specified, then all references
           in the source are not copied. Instead, the references in the target
           are set to null.
        b) If the attribute is a LOB, then it is set to null.

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

/*---------------------------- OCIObjectGetTypeRef --------------------------*/
#if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
sword OCIObjectGetTypeRef(/*_ OCIEnv *env, OCIError *err, dvoid *instance, 
                              OCIRef *type_ref _*/);
#else /* ANSI C */
sword OCIObjectGetTypeRef(    OCIEnv *env, OCIError *err, dvoid *instance, 
                              OCIRef *type_ref    );
#endif
/*
   NAME: OCIObjectGetTypeRef - get the type reference of a standalone 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 
                         retriev