17
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 to the Navigational and Type Functions

• OCI Flush or Refresh Functions

• OCI Mark or Unmark Object and Cache Functions

• OCI Get Object Status Functions

• OCI Miscellaneous Object Functions

• OCI Pin, Unpin, and Free Functions

• OCI Type Information Accessor Functions

Introduction to the Navigational and Type Functions

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

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

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

• 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. 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 17-1 shows how instances can be classified according to their type and lifetime:

Figure 17-1 Classification of Instances by Type and Lifetime

Text description of the illustration oci81032.gif

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:

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

• A referenceable object refers to a persistent object or a transient object.

• A standalone object refers to a persistent object, a transient object or a standalone value of object type.

• An embedded object refers to a embedded value of object type.

• An object is dirty if it has been created (newed), or marked updated or deleted.

  See Also: 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

The function declaration.

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 in Table 18-1, "Function Return Values".

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

Navigational Function Error Codes

Table 17-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 17-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 17-1 have the following meanings.

• ORA-21560 - name argument should not be null

• ORA-21600 - path expression too long

• ORA-21601 - attribute is not an instance of user-defined type

• ORA-21603 - cannot free a dirtied persistent object

• ORA-21700 - object does not exist or has been deleted

• ORA-21701 - invalid object

• ORA-21702 - object is not instantiated in the cache

• ORA-21703 - cannot flush an object that is not modified

• ORA-21704 - terminate cache or connection without flushing

• ORA-21705 - service context is invalid

• ORA-21708 - operations cannot be performed on a transient object

• ORA-21709 - operations can only be performed on a current object

• ORA-21710 - invalid pointer or value passed to the function

• ORA-22279 - cannot perform operation with LOB buffering enabled

• ORA-22305 - name argument is invalid

• ORA-24350 - this OCI call is not allowed from external subroutines

OCI Flush or Refresh Functions

This section describes the OCI flush or refresh functions.

Table 17-2 Flush or Refresh Functions

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