ori.h

ORACLE访问接口

/* Copyright (c) Oracle Corporation 1994, 1996, 1997, 1998, 1999.  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  

    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