OCI Collection and Iterator Functions

This section describes the Collection and Iterator functions.

Table 18-3 Collection and Iterator Functions

Function/Page	Purpose
OCICollAppend()	Collection appends element
OCICollAssign()	Assigns collection
OCICollAssignElem()	Collection assigns element
OCICollGetElem()	Gets pointer to an element
OCICollGetElemArray()	Gets an array of elements from a collection.
OCICollIsLocator()	Indicates whether a collection is locator-based or not
OCICollMax()	Returns maximum number of elements in collection
OCICollSize()	Gets current size of collection (in number of elements)
OCICollTrim()	Trims elements from the collection
OCIIterCreate()	Creates iterator to scan the varray elements
OCIIterDelete()	Deletes iterator
OCIIterGetCurrent()	Gets current collection element
OCIIterInit()	Initializes iterator to scan the given collection
OCIIterNext()	Gets next collection element
OCIIterPrev()	Gets previous collection element

OCICollAppend()

Purpose

Appends an element to the end of a collection.

Syntax

sword OCICollAppend ( OCIEnv              *env,
                      OCIError            *err,
                      CONST dvoid         *elem, 
                      CONST dvoid         *elemind,
                      OCIColl             *coll );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
elem (IN): Pointer to the element which is appended to the end of the given collection.
elemind (IN) [optional]: Pointer to the element's NULL indicator information. If (elemind == NULL) then the NULL indicator information of the appended element will be set to non-NULL.
coll (IN/OUT): Updated collection.

Comments

Appending an element is equivalent to increasing the size of the collection by 1 element and updating (deep-copying) the last element's data with the given element's data. Note that the pointer to the given element elem is not saved by this function, which means that elem is strictly an input parameter.

This function returns an error if the current size of the collection is equal to the max size (upper-bound) of the collection prior to appending the element. This function also returns an error if any of the input parameters is NULL.

Related Functions

OCIErrorGet()

OCICollAssign()

Purpose

Assigns (deep-copies) one collection to another.

Syntax

sword OCICollAssign ( OCIEnv              *env, 
                      OCIError            *err, 
                      CONST OCIColl       *rhs, 
                      OCIColl             *lhs );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
rhs (IN): Right-hand side (source) collection to be assigned from.
lhs (OUT): Left-hand side (target) collection to be assigned to.

Comments

Assigns rhs (source) to lhs (target). The lhs collection may be decreased or increased depending upon the size of rhs. If the lhs contains any elements then the elements will be deleted prior to the assignment. This function performs a deep copy. The memory for the elements comes from the object cache.

An error is returned if the element types of the lhs and rhs collections do not match. Also, an error is returned if the upper-bound of the lhs collection is less than the current number of elements in the rhs collection. An error is also returned if:

any of the input parameters is NULL
there is a type mismatch between the lhs and rhs collections
the upper bound of lhs collection is less than the current number of elements in the rhs collection

Related Functions

OCIErrorGet(), OCICollAssignElem()

OCICollAssignElem()

Purpose

Assigns the given element value elem to the element at coll[index].

Syntax

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

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
index (IN): Index of the element whose is assigned to.
elem (IN): Element which is assigned from (source element).
elemind (IN) [optional]: Pointer to the element's NULL indicator information; if (elemind == NULL) then the NULL indicator information of the assigned element will be set to non-NULL.
coll (IN/OUT): Collection to be updated.

Comments

If the collection is of type nested table, the element at the given index may not exist, as in the case when an element has been deleted. In this case, the given element is inserted at index. Otherwise, the element at index is updated with the value of elem.

Note that the given element is deep-copied and elem is strictly an input parameter.

This function returns an error if any input parameter is NULL or if the given index is beyond the bounds of the given collection.

Related Functions

OCIErrorGet(), OCICollAssign()

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.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().

Table 18-4 Element Pointers

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

OCICollGetElemArray()

Purpose

Gets an array of elements from a collection given a starting index.

