Oracle Call Interface Programmer's Guide
Release 8.1.5

A67846-01

Library

Product

Contents

Index

Prev Next

16
OCI Navigational and Type Functions

This chapter describes the OCI navigational functions which are used to navigate through objects retrieved from an Oracle database server. It also contains the descriptions of the functions which are used to obtain type descriptor objects (TDOs). The chapter contains the following sections:

Introduction

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 Oracle 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 10, "OCI Object-Relational Programming", and Chapter 13, "Object Cache and Object Navigation".

Object Types and Lifetimes

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. See Figure 16-1. In OCI, an object instance can be classified based on the type, the lifetime and referenceability:

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. 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, such as VARCHAR or raw, or an out-of-line element in a collection, such as VARCHAR, raw, or object.

An embedded value is physically included in a containing instance. An embedded value can be an in-line attribute in an object. such as number or nested object, or an in-line element in a collection.

All values are considered to be transient by OCI, which means that 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.

Figure 16-1 shows how instances can be classified according to their type and lifetime:

Figure 16-1 Classification of Instances by Type and Lifetime


The distinction between various instances is further illustrated by the following table:

  Persistent Object   Transient Object   Value  

Type  

object type  

object type  

object type, built-in, collection  

Maximum Lifetime  

until object is deleted  

session  

session  

Referenceable  

yes  

yes  

no  

Embeddable  

no  

no  

yes  

Terminology

In the remainder of this chapter, the following terms will be used:

For a further discussion of the terms used to refer to different types of objects, please see "Persistent Objects, Transient Objects, and Values".

The Function Syntax

The entries for each function contain the following information:

Purpose

A brief description of what the function does.

Syntax

A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.

Comments

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.

Parameters

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 below:

Mode   Description  

IN  

A parameter that passes data to Oracle  

OUT  

A parameter that receives data from Oracle on this or a subsequent call  

IN/OUT  

A parameter that passes data on the call and receives data on the return from this or a subsequent call.  

Returns

A description of what value is returned by the function if the function returns something other than the standard return codes listed above.

Related Functions

A list of related calls which may provide additional useful information.

Navigational Function Return Values

The OCI navigational functions typically return one of the following values:

Return Value   Meaning  

OCI_SUCCESS  

The operation succeeded  

OCI_ERROR  

The operation failed. The specific error can be retrieved by calling OCIErrorGet() on the error handle passed to the function.  

OCI_INVALID_HANDLE  

The environment or error handle passed to the function is NULL.  

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".

Server Roundtrips for Cache and Object Functions

For a table showing the number of server roundtrips required for individual OCI cache and object functions, refer to Appendix C, "OCI Function Server Roundtrips".

Navigational Function Error Codes

Table 16-1 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.

Table 16-1 OCI Navigational Functions Error Codes
Function  Possible ORA Errors 

OCICacheFlush()  

24350, 21560, 21705  

OCICacheFree()  

24350, 21560, 21705  

OCICacheRefresh()  

24350, 21560, 21705  

OCICacheUnmark()  

24350, 21560, 21705  

OCICacheUnpin()  

24350, 21560, 21705  

OCIObjectArrayPin()  

24350, 21560  

OCIObjectCopy()  

24350, 21560, 21705, 21710  

OCIObjectExists()  

24350, 21560, 21710  

OCIObjectFlush()  

24350, 21560, 21701, 21703, 21708, 21710  

OCIObjectFree()  

24350, 21560, 21603, 21710  

OCIObjectGetAttr()  

21560, 21600, 22305  

OCIObjectGetInd()  

24350, 21560, 21710  

OCIObjectGetTypeRef()  

24350, 21560, 21710  

OCIObjectIsDirty()  

24350, 21560, 21710  

OCIObjectIsLocked()  

24350, 21560, 21710  

OCIObjectLock()  

24350, 21560, 21701, 21708, 21710  

OCIObjectLockNoWait()  

24350, 21560, 21701, 21708, 21710  

OCIObjectMarkDelete()  

24350, 21560, 21700, 21701, 21702, 21710  

OCIObjectMarkDeleteByRef()  

24350, 21560  

