sdk/include/ori.h

/* Copyright (c) 1994, 2006, Oracle. All rights reserved.  */

/*
  NAME
    ORI - OCI navigational interface

  DESCRIPTION

    This section is intended to give a brief introduction to the navigational
    interfaces.  Readers can refer to the documents listed in the section 
    'RELATED DOCUMENTS' for more information. 

    PURPOSE 
       The Oracle Call Interface (OCI) supports navigational access of objects.
       In the navigational paradigm, data is represented as a graph of objects 
       connected by references.  Objects in the graph are reached by following
       the references.

    OBJECT ENVIRONMENT

      The object environment is initialized when the OCI environment handle is
      initialized with the object option.  An object environment contains a
      heap which buffers type instances in memory.  The object environment also
      contains an object cache which keeps track of the objects in the object 
      environment.  Readers can refer to the "Functional Specification for 
      Programmatic Interface" for more information about the object 
      environment. 

    INSTANCE, OBJECT AND VALUE

      An OTS instance is an occurence of a type specified by the Oracle Type 
      System (OTS). This section describes how an OTS instance can be 
      represented in OCI. In OCI, an OTS instance can be classified based on
      the type, the lifetime and referencability (see the figure below):

      1) A persistent object is an instance of an object type. A persistent
         object resides in a row of a table in the server and can exist longer
         than the duration of a session (connection). Persistent objects can be
         identified by object references which contain the object identifiers.
         A persistent object is obtained by pinning its object reference.

      2) A transient object is an instance of an object type. A transient 
         object cannot exist longer than the duration of a session, and it is 
         used to contain temporary computing results. Transient objects can 
         also be identified by references which contain transient object
         identifiers.

      3) A value is an instance of an user-defined type (object type or 
         collection type) or any built-in OTS type.  Unlike objects, values of 
         object types are identified by memory pointers, rather than by 
         references.  

         A value can be standalone or embbeded.  A standalone value is usually
         obtained by issuing a select statement.  OCI also allows the client
         program to select a row of object table into a value by issuing a SQL
         statement.  Thus, a referenceable object (in the database) can be 
         represented as a value (which cannot be identified by a reference).
         A standalone value can also be an out-of-line attribute in an object 
         (e.g varchar, raw) or an out-of-line element in a collection (e.g.
         varchar, raw, object).
      
         An embedded value is phyiscally included in a containing instance.
         An embedded value can be an in-line attribute in an object (e.g.
         number, nested object) or an in-line element in a collection.

         All values are considered to be transient by OCI, e.g. OCI does not
         support automatic flushing a value to the database, and the client has
         to explicitly execute a SQL statement to store a value into the 
         database. For embedded values, they are flushed when their containing
         instance are flushed.


                                OTS instance
                                 |        |  
                                 v        v
                               object    value         (type)
                               |    |
                               v    v
                       persistent  transient           (lifetime)
                  
 
                     persistent obj   transient obj     value  
      ---------------------------------------------------------------
      |              |              |               |  object type, |
      | type         | object type  |  object type  |  built-in,    |
      |              |              |               |  collection   |
      ---------------------------------------------------------------
      | maximum      | until object |  session      | session       |
      | lifetime     | is deleted   |               |               | 
      ---------------------------------------------------------------
      | referencable |    yes       |     yes       |    no         |    
      ---------------------------------------------------------------
      | embeddable   |    no        |     no        |    yes        |    
      ---------------------------------------------------------------

    REFERENCEABLE OBJECT, STANDALONE OBJECT, EMBEDDED OBJECT

       In the reminding of this include file, the following term will be used:
       1) The term 'object' can be generally referred to a persistent object,
          a transient object, a standalone value of object type, or an embedded
          value of object type.
       2) The term 'referenceable object' refers to a persistent object or a 
          transient object.
       3) The term 'standalone object' refers to a persistent object, a
          transient object or a standalone value of object type.
       4) The term 'embedded object' referes to a embbeded value of object 
          type.

    META ATTRIBUTES 

      There is a set of meta-attributes that are defined for standalone 
      objects.  A meta-attribute can be transient or persistent. A 
      transient meta-attribute is applicable to an instance only when it is 
      in memory. A persistent meta-attribute can be applicable to an instance 
      that is in the disk. 

      The set of user visible meta-attributes for persistent objects are:
      1) existent (persistent) : Does the object exist?
      2) nullness (persistent) : Null information of the instance
      3) locked   (persistent) : Is the object locked?
      4) pinned    (transient) : Is the object being accessed by the client?
      5) dirty     (transient) : Has the object been modified?
      6) allocation duration (transient) : see below
      7) pin duration        (transient) : see below

      The set of user visible meta-attributes for transient objects are:
      1) existent  (transient) : Does the object exist?
      2) nullness  (transient) : Null information of the instance 
      3) pinned    (transient) : Is the object being accessed by the client? 
      4) dirty     (transient) : Has the object been modified?
      4) allocation duration (transient) : see below
      5) pin duration        (transient) : see below

      The set of user visible meta-attributes for standalone values of object  
      type or collections are:
      1) allocation duration (transient) : see below
      2) nullness            (transient) : Null information of the instance 
                                           (of an object type)

    NULLNESS OF AN INSTANCE 

      Each standalone object is associated with a null structure which keeps 
      the null information about the object.  A null indicates the absence of 
      data. The null structure itself contains null indicators that represent:
        1) atomic nullness : a null value that pertains to the whole object 
        2) null status of the individual attribute in the object 

      The layout of a null structure in memory resembles that of the object,
      except that the null structure has additional indicators to represent 
      the atomic nullness for each object. 

      An non-existent object is different than an object that is atomically 
      null. A atomically null object is an existing object that has no data. 

    MEMORY LAYOUT OF AN OBJECT

      A standalone object in memory is composed of a top level memory chunk, 
      a null structure and optionally, a number of secondary memory chunks. 
      For a DEPARTMENT object type,

          OBJECT TYPE department
          {
              dep_name      varchar2(20),
              budget        number,
              manager       person,              /o person is an object type o/
              employees     collection of person
          }

      Each instance of DEPARTMENT will has a top level memory chunk which
      contains the top level attributes such as dep_name, budget, manager and
      employees.  The attributes dep_name and employees are themselves pointers
      to the additional memory (the secondary memory chunks). The secondary
      memory is for the out-of-line attribute (e.g. varray).

    CONSISTENCY MODEL

      Each pin operation behaves like a distinct SQL select.  Thus, the object 
      cache does not guarantee consistency for a graph of objects.  In order to
      retrieve a consistent graph of objects, the user has to explicitly start 
      a serializable transaction or a read-only transaction. 

    DURATION
      In OCI, a duration is used to specify 

        1) the length of memory allocation of an instance 
           When each instance is allocated, it is associate with an allocation
           duration.  The memory occupied by the object is freed automatically 
           at the end of its allocation duration. The allocation duration of an
           instance cannot be changed.  

        2) the length of pinning of an object
           When each object is pinned, the client has to give a pin duration 
           which specify the length of time that the object is intended to be
           used.  It is an user error to specify a pin duration longer than an
           allocation duration of the object. An object is completely unpinned 
           at the end of its pin duration (see OCIObjectUnpin()). 

      An OCI program can use the allocation duration and the pin duration to 
      automatically free the memory of the instances:
       1) Transient objects and values are freed at the end of the allocation
          duration.
       2) Persistent objects ARE freed at the end of the allocation duration.
          Persistent objects CAN be freed at the end of the pin duration when
          the objects are completely unpinned. The persistent objects are said
          to be aged out. See OCIObjectUnpin() for more details.

      There are 3 predefined duration: session, transaction, call.  The time 
      spans of these durations are defined based on the programming model 
      presented by OCI. The call duration is mapped to the transaction 
      duration in the client-side environment. See oro.h for the macros defined
      for these 3 durations.

      A pin duration can be promoted. For example, if an object is pinned with
      duration 1, and the object is later pinned with duration 2, the pin 
      routine will try to find a duration that is longer or equal to the 
      length of both duration 1 and duration 2.  The pin duration of the object
      is set to the that duration. The object is automatically unpinned only 
      after both duration 1 and duration 2 are terminated. 

  RELATED DOCUMENTS
    "Functional Specification for Oracle Object RDBMS" 
    "Functional Specification for Programmatic Interfaces" 
    "Functional Specification for the Oracle Type System (OTS)" 

  INSPECTION STATUS 
    Inspection date:
    Inspection status:
    Estimated increasing cost defects per page:
    Rule sets:        

  ACCEPTANCE REVIEW STATUS 
    Review date:   
    Review status:
    Reviewers: 

  PUBLIC FUNCTIONS
    OCIObjectNew - OCI new a standalone instance 
    OCIObjectPin - OCI pin an object by reference
    OCIObjectUnpin - OCI unpin a referenceable object
    OCIObjectPinCountReset - OCI reset the pin count of a referenceable object 
    OCIObjectLock - OCI lock a persistent object
    OCIObjectLockNoWait - OCI lock a persistent object
    OCIObjectMarkUpdate - OCI mark a referenceable object as updated
    OCIObjectUnmark - OCI unmark a dirtied referenceable object 
    OCIObjectUnmarkByRef - OCI unmark a dirtied object by reference 
    OCIObjectFree - OCI free a standalone instance 
    OCIObjectMarkDelete - OCI mark a referenceable object as deleted 
    OCIObjectMarkDeleteByRef - OCI mark a referenceable object as deleted by 
                               giving a reference
    OCIObjectFlush - OCI flush a persistent object
    OCIObjectRefresh - OCI refresh a persistent object 
    OCIObjectCopy - OCI CoPy one object to another
    OCIObjectGetTypeRef - OCI get the Type Reference of a standalone object 
    OCIObjectGetObjectRef - OCI get the Object's Reference 
    OCIObjectGetInd - OCI get Null Structure of an standalone object 
    OCIObjectExists - OCI get the existence of a referenceable object
    OCIObjectGetProperty - get object property
    OCIObjectIsLocked - OCI get the lock status of a referenceable object
    OCIObjectIsDirty - OCI get the dirty status of a referenceable object
    OCIObjectPinTable - OCI get Table object 
    OCIObjectArrayPin - OCI pin array of objects 
    OCIObjectGetPrimayKeyTypeRef - OCI get the Ref for the primary key OID's 
                                   type 
    OCIObjectMakeObjectRef - OCI Create a pk or sys generated REF  

    OCIObjectGetNewOID - OCI Create a new Object ID

    OCICacheFlush - OCI flsuh the modified persistent objects in the cache
    OCICacheRefresh - OCI refresh persistent objects in the cache 
    OCICacheUnpin - OCI unpin referenceable objects in the cache
    OCICacheFree - OCI free all instances in the environment
    OCICacheUnmark - OCI unmark all dirty referenceable objects in the cache 

  PRIVATE FUNCTIONS
    None

  EXAMPLES 

    The following types will be used in the examples in this section: 

    OBJECT TYPE professor
    (
        varchar2  name;
        number    department;
        number    num_of_students; 
    );

    OBJECT TYPE course 
    (
        varchar2   name;
        number     grade; 
    );

    OBJECT TYPE student
    (
        vstring      name;
        number       department;
        ref          advisor;                      /o advisor is a professor o/
        collection   courses;
    );

    EXAMPLE 1

      Here is a set of examples to illustrate the usages of some of the
      orio and oric functions.  

      OCIenv    *env;              /o OCI environment handle o/
      OCIError  *err;              /o OCI error handle o/
      OCISvcCtx *svc;              /o OCI service handle o/

      void   *stu_tbl;            /o pointer to the student table o/
      OCIType *stu_tdo;            /o student type tdo o/

      OCIRef    *stu2_ref;         /o object reference to student object o/
      student   *stu1;             /o pointer to the student object o/
      student   *stu2;             /o pointer to the student object o/
      professor *pro;              /o pointer to the professor object o/

      /o Initialize the OCI environment handle, error handle and service
         handle and login to the database o/ 
      ...

      /o CREATE A PERSISTENT OBJECT o/

      /o get the table object of student o/
      if (OCIObjectPinTable(env, err, svc, "ORACLEU", sizeof("ORACLEU"), 
          "STUDENT_TABLE", sizeof("STUDENT_TABLE"), (OCIRef *)0, 
          OCI_DURATION_NULL, &stu_tbl) != OCI_SUCCESS)
          /o error handling code o/ 

      /o get type object of student o/
      if (OCITypeByName(env, err, svc, "ORACLEU", sizeof("ORACLEU"), 
          "STUDENT", sizeof("STUDENT"), OCI_DURATION_NULL, OCI_TYPEGET_HEADER,
          &stu_tdo) != OCI_SUCCESS)
          /o error handling code o/ 

      /o create a persistent object 'mark' (of type student) o/ 
      if (OCIObjectNew(env, err, svc, OCI_TYPECODE_ADT, stu_tdo, stu_tbl, 
            OCI_DURATION_TRANS, (ub1)FALSE, (void **)&stu1) != OCI_SUCCESS)
          /o error handling code o/

      /o RETRIEVE OBJECTS IN PERSISTENT STORES o/ 

      /o Use OCI to retrieve a reference to student object 'joe'.
       o The retrieved reference is bound to the variable stu2_ref.
       o/ 

      /o pin/retrieve the student "joe" by reference o/ 
      if (OCIObjectPin(env, err, &stu2_ref, (OCIComplexObject *)0, OCI_PIN_ANY,
                  OCI_DURATION_TRANS, OCI_LOCK_X, &stu2) != OCI_SUCCESS)
          /o error handling code o/ 

      /o pin/retrieve the advisor of student "joe" by reference o/ 
      if (OCIObjectPin(env, err, &stu2->advisor, (OCIComplexObject *)0,
          OCI_PIN_ANY, OCI_DURATION_TRANS, OCI_LOCK_X, &pro) != OCI_SUCCESS)
          /o error handling code o/ 

      /o MODIFY OBJECTS o/

      /o initialize the newly created object "mark" o/
      DISCARD OCIStringAssignText(env, err, "mark", sizeof("mark"), 
                                    &stu1->name);
      department = 522;
      DISCARD OCINumberFromInt(err, &department, sizeof(department), 
                                    OCI_NUMBER_UNSIGNED, &stu1->department);

      /o assign advisor to student "mark" o/
      DISCARD OCIRefAssign(env, err, &stu2->advisor, &stu1->advisor);

      /o update student "joe". o/  
      department = 533;
      DISCARD OCINumberFromInt(err, &department, sizeof(department), 
                                    OCI_NUMBER_UNSIGNED, &stu2->department);
      DISCARD OCIObjectMarkUpdate(env, err, stu2);

      /o UNPIN OBJECTS AFTER FINSIHED PROCESSING THEM o/ 

      /o unpin the student object "mark" o/
      if (OCIObjectUnpin(env, err, stu1) != OCI_SUCCESS)
          /o error handling code o/ 

      /o unpin the student object "joe" o/
      if (OCIObjectUnpin(env, err, stu2) != OCI_SUCCESS)
          /o error handling code o/ 

      /o unpin the professor object o/
      if (OCIObjectUnpin(env, err, pro) != OCI_SUCCESS)
          /o error handling code o/ 

      /o unpin the type object o/
      if (OCIObjectUnpin(env, err, stu_tdo) != OCI_SUCCESS)
          /o error handling code o/ 

      /o unpin the table object o/
      if (OCIObjectUnpin(env, err, stu_tbl) != OCI_SUCCESS)
          /o error handling code o/ 

      /o FLUSH MODIFIED OBJECTS BACK TO PERSISTENT STORE o/

      if (OCICacheFlush(env, err, svc, (void *)0, ((OCIRef*)(*)())0, 
                       (OCIRef *)0) != OCI_SUCCESS)
          /o error handling code o/

      /o commit transaction o/

    END OF EXAMPLE 1

  NOTES
    This file has been subsetted to contain only the routines that will
    be in the first release.

  MODIFIED
    dmukhin    06/29/05 - ANSI prototypes; miscellaneous cleanup 
    srseshad   03/12/03 - convert oci public api to ansi
    aahluwal   06/03/02 - bug 2360115
    bpalaval   02/09/01 - Change text to oratext.
    rkasamse   06/21/00 - add ociobjectgetnewoid
    rkasamse   05/24/00 - add OCIObjectSetData
    whe        09/01/99 - 976457:check __cplusplus for C++ code
    smuralid   10/29/98 - add comments for OCIObjectMakeObjectRef              
    mkrishna   08/19/98 - change OCIGetPkTypeRef to OCIObjectGetPrimaryKeyTypeR
    mkrishna   08/10/98 - add OCIObjectMakeObjectRef & OCIObjectGetPkTypeRef
    rkasamse   06/22/98 - add comments for OCIDurationBegin(End)
    pmitra     04/01/98 - OCIObjectLockNoWait added                            
    pmitra     11/05/97 - [573769] OCIObjectArrayPin pos parameter cannot be NU
    cxcheng    07/29/97 - fix compile for short names
    skrishna   07/14/97 - add OCIObjectGetProperty
    skrishna   04/30/97 - OCIObjectFlushRefresh: remove duplicate declaration
    skrishna   04/24/97 - flag unsupported functions
    sthakur    03/20/97 - modify flag argument to OCIObjectFree
    skrishna   03/18/97 - fix ifdef for supporting ansi and k&r proto-types
    cxcheng    02/19/97 - remove short names support
    cxcheng    02/06/97 - take out short name support except with SLSHORTNAME
    sthakur    12/20/96 - fix a typepo in OCIOBjectArrayPin
    jboonleu   11/07/96 - modify comments
    cxcheng    10/28/96 - more beautification changes
    jboonleu   10/24/96 - add flag to OCIObjectFree
    jboonleu   10/22/96 - change interface of OCICacheFlush
    cxcheng    10/18/96 - rename OCIObjectPinArray to OCIObjectArrayPin
    cxcheng    10/14/96 - more renaming of types
    jboonleu   10/09/96 - add new interfaces
    cxcheng    10/09/96 - more lint fixes
    cxcheng    10/08/96 - more lint fixes
    jboonleu   09/27/96 - fix lint errors
    jboonleu   10/07/96 - beautify ori.h after conversion to long names
    cxcheng    10/04/96 - replace short names with long names
    sthakur    08/20/96 - add COR context to OCIObjectPin
    mluong     07/17/96 - add back orioglk, oriogdr, oriogiv, and oriocur.
    jboonleu   07/17/96 - rename refresh option to conherency option 
    jboonleu   07/16/96 - change comment for cache consistency
    jwijaya    07/03/96 - add ANSI prototypes
    jboonleu   06/12/96 - update comment
    jboonleu   05/08/96 -  change description of OCIDurationGetParent
    jboonleu   05/01/96 -  add OROOCOSFN
    skrishna   04/08/96 -  change ori*() to take OCIEnv* and OCIError* instead
                           of oroenv*
    jboonleu   01/04/96 -  interface change
    jboonleu   10/24/95 -  support of variable ref
    jboonleu   02/15/95 -  new interface
    sthakur    01/05/95 -  pass username to origrgc 
    skotsovo   12/07/94 -  update example 
    jwijaya    11/15/94 -  rename ORONSPTAB to ORONSPEXT 
    jwijaya    10/06/94 -  add namespace to oriopnm() 
    jwijaya    10/02/94 -  connection handle -> connection number 
    jboonleu   08/16/94 -  fix lint errors 
    jboonleu   07/20/94 -  change interface of OCICacheFlush 
    tanguyen   07/18/94 -  add oriocpe, change OCIObjectCopy to oriocps
    tcheng     07/15/94 -  add init param maximum_sga_heap_size 
    tcheng     07/13/94 -  change origini to get param string 
    jboonleu   07/05/94 -  change sccs string from sccid to a comment 
    jboonleu   07/01/94 -  Add examples to ORIO* and ORIC* functions 
    tanguyen   06/30/94 -  Fix the ORI_ORACLE ifdef
    skotsovo   06/27/94 -  include all public functions in public functions 
                           list at top of header file
    tcheng     06/27/94 -  modify comments according to new template 
    tanguyen   06/24/94 -  fix comments for OCIObjectCopy 
    tcheng     06/24/94 -  fix comments in origrgc()
    tanguyen   06/21/94 -  fix comments and format 
    tcheng     06/20/94 -  commenting origini/trm/err/rgc/urg() functions
    tanguyen   06/16/94 -  fix descriptions of ref operations 
    tanguyen   06/16/94 -  clarifies refs comparison 
    tanguyen   05/12/94 -  adds more interfaces (OCIObjectMarkUpdate)
    jwijaya    05/10/94 -  fix examples, add origurg, change origcon to origrgc
    tanguyen   05/03/94 -  remove unnecessary 'type' argument from 
                           'OCIObjectCopy'
    tanguyen   03/08/94 -  clarifies comments
    jwijaya    02/16/94 -  more questions
    jwijaya    02/11/94 -  more comments
    jwijaya    02/10/94 -  identify optional arguments
    jwijaya    02/07/94 -  Creation
*/