Syntax

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

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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): Pointers to the elements in this collection to be returned.
index (IN): Starting index of the elements.
exists (OUT): Is set to FALSE if the element at the specified index does not exist, else it is set to TRUE.
elem (OUT): Address of the desired elements to be returned.
elemind (OUT): [optional] Address of the NULL indicators information to be returned. If (elemind == NULL) then the NULL indicator information will not be returned.
nelems (IN): Maximum number of pointers to both elem and elemind.

Comments

Gets the address of the elements from the given position. Optionally, this function also returns the address of the element's NULL indicator information.

Related Functions

OCIErrorGet(), OCICollGetElem()

OCICollIsLocator()

Purpose

Indicates whether a collection is locator-based or not.

Syntax

sword OCICollIsLocator ( OCIEnv *env, 
                         OCIError *err,
                         CONST OCIColl *coll, 
                         boolean *result );

Parameters

env (IN): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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): A collection item.
result (OUT): Returns TRUE if the collection item is locator-based, FALSE otherwise.

Comments

This function tests to see whether or not a collection is locator-based. Returns TRUE in the result parameter if the collection item is locator-based, otherwise it returns FALSE.

Related Functions

OCIErrorGet()

OCICollMax()

Purpose

Gets the maximum size in number of elements of the given collection.

Syntax

sb4 OCICollMax ( OCIEnv           *env,
                 CONST OCIColl    *coll );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
coll (IN): Collection whose number of elements is returned. coll must point to a valid collection descriptor.

Comments

Returns the maximum number of elements that the given collection can hold. A value of zero indicates that the collection has no upper bound.

Returns

The upper bound of the given collection.

Related Functions

OCIErrorGet(), OCICollSize()

OCICollSize()

Purpose

Gets the current size in number of elements of the given collection.

Syntax

sword OCICollSize ( OCIEnv           *env,
                    OCIError         *err,
                    CONST OCIColl    *coll 
                    sb4              *size );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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): Collection whose number of elements is returned. Must point to a valid collection descriptor.
size (OUT): Current number of elements in the collection.

Comments

Returns the current number of elements in the given collection. For the case of nested table, this count will not be decremented upon deleting elements. So, this count includes any holes created by deleting elements. A trim operation (OCICollTrim()) will decrement the count by the number of trimmed elements. To get the count minus the deleted elements use OCITableSize().

The following pseudocode shows some examples:

OCICollSize(...); 
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCICollSize(...);
// 'size' returned is still 5

To get the count minus the deleted elements use OCITableSize(). Continuing the earlier example:

OCITableSize(...)
// 'size' returned is equal to 4

A trim operation (OCICollTrim()) decrements the count by the number of trimmed elements. Continuing the earlier example:

OCICollTrim(..,1..); // trim one element
OCICollSize(...);
// 'size' returned is equal to 4

This function returns an error if an error occurs during the loading of the collection into object cache or if any of the input parameters is NULL.

Related Functions

OCIErrorGet(), OCICollMax()

OCICollTrim()

Purpose

Trims the given number of elements from the end of the collection.

Syntax

sword OCICollTrim ( OCIEnv         *env, 
                    OCIError       *err, 
                    sb4            trim_num, 
                    OCIColl        *coll );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()".
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().
trim_num (IN): Number of elements to trim.
coll (IN/OUT): This function removes (frees) trim_num elements from the end of coll.

Comments

The elements are removed from the end of the collection. An error is returned if trim_num is greater than the current size of the collection.

Related Functions

OCIErrorGet(), OCICollSize()

OCIIterCreate()

Purpose

Creates an iterator to scan the elements or the collection.

Syntax

sword OCIIterCreate ( OCIEnv               *env, 
                      OCIError             *err, 
                      CONST OCIColl        *coll, 
                      OCIIter              **itr );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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): Collection which will be scanned. For this release, valid collection types include varrays and nested tables.
itr (OUT): Address to the allocated collection iterator is returned by this function.

Comments

The iterator is created in the object cache. The iterator is initialized to point to the beginning of the collection.

