OCICollGetElem()

Purpose

Gets a pointer to the element at the given index.

Syntax

sword OCICollGetElem ( OCIEnv           *env, 
                       OCIError         *err, 
                       CONST OCIColl    *coll, 
                       sb4              index, 
                       boolean          *exists, 
                       dvoid            **elem, 
                       dvoid            **elemind );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode.

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

coll (IN)

Pointer to the element in this collection is returned.

index (IN)

Index of the element whose pointer is returned.

exists (OUT)

Set to FALSE if the element at the specified index does not exist; otherwise, set to TRUE.

elem (OUT)

Address of the desired element is returned.

elemind (OUT) [optional]

Address of the null indicator information is returned. If (elemind == NULL), then the null indicator information will not be returned.

Comments

Gets the address of the element at the given position. Optionally this function also returns the address of the element's null indicator information.

The following table describes for each collection element type what the corresponding element pointer type is. The element pointer is returned with the elem parameter of OCICollGetElem().

Element Type	*elem is set to
Oracle Number (OCINumber)	OCINumber*
Date (OCIDate)	OCIDate*
Datetime (OCIDateTime)	OCIDateTime*
Interval (OCIInterval)	OCIInterval*
Variable-length string (OCIString*)	OCIString**
Variable-length raw (OCIRaw*)	OCIRaw**
object reference (OCIRef*)	OCIRef**
lob locator (OCILobLocator*)	OCILobLocator**
object type (such as person)	person*

The element pointer returned by OCICollGetElem() is in a form such that it cannot only be used to access the element data but also is in a form that can be used as the target (left-hand-side) of an assignment statement.

For example, assume the user is iterating over the elements of a collection whose element type is object reference (OCIRef*). A call to OCICollGetElem() returns pointer to a reference handle (OCIRef**). After getting, the pointer to the collection element, the user may wish to modify it by assigning a new reference.

This can be accomplished by means of the ref assignment function as follows:

sword OCIRefAssign( OCIEnv       *env, 
                    OCIError     *err, 
                    CONST OCIRef *source, 
                    OCIRef       **target );

Note that the target parameter of OCIRefAssign() is of type OCIRef**. Hence OCICollGetElem() returns OCIRef**. If *target equals NULL, a new REF will be allocated by OCIRefAssign() and returned in the target parameter.

Similarly, if the collection element was of type string (OCIString*), OCICollGetElem() returns pointer to string handle (that is, OCIString**). If a new string is assigned, through OCIStringAssign() or OCIStringAssignText(), the type of the target must be OCIString **.

If the collection element is of type Oracle number, OCICollGetElem() returns OCINumber*. The prototype of OCINumberAssign() is:

sword OCINumberAssign(OCIError        *err, 
                      CONST OCINumber *from,
                      OCINumber       *to);

This function returns an error if any of the input parameters is null.

Related Functions

OCIErrorGet(), OCICollAssignElem()