#ifndef ORATYPES
#include <oratypes.h>
#endif
#ifndef ORO_ORACLE
#include <oro.h>
#endif
#ifndef OCI_ORACLE
#include <oci.h>
#endif
#ifndef ORT_ORACLE
#include <ort.h>
#endif

#ifndef ORI_ORACLE
#define ORI_ORACLE

/*---------------------------------------------------------------------------*/
/*                         SHORT NAMES SUPPORT SECTION                       */
/*---------------------------------------------------------------------------*/

#ifdef SLSHORTNAME

/* the following are short names that are only supported on IBM mainframes
   with the SLSHORTNAME defined.
   With this all subsequent long names will actually be substituted with
   the short names here */

#define OCIDurationBegin                 origbgu
#define OCIDurationEnd                   origedu
#define OCIDurationGetParent             origpdr
#define OCICacheFlushRefresh             oricfrh
#define OCICacheUnpin                    oricunp
#define OCICacheFree                     oricfre
#define OCICacheUnmark                   oricumk
#define OCICacheGetObjects               oricgpr
#define OCICacheRegister                 oricscb
#define OCIObjectUnpin                   oriounp
#define OCIObjectPinCountReset           orioupz
#define OCIObjectLock                    oriolck
#define OCIObjectLockNoWait              oriolnw
#define OCIObjectMarkUpdate              orioupd
#define OCIObjectUnmark                  orioumk
#define OCIObjectUnmarkByRef             orioumr
#define OCIObjectAlwaysLatest            oriomkl
#define OCIObjectNotAlwaysLatest         oriouml
#define OCIObjectMarkDeleteByRef         oriordl
#define OCIObjectMarkDelete              oriopdl
#define OCIObjectFlush                   oriofls
#define OCIObjectFlushRefresh            oriofrh
#define OCIObjectCopy                    oriocpy
#define OCIObjectGetTypeRef              oriogtr
#define OCIObjectGetObjectRef            oriogor
#define OCIObjectGetInd                  oriogns
#define OCIObjectExists                  oriogex
#define OCIObjectGetProperty             oriogpr
#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 ----------------------------------*/
sword OCIObjectNew(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc,
                       OCITypeCode typecode, OCIType *tdo, void  *table, 
                       OCIDuration duration, boolean value, 
                       void  **instance    );
