| TerraLib 4.1

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files
- Examples

- File List
- File Members

E:/Projetos_Primeiro_Semestre_2012/TerraView/terralib/src/terralib/drivers/Oracle/OCI/include/ori.h
Go to the documentation of this file.

    00001 /* Copyright (c) 1994, 2003, Oracle Corporation.  All rights reserved.  */
    00002
    00003 /*
    00004   NAME
    00005     ORI - OCI navigational interface
    00006
    00007   DESCRIPTION
    00008
    00009     This section is intended to give a brief introduction to the navigational
    00010     interfaces.  Readers can refer to the documents listed in the section
    00011     'RELATED DOCUMENTS' for more information.
    00012
    00013     PURPOSE
    00014        The Oracle Call Interface (OCI) supports navigational access of objects.
    00015        In the navigational paradigm, data is represented as a graph of objects
    00016        connected by references.  Objects in the graph are reached by following
    00017        the references.
    00018
    00019     OBJECT ENVIRONMENT
    00020
    00021       The object environment is initialized when the OCI environment handle is
    00022       initialized with the object option.  An object environment contains a
    00023       heap which buffers type instances in memory.  The object environment also
    00024       contains an object cache which keeps track of the objects in the object
    00025       environment.  Readers can refer to the "Functional Specification for
    00026       Programmatic Interface" for more information about the object
    00027       environment.
    00028
    00029     INSTANCE, OBJECT AND VALUE
    00030
    00031       An OTS instance is an occurence of a type specified by the Oracle Type
    00032       System (OTS). This section describes how an OTS instance can be
    00033       represented in OCI. In OCI, an OTS instance can be classified based on
    00034       the type, the lifetime and referencability (see the figure below):
    00035
    00036       1) A persistent object is an instance of an object type. A persistent
    00037          object resides in a row of a table in the server and can exist longer
    00038          than the duration of a session (connection). Persistent objects can be
    00039          identified by object references which contain the object identifiers.
    00040          A persistent object is obtained by pinning its object reference.
    00041
    00042       2) A transient object is an instance of an object type. A transient
    00043          object cannot exist longer than the duration of a session, and it is
    00044          used to contain temporary computing results. Transient objects can
    00045          also be identified by references which contain transient object
    00046          identifiers.
    00047
    00048       3) A value is an instance of an user-defined type (object type or
    00049          collection type) or any built-in OTS type.  Unlike objects, values of
    00050          object types are identified by memory pointers, rather than by
    00051          references.
    00052
    00053          A value can be standalone or embbeded.  A standalone value is usually
    00054          obtained by issuing a select statement.  OCI also allows the client
    00055          program to select a row of object table into a value by issuing a SQL
    00056          statement.  Thus, a referenceable object (in the database) can be
    00057          represented as a value (which cannot be identified by a reference).
    00058          A standalone value can also be an out-of-line attribute in an object
    00059          (e.g varchar, raw) or an out-of-line element in a collection (e.g.
    00060          varchar, raw, object).
    00061
    00062          An embedded value is phyiscally included in a containing instance.
    00063          An embedded value can be an in-line attribute in an object (e.g.
    00064          number, nested object) or an in-line element in a collection.
    00065
    00066          All values are considered to be transient by OCI, e.g. OCI does not
    00067          support automatic flushing a value to the database, and the client has
    00068          to explicitly execute a SQL statement to store a value into the
    00069          database. For embedded values, they are flushed when their containing
    00070          instance are flushed.
    00071
    00072
    00073                                 OTS instance
    00074                                  |        |
    00075                                  v        v
    00076                                object    value         (type)
    00077                                |    |
    00078                                v    v
    00079                        persistent  transient           (lifetime)
    00080
    00081
    00082                      persistent obj   transient obj     value
    00083       ---------------------------------------------------------------
    00084       |              |              |               |  object type, |
    00085       | type         | object type  |  object type  |  built-in,    |
    00086       |              |              |               |  collection   |
    00087       ---------------------------------------------------------------
    00088       | maximum      | until object |  session      | session       |
    00089       | lifetime     | is deleted   |               |               |
    00090       ---------------------------------------------------------------
    00091       | referencable |    yes       |     yes       |    no         |
    00092       ---------------------------------------------------------------
    00093       | embeddable   |    no        |     no        |    yes        |
    00094       ---------------------------------------------------------------
    00095
    00096     REFERENCEABLE OBJECT, STANDALONE OBJECT, EMBEDDED OBJECT
    00097
    00098        In the reminding of this include file, the following term will be used:
    00099        1) The term 'object' can be generally referred to a persistent object,
    00100           a transient object, a standalone value of object type, or an embedded
    00101           value of object type.
    00102        2) The term 'referenceable object' refers to a persistent object or a
    00103           transient object.
    00104        3) The term 'standalone object' refers to a persistent object, a
    00105           transient object or a standalone value of object type.
    00106        4) The term 'embedded object' referes to a embbeded value of object
    00107           type.
    00108
    00109     META ATTRIBUTES
    00110
    00111       There is a set of meta-attributes that are defined for standalone
    00112       objects.  A meta-attribute can be transient or persistent. A
    00113       transient meta-attribute is applicable to an instance only when it is
    00114       in memory. A persistent meta-attribute can be applicable to an instance
    00115       that is in the disk.
    00116
    00117       The set of user visible meta-attributes for persistent objects are:
    00118       1) existent (persistent) : Does the object exist?
    00119       2) nullness (persistent) : Null information of the instance
    00120       3) locked   (persistent) : Is the object locked?
    00121       4) pinned    (transient) : Is the object being accessed by the client?
    00122       5) dirty     (transient) : Has the object been modified?
    00123       6) allocation duration (transient) : see below
    00124       7) pin duration        (transient) : see below
    00125
    00126       The set of user visible meta-attributes for transient objects are:
    00127       1) existent  (transient) : Does the object exist?
    00128       2) nullness  (transient) : Null information of the instance
    00129       3) pinned    (transient) : Is the object being accessed by the client?
    00130       4) dirty     (transient) : Has the object been modified?
    00131       4) allocation duration (transient) : see below
    00132       5) pin duration        (transient) : see below
    00133
    00134       The set of user visible meta-attributes for standalone values of object
    00135       type or collections are:
    00136       1) allocation duration (transient) : see below
    00137       2) nullness            (transient) : Null information of the instance
    00138                                            (of an object type)
    00139
    00140     NULLNESS OF AN INSTANCE
    00141
    00142       Each standalone object is associated with a null structure which keeps
    00143       the null information about the object.  A null indicates the absence of
    00144       data. The null structure itself contains null indicators that represent:
    00145         1) atomic nullness : a null value that pertains to the whole object
    00146         2) null status of the individual attribute in the object
    00147
    00148       The layout of a null structure in memory resembles that of the object,
    00149       except that the null structure has additional indicators to represent
    00150       the atomic nullness for each object.
    00151
    00152       An non-existent object is different than an object that is atomically
    00153       null. A atomically null object is an existing object that has no data.
    00154
    00155     MEMORY LAYOUT OF AN OBJECT
    00156
    00157       A standalone object in memory is composed of a top level memory chunk,
    00158       a null structure and optionally, a number of secondary memory chunks.
    00159       For a DEPARTMENT object type,
    00160
    00161           OBJECT TYPE department
    00162           {
    00163               dep_name      varchar2(20),
    00164               budget        number,
    00165               manager       person,              /o person is an object type o/
    00166               employees     collection of person
    00167           }
    00168
    00169       Each instance of DEPARTMENT will has a top level memory chunk which
    00170       contains the top level attributes such as dep_name, budget, manager and
    00171       employees.  The attributes dep_name and employees are themselves pointers
    00172       to the additional memory (the secondary memory chunks). The secondary
    00173       memory is for the out-of-line attribute (e.g. varray).
    00174
    00175     CONSISTENCY MODEL
    00176
    00177       Each pin operation behaves like a distinct SQL select.  Thus, the object
    00178       cache does not guarantee consistency for a graph of objects.  In order to
    00179       retrieve a consistent graph of objects, the user has to explicitly start
    00180       a serializable transaction or a read-only transaction.
    00181
    00182     DURATION
    00183       In OCI, a duration is used to specify
    00184
    00185         1) the length of memory allocation of an instance
    00186            When each instance is allocated, it is associate with an allocation
    00187            duration.  The memory occupied by the object is freed automatically
    00188            at the end of its allocation duration. The allocation duration of an
    00189            instance cannot be changed.
    00190
    00191         2) the length of pinning of an object
    00192            When each object is pinned, the client has to give a pin duration
    00193            which specify the length of time that the object is intended to be
    00194            used.  It is an user error to specify a pin duration longer than an
    00195            allocation duration of the object. An object is completely unpinned
    00196            at the end of its pin duration (see OCIObjectUnpin()).
    00197
    00198       An OCI program can use the allocation duration and the pin duration to
    00199       automatically free the memory of the instances:
    00200        1) Transient objects and values are freed at the end of the allocation
    00201           duration.
    00202        2) Persistent objects ARE freed at the end of the allocation duration.
    00203           Persistent objects CAN be freed at the end of the pin duration when
    00204           the objects are completely unpinned. The persistent objects are said
    00205           to be aged out. See OCIObjectUnpin() for more details.
    00206
    00207       There are 3 predefined duration: session, transaction, call.  The time
    00208       spans of these durations are defined based on the programming model
    00209       presented by OCI. The call duration is mapped to the transaction
    00210       duration in the client-side environment. See oro.h for the macros defined
    00211       for these 3 durations.
    00212
    00213       A pin duration can be promoted. For example, if an object is pinned with
    00214       duration 1, and the object is later pinned with duration 2, the pin
    00215       routine will try to find a duration that is longer or equal to the
    00216       length of both duration 1 and duration 2.  The pin duration of the object
    00217       is set to the that duration. The object is automatically unpinned only
    00218       after both duration 1 and duration 2 are terminated.
    00219
    00220   RELATED DOCUMENTS
    00221     "Functional Specification for Oracle Object RDBMS"
    00222     "Functional Specification for Programmatic Interfaces"
    00223     "Functional Specification for the Oracle Type System (OTS)"
    00224
    00225   INSPECTION STATUS
    00226     Inspection date:
    00227     Inspection status:
    00228     Estimated increasing cost defects per page:
    00229     Rule sets:
    00230
    00231   ACCEPTANCE REVIEW STATUS
    00232     Review date:
    00233     Review status:
    00234     Reviewers:
    00235
    00236   PUBLIC FUNCTIONS
    00237     OCIObjectNew - OCI new a standalone instance
    00238     OCIObjectPin - OCI pin an object by reference
    00239     OCIObjectUnpin - OCI unpin a referenceable object
    00240     OCIObjectPinCountReset - OCI reset the pin count of a referenceable object
    00241     OCIObjectLock - OCI lock a persistent object
    00242     OCIObjectLockNoWait - OCI lock a persistent object
    00243     OCIObjectMarkUpdate - OCI mark a referenceable object as updated
    00244     OCIObjectUnmark - OCI unmark a dirtied referenceable object
    00245     OCIObjectUnmarkByRef - OCI unmark a dirtied object by reference
    00246     OCIObjectFree - OCI free a standalone instance
    00247     OCIObjectMarkDelete - OCI mark a referenceable object as deleted
    00248     OCIObjectMarkDeleteByRef - OCI mark a referenceable object as deleted by
    00249                                giving a reference
    00250     OCIObjectFlush - OCI flush a persistent object
    00251     OCIObjectRefresh - OCI refresh a persistent object
    00252     OCIObjectCopy - OCI CoPy one object to another
    00253     OCIObjectGetTypeRef - OCI get the Type Reference of a standalone object
    00254     OCIObjectGetObjectRef - OCI get the Object's Reference
    00255     OCIObjectGetInd - OCI get Null Structure of an standalone object
    00256     OCIObjectExists - OCI get the existence of a referenceable object
    00257     OCIObjectGetProperty - get object property
    00258     OCIObjectIsLocked - OCI get the lock status of a referenceable object
    00259     OCIObjectIsDirty - OCI get the dirty status of a referenceable object
    00260     OCIObjectPinTable - OCI get Table object
    00261     OCIObjectArrayPin - OCI pin array of objects
    00262     OCIObjectGetPrimayKeyTypeRef - OCI get the Ref for the primary key OID's
    00263                                    type
    00264     OCIObjectMakeObjectRef - OCI Create a pk or sys generated REF
    00265
    00266     OCIObjectGetNewOID - OCI Create a new Object ID
    00267
    00268     OCICacheFlush - OCI flsuh the modified persistent objects in the cache
    00269     OCICacheRefresh - OCI refresh persistent objects in the cache
    00270     OCICacheUnpin - OCI unpin referenceable objects in the cache
    00271     OCICacheFree - OCI free all instances in the environment
    00272     OCICacheUnmark - OCI unmark all dirty referenceable objects in the cache
    00273
    00274   PRIVATE FUNCTIONS
    00275     None
    00276
    00277   EXAMPLES
    00278
    00279     The following types will be used in the examples in this section:
    00280
    00281     OBJECT TYPE professor
    00282     (
    00283         varchar2  name;
    00284         number    department;
    00285         number    num_of_students;
    00286     );
    00287
    00288     OBJECT TYPE course
    00289     (
    00290         varchar2   name;
    00291         number     grade;
    00292     );
    00293
    00294     OBJECT TYPE student
    00295     (
    00296         vstring      name;
    00297         number       department;
    00298         ref          advisor;                      /o advisor is a professor o/
    00299         collection   courses;
    00300     );
    00301
    00302     EXAMPLE 1
    00303
    00304       Here is a set of examples to illustrate the usages of some of the
    00305       orio and oric functions.
    00306
    00307       OCIenv    *env;              /o OCI environment handle o/
    00308       OCIError  *err;              /o OCI error handle o/
    00309       OCISvcCtx *svc;              /o OCI service handle o/
    00310
    00311       dvoid   *stu_tbl;            /o pointer to the student table o/
    00312       OCIType *stu_tdo;            /o student type tdo o/
    00313
    00314       OCIRef    *stu2_ref;         /o object reference to student object o/
    00315       student   *stu1;             /o pointer to the student object o/
    00316       student   *stu2;             /o pointer to the student object o/
    00317       professor *pro;              /o pointer to the professor object o/
    00318
    00319       /o Initialize the OCI environment handle, error handle and service
    00320          handle and login to the database o/
    00321       ...
    00322
    00323       /o CREATE A PERSISTENT OBJECT o/
    00324
    00325       /o get the table object of student o/
    00326       if (OCIObjectPinTable(env, err, svc, "ORACLEU", sizeof("ORACLEU"),
    00327           "STUDENT_TABLE", sizeof("STUDENT_TABLE"), (OCIRef *)0,
    00328           OCI_DURATION_NULL, &stu_tbl) != OCI_SUCCESS)
    00329           /o error handling code o/
    00330
    00331       /o get type object of student o/
    00332       if (OCITypeByName(env, err, svc, "ORACLEU", sizeof("ORACLEU"),
    00333           "STUDENT", sizeof("STUDENT"), OCI_DURATION_NULL, OCI_TYPEGET_HEADER,
    00334           &stu_tdo) != OCI_SUCCESS)
    00335           /o error handling code o/
    00336
    00337       /o create a persistent object 'mark' (of type student) o/
    00338       if (OCIObjectNew(env, err, svc, OCI_TYPECODE_ADT, stu_tdo, stu_tbl,
    00339             OCI_DURATION_TRANS, (ub1)FALSE, (dvoid **)&stu1) != OCI_SUCCESS)
    00340           /o error handling code o/
    00341
    00342       /o RETRIEVE OBJECTS IN PERSISTENT STORES o/
    00343
    00344       /o Use OCI to retrieve a reference to student object 'joe'.
    00345        o The retrieved reference is bound to the variable stu2_ref.
    00346        o/
    00347
    00348       /o pin/retrieve the student "joe" by reference o/
    00349       if (OCIObjectPin(env, err, &stu2_ref, (OCIComplexObject *)0, OCI_PIN_ANY,
    00350                   OCI_DURATION_TRANS, OCI_LOCK_X, &stu2) != OCI_SUCCESS)
    00351           /o error handling code o/
    00352
    00353       /o pin/retrieve the advisor of student "joe" by reference o/
    00354       if (OCIObjectPin(env, err, &stu2->advisor, (OCIComplexObject *)0,
    00355           OCI_PIN_ANY, OCI_DURATION_TRANS, OCI_LOCK_X, &pro) != OCI_SUCCESS)
    00356           /o error handling code o/
    00357
    00358       /o MODIFY OBJECTS o/
    00359
    00360       /o initialize the newly created object "mark" o/
    00361       DISCARD OCIStringAssignText(env, err, "mark", sizeof("mark"),
    00362                                     &stu1->name);
    00363       department = 522;
    00364       DISCARD OCINumberFromInt(err, &department, sizeof(department),
    00365                                     OCI_NUMBER_UNSIGNED, &stu1->department);
    00366
    00367       /o assign advisor to student "mark" o/
    00368       DISCARD OCIRefAssign(env, err, &stu2->advisor, &stu1->advisor);
    00369
    00370       /o update student "joe". o/
    00371       department = 533;
    00372       DISCARD OCINumberFromInt(err, &department, sizeof(department),
    00373                                     OCI_NUMBER_UNSIGNED, &stu2->department);
    00374       DISCARD OCIObjectMarkUpdate(env, err, stu2);
    00375
    00376       /o UNPIN OBJECTS AFTER FINSIHED PROCESSING THEM o/
    00377
    00378       /o unpin the student object "mark" o/
    00379       if (OCIObjectUnpin(env, err, stu1) != OCI_SUCCESS)
    00380           /o error handling code o/
    00381
    00382       /o unpin the student object "joe" o/
    00383       if (OCIObjectUnpin(env, err, stu2) != OCI_SUCCESS)
    00384           /o error handling code o/
    00385
    00386       /o unpin the professor object o/
    00387       if (OCIObjectUnpin(env, err, pro) != OCI_SUCCESS)
    00388           /o error handling code o/
    00389
    00390       /o unpin the type object o/
    00391       if (OCIObjectUnpin(env, err, stu_tdo) != OCI_SUCCESS)
    00392           /o error handling code o/
    00393
    00394       /o unpin the table object o/
    00395       if (OCIObjectUnpin(env, err, stu_tbl) != OCI_SUCCESS)
    00396           /o error handling code o/
    00397
    00398       /o FLUSH MODIFIED OBJECTS BACK TO PERSISTENT STORE o/
    00399
    00400       if (OCICacheFlush(env, err, svc, (dvoid *)0, ((OCIRef*)(*)())0,
    00401                        (OCIRef *)0) != OCI_SUCCESS)
    00402           /o error handling code o/
    00403
    00404       /o commit transaction o/
    00405
    00406     END OF EXAMPLE 1
    00407
    00408   NOTES
    00409     This file has been subsetted to contain only the routines that will
    00410     be in the first release.
    00411
    00412   MODIFIED
    00413     srseshad   03/12/03 - convert oci public api to ansi
    00414     aahluwal   06/03/02 - bug 2360115
    00415     bpalaval   02/09/01 - Change text to oratext.
    00416     rkasamse   06/21/00 - add ociobjectgetnewoid
    00417     rkasamse   05/24/00 - add OCIObjectSetData
    00418     whe        09/01/99 - 976457:check __cplusplus for C++ code
    00419     smuralid   10/29/98 - add comments for OCIObjectMakeObjectRef
    00420     mkrishna   08/19/98 - change OCIGetPkTypeRef to OCIObjectGetPrimaryKeyTypeR
    00421     mkrishna   08/10/98 - add OCIObjectMakeObjectRef & OCIObjectGetPkTypeRef
    00422     rkasamse   06/22/98 - add comments for OCIDurationBegin(End)
    00423     pmitra     04/01/98 - OCIObjectLockNoWait added
    00424     pmitra     11/05/97 - [573769] OCIObjectArrayPin pos parameter cannot be NU
    00425     cxcheng    07/29/97 - fix compile for short names
    00426     skrishna   07/14/97 - add OCIObjectGetProperty
    00427     skrishna   04/30/97 - OCIObjectFlushRefresh: remove duplicate declaration
    00428     skrishna   04/24/97 - flag unsupported functions
    00429     sthakur    03/20/97 - modify flag argument to OCIObjectFree
    00430     skrishna   03/18/97 - fix ifdef for supporting ansi and k&r proto-types
    00431     cxcheng    02/19/97 - remove short names support
    00432     cxcheng    02/06/97 - take out short name support except with SLSHORTNAME
    00433     sthakur    12/20/96 - fix a typepo in OCIOBjectArrayPin
    00434     jboonleu   11/07/96 - modify comments
    00435     cxcheng    10/28/96 - more beautification changes
    00436     jboonleu   10/24/96 - add flag to OCIObjectFree
    00437     jboonleu   10/22/96 - change interface of OCICacheFlush
    00438     cxcheng    10/18/96 - rename OCIObjectPinArray to OCIObjectArrayPin
    00439     cxcheng    10/14/96 - more renaming of types
    00440     jboonleu   10/09/96 - add new interfaces
    00441     cxcheng    10/09/96 - more lint fixes
    00442     cxcheng    10/08/96 - more lint fixes
    00443     jboonleu   09/27/96 - fix lint errors
    00444     jboonleu   10/07/96 - beautify ori.h after conversion to long names
    00445     cxcheng    10/04/96 - replace short names with long names
    00446     sthakur    08/20/96 - add COR context to OCIObjectPin
    00447     mluong     07/17/96 - add back orioglk, oriogdr, oriogiv, and oriocur.
    00448     jboonleu   07/17/96 - rename refresh option to conherency option
    00449     jboonleu   07/16/96 - change comment for cache consistency
    00450     jwijaya    07/03/96 - add ANSI prototypes
    00451     jboonleu   06/12/96 - update comment
    00452     jboonleu   05/08/96 -  change description of OCIDurationGetParent
    00453     jboonleu   05/01/96 -  add OROOCOSFN
    00454     skrishna   04/08/96 -  change ori*() to take OCIEnv* and OCIError* instead
    00455                            of oroenv*
    00456     jboonleu   01/04/96 -  interface change
    00457     jboonleu   10/24/95 -  support of variable ref
    00458     jboonleu   02/15/95 -  new interface
    00459     sthakur    01/05/95 -  pass username to origrgc
    00460     skotsovo   12/07/94 -  update example
    00461     jwijaya    11/15/94 -  rename ORONSPTAB to ORONSPEXT
    00462     jwijaya    10/06/94 -  add namespace to oriopnm()
    00463     jwijaya    10/02/94 -  connection handle -> connection number
    00464     jboonleu   08/16/94 -  fix lint errors
    00465     jboonleu   07/20/94 -  change interface of OCICacheFlush
    00466     tanguyen   07/18/94 -  add oriocpe, change OCIObjectCopy to oriocps
    00467     tcheng     07/15/94 -  add init param maximum_sga_heap_size
    00468     tcheng     07/13/94 -  change origini to get param string
    00469     jboonleu   07/05/94 -  change sccs string from sccid to a comment
    00470     jboonleu   07/01/94 -  Add examples to ORIO* and ORIC* functions
    00471     tanguyen   06/30/94 -  Fix the ORI_ORACLE ifdef
    00472     skotsovo   06/27/94 -  include all public functions in public functions
    00473                            list at top of header file
    00474     tcheng     06/27/94 -  modify comments according to new template
    00475     tanguyen   06/24/94 -  fix comments for OCIObjectCopy
    00476     tcheng     06/24/94 -  fix comments in origrgc()
    00477     tanguyen   06/21/94 -  fix comments and format
    00478     tcheng     06/20/94 -  commenting origini/trm/err/rgc/urg() functions
    00479     tanguyen   06/16/94 -  fix descriptions of ref operations
    00480     tanguyen   06/16/94 -  clarifies refs comparison
    00481     tanguyen   05/12/94 -  adds more interfaces (OCIObjectMarkUpdate)
    00482     jwijaya    05/10/94 -  fix examples, add origurg, change origcon to origrgc
    00483     tanguyen   05/03/94 -  remove unnecessary 'type' argument from
    00484                            'OCIObjectCopy'
    00485     tanguyen   03/08/94 -  clarifies comments
    00486     jwijaya    02/16/94 -  more questions
    00487     jwijaya    02/11/94 -  more comments
    00488     jwijaya    02/10/94 -  identify optional arguments
    00489     jwijaya    02/07/94 -  Creation
    00490 */
    00491
    00492
    00493 #ifndef ORATYPES
    00494 #include <oratypes.h>
    00495 #endif
    00496 #ifndef ORO_ORACLE
    00497 #include <oro.h>
    00498 #endif
    00499 #ifndef OCI_ORACLE
    00500 #include <oci.h>
    00501 #endif
    00502 #ifndef ORT_ORACLE
    00503 #include <ort.h>
    00504 #endif
    00505
    00506 #ifndef ORI_ORACLE
    00507 #define ORI_ORACLE
    00508
    00509 /*---------------------------------------------------------------------------*/
    00510 /*                         SHORT NAMES SUPPORT SECTION                       */
    00511 /*---------------------------------------------------------------------------*/
    00512
    00513 #ifdef SLSHORTNAME
    00514
    00515 /* the following are short names that are only supported on IBM mainframes
    00516    with the SLSHORTNAME defined.
    00517    With this all subsequent long names will actually be substituted with
    00518    the short names here */
    00519
    00520 #define OCIDurationBegin                 origbgu
    00521 #define OCIDurationEnd                   origedu
    00522 #define OCIDurationGetParent             origpdr
    00523 #define OCICacheFlushRefresh             oricfrh
    00524 #define OCICacheUnpin                    oricunp
    00525 #define OCICacheFree                     oricfre
    00526 #define OCICacheUnmark                   oricumk
    00527 #define OCICacheGetObjects               oricgpr
    00528 #define OCICacheRegister                 oricscb
    00529 #define OCIObjectUnpin                   oriounp
    00530 #define OCIObjectPinCountReset           orioupz
    00531 #define OCIObjectLock                    oriolck
    00532 #define OCIObjectLockNoWait              oriolnw
    00533 #define OCIObjectMarkUpdate              orioupd
    00534 #define OCIObjectUnmark                  orioumk
    00535 #define OCIObjectUnmarkByRef             orioumr
    00536 #define OCIObjectAlwaysLatest            oriomkl
    00537 #define OCIObjectNotAlwaysLatest         oriouml
    00538 #define OCIObjectMarkDeleteByRef         oriordl
    00539 #define OCIObjectMarkDelete              oriopdl
    00540 #define OCIObjectFlush                   oriofls
    00541 #define OCIObjectFlushRefresh            oriofrh
    00542 #define OCIObjectCopy                    oriocpy
    00543 #define OCIObjectGetTypeRef              oriogtr
    00544 #define OCIObjectGetObjectRef            oriogor
    00545 #define OCIObjectGetInd                  oriogns
    00546 #define OCIObjectExists                  oriogex
    00547 #define OCIObjectGetProperty             oriogpr
    00548 #define OCIObjectRefresh                 oriorfs
    00549 #define OCIObjectPinTable                oriogtb
    00550 #define OCIObjectGetPrimaryKeyTypeRef    oriogpf
    00551 #define OCIObjectMakeObjectRef           oriomrf
    00552
    00553 #define OCIObjectNew                     orionew
    00554 #define OCIObjectPin                     oriopin
    00555 #define OCIObjectFree                    oriofre
    00556 #define OCIObjectArrayPin                orioapn
    00557 #define OCIObjectIsDirty                 oriodrt
    00558 #define OCIObjectIsDirtied               oriodrd
    00559 #define OCIObjectIsLoaded                orioldd
    00560 #define OCICacheFlush                    oricfls
    00561 #define OCICacheRefresh                  oricrfs
    00562
    00563 #endif                                                        /* SLSHORTNAME */
    00564
    00565 /*---------------------------------------------------------------------------*/
    00566 /*                       PUBLIC TYPES AND CONSTANTS                          */
    00567 /*---------------------------------------------------------------------------*/
    00568
    00569 /* Also see oro.h. */
    00570
    00571 /*---------------------------------------------------------------------------*/
    00572 /*                           PUBLIC FUNCTIONS                                */
    00573 /*---------------------------------------------------------------------------*/
    00574 /*---------------------------------------------------------------------------*/
    00575 /*                       OBJECT/INSTANCE OPERATIONS                          */
    00576 /*---------------------------------------------------------------------------*/
    00577
    00578 /*--------------------------- OCIObjectNew ----------------------------------*/
    00579 sword OCIObjectNew(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    00580                        OCITypeCode typecode, OCIType *tdo, dvoid *table,
    00581                        OCIDuration duration, boolean value,
    00582                        dvoid **instance    );
    00583 /*
    00584    NAME: OCIObjectNew - OCI new (create) a standalone instance
    00585    PARAMETERS:
    00586         env  (IN/OUT) - OCI environment handle initialized in object mode
    00587         err  (IN/OUT) - error handle. If there is an error, it is
    00588                         recorded in 'err' and this function returns OCI_ERROR.
    00589                         The error recorded in 'err' can be retrieved by calling
    00590                         OCIErrorGet().
    00591         svc      (IN) - OCI service handle.
    00592         typecode (IN) - the typecode of the type of the instance.
    00593         tdo      (IN, optional) - pointer to the type descriptor object. The
    00594                         TDO describes the type of the instance that is to be
    00595                         created. Refer to OCITypeByName() for obtaining a TDO.
    00596                         The TDO is required for creating a named type (e.g. an
    00597                         object or a collection).
    00598         table (IN, optional) - pointer to a table object which specifies a
    00599                         table in the server.  This parameter can be set to NULL
    00600                         if no table is given. See the description below to find
    00601                         out how the table object and the TDO are used together
    00602                         to determine the kind of instances (persistent,
    00603                         transient, value) to be created. Also see
    00604                         OCIObjectPinTable() for retrieving a table object.
    00605         duration (IN) - this is an overloaded parameter. The use of this
    00606                         parameter is based on the kind of the instance that is
    00607                         to be created.
    00608                         a) persistent object. This parameter specifies the
    00609                            pin duration.
    00610                         b) transient object. This parameter specififes the
    00611                            allocation duration and pin duration.
    00612                         c) value. This parameter specifies the allocation
    00613                            duration.
    00614         value    (IN)  - specifies whether the created object is a value.
    00615                          If TRUE, then a value is created. Otherwise, a
    00616                          referenceable object is created.  If the instance is
    00617                          not an object, then this parameter is ignored.
    00618         instance (OUT) - address of the newly created instance
    00619
    00620    REQUIRES:
    00621         - a valid OCI environment handle must be given.
    00622    DESCRIPTION:
    00623         This function creates a new instance of the type specified by the
    00624         typecode or the TDO. Based on the parameters 'typecode' (or 'tdo'),
    00625         'value' and 'table', different kinds of instances can be created:
    00626
    00627                                      The parameter 'table' is not NULL?
    00628
    00629                                                yes              no
    00630              ----------------------------------------------------------------
    00631              | object type (value=TRUE)   |   value         |   value       |
    00632              ----------------------------------------------------------------
    00633              | object type (value=FALSE)  | persistent obj  | transient obj |
    00634        type  ----------------------------------------------------------------
    00635              | built-in type              |   value         |   value       |
    00636              ----------------------------------------------------------------
    00637              | collection type            |   value         |   value       |
    00638              ----------------------------------------------------------------
    00639
    00640         This function allocates the top level memory chunk of an OTS instance.
    00641         The attributes in the top level memory are initialized (e.g. an
    00642         attribute of varchar2 is initialized to a vstring of 0 length).
    00643
    00644         If the instance is an object, the object is marked existed but is
    00645         atomically null.
    00646
    00647         FOR PERSISTENT OBJECTS:
    00648         The object is marked dirty and existed.  The allocation duration for
    00649         the object is session. The object is pinned and the pin duration is
    00650         specified by the given parameter 'duration'.
    00651
    00652         FOR TRANSIENT OBJECTS:
    00653         The object is pinned. The allocation duration and the pin duration are
    00654         specified by the given parameter 'duration'.
    00655
    00656         FOR VALUES:
    00657         The allocation duration is specified by the given parameter 'duration'.
    00658
    00659    RETURNS:
    00660         if environment handle or error handle is null, return
    00661         OCI_INVALID_HANDLE.
    00662         if operation suceeds, return OCI_SUCCESS.
    00663         if operation fails, return OCI_ERROR.
    00664  */
    00665
    00666 /*--------------------------- OCIObjectPin ----------------------------------*/
    00667 sword OCIObjectPin(    OCIEnv *env, OCIError *err, OCIRef *object_ref,
    00668                        OCIComplexObject *corhdl, OCIPinOpt pin_option,
    00669                        OCIDuration pin_duration,
    00670                        OCILockOpt lock_option, dvoid **object    );
    00671 /*
    00672    NAME: OCIObjectPin - OCI pin a referenceable object
    00673    PARAMETERS:
    00674         env        (IN/OUT) - OCI environment handle initialized in object mode
    00675         err        (IN/OUT) - error handle. If there is an error, it is
    00676                               recorded in 'err' and this function returns
    00677                               OCI_ERROR. The error recorded in 'err' can be
    00678                               retrieved by calling OCIErrorGet().
    00679         object_ref     (IN) - the reference to the object.
    00680         corhdl         (IN) - handle for complex object retrieval.
    00681         pin_option     (IN) - See description below.
    00682         pin_duration   (IN) - The duration of which the object is being accesed
    00683                               by a client. The object is implicitly unpinned at
    00684                               the end of the pin duration.
    00685                               If OCI_DURATION_NULL is passed, there is no pin
    00686                               promotion if the object is already loaded into
    00687                               the cache. If the object is not yet loaded, then
    00688                               the pin duration is set to OCI_DURATION_DEFAULT.
    00689         lock_option    (IN) - lock option (e.g., exclusive). If a lock option
    00690                               is specified, the object is locked in the server.
    00691                               See 'oro.h' for description about lock option.
    00692         object        (OUT) - the pointer to the pinned object.
    00693
    00694    REQUIRES:
    00695         - a valid OCI environment handle must be given.
    00696    DESCRIPTION:
    00697
    00698         This function pins a referenceable object instance given the object
    00699         reference. The process of pinning serves three purposes:
    00700
    00701         1) locate an object given its reference. This is done by the object
    00702            cache which keeps track of the objects in the object heap.
    00703
    00704         2) notify the object cache that an object is being in use. An object
    00705            can be pinned many times. A pinned object will remain in memory
    00706            until it is completely unpinned (see OCIObjectUnpin()).
    00707
    00708         3) notify the object cache that a persistent object is being in use
    00709            such that the persistent object cannot be aged out.  Since a
    00710            persistent object can be loaded from the server whenever is needed,
    00711            the memory utilization can be increased if a completely unpinned
    00712            persistent object can be freed (aged out), even before the
    00713            allocation duration is expired.
    00714
    00715         Also see OCIObjectUnpin() for more information about unpinning.
    00716
    00717         FOR PERSISTENT OBJECTS:
    00718
    00719         When pinning a persistent object, if it is not in the cache, the object
    00720         will be fetched from the persistent store. The allocation duration of
    00721         the object is session. If the object is already in the cache, it is
    00722         returned to the client.  The object will be locked in the server if a
    00723         lock option is specified.
    00724
    00725         This function will return an error for a non-existent object.
    00726
    00727         A pin option is used to specify the copy of the object that is to be
    00728         retrieved:
    00729
    00730         1) If option is OCI_PIN_ANY (pin any), if the object is already
    00731            in the environment heap, return this object. Otherwise, the object
    00732            is retrieved from the database.  This option is useful when the
    00733            client knows that he has the exclusive access to the data in a
    00734            session.
    00735
    00736         2) If option is OCI_PIN_LATEST (pin latest), if the object is
    00737            not cached, it is retrieved from the database.  If the object is
    00738            cached, it is refreshed with the latest version. See
    00739            OCIObjectRefresh() for more information about refreshing.
    00740
    00741         3) If option is OCI_PIN_RECENT (pin recent), if the object is loaded
    00742            into the cache in the current transaction, the object is returned.
    00743            If the object is not loaded in the current transaction, the object
    00744            is refreshed from the server.
    00745
    00746         FOR TRANSIENT OBJECTS:
    00747
    00748         This function will return an error if the transient object has already
    00749         been freed. This function does not return an error if an exclusive
    00750         lock is specified in the lock option.
    00751
    00752    RETURNS:
    00753         if environment handle or error handle is null, return
    00754         OCI_INVALID_HANDLE.
    00755         if operation suceeds, return OCI_SUCCESS.
    00756         if operation fails, return OCI_ERROR.
    00757  */
    00758
    00759 /*------------------------------ OCIObjectUnpin -----------------------------*/
    00760 sword OCIObjectUnpin(    OCIEnv *env, OCIError *err, dvoid *object    );
    00761 /*
    00762    NAME: OCIObjectUnpin - OCI unpin a referenceable object
    00763    PARAMETERS:
    00764         env   (IN/OUT) - OCI environment handle initialized in object mode
    00765         err   (IN/OUT) - error handle. If there is an error, it is
    00766                          recorded in 'err' and this function returns OCI_ERROR.
    00767                          The error recorded in 'err' can be retrieved by
    00768                          calling OCIErrorGet().
    00769         object    (IN) - pointer to an object
    00770    REQUIRES:
    00771         - a valid OCI environment handle must be given.
    00772         - The specified object must be pinned.
    00773    DESCRIPTION:
    00774         This function unpins an object.  An object is completely unpinned when
    00775           1) the object was unpinned N times after it has been pinned N times
    00776              (by calling OCIObjectPin()).
    00777           2) it is the end of the pin duration
    00778           3) the function OCIObjectPinCountReset() is called
    00779
    00780         There is a pin count associated with each object which is incremented
    00781         whenever an object is pinned. When the pin count of the object is zero,
    00782         the object is said to be completely unpinned. An unpinned object can
    00783         be freed without error.
    00784
    00785         FOR PERSISTENT OBJECTS:
    00786         When a persistent object is completely unpinned, it becomes a candidate
    00787         for aging. The memory of an object is freed when it is aged out. Aging
    00788         is used to maximize the utilization of memory.  An dirty object cannot
    00789         be aged out unless it is flushed.
    00790
    00791         FOR TRANSIENT OBJECTS:
    00792         The pin count of the object is decremented. A transient can be freed
    00793         only at the end of its allocation duration or when it is explicitly
    00794         deleted by calling OCIObjectFree().
    00795
    00796         FOR VALUE:
    00797         This function will return an error for value.
    00798
    00799    RETURNS:
    00800         if environment handle or error handle is null, return
    00801         OCI_INVALID_HANDLE.
    00802         if operation suceeds, return OCI_SUCCESS.
    00803         if operation fails, return OCI_ERROR.
    00804  */
    00805
    00806 /*---------------------------- OCIObjectPinCountReset -----------------------*/
    00807 sword OCIObjectPinCountReset(    OCIEnv *env, OCIError *err, dvoid *object   );
    00808 /*
    00809    NAME: OCIObjectPinCountReset - OCI resets the pin count of a referenceable
    00810                                   object
    00811    PARAMETERS:
    00812         env   (IN/OUT) - OCI environment handle initialized in object mode
    00813         err   (IN/OUT) - error handle. If there is an error, it is
    00814                          recorded in 'err' and this function returns OCI_ERROR.
    00815                          The error recorded in 'err' can be retrieved by
    00816                          calling OCIErrorGet().
    00817         object    (IN) - pointer to an object
    00818    REQUIRES:
    00819         - a valid OCI environment handle must be given.
    00820         - The specified object must be pinned.
    00821    DESCRIPTION:
    00822         This function completely unpins an object.  When an object is
    00823         completely unpinned, it can be freed without error.
    00824
    00825         FOR PERSISTENT OBJECTS:
    00826         When a persistent object is completely unpinned, it becomes a candidate
    00827         for aging. The memory of an object is freed when it is aged out. Aging
    00828         is used to maximize the utilization of memory.  An dirty object cannot
    00829         be aged out unless it is flushed.
    00830
    00831         FOR TRANSIENT OBJECTS:
    00832         The pin count of the object is decremented. A transient can be freed
    00833         only at the end of its allocation duration or when it is explicitly
    00834         freed by calling OCIObjectFree().
    00835
    00836         FOR VALUE:
    00837         This function will return an error for value.
    00838
    00839    RETURNS:
    00840         if environment handle or error handle is null, return
    00841         OCI_INVALID_HANDLE.
    00842         if operation suceeds, return OCI_SUCCESS.
    00843         if operation fails, return OCI_ERROR.
    00844  */
    00845
    00846 /*--------------------------- OCIObjectLock ---------------------------------*/
    00847 sword OCIObjectLock(    OCIEnv *env, OCIError *err, dvoid *object    );
    00848 /*
    00849    NAME: OCIObjectLock - OCI lock a persistent object
    00850    PARAMETERS:
    00851         env   (IN/OUT) - OCI environment handle initialized in object mode
    00852         err   (IN/OUT) - error handle. If there is an error, it is
    00853                          recorded in 'err' and this function returns OCI_ERROR.
    00854                          The error recorded in 'err' can be retrieved by
    00855                          calling OCIErrorGet().
    00856         object    (IN) - pointer to the persistent object
    00857    REQUIRES:
    00858         - a valid OCI environment handle must be given.
    00859         - The specified object must be pinned.
    00860    DESCRIPTION:
    00861         This function locks a persistent object at the server. Unlike
    00862         OCIObjectLockNoWait() this function waits if another user currently
    00863         holds a lock on the desired object. This function
    00864         returns an error if:
    00865           1) the object is non-existent.
    00866
    00867         This function will return an error for transient objects and values.
    00868         The lock of an object is released at the end of a transaction.
    00869
    00870    RETURNS:
    00871         if environment handle or error handle is null, return
    00872         OCI_INVALID_HANDLE.
    00873         if operation suceeds, return OCI_SUCCESS.
    00874         if operation fails, return OCI_ERROR.
    00875 */
    00876
    00877 /*------------------------ OCIObjectLockNoWait ------------------------------*/
    00878 sword OCIObjectLockNoWait(    OCIEnv *env, OCIError *err, dvoid *object    );
    00879 /*
    00880    NAME: OCIObjectLockNoWait - OCI lock a persistent object, do not wait for
    00881                                the lock, return error if lock not available
    00882    PARAMETERS:
    00883         env   (IN/OUT) - OCI environment handle initialized in object mode
    00884         err   (IN/OUT) - error handle. If there is an error, it is
    00885                          recorded in 'err' and this function returns OCI_ERROR.
    00886                          The error recorded in 'err' can be retrieved by
    00887                          calling OCIErrorGet().
    00888         object    (IN) - pointer to the persistent object
    00889    REQUIRES:
    00890         - a valid OCI environment handle must be given.
    00891         - The specified object must be pinned.
    00892    DESCRIPTION:
    00893         This function locks a persistent object at the server. Unlike
    00894         OCIObjectLock() this function will not wait if another user holds
    00895         the lock on the desired object. This function returns an error if:
    00896           1) the object is non-existent.
    00897           2) the object is currently locked by another user in which
    00898              case this function returns with an error.
    00899
    00900         This function will return an error for transient objects and values.
    00901         The lock of an object is released at the end of a transaction.
    00902
    00903    RETURNS:
    00904         if environment handle or error handle is null, return
    00905         OCI_INVALID_HANDLE.
    00906         if operation suceeds, return OCI_SUCCESS.
    00907         if operation fails, return OCI_ERROR.
    00908 */
    00909
    00910 /*--------------------------- OCIObjectMarkUpdate ---------------------------*/
    00911 sword OCIObjectMarkUpdate(    OCIEnv *env, OCIError *err, dvoid *object    );
    00912 /*
    00913    NAME: OCIObjectMarkUpdate - OCI marks an object as updated
    00914    PARAMETERS:
    00915         env   (IN/OUT) - OCI environment handle initialized in object mode
    00916         err   (IN/OUT) - error handle. If there is an error, it is
    00917                          recorded in 'err' and this function returns OCI_ERROR.
    00918                          The error recorded in 'err' can be retrieved by
    00919                          calling OCIErrorGet().
    00920         object    (IN) - pointer to the persistent object
    00921    REQUIRES:
    00922         - a valid OCI environment handle must be given.
    00923         - The specified object must be pinned.
    00924    DESCRIPTION:
    00925         FOR PERSISTENT OBJECTS:
    00926         This function marks the specified persistent object as updated. The
    00927         persistent objects will be written to the server when the object cache
    00928         is flushed.  The object is not locked or flushed by this function. It
    00929         is an error to update a deleted object.
    00930
    00931         After an object is marked updated and flushed, this function must be
    00932         called again to mark the object as updated if it has been dirtied
    00933         after it is being flushed.
    00934
    00935         FOR TRANSIENT OBJECTS:
    00936         This function marks the specified transient object as updated. The
    00937         transient objects will NOT be written to the server. It is an error
    00938         to update a deleted object.
    00939
    00940         FOR VALUES:
    00941         It is an no-op for values.
    00942
    00943    RETURNS:
    00944         if environment handle or error handle is null, return
    00945         OCI_INVALID_HANDLE.
    00946         if operation suceeds, return OCI_SUCCESS.
    00947         if operation fails, return OCI_ERROR.
    00948  */
    00949
    00950 /*----------------------------- OCIObjectUnmark -----------------------------*/
    00951 sword OCIObjectUnmark(    OCIEnv *env, OCIError *err, dvoid *object    );
    00952 /*
    00953    NAME: OCIObjectUnmark - OCI unmarks an object
    00954    PARAMETERS:
    00955         env   (IN/OUT) - OCI environment handle initialized in object mode
    00956         err   (IN/OUT) - error handle. If there is an error, it is
    00957                          recorded in 'err' and this function returns OCI_ERROR.
    00958                          The error recorded in 'err' can be retrieved by
    00959                          calling OCIErrorGet().
    00960         object    (IN) - pointer to the persistent object
    00961    REQUIRES:
    00962         - a valid OCI environment handle must be given.
    00963         - The specified object must be pinned.
    00964    DESCRIPTION:
    00965         FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
    00966         This function unmarks the specified persistent object as dirty. Changes
    00967         that are made to the object will not be written to the server. If the
    00968         object is marked locked, it remains marked locked.  The changes that
    00969         have already made to the object will not be undone implicitly.
    00970
    00971         FOR VALUES:
    00972         It is an no-op for values.
    00973
    00974    RETURNS:
    00975         if environment handle or error handle is null, return
    00976         OCI_INVALID_HANDLE.
    00977         if operation suceeds, return OCI_SUCCESS.
    00978         if operation fails, return OCI_ERROR.
    00979  */
    00980
    00981 /*----------------------------- OCIObjectUnmarkByRef ------------------------*/
    00982 sword OCIObjectUnmarkByRef(    OCIEnv *env, OCIError *err, OCIRef *ref    );
    00983 /*
    00984    NAME: OCIObjectUnmarkByRef - OCI unmarks an object by Ref
    00985    PARAMETERS:
    00986         env   (IN/OUT) - OCI environment handle initialized in object mode
    00987         err   (IN/OUT) - error handle. If there is an error, it is
    00988                          recorded in 'err' and this function returns OCI_ERROR.
    00989                          The error recorded in 'err' can be retrieved by
    00990                          calling OCIErrorGet().
    00991         ref   (IN) - reference of the object
    00992    REQUIRES:
    00993         - a valid OCI environment handle must be given.
    00994         - The specified object must be pinned.
    00995    DESCRIPTION:
    00996         FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
    00997         This function unmarks the specified persistent object as dirty. Changes
    00998         that are made to the object will not be written to the server. If the
    00999         object is marked locked, it remains marked locked.  The changes that
    01000         have already made to the object will not be undone implicitly.
    01001
    01002         FOR VALUES:
    01003         It is an no-op for values.
    01004
    01005    RETURNS:
    01006         if environment handle or error handle is null, return
    01007         OCI_INVALID_HANDLE.
    01008         if operation suceeds, return OCI_SUCCESS.
    01009         if operation fails, return OCI_ERROR.
    01010  */
    01011
    01012 /*--------------------------- OCIObjectFree ---------------------------------*/
    01013 sword OCIObjectFree(    OCIEnv *env, OCIError *err, dvoid *instance,
    01014                         ub2 flags   );
    01015 /*
    01016    NAME: OCIObjectFree - OCI free (and unpin) an standalone instance
    01017    PARAMETERS:
    01018         env    (IN/OUT) - OCI environment handle initialized in object mode
    01019         err    (IN/OUT) - error handle. If there is an error, it is
    01020                           recorded in 'err' and this function returns
    01021                           OCI_ERROR.  The error recorded in 'err' can be
    01022                           retrieved by calling OCIErrorGet().
    01023         instance   (IN) - pointer to a standalone instance.
    01024         flags      (IN) - If OCI_OBJECT_FREE_FORCE is set, free the object
    01025                           even if it is pinned or dirty.
    01026                           If OCI_OBJECT_FREE_NONULL is set, the null
    01027                           structure will not be freed.
    01028    REQUIRES:
    01029         - a valid OCI environment handle must be given.
    01030         - The instance to be freed must be standalone.
    01031         - If the instance is a referenceable object, the object must be pinned.
    01032    DESCRIPTION:
    01033         This function deallocates all the memory allocated for an OTS instance,
    01034         including the null structure.
    01035
    01036         FOR PERSISTENT OBJECTS:
    01037         This function will return an error if the client is attempting to free
    01038         a dirty persistent object that has not been flushed. The client should
    01039         either flush the persistent object or set the parameter 'flag' to
    01040         OCI_OBJECT_FREE_FORCE.
    01041
    01042         This function will call OCIObjectUnpin() once to check if the object
    01043         can be completely unpin. If it succeeds, the rest of the function will
    01044         proceed to free the object.  If it fails, then an error is returned
    01045         unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE.
    01046
    01047         Freeing a persistent object in memory will not change the persistent
    01048         state of that object at the server.  For example, the object will
    01049         remain locked after the object is freed.
    01050
    01051         FOR TRANSIENT OBJECTS:
    01052
    01053         This function will call OCIObjectUnpin() once to check if the object
    01054         can be completely unpin. If it succeeds, the rest of the function will
    01055         proceed to free the object.  If it fails, then an error is returned
    01056         unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE.
    01057
    01058         FOR VALUES:
    01059         The memory of the object is freed immediately.
    01060
    01061    RETURNS:
    01062         if environment handle or error handle is null, return
    01063         OCI_INVALID_HANDLE.
    01064         if operation suceeds, return OCI_SUCCESS.
    01065         if operation fails, return OCI_ERROR.
    01066 */
    01067
    01068 /*----------------------- OCIObjectMarkDeleteByRef --------------------------*/
    01069 sword OCIObjectMarkDeleteByRef(    OCIEnv *env, OCIError *err,
    01070                                    OCIRef *object_ref);
    01071 /*
    01072    NAME: OCIObjectMarkDeleteByRef - OCI "delete" (and unpin) an object given
    01073                                     a reference
    01074    PARAMETERS:
    01075         env     (IN/OUT) - OCI environment handle initialized in object mode
    01076         err     (IN/OUT) - error handle. If there is an error, it is
    01077                            recorded in 'err' and this function returns
    01078                            OCI_ERROR.  The error recorded in 'err' can be
    01079                            retrieved by calling OCIErrorGet().
    01080         object_ref  (IN) - ref of the object to be deleted
    01081
    01082    REQUIRES:
    01083         - a valid OCI environment handle must be given.
    01084    DESCRIPTION:
    01085         This function marks the object designated by 'object_ref' as deleted.
    01086
    01087         FOR PERSISTENT OBJECTS:
    01088         If the object is not loaded, then a temporary object is created and is
    01089         marked deleted. Otherwise, the object is marked deleted.
    01090
    01091         The object is deleted in the server when the object is flushed.
    01092
    01093         FOR TRANSIENT OBJECTS:
    01094         The object is marked deleted.  The object is not freed until it is
    01095         unpinned.
    01096
    01097    RETURNS:
    01098         if environment handle or error handle is null, return
    01099         OCI_INVALID_HANDLE.
    01100         if operation suceeds, return OCI_SUCCESS.
    01101         if operation fails, return OCI_ERROR.
    01102  */
    01103
    01104 /*--------------------------- OCIObjectMarkDelete ---------------------------*/
    01105 sword OCIObjectMarkDelete(    OCIEnv *env, OCIError *err, dvoid *instance    );
    01106 /*
    01107    NAME: OCIObjectMarkDelete - OCI "delete" an instance given a Pointer
    01108    PARAMETERS:
    01109         env    (IN/OUT) - OCI environment handle initialized in object mode
    01110         err    (IN/OUT) - error handle. If there is an error, it is
    01111                           recorded in 'err' and this function returns
    01112                           OCI_ERROR.  The error recorded in 'err' can be
    01113                           retrieved by calling OCIErrorGet().
    01114         instance   (IN) - pointer to the instance
    01115    REQUIRES:
    01116         - a valid OCI environment handle must be given.
    01117         - The instance must be standalone.
    01118         - If the instance is a referenceable object, then it must be pinned.
    01119    DESCRIPTION:
    01120
    01121         FOR PERSISTENT OBJECTS:
    01122         The object is marked deleted.  The memory of the object is not freed.
    01123         The object is deleted in the server when the object is flushed.
    01124
    01125         FOR TRANSIENT OBJECTS:
    01126         The object is marked deleted.  The memory of the object is not freed.
    01127
    01128         FOR VALUES:
    01129         This function frees a value immediately.
    01130
    01131    RETURNS:
    01132         if environment handle or error handle is null, return
    01133         OCI_INVALID_HANDLE.
    01134         if operation suceeds, return OCI_SUCCESS.
    01135         if operation fails, return OCI_ERROR.
    01136  */
    01137
    01138 /*---------------------------- OCIObjectFlush -------------------------------*/
    01139 sword OCIObjectFlush(    OCIEnv *env, OCIError *err, dvoid *object    );
    01140 /*
    01141    NAME: OCIObjectFlush - OCI flush a persistent object
    01142    PARAMETERS:
    01143         env    (IN/OUT) - OCI environment handle initialized in object mode
    01144         err    (IN/OUT) - error handle. If there is an error, it is
    01145                           recorded in 'err' and this function returns
    01146                           OCI_ERROR.  The error recorded in 'err' can be
    01147                           retrieved by calling OCIErrorGet().
    01148         object     (IN) - pointer to the persistent object
    01149    REQUIRES:
    01150         - a valid OCI environment handle must be given.
    01151         - The specified object must be pinned.
    01152    DESCRIPTION:
    01153         This function flushes a modified persistent object to the server.
    01154         An exclusive lock is obtained implicitly for the object when flushed.
    01155
    01156         When the object is written to the server, triggers may be fired.
    01157         Objects can be modified by the triggers at the server.  To keep the
    01158         objects in the object cache being coherent with the database, the
    01159         clients can free or refresh the objects in the cache.
    01160
    01161         This function will return an error for transient objects and values.
    01162
    01163    RETURNS:
    01164         if environment handle or error handle is null, return
    01165         OCI_INVALID_HANDLE.
    01166         if operation suceeds, return OCI_SUCCESS.
    01167         if operation fails, return OCI_ERROR.
    01168  */
    01169
    01170 /*------------------------ OCIObjectRefresh ---------------------------------*/
    01171 sword OCIObjectRefresh(    OCIEnv *env, OCIError *err, dvoid *object    );
    01172 /*
    01173    NAME: OCIObjectRefresh - OCI refresh a persistent object
    01174    PARAMETERS:
    01175         env    (IN/OUT) - OCI environment handle initialized in object mode
    01176         err    (IN/OUT) - error handle. If there is an error, it is
    01177                           recorded in 'err' and this function returns
    01178                           OCI_ERROR.  The error recorded in 'err' can be
    01179                           retrieved by calling OCIErrorGet().
    01180         object     (IN) - pointer to the persistent object
    01181    REQUIRES:
    01182         - a valid OCI environment handle must be given.
    01183         - The specified object must be pinned.
    01184    DESCRIPTION:
    01185         This function refreshes an unmarked object with data retrieved from the
    01186         latest snapshot in the server. An object should be refreshed when the
    01187         objects in the cache are inconsistent with the objects at
    01188         the server:
    01189         1) When an object is flushed to the server, triggers can be fired to
    01190            modify more objects in the server.  The same objects (modified by
    01191            the triggers) in the object cache become obsolete.
    01192         2) When the user issues a SQL or executes a PL/SQL procedure to modify
    01193            any object in the server, the same object in the cache becomes
    01194            obsolete.
    01195
    01196         The object that is refreshed will be 'replaced-in-place'. When an
    01197         object is 'replaced-in-place', the top level memory of the object will
    01198         be reused so that new data can be loaded into the same memory address.
    01199         The top level memory of the null structre is also reused. Unlike the
    01200         top level memory chunk, the secondary memory chunks may be resized and
    01201         reallocated.  The client should be careful when holding onto a pointer
    01202         to the secondary memory chunk (e.g. assigning the address of a
    01203         secondary memory to a local variable), since this pointer can become
    01204         invalid after the object is refreshed.
    01205
    01206         The object state will be modified as followed after being refreshed:
    01207           - existent : set to appropriate value
    01208           - pinned   : unchanged
    01209           - allocation duration : unchanged
    01210           - pin duration : unchanged
    01211
    01212         This function is an no-op for transient objects or values.
    01213
    01214    RETURNS:
    01215         if environment handle or error handle is null, return
    01216         OCI_INVALID_HANDLE.
    01217         if operation suceeds, return OCI_SUCCESS.
    01218         if operation fails, return OCI_ERROR.
    01219  */
    01220
    01221 /*---------------------------- OCIObjectCopy --------------------------------*/
    01222 sword OCIObjectCopy(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01223                         dvoid *source, dvoid *null_source,
    01224                         dvoid *target, dvoid *null_target, OCIType *tdo,
    01225                         OCIDuration duration, ub1 option    );
    01226 /*
    01227    NAME: OCIObjectCopy - OCI copy one instance to another
    01228    PARAMETERS:
    01229         env     (IN/OUT) - OCI environment handle initialized in object mode
    01230         err     (IN/OUT) - error handle. If there is an error, it is
    01231                            recorded in 'err' and this function returns
    01232                            OCI_ERROR.  The error recorded in 'err' can be
    01233                            retrieved by calling OCIErrorGet().
    01234         svc         (IN) - OCI service context handle
    01235         source      (IN) - pointer to the source instance
    01236         null_source (IN) - pointer to the null structure of the source
    01237         target      (IN) - pointer to the target instance
    01238         null_target (IN) - pointer to the null structure of the target
    01239         tdo         (IN) - the TDO for both source and target
    01240         duration    (IN) - allocation duration of the target memory
    01241         option      (IN) - specify the copy option:
    01242                         OROOCOSFN - Set Reference to Null. All references
    01243                         in the source will not be copied to the target. The
    01244                         references in the target are set to null.
    01245    REQUIRES:
    01246         - a valid OCI environment handle must be given.
    01247         - If source or target is referenceable, it must be pinned.
    01248         - The target or the containing instance of the target must be already
    01249           be instantiated (e.g. created by OCIObjectNew()).
    01250         - The source and target instances must be of the same type. If the
    01251           source and target are located in a different databases, then the
    01252           same type must exist in both databases.
    01253    DESCRIPTION:
    01254         This function copies the contents of the 'source' instance to the
    01255         'target' instance. This function performs a deep-copy such that the
    01256         data that is copied/duplicated include:
    01257         a) all the top level attributes (see the exceptions below)
    01258         b) all the secondary memory (of the source) that is reachable from the
    01259            top level attributes.
    01260         c) the null structure of the instance
    01261
    01262         Memory is allocated with the specified allocation duration.
    01263
    01264         Certain data items are not copied:
    01265         a) If the option OCI_OBJECTCOPY_NOREF is specified, then all references
    01266            in the source are not copied. Instead, the references in the target
    01267            are set to null.
    01268         b) If the attribute is a LOB, then it is set to null.
    01269
    01270    RETURNS:
    01271         if environment handle or error handle is null, return
    01272         OCI_INVALID_HANDLE.
    01273         if operation suceeds, return OCI_SUCCESS.
    01274         if operation fails, return OCI_ERROR.
    01275  */
    01276
    01277 /*---------------------------- OCIObjectGetTypeRef --------------------------*/
    01278 sword OCIObjectGetTypeRef(    OCIEnv *env, OCIError *err, dvoid *instance,
    01279                               OCIRef *type_ref    );
    01280 /*
    01281    NAME: OCIObjectGetTypeRef - get the type reference of a standalone object
    01282    PARAMETERS:
    01283         env   (IN/OUT) - OCI environment handle initialized in object mode
    01284         err   (IN/OUT) - error handle. If there is an error, it is
    01285                          recorded in 'err' and this function returns
    01286                          OCI_ERROR.  The error recorded in 'err' can be
    01287                          retrieved by calling OCIErrorGet().
    01288         instance  (IN) - pointer to an standalone instance
    01289         type_ref (OUT) - reference to the type of the object.  The reference
    01290                          must already be allocated.
    01291    REQUIRES:
    01292         - a valid OCI environment handle must be given.
    01293         - The instance must be standalone.
    01294         - If the object is referenceable, the specified object must be pinned.
    01295         - The reference must already be allocated.
    01296    DESCRIPTION:
    01297         This function returns a reference to the TDO of a standalone instance.
    01298    RETURNS:
    01299         if environment handle or error handle is null, return
    01300         OCI_INVALID_HANDLE.
    01301         if operation suceeds, return OCI_SUCCESS.
    01302         if operation fails, return OCI_ERROR.
    01303  */
    01304
    01305 /*--------------------------- OCIObjectGetObjectRef -------------------------*/
    01306 sword OCIObjectGetObjectRef(    OCIEnv *env, OCIError *err, dvoid *object,
    01307                                 OCIRef *object_ref    );
    01308 /*
    01309    NAME: OCIObjectGetObjectRef - OCI get the object reference of an
    01310                                  referenceable object
    01311    PARAMETERS:
    01312         env     (IN/OUT) - OCI environment handle initialized in object mode
    01313         err     (IN/OUT) - error handle. If there is an error, it is
    01314                            recorded in 'err' and this function returns
    01315                            OCI_ERROR.  The error recorded in 'err' can be
    01316                            retrieved by calling OCIErrorGet().
    01317         object      (IN) - pointer to a persistent object
    01318         object_ref (OUT) - reference of the given object. The reference must
    01319                            already be allocated.
    01320    REQUIRES:
    01321         - a valid OCI environment handle must be given.
    01322         - The specified object must be pinned.
    01323         - The reference must already be allocated.
    01324    DESCRIPTION:
    01325         This function returns a reference to the given object.  It returns an
    01326         error for values.
    01327    RETURNS:
    01328         if environment handle or error handle is null, return
    01329         OCI_INVALID_HANDLE.
    01330         if operation suceeds, return OCI_SUCCESS.
    01331         if operation fails, return OCI_ERROR.
    01332  */
    01333
    01334 /*--------------------------- OCIObjectMakeObjectRef -----------------------*/
    01335 sword OCIObjectMakeObjectRef(    OCIEnv *env, OCIError *err,
    01336                                  CONST OCISvcCtx *svc, dvoid * table,
    01337                                  dvoid **values, ub4 array_len,
    01338                                  OCIRef *object_ref    );
    01339 /*
    01340    NAME: OCIObjectMakeObjectRef - OCI Create an object reference to a
    01341                                  referenceable object.
    01342    PARAMETERS:
    01343         env     (IN/OUT) - OCI environment handle initialized in object mode
    01344         err     (IN/OUT) - error handle. If there is an error, it is
    01345                            recorded in 'err' and this function returns
    01346                            OCI_ERROR.  The error recorded in 'err' can be
    01347                            retrieved by calling OCIErrorGet().
    01348         svc         (IN) - the service context
    01349         table       (IN) - A pointer to the table object (must be pinned)
    01350         attrlist    (IN) - A list of values (OCI type values) from which
    01351                            the ref is to be created.
    01352         attrcnt     (IN)  - The length of the attrlist array.
    01353         object_ref (OUT) - reference of the given object. The reference must
    01354                            already be allocated.
    01355    REQUIRES:
    01356         - a valid OCI environment handle must be given.
    01357         - The specified table object must be pinned.
    01358         - The reference must already be allocated.
    01359    DESCRIPTION:
    01360         This function creates a reference given the values that make up the
    01361         reference and also a pointer to the table object.
    01362         Based on the table's OID property, whether it is a pk based OID or
    01363         a system generated OID, the function creates a sys-generated REF or
    01364         a pk based REF.
    01365         In case of system generated REFs pass in a OCIRaw which is 16 bytes
    01366         long contatining the sys generated OID.
    01367         In case of PK refs pass in the OCI equivalent for numbers, chars etc..
    01368    RETURNS:
    01369         if environment handle or error handle is null, return
    01370         OCI_INVALID_HANDLE.
    01371         if operation suceeds, return OCI_SUCCESS.
    01372         if operation fails, return OCI_ERROR.
    01373  */
    01374
    01375 /*--------------------------- OCIObjectGetPrimaryKeyTypeRef --------------- */
    01376 sword OCIObjectGetPrimaryKeyTypeRef( OCIEnv *env, OCIError *err,
    01377                                      CONST OCISvcCtx *svc, dvoid *table,
    01378                                      OCIRef *type_ref );
    01379 /*
    01380    NAME: OCIObjectGetPrimaryKeyTypeRef - OCI get the REF to the pk OID type
    01381    PARAMETERS:
    01382         env     (IN/OUT) - OCI environment handle initialized in object mode
    01383         err     (IN/OUT) - error handle. If there is an error, it is
    01384                            recorded in 'err' and this function returns
    01385                            OCI_ERROR.  The error recorded in 'err' can be
    01386                            retrieved by calling OCIErrorGet().
    01387         svc     (IN)     - the service context
    01388         table   (IN)     - pointer to the table object
    01389         type_ref   (OUT) - reference of the pk type. The reference must
    01390                            already be allocated.
    01391    REQUIRES:
    01392         - a valid OCI environment handle must be given.
    01393         - The specified table object must be pinned.
    01394         - The reference must already be allocated.
    01395    DESCRIPTION:
    01396         This function returns a reference to the pk type.  It returns an
    01397         error for values.  If the table is not a Pk oid table/view, then
    01398         it returns error.
    01399    RETURNS:
    01400         if environment handle or error handle is null, return
    01401         OCI_INVALID_HANDLE.
    01402         if operation suceeds, return OCI_SUCCESS.
    01403         if operation fails, return OCI_ERROR.
    01404  */
    01405
    01406 /*-------------------------- OCIObjectGetInd --------------------------------*/
    01407 sword OCIObjectGetInd(    OCIEnv *env, OCIError *err, dvoid *instance,
    01408                           dvoid **null_struct    );
    01409 /*
    01410    NAME: OCIObjectGetInd - OCI get the null structure of a standalone object
    01411    PARAMETERS:
    01412         env     (IN/OUT) - OCI environment handle initialized in object mode
    01413         err     (IN/OUT) - error handle. If there is an error, it is
    01414                            recorded in 'err' and this function returns
    01415                            OCI_ERROR.  The error recorded in 'err' can be
    01416                            retrieved by calling OCIErrorGet().
    01417         instance      (IN) - pointer to the instance
    01418         null_struct (OUT) - null structure
    01419    REQUIRES:
    01420         - a valid OCI environment handle must be given.
    01421         - The object must be standalone.
    01422         - If the object is referenceable, the specified object must be pinned.
    01423    DESCRIPTION:
    01424         This function returns the null structure of an instance. This function
    01425         will allocate the top level memory of the null structure if it is not
    01426         already allocated. If an null structure cannot be allocated for the
    01427         instance, then an error is returned. This function only works for
    01428         ADT or row type instance.
    01429    RETURNS:
    01430         if environment handle or error handle is null, return
    01431         OCI_INVALID_HANDLE.
    01432         if operation suceeds, return OCI_SUCCESS.
    01433         if operation fails, return OCI_ERROR.
    01434  */
    01435
    01436 /*------------------------- OCIObjectExists --------------------------------*/
    01437 sword OCIObjectExists(OCIEnv *env, OCIError *err, dvoid *ins, boolean *exist);
    01438 /*
    01439    NAME: OCIObjectExist - OCI checks if the object exists
    01440    PARAMETERS:
    01441         env       (IN/OUT) - OCI environment handle initialized in object mode
    01442         err       (IN/OUT) - error handle. If there is an error, it is
    01443                              recorded in 'err' and this function returns
    01444                              OCI_ERROR.  The error recorded in 'err' can be
    01445                              retrieved by calling OCIErrorGet().
    01446         ins           (IN) - pointer to an instance
    01447         exist        (OUT) - return TRUE if the object exists
    01448    REQUIRES:
    01449         - a valid OCI environment handle must be given.
    01450         - The object must be standalone.
    01451         - if object is a referenceable, it must be pinned.
    01452    DESCRIPTION:
    01453         This function returns the existence of an instance. If the instance
    01454         is a value, this function always returns TRUE.
    01455    RETURNS:
    01456         if environment handle or error handle is null, return
    01457         OCI_INVALID_HANDLE.
    01458         if operation suceeds, return OCI_SUCCESS.
    01459         if operation fails, return OCI_ERROR.
    01460  */
    01461
    01462 /*------------------------- OCIObjectGetProperty ---------------------------*/
    01463 sword OCIObjectGetProperty(OCIEnv *envh, OCIError *errh, CONST dvoid *obj,
    01464                            OCIObjectPropId propertyId,
    01465                            dvoid *property, ub4 *size );
    01466 /*
    01467    NAME: OCIObjectGetProperty - OCIObject Get Property of given object
    01468    PARAMETERS:
    01469         env       (IN/OUT) - OCI environment handle initialized in object mode
    01470         err       (IN/OUT) - error handle. If there is an error, it is
    01471                              recorded in 'err' and this function returns
    01472                              OCI_ERROR.  The error recorded in 'err' can be
    01473                              retrieved by calling OCIErrorGet().
    01474         obj           (IN) - object whose property is returned
    01475         propertyId    (IN) - id which identifies the desired property
    01476         property     (OUT) - buffer into which the desired property is
    01477                              copied
    01478         size      (IN/OUT) - on input specifies the size of the property buffer
    01479                              passed by caller, on output will contain the
    01480                              size in bytes of the property returned.
    01481                              This parameter is required for string type
    01482                              properties only (e.g OCI_OBJECTPROP_SCHEMA,
    01483                              OCI_OBJECTPROP_TABLE). For non-string
    01484                              properties this parameter is ignored since
    01485                              the size is fixed.
    01486    DESCRIPTION:
    01487         This function returns the specified property of the object.
    01488         The desired property is identified by 'propertyId'. The property
    01489         value is copied into 'property' and for string typed properties
    01490         the string size is returned via 'size'.
    01491
    01492         Objects are classified as persistent, transient and value
    01493         depending upon the lifetime and referenceability of the object.
    01494         Some of the properties are applicable only to persistent
    01495         objects and some others only apply to persistent and
    01496         transient objects. An error is returned if the user tries to
    01497         get a property which in not applicable to the given object.
    01498         To avoid such an error, the user should first check whether
    01499         the object is persistent or transient or value
    01500         (OCI_OBJECTPROP_LIFETIME property) and then appropriately
    01501         query for other properties.
    01502
    01503         The different property ids and the corresponding type of
    01504         'property' argument is given below.
    01505
    01506           OCI_OBJECTPROP_LIFETIME
    01507             This identifies whether the given object is a persistent
    01508             object (OCI_OBJECT_PERSISTENT) or a
    01509             transient object (OCI_OBJECT_TRANSIENT) or a
    01510             value instance (OCI_OBJECT_VALUE).
    01511             'property' argument must be a pointer to a variable of
    01512             type OCIObjectLifetime.
    01513
    01514           OCI_OBJECTPROP_SCHEMA
    01515             This returns the schema name of the table in which the
    01516             object exists. An error is returned if the given object
    01517             points to a transient instance or a value. If the input
    01518             buffer is not big enough to hold the schema name an error
    01519             is returned, the error message will communicate the
    01520             required size. Upon success, the size of the returned
    01521             schema name in bytes is returned via 'size'.
    01522             'property' argument must be an array of type text and 'size'
    01523             should be set to size of array in bytes by the caller.
    01524
    01525           OCI_OBJECTPROP_TABLE
    01526             This returns the table name in which the object exists. An
    01527             error is returned if the given object points to a
    01528             transient instance or a value. If the input buffer is not
    01529             big enough to hold the table name an error is returned,
    01530             the error message will communicate the required size. Upon
    01531             success, the size of the returned table name in bytes is
    01532             returned via 'size'. 'property' argument must be an array
    01533             of type text and 'size' should be set to size of array in
    01534             bytes by the caller.
    01535
    01536           OCI_OBJECTPROP_PIN_DURATION
    01537             This returns the pin duration of the object.
    01538             An error is returned if the given object points to a value
    01539             instance. Valid pin durations are: OCI_DURATION_SESSION and
    01540             OCI_DURATION_TRANS.
    01541             'property' argument must be a pointer to a variable of type
    01542             OCIDuration.
    01543
    01544           OCI_OBJECTPROP_ALLOC_DURATION
    01545             This returns the allocation duration of the object.
    01546             Valid allocation durations are: OCI_DURATION_SESSION and
    01547             OCI_DURATION_TRANS.
    01548             'property' argument must be a pointer to a variable of type
    01549             OCIDuration.
    01550
    01551           OCI_OBJECTPROP_LOCK
    01552             This returns the lock status of the
    01553             object. The possible lock status is enumerated by OCILockOpt.
    01554             An error is returned if the given object points to a transient
    01555             or value instance.
    01556             'property' argument must be a pointer to a variable of
    01557             type OCILockOpt.
    01558             Note, the lock status of an object can also be retrieved by
    01559             calling OCIObjectIsLocked().
    01560
    01561           OCI_OBJECTPROP_MARKSTATUS
    01562             This returns the status flag which indicates whether the
    01563             object is a new object, updated object and/or deleted object.
    01564             The following macros can be used to test the mark status
    01565             flag:
    01566
    01567               OCI_OBJECT_IS_UPDATED(flag)
    01568               OCI_OBJECT_IS_DELETED(flag)
    01569               OCI_OBJECT_IS_NEW(flag)
    01570               OCI_OBJECT_IS_DIRTY(flag)
    01571
    01572             An object is dirty if it is a new object or marked deleted or
    01573             marked updated.
    01574             An error is returned if the given object points to a transient
    01575             or value instance. 'property' argument must be of type
    01576             OCIObjectMarkStatus.
    01577
    01578           OCI_OBJECTPROP_VIEW
    01579             This identifies whether the specified object is a view object
    01580             or not. If property value returned is TRUE, it indicates the
    01581             object is a view otherwise it is not.
    01582             'property' argument must be of type boolean.
    01583
    01584    RETURNS:
    01585         if environment handle or error handle is null, return
    01586         OCI_INVALID_HANDLE.
    01587         if operation suceeds, return OCI_SUCCESS.
    01588         if operation fails, return OCI_ERROR. Possible errors are TBD
    01589  */
    01590
    01591 /*---------------------------- OCIObjectIsLocked --------------------------*/
    01592 sword OCIObjectIsLocked(    OCIEnv *env, OCIError *err, dvoid *ins,
    01593                               boolean *lock);
    01594 /*
    01595    NAME: OCIObjectIsLocked - OCI get the lock status of a standalone object
    01596    PARAMETERS:
    01597         env       (IN/OUT) - OCI environment handle initialized in object mode
    01598         err       (IN/OUT) - error handle. If there is an error, it is
    01599                              recorded in 'err' and this function returns
    01600                              OCI_ERROR.  The error recorded in 'err' can be
    01601                              retrieved by calling OCIErrorGet().
    01602         ins           (IN) - pointer to an instance
    01603         lock         (OUT) - return value for the lock status.
    01604    REQUIRES:
    01605         - a valid OCI environment handle must be given.
    01606         - The instance must be standalone.
    01607         - If the object is referenceable, the specified object must be pinned.
    01608    DESCRIPTION:
    01609         This function returns the lock status of an instance. If the instance
    01610         is a value, this function always returns FALSE.
    01611    RETURNS:
    01612         if environment handle or error handle is null, return
    01613         OCI_INVALID_HANDLE.
    01614         if operation suceeds, return OCI_SUCCESS.
    01615         if operation fails, return OCI_ERROR.
    01616  */
    01617
    01618 /*------------------------- OCIObjectIsDirty ------------------------------*/
    01619 sword OCIObjectIsDirty(    OCIEnv *env, OCIError *err, dvoid *ins,
    01620                            boolean *dirty);
    01621 /*
    01622    NAME: OCIObjectIsDirty - OCI get the dirty status of a standalone object
    01623    PARAMETERS:
    01624         env       (IN/OUT) - OCI environment handle initialized in object mode
    01625         err       (IN/OUT) - error handle. If there is an error, it is
    01626                              recorded in 'err' and this function returns
    01627                              OCI_ERROR.  The error recorded in 'err' can be
    01628                              retrieved by calling OCIErrorGet().
    01629         ins           (IN) - pointer to an instance
    01630         dirty        (OUT) - return value for the dirty status.
    01631    REQUIRES:
    01632         - a valid OCI environment handle must be given.
    01633         - The instance must be standalone.
    01634         - if instance is an object, the instance must be pinned.
    01635    DESCRIPTION:
    01636         This function returns the dirty status of an instance. If the instance
    01637         is a value, this function always returns FALSE.
    01638    RETURNS:
    01639         if environment handle or error handle is null, return
    01640         OCI_INVALID_HANDLE.
    01641         if operation suceeds, return OCI_SUCCESS.
    01642         if operation fails, return OCI_ERROR.
    01643  */
    01644
    01645 /*--------------------------- OCIObjectPinTable -----------------------------*/
    01646 sword OCIObjectPinTable(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01647                   CONST oratext *schema_name,
    01648                   ub4 s_n_length, CONST oratext *object_name, ub4 o_n_length,
    01649                   CONST OCIRef *scope_obj_ref, OCIDuration pin_duration,
    01650                   dvoid** object    );
    01651 /*
    01652    NAME: OCIObjectPinTable - OCI get table object
    01653    PARAMETERS:
    01654         env       (IN/OUT) - OCI environment handle initialized in object mode
    01655         err       (IN/OUT) - error handle. If there is an error, it is
    01656                              recorded in 'err' and this function returns
    01657                              OCI_ERROR.  The error recorded in 'err' can be
    01658                              retrieved by calling OCIErrorGet().
    01659         svc                     (IN) - OCI service context handle
    01660         schema_name   (IN, optional) - schema name of the table
    01661         s_n_length    (IN, optional) - length of the schema name
    01662         object_name   (IN) - name of the table
    01663         o_n_length    (IN) - length of the table name
    01664         scope_obj_ref (IN, optional) - reference of the scoping object
    01665         pin_duration  (IN) - pin duration. See description in OCIObjectPin().
    01666         object       (OUT) - the pinned table object
    01667    REQUIRES:
    01668         - a valid OCI environment handle must be given.
    01669    DESCRIPTION:
    01670         This function pin a table object with the specified pin duration.
    01671         The client can unpin the object by calling OCIObjectUnpin(). See
    01672         OCIObjectPin() and OCIObjectUnpin() for more information about pinning
    01673         and unpinning.
    01674    RETURNS:
    01675         if environment handle or error handle is null, return
    01676         OCI_INVALID_HANDLE.
    01677         if operation suceeds, return OCI_SUCCESS.
    01678         if operation fails, return OCI_ERROR.
    01679  */
    01680
    01681 /*------------------------- OCIObjectArrayPin -------------------------------*/
    01682 sword OCIObjectArrayPin(OCIEnv *env, OCIError *err, OCIRef **ref_array,
    01683                   ub4 array_size, OCIComplexObject **cor_array,
    01684                   ub4 cor_array_size, OCIPinOpt pin_option,
    01685                   OCIDuration pin_duration, OCILockOpt lock,
    01686                   dvoid **obj_array, ub4 *pos    );
    01687 /*
    01688    NAME: OCIObjectArrayPin - ORIO array pin
    01689    PARAMETERS:
    01690         env       (IN/OUT) - OCI environment handle initialized in object mode
    01691         err       (IN/OUT) - error handle. If there is an error, it is
    01692                              recorded in 'err' and this function returns
    01693                              OCI_ERROR.  The error recorded in 'err' can be
    01694                              retrieved by calling OCIErrorGet().
    01695         ref_array     (IN) - array of references to be pinned
    01696         array_size    (IN) - number of elements in the array of references
    01697         pin_option    (IN) - pin option. See OCIObjectPin().
    01698         pin_duration  (IN) - pin duration. See OCIObjectPin().
    01699         lock_option   (IN) - lock option. See OCIObjectPin().
    01700         obj_array    (OUT) - If this argument is not NULL, the pinned objects
    01701                              will be returned in the array. The user must
    01702                              allocate this array with element type being
    01703                              'dvoid *'. The size of this array is identical to
    01704                              'array'.
    01705         pos          (OUT) - If there is an error, this argument will contain
    01706                              the element that is causing the error.  Note that
    01707                              this argument is set to 1 for the first element in
    01708                              the ref_array.
    01709    REQUIRE:
    01710         - a valid OCI environment handle must be given.
    01711         - If 'obj_array' is not NULL, then it must already be allocated and
    01712              the size of 'obj_array' is 'array_size'.
    01713    DESCRIPTION:
    01714         This function pin an array of references.  All the pinned objects are
    01715         retrieved from the database in one network roundtrip.  If the user
    01716         specifies an output array ('obj_array'), then the address of the
    01717         pinned objects will be assigned to the elements in the array. See
    01718         OCIObjectPin() for more information about pinning.
    01719    RETURNS:
    01720         if environment handle or error handle is null, return
    01721         OCI_INVALID_HANDLE.
    01722         if operation suceeds, return OCI_SUCCESS.
    01723         if operation fails, return OCI_ERROR.
    01724  */
    01725
    01726 /*---------------------------------------------------------------------------*/
    01727 /*                           HEAP/CACHE OPERATIONS                           */
    01728 /*---------------------------------------------------------------------------*/
    01729
    01730 /*--------------------------- OCICacheFlush ---------------------------------*/
    01731 sword OCICacheFlush(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01732                   dvoid *context, OCIRef *(*get)(dvoid *context, ub1 *last),
    01733                   OCIRef **ref  );
    01734 /*
    01735    NAME: OCICacheFlush - OCI flush persistent objects
    01736    PARAMETERS:
    01737         env (IN/OUT) - OCI environment handle initialized in object mode
    01738         err (IN/OUT) - error handle. If there is an error, it is
    01739                       recorded in 'err' and this function returns
    01740                       OCI_ERROR.  The error recorded in 'err' can be
    01741                       retrieved by calling OCIErrorGet().
    01742         svc      (IN) [optional] - OCI service context.  If null pointer is
    01743                       specified, then the dirty objects in all connections
    01744                       will be flushed.
    01745         context  (IN) [optional] - specifies an user context that is an
    01746                       argument to the client callback function 'get'. This
    01747                       parameter is set to NULL if there is no user context.
    01748         get      (IN) [optional] - an client-defined function which acts an
    01749                       iterator to retrieve a batch of dirty objects that need
    01750                       to be flushed. If the function is not NULL, this function
    01751                       will be called to get a reference of a dirty object.
    01752                       This is repeated until a null reference is returned by
    01753                       the client function or the parameter 'last' is set to
    01754                       TRUE. The parameter 'context' is passed to get()
    01755                       for each invocation of the client function.  This
    01756                       parameter should be NULL if user callback is not given.
    01757                       If the object that is returned by the client function is
    01758                       not a dirtied persistent object, the object is ignored.
    01759                       All the objects that are returned from the client
    01760                       function must be from newed or pinned the same service
    01761                       context, otherwise, an error is signalled. Note that the
    01762                       returned objects are flushed in the order in which they
    01763                       are marked dirty.
    01764         ref     (OUT) [optional] - if there is an error in flushing the
    01765                       objects, (*ref) will point to the object that
    01766                       is causing the error.  If 'ref' is NULL, then the object
    01767                       will not be returned.  If '*ref' is NULL, then a
    01768                       reference will be allocated and set to point to the
    01769                       object.  If '*ref' is not NULL, then the reference of
    01770                       the object is copied into the given space. If the
    01771                       error is not caused by any of the dirtied object,
    01772                       the given ref is initalized to be a NULL reference
    01773                       (OCIRefIsNull(*ref) is TRUE).
    01774    REQUIRES:
    01775         - a valid OCI environment handle must be given.
    01776    DESCRIPTION:
    01777         This function flushes the modified persistent objects from the
    01778         environment heap to the server. The objects are flushed in the order
    01779         that they are marked updated or deleted.
    01780
    01781         See OCIObjectFlush() for more information about flushing.
    01782
    01783    RETURNS:
    01784         if environment handle or error handle is null, return
    01785         OCI_INVALID_HANDLE.
    01786         if operation suceeds, return OCI_SUCCESS.
    01787         if operation fails, return OCI_ERROR.
    01788  */
    01789
    01790 /*--------------------------- OCICacheRefresh -------------------------------*/
    01791 sword OCICacheRefresh(OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01792                   OCIRefreshOpt option, dvoid *context,
    01793                   OCIRef *(*get)(dvoid *context), OCIRef **ref);
    01794 /*
    01795    NAME: OCICacheRefresh - OCI ReFreSh persistent objects
    01796    PARAMETERS:
    01797         env (IN/OUT) - OCI environment handle initialized in object mode
    01798         err (IN/OUT) - error handle. If there is an error, it is
    01799                        recorded in 'err' and this function returns
    01800                        OCI_ERROR.  The error recorded in 'err' can be
    01801                        retrieved by calling OCIErrorGet().
    01802         svc     (IN) [optional] - OCI service context.  If null pointer is
    01803                       specified, then the persistent objects in all connections
    01804                       will be refreshed.
    01805         option   (IN) [optional] - if OCI_REFRESH_LOAD is specified, all
    01806                       objects that is loaded within the transaction are
    01807                       refreshed. If the option is OCI_REFERSH_LOAD and the
    01808                       parameter 'get' is not NULL, this function will ignore
    01809                       the parameter.
    01810         context  (IN) [optional] - specifies an user context that is an
    01811                       argument to the client callback function 'get'. This
    01812                       parameter is set to NULL if there is no user context.
    01813         get      (IN) [optional] - an client-defined function which acts an
    01814                       iterator to retrieve a batch of objects that need to be
    01815                       refreshed. If the function is not NULL, this function
    01816                       will be called to get a reference of an object.  If
    01817                       the reference is not NULL, then the object will be
    01818                       refreshed.  These steps are repeated until a null
    01819                       reference is returned by this function.  The parameter
    01820                       'context' is passed to get() for each invocation of the
    01821                       client function.  This parameter should be NULL if user
    01822                       callback is not given.
    01823         ref     (OUT) [optional] - if there is an error in refreshing the
    01824                       objects, (*ref) will point to the object that
    01825                       is causing the error.  If 'ref' is NULL, then the object
    01826                       will not be returned.  If '*ref' is NULL, then a
    01827                       reference will be allocated and set to point to the
    01828                       object.  If '*ref' is not NULL, then the reference of
    01829                       the object is copied into the given space. If the
    01830                       error is not caused by any of the object,
    01831                       the given ref is initalized to be a NULL reference
    01832                       (OCIRefIsNull(*ref) is TRUE).
    01833    REQUIRES:
    01834         - a valid OCI environment handle must be given.
    01835    DESCRIPTION:
    01836         This function refreshes all pinned persistent objects. All unpinned
    01837         persistent objects are freed.  See OCIObjectRefresh() for more
    01838         information about refreshing.
    01839    RETURNS:
    01840         if environment handle or error handle is null, return
    01841         OCI_INVALID_HANDLE.
    01842         if operation suceeds, return OCI_SUCCESS.
    01843         if operation fails, return OCI_ERROR.
    01844  */
    01845
    01846 /*---------------------------- OCICacheUnpin --------------------------------*/
    01847 sword OCICacheUnpin(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc    );
    01848 /*
    01849    NAME: OCICacheUnpin - OCI UNPin objects
    01850    PARAMETERS:
    01851         env (IN/OUT) - OCI environment handle initialized in object mode
    01852         err (IN/OUT) - error handle. If there is an error, it is
    01853                        recorded in 'err' and this function returns
    01854                        OCI_ERROR.  The error recorded in 'err' can be
    01855                        retrieved by calling OCIErrorGet().
    01856         svc     (IN) [optional] - OCI service context. If null pointer is
    01857                        specified, then the objects in all connections
    01858                        will be unpinned.
    01859    REQUIRES:
    01860         - a valid OCI environment handle must be given.
    01861    DESCRIPTION:
    01862         If a connection is specified, this function completely unpins the
    01863         persistent objects in that connection. Otherwise, all persistent
    01864         objects in the heap are completely unpinned. All transient objects in
    01865         the heap are also completely unpinned. See OCIObjectUnpin() for more
    01866         information about unpinning.
    01867    RETURNS:
    01868         if environment handle or error handle is null, return
    01869         OCI_INVALID_HANDLE.
    01870         if operation suceeds, return OCI_SUCCESS.
    01871         if operation fails, return OCI_ERROR.
    01872  */
    01873
    01874 /*----------------------------- OCICacheFree --------------------------------*/
    01875 sword OCICacheFree(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc    );
    01876 /*
    01877    NAME: OCICacheFree - OCI FREe instances
    01878    PARAMETERS:
    01879         env (IN/OUT) - OCI environment handle initialized in object mode
    01880         err (IN/OUT) - error handle. If there is an error, it is
    01881                        recorded in 'err' and this function returns
    01882                        OCI_ERROR.  The error recorded in 'err' can be
    01883                        retrieved by calling OCIErrorGet().
    01884         svc     (IN) [optional] - OCI service context. If null pointer is
    01885                        specified, then the objects in all connections
    01886                        will be freed.
    01887    REQUIRES:
    01888         - a valid OCI environment handle must be given.
    01889    DESCRIPTION:
    01890         If a connection is specified, this function frees the persistent
    01891         objects, transient objects and values allocated for that connection.
    01892         Otherwise, all persistent objects, transient objects and values in the
    01893         heap are freed. Objects are freed regardless of their pin count.  See
    01894         OCIObjectFree() for more information about freeing an instance.
    01895    RETURNS:
    01896         if environment handle or error handle is null, return
    01897         OCI_INVALID_HANDLE.
    01898         if operation suceeds, return OCI_SUCCESS.
    01899         if operation fails, return OCI_ERROR.
    01900 */
    01901
    01902 /*---------------------------- OCICacheUnmark -------------------------------*/
    01903 sword OCICacheUnmark(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc    );
    01904 /*
    01905    NAME: OCICacheUnmark - OCI Unmark all dirty objects
    01906    PARAMETERS:
    01907         env (IN/OUT) - OCI environment handle initialized in object mode
    01908         err (IN/OUT) - error handle. If there is an error, it is
    01909                        recorded in 'err' and this function returns
    01910                        OCI_ERROR.  The error recorded in 'err' can be
    01911                        retrieved by calling OCIErrorGet().
    01912         svc     (IN) [optional] - OCI service context. If null pointer is
    01913                        specified, then the objects in all connections
    01914                        will be unmarked.
    01915    REQUIRES:
    01916         - a valid OCI environment handle must be given.
    01917    DESCRIPTION:
    01918         If a connection is specified, this function unmarks all dirty objects
    01919         in that connection.  Otherwise, all dirty objects in the cache are
    01920         unmarked. See OCIObjectUnmark() for more information about unmarking
    01921         an object.
    01922    RETURNS:
    01923         if environment handle or error handle is null, return
    01924         OCI_INVALID_HANDLE.
    01925         if operation suceeds, return OCI_SUCCESS.
    01926         if operation fails, return OCI_ERROR.
    01927  */
    01928
    01929
    01930 sword OCIDurationBegin(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01931                            OCIDuration parent, OCIDuration *dur    );
    01932 /*
    01933    NAME: OCIDurationBegin - OCI DURATION BEGIN
    01934    PARAMETERS:
    01935         env  (IN/OUT) - OCI environment handle initialized in object mode
    01936                         This should be passed NULL, when cartridge services
    01937                         are to be used.
    01938         err  (IN/OUT) - error handle. If there is an error, it is
    01939                         recorded in 'err' and this function returns OCI_ERROR.
    01940                         The error recorded in 'err' can be retrieved by calling
    01941                        OCIErrorGet().
    01942         svc  (IN/OUT) - OCI service handle.
    01943         parent   (IN) - parent for the duration to be started.
    01944         dur     (OUT) - newly created user duration
    01945    REQUIRES:
    01946         - a valid OCI environment handle must be given for non-cartridge
    01947           services.
    01948         - For cartridge services, NULL should be given for environment handle
    01949         - A valid service handle must be given in all cases.
    01950    DESCRIPTION:
    01951         This function starts a new user duration.  A user can have multiple
    01952         active user durations simultaneously. The user durations do not have
    01953         to be nested.
    01954
    01955         The object subsystem predefines 3 durations :
    01956           1) session     - memory allocated with session duration comes from
    01957                            the UGA heap (OCI_DURATION_SESSION). A session
    01958                            duration terminates at the end of the user session.
    01959           2) transaction - memory allocated with transaction duration comes
    01960                            from the UGA heap (OCI_DURATION_TRANS). A trans-
    01961                            action duration terminates at the end of the user
    01962                            transaction.
    01963           3) call        - memory allocated with call duration comes from PGA
    01964                            heap (OCI_DURATION_CALL). A call duration terminates
    01965                            at the end of the user call.
    01966
    01967         Each user duration has a parent duration.  A parent duration can be a
    01968         predefined duration or another user duration.  The relationship between
    01969         a user duration and its parent duration (child duration) are:
    01970
    01971          1) An user duration is nested within the parent duration. When its
    01972              parent duration terminates, the user duration will also terminate.
    01973          2) The memory allocated with an user duration comes from the heap of
    01974              its parent duration. For example, if the parent duration of an
    01975              user duration is call, then the memory allocated with the user
    01976              duration will also come from the PGA heap.
    01977
    01978         This function can be used as both part of cartridge services as well
    01979         as without cartridge services.
    01980         The difference in the function in the case of cartridge and
    01981         non-cartridge services is:
    01982                 In case of cartridge services, as descibed above a new user
    01983         duration is created as a child of the "parent" duration.
    01984                 But when used for non-cartridge purposes, when a pre-defined
    01985         duration is passed in as parent, it is mapped to the cache duration
    01986         for that connection (which is created if not already present) and
    01987         the new user duration will be child of the cache duration.
    01988
    01989    RETURNS:
    01990         if environment handle and service handle is null or if error
    01991         handle is null return OCI_INVALID_HANDLE.
    01992         if operation suceeds, return OCI_SUCCESS.
    01993         if operation fails, return OCI_ERROR.
    01994  */
    01995
    01996
    01997 sword OCIDurationEnd(    OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
    01998                          OCIDuration duration    );
    01999 /*
    02000    NAME: OCIDurationEnd - OCI DURATION END
    02001    PARAMETERS:
    02002         env  (IN/OUT) - OCI environment handle initialized in object mode
    02003                         This should be passed NULL, when cartridge services
    02004                         are to be used.
    02005         err  (IN/OUT) - error handle. If there is an error, it is
    02006                         recorded in 'err' and this function returns OCI_ERROR.
    02007                         The error recorded in 'err' can be retrieved by calling
    02008                        OCIErrorGet().
    02009         svc  (IN/OUT) - OCI service handle.
    02010         dur     (OUT) - a previously created user duration using
    02011                         OCIDurationBegin()
    02012    REQUIRES:
    02013         - a valid OCI environment handle must be given for non-cartridge
    02014           services.
    02015         - For cartridge services, NULL should be given for environment handle
    02016         - A valid service handle must be given in all cases.
    02017    DESCRIPTION:
    02018         This function terminates a user duration.  All memory allocated for
    02019         this duration is freed.
    02020
    02021         This function can be used as both part of cartridge services as well
    02022         as without cartridge services.  In both cased, the heap duration
    02023         is freed and all the allocated memory for that duration is freed.
    02024         The difference in the function in the case of cartridge and
    02025         non-cartridge services is:
    02026                 In case of non-cartridge services, if the duration is pre-
    02027         defined, the associated cache duration (see OCIDurationBegin())
    02028         is also terminated and the following is done.
    02029           1) The child durations are terminated.
    02030           2) All objects pinned for this duration are unpinned.
    02031           3) All instances allocated for this duration are freed.
    02032
    02033                 In case of cartridge services, only the heap duration is
    02034         freed.  All the context entries allocated for that duration are
    02035         freed from the context hash table..
    02036
    02037    RETURNS:
    02038         if environment handle and service handle is null or if error
    02039         handle is null return OCI_INVALID_HANDLE.
    02040         if operation suceeds, return OCI_SUCCESS.
    02041         if operation fails, return OCI_ERROR.
    02042  */
    02043
    02044 /******************************************************************************
    02045 **          DO  NOT  USE  THE  FUNCTIONS  BELOW!                             **
    02046 **          UNSUPPORTED INTERFACE                                            **
    02047 **          WILL BE REMOVED/CHANGED IN A FUTURE RELEASE                      **
    02048 ******************************************************************************/
    02049
    02050 sword OCIDurationGetParent(    OCIEnv *env, OCIError *err,
    02051                                OCIDuration duration, OCIDuration *parent    );
    02052
    02053 sword OCIObjectAlwaysLatest(    OCIEnv *env, OCIError *err, dvoid *object    );
    02054
    02055 sword OCIObjectNotAlwaysLatest(    OCIEnv *env, OCIError *err,
    02056                                    dvoid *object    );
    02057
    02058 sword OCIObjectFlushRefresh(    OCIEnv *env, OCIError *err, dvoid *object);
    02059
    02060 sword OCIObjectIsLoaded(    OCIEnv *env, OCIError *err, dvoid *ins,
    02061                               boolean *load);
    02062
    02063 sword OCIObjectIsDirtied(    OCIEnv *env, OCIError *err, dvoid *ins,
    02064                               boolean *dirty);
    02065
    02066 sword OCICacheGetObjects(       OCIEnv *env, OCIError *err,
    02067                                 CONST OCISvcCtx *svc,
    02068                                 OCIObjectProperty property,
    02069                                 dvoid *client_context,
    02070                                 void (*client_callback)(
    02071                                     dvoid *client_context,
    02072                                     dvoid *object  ));
    02073
    02074 sword OCICacheRegister(      OCIEnv *env, OCIError *err,
    02075                              OCIObjectEvent event,
    02076                              dvoid *client_context,
    02077                              void (*client_callback)(
    02078                                     dvoid *client_context,
    02079                                     OCIObjectEvent event,
    02080                                     dvoid *object));
    02081
    02082 sword OCICacheFlushRefresh(    OCIEnv *env, OCIError *err,
    02083                                CONST OCISvcCtx *svc, dvoid *context,
    02084                                OCIRef *(*get)(dvoid *context, ub1 *last),
    02085                                OCIRef **ref    );
    02086
    02087 sword OCIObjectSetData(OCIEnv *env, OCIError *err, dvoid *obj_hdr,
    02088         dvoid *data);
    02089
    02090 sword OCIObjectGetNewOID(OCIEnv *env, OCIError *err, OCISvcCtx *svc,
    02091         ub1 *oid);
    02092
    02093
    02094 #endif /* ORI_ORACLE */

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines