Skip Headers

Oracle Call Interface Programmer's Guide
Release 2 (9.2)

Part Number A96584-01
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback

Go to previous page Go to next page

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

See Also:

For code examples, see the demonstration programs included with your Oracle installation. For additional information, refer to Appendix B, "OCI Demonstration Programs".

The chapter contains the following sections:

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 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 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 lnoci032.gif follows
Text description of the illustration lnoci032.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:

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 OCI handle passed to the function is invalid.

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 Round-trips for Cache and Object Functions

For a table showing the number of server round-trips 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.

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


Go to previous page Go to next page
Oracle
Copyright © 1996, 2002 Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Book List
Go To Table Of Contents
Contents
Go To Index
Index

Master Index

Feedback