/*
   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 ----------------------------------*/
sword OCIObjectPin(    OCIEnv *env, OCIError *err, OCIRef *object_ref, 
                       OCIComplexObject *corhdl, OCIPinOpt pin_option, 
                       OCIDuration pin_duration, 
                       OCILockOpt lock_option, void  **object    );
/*
   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 -----------------------------*/
sword OCIObjectUnpin(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 -----------------------*/
sword OCIObjectPinCountReset(    OCIEnv *env, OCIError *err, void  *object   );
/*
   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.
   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 ---------------------------------*/
sword OCIObjectLock(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 ------------------------------*/
sword OCIObjectLockNoWait(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 ---------------------------*/
sword OCIObjectMarkUpdate(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 -----------------------------*/
sword OCIObjectUnmark(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 ------------------------*/
sword OCIObjectUnmarkByRef(    OCIEnv *env, OCIError *err, OCIRef *ref    );
/*
   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 ---------------------------------*/
sword OCIObjectFree(    OCIEnv *env, OCIError *err, void  *instance, 
                        ub2 flags   );
/*
   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 --------------------------*/
sword OCIObjectMarkDeleteByRef(    OCIEnv *env, OCIError *err, 
                                   OCIRef *object_ref);
/*
   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 ---------------------------*/
sword OCIObjectMarkDelete(    OCIEnv *env, OCIError *err, void  *instance    );
/*
   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 -------------------------------*/
sword OCIObjectFlush(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 ---------------------------------*/
sword OCIObjectRefresh(    OCIEnv *env, OCIError *err, void  *object    );
/*
   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 --------------------------------*/
sword OCIObjectCopy(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc, 
                        void  *source, void  *null_source,
                        void  *target, void  *null_target, OCIType *tdo, 
                        OCIDuration duration, ub1 option    );
/*
   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 --------------------------*/
sword OCIObjectGetTypeRef(    OCIEnv *env, OCIError *err, void  *instance, 
                              OCIRef *type_ref    );
/*
   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 
                         retrieved by calling OCIErrorGet().
        instance  (IN) - pointer to an standalone instance 
        type_ref (OUT) - reference to the type of the object.  The reference 
                         must already be allocated.
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The instance must be standalone.
        - If the object is referenceable, the specified object must be pinned.
        - The reference must already be allocated.
   DESCRIPTION:
        This function returns a reference to the TDO of a standalone instance. 
   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. 
 */

/*--------------------------- OCIObjectGetObjectRef -------------------------*/
sword OCIObjectGetObjectRef(    OCIEnv *env, OCIError *err, void  *object, 
                                OCIRef *object_ref    );
/*
   NAME: OCIObjectGetObjectRef - OCI get the object reference of an 
                                 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 a persistent object
        object_ref (OUT) - reference of the given object. The reference must 
                           already be allocated.
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified object must be pinned.
        - The reference must already be allocated.
   DESCRIPTION:
        This function returns a reference to the given object.  It returns an 
        error 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. 
 */

/*--------------------------- OCIObjectMakeObjectRef -----------------------*/
sword OCIObjectMakeObjectRef(    OCIEnv *env, OCIError *err, 
                                 const OCISvcCtx *svc, void  * table,
                                 void  **values, ub4 array_len, 
                                 OCIRef *object_ref    );
/*
   NAME: OCIObjectMakeObjectRef - OCI Create an object reference to 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().
        svc         (IN) - the service context
        table       (IN) - A pointer to the table object (must be pinned)
        attrlist    (IN) - A list of values (OCI type values) from which
                           the ref is to be created.
        attrcnt     (IN)  - The length of the attrlist array. 
        object_ref (OUT) - reference of the given object. The reference must 
                           already be allocated. 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified table object must be pinned.
        - The reference must already be allocated.
   DESCRIPTION:
        This function creates a reference given the values that make up the 
        reference and also a pointer to the table object. 
        Based on the table's OID property, whether it is a pk based OID or
        a system generated OID, the function creates a sys-generated REF or
        a pk based REF.
        In case of system generated REFs pass in a OCIRaw which is 16 bytes
        long contatining the sys generated OID.
        In case of PK refs pass in the OCI equivalent for numbers, chars etc..
   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. 
 */

/*--------------------------- OCIObjectGetPrimaryKeyTypeRef --------------- */ 
sword OCIObjectGetPrimaryKeyTypeRef( OCIEnv *env, OCIError *err,
                                     const OCISvcCtx *svc, void  *table, 
                                     OCIRef *type_ref );
/*
   NAME: OCIObjectGetPrimaryKeyTypeRef - OCI get the REF to the pk OID type 
   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)     - the service context 
        table   (IN)     - pointer to the table object
        type_ref   (OUT) - reference of the pk type. The reference must 
                           already be allocated.
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The specified table object must be pinned.
        - The reference must already be allocated.
   DESCRIPTION:
        This function returns a reference to the pk type.  It returns an 
        error for values.  If the table is not a Pk oid table/view, then
        it returns error.
   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. 
 */

/*-------------------------- OCIObjectGetInd --------------------------------*/
sword OCIObjectGetInd(    OCIEnv *env, OCIError *err, void  *instance, 
                          void  **null_struct    );
/*
   NAME: OCIObjectGetInd - OCI get the null structure 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 
                           retrieved by calling OCIErrorGet().
        instance      (IN) - pointer to the instance 
        null_struct (OUT) - null structure 
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The object must be standalone.
        - If the object is referenceable, the specified object must be pinned.
   DESCRIPTION:
        This function returns the null structure of an instance. This function
        will allocate the top level memory of the null structure if it is not
        already allocated. If an null structure cannot be allocated for the 
        instance, then an error is returned. This function only works for 
        ADT or row type instance. 
   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. 
 */

/*------------------------- OCIObjectExists --------------------------------*/
sword OCIObjectExists(OCIEnv *env, OCIError *err, void  *ins, boolean *exist); 
/*
   NAME: OCIObjectExist - OCI checks if the object exists 
   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().
        ins           (IN) - pointer to an instance 
        exist        (OUT) - return TRUE if the object exists
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The object must be standalone.
        - if object is a referenceable, it must be pinned.
   DESCRIPTION:
        This function returns the existence of an instance. If the instance
        is a value, this function always returns TRUE.
   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. 
 */

/*------------------------- OCIObjectGetProperty ---------------------------*/
sword OCIObjectGetProperty(OCIEnv *envh, OCIError *errh, const void  *obj, 
                           OCIObjectPropId propertyId,
                           void  *property, ub4 *size );
/*
   NAME: OCIObjectGetProperty - OCIObject Get Property of given 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().
        obj           (IN) - object whose property is returned
        propertyId    (IN) - id which identifies the desired property
        property     (OUT) - buffer into which the desired property is
                             copied
        size      (IN/OUT) - on input specifies the size of the property buffer
                             passed by caller, on output will contain the 
                             size in bytes of the property returned.
                             This parameter is required for string type 
                             properties only (e.g OCI_OBJECTPROP_SCHEMA,
                             OCI_OBJECTPROP_TABLE). For non-string
                             properties this parameter is ignored since
                             the size is fixed.
   DESCRIPTION:
        This function returns the specified property of the object.
        The desired property is identified by 'propertyId'. The property
        value is copied into 'property' and for string typed properties
        the string size is returned via 'size'. 
        
        Objects are classified as persistent, transient and value
        depending upon the lifetime and referenceability of the object.
        Some of the properties are applicable only to persistent
        objects and some others only apply to persistent and 
        transient objects. An error is returned if the user tries to 
        get a property which in not applicable to the given object. 
        To avoid such an error, the user should first check whether
        the object is persistent or transient or value 
        (OCI_OBJECTPROP_LIFETIME property) and then appropriately
        query for other properties.

        The different property ids and the corresponding type of 
        'property' argument is given below.

          OCI_OBJECTPROP_LIFETIME 
            This identifies whether the given object is a persistent
            object (OCI_OBJECT_PERSISTENT) or a 
            transient object (OCI_OBJECT_TRANSIENT) or a
            value instance (OCI_OBJECT_VALUE).
            'property' argument must be a pointer to a variable of 
            type OCIObjectLifetime.
            
          OCI_OBJECTPROP_SCHEMA
            This returns the schema name of the table in which the 
            object exists. An error is returned if the given object 
            points to a transient instance or a value. If the input 
            buffer is not big enough to hold the schema name an error 
            is returned, the error message will communicate the 
            required size. Upon success, the size of the returned 
            schema name in bytes is returned via 'size'.
            'property' argument must be an array of type text and 'size'
            should be set to size of array in bytes by the caller.

          OCI_OBJECTPROP_TABLE
            This returns the table name in which the object exists. An 
            error is returned if the given object points to a 
            transient instance or a value. If the input buffer is not 
            big enough to hold the table name an error is returned, 
            the error message will communicate the required size. Upon 
            success, the size of the returned table name in bytes is 
            returned via 'size'. 'property' argument must be an array 
            of type text and 'size' should be set to size of array in 
            bytes by the caller.
            
          OCI_OBJECTPROP_PIN_DURATION
            This returns the pin duration of the object.
            An error is returned if the given object points to a value 
            instance. Valid pin durations are: OCI_DURATION_SESSION and
            OCI_DURATION_TRANS.
            'property' argument must be a pointer to a variable of type 
            OCIDuration.
            
          OCI_OBJECTPROP_ALLOC_DURATION
            This returns the allocation duration of the object.
            Valid allocation durations are: OCI_DURATION_SESSION and
            OCI_DURATION_TRANS.
            'property' argument must be a pointer to a variable of type 
            OCIDuration.
            
          OCI_OBJECTPROP_LOCK
            This returns the lock status of the 
            object. The possible lock status is enumerated by OCILockOpt.
            An error is returned if the given object points to a transient
            or value instance.
            'property' argument must be a pointer to a variable of 
            type OCILockOpt.
            Note, the lock status of an object can also be retrieved by
            calling OCIObjectIsLocked().

          OCI_OBJECTPROP_MARKSTATUS
            This returns the status flag which indicates whether the
            object is a new object, updated object and/or deleted object.
            The following macros can be used to test the mark status
            flag:

              OCI_OBJECT_IS_UPDATED(flag)
              OCI_OBJECT_IS_DELETED(flag)
              OCI_OBJECT_IS_NEW(flag)
              OCI_OBJECT_IS_DIRTY(flag)

            An object is dirty if it is a new object or marked deleted or 
            marked updated.
            An error is returned if the given object points to a transient
            or value instance. 'property' argument must be of type 
            OCIObjectMarkStatus.
            
          OCI_OBJECTPROP_VIEW
            This identifies whether the specified object is a view object
            or not. If property value returned is TRUE, it indicates the
            object is a view otherwise it is not.
            'property' argument must be of type boolean.

   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. Possible errors are TBD
 */

/*---------------------------- OCIObjectIsLocked --------------------------*/
sword OCIObjectIsLocked(    OCIEnv *env, OCIError *err, void  *ins,
                              boolean *lock);
/*
   NAME: OCIObjectIsLocked - OCI get the lock status 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
                             retrieved by calling OCIErrorGet().
        ins           (IN) - pointer to an instance
        lock         (OUT) - return value for the lock status.
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The instance must be standalone.
        - If the object is referenceable, the specified object must be pinned.
   DESCRIPTION:
        This function returns the lock status of an instance. If the instance
        is a value, this function always returns FALSE.
   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.
 */

/*------------------------- OCIObjectIsDirty ------------------------------*/
sword OCIObjectIsDirty(    OCIEnv *env, OCIError *err, void  *ins,
                           boolean *dirty);
/*
   NAME: OCIObjectIsDirty - OCI get the dirty status 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
                             retrieved by calling OCIErrorGet().
        ins           (IN) - pointer to an instance
        dirty        (OUT) - return value for the dirty status.
   REQUIRES:
        - a valid OCI environment handle must be given.
        - The instance must be standalone.
        - if instance is an object, the instance must be pinned.
   DESCRIPTION:
        This function returns the dirty status of an instance. If the instance
        is a value, this function always returns FALSE.
   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.
 */

/*--------------------------- OCIObjectPinTable -----------------------------*/
sword OCIObjectPinTable(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc, 
                  const oratext *schema_name, 
                  ub4 s_n_length, const oratext *object_name, ub4 o_n_length, 
                  const OCIRef *scope_obj_ref, OCIDuration pin_duration, 
                  void ** object    );
/*
   NAME: OCIObjectPinTable - OCI get table 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().
        svc                     (IN) - OCI service context handle
        schema_name   (IN, optional) - schema name of the table 
        s_n_length    (IN, optional) - length of the schema name
        object_name   (IN) - name of the table 
        o_n_length    (IN) - length of the table name
        scope_obj_ref (IN, optional) - reference of the scoping object
        pin_duration  (IN) - pin duration. See description in OCIObjectPin(). 
        object       (OUT) - the pinned table object
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        This function pin a table object with the specified pin duration. 
        The client can unpin the object by calling OCIObjectUnpin(). See 
        OCIObjectPin() and OCIObjectUnpin() for more information about pinning
        and unpinning. 
   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. 
 */

/*------------------------- OCIObjectArrayPin -------------------------------*/
sword OCIObjectArrayPin(OCIEnv *env, OCIError *err, OCIRef **ref_array, 
                  ub4 array_size, OCIComplexObject **cor_array,
                  ub4 cor_array_size, OCIPinOpt pin_option, 
                  OCIDuration pin_duration, OCILockOpt lock, 
                  void  **obj_array, ub4 *pos    );
/*
   NAME: OCIObjectArrayPin - ORIO array pin 
   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_array     (IN) - array of references to be pinned 
        array_size    (IN) - number of elements in the array of references 
        pin_option    (IN) - pin option. See OCIObjectPin().
        pin_duration  (IN) - pin duration. See OCIObjectPin(). 
        lock_option   (IN) - lock option. See OCIObjectPin().
        obj_array    (OUT) - If this argument is not NULL, the pinned objects 
                             will be returned in the array. The user must 
                             allocate this array with element type being 
                             'void *'. The size of this array is identical to
                             'array'. 
        pos          (OUT) - If there is an error, this argument will contain
                             the element that is causing the error.  Note that
                             this argument is set to 1 for the first element in
                             the ref_array. 
   REQUIRE:
        - a valid OCI environment handle must be given.
        - If 'obj_array' is not NULL, then it must already be allocated and
             the size of 'obj_array' is 'array_size'. 
   DESCRIPTION:
        This function pin an array of references.  All the pinned objects are 
        retrieved from the database in one network roundtrip.  If the user 
        specifies an output array ('obj_array'), then the address of the 
        pinned objects will be assigned to the elements in the array. See
        OCIObjectPin() for more information about pinning.
   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. 
 */

/*---------------------------------------------------------------------------*/
/*                           HEAP/CACHE OPERATIONS                           */
/*---------------------------------------------------------------------------*/

/*--------------------------- OCICacheFlush ---------------------------------*/
sword OCICacheFlush(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc, 
                  void  *context, OCIRef *(*get)(void  *context, ub1 *last),
                  OCIRef **ref  );
/*
   NAME: OCICacheFlush - OCI flush persistent objects 
   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) [optional] - OCI service context.  If null pointer is
                      specified, then the dirty objects in all connections
                      will be flushed.
        context  (IN) [optional] - specifies an user context that is an 
                      argument to the client callback function 'get'. This 
                      parameter is set to NULL if there is no user context.
        get      (IN) [optional] - an client-defined function which acts an 
                      iterator to retrieve a batch of dirty objects that need 
                      to be flushed. If the function is not NULL, this function
                      will be called to get a reference of a dirty object.  
                      This is repeated until a null reference is returned by 
                      the client function or the parameter 'last' is set to 
                      TRUE. The parameter 'context' is passed to get() 
                      for each invocation of the client function.  This 
                      parameter should be NULL if user callback is not given.
                      If the object that is returned by the client function is
                      not a dirtied persistent object, the object is ignored.
                      All the objects that are returned from the client
                      function must be from newed or pinned the same service 
                      context, otherwise, an error is signalled. Note that the 
                      returned objects are flushed in the order in which they
                      are marked dirty.
        ref     (OUT) [optional] - if there is an error in flushing the 
                      objects, (*ref) will point to the object that
                      is causing the error.  If 'ref' is NULL, then the object 
                      will not be returned.  If '*ref' is NULL, then a 
                      reference will be allocated and set to point to the 
                      object.  If '*ref' is not NULL, then the reference of
                      the object is copied into the given space. If the
                      error is not caused by any of the dirtied object,
                      the given ref is initalized to be a NULL reference
                      (OCIRefIsNull(*ref) is TRUE).
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        This function flushes the modified persistent objects from the 
        environment heap to the server. The objects are flushed in the order 
        that they are marked updated or deleted. 

        See OCIObjectFlush() for more information about flushing.

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

/*--------------------------- OCICacheRefresh -------------------------------*/
sword OCICacheRefresh(OCIEnv *env, OCIError *err, const OCISvcCtx *svc,
                  OCIRefreshOpt option, void  *context,
                  OCIRef *(*get)(void  *context), OCIRef **ref);
/*
   NAME: OCICacheRefresh - OCI ReFreSh persistent objects 
   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) [optional] - OCI service context.  If null pointer is
                      specified, then the persistent objects in all connections
                      will be refreshed. 
        option   (IN) [optional] - if OCI_REFRESH_LOAD is specified, all
                      objects that is loaded within the transaction are
                      refreshed. If the option is OCI_REFERSH_LOAD and the
                      parameter 'get' is not NULL, this function will ignore
                      the parameter. 
        context  (IN) [optional] - specifies an user context that is an 
                      argument to the client callback function 'get'. This 
                      parameter is set to NULL if there is no user context.
        get      (IN) [optional] - an client-defined function which acts an 
                      iterator to retrieve a batch of objects that need to be
                      refreshed. If the function is not NULL, this function
                      will be called to get a reference of an object.  If 
                      the reference is not NULL, then the object will be 
                      refreshed.  These steps are repeated until a null 
                      reference is returned by this function.  The parameter
                      'context' is passed to get() for each invocation of the
                      client function.  This parameter should be NULL if user 
                      callback is not given.
        ref     (OUT) [optional] - if there is an error in refreshing the
                      objects, (*ref) will point to the object that
                      is causing the error.  If 'ref' is NULL, then the object
                      will not be returned.  If '*ref' is NULL, then a
                      reference will be allocated and set to point to the
                      object.  If '*ref' is not NULL, then the reference of
                      the object is copied into the given space. If the
                      error is not caused by any of the object,
                      the given ref is initalized to be a NULL reference
                      (OCIRefIsNull(*ref) is TRUE).
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        This function refreshes all pinned persistent objects. All unpinned 
        persistent objects are freed.  See OCIObjectRefresh() for more 
        information about refreshing.
   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. 
 */

/*---------------------------- OCICacheUnpin --------------------------------*/
sword OCICacheUnpin(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc    );
/*
   NAME: OCICacheUnpin - OCI UNPin objects 
   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) [optional] - OCI service context. If null pointer is
                       specified, then the objects in all connections
                       will be unpinned.
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        If a connection is specified, this function completely unpins the 
        persistent objects in that connection. Otherwise, all persistent 
        objects in the heap are completely unpinned. All transient objects in 
        the heap are also completely unpinned. See OCIObjectUnpin() for more 
        information about unpinning.
   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. 
 */

/*----------------------------- OCICacheFree --------------------------------*/
sword OCICacheFree(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc    ); 
/*
   NAME: OCICacheFree - OCI FREe instances 
   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) [optional] - OCI service context. If null pointer is
                       specified, then the objects in all connections
                       will be freed.
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        If a connection is specified, this function frees the persistent 
        objects, transient objects and values allocated for that connection.  
        Otherwise, all persistent objects, transient objects and values in the 
        heap are freed. Objects are freed regardless of their pin count.  See 
        OCIObjectFree() for more information about freeing an instance.
   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. 
*/

/*---------------------------- OCICacheUnmark -------------------------------*/
sword OCICacheUnmark(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc    );
/*
   NAME: OCICacheUnmark - OCI Unmark all dirty objects
   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) [optional] - OCI service context. If null pointer is
                       specified, then the objects in all connections
                       will be unmarked. 
   REQUIRES:
        - a valid OCI environment handle must be given.
   DESCRIPTION:
        If a connection is specified, this function unmarks all dirty objects 
        in that connection.  Otherwise, all dirty objects in the cache are
        unmarked. See OCIObjectUnmark() for more information about unmarking
        an object.
   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.
 */


sword OCIDurationBegin(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc, 
                           OCIDuration parent, OCIDuration *dur    );
/*
   NAME: OCIDurationBegin - OCI DURATION BEGIN
   PARAMETERS:
        env  (IN/OUT) - OCI environment handle initialized in object mode
                        This should be passed NULL, when cartridge services
                        are to be used.
        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/OUT) - OCI service handle.  
        parent   (IN) - parent for the duration to be started.
        dur     (OUT) - newly created user duration 
   REQUIRES:
        - a valid OCI environment handle must be given for non-cartridge
          services.
        - For cartridge services, NULL should be given for environment handle
        - A valid service handle must be given in all cases.
   DESCRIPTION:
        This function starts a new user duration.  A user can have multiple
        active user durations simultaneously. The user durations do not have
        to be nested.
 
        The object subsystem predefines 3 durations :
          1) session     - memory allocated with session duration comes from
                           the UGA heap (OCI_DURATION_SESSION). A session 
                           duration terminates at the end of the user session.
          2) transaction - memory allocated with transaction duration comes
                           from the UGA heap (OCI_DURATION_TRANS). A trans-
                           action duration terminates at the end of the user
                           transaction.
          3) call        - memory allocated with call duration comes from PGA
                           heap (OCI_DURATION_CALL). A call duration terminates
                           at the end of the user call.
 
        Each user duration has a parent duration.  A parent duration can be a
        predefined duration or another user duration.  The relationship between
        a user duration and its parent duration (child duration) are:
 
         1) An user duration is nested within the parent duration. When its
             parent duration terminates, the user duration will also terminate.
         2) The memory allocated with an user duration comes from the heap of
             its parent duration. For example, if the parent duration of an
             user duration is call, then the memory allocated with the user
             duration will also come from the PGA heap.

        This function can be used as both part of cartridge services as well 
        as without cartridge services.
        The difference in the function in the case of cartridge and 
        non-cartridge services is:
                In case of cartridge services, as descibed above a new user
        duration is created as a child of the "parent" duration.
                But when used for non-cartridge purposes, when a pre-defined
        duration is passed in as parent, it is mapped to the cache duration
        for that connection (which is created if not already present) and 
        the new user duration will be child of the cache duration.

   RETURNS:
        if environment handle and service handle is null or if error 
        handle is null return OCI_INVALID_HANDLE.
        if operation suceeds, return OCI_SUCCESS.
        if operation fails, return OCI_ERROR.
 */


sword OCIDurationEnd(    OCIEnv *env, OCIError *err, const OCISvcCtx *svc, 
                         OCIDuration duration    );
/*
   NAME: OCIDurationEnd - OCI DURATION END
   PARAMETERS:
        env  (IN/OUT) - OCI environment handle initialized in object mode
                        This should be passed NULL, when cartridge services
                        are to be used.
        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/OUT) - OCI service handle.  
        dur     (OUT) - a previously created user duration using 
                        OCIDurationBegin()
   REQUIRES:
        - a valid OCI environment handle must be given for non-cartridge
          services.
        - For cartridge services, NULL should be given for environment handle
        - A valid service handle must be given in all cases.
   DESCRIPTION:
        This function terminates a user duration.  All memory allocated for
        this duration is freed.

        This function can be used as both part of cartridge services as well 
        as without cartridge services.  In both cased, the heap duration
        is freed and all the allocated memory for that duration is freed.
        The difference in the function in the case of cartridge and 
        non-cartridge services is:
                In case of non-cartridge services, if the duration is pre-
        defined, the associated cache duration (see OCIDurationBegin())
        is also terminated and the following is done.
          1) The child durations are terminated.
          2) All objects pinned for this duration are unpinned.
          3) All instances allocated for this duration are freed.

                In case of cartridge services, only the heap duration is
        freed.  All the context entries allocated for that duration are 
        freed from the context hash table..

   RETURNS:
        if environment handle and service handle is null or if error 
        handle is null return OCI_INVALID_HANDLE.
        if operation suceeds, return OCI_SUCCESS.
        if operation fails, return OCI_ERROR.
 */

/******************************************************************************
**          DO  NOT  USE  THE  FUNCTIONS  BELOW!                             **
**          UNSUPPORTED INTERFACE                                            **
**          WILL BE REMOVED/CHANGED IN A FUTURE RELEASE                      **
******************************************************************************/

sword OCIDurationGetParent(    OCIEnv *env, OCIError *err, 
                               OCIDuration duration, OCIDuration *parent    );

sword OCIObjectAlwaysLatest(    OCIEnv *env, OCIError *err, void  *object    );

sword OCIObjectNotAlwaysLatest(    OCIEnv *env, OCIError *err, 
                                   void  *object    );

sword OCIObjectFlushRefresh(    OCIEnv *env, OCIError *err, void  *object);

sword OCIObjectIsLoaded(    OCIEnv *env, OCIError *err, void  *ins, 
                              boolean *load);

sword OCIObjectIsDirtied(    OCIEnv *env, OCIError *err, void  *ins,
                              boolean *dirty);

sword OCICacheGetObjects(       OCIEnv *env, OCIError *err,
                                const OCISvcCtx *svc,
                                OCIObjectProperty property,
                                void  *client_context,
                                void (*client_callback)(
                                    void  *client_context,
                                    void  *object  ));

sword OCICacheRegister(      OCIEnv *env, OCIError *err,
                             OCIObjectEvent event,
                             void  *client_context,
                             void (*client_callback)(
                                    void  *client_context,
                                    OCIObjectEvent event,
                                    void  *object));

sword OCICacheFlushRefresh(    OCIEnv *env, OCIError *err, 
                               const OCISvcCtx *svc, void  *context,
                               OCIRef *(*get)(void  *context, ub1 *last),
                               OCIRef **ref    );

sword OCIObjectSetData(OCIEnv *env, OCIError *err, void  *obj_hdr, 
        void  *data);

sword OCIObjectGetNewOID(OCIEnv *env, OCIError *err, OCISvcCtx *svc, 
        ub1 *oid);


#endif /* ORI_ORACLE */