OCIObjectMarkUpdate()  

24350, 21560, 21700, 21701, 21710  

OCIObjectNew()  

24350, 21560, 21705, 21710  

OCIObjectPin()  

24350, 21560, 21700, 21702  

OCIObjectPinCountReset()  

24350, 21560, 21710  

OCIObjectPinTable()  

24350, 21560, 21705  

OCIObjectRefresh()  

24350, 21560, 21709, 21710  

OCIObjectSetAttr()  

21560, 21600, 22305, 22279, 21601  

OCIObjectUnmark()  

24350, 21560, 21710  

OCIObjectUnmarkByRef()  

24350, 21560  

OCIObjectUnpin()  

24350, 21560, 21710  

OCIOjectGetObjectRef()  

24350, 21560, 21710  

The ORA errors in Table 16-1 have the following meanings.

OCI Flush or Refresh Functions

This section describes the OCI flush or refresh functions.

Table 16-2 OCI Flush or Refresh Functions Quick Reference
Function/Page  Purpose 

OCICacheFlush()  

Flush modified persistent objects in cache to server  

OCICacheRefresh()  

Refresh pinned persistent objects  

OCIObjectFlush()  

Flush a modified persistent object to the server  

OCIObjectRefresh()  

Refresh a persistent object  


OCICacheFlush()

Purpose

Flushes modified persistent objects to the server

Syntax