If OCIIterNext() is called immediately after creating the iterator then the first element of the collection is returned. If OCIIterPrev() is called immediately after creating the iterator then a "at beginning of collection" error is returned.

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

Related Functions

OCIErrorGet(), OCIIterDelete()

OCIIterDelete()

Purpose

Deletes a collection iterator.

Syntax

sword OCIIterDelete ( OCIEnv           *env, 
                      OCIError         *err, 
                      OCIIter          **itr );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
itr (IN/OUT): The allocated collection iterator which is destroyed and set to NULL prior to returning.

Comments

Deletes an iterator which was previously created by a call to OCIIterCreate().

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

Related Functions

OCIErrorGet(), OCIIterCreate()

OCIIterGetCurrent()

Purpose

Gets a pointer to the current iterator collection element.

Syntax

sword OCIIterGetCurrent ( OCIEnv            *env, 
                          OCIError          *err, 
                          CONST OCIIter     *itr, 
                          dvoid             **elem, 
                          dvoid             **elemind );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
itr (IN): Iterator which points to the current element.
elem (OUT): Address of the element pointed by the iterator is returned.
elemind (OUT) [optional]: Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.

Comments

Returns pointer to the current iterator collection element and its corresponding NULL information. This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterNext(), OCIIterPrev()

OCIIterInit()

Purpose

Initializes an iterator to scan a collection.

Syntax

sword OCIIterInit ( OCIEnv              *env, 
                    OCIError            *err, 
                    CONST OCIColl       *coll, 
                    OCIIter             *itr );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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): Collection which will be scanned. For Oracle8i or later, valid collection types include varrays and nested tables.
itr (IN/OUT): Pointer to an allocated collection iterator.

Comments

Initializes given iterator to point to the beginning of given collection. Returns an error if any input parameter is NULL. This function can be used to:

reset an iterator to point back to the beginning of the collection, or
reuse an allocated iterator to scan a different collection.

Related Functions

OCIErrorGet()

OCIIterNext()

Purpose

Gets a pointer to the next iterator collection element.

Syntax

sword OCIIterNext ( OCIEnv            *env,
                    OCIError          *err, 
                    OCIIter           *itr, 
                    dvoid             **elem,
                    dvoid             **elemind,
                    boolean           *eoc);

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
itr (IN/OUT): Iterator is updated to point to the next element.
elem (OUT): After updating the iterator to point to the next element, address of the element is returned.
elemind (OUT) [optional]: Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.
eoc (OUT): TRUE if iterator is at End of Collection (that is, next element does not exist); otherwise, FALSE.

Comments

This function returns a pointer to the next iterator collection element and its corresponding NULL information. It also updates the iterator to point to the next element.

If the iterator is pointing to the last element of the collection prior to executing this function, then calling this function will set the eoc flag to TRUE. The iterator will be left unchanged in that case.

This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterGetCurrent(), OCIIterPrev()

OCIIterPrev()

Purpose

Gets a pointer to the previous iterator collection element.

Syntax

sword OCIIterPrev ( OCIEnv            *env, 
                    OCIError          *err, 
                    OCIIter           *itr, 
                    dvoid             **elem, 
                    dvoid             **elemind,
                    boolean           *boc );

Parameters

env (IN/OUT): The OCI environment handle initialized in object mode.

See Also:
"OCIEnvCreate()" and "OCIInitialize()"
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().
itr (IN/OUT): Iterator which is updated to point to the previous element.
elem (OUT): Address of the previous element; returned after the iterator is updated to point to it.
elemind (OUT) [optional]: Address of the element's NULL indicator; if (elemind == NULL) then the NULL indicator will not be returned.
boc (OUT): TRUE if iterator is at beginning of collection (that is, previous element does not exist); otherwise, FALSE.

Comments

This function returns a pointer to the previous iterator collection element and its corresponding NULL information. The iterator is updated to point to the previous element.

If the iterator is pointing to the first element of the collection prior to executing this function, then calling this function will set boc to TRUE. The iterator is left unchanged in that case.

This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterGetCurrent(), OCIIterNext()