Annotation of win32/sql/oracle/include/oci/ori.h, revision 1.1
1.1 ! parser 1: /* Copyright (c) Oracle Corporation 1994, 1996, 1997, 1998, 1999. All Rights Reserved. */
! 2:
! 3: /*
! 4: NAME
! 5: ORI - OCI navigational interface
! 6:
! 7: DESCRIPTION
! 8:
! 9: This section is intended to give a brief introduction to the navigational
! 10: interfaces. Readers can refer to the documents listed in the section
! 11: 'RELATED DOCUMENTS' for more information.
! 12:
! 13: PURPOSE
! 14: The Oracle Call Interface (OCI) supports navigational access of objects.
! 15: In the navigational paradigm, data is represented as a graph of objects
! 16: connected by references. Objects in the graph are reached by following
! 17: the references.
! 18:
! 19: OBJECT ENVIRONMENT
! 20:
! 21: The object environment is initialized when the OCI environment handle is
! 22: initialized with the object option. An object environment contains a
! 23: heap which buffers type instances in memory. The object environment also
! 24: contains an object cache which keeps track of the objects in the object
! 25: environment. Readers can refer to the "Functional Specification for
! 26: Programmatic Interface" for more information about the object
! 27: environment.
! 28:
! 29: INSTANCE, OBJECT AND VALUE
! 30:
! 31: An OTS instance is an occurence of a type specified by the Oracle Type
! 32: System (OTS). This section describes how an OTS instance can be
! 33: represented in OCI. In OCI, an OTS instance can be classified based on
! 34: the type, the lifetime and referencability (see the figure below):
! 35:
! 36: 1) A persistent object is an instance of an object type. A persistent
! 37: object resides in a row of a table in the server and can exist longer
! 38: than the duration of a session (connection). Persistent objects can be
! 39: identified by object references which contain the object identifiers.
! 40: A persistent object is obtained by pinning its object reference.
! 41:
! 42: 2) A transient object is an instance of an object type. A transient
! 43: object cannot exist longer than the duration of a session, and it is
! 44: used to contain temporary computing results. Transient objects can
! 45: also be identified by references which contain transient object
! 46: identifiers.
! 47:
! 48: 3) A value is an instance of an user-defined type (object type or
! 49: collection type) or any built-in OTS type. Unlike objects, values of
! 50: object types are identified by memory pointers, rather than by
! 51: references.
! 52:
! 53: A value can be standalone or embbeded. A standalone value is usually
! 54: obtained by issuing a select statement. OCI also allows the client
! 55: program to select a row of object table into a value by issuing a SQL
! 56: statement. Thus, a referenceable object (in the database) can be
! 57: represented as a value (which cannot be identified by a reference).
! 58: A standalone value can also be an out-of-line attribute in an object
! 59: (e.g varchar, raw) or an out-of-line element in a collection (e.g.
! 60: varchar, raw, object).
! 61:
! 62: An embedded value is phyiscally included in a containing instance.
! 63: An embedded value can be an in-line attribute in an object (e.g.
! 64: number, nested object) or an in-line element in a collection.
! 65:
! 66: All values are considered to be transient by OCI, e.g. OCI does not
! 67: support automatic flushing a value to the database, and the client has
! 68: to explicitly execute a SQL statement to store a value into the
! 69: database. For embedded values, they are flushed when their containing
! 70: instance are flushed.
! 71:
! 72:
! 73: OTS instance
! 74: | |
! 75: v v
! 76: object value (type)
! 77: | |
! 78: v v
! 79: persistent transient (lifetime)
! 80:
! 81:
! 82: persistent obj transient obj value
! 83: ---------------------------------------------------------------
! 84: | | | | object type, |
! 85: | type | object type | object type | built-in, |
! 86: | | | | collection |
! 87: ---------------------------------------------------------------
! 88: | maximum | until object | session | session |
! 89: | lifetime | is deleted | | |
! 90: ---------------------------------------------------------------
! 91: | referencable | yes | yes | no |
! 92: ---------------------------------------------------------------
! 93: | embeddable | no | no | yes |
! 94: ---------------------------------------------------------------
! 95:
! 96: REFERENCEABLE OBJECT, STANDALONE OBJECT, EMBEDDED OBJECT
! 97:
! 98: In the reminding of this include file, the following term will be used:
! 99: 1) The term 'object' can be generally referred to a persistent object,
! 100: a transient object, a standalone value of object type, or an embedded
! 101: value of object type.
! 102: 2) The term 'referenceable object' refers to a persistent object or a
! 103: transient object.
! 104: 3) The term 'standalone object' refers to a persistent object, a
! 105: transient object or a standalone value of object type.
! 106: 4) The term 'embedded object' referes to a embbeded value of object
! 107: type.
! 108:
! 109: META ATTRIBUTES
! 110:
! 111: There is a set of meta-attributes that are defined for standalone
! 112: objects. A meta-attribute can be transient or persistent. A
! 113: transient meta-attribute is applicable to an instance only when it is
! 114: in memory. A persistent meta-attribute can be applicable to an instance
! 115: that is in the disk.
! 116:
! 117: The set of user visible meta-attributes for persistent objects are:
! 118: 1) existent (persistent) : Does the object exist?
! 119: 2) nullness (persistent) : Null information of the instance
! 120: 3) locked (persistent) : Is the object locked?
! 121: 4) pinned (transient) : Is the object being accessed by the client?
! 122: 5) dirty (transient) : Has the object been modified?
! 123: 6) allocation duration (transient) : see below
! 124: 7) pin duration (transient) : see below
! 125:
! 126: The set of user visible meta-attributes for transient objects are:
! 127: 1) existent (transient) : Does the object exist?
! 128: 2) nullness (transient) : Null information of the instance
! 129: 3) pinned (transient) : Is the object being accessed by the client?
! 130: 4) dirty (transient) : Has the object been modified?
! 131: 4) allocation duration (transient) : see below
! 132: 5) pin duration (transient) : see below
! 133:
! 134: The set of user visible meta-attributes for standalone values of object
! 135: type or collections are:
! 136: 1) allocation duration (transient) : see below
! 137: 2) nullness (transient) : Null information of the instance
! 138: (of an object type)
! 139:
! 140: NULLNESS OF AN INSTANCE
! 141:
! 142: Each standalone object is associated with a null structure which keeps
! 143: the null information about the object. A null indicates the absence of
! 144: data. The null structure itself contains null indicators that represent:
! 145: 1) atomic nullness : a null value that pertains to the whole object
! 146: 2) null status of the individual attribute in the object
! 147:
! 148: The layout of a null structure in memory resembles that of the object,
! 149: except that the null structure has additional indicators to represent
! 150: the atomic nullness for each object.
! 151:
! 152: An non-existent object is different than an object that is atomically
! 153: null. A atomically null object is an existing object that has no data.
! 154:
! 155: MEMORY LAYOUT OF AN OBJECT
! 156:
! 157: A standalone object in memory is composed of a top level memory chunk,
! 158: a null structure and optionally, a number of secondary memory chunks.
! 159: For a DEPARTMENT object type,
! 160:
! 161: OBJECT TYPE department
! 162: {
! 163: dep_name varchar2(20),
! 164: budget number,
! 165: manager person, /o person is an object type o/
! 166: employees collection of person
! 167: }
! 168:
! 169: Each instance of DEPARTMENT will has a top level memory chunk which
! 170: contains the top level attributes such as dep_name, budget, manager and
! 171: employees. The attributes dep_name and employees are themselves pointers
! 172: to the additional memory (the secondary memory chunks). The secondary
! 173: memory is for the out-of-line attribute (e.g. varray).
! 174:
! 175: CONSISTENCY MODEL
! 176:
! 177: Each pin operation behaves like a distinct SQL select. Thus, the object
! 178: cache does not guarantee consistency for a graph of objects. In order to
! 179: retrieve a consistent graph of objects, the user has to explicitly start
! 180: a serializable transaction or a read-only transaction.
! 181:
! 182: DURATION
! 183: In OCI, a duration is used to specify
! 184:
! 185: 1) the length of memory allocation of an instance
! 186: When each instance is allocated, it is associate with an allocation
! 187: duration. The memory occupied by the object is freed automatically
! 188: at the end of its allocation duration. The allocation duration of an
! 189: instance cannot be changed.
! 190:
! 191: 2) the length of pinning of an object
! 192: When each object is pinned, the client has to give a pin duration
! 193: which specify the length of time that the object is intended to be
! 194: used. It is an user error to specify a pin duration longer than an
! 195: allocation duration of the object. An object is completely unpinned
! 196: at the end of its pin duration (see OCIObjectUnpin()).
! 197:
! 198: An OCI program can use the allocation duration and the pin duration to
! 199: automatically free the memory of the instances:
! 200: 1) Transient objects and values are freed at the end of the allocation
! 201: duration.
! 202: 2) Persistent objects ARE freed at the end of the allocation duration.
! 203: Persistent objects CAN be freed at the end of the pin duration when
! 204: the objects are completely unpinned. The persistent objects are said
! 205: to be aged out. See OCIObjectUnpin() for more details.
! 206:
! 207: There are 3 predefined duration: session, transaction, call. The time
! 208: spans of these durations are defined based on the programming model
! 209: presented by OCI. The call duration is mapped to the transaction
! 210: duration in the client-side environment. See oro.h for the macros defined
! 211: for these 3 durations.
! 212:
! 213: A pin duration can be promoted. For example, if an object is pinned with
! 214: duration 1, and the object is later pinned with duration 2, the pin
! 215: routine will try to find a duration that is longer or equal to the
! 216: length of both duration 1 and duration 2. The pin duration of the object
! 217: is set to the that duration. The object is automatically unpinned only
! 218: after both duration 1 and duration 2 are terminated.
! 219:
! 220: RELATED DOCUMENTS
! 221: "Functional Specification for Oracle Object RDBMS"
! 222: "Functional Specification for Programmatic Interfaces"
! 223: "Functional Specification for the Oracle Type System (OTS)"
! 224:
! 225: INSPECTION STATUS
! 226: Inspection date:
! 227: Inspection status:
! 228: Estimated increasing cost defects per page:
! 229: Rule sets:
! 230:
! 231: ACCEPTANCE REVIEW STATUS
! 232: Review date:
! 233: Review status:
! 234: Reviewers:
! 235:
! 236: PUBLIC FUNCTIONS
! 237: OCIObjectNew - OCI new a standalone instance
! 238: OCIObjectPin - OCI pin an object by reference
! 239: OCIObjectUnpin - OCI unpin a referenceable object
! 240: OCIObjectPinCountReset - OCI reset the pin count of a referenceable object
! 241: OCIObjectLock - OCI lock a persistent object
! 242: OCIObjectLockNoWait - OCI lock a persistent object
! 243: OCIObjectMarkUpdate - OCI mark a referenceable object as updated
! 244: OCIObjectUnmark - OCI unmark a dirtied referenceable object
! 245: OCIObjectUnmarkByRef - OCI unmark a dirtied object by reference
! 246: OCIObjectFree - OCI free a standalone instance
! 247: OCIObjectMarkDelete - OCI mark a referenceable object as deleted
! 248: OCIObjectMarkDeleteByRef - OCI mark a referenceable object as deleted by
! 249: giving a reference
! 250: OCIObjectFlush - OCI flush a persistent object
! 251: OCIObjectRefresh - OCI refresh a persistent object
! 252: OCIObjectCopy - OCI CoPy one object to another
! 253: OCIObjectGetTypeRef - OCI get the Type Reference of a standalone object
! 254: OCIObjectGetObjectRef - OCI get the Object's Reference
! 255: OCIObjectGetInd - OCI get Null Structure of an standalone object
! 256: OCIObjectExists - OCI get the existence of a referenceable object
! 257: OCIObjectGetProperty - get object property
! 258: OCIObjectIsLocked - OCI get the lock status of a referenceable object
! 259: OCIObjectIsDirty - OCI get the dirty status of a referenceable object
! 260: OCIObjectPinTable - OCI get Table object
! 261: OCIObjectArrayPin - OCI pin array of objects
! 262: OCIObjectGetPrimayKeyTypeRef - OCI get the Ref for the primary key OID's type
! 263: OCIObjectMakeObjectRef - OCI Create a pk or sys generated REF
! 264:
! 265: OCICacheFlush - OCI flsuh the modified persistent objects in the cache
! 266: OCICacheRefresh - OCI refresh persistent objects in the cache
! 267: OCICacheUnpin - OCI unpin referenceable objects in the cache
! 268: OCICacheFree - OCI free all instances in the environment
! 269: OCICacheUnmark - OCI unmark all dirty referenceable objects in the cache
! 270:
! 271: PRIVATE FUNCTIONS
! 272: None
! 273:
! 274: EXAMPLES
! 275:
! 276: The following types will be used in the examples in this section:
! 277:
! 278: OBJECT TYPE professor
! 279: (
! 280: varchar2 name;
! 281: number department;
! 282: number num_of_students;
! 283: );
! 284:
! 285: OBJECT TYPE course
! 286: (
! 287: varchar2 name;
! 288: number grade;
! 289: );
! 290:
! 291: OBJECT TYPE student
! 292: (
! 293: vstring name;
! 294: number department;
! 295: ref advisor; /o advisor is a professor o/
! 296: collection courses;
! 297: );
! 298:
! 299: EXAMPLE 1
! 300:
! 301: Here is a set of examples to illustrate the usages of some of the
! 302: orio and oric functions.
! 303:
! 304: OCIenv *env; /o OCI environment handle o/
! 305: OCIError *err; /o OCI error handle o/
! 306: OCISvcCtx *svc; /o OCI service handle o/
! 307:
! 308: dvoid *stu_tbl; /o pointer to the student table o/
! 309: OCIType *stu_tdo; /o student type tdo o/
! 310:
! 311: OCIRef *stu2_ref; /o object reference to student object o/
! 312: student *stu1; /o pointer to the student object o/
! 313: student *stu2; /o pointer to the student object o/
! 314: professor *pro; /o pointer to the professor object o/
! 315:
! 316: /o Initialize the OCI environment handle, error handle and service
! 317: handle and login to the database o/
! 318: ...
! 319:
! 320: /o CREATE A PERSISTENT OBJECT o/
! 321:
! 322: /o get the table object of student o/
! 323: if (OCIObjectPinTable(env, err, svc, "ORACLEU", sizeof("ORACLEU"),
! 324: "STUDENT_TABLE", sizeof("STUDENT_TABLE"), (OCIRef *)0,
! 325: OCI_DURATION_NULL, &stu_tbl) != OCI_SUCCESS)
! 326: /o error handling code o/
! 327:
! 328: /o get type object of student o/
! 329: if (OCITypeByName(env, err, svc, "ORACLEU", sizeof("ORACLEU"),
! 330: "STUDENT", sizeof("STUDENT"), OCI_DURATION_NULL, OCI_TYPEGET_HEADER,
! 331: &stu_tdo) != OCI_SUCCESS)
! 332: /o error handling code o/
! 333:
! 334: /o create a persistent object 'mark' (of type student) o/
! 335: if (OCIObjectNew(env, err, svc, OCI_TYPECODE_ADT, stu_tdo, stu_tbl,
! 336: OCI_DURATION_TRANS, (ub1)FALSE, (dvoid **)&stu1) != OCI_SUCCESS)
! 337: /o error handling code o/
! 338:
! 339: /o RETRIEVE OBJECTS IN PERSISTENT STORES o/
! 340:
! 341: /o Use OCI to retrieve a reference to student object 'joe'.
! 342: o The retrieved reference is bound to the variable stu2_ref.
! 343: o/
! 344:
! 345: /o pin/retrieve the student "joe" by reference o/
! 346: if (OCIObjectPin(env, err, &stu2_ref, (OCIComplexObject *)0, OCI_PIN_ANY,
! 347: OCI_DURATION_TRANS, OCI_LOCK_X, &stu2) != OCI_SUCCESS)
! 348: /o error handling code o/
! 349:
! 350: /o pin/retrieve the advisor of student "joe" by reference o/
! 351: if (OCIObjectPin(env, err, &stu2->advisor, (OCIComplexObject *)0,
! 352: OCI_PIN_ANY, OCI_DURATION_TRANS, OCI_LOCK_X, &pro) != OCI_SUCCESS)
! 353: /o error handling code o/
! 354:
! 355: /o MODIFY OBJECTS o/
! 356:
! 357: /o initialize the newly created object "mark" o/
! 358: DISCARD OCIStringAssignText(env, err, "mark", sizeof("mark"),
! 359: &stu1->name);
! 360: department = 522;
! 361: DISCARD OCINumberFromInt(err, &department, sizeof(department),
! 362: OCI_NUMBER_UNSIGNED, &stu1->department);
! 363:
! 364: /o assign advisor to student "mark" o/
! 365: DISCARD OCIRefAssign(env, err, &stu2->advisor, &stu1->advisor);
! 366:
! 367: /o update student "joe". o/
! 368: department = 533;
! 369: DISCARD OCINumberFromInt(err, &department, sizeof(department),
! 370: OCI_NUMBER_UNSIGNED, &stu2->department);
! 371: DISCARD OCIObjectMarkUpdate(env, err, stu2);
! 372:
! 373: /o UNPIN OBJECTS AFTER FINSIHED PROCESSING THEM o/
! 374:
! 375: /o unpin the student object "mark" o/
! 376: if (OCIObjectUnpin(env, err, stu1) != OCI_SUCCESS)
! 377: /o error handling code o/
! 378:
! 379: /o unpin the student object "joe" o/
! 380: if (OCIObjectUnpin(env, err, stu2) != OCI_SUCCESS)
! 381: /o error handling code o/
! 382:
! 383: /o unpin the professor object o/
! 384: if (OCIObjectUnpin(env, err, pro) != OCI_SUCCESS)
! 385: /o error handling code o/
! 386:
! 387: /o unpin the type object o/
! 388: if (OCIObjectUnpin(env, err, stu_tdo) != OCI_SUCCESS)
! 389: /o error handling code o/
! 390:
! 391: /o unpin the table object o/
! 392: if (OCIObjectUnpin(env, err, stu_tbl) != OCI_SUCCESS)
! 393: /o error handling code o/
! 394:
! 395: /o FLUSH MODIFIED OBJECTS BACK TO PERSISTENT STORE o/
! 396:
! 397: if (OCICacheFlush(env, err, svc, (dvoid *)0, ((OCIRef*)(*)())0,
! 398: (OCIRef *)0) != OCI_SUCCESS)
! 399: /o error handling code o/
! 400:
! 401: /o commit transaction o/
! 402:
! 403: END OF EXAMPLE 1
! 404:
! 405: NOTES
! 406: This file has been subsetted to contain only the routines that will
! 407: be in the first release.
! 408:
! 409: MODIFIED
! 410: whe 09/01/99 - 976457:check __cplusplus for C++ code
! 411: smuralid 10/29/98 - add comments for OCIObjectMakeObjectRef
! 412: mkrishna 08/19/98 - change OCIGetPkTypeRef to OCIObjectGetPrimaryKeyTypeR
! 413: mkrishna 08/10/98 - add OCIObjectMakeObjectRef & OCIObjectGetPkTypeRef
! 414: rkasamse 06/22/98 - add comments for OCIDurationBegin(End)
! 415: pmitra 04/01/98 - OCIObjectLockNoWait added
! 416: pmitra 11/05/97 - [573769] OCIObjectArrayPin pos parameter cannot be NU
! 417: cxcheng 07/29/97 - fix compile for short names
! 418: skrishna 07/14/97 - add OCIObjectGetProperty
! 419: skrishna 04/30/97 - OCIObjectFlushRefresh: remove duplicate declaration
! 420: skrishna 04/24/97 - flag unsupported functions
! 421: sthakur 03/20/97 - modify flag argument to OCIObjectFree
! 422: skrishna 03/18/97 - fix ifdef for supporting ansi and k&r proto-types
! 423: cxcheng 02/19/97 - remove short names support
! 424: cxcheng 02/06/97 - take out short name support except with SLSHORTNAME
! 425: sthakur 12/20/96 - fix a typepo in OCIOBjectArrayPin
! 426: jboonleu 11/07/96 - modify comments
! 427: cxcheng 10/28/96 - more beautification changes
! 428: jboonleu 10/24/96 - add flag to OCIObjectFree
! 429: jboonleu 10/22/96 - change interface of OCICacheFlush
! 430: cxcheng 10/18/96 - rename OCIObjectPinArray to OCIObjectArrayPin
! 431: cxcheng 10/14/96 - more renaming of types
! 432: jboonleu 10/09/96 - add new interfaces
! 433: cxcheng 10/09/96 - more lint fixes
! 434: cxcheng 10/08/96 - more lint fixes
! 435: jboonleu 09/27/96 - fix lint errors
! 436: jboonleu 10/07/96 - beautify ori.h after conversion to long names
! 437: cxcheng 10/04/96 - replace short names with long names
! 438: sthakur 08/20/96 - add COR context to OCIObjectPin
! 439: mluong 07/17/96 - add back orioglk, oriogdr, oriogiv, and oriocur.
! 440: jboonleu 07/17/96 - rename refresh option to conherency option
! 441: jboonleu 07/16/96 - change comment for cache consistency
! 442: jwijaya 07/03/96 - add ANSI prototypes
! 443: jboonleu 06/12/96 - update comment
! 444: jboonleu 05/08/96 - change description of OCIDurationGetParent
! 445: jboonleu 05/01/96 - add OROOCOSFN
! 446: skrishna 04/08/96 - change ori*() to take OCIEnv* and OCIError* instead
! 447: of oroenv*
! 448: jboonleu 01/04/96 - interface change
! 449: jboonleu 10/24/95 - support of variable ref
! 450: jboonleu 02/15/95 - new interface
! 451: sthakur 01/05/95 - pass username to origrgc
! 452: skotsovo 12/07/94 - update example
! 453: jwijaya 11/15/94 - rename ORONSPTAB to ORONSPEXT
! 454: jwijaya 10/06/94 - add namespace to oriopnm()
! 455: jwijaya 10/02/94 - connection handle -> connection number
! 456: jboonleu 08/16/94 - fix lint errors
! 457: jboonleu 07/20/94 - change interface of OCICacheFlush
! 458: tanguyen 07/18/94 - add oriocpe, change OCIObjectCopy to oriocps
! 459: tcheng 07/15/94 - add init param maximum_sga_heap_size
! 460: tcheng 07/13/94 - change origini to get param string
! 461: jboonleu 07/05/94 - change sccs string from sccid to a comment
! 462: jboonleu 07/01/94 - Add examples to ORIO* and ORIC* functions
! 463: tanguyen 06/30/94 - Fix the ORI_ORACLE ifdef
! 464: skotsovo 06/27/94 - include all public functions in public functions
! 465: list at top of header file
! 466: tcheng 06/27/94 - modify comments according to new template
! 467: tanguyen 06/24/94 - fix comments for OCIObjectCopy
! 468: tcheng 06/24/94 - fix comments in origrgc()
! 469: tanguyen 06/21/94 - fix comments and format
! 470: tcheng 06/20/94 - commenting origini/trm/err/rgc/urg() functions
! 471: tanguyen 06/16/94 - fix descriptions of ref operations
! 472: tanguyen 06/16/94 - clarifies refs comparison
! 473: tanguyen 05/12/94 - adds more interfaces (OCIObjectMarkUpdate)
! 474: jwijaya 05/10/94 - fix examples, add origurg, change origcon to origrgc
! 475: tanguyen 05/03/94 - remove unnecessary 'type' argument from
! 476: 'OCIObjectCopy'
! 477: tanguyen 03/08/94 - clarifies comments
! 478: jwijaya 02/16/94 - more questions
! 479: jwijaya 02/11/94 - more comments
! 480: jwijaya 02/10/94 - identify optional arguments
! 481: jwijaya 02/07/94 - Creation
! 482: */
! 483:
! 484:
! 485: #ifndef ORATYPES
! 486: #include <oratypes.h>
! 487: #endif
! 488: #ifndef ORO_ORACLE
! 489: #include <oro.h>
! 490: #endif
! 491: #ifndef OCI_ORACLE
! 492: #include <oci.h>
! 493: #endif
! 494: #ifndef ORT_ORACLE
! 495: #include <ort.h>
! 496: #endif
! 497:
! 498: #ifndef ORI_ORACLE
! 499: #define ORI_ORACLE
! 500:
! 501: /*---------------------------------------------------------------------------*/
! 502: /* SHORT NAMES SUPPORT SECTION */
! 503: /*---------------------------------------------------------------------------*/
! 504:
! 505: #ifdef SLSHORTNAME
! 506:
! 507: /* the following are short names that are only supported on IBM mainframes
! 508: with the SLSHORTNAME defined.
! 509: With this all subsequent long names will actually be substituted with
! 510: the short names here */
! 511:
! 512: #define OCIDurationBegin origbgu
! 513: #define OCIDurationEnd origedu
! 514: #define OCIDurationGetParent origpdr
! 515: #define OCICacheFlushRefresh oricfrh
! 516: #define OCICacheUnpin oricunp
! 517: #define OCICacheFree oricfre
! 518: #define OCICacheUnmark oricumk
! 519: #define OCICacheGetObjects oricgpr
! 520: #define OCICacheRegister oricscb
! 521: #define OCIObjectUnpin oriounp
! 522: #define OCIObjectPinCountReset orioupz
! 523: #define OCIObjectLock oriolck
! 524: #define OCIObjectLockNoWait oriolnw
! 525: #define OCIObjectMarkUpdate orioupd
! 526: #define OCIObjectUnmark orioumk
! 527: #define OCIObjectUnmarkByRef orioumr
! 528: #define OCIObjectAlwaysLatest oriomkl
! 529: #define OCIObjectNotAlwaysLatest oriouml
! 530: #define OCIObjectMarkDeleteByRef oriordl
! 531: #define OCIObjectMarkDelete oriopdl
! 532: #define OCIObjectFlush oriofls
! 533: #define OCIObjectFlushRefresh oriofrh
! 534: #define OCIObjectCopy oriocpy
! 535: #define OCIObjectGetTypeRef oriogtr
! 536: #define OCIObjectGetObjectRef oriogor
! 537: #define OCIObjectGetInd oriogns
! 538: #define OCIObjectExists oriogex
! 539: #define OCIObjectGetProperty oriogpr
! 540: #define OCIObjectRefresh oriorfs
! 541: #define OCIObjectPinTable oriogtb
! 542: #define OCIObjectGetPrimaryKeyTypeRef oriogpf
! 543: #define OCIObjectMakeObjectRef oriomrf
! 544:
! 545: #define OCIObjectNew orionew
! 546: #define OCIObjectPin oriopin
! 547: #define OCIObjectFree oriofre
! 548: #define OCIObjectArrayPin orioapn
! 549: #define OCIObjectIsDirty oriodrt
! 550: #define OCIObjectIsDirtied oriodrd
! 551: #define OCIObjectIsLoaded orioldd
! 552: #define OCICacheFlush oricfls
! 553: #define OCICacheRefresh oricrfs
! 554:
! 555: #endif /* SLSHORTNAME */
! 556:
! 557: /*---------------------------------------------------------------------------*/
! 558: /* PUBLIC TYPES AND CONSTANTS */
! 559: /*---------------------------------------------------------------------------*/
! 560:
! 561: /* Also see oro.h. */
! 562:
! 563: /*---------------------------------------------------------------------------*/
! 564: /* PUBLIC FUNCTIONS */
! 565: /*---------------------------------------------------------------------------*/
! 566: /*---------------------------------------------------------------------------*/
! 567: /* OBJECT/INSTANCE OPERATIONS */
! 568: /*---------------------------------------------------------------------------*/
! 569:
! 570: /*--------------------------- OCIObjectNew ----------------------------------*/
! 571: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 572: sword OCIObjectNew(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 573: OCITypeCode typecode, OCIType *tdo, dvoid *table,
! 574: OCIDuration duration, boolean value,
! 575: dvoid **instance _*/);
! 576: #else /* ANSI C */
! 577: sword OCIObjectNew( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 578: OCITypeCode typecode, OCIType *tdo, dvoid *table,
! 579: OCIDuration duration, boolean value,
! 580: dvoid **instance );
! 581: #endif
! 582: /*
! 583: NAME: OCIObjectNew - OCI new (create) a standalone instance
! 584: PARAMETERS:
! 585: env (IN/OUT) - OCI environment handle initialized in object mode
! 586: err (IN/OUT) - error handle. If there is an error, it is
! 587: recorded in 'err' and this function returns OCI_ERROR.
! 588: The error recorded in 'err' can be retrieved by calling
! 589: OCIErrorGet().
! 590: svc (IN) - OCI service handle.
! 591: typecode (IN) - the typecode of the type of the instance.
! 592: tdo (IN, optional) - pointer to the type descriptor object. The
! 593: TDO describes the type of the instance that is to be
! 594: created. Refer to OCITypeByName() for obtaining a TDO.
! 595: The TDO is required for creating a named type (e.g. an
! 596: object or a collection).
! 597: table (IN, optional) - pointer to a table object which specifies a
! 598: table in the server. This parameter can be set to NULL
! 599: if no table is given. See the description below to find
! 600: out how the table object and the TDO are used together
! 601: to determine the kind of instances (persistent,
! 602: transient, value) to be created. Also see
! 603: OCIObjectPinTable() for retrieving a table object.
! 604: duration (IN) - this is an overloaded parameter. The use of this
! 605: parameter is based on the kind of the instance that is
! 606: to be created.
! 607: a) persistent object. This parameter specifies the
! 608: pin duration.
! 609: b) transient object. This parameter specififes the
! 610: allocation duration and pin duration.
! 611: c) value. This parameter specifies the allocation
! 612: duration.
! 613: value (IN) - specifies whether the created object is a value.
! 614: If TRUE, then a value is created. Otherwise, a
! 615: referenceable object is created. If the instance is
! 616: not an object, then this parameter is ignored.
! 617: instance (OUT) - address of the newly created instance
! 618:
! 619: REQUIRES:
! 620: - a valid OCI environment handle must be given.
! 621: DESCRIPTION:
! 622: This function creates a new instance of the type specified by the
! 623: typecode or the TDO. Based on the parameters 'typecode' (or 'tdo'),
! 624: 'value' and 'table', different kinds of instances can be created:
! 625:
! 626: The parameter 'table' is not NULL?
! 627:
! 628: yes no
! 629: ----------------------------------------------------------------
! 630: | object type (value=TRUE) | value | value |
! 631: ----------------------------------------------------------------
! 632: | object type (value=FALSE) | persistent obj | transient obj |
! 633: type ----------------------------------------------------------------
! 634: | built-in type | value | value |
! 635: ----------------------------------------------------------------
! 636: | collection type | value | value |
! 637: ----------------------------------------------------------------
! 638:
! 639: This function allocates the top level memory chunk of an OTS instance.
! 640: The attributes in the top level memory are initialized (e.g. an
! 641: attribute of varchar2 is initialized to a vstring of 0 length).
! 642:
! 643: If the instance is an object, the object is marked existed but is
! 644: atomically null.
! 645:
! 646: FOR PERSISTENT OBJECTS:
! 647: The object is marked dirty and existed. The allocation duration for
! 648: the object is session. The object is pinned and the pin duration is
! 649: specified by the given parameter 'duration'.
! 650:
! 651: FOR TRANSIENT OBJECTS:
! 652: The object is pinned. The allocation duration and the pin duration are
! 653: specified by the given parameter 'duration'.
! 654:
! 655: FOR VALUES:
! 656: The allocation duration is specified by the given parameter 'duration'.
! 657:
! 658: RETURNS:
! 659: if environment handle or error handle is null, return
! 660: OCI_INVALID_HANDLE.
! 661: if operation suceeds, return OCI_SUCCESS.
! 662: if operation fails, return OCI_ERROR.
! 663: */
! 664:
! 665: /*--------------------------- OCIObjectPin ----------------------------------*/
! 666: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 667: sword OCIObjectPin(/*_ OCIEnv *env, OCIError *err, OCIRef *object_ref,
! 668: OCIComplexObject *corhdl, OCIPinOpt pin_option,
! 669: OCIDuration pin_duration, OCILockOpt lock_option,
! 670: dvoid **object _*/);
! 671: #else /* ANSI C */
! 672: sword OCIObjectPin( OCIEnv *env, OCIError *err, OCIRef *object_ref,
! 673: OCIComplexObject *corhdl, OCIPinOpt pin_option,
! 674: OCIDuration pin_duration,
! 675: OCILockOpt lock_option, dvoid **object );
! 676: #endif
! 677: /*
! 678: NAME: OCIObjectPin - OCI pin a referenceable object
! 679: PARAMETERS:
! 680: env (IN/OUT) - OCI environment handle initialized in object mode
! 681: err (IN/OUT) - error handle. If there is an error, it is
! 682: recorded in 'err' and this function returns
! 683: OCI_ERROR. The error recorded in 'err' can be
! 684: retrieved by calling OCIErrorGet().
! 685: object_ref (IN) - the reference to the object.
! 686: corhdl (IN) - handle for complex object retrieval.
! 687: pin_option (IN) - See description below.
! 688: pin_duration (IN) - The duration of which the object is being accesed
! 689: by a client. The object is implicitly unpinned at
! 690: the end of the pin duration.
! 691: If OCI_DURATION_NULL is passed, there is no pin
! 692: promotion if the object is already loaded into
! 693: the cache. If the object is not yet loaded, then
! 694: the pin duration is set to OCI_DURATION_DEFAULT.
! 695: lock_option (IN) - lock option (e.g., exclusive). If a lock option
! 696: is specified, the object is locked in the server.
! 697: See 'oro.h' for description about lock option.
! 698: object (OUT) - the pointer to the pinned object.
! 699:
! 700: REQUIRES:
! 701: - a valid OCI environment handle must be given.
! 702: DESCRIPTION:
! 703:
! 704: This function pins a referenceable object instance given the object
! 705: reference. The process of pinning serves three purposes:
! 706:
! 707: 1) locate an object given its reference. This is done by the object
! 708: cache which keeps track of the objects in the object heap.
! 709:
! 710: 2) notify the object cache that an object is being in use. An object
! 711: can be pinned many times. A pinned object will remain in memory
! 712: until it is completely unpinned (see OCIObjectUnpin()).
! 713:
! 714: 3) notify the object cache that a persistent object is being in use
! 715: such that the persistent object cannot be aged out. Since a
! 716: persistent object can be loaded from the server whenever is needed,
! 717: the memory utilization can be increased if a completely unpinned
! 718: persistent object can be freed (aged out), even before the
! 719: allocation duration is expired.
! 720:
! 721: Also see OCIObjectUnpin() for more information about unpinning.
! 722:
! 723: FOR PERSISTENT OBJECTS:
! 724:
! 725: When pinning a persistent object, if it is not in the cache, the object
! 726: will be fetched from the persistent store. The allocation duration of
! 727: the object is session. If the object is already in the cache, it is
! 728: returned to the client. The object will be locked in the server if a
! 729: lock option is specified.
! 730:
! 731: This function will return an error for a non-existent object.
! 732:
! 733: A pin option is used to specify the copy of the object that is to be
! 734: retrieved:
! 735:
! 736: 1) If option is OCI_PIN_ANY (pin any), if the object is already
! 737: in the environment heap, return this object. Otherwise, the object
! 738: is retrieved from the database. This option is useful when the
! 739: client knows that he has the exclusive access to the data in a
! 740: session.
! 741:
! 742: 2) If option is OCI_PIN_LATEST (pin latest), if the object is
! 743: not cached, it is retrieved from the database. If the object is
! 744: cached, it is refreshed with the latest version. See
! 745: OCIObjectRefresh() for more information about refreshing.
! 746:
! 747: 3) If option is OCI_PIN_RECENT (pin recent), if the object is loaded
! 748: into the cache in the current transaction, the object is returned.
! 749: If the object is not loaded in the current transaction, the object
! 750: is refreshed from the server.
! 751:
! 752: FOR TRANSIENT OBJECTS:
! 753:
! 754: This function will return an error if the transient object has already
! 755: been freed. This function does not return an error if an exclusive
! 756: lock is specified in the lock option.
! 757:
! 758: RETURNS:
! 759: if environment handle or error handle is null, return
! 760: OCI_INVALID_HANDLE.
! 761: if operation suceeds, return OCI_SUCCESS.
! 762: if operation fails, return OCI_ERROR.
! 763: */
! 764:
! 765: /*------------------------------ OCIObjectUnpin -----------------------------*/
! 766: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 767: sword OCIObjectUnpin(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 768: #else /* ANSI C */
! 769: sword OCIObjectUnpin( OCIEnv *env, OCIError *err, dvoid *object );
! 770: #endif
! 771: /*
! 772: NAME: OCIObjectUnpin - OCI unpin a referenceable object
! 773: PARAMETERS:
! 774: env (IN/OUT) - OCI environment handle initialized in object mode
! 775: err (IN/OUT) - error handle. If there is an error, it is
! 776: recorded in 'err' and this function returns OCI_ERROR.
! 777: The error recorded in 'err' can be retrieved by
! 778: calling OCIErrorGet().
! 779: object (IN) - pointer to an object
! 780: REQUIRES:
! 781: - a valid OCI environment handle must be given.
! 782: - The specified object must be pinned.
! 783: DESCRIPTION:
! 784: This function unpins an object. An object is completely unpinned when
! 785: 1) the object was unpinned N times after it has been pinned N times
! 786: (by calling OCIObjectPin()).
! 787: 2) it is the end of the pin duration
! 788: 3) the function OCIObjectPinCountReset() is called
! 789:
! 790: There is a pin count associated with each object which is incremented
! 791: whenever an object is pinned. When the pin count of the object is zero,
! 792: the object is said to be completely unpinned. An unpinned object can
! 793: be freed without error.
! 794:
! 795: FOR PERSISTENT OBJECTS:
! 796: When a persistent object is completely unpinned, it becomes a candidate
! 797: for aging. The memory of an object is freed when it is aged out. Aging
! 798: is used to maximize the utilization of memory. An dirty object cannot
! 799: be aged out unless it is flushed.
! 800:
! 801: FOR TRANSIENT OBJECTS:
! 802: The pin count of the object is decremented. A transient can be freed
! 803: only at the end of its allocation duration or when it is explicitly
! 804: deleted by calling OCIObjectFree().
! 805:
! 806: FOR VALUE:
! 807: This function will return an error for value.
! 808:
! 809: RETURNS:
! 810: if environment handle or error handle is null, return
! 811: OCI_INVALID_HANDLE.
! 812: if operation suceeds, return OCI_SUCCESS.
! 813: if operation fails, return OCI_ERROR.
! 814: */
! 815:
! 816: /*---------------------------- OCIObjectPinCountReset -----------------------*/
! 817: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 818: sword OCIObjectPinCountReset(/*_ OCIEnv *env,OCIError *err,dvoid *object _*/);
! 819: #else /* ANSI C */
! 820: sword OCIObjectPinCountReset( OCIEnv *env, OCIError *err, dvoid *object );
! 821: #endif
! 822: /*
! 823: NAME: OCIObjectPinCountReset - OCI resets the pin count of a referenceable
! 824: object
! 825: PARAMETERS:
! 826: env (IN/OUT) - OCI environment handle initialized in object mode
! 827: err (IN/OUT) - error handle. If there is an error, it is
! 828: recorded in 'err' and this function returns OCI_ERROR.
! 829: The error recorded in 'err' can be retrieved by
! 830: calling OCIErrorGet().
! 831: object (IN) - pointer to an object
! 832: REQUIRES:
! 833: - a valid OCI environment handle must be given.
! 834: - The specified object must be pinned.
! 835: DESCRIPTION:
! 836: This function completely unpins an object. When an object is
! 837: completely unpinned, it can be freed without error.
! 838:
! 839: FOR PERSISTENT OBJECTS:
! 840: When a persistent object is completely unpinned, it becomes a candidate
! 841: for aging. The memory of an object is freed when it is aged out. Aging
! 842: is used to maximize the utilization of memory. An dirty object cannot
! 843: be aged out unless it is flushed.
! 844:
! 845: FOR TRANSIENT OBJECTS:
! 846: The pin count of the object is decremented. A transient can be freed
! 847: only at the end of its allocation duration or when it is explicitly
! 848: freed by calling OCIObjectFree().
! 849:
! 850: FOR VALUE:
! 851: This function will return an error for value.
! 852:
! 853: RETURNS:
! 854: if environment handle or error handle is null, return
! 855: OCI_INVALID_HANDLE.
! 856: if operation suceeds, return OCI_SUCCESS.
! 857: if operation fails, return OCI_ERROR.
! 858: */
! 859:
! 860: /*--------------------------- OCIObjectLock ---------------------------------*/
! 861: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 862: sword OCIObjectLock(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 863: #else /* ANSI C */
! 864: sword OCIObjectLock( OCIEnv *env, OCIError *err, dvoid *object );
! 865: #endif
! 866: /*
! 867: NAME: OCIObjectLock - OCI lock a persistent object
! 868: PARAMETERS:
! 869: env (IN/OUT) - OCI environment handle initialized in object mode
! 870: err (IN/OUT) - error handle. If there is an error, it is
! 871: recorded in 'err' and this function returns OCI_ERROR.
! 872: The error recorded in 'err' can be retrieved by
! 873: calling OCIErrorGet().
! 874: object (IN) - pointer to the persistent object
! 875: REQUIRES:
! 876: - a valid OCI environment handle must be given.
! 877: - The specified object must be pinned.
! 878: DESCRIPTION:
! 879: This function locks a persistent object at the server. Unlike
! 880: OCIObjectLockNoWait() this function waits if another user currently
! 881: holds a lock on the desired object. This function
! 882: returns an error if:
! 883: 1) the object is non-existent.
! 884:
! 885: This function will return an error for transient objects and values.
! 886: The lock of an object is released at the end of a transaction.
! 887:
! 888: RETURNS:
! 889: if environment handle or error handle is null, return
! 890: OCI_INVALID_HANDLE.
! 891: if operation suceeds, return OCI_SUCCESS.
! 892: if operation fails, return OCI_ERROR.
! 893: */
! 894:
! 895: /*------------------------ OCIObjectLockNoWait ------------------------------*/
! 896: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 897: sword OCIObjectLockNoWait(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 898: #else /* ANSI C */
! 899: sword OCIObjectLockNoWait( OCIEnv *env, OCIError *err, dvoid *object );
! 900: #endif
! 901: /*
! 902: NAME: OCIObjectLockNoWait - OCI lock a persistent object, do not wait for
! 903: the lock, return error if lock not available
! 904: PARAMETERS:
! 905: env (IN/OUT) - OCI environment handle initialized in object mode
! 906: err (IN/OUT) - error handle. If there is an error, it is
! 907: recorded in 'err' and this function returns OCI_ERROR.
! 908: The error recorded in 'err' can be retrieved by
! 909: calling OCIErrorGet().
! 910: object (IN) - pointer to the persistent object
! 911: REQUIRES:
! 912: - a valid OCI environment handle must be given.
! 913: - The specified object must be pinned.
! 914: DESCRIPTION:
! 915: This function locks a persistent object at the server. Unlike
! 916: OCIObjectLock() this function will not wait if another user holds
! 917: the lock on the desired object. This function returns an error if:
! 918: 1) the object is non-existent.
! 919: 2) the object is currently locked by another user in which
! 920: case this function returns with an error.
! 921:
! 922: This function will return an error for transient objects and values.
! 923: The lock of an object is released at the end of a transaction.
! 924:
! 925: RETURNS:
! 926: if environment handle or error handle is null, return
! 927: OCI_INVALID_HANDLE.
! 928: if operation suceeds, return OCI_SUCCESS.
! 929: if operation fails, return OCI_ERROR.
! 930: */
! 931:
! 932: /*--------------------------- OCIObjectMarkUpdate ----------------------------*/
! 933: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 934: sword OCIObjectMarkUpdate(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 935: #else /* ANSI C */
! 936: sword OCIObjectMarkUpdate( OCIEnv *env, OCIError *err, dvoid *object );
! 937: #endif
! 938: /*
! 939: NAME: OCIObjectMarkUpdate - OCI marks an object as updated
! 940: PARAMETERS:
! 941: env (IN/OUT) - OCI environment handle initialized in object mode
! 942: err (IN/OUT) - error handle. If there is an error, it is
! 943: recorded in 'err' and this function returns OCI_ERROR.
! 944: The error recorded in 'err' can be retrieved by
! 945: calling OCIErrorGet().
! 946: object (IN) - pointer to the persistent object
! 947: REQUIRES:
! 948: - a valid OCI environment handle must be given.
! 949: - The specified object must be pinned.
! 950: DESCRIPTION:
! 951: FOR PERSISTENT OBJECTS:
! 952: This function marks the specified persistent object as updated. The
! 953: persistent objects will be written to the server when the object cache
! 954: is flushed. The object is not locked or flushed by this function. It
! 955: is an error to update a deleted object.
! 956:
! 957: After an object is marked updated and flushed, this function must be
! 958: called again to mark the object as updated if it has been dirtied
! 959: after it is being flushed.
! 960:
! 961: FOR TRANSIENT OBJECTS:
! 962: This function marks the specified transient object as updated. The
! 963: transient objects will NOT be written to the server. It is an error
! 964: to update a deleted object.
! 965:
! 966: FOR VALUES:
! 967: It is an no-op for values.
! 968:
! 969: RETURNS:
! 970: if environment handle or error handle is null, return
! 971: OCI_INVALID_HANDLE.
! 972: if operation suceeds, return OCI_SUCCESS.
! 973: if operation fails, return OCI_ERROR.
! 974: */
! 975:
! 976: /*----------------------------- OCIObjectUnmark -----------------------------*/
! 977: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 978: sword OCIObjectUnmark(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 979: #else /* ANSI C */
! 980: sword OCIObjectUnmark( OCIEnv *env, OCIError *err, dvoid *object );
! 981: #endif
! 982: /*
! 983: NAME: OCIObjectUnmark - OCI unmarks an object
! 984: PARAMETERS:
! 985: env (IN/OUT) - OCI environment handle initialized in object mode
! 986: err (IN/OUT) - error handle. If there is an error, it is
! 987: recorded in 'err' and this function returns OCI_ERROR.
! 988: The error recorded in 'err' can be retrieved by
! 989: calling OCIErrorGet().
! 990: object (IN) - pointer to the persistent object
! 991: REQUIRES:
! 992: - a valid OCI environment handle must be given.
! 993: - The specified object must be pinned.
! 994: DESCRIPTION:
! 995: FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
! 996: This function unmarks the specified persistent object as dirty. Changes
! 997: that are made to the object will not be written to the server. If the
! 998: object is marked locked, it remains marked locked. The changes that
! 999: have already made to the object will not be undone implicitly.
! 1000:
! 1001: FOR VALUES:
! 1002: It is an no-op for values.
! 1003:
! 1004: RETURNS:
! 1005: if environment handle or error handle is null, return
! 1006: OCI_INVALID_HANDLE.
! 1007: if operation suceeds, return OCI_SUCCESS.
! 1008: if operation fails, return OCI_ERROR.
! 1009: */
! 1010:
! 1011: /*----------------------------- OCIObjectUnmarkByRef ------------------------*/
! 1012: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1013: sword OCIObjectUnmarkByRef(/*_ OCIEnv *env, OCIError *err, OCIRef *ref _*/);
! 1014: #else /* ANSI C */
! 1015: sword OCIObjectUnmarkByRef( OCIEnv *env, OCIError *err, OCIRef *ref );
! 1016: #endif
! 1017: /*
! 1018: NAME: OCIObjectUnmarkByRef - OCI unmarks an object by Ref
! 1019: PARAMETERS:
! 1020: env (IN/OUT) - OCI environment handle initialized in object mode
! 1021: err (IN/OUT) - error handle. If there is an error, it is
! 1022: recorded in 'err' and this function returns OCI_ERROR.
! 1023: The error recorded in 'err' can be retrieved by
! 1024: calling OCIErrorGet().
! 1025: ref (IN) - reference of the object
! 1026: REQUIRES:
! 1027: - a valid OCI environment handle must be given.
! 1028: - The specified object must be pinned.
! 1029: DESCRIPTION:
! 1030: FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS:
! 1031: This function unmarks the specified persistent object as dirty. Changes
! 1032: that are made to the object will not be written to the server. If the
! 1033: object is marked locked, it remains marked locked. The changes that
! 1034: have already made to the object will not be undone implicitly.
! 1035:
! 1036: FOR VALUES:
! 1037: It is an no-op for values.
! 1038:
! 1039: RETURNS:
! 1040: if environment handle or error handle is null, return
! 1041: OCI_INVALID_HANDLE.
! 1042: if operation suceeds, return OCI_SUCCESS.
! 1043: if operation fails, return OCI_ERROR.
! 1044: */
! 1045:
! 1046: /*--------------------------- OCIObjectFree ---------------------------------*/
! 1047: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1048: sword OCIObjectFree(/*_ OCIEnv *env, OCIError *err, dvoid *instance,
! 1049: ub2 flags _*/);
! 1050: #else /* ANSI C */
! 1051: sword OCIObjectFree( OCIEnv *env, OCIError *err, dvoid *instance,
! 1052: ub2 flags );
! 1053: #endif
! 1054: /*
! 1055: NAME: OCIObjectFree - OCI free (and unpin) an standalone instance
! 1056: PARAMETERS:
! 1057: env (IN/OUT) - OCI environment handle initialized in object mode
! 1058: err (IN/OUT) - error handle. If there is an error, it is
! 1059: recorded in 'err' and this function returns
! 1060: OCI_ERROR. The error recorded in 'err' can be
! 1061: retrieved by calling OCIErrorGet().
! 1062: instance (IN) - pointer to a standalone instance.
! 1063: flags (IN) - If OCI_OBJECT_FREE_FORCE is set, free the object
! 1064: even if it is pinned or dirty.
! 1065: If OCI_OBJECT_FREE_NONULL is set, the null
! 1066: structure will not be freed.
! 1067: REQUIRES:
! 1068: - a valid OCI environment handle must be given.
! 1069: - The instance to be freed must be standalone.
! 1070: - If the instance is a referenceable object, the object must be pinned.
! 1071: DESCRIPTION:
! 1072: This function deallocates all the memory allocated for an OTS instance,
! 1073: including the null structure.
! 1074:
! 1075: FOR PERSISTENT OBJECTS:
! 1076: This function will return an error if the client is attempting to free
! 1077: a dirty persistent object that has not been flushed. The client should
! 1078: either flush the persistent object or set the parameter 'flag' to
! 1079: OCI_OBJECT_FREE_FORCE.
! 1080:
! 1081: This function will call OCIObjectUnpin() once to check if the object
! 1082: can be completely unpin. If it succeeds, the rest of the function will
! 1083: proceed to free the object. If it fails, then an error is returned
! 1084: unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE.
! 1085:
! 1086: Freeing a persistent object in memory will not change the persistent
! 1087: state of that object at the server. For example, the object will
! 1088: remain locked after the object is freed.
! 1089:
! 1090: FOR TRANSIENT OBJECTS:
! 1091:
! 1092: This function will call OCIObjectUnpin() once to check if the object
! 1093: can be completely unpin. If it succeeds, the rest of the function will
! 1094: proceed to free the object. If it fails, then an error is returned
! 1095: unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE.
! 1096:
! 1097: FOR VALUES:
! 1098: The memory of the object is freed immediately.
! 1099:
! 1100: RETURNS:
! 1101: if environment handle or error handle is null, return
! 1102: OCI_INVALID_HANDLE.
! 1103: if operation suceeds, return OCI_SUCCESS.
! 1104: if operation fails, return OCI_ERROR.
! 1105: */
! 1106:
! 1107: /*------------------------ OCIObjectMarkDeleteByRef --------------------------*/
! 1108: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1109: sword OCIObjectMarkDeleteByRef(/*_ OCIEnv *env,OCIError *err,
! 1110: OCIRef *object_ref _*/);
! 1111: #else /* ANSI C */
! 1112: sword OCIObjectMarkDeleteByRef( OCIEnv *env, OCIError *err,
! 1113: OCIRef *object_ref);
! 1114: #endif
! 1115: /*
! 1116: NAME: OCIObjectMarkDeleteByRef - OCI "delete" (and unpin) an object given
! 1117: a reference
! 1118: PARAMETERS:
! 1119: env (IN/OUT) - OCI environment handle initialized in object mode
! 1120: err (IN/OUT) - error handle. If there is an error, it is
! 1121: recorded in 'err' and this function returns
! 1122: OCI_ERROR. The error recorded in 'err' can be
! 1123: retrieved by calling OCIErrorGet().
! 1124: object_ref (IN) - ref of the object to be deleted
! 1125:
! 1126: REQUIRES:
! 1127: - a valid OCI environment handle must be given.
! 1128: DESCRIPTION:
! 1129: This function marks the object designated by 'object_ref' as deleted.
! 1130:
! 1131: FOR PERSISTENT OBJECTS:
! 1132: If the object is not loaded, then a temporary object is created and is
! 1133: marked deleted. Otherwise, the object is marked deleted.
! 1134:
! 1135: The object is deleted in the server when the object is flushed.
! 1136:
! 1137: FOR TRANSIENT OBJECTS:
! 1138: The object is marked deleted. The object is not freed until it is
! 1139: unpinned.
! 1140:
! 1141: RETURNS:
! 1142: if environment handle or error handle is null, return
! 1143: OCI_INVALID_HANDLE.
! 1144: if operation suceeds, return OCI_SUCCESS.
! 1145: if operation fails, return OCI_ERROR.
! 1146: */
! 1147:
! 1148: /*---------------------------- OCIObjectMarkDelete ---------------------------*/
! 1149: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1150: sword OCIObjectMarkDelete(/*_ OCIEnv *env, OCIError *err, dvoid *instance _*/);
! 1151: #else /* ANSI C */
! 1152: sword OCIObjectMarkDelete( OCIEnv *env, OCIError *err, dvoid *instance );
! 1153: #endif
! 1154: /*
! 1155: NAME: OCIObjectMarkDelete - OCI "delete" an instance given a Pointer
! 1156: PARAMETERS:
! 1157: env (IN/OUT) - OCI environment handle initialized in object mode
! 1158: err (IN/OUT) - error handle. If there is an error, it is
! 1159: recorded in 'err' and this function returns
! 1160: OCI_ERROR. The error recorded in 'err' can be
! 1161: retrieved by calling OCIErrorGet().
! 1162: instance (IN) - pointer to the instance
! 1163: REQUIRES:
! 1164: - a valid OCI environment handle must be given.
! 1165: - The instance must be standalone.
! 1166: - If the instance is a referenceable object, then it must be pinned.
! 1167: DESCRIPTION:
! 1168:
! 1169: FOR PERSISTENT OBJECTS:
! 1170: The object is marked deleted. The memory of the object is not freed.
! 1171: The object is deleted in the server when the object is flushed.
! 1172:
! 1173: FOR TRANSIENT OBJECTS:
! 1174: The object is marked deleted. The memory of the object is not freed.
! 1175:
! 1176: FOR VALUES:
! 1177: This function frees a value immediately.
! 1178:
! 1179: RETURNS:
! 1180: if environment handle or error handle is null, return
! 1181: OCI_INVALID_HANDLE.
! 1182: if operation suceeds, return OCI_SUCCESS.
! 1183: if operation fails, return OCI_ERROR.
! 1184: */
! 1185:
! 1186: /*---------------------------- OCIObjectFlush -------------------------------*/
! 1187: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1188: sword OCIObjectFlush(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 1189: #else /* ANSI C */
! 1190: sword OCIObjectFlush( OCIEnv *env, OCIError *err, dvoid *object );
! 1191: #endif
! 1192: /*
! 1193: NAME: OCIObjectFlush - OCI flush a persistent object
! 1194: PARAMETERS:
! 1195: env (IN/OUT) - OCI environment handle initialized in object mode
! 1196: err (IN/OUT) - error handle. If there is an error, it is
! 1197: recorded in 'err' and this function returns
! 1198: OCI_ERROR. The error recorded in 'err' can be
! 1199: retrieved by calling OCIErrorGet().
! 1200: object (IN) - pointer to the persistent object
! 1201: REQUIRES:
! 1202: - a valid OCI environment handle must be given.
! 1203: - The specified object must be pinned.
! 1204: DESCRIPTION:
! 1205: This function flushes a modified persistent object to the server.
! 1206: An exclusive lock is obtained implicitly for the object when flushed.
! 1207:
! 1208: When the object is written to the server, triggers may be fired.
! 1209: Objects can be modified by the triggers at the server. To keep the
! 1210: objects in the object cache being coherent with the database, the
! 1211: clients can free or refresh the objects in the cache.
! 1212:
! 1213: This function will return an error for transient objects and values.
! 1214:
! 1215: RETURNS:
! 1216: if environment handle or error handle is null, return
! 1217: OCI_INVALID_HANDLE.
! 1218: if operation suceeds, return OCI_SUCCESS.
! 1219: if operation fails, return OCI_ERROR.
! 1220: */
! 1221:
! 1222: /*------------------------ OCIObjectRefresh ---------------------------------*/
! 1223: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1224: sword OCIObjectRefresh(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 1225: #else /* ANSI C */
! 1226: sword OCIObjectRefresh( OCIEnv *env, OCIError *err, dvoid *object );
! 1227: #endif
! 1228: /*
! 1229: NAME: OCIObjectRefresh - OCI refresh a persistent object
! 1230: PARAMETERS:
! 1231: env (IN/OUT) - OCI environment handle initialized in object mode
! 1232: err (IN/OUT) - error handle. If there is an error, it is
! 1233: recorded in 'err' and this function returns
! 1234: OCI_ERROR. The error recorded in 'err' can be
! 1235: retrieved by calling OCIErrorGet().
! 1236: object (IN) - pointer to the persistent object
! 1237: REQUIRES:
! 1238: - a valid OCI environment handle must be given.
! 1239: - The specified object must be pinned.
! 1240: DESCRIPTION:
! 1241: This function refreshes an unmarked object with data retrieved from the
! 1242: latest snapshot in the server. An object should be refreshed when the
! 1243: objects in the cache are inconsistent with the objects at
! 1244: the server:
! 1245: 1) When an object is flushed to the server, triggers can be fired to
! 1246: modify more objects in the server. The same objects (modified by
! 1247: the triggers) in the object cache become obsolete.
! 1248: 2) When the user issues a SQL or executes a PL/SQL procedure to modify
! 1249: any object in the server, the same object in the cache becomes
! 1250: obsolete.
! 1251:
! 1252: The object that is refreshed will be 'replaced-in-place'. When an
! 1253: object is 'replaced-in-place', the top level memory of the object will
! 1254: be reused so that new data can be loaded into the same memory address.
! 1255: The top level memory of the null structre is also reused. Unlike the
! 1256: top level memory chunk, the secondary memory chunks may be resized and
! 1257: reallocated. The client should be careful when holding onto a pointer
! 1258: to the secondary memory chunk (e.g. assigning the address of a
! 1259: secondary memory to a local variable), since this pointer can become
! 1260: invalid after the object is refreshed.
! 1261:
! 1262: The object state will be modified as followed after being refreshed:
! 1263: - existent : set to appropriate value
! 1264: - pinned : unchanged
! 1265: - allocation duration : unchanged
! 1266: - pin duration : unchanged
! 1267:
! 1268: This function is an no-op for transient objects or values.
! 1269:
! 1270: RETURNS:
! 1271: if environment handle or error handle is null, return
! 1272: OCI_INVALID_HANDLE.
! 1273: if operation suceeds, return OCI_SUCCESS.
! 1274: if operation fails, return OCI_ERROR.
! 1275: */
! 1276:
! 1277: /*---------------------------- OCIObjectCopy --------------------------------*/
! 1278: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1279: sword OCIObjectCopy(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1280: dvoid *source, dvoid *null_source,
! 1281: dvoid *target, dvoid *null_target, OCIType *tdo,
! 1282: OCIDuration duration, ub1 option _*/);
! 1283: #else /* ANSI C */
! 1284: sword OCIObjectCopy( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1285: dvoid *source, dvoid *null_source,
! 1286: dvoid *target, dvoid *null_target, OCIType *tdo,
! 1287: OCIDuration duration, ub1 option );
! 1288: #endif
! 1289: /*
! 1290: NAME: OCIObjectCopy - OCI copy one instance to another
! 1291: PARAMETERS:
! 1292: env (IN/OUT) - OCI environment handle initialized in object mode
! 1293: err (IN/OUT) - error handle. If there is an error, it is
! 1294: recorded in 'err' and this function returns
! 1295: OCI_ERROR. The error recorded in 'err' can be
! 1296: retrieved by calling OCIErrorGet().
! 1297: svc (IN) - OCI service context handle
! 1298: source (IN) - pointer to the source instance
! 1299: null_source (IN) - pointer to the null structure of the source
! 1300: target (IN) - pointer to the target instance
! 1301: null_target (IN) - pointer to the null structure of the target
! 1302: tdo (IN) - the TDO for both source and target
! 1303: duration (IN) - allocation duration of the target memory
! 1304: option (IN) - specify the copy option:
! 1305: OROOCOSFN - Set Reference to Null. All references
! 1306: in the source will not be copied to the target. The
! 1307: references in the target are set to null.
! 1308: REQUIRES:
! 1309: - a valid OCI environment handle must be given.
! 1310: - If source or target is referenceable, it must be pinned.
! 1311: - The target or the containing instance of the target must be already
! 1312: be instantiated (e.g. created by OCIObjectNew()).
! 1313: - The source and target instances must be of the same type. If the
! 1314: source and target are located in a different databases, then the
! 1315: same type must exist in both databases.
! 1316: DESCRIPTION:
! 1317: This function copies the contents of the 'source' instance to the
! 1318: 'target' instance. This function performs a deep-copy such that the
! 1319: data that is copied/duplicated include:
! 1320: a) all the top level attributes (see the exceptions below)
! 1321: b) all the secondary memory (of the source) that is reachable from the
! 1322: top level attributes.
! 1323: c) the null structure of the instance
! 1324:
! 1325: Memory is allocated with the specified allocation duration.
! 1326:
! 1327: Certain data items are not copied:
! 1328: a) If the option OCI_OBJECTCOPY_NOREF is specified, then all references
! 1329: in the source are not copied. Instead, the references in the target
! 1330: are set to null.
! 1331: b) If the attribute is a LOB, then it is set to null.
! 1332:
! 1333: RETURNS:
! 1334: if environment handle or error handle is null, return
! 1335: OCI_INVALID_HANDLE.
! 1336: if operation suceeds, return OCI_SUCCESS.
! 1337: if operation fails, return OCI_ERROR.
! 1338: */
! 1339:
! 1340: /*---------------------------- OCIObjectGetTypeRef --------------------------*/
! 1341: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1342: sword OCIObjectGetTypeRef(/*_ OCIEnv *env, OCIError *err, dvoid *instance,
! 1343: OCIRef *type_ref _*/);
! 1344: #else /* ANSI C */
! 1345: sword OCIObjectGetTypeRef( OCIEnv *env, OCIError *err, dvoid *instance,
! 1346: OCIRef *type_ref );
! 1347: #endif
! 1348: /*
! 1349: NAME: OCIObjectGetTypeRef - get the type reference of a standalone object
! 1350: PARAMETERS:
! 1351: env (IN/OUT) - OCI environment handle initialized in object mode
! 1352: err (IN/OUT) - error handle. If there is an error, it is
! 1353: recorded in 'err' and this function returns
! 1354: OCI_ERROR. The error recorded in 'err' can be
! 1355: retrieved by calling OCIErrorGet().
! 1356: instance (IN) - pointer to an standalone instance
! 1357: type_ref (OUT) - reference to the type of the object. The reference
! 1358: must already be allocated.
! 1359: REQUIRES:
! 1360: - a valid OCI environment handle must be given.
! 1361: - The instance must be standalone.
! 1362: - If the object is referenceable, the specified object must be pinned.
! 1363: - The reference must already be allocated.
! 1364: DESCRIPTION:
! 1365: This function returns a reference to the TDO of a standalone instance.
! 1366: RETURNS:
! 1367: if environment handle or error handle is null, return
! 1368: OCI_INVALID_HANDLE.
! 1369: if operation suceeds, return OCI_SUCCESS.
! 1370: if operation fails, return OCI_ERROR.
! 1371: */
! 1372:
! 1373: /*--------------------------- OCIObjectGetObjectRef -------------------------*/
! 1374: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1375: sword OCIObjectGetObjectRef(/*_ OCIEnv *env, OCIError *err, dvoid *object,
! 1376: OCIRef *object_ref _*/);
! 1377: #else /* ANSI C */
! 1378: sword OCIObjectGetObjectRef( OCIEnv *env, OCIError *err, dvoid *object,
! 1379: OCIRef *object_ref );
! 1380: #endif
! 1381: /*
! 1382: NAME: OCIObjectGetObjectRef - OCI get the object reference of an
! 1383: referenceable object
! 1384: PARAMETERS:
! 1385: env (IN/OUT) - OCI environment handle initialized in object mode
! 1386: err (IN/OUT) - error handle. If there is an error, it is
! 1387: recorded in 'err' and this function returns
! 1388: OCI_ERROR. The error recorded in 'err' can be
! 1389: retrieved by calling OCIErrorGet().
! 1390: object (IN) - pointer to a persistent object
! 1391: object_ref (OUT) - reference of the given object. The reference must
! 1392: already be allocated.
! 1393: REQUIRES:
! 1394: - a valid OCI environment handle must be given.
! 1395: - The specified object must be pinned.
! 1396: - The reference must already be allocated.
! 1397: DESCRIPTION:
! 1398: This function returns a reference to the given object. It returns an
! 1399: error for values.
! 1400: RETURNS:
! 1401: if environment handle or error handle is null, return
! 1402: OCI_INVALID_HANDLE.
! 1403: if operation suceeds, return OCI_SUCCESS.
! 1404: if operation fails, return OCI_ERROR.
! 1405: */
! 1406:
! 1407: /*--------------------------- OCIObjectMakeObjectRef -----------------------*/
! 1408: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1409: sword OCIObjectMakeObjectRef(/*_ OCIEnv *env, OCIError *err,
! 1410: CONST OCISvcCtx *svc, dvoid *table,
! 1411: dvoid **attrlist, ub4 attrcnt,
! 1412: OCIRef *object_ref _*/);
! 1413: #else /* ANSI C */
! 1414: sword OCIObjectMakeObjectRef( OCIEnv *env, OCIError *err,
! 1415: CONST OCISvcCtx *svc, dvoid * table,
! 1416: dvoid **values, ub4 array_len,
! 1417: OCIRef *object_ref );
! 1418: #endif
! 1419: /*
! 1420: NAME: OCIObjectMakeObjectRef - OCI Create an object reference to a
! 1421: referenceable object.
! 1422: PARAMETERS:
! 1423: env (IN/OUT) - OCI environment handle initialized in object mode
! 1424: err (IN/OUT) - error handle. If there is an error, it is
! 1425: recorded in 'err' and this function returns
! 1426: OCI_ERROR. The error recorded in 'err' can be
! 1427: retrieved by calling OCIErrorGet().
! 1428: svc (IN) - the service context
! 1429: table (IN) - A pointer to the table object (must be pinned)
! 1430: attrlist (IN) - A list of values (OCI type values) from which
! 1431: the ref is to be created.
! 1432: attrcnt (IN) - The length of the attrlist array.
! 1433: object_ref (OUT) - reference of the given object. The reference must
! 1434: already be allocated.
! 1435: REQUIRES:
! 1436: - a valid OCI environment handle must be given.
! 1437: - The specified table object must be pinned.
! 1438: - The reference must already be allocated.
! 1439: DESCRIPTION:
! 1440: This function creates a reference given the values that make up the
! 1441: reference and also a pointer to the table object.
! 1442: Based on the table's OID property, whether it is a pk based OID or
! 1443: a system generated OID, the function creates a sys-generated REF or
! 1444: a pk based REF.
! 1445: In case of system generated REFs pass in a OCIRaw which is 16 bytes
! 1446: long contatining the sys generated OID.
! 1447: In case of PK refs pass in the OCI equivalent for numbers, chars etc..
! 1448: RETURNS:
! 1449: if environment handle or error handle is null, return
! 1450: OCI_INVALID_HANDLE.
! 1451: if operation suceeds, return OCI_SUCCESS.
! 1452: if operation fails, return OCI_ERROR.
! 1453: */
! 1454:
! 1455: /*--------------------------- OCIObjectGetPrimaryKeyTypeRef --------------- */
! 1456: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1457: sword OCIObjectGetPrimaryKeyTypeRef(/*_ OCIEnv *env, OCIError *err,
! 1458: CONST OCISvcCtx *svc, dvoid *table,
! 1459: OCIRef *type_ref _*/);
! 1460: #else /* ANSI C */
! 1461: sword OCIObjectGetPrimaryKeyTypeRef( OCIEnv *env, OCIError *err,
! 1462: CONST OCISvcCtx *svc, dvoid *table,
! 1463: OCIRef *type_ref );
! 1464: #endif
! 1465: /*
! 1466: NAME: OCIObjectGetPrimaryKeyTypeRef - OCI get the REF to the pk OID type
! 1467: PARAMETERS:
! 1468: env (IN/OUT) - OCI environment handle initialized in object mode
! 1469: err (IN/OUT) - error handle. If there is an error, it is
! 1470: recorded in 'err' and this function returns
! 1471: OCI_ERROR. The error recorded in 'err' can be
! 1472: retrieved by calling OCIErrorGet().
! 1473: svc (IN) - the service context
! 1474: table (IN) - pointer to the table object
! 1475: type_ref (OUT) - reference of the pk type. The reference must
! 1476: already be allocated.
! 1477: REQUIRES:
! 1478: - a valid OCI environment handle must be given.
! 1479: - The specified table object must be pinned.
! 1480: - The reference must already be allocated.
! 1481: DESCRIPTION:
! 1482: This function returns a reference to the pk type. It returns an
! 1483: error for values. If the table is not a Pk oid table/view, then
! 1484: it returns error.
! 1485: RETURNS:
! 1486: if environment handle or error handle is null, return
! 1487: OCI_INVALID_HANDLE.
! 1488: if operation suceeds, return OCI_SUCCESS.
! 1489: if operation fails, return OCI_ERROR.
! 1490: */
! 1491:
! 1492: /*-------------------------- OCIObjectGetInd --------------------------------*/
! 1493: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1494: sword OCIObjectGetInd(/*_ OCIEnv *env, OCIError *err, dvoid *instance,
! 1495: dvoid **null_struct _*/);
! 1496: #else /* ANSI C */
! 1497: sword OCIObjectGetInd( OCIEnv *env, OCIError *err, dvoid *instance,
! 1498: dvoid **null_struct );
! 1499: #endif
! 1500: /*
! 1501: NAME: OCIObjectGetInd - OCI get the null structure of a standalone object
! 1502: PARAMETERS:
! 1503: env (IN/OUT) - OCI environment handle initialized in object mode
! 1504: err (IN/OUT) - error handle. If there is an error, it is
! 1505: recorded in 'err' and this function returns
! 1506: OCI_ERROR. The error recorded in 'err' can be
! 1507: retrieved by calling OCIErrorGet().
! 1508: instance (IN) - pointer to the instance
! 1509: null_struct (OUT) - null structure
! 1510: REQUIRES:
! 1511: - a valid OCI environment handle must be given.
! 1512: - The object must be standalone.
! 1513: - If the object is referenceable, the specified object must be pinned.
! 1514: DESCRIPTION:
! 1515: This function returns the null structure of an instance. This function
! 1516: will allocate the top level memory of the null structure if it is not
! 1517: already allocated. If an null structure cannot be allocated for the
! 1518: instance, then an error is returned. This function only works for
! 1519: ADT or row type instance.
! 1520: RETURNS:
! 1521: if environment handle or error handle is null, return
! 1522: OCI_INVALID_HANDLE.
! 1523: if operation suceeds, return OCI_SUCCESS.
! 1524: if operation fails, return OCI_ERROR.
! 1525: */
! 1526:
! 1527: /*--------------------------- OCIObjectExists --------------------------------*/
! 1528: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1529: sword OCIObjectExists(/*_ OCIEnv *env, OCIError *err, dvoid *ins,
! 1530: boolean *exist _*/);
! 1531: #else /* ANSI C */
! 1532: sword OCIObjectExists(OCIEnv *env, OCIError *err, dvoid *ins, boolean *exist);
! 1533: #endif
! 1534: /*
! 1535: NAME: OCIObjectExist - OCI checks if the object exists
! 1536: PARAMETERS:
! 1537: env (IN/OUT) - OCI environment handle initialized in object mode
! 1538: err (IN/OUT) - error handle. If there is an error, it is
! 1539: recorded in 'err' and this function returns
! 1540: OCI_ERROR. The error recorded in 'err' can be
! 1541: retrieved by calling OCIErrorGet().
! 1542: ins (IN) - pointer to an instance
! 1543: exist (OUT) - return TRUE if the object exists
! 1544: REQUIRES:
! 1545: - a valid OCI environment handle must be given.
! 1546: - The object must be standalone.
! 1547: - if object is a referenceable, it must be pinned.
! 1548: DESCRIPTION:
! 1549: This function returns the existence of an instance. If the instance
! 1550: is a value, this function always returns TRUE.
! 1551: RETURNS:
! 1552: if environment handle or error handle is null, return
! 1553: OCI_INVALID_HANDLE.
! 1554: if operation suceeds, return OCI_SUCCESS.
! 1555: if operation fails, return OCI_ERROR.
! 1556: */
! 1557:
! 1558: /*--------------------------- OCIObjectGetProperty ---------------------------*/
! 1559: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1560: sword OCIObjectGetProperty(/*_ OCIEnv *envh, OCIError *errh,
! 1561: CONST dvoid *obj, OCIObjectPropId propertyId,
! 1562: dvoid *property, ub4 *size _*/);
! 1563: #else /* ANSI C */
! 1564: sword OCIObjectGetProperty(OCIEnv *envh, OCIError *errh, CONST dvoid *obj,
! 1565: OCIObjectPropId propertyId,
! 1566: dvoid *property, ub4 *size );
! 1567: #endif
! 1568: /*
! 1569: NAME: OCIObjectGetProperty - OCIObject Get Property of given object
! 1570: PARAMETERS:
! 1571: env (IN/OUT) - OCI environment handle initialized in object mode
! 1572: err (IN/OUT) - error handle. If there is an error, it is
! 1573: recorded in 'err' and this function returns
! 1574: OCI_ERROR. The error recorded in 'err' can be
! 1575: retrieved by calling OCIErrorGet().
! 1576: obj (IN) - object whose property is returned
! 1577: propertyId (IN) - id which identifies the desired property
! 1578: property (OUT) - buffer into which the desired property is
! 1579: copied
! 1580: size (IN/OUT) - on input specifies the size of the property buffer
! 1581: passed by caller, on output will contain the
! 1582: size in bytes of the property returned.
! 1583: This parameter is required for string type
! 1584: properties only (e.g OCI_OBJECTPROP_SCHEMA,
! 1585: OCI_OBJECTPROP_TABLE). For non-string
! 1586: properties this parameter is ignored since
! 1587: the size is fixed.
! 1588: DESCRIPTION:
! 1589: This function returns the specified property of the object.
! 1590: The desired property is identified by 'propertyId'. The property
! 1591: value is copied into 'property' and for string typed properties
! 1592: the string size is returned via 'size'.
! 1593:
! 1594: Objects are classified as persistent, transient and value
! 1595: depending upon the lifetime and referenceability of the object.
! 1596: Some of the properties are applicable only to persistent
! 1597: objects and some others only apply to persistent and
! 1598: transient objects. An error is returned if the user tries to
! 1599: get a property which in not applicable to the given object.
! 1600: To avoid such an error, the user should first check whether
! 1601: the object is persistent or transient or value
! 1602: (OCI_OBJECTPROP_LIFETIME property) and then appropriately
! 1603: query for other properties.
! 1604:
! 1605: The different property ids and the corresponding type of
! 1606: 'property' argument is given below.
! 1607:
! 1608: OCI_OBJECTPROP_LIFETIME
! 1609: This identifies whether the given object is a persistent
! 1610: object (OCI_OBJECT_PERSISTENT) or a
! 1611: transient object (OCI_OBJECT_TRANSIENT) or a
! 1612: value instance (OCI_OBJECT_VALUE).
! 1613: 'property' argument must be a pointer to a variable of
! 1614: type OCIObjectLifetime.
! 1615:
! 1616: OCI_OBJECTPROP_SCHEMA
! 1617: This returns the schema name of the table in which the
! 1618: object exists. An error is returned if the given object
! 1619: points to a transient instance or a value. If the input
! 1620: buffer is not big enough to hold the schema name an error
! 1621: is returned, the error message will communicate the
! 1622: required size. Upon success, the size of the returned
! 1623: schema name in bytes is returned via 'size'.
! 1624: 'property' argument must be an array of type text and 'size'
! 1625: should be set to size of array in bytes by the caller.
! 1626:
! 1627: OCI_OBJECTPROP_TABLE
! 1628: This returns the table name in which the object exists. An
! 1629: error is returned if the given object points to a
! 1630: transient instance or a value. If the input buffer is not
! 1631: big enough to hold the table name an error is returned,
! 1632: the error message will communicate the required size. Upon
! 1633: success, the size of the returned table name in bytes is
! 1634: returned via 'size'. 'property' argument must be an array
! 1635: of type text and 'size' should be set to size of array in
! 1636: bytes by the caller.
! 1637:
! 1638: OCI_OBJECTPROP_PIN_DURATION
! 1639: This returns the pin duration of the object.
! 1640: An error is returned if the given object points to a value
! 1641: instance. Valid pin durations are: OCI_DURATION_SESSION and
! 1642: OCI_DURATION_TRANS.
! 1643: 'property' argument must be a pointer to a variable of type
! 1644: OCIDuration.
! 1645:
! 1646: OCI_OBJECTPROP_ALLOC_DURATION
! 1647: This returns the allocation duration of the object.
! 1648: Valid allocation durations are: OCI_DURATION_SESSION and
! 1649: OCI_DURATION_TRANS.
! 1650: 'property' argument must be a pointer to a variable of type
! 1651: OCIDuration.
! 1652:
! 1653: OCI_OBJECTPROP_LOCK
! 1654: This returns the lock status of the
! 1655: object. The possible lock status is enumerated by OCILockOpt.
! 1656: An error is returned if the given object points to a transient
! 1657: or value instance.
! 1658: 'property' argument must be a pointer to a variable of
! 1659: type OCILockOpt.
! 1660: Note, the lock status of an object can also be retrieved by
! 1661: calling OCIObjectIsLocked().
! 1662:
! 1663: OCI_OBJECTPROP_MARKSTATUS
! 1664: This returns the status flag which indicates whether the
! 1665: object is a new object, updated object and/or deleted object.
! 1666: The following macros can be used to test the mark status
! 1667: flag:
! 1668:
! 1669: OCI_OBJECT_IS_UPDATED(flag)
! 1670: OCI_OBJECT_IS_DELETED(flag)
! 1671: OCI_OBJECT_IS_NEW(flag)
! 1672: OCI_OBJECT_IS_DIRTY(flag)
! 1673:
! 1674: An object is dirty if it is a new object or marked deleted or
! 1675: marked updated.
! 1676: An error is returned if the given object points to a transient
! 1677: or value instance. 'property' argument must be of type
! 1678: OCIObjectMarkStatus.
! 1679:
! 1680: OCI_OBJECTPROP_VIEW
! 1681: This identifies whether the specified object is a view object
! 1682: or not. If property value returned is TRUE, it indicates the
! 1683: object is a view otherwise it is not.
! 1684: 'property' argument must be of type boolean.
! 1685:
! 1686: RETURNS:
! 1687: if environment handle or error handle is null, return
! 1688: OCI_INVALID_HANDLE.
! 1689: if operation suceeds, return OCI_SUCCESS.
! 1690: if operation fails, return OCI_ERROR. Possible errors are TBD
! 1691: */
! 1692:
! 1693: /*---------------------------- OCIObjectIsLocked --------------------------*/
! 1694: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1695: sword OCIObjectIsLocked(/*_ OCIEnv *env, OCIError *err, dvoid *ins,
! 1696: boolean *lock _*/);
! 1697: #else /* ANSI C */
! 1698: sword OCIObjectIsLocked( OCIEnv *env, OCIError *err, dvoid *ins,
! 1699: boolean *lock);
! 1700: #endif
! 1701: /*
! 1702: NAME: OCIObjectIsLocked - OCI get the lock status of a standalone object
! 1703: PARAMETERS:
! 1704: env (IN/OUT) - OCI environment handle initialized in object mode
! 1705: err (IN/OUT) - error handle. If there is an error, it is
! 1706: recorded in 'err' and this function returns
! 1707: OCI_ERROR. The error recorded in 'err' can be
! 1708: retrieved by calling OCIErrorGet().
! 1709: ins (IN) - pointer to an instance
! 1710: lock (OUT) - return value for the lock status.
! 1711: REQUIRES:
! 1712: - a valid OCI environment handle must be given.
! 1713: - The instance must be standalone.
! 1714: - If the object is referenceable, the specified object must be pinned.
! 1715: DESCRIPTION:
! 1716: This function returns the lock status of an instance. If the instance
! 1717: is a value, this function always returns FALSE.
! 1718: RETURNS:
! 1719: if environment handle or error handle is null, return
! 1720: OCI_INVALID_HANDLE.
! 1721: if operation suceeds, return OCI_SUCCESS.
! 1722: if operation fails, return OCI_ERROR.
! 1723: */
! 1724:
! 1725: /*--------------------------- OCIObjectIsDirty ------------------------------*/
! 1726: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1727: sword OCIObjectIsDirty(/*_ OCIEnv *env, OCIError *err, dvoid *ins,
! 1728: boolean *dirty _*/);
! 1729: #else /* ANSI C */
! 1730: sword OCIObjectIsDirty( OCIEnv *env, OCIError *err, dvoid *ins,
! 1731: boolean *dirty);
! 1732: #endif
! 1733: /*
! 1734: NAME: OCIObjectIsDirty - OCI get the dirty status of a standalone object
! 1735: PARAMETERS:
! 1736: env (IN/OUT) - OCI environment handle initialized in object mode
! 1737: err (IN/OUT) - error handle. If there is an error, it is
! 1738: recorded in 'err' and this function returns
! 1739: OCI_ERROR. The error recorded in 'err' can be
! 1740: retrieved by calling OCIErrorGet().
! 1741: ins (IN) - pointer to an instance
! 1742: dirty (OUT) - return value for the dirty status.
! 1743: REQUIRES:
! 1744: - a valid OCI environment handle must be given.
! 1745: - The instance must be standalone.
! 1746: - if instance is an object, the instance must be pinned.
! 1747: DESCRIPTION:
! 1748: This function returns the dirty status of an instance. If the instance
! 1749: is a value, this function always returns FALSE.
! 1750: RETURNS:
! 1751: if environment handle or error handle is null, return
! 1752: OCI_INVALID_HANDLE.
! 1753: if operation suceeds, return OCI_SUCCESS.
! 1754: if operation fails, return OCI_ERROR.
! 1755: */
! 1756:
! 1757: /*--------------------------- OCIObjectPinTable -----------------------------*/
! 1758: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1759: sword OCIObjectPinTable(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1760: CONST text *schema_name,
! 1761: ub4 s_n_length, CONST text *object_name, ub4 o_n_length,
! 1762: CONST OCIRef *scope_obj_ref, OCIDuration pin_duration,
! 1763: dvoid** object _*/);
! 1764: #else /* ANSI C */
! 1765: sword OCIObjectPinTable( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1766: CONST text *schema_name,
! 1767: ub4 s_n_length, CONST text *object_name, ub4 o_n_length,
! 1768: CONST OCIRef *scope_obj_ref, OCIDuration pin_duration,
! 1769: dvoid** object );
! 1770: #endif
! 1771: /*
! 1772: NAME: OCIObjectPinTable - OCI get table object
! 1773: PARAMETERS:
! 1774: env (IN/OUT) - OCI environment handle initialized in object mode
! 1775: err (IN/OUT) - error handle. If there is an error, it is
! 1776: recorded in 'err' and this function returns
! 1777: OCI_ERROR. The error recorded in 'err' can be
! 1778: retrieved by calling OCIErrorGet().
! 1779: svc (IN) - OCI service context handle
! 1780: schema_name (IN, optional) - schema name of the table
! 1781: s_n_length (IN, optional) - length of the schema name
! 1782: object_name (IN) - name of the table
! 1783: o_n_length (IN) - length of the table name
! 1784: scope_obj_ref (IN, optional) - reference of the scoping object
! 1785: pin_duration (IN) - pin duration. See description in OCIObjectPin().
! 1786: object (OUT) - the pinned table object
! 1787: REQUIRES:
! 1788: - a valid OCI environment handle must be given.
! 1789: DESCRIPTION:
! 1790: This function pin a table object with the specified pin duration.
! 1791: The client can unpin the object by calling OCIObjectUnpin(). See
! 1792: OCIObjectPin() and OCIObjectUnpin() for more information about pinning
! 1793: and unpinning.
! 1794: RETURNS:
! 1795: if environment handle or error handle is null, return
! 1796: OCI_INVALID_HANDLE.
! 1797: if operation suceeds, return OCI_SUCCESS.
! 1798: if operation fails, return OCI_ERROR.
! 1799: */
! 1800:
! 1801: /*------------------------- OCIObjectArrayPin -------------------------------*/
! 1802: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1803: sword OCIObjectArrayPin(/*_ OCIEnv *env, OCIError *err, OCIRef **ref_array,
! 1804: ub4 array_size, OCIComplexObject **cor_array,
! 1805: ub4 cor_array_size, OCIPinOpt pin_option,
! 1806: OCIDuration pin_duration, OCILockOpt lock,
! 1807: dvoid **obj_array, ub4 *pos _*/);
! 1808: #else /* ANSI C */
! 1809: sword OCIObjectArrayPin(OCIEnv *env, OCIError *err, OCIRef **ref_array,
! 1810: ub4 array_size, OCIComplexObject **cor_array,
! 1811: ub4 cor_array_size, OCIPinOpt pin_option,
! 1812: OCIDuration pin_duration, OCILockOpt lock,
! 1813: dvoid **obj_array, ub4 *pos );
! 1814: #endif
! 1815: /*
! 1816: NAME: OCIObjectArrayPin - ORIO array pin
! 1817: PARAMETERS:
! 1818: env (IN/OUT) - OCI environment handle initialized in object mode
! 1819: err (IN/OUT) - error handle. If there is an error, it is
! 1820: recorded in 'err' and this function returns
! 1821: OCI_ERROR. The error recorded in 'err' can be
! 1822: retrieved by calling OCIErrorGet().
! 1823: ref_array (IN) - array of references to be pinned
! 1824: array_size (IN) - number of elements in the array of references
! 1825: pin_option (IN) - pin option. See OCIObjectPin().
! 1826: pin_duration (IN) - pin duration. See OCIObjectPin().
! 1827: lock_option (IN) - lock option. See OCIObjectPin().
! 1828: obj_array (OUT) - If this argument is not NULL, the pinned objects
! 1829: will be returned in the array. The user must
! 1830: allocate this array with element type being
! 1831: 'dvoid *'. The size of this array is identical to
! 1832: 'array'.
! 1833: pos (OUT) - If there is an error, this argument will contain
! 1834: the element that is causing the error. Note that
! 1835: this argument is set to 1 for the first element in
! 1836: the ref_array.
! 1837: REQUIRE:
! 1838: - a valid OCI environment handle must be given.
! 1839: - If 'obj_array' is not NULL, then it must already be allocated and
! 1840: the size of 'obj_array' is 'array_size'.
! 1841: DESCRIPTION:
! 1842: This function pin an array of references. All the pinned objects are
! 1843: retrieved from the database in one network roundtrip. If the user
! 1844: specifies an output array ('obj_array'), then the address of the
! 1845: pinned objects will be assigned to the elements in the array. See
! 1846: OCIObjectPin() for more information about pinning.
! 1847: RETURNS:
! 1848: if environment handle or error handle is null, return
! 1849: OCI_INVALID_HANDLE.
! 1850: if operation suceeds, return OCI_SUCCESS.
! 1851: if operation fails, return OCI_ERROR.
! 1852: */
! 1853:
! 1854: /*---------------------------------------------------------------------------*/
! 1855: /* HEAP/CACHE OPERATIONS */
! 1856: /*---------------------------------------------------------------------------*/
! 1857:
! 1858: /*--------------------------- OCICacheFlush ---------------------------------*/
! 1859: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1860: sword OCICacheFlush(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1861: dvoid *context, OCIRef *(*get)(dvoid *context, ub1 *last),
! 1862: OCIRef **ref _*/);
! 1863: #else /* ANSI C */
! 1864: sword OCICacheFlush( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1865: dvoid *context, OCIRef *(*get)(dvoid *context, ub1 *last),
! 1866: OCIRef **ref );
! 1867: #endif
! 1868: /*
! 1869: NAME: OCICacheFlush - OCI flush persistent objects
! 1870: PARAMETERS:
! 1871: env (IN/OUT) - OCI environment handle initialized in object mode
! 1872: err (IN/OUT) - error handle. If there is an error, it is
! 1873: recorded in 'err' and this function returns
! 1874: OCI_ERROR. The error recorded in 'err' can be
! 1875: retrieved by calling OCIErrorGet().
! 1876: svc (IN) [optional] - OCI service context. If null pointer is
! 1877: specified, then the dirty objects in all connections
! 1878: will be flushed.
! 1879: context (IN) [optional] - specifies an user context that is an
! 1880: argument to the client callback function 'get'. This
! 1881: parameter is set to NULL if there is no user context.
! 1882: get (IN) [optional] - an client-defined function which acts an
! 1883: iterator to retrieve a batch of dirty objects that need
! 1884: to be flushed. If the function is not NULL, this function
! 1885: will be called to get a reference of a dirty object.
! 1886: This is repeated until a null reference is returned by
! 1887: the client function or the parameter 'last' is set to
! 1888: TRUE. The parameter 'context' is passed to get()
! 1889: for each invocation of the client function. This
! 1890: parameter should be NULL if user callback is not given.
! 1891: If the object that is returned by the client function is
! 1892: not a dirtied persistent object, the object is ignored.
! 1893: All the objects that are returned from the client
! 1894: function must be from newed or pinned the same service
! 1895: context, otherwise, an error is signalled. Note that the
! 1896: returned objects are flushed in the order in which they
! 1897: are marked dirty.
! 1898: ref (OUT) [optional] - if there is an error in flushing the
! 1899: objects, (*ref) will point to the object that
! 1900: is causing the error. If 'ref' is NULL, then the object
! 1901: will not be returned. If '*ref' is NULL, then a
! 1902: reference will be allocated and set to point to the
! 1903: object. If '*ref' is not NULL, then the reference of
! 1904: the object is copied into the given space. If the
! 1905: error is not caused by any of the dirtied object,
! 1906: the given ref is initalized to be a NULL reference
! 1907: (OCIRefIsNull(*ref) is TRUE).
! 1908: REQUIRES:
! 1909: - a valid OCI environment handle must be given.
! 1910: DESCRIPTION:
! 1911: This function flushes the modified persistent objects from the
! 1912: environment heap to the server. The objects are flushed in the order
! 1913: that they are marked updated or deleted.
! 1914:
! 1915: See OCIObjectFlush() for more information about flushing.
! 1916:
! 1917: RETURNS:
! 1918: if environment handle or error handle is null, return
! 1919: OCI_INVALID_HANDLE.
! 1920: if operation suceeds, return OCI_SUCCESS.
! 1921: if operation fails, return OCI_ERROR.
! 1922: */
! 1923:
! 1924: /*--------------------------- OCICacheRefresh -------------------------------*/
! 1925: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1926: sword OCICacheRefresh(/*_ OCIEnv *env,OCIError *err,CONST OCISvcCtx *svc,
! 1927: OCIRefreshOpt option, dvoid *context,
! 1928: OCIRef *(*get)(dvoid *context), OCIRef **ref _*/);
! 1929: #else /* ANSI C */
! 1930: sword OCICacheRefresh(OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 1931: OCIRefreshOpt option, dvoid *context,
! 1932: OCIRef *(*get)(dvoid *context), OCIRef **ref);
! 1933: #endif
! 1934: /*
! 1935: NAME: OCICacheRefresh - OCI ReFreSh persistent objects
! 1936: PARAMETERS:
! 1937: env (IN/OUT) - OCI environment handle initialized in object mode
! 1938: err (IN/OUT) - error handle. If there is an error, it is
! 1939: recorded in 'err' and this function returns
! 1940: OCI_ERROR. The error recorded in 'err' can be
! 1941: retrieved by calling OCIErrorGet().
! 1942: svc (IN) [optional] - OCI service context. If null pointer is
! 1943: specified, then the persistent objects in all connections
! 1944: will be refreshed.
! 1945: option (IN) [optional] - if OCI_REFRESH_LOAD is specified, all
! 1946: objects that is loaded within the transaction are
! 1947: refreshed. If the option is OCI_REFERSH_LOAD and the
! 1948: parameter 'get' is not NULL, this function will ignore
! 1949: the parameter.
! 1950: context (IN) [optional] - specifies an user context that is an
! 1951: argument to the client callback function 'get'. This
! 1952: parameter is set to NULL if there is no user context.
! 1953: get (IN) [optional] - an client-defined function which acts an
! 1954: iterator to retrieve a batch of objects that need to be
! 1955: refreshed. If the function is not NULL, this function
! 1956: will be called to get a reference of an object. If
! 1957: the reference is not NULL, then the object will be
! 1958: refreshed. These steps are repeated until a null
! 1959: reference is returned by this function. The parameter
! 1960: 'context' is passed to get() for each invocation of the
! 1961: client function. This parameter should be NULL if user
! 1962: callback is not given.
! 1963: ref (OUT) [optional] - if there is an error in refreshing the
! 1964: objects, (*ref) will point to the object that
! 1965: is causing the error. If 'ref' is NULL, then the object
! 1966: will not be returned. If '*ref' is NULL, then a
! 1967: reference will be allocated and set to point to the
! 1968: object. If '*ref' is not NULL, then the reference of
! 1969: the object is copied into the given space. If the
! 1970: error is not caused by any of the object,
! 1971: the given ref is initalized to be a NULL reference
! 1972: (OCIRefIsNull(*ref) is TRUE).
! 1973: REQUIRES:
! 1974: - a valid OCI environment handle must be given.
! 1975: DESCRIPTION:
! 1976: This function refreshes all pinned persistent objects. All unpinned
! 1977: persistent objects are freed. See OCIObjectRefresh() for more
! 1978: information about refreshing.
! 1979: RETURNS:
! 1980: if environment handle or error handle is null, return
! 1981: OCI_INVALID_HANDLE.
! 1982: if operation suceeds, return OCI_SUCCESS.
! 1983: if operation fails, return OCI_ERROR.
! 1984: */
! 1985:
! 1986: /*---------------------------- OCICacheUnpin --------------------------------*/
! 1987: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 1988: sword OCICacheUnpin(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc _*/);
! 1989: #else /* ANSI C */
! 1990: sword OCICacheUnpin( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
! 1991: #endif
! 1992: /*
! 1993: NAME: OCICacheUnpin - OCI UNPin objects
! 1994: PARAMETERS:
! 1995: env (IN/OUT) - OCI environment handle initialized in object mode
! 1996: err (IN/OUT) - error handle. If there is an error, it is
! 1997: recorded in 'err' and this function returns
! 1998: OCI_ERROR. The error recorded in 'err' can be
! 1999: retrieved by calling OCIErrorGet().
! 2000: svc (IN) [optional] - OCI service context. If null pointer is
! 2001: specified, then the objects in all connections
! 2002: will be unpinned.
! 2003: REQUIRES:
! 2004: - a valid OCI environment handle must be given.
! 2005: DESCRIPTION:
! 2006: If a connection is specified, this function completely unpins the
! 2007: persistent objects in that connection. Otherwise, all persistent
! 2008: objects in the heap are completely unpinned. All transient objects in
! 2009: the heap are also completely unpinned. See OCIObjectUnpin() for more
! 2010: information about unpinning.
! 2011: RETURNS:
! 2012: if environment handle or error handle is null, return
! 2013: OCI_INVALID_HANDLE.
! 2014: if operation suceeds, return OCI_SUCCESS.
! 2015: if operation fails, return OCI_ERROR.
! 2016: */
! 2017:
! 2018: /*----------------------------- OCICacheFree --------------------------------*/
! 2019: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2020: sword OCICacheFree(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc _*/);
! 2021: #else /* ANSI C */
! 2022: sword OCICacheFree( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
! 2023: #endif
! 2024: /*
! 2025: NAME: OCICacheFree - OCI FREe instances
! 2026: PARAMETERS:
! 2027: env (IN/OUT) - OCI environment handle initialized in object mode
! 2028: err (IN/OUT) - error handle. If there is an error, it is
! 2029: recorded in 'err' and this function returns
! 2030: OCI_ERROR. The error recorded in 'err' can be
! 2031: retrieved by calling OCIErrorGet().
! 2032: svc (IN) [optional] - OCI service context. If null pointer is
! 2033: specified, then the objects in all connections
! 2034: will be freed.
! 2035: REQUIRES:
! 2036: - a valid OCI environment handle must be given.
! 2037: DESCRIPTION:
! 2038: If a connection is specified, this function frees the persistent
! 2039: objects, transient objects and values allocated for that connection.
! 2040: Otherwise, all persistent objects, transient objects and values in the
! 2041: heap are freed. Objects are freed regardless of their pin count. See
! 2042: OCIObjectFree() for more information about freeing an instance.
! 2043: RETURNS:
! 2044: if environment handle or error handle is null, return
! 2045: OCI_INVALID_HANDLE.
! 2046: if operation suceeds, return OCI_SUCCESS.
! 2047: if operation fails, return OCI_ERROR.
! 2048: */
! 2049:
! 2050: /*---------------------------- OCICacheUnmark -------------------------------*/
! 2051: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2052: sword OCICacheUnmark(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc _*/);
! 2053: #else /* ANSI C */
! 2054: sword OCICacheUnmark( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
! 2055: #endif
! 2056: /*
! 2057: NAME: OCICacheUnmark - OCI Unmark all dirty objects
! 2058: PARAMETERS:
! 2059: env (IN/OUT) - OCI environment handle initialized in object mode
! 2060: err (IN/OUT) - error handle. If there is an error, it is
! 2061: recorded in 'err' and this function returns
! 2062: OCI_ERROR. The error recorded in 'err' can be
! 2063: retrieved by calling OCIErrorGet().
! 2064: svc (IN) [optional] - OCI service context. If null pointer is
! 2065: specified, then the objects in all connections
! 2066: will be unmarked.
! 2067: REQUIRES:
! 2068: - a valid OCI environment handle must be given.
! 2069: DESCRIPTION:
! 2070: If a connection is specified, this function unmarks all dirty objects
! 2071: in that connection. Otherwise, all dirty objects in the cache are
! 2072: unmarked. See OCIObjectUnmark() for more information about unmarking
! 2073: an object.
! 2074: RETURNS:
! 2075: if environment handle or error handle is null, return
! 2076: OCI_INVALID_HANDLE.
! 2077: if operation suceeds, return OCI_SUCCESS.
! 2078: if operation fails, return OCI_ERROR.
! 2079: */
! 2080:
! 2081:
! 2082: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2083: sword OCIDurationBegin(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 2084: OCIDuration parent, OCIDuration *dur _*/);
! 2085: #else /* ANSI C */
! 2086: sword OCIDurationBegin( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 2087: OCIDuration parent, OCIDuration *dur );
! 2088: #endif
! 2089: /*
! 2090: NAME: OCIDurationBegin - OCI DURATION BEGIN
! 2091: PARAMETERS:
! 2092: env (IN/OUT) - OCI environment handle initialized in object mode
! 2093: This should be passed NULL, when cartridge services
! 2094: are to be used.
! 2095: err (IN/OUT) - error handle. If there is an error, it is
! 2096: recorded in 'err' and this function returns OCI_ERROR.
! 2097: The error recorded in 'err' can be retrieved by calling
! 2098: OCIErrorGet().
! 2099: svc (IN/OUT) - OCI service handle.
! 2100: parent (IN) - parent for the duration to be started.
! 2101: dur (OUT) - newly created user duration
! 2102: REQUIRES:
! 2103: - a valid OCI environment handle must be given for non-cartridge
! 2104: services.
! 2105: - For cartridge services, NULL should be given for environment handle
! 2106: - A valid service handle must be given in all cases.
! 2107: DESCRIPTION:
! 2108: This function starts a new user duration. A user can have multiple
! 2109: active user durations simultaneously. The user durations do not have
! 2110: to be nested.
! 2111:
! 2112: The object subsystem predefines 3 durations :
! 2113: 1) session - memory allocated with session duration comes from
! 2114: the UGA heap (OCI_DURATION_SESSION). A session
! 2115: duration terminates at the end of the user session.
! 2116: 2) transaction - memory allocated with transaction duration comes
! 2117: from the UGA heap (OCI_DURATION_TRANS). A trans-
! 2118: action duration terminates at the end of the user
! 2119: transaction.
! 2120: 3) call - memory allocated with call duration comes from PGA
! 2121: heap (OCI_DURATION_CALL). A call duration terminates
! 2122: at the end of the user call.
! 2123:
! 2124: Each user duration has a parent duration. A parent duration can be a
! 2125: predefined duration or another user duration. The relationship between
! 2126: a user duration and its parent duration (child duration) are:
! 2127:
! 2128: 1) An user duration is nested within the parent duration. When its
! 2129: parent duration terminates, the user duration will also terminate.
! 2130: 2) The memory allocated with an user duration comes from the heap of
! 2131: its parent duration. For example, if the parent duration of an
! 2132: user duration is call, then the memory allocated with the user
! 2133: duration will also come from the PGA heap.
! 2134:
! 2135: This function can be used as both part of cartridge services as well
! 2136: as without cartridge services.
! 2137: The difference in the function in the case of cartridge and
! 2138: non-cartridge services is:
! 2139: In case of cartridge services, as descibed above a new user
! 2140: duration is created as a child of the "parent" duration.
! 2141: But when used for non-cartridge purposes, when a pre-defined
! 2142: duration is passed in as parent, it is mapped to the cache duration
! 2143: for that connection (which is created if not already present) and
! 2144: the new user duration will be child of the cache duration.
! 2145:
! 2146: RETURNS:
! 2147: if environment handle and service handle is null or if error
! 2148: handle is null return OCI_INVALID_HANDLE.
! 2149: if operation suceeds, return OCI_SUCCESS.
! 2150: if operation fails, return OCI_ERROR.
! 2151: */
! 2152:
! 2153:
! 2154: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2155: sword OCIDurationEnd(/*_ OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 2156: OCIDuration duration _*/);
! 2157: #else /* ANSI C */
! 2158: sword OCIDurationEnd( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc,
! 2159: OCIDuration duration );
! 2160: #endif
! 2161: /*
! 2162: NAME: OCIDurationEnd - OCI DURATION END
! 2163: PARAMETERS:
! 2164: env (IN/OUT) - OCI environment handle initialized in object mode
! 2165: This should be passed NULL, when cartridge services
! 2166: are to be used.
! 2167: err (IN/OUT) - error handle. If there is an error, it is
! 2168: recorded in 'err' and this function returns OCI_ERROR.
! 2169: The error recorded in 'err' can be retrieved by calling
! 2170: OCIErrorGet().
! 2171: svc (IN/OUT) - OCI service handle.
! 2172: dur (OUT) - a previously created user duration using
! 2173: OCIDurationBegin()
! 2174: REQUIRES:
! 2175: - a valid OCI environment handle must be given for non-cartridge
! 2176: services.
! 2177: - For cartridge services, NULL should be given for environment handle
! 2178: - A valid service handle must be given in all cases.
! 2179: DESCRIPTION:
! 2180: This function terminates a user duration. All memory allocated for
! 2181: this duration is freed.
! 2182:
! 2183: This function can be used as both part of cartridge services as well
! 2184: as without cartridge services. In both cased, the heap duration
! 2185: is freed and all the allocated memory for that duration is freed.
! 2186: The difference in the function in the case of cartridge and
! 2187: non-cartridge services is:
! 2188: In case of non-cartridge services, if the duration is pre-
! 2189: defined, the associated cache duration (see OCIDurationBegin())
! 2190: is also terminated and the following is done.
! 2191: 1) The child durations are terminated.
! 2192: 2) All objects pinned for this duration are unpinned.
! 2193: 3) All instances allocated for this duration are freed.
! 2194:
! 2195: In case of cartridge services, only the heap duration is
! 2196: freed. All the context entries allocated for that duration are
! 2197: freed from the context hash table..
! 2198:
! 2199: RETURNS:
! 2200: if environment handle and service handle is null or if error
! 2201: handle is null return OCI_INVALID_HANDLE.
! 2202: if operation suceeds, return OCI_SUCCESS.
! 2203: if operation fails, return OCI_ERROR.
! 2204: */
! 2205:
! 2206: /******************************************************************************
! 2207: ** DO NOT USE THE FUNCTIONS BELOW! **
! 2208: ** UNSUPPORTED INTERFACE **
! 2209: ** WILL BE REMOVED/CHANGED IN A FUTURE RELEASE **
! 2210: ******************************************************************************/
! 2211:
! 2212: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2213: sword OCIDurationGetParent(/*_ OCIEnv *env, OCIError *err,
! 2214: OCIDuration duration, OCIDuration *parent _*/);
! 2215: #else /* ANSI C */
! 2216: sword OCIDurationGetParent( OCIEnv *env, OCIError *err,
! 2217: OCIDuration duration, OCIDuration *parent );
! 2218: #endif
! 2219:
! 2220: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2221: sword OCIObjectAlwaysLatest(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 2222: #else /* ANSI C */
! 2223: sword OCIObjectAlwaysLatest( OCIEnv *env, OCIError *err, dvoid *object );
! 2224: #endif
! 2225:
! 2226: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2227: sword OCIObjectNotAlwaysLatest(/*_ OCIEnv *env, OCIError *err,
! 2228: dvoid *object _*/);
! 2229: #else /* ANSI C */
! 2230: sword OCIObjectNotAlwaysLatest( OCIEnv *env, OCIError *err,
! 2231: dvoid *object );
! 2232: #endif
! 2233:
! 2234: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2235: sword OCIObjectFlushRefresh(/*_ OCIEnv *env, OCIError *err, dvoid *object _*/);
! 2236: #else /* ANSI C */
! 2237: sword OCIObjectFlushRefresh( OCIEnv *env, OCIError *err, dvoid *object);
! 2238: #endif
! 2239:
! 2240: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2241: sword OCIObjectIsLoaded(/*_ OCIEnv *env, OCIError *err, dvoid *ins,
! 2242: boolean *load _*/);
! 2243: #else /* ANSI C */
! 2244: sword OCIObjectIsLoaded( OCIEnv *env, OCIError *err, dvoid *ins,
! 2245: boolean *load);
! 2246: #endif
! 2247:
! 2248: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2249: sword OCIObjectIsDirtied(/*_ OCIEnv *env, OCIError *err, dvoid *ins,
! 2250: boolean *dirty _*/);
! 2251: #else /* ANSI C */
! 2252: sword OCIObjectIsDirtied( OCIEnv *env, OCIError *err, dvoid *ins,
! 2253: boolean *dirty);
! 2254: #endif
! 2255:
! 2256: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2257: sword OCICacheGetObjects(/*_ OCIEnv *env, OCIError *err,
! 2258: CONST OCISvcCtx *svc,
! 2259: OCIObjectProperty property,
! 2260: dvoid *client_context,
! 2261: void (*client_callback)(
! 2262: dvoid *client_context,
! 2263: dvoid *object ) _*/);
! 2264: #else /* ANSI C */
! 2265: sword OCICacheGetObjects( OCIEnv *env, OCIError *err,
! 2266: CONST OCISvcCtx *svc,
! 2267: OCIObjectProperty property,
! 2268: dvoid *client_context,
! 2269: void (*client_callback)(
! 2270: dvoid *client_context,
! 2271: dvoid *object ));
! 2272: #endif
! 2273:
! 2274: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2275: sword OCICacheRegister(/*_ OCIEnv *env, OCIError *err,
! 2276: OCIObjectEvent event,
! 2277: dvoid *client_context,
! 2278: void (*client_callback)(
! 2279: dvoid *client_context,
! 2280: OCIObjectEvent event,
! 2281: dvoid *object ) _*/);
! 2282: #else /* ANSI C */
! 2283: sword OCICacheRegister( OCIEnv *env, OCIError *err,
! 2284: OCIObjectEvent event,
! 2285: dvoid *client_context,
! 2286: void (*client_callback)(
! 2287: dvoid *client_context,
! 2288: OCIObjectEvent event,
! 2289: dvoid *object));
! 2290: #endif
! 2291:
! 2292: #if !defined(__STDC__) && !defined(__cplusplus) /* K&R C - not ANSI C */
! 2293: sword OCICacheFlushRefresh(/*_ OCIEnv *env, OCIError *err,
! 2294: CONST OCISvcCtx *svc, dvoid *context,
! 2295: OCIRef *(*get)(dvoid *context, ub1 *last),
! 2296: OCIRef **ref _*/);
! 2297: #else /* ANSI C */
! 2298: sword OCICacheFlushRefresh( OCIEnv *env, OCIError *err,
! 2299: CONST OCISvcCtx *svc, dvoid *context,
! 2300: OCIRef *(*get)(dvoid *context, ub1 *last),
! 2301: OCIRef **ref );
! 2302: #endif
! 2303:
! 2304: #endif /* ORI_ORACLE */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ori.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / sql / oracle / include / oci