sword OCICacheFlush ( OCIEnv              *env, 
                      OCIError            *err, 
                      CONST OCISvcCtx     *svc, 
                      dvoid               *context,
                      OCIRef              *(*get)
                                          ( dvoid   *context,
                                            ub1     *last ), 
                      OCIRef              **ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

OCI service context.

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 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.

Comments

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. See OCIObjectFlush() for more information about flushing.

This function incurs at most one network round-trip.

Related Functions

OCIObjectFlush()


OCICacheRefresh()

Purpose

Refreshes all pinned persistent objects in the cache.

Syntax

sword OCICacheRefresh ( OCIEnv            *env, 
                       OCIError           *err, 
                       CONST OCISvcCtx    *svc,
                       OCIRefreshOpt      option, 
                       dvoid              *context,
                       OCIRef             *(*get)(dvoid *context), 
                       OCIRef             **ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

OCI service context.

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).

Comments

This function refreshes all pinned persistent objects and all unpinned persistent objects are freed from the object cache.

For more information about refreshing, see the description of OCIObjectRefresh(), and the section "Refreshing an Object Copy".

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 *.

Related Functions

OCIObjectRefresh()


OCIObjectFlush()

Purpose

Flushes a modified persistent object to the server.

Syntax

sword OCIObjectFlush ( OCIEnv        *env,
                       OCIError      *err,
                       dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object. The object must be pinned before this call.

Comments

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 triggers at the server. To keep objects in the cache consistent with the database, an application can free or refresh objects in the cache.

If the object to flush contains an internal LOB attribute and the LOB attribute was modified due to an OCIObjectCopy(), OCILobAssign(), or OCILobLocatorAssign() or by assigning another LOB locator to it, then 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. For more information on LOB functions, see "LOB Functions".

Related Functions

OCIObjectPin(), OCICacheFlush()


OCIObjectRefresh()

Purpose

Refreshes a persistent object from the most current database snapshot.

Syntax

sword OCIObjectRefresh ( OCIEnv        *env, 
                         OCIError      *err, 
                         dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object, which must already be pinned.

Comments

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 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.

You should be careful when writing functionality that holds on to a pointer to the secondary memory chunk, such as assigning the address of a secondary memory to a local variable, because this pointer can become invalid after the object is refreshed.

This function does nothing for transient objects or values.

Related Functions

OCICacheRefresh()

OCI Mark or Unmark Object and Cache Functions

This section describe the OCI mark or unmark Object and Cache functions.

Table 16-3 OCI Navigational Functions Quick Reference
Function/Page  Purpose 

OCICacheUnmark()  

Unmarks objects in the cache  

OCIObjectMarkDelete()  

Mark an object deleted / delete a value instance  

OCIObjectMarkDeleteByRef()  

Mark an object deleted given a ref  

OCIObjectMarkUpdate()  

Mark an object as updated/dirty  

OCIObjectUnmark()  

Unmarks an object  

OCIObjectUnmarkByRef()  

Unmarks an object, given a ref to it  


OCICacheUnmark()

Purpose

Unmarks all dirty objects in the object cache.

Syntax

sword OCICacheUnmark ( OCIEnv            *env, 
                       OCIError          *err,
                       CONST OCISvcCtx   *svc );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

OCI service context.

Comments

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.

Related Functions

OCIObjectUnmark()


OCIObjectMarkDelete()

Purpose

Marks a standalone instance as deleted, given a pointer to the instance.

Syntax

sword OCIObjectMarkDelete ( OCIEnv        *env, 
                            OCIError      *err, 
                            dvoid         *instance );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

instance (IN)

Pointer to the instance. It must be standalone, and if it is an object it must be pinned.

Comments

This function accepts a pointer to a standalone instance and marks the object as deleted. The object is freed according to the following rules:

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.

Related Functions

OCIObjectMarkDeleteByRef(), OCIObjectGetProperty()


OCIObjectMarkDeleteByRef()

Purpose

Marks an object as deleted, given a reference to the object.

Syntax

sword OCIObjectMarkDeleteByRef ( OCIEnv         *env, 
                                 OCIError       *err, 
                                 OCIRef         *object_ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object_ref (IN)

Reference to the object to be deleted.

Comments

This function accepts a reference to an object, and marks the object designated by object_ref as deleted. The object is marked and freed as follows:

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.

Related Functions

OCIObjectMarkDelete(), OCIObjectGetProperty()


OCIObjectMarkUpdate()

Purpose

Marks a persistent object as updated, or dirty.

Syntax

sword OCIObjectMarkUpdate ( OCIEnv        *env,
                            OCIError      *err, 
                            dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object, which must already be pinned.

Comments

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 OCIObjectIsLocked().

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

This function is an no-op for values.

For more information about the use of this function, see "Marking Objects and Flushing Changes".

Related Functions

OCIObjectPin(), OCIObjectGetProperty()


OCIObjectUnmark()

Purpose

Unmarks an object as dirty.

Syntax

sword OCIObjectUnmark ( OCIEnv       *env,
                        OCIError     *err,
                        dvoid        *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

Pointer to the persistent object. It must be pinned.

Comments

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

This function is an no-op for values. This means that the function will have no effect if called on a value.

Related Functions

OCIObjectUnmarkByRef()


OCIObjectUnmarkByRef()

Purpose

Unmarks an object as dirty, given a REF to the object.

Syntax

sword OCIObjectUnmarkByRef ( OCIEnv      *env, 
                             OCIError    *err,
                             OCIRef      *ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

ref (IN)

Reference of the object. It must be pinned.

Comments

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.

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

This function is a no-op for values.

Related Functions

OCIObjectUnmark()

OCI Get Object Status Functions

This section describes the OCI get object status functions.

Table 16-4 OCI Navigational Functions Quick Reference
Function/Page  Purpose 

OCIObjectExists()  

Get the existent status of an instance  

OCIObjectGetProperty()  

Get the status of a particular object property  

OCIObjectIsLocked()  

Get the dirtied status of an instance  

OCIObjectIsLocked()  

Get the locked status of an instance  


OCIObjectExists()

Purpose

Returns the existence meta-attribute of a standalone instance.

Syntax

sword OCIObjectExists ( OCIEnv         *env,
                        OCIError       *err,
                        dvoid          *ins,
                        boolean        *exist ); 

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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.

Comments

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".

Related Functions

OCIObjectPin()


OCIObjectGetProperty()

Purpose

Retrieve a given property of an object.

Syntax

sword OCIObjectGetProperty ( OCIEnv              *envh, 
                             OCIError            *errh, 
                             CONST dvoid         *obj, 
                             OCIObjectPropId     propertyId,
                             dvoid               *property, 
                             ub4                 *size );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

obj (IN)

The object whose property is returned.

propertyId (IN)

The identifier which identifies the desired property.

property (OUT)

The buffer into which the desired property is copied.

size (IN/OUT)

On input, this parameter specifies the size of the property buffer passed by caller.

On output it contains the size in bytes of the property returned. This parameter is required for string-type properties only, such as OCI_OBJECTPROP_SCHEMA, OCI_OBJECTPROP_TABLE). For non-string properties this parameter is ignored since the size is fixed.

Comments

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 are given below.

OCI_OBJECTPROP_LIFETIME

This identifies whether the given object is a persistent object or a transient object or a value instance. The property argument must be a pointer to a variable of type OCIObjectLifetime. Possible values include:

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. The 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. The 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. The property argument must be a pointer to a variable of type OCIDuration. Valid values include

For more information about durations, see "Object Duration".

OCI_OBJECTPROP_ALLOC_DURATION

This returns the allocation duration of the object. The property argument must be a pointer to a variable of type OCIDuration. Valid values include:

For more information about durations, see "Object Duration".

OCI_OBJECTPROP_LOCK

This returns the lock status of the object. The possible lock statuses are enumerated by OCILockOpt. An error is returned if the given object points to a transient or value instance. The 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(). Valid values include:

OCI_OBJECTPROP_MARKSTATUS

This returns the dirty status and indicates whether the object is a new object, updated object or deleted object. An error is returned if the given object points to a transient or value instance. The property argument must be of type OCIObjectMarkStatus. Valid values include:

The following macros are available to test the object mark status:

OCI_OBJECTPROP_VIEW

This identifies whether the specified object is a view object or not. If the property value returned is TRUE, it indicates the object is a view otherwise it is not. An error is returned if the given object points to a transient or value instance. The property argument must be of type boolean.

Related Functions

OCIObjectLock(), OCIObjectMarkDelete(), OCIObjectMarkUpdate(), OCIObjectPin(), OCIObjectPin()


OCIObjectIsDirty()

Purpose

Checks to see if an object is marked as dirty.

Syntax

sword OCIObjectIsDirty ( OCIEnv       *env,
                         OCIError     *err, 
                         dvoid        *ins,
                         boolean      *dirty );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

ins (IN)

Pointer to an instance.

dirty (OUT)

Return value for the dirty status.

Comments

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.

Related Functions

OCIObjectMarkUpdate(), OCIObjectGetProperty()


OCIObjectIsLocked()

Purpose

Get lock status of an object.

Syntax

sword OCIObjectIsLocked ( OCIEnv       *env, 
                          OCIError     *err, 
                          dvoid        *ins,
                          boolean      *lock );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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.

Comments

This function returns the lock status of an instance. If the instance is a value, this function always returns FALSE.

Related Functions

OCIObjectLock(), OCIObjectGetProperty()

OCI Miscellaneous Object Functions

This section describes the miscellaneous object functions.

Table 16-5 OCI Navigational Functions Quick Reference
Function/Page  Purpose 

OCIObjectCopy()  

Copy one instance to another  

OCIObjectGetAttr()  

Gets an object attribute  

OCIObjectGetInd()  

Get null structure of an instance  

OCIObjectGetObjectRef()  

Return reference to a given object  

OCIObjectGetTypeRef()  

Get a reference to a TDO of an instance  

OCIObjectLock()  

Lock a persistent object  

OCIObjectLockNoWait()  

Lock a persistent object but do not wait for the lock  

OCIObjectPin()  

Create a new instance  

OCIObjectSetAttr()  

Sets an object attribute  


OCIObjectCopy()

Purpose

Copies a source instance to a destination.

Syntax

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 );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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.

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.

Comments

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 OCIObjectPin().

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.

Related Functions

OCIObjectPin()


OCIObjectGetAttr()

Purpose

Retrieves an object attribute.

Syntax

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 );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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]

Not currently supported. Pass as (ub4 *)0.

index_count (IN) [optional]

Not currently supported. Pass as (ub4)0.

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.

Comments

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.

Related Functions

OCIObjectSetAttr()


OCIObjectGetInd()

Purpose

Gets the NULL structure of a standalone instance.

Syntax

sword OCIObjectGetInd ( OCIEnv        *env, 
                        OCIError      *err, 
                        dvoid         *instance, 
                        dvoid         **null_struct );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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.

Comments

None.

Related Functions

OCIObjectPin()


OCIObjectGetObjectRef()

Purpose

Returns a reference to a given persistent object.

Syntax

sword OCIObjectGetObjectRef ( OCIEnv        *env, 
                              OCIError      *err,
                              dvoid         *object, 
                              OCIRef        *object_ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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().

Comments

This function returns a reference to the given persistent object, given a pointer to the object. Passing a value (rather than an object) to this function causes an error.

See Also: For more information about object meta-attributes, see "Object Meta-Attributes".

Related Functions

OCIObjectPin(), OCIObjectPin()


OCIObjectGetTypeRef()

Purpose

Returns a reference to the type descriptor object (TDO) of a standalone instance.

Syntax

sword OCIObjectGetTypeRef ( OCIEnv        *env, 
                            OCIError      *err, 
                            dvoid         *instance, 
                            OCIRef        *type_ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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().

Comments

None.

Related Functions

OCIObjectPin(), OCIObjectPin()


OCIObjectLock()

Purpose

Locks a persistent object at the server.

Syntax

sword OCIObjectLock ( OCIEnv        *env, 
                      OCIError      *err, 
                      dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object being locked. It must already be pinned.

Comments

This function will return an error for transient objects and values. It also returns an error if the object does not exist.

For more information about object locking, see "Locking Objects For Update".

Related Functions

OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(), OCIObjectLockNoWait()


OCIObjectLockNoWait()

Purpose

Locks a persistent object at the server but does not wait for the lock. and returns an error if the lock is unavailable.

Syntax

sword OCIObjectLockNoWait ( OCIEnv        *env, 
                            OCIError      *err, 
                            dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to the persistent object being locked. It must already be pinned.

Comments

This function locks a persistent object at the server. However, unlike OCIObjectLock(), this function does not wait if another user holds the lock on the desired object and an error is returned if the object is currently locked by another user. This function also returns an error for transient objects and values, or objects that do not exist.

The lock of an object is released at the end of a transaction. For more information about object locking, see "Locking Objects For Update".

OCIObjectLockNoWait() returns the following values:

Related Functions

OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(), OCIObjectLock()


OCIObjectNew()

Purpose

Creates a standalone instance

Syntax

sword OCIObjectNew ( OCIEnv            *env, 
                     OCIError          *err, 
                     CONST OCISvcCtx   *svc, 
                     OCITypeCode       typecode,
                     OCIType           *tdo, 
                     dvoid             *table,
                     OCIDuration       duration,
                     boolean           value,
                     dvoid             **instance ); 

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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" 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, such as 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 following description 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.

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

Comments

This function creates a new instance of the type specified by the typecode or the TDO. For more information about typecodes, see "Typecodes". Based on the parameters typecode (or tdo), value and table, different instances are 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  

This function allocates the top-level memory chunk of an instance. The attributes in the top-level memory are initialized which means that an attribute of varchar2 is initialized to a OCIString of 0 length. If the instance is an object, the object is marked existed but is atomically null.

See Also: For information about creating new objects based on object views or user-created OIDs, see "Creating Objects Based on Object Views or User-defined OIDs".

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. Creating a persistent object does not cause any entries to be made into a database table until the object is flushed to the server.

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.

Attribute Values of New Objects

By default, all attributes of a newly created objects have NULL values. After initializing attribute data, the user must change the corresponding NULL status of each attribute to non-NULL.

It is possible to have attributes set to non-NULL values when an object is created. This is accomplished by setting the OCI_OBJECT_NEWNOTNULL attribute of the environment handle to TRUE using OCIAttrSet(). This mode can later be turned off by setting the attribute to FALSE. If OCI_OBJECT_NEWNOTNULL is set to TRUE, then OCIObjectNew() creates a non-null object. For more information, refer to "Attribute Values of New Objects".

Objects with LOB Attributes

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 before flushing the object to the database. It is an error to INSERT or UPDATE a FILE without first indicating a directory alias and filename. Once the filename is set, the user can start reading from the FILE.

Note: Oracle8i supports only binary FILEs (BFILEs).

Related Functions

OCIObjectPinTable(), OCIObjectFree()


OCIObjectSetAttr()

Purpose

Set an object attribute.

Syntax

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 );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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]

Not currently supported. Pass as (ub4 *)0.

index_count (IN) [optional]

Not currently supported. Pass as (ub4)0.

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.

Comments

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.

Example

For the path expression stanford.cs.stu[5].addr, the arrays will look like:

names = {"stanford", "cs", "stu", "addr"}

lengths = {8, 2, 3, 4}

indexes = {5}

Related Functions

OCIObjectMarkDelete()

OCI Pin, Unpin, and Free Functions

This section describes the OCI pin unpin, and free functions.

Table 16-6 OCI Pin, Unpin, and Free Functions Quick Reference
Function/Page  Purpose 

OCICacheFree()  

Free objects in the cache  

OCICacheUnpin()  

Unpin persistent objects in cache or connection  

OCIObjectArrayPin()  

Pin an array of references  

OCIObjectFree()  

Free a previously allocated object  

OCIObjectPin()  

Pin an object  

OCIObjectPinCountReset()  

Unpin an object to zero pin count  

OCIObjectPinTable()  

Pin a table object with a given duration  

OCIObjectUnpin()  

Unpin an object  


OCICacheFree()

Purpose

Frees all objects and values in the cache for the specified connection.

Syntax

sword OCICacheFree ( OCIEnv              *env,
                     OCIError            *err, 
                     CONST OCISvcCtx     *svc ); 

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

An OCI service context.

Comments

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.

Related Functions

OCIObjectFree()


OCICacheUnpin()

Purpose

Unpins persistent objects.

Syntax

sword OCICacheUnpin ( OCIEnv              *env,
                      OCIError            *err, 
                      CONST OCISvcCtx     *svc );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

An OCI service context handle. The objects on the specified connection are unpinned.

Comments

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", and "Pin Count and Unpinning".

Related Functions

OCIObjectUnpin()


OCIObjectArrayPin()

Purpose

Pins an array of references.

Syntax

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 );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

ref_array (IN)

Array of references to be pinned

array_size (IN)

Number of elements in the array of references

cor_array

An array of COR handles corresponding to the objects being pinned.

cor_array_size

The number of elements in cor_array.

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 there is an error, this argument indicates the element that is causing the error. Note that this argument is set to 1 for the first element in the ref_array.

Comments

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.

Related Functions

OCIObjectPin()


OCIObjectFree()

Purpose

Frees and unpins an object instance.

Syntax

sword OCIObjectFree ( OCIEnv          *env, 
                      OCIError        *err, 
                      dvoid           *instance, 
                      ub2             flags );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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 passed, free the object even if it is pinned or dirty. If OCI_OBJECTFREE_NONULL is passed, the null structure is not freed.

Comments

This function deallocates all the memory allocated for an object instance, including the null structure. The following rules apply for different instance types:

For Persistent Objects

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.

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_OBJECTFREE_FORCE.

For Values

The memory of the object is freed immediately.

Related Functions

OCICacheFree()


OCIObjectPin()

Purpose

Pin a referenceable object.

Syntax

sword OCIObjectPin ( OCIEnv              *env, 
                     OCIError            *err, 
                     OCIRef              *object_ref,
                     OCIComplexObject    *corhdl,
                     OCIPinOpt           pin_option, 
                     OCIDuration         pin_duration, 
                     OCILockOpt          lock_option,
                     dvoid               **object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object_ref (IN)

The reference to the object.

corhdl (IN)

Handle for complex object retrieval.

pin_option (IN)

Used to specify the copy of the object that is to be retrieved.

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. Note, the lock status of an object can also be retrieved by calling OCIObjectIsLocked(). Valid values include:

See Also: For information about the NOWAIT option, see "Locking With the NOWAIT Option"

object (OUT)

The pointer to the pinned object.

Comments

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.

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:

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.

Related Functions

OCIObjectUnpin(), OCIObjectPinCountReset()


OCIObjectPinCountReset()

Purpose

Completely unpins an object, setting its pin count to zero.

Syntax

sword OCIObjectPinCountReset ( OCIEnv        *env, 
                               OCIError      *err, 
                               dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to an object, which must already be pinned.

Comments

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:

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 Values

This function will return an error for value.

For more information about the use of this function, see "Pin Count and Unpinning".

Related Functions

OCIObjectPin(), OCIObjectUnpin()


OCIObjectPinTable()

Purpose

Pins a table object for a specified duration.

Syntax

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 );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information 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.

Comments

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.

Related Functions

OCIObjectPin(), OCIObjectUnpin()


OCIObjectUnpin()

Purpose

Unpins an object.

Syntax

sword OCIObjectUnpin ( OCIEnv        *env,
                       OCIError      *err, 
                       dvoid         *object );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

object (IN)

A pointer to an object, which must already be pinned.

Comments

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.

This function unpins an object. An object is completely unpinned when any of the following is true:

  1. The object's pin count reaches zero (i.e., it is unpinned a total of N times after being pinned a total of N times).

  2. It is the end of the object's pin duration.

  3. The function OCIObjectPinCountReset() is called on the object.

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:

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 Values

This function returns an error for values.

Related Functions

OCIObjectPin(), OCIObjectPinCountReset()

OCI Type Information Accessor Functions

This section describes the OCI type information accessor functions.

Table 16-7 OCI Type Information Accessor Functions Quick Reference
Function/Page  Purpose 

OCITypeArrayByName()  

Get an array of TDOs given an array of object names  

OCITypeArrayByRef()  

Get an array of TDOs given an array of object references  

OCITypeByName()  

Get a TDO given an object name  

OCITypeByRef()  

Get a TDO given an object reference  


OCITypeArrayByName()

Purpose

Get an array of types given an array of names.

Syntax

sword OCITypeArrayByName ( OCIEnv             *envhp,
                           OCIError           *errhp,
                           CONST OCISvcCtx    *svc,
                           ub4                array_len,
                           CONST text         *schema_name[],
                           ub4                s_length[],
                           CONST text         *type_name[],
                           ub4                t_length[],
                           CONST text         *version_name[],
                           ub4                v_length[],
                           OCIDuration        pin_duration,
                           OCITypeGetOpt      get_option,
                           OCIType            *tdo[] );

Parameters

envhp (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

OCI service handle.

array_len (IN)

Number of schema_name/type_name/version_name entries to be retrieved.

schema_name (IN, optional)

Array of schema names associated with the types to be retrieved. The array must have array_len elements if specified. If 0 is supplied, the default schema is assumed, otherwise it MUST have array_len number of elements. 0 can be supplied for one or more of the entries to indicate that the default schema is desired for those entries.

s_length (IN)

Array of schema_name lengths with each entry corresponding to the length of the corresponding schema_name entry in the schema_name array in bytes. The array must either have array_len number of elements or it MUST be 0 if schema_name is not specified.

type_name (IN)

Array of the names of the types to retrieve. This MUST have array_len number of elements.

t_length (IN)

Array of the lengths of type names in the type_name array in bytes.

version_name (IN)

Array of the version names of the types to retrieve corresponding. This can be 0 to indicate retrieval of the most current versions, or it MUST have array_len number of elements.

If 0 is supplied, the most current version is assumed, otherwise it MUST have array_len number of elements. 0 can be supplied for one or more of the entries to indicate that the current version is desired for those entries.

Note: In release 8.0 the version parameters are ignored.

v_length (IN)

Array of the lengths of version names in the version_name array in bytes.

Note: In release 8.0 the version parameters are ignored.

pin_duration (IN)

Pin duration (e.g. until the end of current transaction) for the types retrieved. See oro.h for a description of each option.

get_option (IN)

Options for loading the types. It can be one of two values:

tdo (OUT)

Output array for the pointers to each pinned type in the object cache. It must have space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the CREF to each pinned type descriptor.

Comments

Gets pointers to the existing types associated with the schema/type name array.

The get_option parameter can be used to control the portion of the TDO that gets loaded per roundtrip.

This function returns an error if any of the required parameters is null or any object types associated with a schema/type name entry do not exist.

To retrieve a single type, rather than an array, use OCITypeByName().

Related Functions

OCITypeArrayByRef(), OCITypeByName(), OCITypeByRef()


OCITypeArrayByRef()

Purpose

Get an array of types given an array of references.

Syntax

sword OCITypeArrayByRef ( OCIEnv           *envhp,
                          OCIError         *errhp,
                          ub4              array_len,
                          CONST OCIRef     *type_ref[],
                          OCIDuration      pin_duration,
                          OCITypeGetOpt    get_option,
                          OCIType          *tdo[] );

Parameters

envhp (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

errhp (IN/OUT)

The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().

array_len (IN)

Number of schema_name/type_name/version_name entries to be retrieved.

type_ref (IN)

Array of OCIRef * pointing to the particular version of the type descriptor object to obtain. The array must have array_len elements if specified.

pin_duration (IN)

Pin duration (e.g. until the end of current transaction) for the types retrieved. See oro.h for a description of each option.

get_option (IN)

Options for loading the types. It can be one of two values:

tdo (OUT)

Output array for the pointers to each pinned type in the object cache. It must have space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the CREF to each pinned type descriptor.

Comments

Gets pointers to the with the schema/type name array.

This function returns an error if:

To retrieve a single type, rather than an array of types, use OCITypeByName().

Related Functions

OCITypeArrayByName(), OCITypeByRef(), OCITypeByName()


OCITypeByName()

Purpose

Get the most current version of an existing type by name.

Syntax

sword OCITypeByName ( OCIEnv               *env,
                      OCIError             *err, 
                      CONST OCISvcCtx      *svc, 
                      CONST text           *schema_name,
                      ub4                  s_length, 
                      CONST text           *type_name, 
                      ub4                  t_length, 
                      CONST text           *version_name,
                      ub4                  v_length,
                      OCIDuration          pin_duration,
                      OCITypeGetOpt        get_option
                      OCIType              **tdo );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

svc (IN)

OCI service handle.

schema_name (IN, optional)

Name of schema associated with the type. By default, the user's schema name is used.

s_length (IN)

Length of the schema_name parameter.

type_name (IN)

Name of the type to get.

t_length (IN)

Length of the type_name parameter.

version_name (IN, optional)

User-readable version of the type. Pass as (text *) 0 to retrieve the most current version. For release 8.0 only a single version is supported.

v_length (IN)

Length of version_name in bytes. Pass as 0 if the most current version is to be retrieved.

pin_duration (IN)

Pin duration. Refer to the section "Object Duration" for more information.

get_option ((IN)

Options for loading the types. It can be one of two values:

tdo (OUT)

Pointer to the pinned type in the object cache.

Comments

This function gets a pointer to the existing type associated with schema/type name. It returns an error if any of the required parameters is NULL, or if the object type associated with schema/type name does not exist.

Note: Schema and type names are CASE-SENSITIVE. If they have been created with SQL, you need to use uppercase names.

An application can retrieve an array of TDOs by calling OCITypeArrayByName(), or OCITypeArrayByRef().

Related Functions

OCITypeByRef(), OCITypeArrayByName(), OCITypeArrayByRef()


OCITypeByRef()

Purpose

Get a type given a reference.

Syntax

sword OCITypeByRef ( OCIEnv          *env,
                     OCIError        *err,
                     CONST OCIRef    *type_ref,
                     OCIDuration     pin_duration,
                     OCITypeGetOpt   get_option,
                     OCIType         *tdo );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 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. Obtain diagnostic information by calling OCIErrorGet().

type_ref (IN)

An OCIRef * pointing to the version of the type descriptor object to obtain.

pin_duration (IN)

Pin duration until the end of current transaction for the type to retrieve. See oro.h for a description of each option.

get_option (IN)

Options for loading the type. It can be one of two values:

tdo (OUT)

Pointer to the pinned type in the object cache.

Comments

OCITypeByRef() returns an error if: any of the required parameters is null or any object types associated with a schema/type name entry do not exist.

Related Functions

OCITypeByName(), OCITypeArrayByName(), OCITypeArrayByRef()




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index