Release 8.0
A54656_01
 Library |
 Product |
 Contents |
 Index |
| Programmer's Guide to the Oracle Call Interface Release 8.0 A54656_01 |
|
This chapter describes the OCI functions which are used to navigate through objects retrieved from an Oracle8 Server. The chapter contains the following sections:
In an object navigational paradigm, data is represented as a graph of objects connected by references. Objects in the graph are reached by following the references. The OCI provides a navigational interface to objects in the Oracle8 Server. Those calls are described in this chapter.
The OCI object environment is initialized when the application calls OCIInitialize() in OCI_OBJECT mode.
See Also: For more information about using the calls in this chapter, refer to Chapter 8, "Object-Relational Programming with the OCI", and Chapter 11, "Object Cache and Object Navigation".
An object instance is an occurrence of a type defined in an Oracle database. This section describes how an object instance can be represented in OCI. In OCI, an object instance can be classified based on the type, the lifetime and referenceability (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 Oracle type. Unlike objects, values of object types are identified by memory pointers, rather than by references.
A value can be standalone or embedded. 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 physically 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.
The following figure shows how instances can be classified according to their type and lifetime:
The distinction between various instances is further illustrated by the following table:
In the remainder of this chapter, the following terms will be used:
1) The term object can be generally used to refer 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 refers to a embedded value of object type.
For a further discussion of the terms used to refer to different types of objects, please see "Persistent Objects, Transient Objects, and Values" on page 8-6.
An object is dirty if it has been created (newed), or marked updated or deleted.
The OCI navigational functions typically return one of the following values:
Function-specific return information follows the description of each function in this chapter. Information about specific error codes returned by each function is presented in the following section.
See Also: For more information about return codes and error handling, see the section "Error Handling" on page 2-25.
Table 14-3 lists the external Oracle error codes which can be returned by each of the OCI navigational functions. The list following the table identifies what each error represents.
The ORA errors in Table 14-3 have the following meanings.
For a table showing the number of server roundtrips required for individual OCI cache and object functions, refer to Appendix E, "OCI Function Server Roundtrips".
This section is intended to help you figure out which OCI navigational call you need to use in a given situation. Table 14-4 includes all of the navigational functions, grouped by categories of functionality. The list includes the name of each call, a brief description of its purpose, and the page number on which the full description can be found.
This chapter describes the functions which belong to the object navigational component of the OCI. The entries for each function contain the following information:
A brief description of what the function does.
A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.
Detailed information about the function (if available). This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.
A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described in Table 14-5
A description of what value is returned by the function if the function returns something other than the standard return codes listed in Table 14-2.
A list of related calls which may provide additional useful information.
Flushes modified persistent objects to the server
sword OCICacheFlush ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, dvoid *context, OCIRef *(*get) ( dvoid *context, ub1 *last ), OCIRef **ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained 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 newed or pinned using the same service context, otherwise an error is signalled. Note that the cache flushes the returned objects in the order in which they were marked dirty.
If this parameter is passed as NULL (e.g., no client-defined function is provided), then all dirty persistent objects for the given service context are flushed in the order in which they were dirtied.
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 initialized to be a NULL reference (OCIRefIsNull(*ref) is TRUE).
The REF is allocated for session duration (OCI_DURATION_SESSION). The application can free the allocated REF using the OCIObjectFree() function.
This function flushes the modified persistent objects from the object cache to the server. The objects are flushed in the order that they are newed or marked updated or deleted.
This function incurs at most one network round-trip.
See OCIObjectFlush() for more information about flushing.
Frees all objects and values in the cache for the specified connection
sword OCICacheFree ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN) - an OCI service context.
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 object cache are freed. Objects are freed regardless of their pin count.
See OCIObjectFree() for more information about freeing an instance.
Refreshes all pinned persistent objects in the cache.
sword OCICacheRefresh ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCIRefreshOpt option, dvoid *context, OCIRef *(*get)(dvoid *context), OCIRef **ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained 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_LOADED is specified, all objects that are loaded within the transaction are refreshed. If the option is OCI_REFRESH_LOADED 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] - a 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 initialized to be a NULL reference (OCIRefIsNull(*ref) is TRUE).
This function refreshes all pinned persistent objects.
All unpinned persistent objects are freed from the object cache.
For more information about refreshing, see the description of OCIObjectRefresh() on page 14-42, and the section "Refreshing an Object Copy" on page 11-11.
Warning: When objects are refreshed, the secondary-level memory of those objects could potentially move to a different place in memory. As a result, any pointers to attributes which were saved prior to this call may be invalidated. Examples of attributes using secondary-level memory include OCIString *, OCIColl *, and OCIRaw *.
Unmarks all dirty objects in the object cache.
sword OCICacheUnmark ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN) [optional] - OCI service context. If null pointer is specified, then the objects in all connections will be unmarked.
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.
Unpins persistent objects
sword OCICacheUnpin ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN) - an OCI service context handle. The objects on the specified connection are unpinned.
This function completely unpins all of the persistent objects for the given connection.
The pin count for the objects is reset to zero.
For more information about pinning and unpinning, see "Pinning an Object" on page 8-12, and "Pin Count and Unpinning" on page 8-25.
Pins an array of references
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, dvoid **obj_array, ub4 *pos );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) -The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained 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 (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 dvoid *. The size of this array is identical to array_size.
pos (OUT) - If this argument is not NULL and 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.
This function pins 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.
Copies a source instance to a destination
sword OCIObjectCopy ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, dvoid *source, dvoid *null_source, dvoid *target, dvoid *null_target, OCIType *tdo, OCIDuration duration, ub1 option );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN) - an OCI service context handle, specifying the service context on which the copy operation is taking place
source (IN) - a pointer to the source instance; if it is an object, it must be pinned. See OCIObjectPin().
null_source (IN) - pointer to the NULL structure of the source object.
target (IN) - a pointer to the target instance; if it is an object is must be pinned. See OCIObjectPin().
null_target (IN) - a pointer to the NULL structure of the target object.
tdo (IN) - the TDO for both the source and the target. Can be retrieved with OCIDescribeAny().
duration (IN) - allocation duration of the target memory.
option (IN) - this parameter is currently unused. Pass as zero or OCI_DEFAULT.
This function copies the contents of the source instance to the target instance. This function performs a deep-copy such that all of the following is copied:
Memory is allocated with the duration specified in the duration parameter.
Certain data items are not copied:
The target or the containing instance of the target must be already have been created. This may be done with 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.
Returns the existence meta-attribute of a standalone instance
sword OCIObjectExists ( OCIEnv *env, OCIError *err, dvoid *ins, boolean *exist );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
ins (IN) - pointer to an instance. If it is an object, it must be pinned.
exist (OUT) - return value for the existence status.
This function returns the existence of an instance. If the instance is a value, this function always returns TRUE.
The instance must be a standalone persistent or transient object.
For more information about object meta-attributes, see "Object Meta-Attributes" on page 8-17.
Flushes a modified persistent object to the server
sword OCIObjectFlush ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to the persistent object. The object must be pinned before this call can be made.
This function flushes a modified persistent object to the server. An exclusive lock is obtained implicitly for the object when it is flushed. When the object is written to the server, triggers may be fired. This function returns an error for transient objects and values, and for unmodified persistent objects.
Objects can be modified by the triggers at the server. To keep the objects in the object cache consistent with the database, an OCI application can free or refresh the objects in the object cache.
If the object to flush contains an internal LOB attribute, and the LOB attribute was modified due to an OCIObjectCopy() or OCILobAssign(), or by assigning another LOB locator to it, the flush makes a copy of the LOB value that existed in the source LOB at the time of the assignment or copy of the internal LOB locator or object.
OCIObjectPin(), OCICacheFlush()
Frees and unpins an object instance
sword OCIObjectFree ( OCIEnv *env, OCIError *err, dvoid *instance, ub2 flags );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - pointer to a standalone instance. If it is an object, it must be pinned.
flags (IN) - If OCI_OBJECTFREE_FORCE is set, free the object even if it is pinned or dirty. If OCI_OBJECTFREE_NONULL is set, the null structure is not freed.
This function deallocates all the memory allocated for an object instance, including the null structure. The following rules apply for different instance types:
This function returns 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, unmark it, or set the parameter flags to OCI_OBJECTFREE_FORCE.
This function calls OCIObjectUnpin() once to check if the object can be completely unpin. If it succeeds, the rest of the function proceeds to free the object. If it fails, then an error is returned unless the parameter flag is set to OCI_OBJECTFREE_FORCE.
Freeing a persistent object in memory does not change the persistent state of that object at the server. For example, the object remains locked after the object is freed.
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_OBJECTFREE_FORCE.
The memory of the object is freed immediately.
Retrieves an object attribute
sword OCIObjectGetAttr ( OCIEnv *env, OCIError *err, dvoid *instance, dvoid *null_struct, struct OCIType *tdo, CONST text **names, CONST ub4 *lengths, CONST ub4 name_count, CONST ub4 *indexes, CONST ub4 index_count, OCIInd *attr_null_status, dvoid **attr_null_struct, dvoid **attr_value, struct OCIType **attr_tdo );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - pointer to an object.
null_struct (IN) - the null structure of the object or array.
tdo (IN) - pointer to the TDO.
names (IN) - array of attribute names. This is used to specify the names of the attributes in the path expression.
lengths (IN) - array of lengths of attribute names.
name_count (IN) - number of element in the array names.
indexes (IN) [OPTIONAL] - array of collection indexes. This is used to specify the position of a collection in the path expression.
index_count (IN) [OPTIONAL] - number of element in the array indexes.
attr_null_status (OUT) - the null status of the attribute if the type of attribute is primitive.
attr_null_struct (OUT) - the null structure of an object or collection attribute.
attr_value (OUT) - pointer to the attribute value.
attr_tdo (OUT) - pointer to the TDO of the attribute.
This function gets a value from an object or from an array. If the parameter instance points to an object, then the path expression specifies the location of the attribute in the object. It is assumed that the object is pinned and that the value returned is valid until the object is unpinned.
Gets the NULL structure of a standalone instance
sword OCIObjectGetInd ( OCIEnv *env, OCIError *err, dvoid *instance, dvoid **null_struct );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - a pointer to the instance whose NULL structure is being retrieved. The instance must be standalone. If instance is an object, it must already be pinned.
null_struct (OUT) - the NULL structure for the instance.
This function returns the NULL structure of an instance.
Returns a reference to a given persistent object
sword OCIObjectGetObjectRef ( OCIEnv *env, OCIError *err, dvoid *object, OCIRef *object_ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - pointer to a persistent object. It must already be pinned.
object_ref (OUT) - a reference to the object specified in object. The reference must already be allocated. This can be accomplished with OCIObjectNew().
This function returns a reference to the given persistent object, given a pointer to the object.
Passing a value to this function causes an error.
See Also: For more information about object meta-attributes, see "Object Meta-Attributes" on page 8-17.
OCIObjectNew(), OCIObjectPin()
Returns a reference to the TDO of a standalone instance
sword OCIObjectGetTypeRef ( OCIEnv *env, OCIError *err, dvoid *instance, OCIRef *type_ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - a pointer to the standalone instance. It must be standalone, and if it is an object, it must already be pinned.
type_ref (OUT) - a reference to the type of the object. The reference must already be allocate. This can be accomplished with OCIObjectNew().
This function returns a reference to the type descriptor object (TDO) of a standalone instance.
OCIObjectNew(), OCIObjectPin()
Check to see if an object is marked as dirty
sword OCIObjectIsDirty ( OCIEnv *env, OCIError *err, dvoid *ins, boolean *dirty );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
ins (IN) - pointer to an instance.
dirty (OUT) - return value for the dirty status.
The instance passed to this function must be standalone. If the instance is an object, the instance must be pinned.
This function returns the dirty status of an instance. If the instance is a value, this function always returns FALSE for the dirty status.
Get lock status of an object.
sword OCIObjectIsLocked ( OCIEnv *env, OCIError *err, dvoid *ins, boolean *lock );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
ins (IN) - pointer to an instance. The instance must be standalone, and if it is an object it must be pinned.
lock (OUT) - return value for the lock status.
This function returns the lock status of an instance. If the instance is a value, this function always returns FALSE.
Locks a persistent object at the server
sword OCIObjectLock ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) -The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to the persistent object being locked. It must already be pinned.
This function locks a persistent object at the server. This function will return an error for transient objects and values.
For more information about object locking, see "Locking Objects For Update" on page 11-13.
This function returns an error if the object does not exist.
OCIObjectPin(), OCIObjectIsLocked()
Marks a standalone instance as deleted, given a pointer to the instance
sword OCIObjectMarkDelete ( OCIEnv *env, OCIError *err, dvoid *instance );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - pointer to the instance. It must be standalone, and if it is an object it must be pinned.
This function accepts a pointer to a standalone instance and marks the object as deleted. The object is freed according to the following rules:
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.
The object is marked deleted. The memory of the object is not freed.
This function frees a value immediately.
Marks an object as deleted, given a reference to the object
sword OCIObjectMarkDeleteByRef ( OCIEnv *env, OCIError *err, OCIRef *object_ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object_ref (IN) - reference to the object to be deleted.
This function accepts a reference to an object, and marks the object designated by object_ref as deleted. The object is marked and freed according to the following rules:
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.
The object is marked deleted. The object is not freed until it is unpinned.
Marks a persistent object as updated, or `dirty'
sword OCIObjectMarkUpdate ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to the persistent object, which must already be pinned.
This function marks a persistent object as updated, or `dirty.' The following special rules apply to different types of objects. The dirty status of an object may be checked by calling OCIObjectIsDirty().
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.
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.
This function is an no-op for values.
For more information about the use of this function, see "Marking Objects and Flushing Changes" on page 8-14.
Creates a standalone instance
sword OCIObjectNew ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, OCITypeCode typecode, OCIType *tdo, dvoid *table, OCIDuration duration, boolean value, dvoid **instance );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN, optional) - OCI service handle. It must be given if the program wants to associate the duration of an instance with an OCI service (e.g. free a string when the transaction is committed). This parameter is ignored if the TDO is given.
typecode (IN) - the typecode of the type of the instance. See "Typecodes" on page 3-24 for more information.
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 specifies 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
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:
| Value of table Parameter | ||
|---|---|---|
|
TYPE |
Not NULL |
NULL |
|
object type (value=TRUE) |
value |
value |
|
object type (value=FALSE) |
persistent object |
transient object |
|
built-in type |
value |
value |
|
collection type |
value |
value |
For more information about typecodes, see "Typecodes" on page 3-24.
This function allocates the top-level memory chunk of an instance. The attributes in the top-level memory are initialized (e.g. an attribute of varchar2 is initialized to a string of 0 length).
If the instance is an object, the object is marked existed but is atomically null.
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. Creating a persistent object does not cause any entries to be made into a database table until the object is flushed to the server.
The object is pinned. The allocation duration and the pin duration are specified by the given parameter duration.
The allocation duration is specified by the given parameter duration.
If the object contains an internal LOB attribute, the LOB is set to empty. The object must be marked as dirty and flushed (in order to insert the object into the table) and repinned before the user can start writing data into the LOB. When pinning the object after creating it, you must use the OCI_PIN_LATEST pin option in order to retrieve the newly updated LOB locator from the server.
If the object contains an external LOB attribute (FILE), the FILE locator is allocated but not initialized. The user must call OCILobFileSetName() to initialize the FILE attribute. Once the filename is set, the user can start reading from the FILE.
Note: Oracle8 supports only binary FILEs (BFILEs).
OCIObjectPinTable(), OCIObjectFree()
Pin a referenceable object
sword OCIObjectPin ( OCIEnv *env, OCIError *err, OCIRef *object_ref, OCIComplexObject *corhdl, OCIPinOpt pin_option, OCIDuration pin_duration, OCILockOpt lock_option, dvoid **object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained 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 accessed 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 in the case of OCI_DURATION_NULL.
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.
This function pins a referenceable object instance given the object reference. The process of pinning serves two purposes:
Also see OCIObjectUnpin() for more information about unpinning.
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 pin_option is OCI_PIN_ANY (pin any), if the object is already in the object cache, 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 pin_option is OCI_PIN_LATEST (pin latest), if the object is not locked, 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 pin_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.
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.
OCIObjectUnpin(), OCIObjectPinCountReset()
Completely unpins an object, setting its pin count to zero
sword OCIObjectPinCountReset ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to an object, which must already be pinned.
This function completely unpins an object, setting its pin count to zero. When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error.
The following rules apply for specific object types:
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.
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().
This function will return an error for value.
For more information about the use of this function, see "Pin Count and Unpinning" on page 8-25.
OCIObjectPin(), OCIObjectUnpin()
Pins a table object for a specified duration
sword OCIObjectPinTable ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, CONST text *schema_name, ub4 s_n_length, CONST text *object_name, ub4 o_n_length, dvoid *not_used, OCIDuration pin_duration, dvoid **object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
svc (IN) - the OCI service context handle.
schema_name (IN, optional) - the schema name of the table.
s_n_length (IN, optional) - the length of the schema name indicated in schema_name.
object_name (IN) - the name of the table.
o_n_length (IN) - the length of the table name specified in object_name.
not_used (IN/OUT) - this parameter is not currently used. Pass as NULL.
pin_duration (IN) - the pin duration. See description in OCIObjectPin().
object (OUT) - the pinned table object.
This function pins a table object with the specified pin duration.
The client can unpin the object by calling OCIObjectUnpin().
The table object pinned by this call can be passed as a parameter to OCIObjectNew() to create a standalone persistent object.
OCIObjectPin(), OCIObjectUnpin()
Refreshes a persistent object from the most current database snapshot
sword OCIObjectRefresh ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to the persistent object, which must already be pinned.
This function refreshes an object with data retrieved from the latest snapshot in the server. An object should be refreshed when the objects in the object cache are inconsistent with the objects at the server.
Note: 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 out-of-date, and must be refreshed before they can be locked or flushed.
This occurs when the user issues a SQL statement or PL/SQL procedure to modify any object in the server.
Warning: Modifications made to objects (dirty objects) since the last flush are lost if object are refreshed by this function.
The various meta-attribute flags and durations of an object are modified as followed after being refreshed:
| Object Attribute | Status After Refresh |
|---|---|
|
existent |
set to appropriate value |
|
pinned |
unchanged |
|
allocation duration |
unchanged |
|
pin duration |
unchanged |
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 structure is also reused. Unlike the top-level memory chunk, the secondary memory chunks will be freed and reallocated. The client should be careful when holding on to 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.
This function does nothing for transient objects or values.
Set an object attribute.
sword OCIObjectSetAttr ( OCIEnv *env, OCIError *err, dvoid *instance, dvoid *null_struct, struct OCIType *tdo, CONST text **names, CONST ub4 *lengths, CONST ub4 name_count, CONST ub4 *indexes, CONST ub4 index_count, CONST OCIInd null_status, CONST dvoid *attr_null_struct, CONST dvoid *attr_value );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
instance (IN) - pointer to an object instance.
null_struct (IN) - the null structure of the object instance or array.
tdo (IN) - pointer to the TDO.
names (IN) - array of attribute names. This is used to specify the names of the attributes in the path expression.
lengths (IN) - array of lengths of attribute names.
name_count (IN) - number of element in the array names.
indexes (IN) [OPTIONAL] - array of collection indexes. This is used to specify the position of a collection in the path expression.
index_count (IN) [OPTIONAL] - number of element in the array indexes.
attr_null_status (IN) - the null status of the attribute if the type of attribute is primitive.
attr_null_struct (IN) - the null structure of an object or collection attribute.
attr_value (IN) - pointer to the attribute value.
This function sets the attribute of the given object with the given value. The position of the attribute is specified as a path expression which is an array of names and an array of indexes.
For path expression stanford.cs.stu[5].addr, the arrays will look like
names = {"stanford", "cs", "stu", "addr"}
lengths = {8, 2, 3, 4}
indexes = {5}
Unmarks an object as dirty.
sword OCIObjectUnmark ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - pointer to the persistent object. It must be pinned.
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.
This function is an no-op for values.
Unmarks an object as dirty, given a REF to the object.
sword OCIObjectUnmarkByRef ( OCIEnv *env, OCIError *err, OCIRef *ref );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
ref (IN) - reference of the object. It must be pinned.
This function unmarks an object as dirty. This function is identical to OCIObjectUnmark(), except that it takes a REF to the object as an argument.
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.
This function is a no-op for values.
Unpins an object
sword OCIObjectUnpin ( OCIEnv *env, OCIError *err, dvoid *object );
env (IN/OUT) - The OCI environment handle initialized in object mode. See the description of OCIEnvInit() in Chapter 13 for more information.
err (IN/OUT) - The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Diagnostic information can be obtained by calling OCIErrorGet().
object (IN) - a pointer to an object, which must already be pinned.
This function unpins an object. An object is completely unpinned when
When an object is completely unpinned, it can be freed implicitly by the OCI at any time without error.
The following rules apply for unpinning different types of objects:
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 implicitly by the OCI at any time without error.
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.
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().
This function will return an error for value.
OCIObjectPin(), OCIObjectPinCountReset()
