/* Copyright (c) 1994, 2006, Oracle. All rights reserved. */ /* NAME ORI - OCI navigational interface DESCRIPTION This section is intended to give a brief introduction to the navigational interfaces. Readers can refer to the documents listed in the section 'RELATED DOCUMENTS' for more information. PURPOSE The Oracle Call Interface (OCI) supports navigational access of objects. In the navigational paradigm, data is represented as a graph of objects connected by references. Objects in the graph are reached by following the references. OBJECT ENVIRONMENT The object environment is initialized when the OCI environment handle is initialized with the object option. An object environment contains a heap which buffers type instances in memory. The object environment also contains an object cache which keeps track of the objects in the object environment. Readers can refer to the "Functional Specification for Programmatic Interface" for more information about the object environment. INSTANCE, OBJECT AND VALUE An OTS instance is an occurence of a type specified by the Oracle Type System (OTS). This section describes how an OTS instance can be represented in OCI. In OCI, an OTS instance can be classified based on the type, the lifetime and referencability (see the figure below): 1) A persistent object is an instance of an object type. A persistent object resides in a row of a table in the server and can exist longer than the duration of a session (connection). Persistent objects can be identified by object references which contain the object identifiers. A persistent object is obtained by pinning its object reference. 2) A transient object is an instance of an object type. A transient object cannot exist longer than the duration of a session, and it is used to contain temporary computing results. Transient objects can also be identified by references which contain transient object identifiers. 3) A value is an instance of an user-defined type (object type or collection type) or any built-in OTS type. Unlike objects, values of object types are identified by memory pointers, rather than by references. A value can be standalone or embbeded. A standalone value is usually obtained by issuing a select statement. OCI also allows the client program to select a row of object table into a value by issuing a SQL statement. Thus, a referenceable object (in the database) can be represented as a value (which cannot be identified by a reference). A standalone value can also be an out-of-line attribute in an object (e.g varchar, raw) or an out-of-line element in a collection (e.g. varchar, raw, object). An embedded value is phyiscally included in a containing instance. An embedded value can be an in-line attribute in an object (e.g. number, nested object) or an in-line element in a collection. All values are considered to be transient by OCI, e.g. OCI does not support automatic flushing a value to the database, and the client has to explicitly execute a SQL statement to store a value into the database. For embedded values, they are flushed when their containing instance are flushed. OTS instance | | v v object value (type) | | v v persistent transient (lifetime) persistent obj transient obj value --------------------------------------------------------------- | | | | object type, | | type | object type | object type | built-in, | | | | | collection | --------------------------------------------------------------- | maximum | until object | session | session | | lifetime | is deleted | | | --------------------------------------------------------------- | referencable | yes | yes | no | --------------------------------------------------------------- | embeddable | no | no | yes | --------------------------------------------------------------- REFERENCEABLE OBJECT, STANDALONE OBJECT, EMBEDDED OBJECT In the reminding of this include file, the following term will be used: 1) The term 'object' can be generally referred to a persistent object, a transient object, a standalone value of object type, or an embedded value of object type. 2) The term 'referenceable object' refers to a persistent object or a transient object. 3) The term 'standalone object' refers to a persistent object, a transient object or a standalone value of object type. 4) The term 'embedded object' referes to a embbeded value of object type. META ATTRIBUTES There is a set of meta-attributes that are defined for standalone objects. A meta-attribute can be transient or persistent. A transient meta-attribute is applicable to an instance only when it is in memory. A persistent meta-attribute can be applicable to an instance that is in the disk. The set of user visible meta-attributes for persistent objects are: 1) existent (persistent) : Does the object exist? 2) nullness (persistent) : Null information of the instance 3) locked (persistent) : Is the object locked? 4) pinned (transient) : Is the object being accessed by the client? 5) dirty (transient) : Has the object been modified? 6) allocation duration (transient) : see below 7) pin duration (transient) : see below The set of user visible meta-attributes for transient objects are: 1) existent (transient) : Does the object exist? 2) nullness (transient) : Null information of the instance 3) pinned (transient) : Is the object being accessed by the client? 4) dirty (transient) : Has the object been modified? 4) allocation duration (transient) : see below 5) pin duration (transient) : see below The set of user visible meta-attributes for standalone values of object type or collections are: 1) allocation duration (transient) : see below 2) nullness (transient) : Null information of the instance (of an object type) NULLNESS OF AN INSTANCE Each standalone object is associated with a null structure which keeps the null information about the object. A null indicates the absence of data. The null structure itself contains null indicators that represent: 1) atomic nullness : a null value that pertains to the whole object 2) null status of the individual attribute in the object The layout of a null structure in memory resembles that of the object, except that the null structure has additional indicators to represent the atomic nullness for each object. An non-existent object is different than an object that is atomically null. A atomically null object is an existing object that has no data. MEMORY LAYOUT OF AN OBJECT A standalone object in memory is composed of a top level memory chunk, a null structure and optionally, a number of secondary memory chunks. For a DEPARTMENT object type, OBJECT TYPE department { dep_name varchar2(20), budget number, manager person, /o person is an object type o/ employees collection of person } Each instance of DEPARTMENT will has a top level memory chunk which contains the top level attributes such as dep_name, budget, manager and employees. The attributes dep_name and employees are themselves pointers to the additional memory (the secondary memory chunks). The secondary memory is for the out-of-line attribute (e.g. varray). CONSISTENCY MODEL Each pin operation behaves like a distinct SQL select. Thus, the object cache does not guarantee consistency for a graph of objects. In order to retrieve a consistent graph of objects, the user has to explicitly start a serializable transaction or a read-only transaction. DURATION In OCI, a duration is used to specify 1) the length of memory allocation of an instance When each instance is allocated, it is associate with an allocation duration. The memory occupied by the object is freed automatically at the end of its allocation duration. The allocation duration of an instance cannot be changed. 2) the length of pinning of an object When each object is pinned, the client has to give a pin duration which specify the length of time that the object is intended to be used. It is an user error to specify a pin duration longer than an allocation duration of the object. An object is completely unpinned at the end of its pin duration (see OCIObjectUnpin()). An OCI program can use the allocation duration and the pin duration to automatically free the memory of the instances: 1) Transient objects and values are freed at the end of the allocation duration. 2) Persistent objects ARE freed at the end of the allocation duration. Persistent objects CAN be freed at the end of the pin duration when the objects are completely unpinned. The persistent objects are said to be aged out. See OCIObjectUnpin() for more details. There are 3 predefined duration: session, transaction, call. The time spans of these durations are defined based on the programming model presented by OCI. The call duration is mapped to the transaction duration in the client-side environment. See oro.h for the macros defined for these 3 durations. A pin duration can be promoted. For example, if an object is pinned with duration 1, and the object is later pinned with duration 2, the pin routine will try to find a duration that is longer or equal to the length of both duration 1 and duration 2. The pin duration of the object is set to the that duration. The object is automatically unpinned only after both duration 1 and duration 2 are terminated. RELATED DOCUMENTS "Functional Specification for Oracle Object RDBMS" "Functional Specification for Programmatic Interfaces" "Functional Specification for the Oracle Type System (OTS)" INSPECTION STATUS Inspection date: Inspection status: Estimated increasing cost defects per page: Rule sets: ACCEPTANCE REVIEW STATUS Review date: Review status: Reviewers: PUBLIC FUNCTIONS OCIObjectNew - OCI new a standalone instance OCIObjectPin - OCI pin an object by reference OCIObjectUnpin - OCI unpin a referenceable object OCIObjectPinCountReset - OCI reset the pin count of a referenceable object OCIObjectLock - OCI lock a persistent object OCIObjectLockNoWait - OCI lock a persistent object OCIObjectMarkUpdate - OCI mark a referenceable object as updated OCIObjectUnmark - OCI unmark a dirtied referenceable object OCIObjectUnmarkByRef - OCI unmark a dirtied object by reference OCIObjectFree - OCI free a standalone instance OCIObjectMarkDelete - OCI mark a referenceable object as deleted OCIObjectMarkDeleteByRef - OCI mark a referenceable object as deleted by giving a reference OCIObjectFlush - OCI flush a persistent object OCIObjectRefresh - OCI refresh a persistent object OCIObjectCopy - OCI CoPy one object to another OCIObjectGetTypeRef - OCI get the Type Reference of a standalone object OCIObjectGetObjectRef - OCI get the Object's Reference OCIObjectGetInd - OCI get Null Structure of an standalone object OCIObjectExists - OCI get the existence of a referenceable object OCIObjectGetProperty - get object property OCIObjectIsLocked - OCI get the lock status of a referenceable object OCIObjectIsDirty - OCI get the dirty status of a referenceable object OCIObjectPinTable - OCI get Table object OCIObjectArrayPin - OCI pin array of objects OCIObjectGetPrimayKeyTypeRef - OCI get the Ref for the primary key OID's type OCIObjectMakeObjectRef - OCI Create a pk or sys generated REF OCIObjectGetNewOID - OCI Create a new Object ID OCICacheFlush - OCI flsuh the modified persistent objects in the cache OCICacheRefresh - OCI refresh persistent objects in the cache OCICacheUnpin - OCI unpin referenceable objects in the cache OCICacheFree - OCI free all instances in the environment OCICacheUnmark - OCI unmark all dirty referenceable objects in the cache PRIVATE FUNCTIONS None EXAMPLES The following types will be used in the examples in this section: OBJECT TYPE professor ( varchar2 name; number department; number num_of_students; ); OBJECT TYPE course ( varchar2 name; number grade; ); OBJECT TYPE student ( vstring name; number department; ref advisor; /o advisor is a professor o/ collection courses; ); EXAMPLE 1 Here is a set of examples to illustrate the usages of some of the orio and oric functions. OCIenv *env; /o OCI environment handle o/ OCIError *err; /o OCI error handle o/ OCISvcCtx *svc; /o OCI service handle o/ void *stu_tbl; /o pointer to the student table o/ OCIType *stu_tdo; /o student type tdo o/ OCIRef *stu2_ref; /o object reference to student object o/ student *stu1; /o pointer to the student object o/ student *stu2; /o pointer to the student object o/ professor *pro; /o pointer to the professor object o/ /o Initialize the OCI environment handle, error handle and service handle and login to the database o/ ... /o CREATE A PERSISTENT OBJECT o/ /o get the table object of student o/ if (OCIObjectPinTable(env, err, svc, "ORACLEU", sizeof("ORACLEU"), "STUDENT_TABLE", sizeof("STUDENT_TABLE"), (OCIRef *)0, OCI_DURATION_NULL, &stu_tbl) != OCI_SUCCESS) /o error handling code o/ /o get type object of student o/ if (OCITypeByName(env, err, svc, "ORACLEU", sizeof("ORACLEU"), "STUDENT", sizeof("STUDENT"), OCI_DURATION_NULL, OCI_TYPEGET_HEADER, &stu_tdo) != OCI_SUCCESS) /o error handling code o/ /o create a persistent object 'mark' (of type student) o/ if (OCIObjectNew(env, err, svc, OCI_TYPECODE_ADT, stu_tdo, stu_tbl, OCI_DURATION_TRANS, (ub1)FALSE, (void **)&stu1) != OCI_SUCCESS) /o error handling code o/ /o RETRIEVE OBJECTS IN PERSISTENT STORES o/ /o Use OCI to retrieve a reference to student object 'joe'. o The retrieved reference is bound to the variable stu2_ref. o/ /o pin/retrieve the student "joe" by reference o/ if (OCIObjectPin(env, err, &stu2_ref, (OCIComplexObject *)0, OCI_PIN_ANY, OCI_DURATION_TRANS, OCI_LOCK_X, &stu2) != OCI_SUCCESS) /o error handling code o/ /o pin/retrieve the advisor of student "joe" by reference o/ if (OCIObjectPin(env, err, &stu2->advisor, (OCIComplexObject *)0, OCI_PIN_ANY, OCI_DURATION_TRANS, OCI_LOCK_X, &pro) != OCI_SUCCESS) /o error handling code o/ /o MODIFY OBJECTS o/ /o initialize the newly created object "mark" o/ DISCARD OCIStringAssignText(env, err, "mark", sizeof("mark"), &stu1->name); department = 522; DISCARD OCINumberFromInt(err, &department, sizeof(department), OCI_NUMBER_UNSIGNED, &stu1->department); /o assign advisor to student "mark" o/ DISCARD OCIRefAssign(env, err, &stu2->advisor, &stu1->advisor); /o update student "joe". o/ department = 533; DISCARD OCINumberFromInt(err, &department, sizeof(department), OCI_NUMBER_UNSIGNED, &stu2->department); DISCARD OCIObjectMarkUpdate(env, err, stu2); /o UNPIN OBJECTS AFTER FINSIHED PROCESSING THEM o/ /o unpin the student object "mark" o/ if (OCIObjectUnpin(env, err, stu1) != OCI_SUCCESS) /o error handling code o/ /o unpin the student object "joe" o/ if (OCIObjectUnpin(env, err, stu2) != OCI_SUCCESS) /o error handling code o/ /o unpin the professor object o/ if (OCIObjectUnpin(env, err, pro) != OCI_SUCCESS) /o error handling code o/ /o unpin the type object o/ if (OCIObjectUnpin(env, err, stu_tdo) != OCI_SUCCESS) /o error handling code o/ /o unpin the table object o/ if (OCIObjectUnpin(env, err, stu_tbl) != OCI_SUCCESS) /o error handling code o/ /o FLUSH MODIFIED OBJECTS BACK TO PERSISTENT STORE o/ if (OCICacheFlush(env, err, svc, (void *)0, ((OCIRef*)(*)())0, (OCIRef *)0) != OCI_SUCCESS) /o error handling code o/ /o commit transaction o/ END OF EXAMPLE 1 NOTES This file has been subsetted to contain only the routines that will be in the first release. MODIFIED dmukhin 06/29/05 - ANSI prototypes; miscellaneous cleanup srseshad 03/12/03 - convert oci public api to ansi aahluwal 06/03/02 - bug 2360115 bpalaval 02/09/01 - Change text to oratext. rkasamse 06/21/00 - add ociobjectgetnewoid rkasamse 05/24/00 - add OCIObjectSetData whe 09/01/99 - 976457:check __cplusplus for C++ code smuralid 10/29/98 - add comments for OCIObjectMakeObjectRef mkrishna 08/19/98 - change OCIGetPkTypeRef to OCIObjectGetPrimaryKeyTypeR mkrishna 08/10/98 - add OCIObjectMakeObjectRef & OCIObjectGetPkTypeRef rkasamse 06/22/98 - add comments for OCIDurationBegin(End) pmitra 04/01/98 - OCIObjectLockNoWait added pmitra 11/05/97 - [573769] OCIObjectArrayPin pos parameter cannot be NU cxcheng 07/29/97 - fix compile for short names skrishna 07/14/97 - add OCIObjectGetProperty skrishna 04/30/97 - OCIObjectFlushRefresh: remove duplicate declaration skrishna 04/24/97 - flag unsupported functions sthakur 03/20/97 - modify flag argument to OCIObjectFree skrishna 03/18/97 - fix ifdef for supporting ansi and k&r proto-types cxcheng 02/19/97 - remove short names support cxcheng 02/06/97 - take out short name support except with SLSHORTNAME sthakur 12/20/96 - fix a typepo in OCIOBjectArrayPin jboonleu 11/07/96 - modify comments cxcheng 10/28/96 - more beautification changes jboonleu 10/24/96 - add flag to OCIObjectFree jboonleu 10/22/96 - change interface of OCICacheFlush cxcheng 10/18/96 - rename OCIObjectPinArray to OCIObjectArrayPin cxcheng 10/14/96 - more renaming of types jboonleu 10/09/96 - add new interfaces cxcheng 10/09/96 - more lint fixes cxcheng 10/08/96 - more lint fixes jboonleu 09/27/96 - fix lint errors jboonleu 10/07/96 - beautify ori.h after conversion to long names cxcheng 10/04/96 - replace short names with long names sthakur 08/20/96 - add COR context to OCIObjectPin mluong 07/17/96 - add back orioglk, oriogdr, oriogiv, and oriocur. jboonleu 07/17/96 - rename refresh option to conherency option jboonleu 07/16/96 - change comment for cache consistency jwijaya 07/03/96 - add ANSI prototypes jboonleu 06/12/96 - update comment jboonleu 05/08/96 - change description of OCIDurationGetParent jboonleu 05/01/96 - add OROOCOSFN skrishna 04/08/96 - change ori*() to take OCIEnv* and OCIError* instead of oroenv* jboonleu 01/04/96 - interface change jboonleu 10/24/95 - support of variable ref jboonleu 02/15/95 - new interface sthakur 01/05/95 - pass username to origrgc skotsovo 12/07/94 - update example jwijaya 11/15/94 - rename ORONSPTAB to ORONSPEXT jwijaya 10/06/94 - add namespace to oriopnm() jwijaya 10/02/94 - connection handle -> connection number jboonleu 08/16/94 - fix lint errors jboonleu 07/20/94 - change interface of OCICacheFlush tanguyen 07/18/94 - add oriocpe, change OCIObjectCopy to oriocps tcheng 07/15/94 - add init param maximum_sga_heap_size tcheng 07/13/94 - change origini to get param string jboonleu 07/05/94 - change sccs string from sccid to a comment jboonleu 07/01/94 - Add examples to ORIO* and ORIC* functions tanguyen 06/30/94 - Fix the ORI_ORACLE ifdef skotsovo 06/27/94 - include all public functions in public functions list at top of header file tcheng 06/27/94 - modify comments according to new template tanguyen 06/24/94 - fix comments for OCIObjectCopy tcheng 06/24/94 - fix comments in origrgc() tanguyen 06/21/94 - fix comments and format tcheng 06/20/94 - commenting origini/trm/err/rgc/urg() functions tanguyen 06/16/94 - fix descriptions of ref operations tanguyen 06/16/94 - clarifies refs comparison tanguyen 05/12/94 - adds more interfaces (OCIObjectMarkUpdate) jwijaya 05/10/94 - fix examples, add origurg, change origcon to origrgc tanguyen 05/03/94 - remove unnecessary 'type' argument from 'OCIObjectCopy' tanguyen 03/08/94 - clarifies comments jwijaya 02/16/94 - more questions jwijaya 02/11/94 - more comments jwijaya 02/10/94 - identify optional arguments jwijaya 02/07/94 - Creation */ #ifndef ORATYPES #include #endif #ifndef ORO_ORACLE #include #endif #ifndef OCI_ORACLE #include #endif #ifndef ORT_ORACLE #include #endif #ifndef ORI_ORACLE #define ORI_ORACLE /*---------------------------------------------------------------------------*/ /* SHORT NAMES SUPPORT SECTION */ /*---------------------------------------------------------------------------*/ #ifdef SLSHORTNAME /* the following are short names that are only supported on IBM mainframes with the SLSHORTNAME defined. With this all subsequent long names will actually be substituted with the short names here */ #define OCIDurationBegin origbgu #define OCIDurationEnd origedu #define OCIDurationGetParent origpdr #define OCICacheFlushRefresh oricfrh #define OCICacheUnpin oricunp #define OCICacheFree oricfre #define OCICacheUnmark oricumk #define OCICacheGetObjects oricgpr #define OCICacheRegister oricscb #define OCIObjectUnpin oriounp #define OCIObjectPinCountReset orioupz #define OCIObjectLock oriolck #define OCIObjectLockNoWait oriolnw #define OCIObjectMarkUpdate orioupd #define OCIObjectUnmark orioumk #define OCIObjectUnmarkByRef orioumr #define OCIObjectAlwaysLatest oriomkl #define OCIObjectNotAlwaysLatest oriouml #define OCIObjectMarkDeleteByRef oriordl #define OCIObjectMarkDelete oriopdl #define OCIObjectFlush oriofls #define OCIObjectFlushRefresh oriofrh #define OCIObjectCopy oriocpy #define OCIObjectGetTypeRef oriogtr #define OCIObjectGetObjectRef oriogor #define OCIObjectGetInd oriogns #define OCIObjectExists oriogex #define OCIObjectGetProperty oriogpr #define OCIObjectRefresh oriorfs #define OCIObjectPinTable oriogtb #define OCIObjectGetPrimaryKeyTypeRef oriogpf #define OCIObjectMakeObjectRef oriomrf #define OCIObjectNew orionew #define OCIObjectPin oriopin #define OCIObjectFree oriofre #define OCIObjectArrayPin orioapn #define OCIObjectIsDirty oriodrt #define OCIObjectIsDirtied oriodrd #define OCIObjectIsLoaded orioldd #define OCICacheFlush oricfls #define OCICacheRefresh oricrfs #endif /* SLSHORTNAME */ /*---------------------------------------------------------------------------*/ /* PUBLIC TYPES AND CONSTANTS */ /*---------------------------------------------------------------------------*/ /* Also see oro.h. */ /*---------------------------------------------------------------------------*/ /* PUBLIC FUNCTIONS */ /*---------------------------------------------------------------------------*/ /*---------------------------------------------------------------------------*/ /* OBJECT/INSTANCE OPERATIONS */ /*---------------------------------------------------------------------------*/ /*--------------------------- OCIObjectNew ----------------------------------*/ sword OCIObjectNew( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCITypeCode typecode, OCIType *tdo, void *table, OCIDuration duration, boolean value, void **instance ); /* NAME: OCIObjectNew - OCI new (create) a standalone instance PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) - OCI service handle. typecode (IN) - the typecode of the type of the instance. tdo (IN, optional) - pointer to the type descriptor object. The TDO describes the type of the instance that is to be created. Refer to OCITypeByName() for obtaining a TDO. The TDO is required for creating a named type (e.g. an object or a collection). table (IN, optional) - pointer to a table object which specifies a table in the server. This parameter can be set to NULL if no table is given. See the description below to find out how the table object and the TDO are used together to determine the kind of instances (persistent, transient, value) to be created. Also see OCIObjectPinTable() for retrieving a table object. duration (IN) - this is an overloaded parameter. The use of this parameter is based on the kind of the instance that is to be created. a) persistent object. This parameter specifies the pin duration. b) transient object. This parameter specififes the allocation duration and pin duration. c) value. This parameter specifies the allocation duration. value (IN) - specifies whether the created object is a value. If TRUE, then a value is created. Otherwise, a referenceable object is created. If the instance is not an object, then this parameter is ignored. instance (OUT) - address of the newly created instance REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function creates a new instance of the type specified by the typecode or the TDO. Based on the parameters 'typecode' (or 'tdo'), 'value' and 'table', different kinds of instances can be created: The parameter 'table' is not NULL? yes no ---------------------------------------------------------------- | object type (value=TRUE) | value | value | ---------------------------------------------------------------- | object type (value=FALSE) | persistent obj | transient obj | type ---------------------------------------------------------------- | built-in type | value | value | ---------------------------------------------------------------- | collection type | value | value | ---------------------------------------------------------------- This function allocates the top level memory chunk of an OTS instance. The attributes in the top level memory are initialized (e.g. an attribute of varchar2 is initialized to a vstring of 0 length). If the instance is an object, the object is marked existed but is atomically null. FOR PERSISTENT OBJECTS: The object is marked dirty and existed. The allocation duration for the object is session. The object is pinned and the pin duration is specified by the given parameter 'duration'. FOR TRANSIENT OBJECTS: The object is pinned. The allocation duration and the pin duration are specified by the given parameter 'duration'. FOR VALUES: The allocation duration is specified by the given parameter 'duration'. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectPin ----------------------------------*/ sword OCIObjectPin( OCIEnv *env, OCIError *err, OCIRef *object_ref, OCIComplexObject *corhdl, OCIPinOpt pin_option, OCIDuration pin_duration, OCILockOpt lock_option, void **object ); /* NAME: OCIObjectPin - OCI pin a referenceable object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object_ref (IN) - the reference to the object. corhdl (IN) - handle for complex object retrieval. pin_option (IN) - See description below. pin_duration (IN) - The duration of which the object is being accesed by a client. The object is implicitly unpinned at the end of the pin duration. If OCI_DURATION_NULL is passed, there is no pin promotion if the object is already loaded into the cache. If the object is not yet loaded, then the pin duration is set to OCI_DURATION_DEFAULT. lock_option (IN) - lock option (e.g., exclusive). If a lock option is specified, the object is locked in the server. See 'oro.h' for description about lock option. object (OUT) - the pointer to the pinned object. REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function pins a referenceable object instance given the object reference. The process of pinning serves three purposes: 1) locate an object given its reference. This is done by the object cache which keeps track of the objects in the object heap. 2) notify the object cache that an object is being in use. An object can be pinned many times. A pinned object will remain in memory until it is completely unpinned (see OCIObjectUnpin()). 3) notify the object cache that a persistent object is being in use such that the persistent object cannot be aged out. Since a persistent object can be loaded from the server whenever is needed, the memory utilization can be increased if a completely unpinned persistent object can be freed (aged out), even before the allocation duration is expired. Also see OCIObjectUnpin() for more information about unpinning. FOR PERSISTENT OBJECTS: When pinning a persistent object, if it is not in the cache, the object will be fetched from the persistent store. The allocation duration of the object is session. If the object is already in the cache, it is returned to the client. The object will be locked in the server if a lock option is specified. This function will return an error for a non-existent object. A pin option is used to specify the copy of the object that is to be retrieved: 1) If option is OCI_PIN_ANY (pin any), if the object is already in the environment heap, return this object. Otherwise, the object is retrieved from the database. This option is useful when the client knows that he has the exclusive access to the data in a session. 2) If option is OCI_PIN_LATEST (pin latest), if the object is not cached, it is retrieved from the database. If the object is cached, it is refreshed with the latest version. See OCIObjectRefresh() for more information about refreshing. 3) If option is OCI_PIN_RECENT (pin recent), if the object is loaded into the cache in the current transaction, the object is returned. If the object is not loaded in the current transaction, the object is refreshed from the server. FOR TRANSIENT OBJECTS: This function will return an error if the transient object has already been freed. This function does not return an error if an exclusive lock is specified in the lock option. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------------ OCIObjectUnpin -----------------------------*/ sword OCIObjectUnpin( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectUnpin - OCI unpin a referenceable object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to an object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function unpins an object. An object is completely unpinned when 1) the object was unpinned N times after it has been pinned N times (by calling OCIObjectPin()). 2) it is the end of the pin duration 3) the function OCIObjectPinCountReset() is called There is a pin count associated with each object which is incremented whenever an object is pinned. When the pin count of the object is zero, the object is said to be completely unpinned. An unpinned object can be freed without error. FOR PERSISTENT OBJECTS: When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed. FOR TRANSIENT OBJECTS: The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly deleted by calling OCIObjectFree(). FOR VALUE: This function will return an error for value. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCIObjectPinCountReset -----------------------*/ sword OCIObjectPinCountReset( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectPinCountReset - OCI resets the pin count of a referenceable object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to an object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function completely unpins an object. When an object is completely unpinned, it can be freed without error. FOR PERSISTENT OBJECTS: When a persistent object is completely unpinned, it becomes a candidate for aging. The memory of an object is freed when it is aged out. Aging is used to maximize the utilization of memory. An dirty object cannot be aged out unless it is flushed. FOR TRANSIENT OBJECTS: The pin count of the object is decremented. A transient can be freed only at the end of its allocation duration or when it is explicitly freed by calling OCIObjectFree(). FOR VALUE: This function will return an error for value. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectLock ---------------------------------*/ sword OCIObjectLock( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectLock - OCI lock a persistent object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function locks a persistent object at the server. Unlike OCIObjectLockNoWait() this function waits if another user currently holds a lock on the desired object. This function returns an error if: 1) the object is non-existent. This function will return an error for transient objects and values. The lock of an object is released at the end of a transaction. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------ OCIObjectLockNoWait ------------------------------*/ sword OCIObjectLockNoWait( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectLockNoWait - OCI lock a persistent object, do not wait for the lock, return error if lock not available PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function locks a persistent object at the server. Unlike OCIObjectLock() this function will not wait if another user holds the lock on the desired object. This function returns an error if: 1) the object is non-existent. 2) the object is currently locked by another user in which case this function returns with an error. This function will return an error for transient objects and values. The lock of an object is released at the end of a transaction. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectMarkUpdate ---------------------------*/ sword OCIObjectMarkUpdate( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectMarkUpdate - OCI marks an object as updated PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: FOR PERSISTENT OBJECTS: This function marks the specified persistent object as updated. The persistent objects will be written to the server when the object cache is flushed. The object is not locked or flushed by this function. It is an error to update a deleted object. After an object is marked updated and flushed, this function must be called again to mark the object as updated if it has been dirtied after it is being flushed. FOR TRANSIENT OBJECTS: This function marks the specified transient object as updated. The transient objects will NOT be written to the server. It is an error to update a deleted object. FOR VALUES: It is an no-op for values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*----------------------------- OCIObjectUnmark -----------------------------*/ sword OCIObjectUnmark( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectUnmark - OCI unmarks an object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS: This function unmarks the specified persistent object as dirty. Changes that are made to the object will not be written to the server. If the object is marked locked, it remains marked locked. The changes that have already made to the object will not be undone implicitly. FOR VALUES: It is an no-op for values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*----------------------------- OCIObjectUnmarkByRef ------------------------*/ sword OCIObjectUnmarkByRef( OCIEnv *env, OCIError *err, OCIRef *ref ); /* NAME: OCIObjectUnmarkByRef - OCI unmarks an object by Ref PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). ref (IN) - reference of the object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: FOR PERSISTENT OBJECTS AND TRANSIENT OBJECTS: This function unmarks the specified persistent object as dirty. Changes that are made to the object will not be written to the server. If the object is marked locked, it remains marked locked. The changes that have already made to the object will not be undone implicitly. FOR VALUES: It is an no-op for values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectFree ---------------------------------*/ sword OCIObjectFree( OCIEnv *env, OCIError *err, void *instance, ub2 flags ); /* NAME: OCIObjectFree - OCI free (and unpin) an standalone instance PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). instance (IN) - pointer to a standalone instance. flags (IN) - If OCI_OBJECT_FREE_FORCE is set, free the object even if it is pinned or dirty. If OCI_OBJECT_FREE_NONULL is set, the null structure will not be freed. REQUIRES: - a valid OCI environment handle must be given. - The instance to be freed must be standalone. - If the instance is a referenceable object, the object must be pinned. DESCRIPTION: This function deallocates all the memory allocated for an OTS instance, including the null structure. FOR PERSISTENT OBJECTS: This function will return an error if the client is attempting to free a dirty persistent object that has not been flushed. The client should either flush the persistent object or set the parameter 'flag' to OCI_OBJECT_FREE_FORCE. This function will call OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function will proceed to free the object. If it fails, then an error is returned unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE. Freeing a persistent object in memory will not change the persistent state of that object at the server. For example, the object will remain locked after the object is freed. FOR TRANSIENT OBJECTS: This function will call OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function will proceed to free the object. If it fails, then an error is returned unless the parameter 'flag' is set to OCI_OBJECT_FREE_FORCE. FOR VALUES: The memory of the object is freed immediately. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*----------------------- OCIObjectMarkDeleteByRef --------------------------*/ sword OCIObjectMarkDeleteByRef( OCIEnv *env, OCIError *err, OCIRef *object_ref); /* NAME: OCIObjectMarkDeleteByRef - OCI "delete" (and unpin) an object given a reference PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object_ref (IN) - ref of the object to be deleted REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function marks the object designated by 'object_ref' as deleted. FOR PERSISTENT OBJECTS: If the object is not loaded, then a temporary object is created and is marked deleted. Otherwise, the object is marked deleted. The object is deleted in the server when the object is flushed. FOR TRANSIENT OBJECTS: The object is marked deleted. The object is not freed until it is unpinned. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectMarkDelete ---------------------------*/ sword OCIObjectMarkDelete( OCIEnv *env, OCIError *err, void *instance ); /* NAME: OCIObjectMarkDelete - OCI "delete" an instance given a Pointer PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). instance (IN) - pointer to the instance REQUIRES: - a valid OCI environment handle must be given. - The instance must be standalone. - If the instance is a referenceable object, then it must be pinned. DESCRIPTION: FOR PERSISTENT OBJECTS: The object is marked deleted. The memory of the object is not freed. The object is deleted in the server when the object is flushed. FOR TRANSIENT OBJECTS: The object is marked deleted. The memory of the object is not freed. FOR VALUES: This function frees a value immediately. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCIObjectFlush -------------------------------*/ sword OCIObjectFlush( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectFlush - OCI flush a persistent object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function flushes a modified persistent object to the server. An exclusive lock is obtained implicitly for the object when flushed. When the object is written to the server, triggers may be fired. Objects can be modified by the triggers at the server. To keep the objects in the object cache being coherent with the database, the clients can free or refresh the objects in the cache. This function will return an error for transient objects and values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------ OCIObjectRefresh ---------------------------------*/ sword OCIObjectRefresh( OCIEnv *env, OCIError *err, void *object ); /* NAME: OCIObjectRefresh - OCI refresh a persistent object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to the persistent object REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. DESCRIPTION: This function refreshes an unmarked object with data retrieved from the latest snapshot in the server. An object should be refreshed when the objects in the cache are inconsistent with the objects at the server: 1) When an object is flushed to the server, triggers can be fired to modify more objects in the server. The same objects (modified by the triggers) in the object cache become obsolete. 2) When the user issues a SQL or executes a PL/SQL procedure to modify any object in the server, the same object in the cache becomes obsolete. The object that is refreshed will be 'replaced-in-place'. When an object is 'replaced-in-place', the top level memory of the object will be reused so that new data can be loaded into the same memory address. The top level memory of the null structre is also reused. Unlike the top level memory chunk, the secondary memory chunks may be resized and reallocated. The client should be careful when holding onto a pointer to the secondary memory chunk (e.g. assigning the address of a secondary memory to a local variable), since this pointer can become invalid after the object is refreshed. The object state will be modified as followed after being refreshed: - existent : set to appropriate value - pinned : unchanged - allocation duration : unchanged - pin duration : unchanged This function is an no-op for transient objects or values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCIObjectCopy --------------------------------*/ sword OCIObjectCopy( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, void *source, void *null_source, void *target, void *null_target, OCIType *tdo, OCIDuration duration, ub1 option ); /* NAME: OCIObjectCopy - OCI copy one instance to another PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) - OCI service context handle source (IN) - pointer to the source instance null_source (IN) - pointer to the null structure of the source target (IN) - pointer to the target instance null_target (IN) - pointer to the null structure of the target tdo (IN) - the TDO for both source and target duration (IN) - allocation duration of the target memory option (IN) - specify the copy option: OROOCOSFN - Set Reference to Null. All references in the source will not be copied to the target. The references in the target are set to null. REQUIRES: - a valid OCI environment handle must be given. - If source or target is referenceable, it must be pinned. - The target or the containing instance of the target must be already be instantiated (e.g. created by OCIObjectNew()). - The source and target instances must be of the same type. If the source and target are located in a different databases, then the same type must exist in both databases. DESCRIPTION: This function copies the contents of the 'source' instance to the 'target' instance. This function performs a deep-copy such that the data that is copied/duplicated include: a) all the top level attributes (see the exceptions below) b) all the secondary memory (of the source) that is reachable from the top level attributes. c) the null structure of the instance Memory is allocated with the specified allocation duration. Certain data items are not copied: a) If the option OCI_OBJECTCOPY_NOREF is specified, then all references in the source are not copied. Instead, the references in the target are set to null. b) If the attribute is a LOB, then it is set to null. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCIObjectGetTypeRef --------------------------*/ sword OCIObjectGetTypeRef( OCIEnv *env, OCIError *err, void *instance, OCIRef *type_ref ); /* NAME: OCIObjectGetTypeRef - get the type reference of a standalone object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). instance (IN) - pointer to an standalone instance type_ref (OUT) - reference to the type of the object. The reference must already be allocated. REQUIRES: - a valid OCI environment handle must be given. - The instance must be standalone. - If the object is referenceable, the specified object must be pinned. - The reference must already be allocated. DESCRIPTION: This function returns a reference to the TDO of a standalone instance. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectGetObjectRef -------------------------*/ sword OCIObjectGetObjectRef( OCIEnv *env, OCIError *err, void *object, OCIRef *object_ref ); /* NAME: OCIObjectGetObjectRef - OCI get the object reference of an referenceable object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). object (IN) - pointer to a persistent object object_ref (OUT) - reference of the given object. The reference must already be allocated. REQUIRES: - a valid OCI environment handle must be given. - The specified object must be pinned. - The reference must already be allocated. DESCRIPTION: This function returns a reference to the given object. It returns an error for values. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectMakeObjectRef -----------------------*/ sword OCIObjectMakeObjectRef( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, void * table, void **values, ub4 array_len, OCIRef *object_ref ); /* NAME: OCIObjectMakeObjectRef - OCI Create an object reference to a referenceable object. PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) - the service context table (IN) - A pointer to the table object (must be pinned) attrlist (IN) - A list of values (OCI type values) from which the ref is to be created. attrcnt (IN) - The length of the attrlist array. object_ref (OUT) - reference of the given object. The reference must already be allocated. REQUIRES: - a valid OCI environment handle must be given. - The specified table object must be pinned. - The reference must already be allocated. DESCRIPTION: This function creates a reference given the values that make up the reference and also a pointer to the table object. Based on the table's OID property, whether it is a pk based OID or a system generated OID, the function creates a sys-generated REF or a pk based REF. In case of system generated REFs pass in a OCIRaw which is 16 bytes long contatining the sys generated OID. In case of PK refs pass in the OCI equivalent for numbers, chars etc.. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectGetPrimaryKeyTypeRef --------------- */ sword OCIObjectGetPrimaryKeyTypeRef( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, void *table, OCIRef *type_ref ); /* NAME: OCIObjectGetPrimaryKeyTypeRef - OCI get the REF to the pk OID type PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) - the service context table (IN) - pointer to the table object type_ref (OUT) - reference of the pk type. The reference must already be allocated. REQUIRES: - a valid OCI environment handle must be given. - The specified table object must be pinned. - The reference must already be allocated. DESCRIPTION: This function returns a reference to the pk type. It returns an error for values. If the table is not a Pk oid table/view, then it returns error. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*-------------------------- OCIObjectGetInd --------------------------------*/ sword OCIObjectGetInd( OCIEnv *env, OCIError *err, void *instance, void **null_struct ); /* NAME: OCIObjectGetInd - OCI get the null structure of a standalone object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). instance (IN) - pointer to the instance null_struct (OUT) - null structure REQUIRES: - a valid OCI environment handle must be given. - The object must be standalone. - If the object is referenceable, the specified object must be pinned. DESCRIPTION: This function returns the null structure of an instance. This function will allocate the top level memory of the null structure if it is not already allocated. If an null structure cannot be allocated for the instance, then an error is returned. This function only works for ADT or row type instance. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------- OCIObjectExists --------------------------------*/ sword OCIObjectExists(OCIEnv *env, OCIError *err, void *ins, boolean *exist); /* NAME: OCIObjectExist - OCI checks if the object exists PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). ins (IN) - pointer to an instance exist (OUT) - return TRUE if the object exists REQUIRES: - a valid OCI environment handle must be given. - The object must be standalone. - if object is a referenceable, it must be pinned. DESCRIPTION: This function returns the existence of an instance. If the instance is a value, this function always returns TRUE. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------- OCIObjectGetProperty ---------------------------*/ sword OCIObjectGetProperty(OCIEnv *envh, OCIError *errh, const void *obj, OCIObjectPropId propertyId, void *property, ub4 *size ); /* NAME: OCIObjectGetProperty - OCIObject Get Property of given object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). obj (IN) - object whose property is returned propertyId (IN) - id which identifies the desired property property (OUT) - buffer into which the desired property is copied size (IN/OUT) - on input specifies the size of the property buffer passed by caller, on output will contain the size in bytes of the property returned. This parameter is required for string type properties only (e.g OCI_OBJECTPROP_SCHEMA, OCI_OBJECTPROP_TABLE). For non-string properties this parameter is ignored since the size is fixed. DESCRIPTION: This function returns the specified property of the object. The desired property is identified by 'propertyId'. The property value is copied into 'property' and for string typed properties the string size is returned via 'size'. Objects are classified as persistent, transient and value depending upon the lifetime and referenceability of the object. Some of the properties are applicable only to persistent objects and some others only apply to persistent and transient objects. An error is returned if the user tries to get a property which in not applicable to the given object. To avoid such an error, the user should first check whether the object is persistent or transient or value (OCI_OBJECTPROP_LIFETIME property) and then appropriately query for other properties. The different property ids and the corresponding type of 'property' argument is given below. OCI_OBJECTPROP_LIFETIME This identifies whether the given object is a persistent object (OCI_OBJECT_PERSISTENT) or a transient object (OCI_OBJECT_TRANSIENT) or a value instance (OCI_OBJECT_VALUE). 'property' argument must be a pointer to a variable of type OCIObjectLifetime. OCI_OBJECTPROP_SCHEMA This returns the schema name of the table in which the object exists. An error is returned if the given object points to a transient instance or a value. If the input buffer is not big enough to hold the schema name an error is returned, the error message will communicate the required size. Upon success, the size of the returned schema name in bytes is returned via 'size'. 'property' argument must be an array of type text and 'size' should be set to size of array in bytes by the caller. OCI_OBJECTPROP_TABLE This returns the table name in which the object exists. An error is returned if the given object points to a transient instance or a value. If the input buffer is not big enough to hold the table name an error is returned, the error message will communicate the required size. Upon success, the size of the returned table name in bytes is returned via 'size'. 'property' argument must be an array of type text and 'size' should be set to size of array in bytes by the caller. OCI_OBJECTPROP_PIN_DURATION This returns the pin duration of the object. An error is returned if the given object points to a value instance. Valid pin durations are: OCI_DURATION_SESSION and OCI_DURATION_TRANS. 'property' argument must be a pointer to a variable of type OCIDuration. OCI_OBJECTPROP_ALLOC_DURATION This returns the allocation duration of the object. Valid allocation durations are: OCI_DURATION_SESSION and OCI_DURATION_TRANS. 'property' argument must be a pointer to a variable of type OCIDuration. OCI_OBJECTPROP_LOCK This returns the lock status of the object. The possible lock status is enumerated by OCILockOpt. An error is returned if the given object points to a transient or value instance. 'property' argument must be a pointer to a variable of type OCILockOpt. Note, the lock status of an object can also be retrieved by calling OCIObjectIsLocked(). OCI_OBJECTPROP_MARKSTATUS This returns the status flag which indicates whether the object is a new object, updated object and/or deleted object. The following macros can be used to test the mark status flag: OCI_OBJECT_IS_UPDATED(flag) OCI_OBJECT_IS_DELETED(flag) OCI_OBJECT_IS_NEW(flag) OCI_OBJECT_IS_DIRTY(flag) An object is dirty if it is a new object or marked deleted or marked updated. An error is returned if the given object points to a transient or value instance. 'property' argument must be of type OCIObjectMarkStatus. OCI_OBJECTPROP_VIEW This identifies whether the specified object is a view object or not. If property value returned is TRUE, it indicates the object is a view otherwise it is not. 'property' argument must be of type boolean. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. Possible errors are TBD */ /*---------------------------- OCIObjectIsLocked --------------------------*/ sword OCIObjectIsLocked( OCIEnv *env, OCIError *err, void *ins, boolean *lock); /* NAME: OCIObjectIsLocked - OCI get the lock status of a standalone object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). ins (IN) - pointer to an instance lock (OUT) - return value for the lock status. REQUIRES: - a valid OCI environment handle must be given. - The instance must be standalone. - If the object is referenceable, the specified object must be pinned. DESCRIPTION: This function returns the lock status of an instance. If the instance is a value, this function always returns FALSE. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------- OCIObjectIsDirty ------------------------------*/ sword OCIObjectIsDirty( OCIEnv *env, OCIError *err, void *ins, boolean *dirty); /* NAME: OCIObjectIsDirty - OCI get the dirty status of a standalone object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). ins (IN) - pointer to an instance dirty (OUT) - return value for the dirty status. REQUIRES: - a valid OCI environment handle must be given. - The instance must be standalone. - if instance is an object, the instance must be pinned. DESCRIPTION: This function returns the dirty status of an instance. If the instance is a value, this function always returns FALSE. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCIObjectPinTable -----------------------------*/ sword OCIObjectPinTable( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, const oratext *schema_name, ub4 s_n_length, const oratext *object_name, ub4 o_n_length, const OCIRef *scope_obj_ref, OCIDuration pin_duration, void ** object ); /* NAME: OCIObjectPinTable - OCI get table object PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) - OCI service context handle schema_name (IN, optional) - schema name of the table s_n_length (IN, optional) - length of the schema name object_name (IN) - name of the table o_n_length (IN) - length of the table name scope_obj_ref (IN, optional) - reference of the scoping object pin_duration (IN) - pin duration. See description in OCIObjectPin(). object (OUT) - the pinned table object REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function pin a table object with the specified pin duration. The client can unpin the object by calling OCIObjectUnpin(). See OCIObjectPin() and OCIObjectUnpin() for more information about pinning and unpinning. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*------------------------- OCIObjectArrayPin -------------------------------*/ sword OCIObjectArrayPin(OCIEnv *env, OCIError *err, OCIRef **ref_array, ub4 array_size, OCIComplexObject **cor_array, ub4 cor_array_size, OCIPinOpt pin_option, OCIDuration pin_duration, OCILockOpt lock, void **obj_array, ub4 *pos ); /* NAME: OCIObjectArrayPin - ORIO array pin PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). ref_array (IN) - array of references to be pinned array_size (IN) - number of elements in the array of references pin_option (IN) - pin option. See OCIObjectPin(). pin_duration (IN) - pin duration. See OCIObjectPin(). lock_option (IN) - lock option. See OCIObjectPin(). obj_array (OUT) - If this argument is not NULL, the pinned objects will be returned in the array. The user must allocate this array with element type being 'void *'. The size of this array is identical to 'array'. pos (OUT) - If there is an error, this argument will contain the element that is causing the error. Note that this argument is set to 1 for the first element in the ref_array. REQUIRE: - a valid OCI environment handle must be given. - If 'obj_array' is not NULL, then it must already be allocated and the size of 'obj_array' is 'array_size'. DESCRIPTION: This function pin an array of references. All the pinned objects are retrieved from the database in one network roundtrip. If the user specifies an output array ('obj_array'), then the address of the pinned objects will be assigned to the elements in the array. See OCIObjectPin() for more information about pinning. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------------------------------------------------------*/ /* HEAP/CACHE OPERATIONS */ /*---------------------------------------------------------------------------*/ /*--------------------------- OCICacheFlush ---------------------------------*/ sword OCICacheFlush( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, void *context, OCIRef *(*get)(void *context, ub1 *last), OCIRef **ref ); /* NAME: OCICacheFlush - OCI flush persistent objects PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) [optional] - OCI service context. If null pointer is specified, then the dirty objects in all connections will be flushed. context (IN) [optional] - specifies an user context that is an argument to the client callback function 'get'. This parameter is set to NULL if there is no user context. get (IN) [optional] - an client-defined function which acts an iterator to retrieve a batch of dirty objects that need to be flushed. If the function is not NULL, this function will be called to get a reference of a dirty object. This is repeated until a null reference is returned by the client function or the parameter 'last' is set to TRUE. The parameter 'context' is passed to get() for each invocation of the client function. This parameter should be NULL if user callback is not given. If the object that is returned by the client function is not a dirtied persistent object, the object is ignored. All the objects that are returned from the client function must be from newed or pinned the same service context, otherwise, an error is signalled. Note that the returned objects are flushed in the order in which they are marked dirty. ref (OUT) [optional] - if there is an error in flushing the objects, (*ref) will point to the object that is causing the error. If 'ref' is NULL, then the object will not be returned. If '*ref' is NULL, then a reference will be allocated and set to point to the object. If '*ref' is not NULL, then the reference of the object is copied into the given space. If the error is not caused by any of the dirtied object, the given ref is initalized to be a NULL reference (OCIRefIsNull(*ref) is TRUE). REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function flushes the modified persistent objects from the environment heap to the server. The objects are flushed in the order that they are marked updated or deleted. See OCIObjectFlush() for more information about flushing. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*--------------------------- OCICacheRefresh -------------------------------*/ sword OCICacheRefresh(OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIRefreshOpt option, void *context, OCIRef *(*get)(void *context), OCIRef **ref); /* NAME: OCICacheRefresh - OCI ReFreSh persistent objects PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) [optional] - OCI service context. If null pointer is specified, then the persistent objects in all connections will be refreshed. option (IN) [optional] - if OCI_REFRESH_LOAD is specified, all objects that is loaded within the transaction are refreshed. If the option is OCI_REFERSH_LOAD and the parameter 'get' is not NULL, this function will ignore the parameter. context (IN) [optional] - specifies an user context that is an argument to the client callback function 'get'. This parameter is set to NULL if there is no user context. get (IN) [optional] - an client-defined function which acts an iterator to retrieve a batch of objects that need to be refreshed. If the function is not NULL, this function will be called to get a reference of an object. If the reference is not NULL, then the object will be refreshed. These steps are repeated until a null reference is returned by this function. The parameter 'context' is passed to get() for each invocation of the client function. This parameter should be NULL if user callback is not given. ref (OUT) [optional] - if there is an error in refreshing the objects, (*ref) will point to the object that is causing the error. If 'ref' is NULL, then the object will not be returned. If '*ref' is NULL, then a reference will be allocated and set to point to the object. If '*ref' is not NULL, then the reference of the object is copied into the given space. If the error is not caused by any of the object, the given ref is initalized to be a NULL reference (OCIRefIsNull(*ref) is TRUE). REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: This function refreshes all pinned persistent objects. All unpinned persistent objects are freed. See OCIObjectRefresh() for more information about refreshing. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCICacheUnpin --------------------------------*/ sword OCICacheUnpin( OCIEnv *env, OCIError *err, const OCISvcCtx *svc ); /* NAME: OCICacheUnpin - OCI UNPin objects PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) [optional] - OCI service context. If null pointer is specified, then the objects in all connections will be unpinned. REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: If a connection is specified, this function completely unpins the persistent objects in that connection. Otherwise, all persistent objects in the heap are completely unpinned. All transient objects in the heap are also completely unpinned. See OCIObjectUnpin() for more information about unpinning. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*----------------------------- OCICacheFree --------------------------------*/ sword OCICacheFree( OCIEnv *env, OCIError *err, const OCISvcCtx *svc ); /* NAME: OCICacheFree - OCI FREe instances PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) [optional] - OCI service context. If null pointer is specified, then the objects in all connections will be freed. REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: If a connection is specified, this function frees the persistent objects, transient objects and values allocated for that connection. Otherwise, all persistent objects, transient objects and values in the heap are freed. Objects are freed regardless of their pin count. See OCIObjectFree() for more information about freeing an instance. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /*---------------------------- OCICacheUnmark -------------------------------*/ sword OCICacheUnmark( OCIEnv *env, OCIError *err, const OCISvcCtx *svc ); /* NAME: OCICacheUnmark - OCI Unmark all dirty objects PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN) [optional] - OCI service context. If null pointer is specified, then the objects in all connections will be unmarked. REQUIRES: - a valid OCI environment handle must be given. DESCRIPTION: If a connection is specified, this function unmarks all dirty objects in that connection. Otherwise, all dirty objects in the cache are unmarked. See OCIObjectUnmark() for more information about unmarking an object. RETURNS: if environment handle or error handle is null, return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ sword OCIDurationBegin( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIDuration parent, OCIDuration *dur ); /* NAME: OCIDurationBegin - OCI DURATION BEGIN PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode This should be passed NULL, when cartridge services are to be used. err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN/OUT) - OCI service handle. parent (IN) - parent for the duration to be started. dur (OUT) - newly created user duration REQUIRES: - a valid OCI environment handle must be given for non-cartridge services. - For cartridge services, NULL should be given for environment handle - A valid service handle must be given in all cases. DESCRIPTION: This function starts a new user duration. A user can have multiple active user durations simultaneously. The user durations do not have to be nested. The object subsystem predefines 3 durations : 1) session - memory allocated with session duration comes from the UGA heap (OCI_DURATION_SESSION). A session duration terminates at the end of the user session. 2) transaction - memory allocated with transaction duration comes from the UGA heap (OCI_DURATION_TRANS). A trans- action duration terminates at the end of the user transaction. 3) call - memory allocated with call duration comes from PGA heap (OCI_DURATION_CALL). A call duration terminates at the end of the user call. Each user duration has a parent duration. A parent duration can be a predefined duration or another user duration. The relationship between a user duration and its parent duration (child duration) are: 1) An user duration is nested within the parent duration. When its parent duration terminates, the user duration will also terminate. 2) The memory allocated with an user duration comes from the heap of its parent duration. For example, if the parent duration of an user duration is call, then the memory allocated with the user duration will also come from the PGA heap. This function can be used as both part of cartridge services as well as without cartridge services. The difference in the function in the case of cartridge and non-cartridge services is: In case of cartridge services, as descibed above a new user duration is created as a child of the "parent" duration. But when used for non-cartridge purposes, when a pre-defined duration is passed in as parent, it is mapped to the cache duration for that connection (which is created if not already present) and the new user duration will be child of the cache duration. RETURNS: if environment handle and service handle is null or if error handle is null return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ sword OCIDurationEnd( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIDuration duration ); /* NAME: OCIDurationEnd - OCI DURATION END PARAMETERS: env (IN/OUT) - OCI environment handle initialized in object mode This should be passed NULL, when cartridge services are to be used. err (IN/OUT) - error handle. If there is an error, it is recorded in 'err' and this function returns OCI_ERROR. The error recorded in 'err' can be retrieved by calling OCIErrorGet(). svc (IN/OUT) - OCI service handle. dur (OUT) - a previously created user duration using OCIDurationBegin() REQUIRES: - a valid OCI environment handle must be given for non-cartridge services. - For cartridge services, NULL should be given for environment handle - A valid service handle must be given in all cases. DESCRIPTION: This function terminates a user duration. All memory allocated for this duration is freed. This function can be used as both part of cartridge services as well as without cartridge services. In both cased, the heap duration is freed and all the allocated memory for that duration is freed. The difference in the function in the case of cartridge and non-cartridge services is: In case of non-cartridge services, if the duration is pre- defined, the associated cache duration (see OCIDurationBegin()) is also terminated and the following is done. 1) The child durations are terminated. 2) All objects pinned for this duration are unpinned. 3) All instances allocated for this duration are freed. In case of cartridge services, only the heap duration is freed. All the context entries allocated for that duration are freed from the context hash table.. RETURNS: if environment handle and service handle is null or if error handle is null return OCI_INVALID_HANDLE. if operation suceeds, return OCI_SUCCESS. if operation fails, return OCI_ERROR. */ /****************************************************************************** ** DO NOT USE THE FUNCTIONS BELOW! ** ** UNSUPPORTED INTERFACE ** ** WILL BE REMOVED/CHANGED IN A FUTURE RELEASE ** ******************************************************************************/ sword OCIDurationGetParent( OCIEnv *env, OCIError *err, OCIDuration duration, OCIDuration *parent ); sword OCIObjectAlwaysLatest( OCIEnv *env, OCIError *err, void *object ); sword OCIObjectNotAlwaysLatest( OCIEnv *env, OCIError *err, void *object ); sword OCIObjectFlushRefresh( OCIEnv *env, OCIError *err, void *object); sword OCIObjectIsLoaded( OCIEnv *env, OCIError *err, void *ins, boolean *load); sword OCIObjectIsDirtied( OCIEnv *env, OCIError *err, void *ins, boolean *dirty); sword OCICacheGetObjects( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, OCIObjectProperty property, void *client_context, void (*client_callback)( void *client_context, void *object )); sword OCICacheRegister( OCIEnv *env, OCIError *err, OCIObjectEvent event, void *client_context, void (*client_callback)( void *client_context, OCIObjectEvent event, void *object)); sword OCICacheFlushRefresh( OCIEnv *env, OCIError *err, const OCISvcCtx *svc, void *context, OCIRef *(*get)(void *context, ub1 *last), OCIRef **ref ); sword OCIObjectSetData(OCIEnv *env, OCIError *err, void *obj_hdr, void *data); sword OCIObjectGetNewOID(OCIEnv *env, OCIError *err, OCISvcCtx *svc, ub1 *oid); #endif /* ORI_ORACLE */