Annotation of win32/sql/oracle/include/oci/ori.h, revision 1.1.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