Table 19-2 describes the collection and iterator functions that are described in this section.
Table 19-2 Collection and Iterator Functions
| Function | Purpose |
|---|---|
|
Append an element to the end of a collection |
|
|
Assign (deep copy) one collection to another |
|
|
Assign the given element value |
|
|
Get pointer to an element |
|
|
Get an array of elements from a collection |
|
|
Indicate whether a collection is locator-based or not |
|
|
Return maximum number of elements in collection |
|
|
Get current size of collection (in number of elements) |
|
|
Trim elements from the collection |
|
|
Create iterator to scan the varray elements |
|
|
Delete iterator |
|
|
Get current collection element |
|
|
Initialize iterator to scan the given collection |
|
|
Get next collection element |
|
|
Get previous collection element |
sword OCICollAppend ( OCIEnv *env,
OCIError *err,
const void *elem,
const void *elemind,
OCIColl *coll );
The OCI environment handle initialized in object mode.
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().
Pointer to the element to be appended to the end of the given collection.
Pointer to the element's NULL indicator information. If (elemind == NULL) then the NULL indicator information of the appended element is set to non-NULL.
Updated collection.
Appending an element is equivalent to increasing the size of the collection by one 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 equals the maximum size (upper bound) of the collection before appending the element. This function also returns an error if any of the input parameters is NULL.
The OCI environment handle initialized in object mode.
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().
Right-hand side (source) collection to be assigned from.
Left-hand side (target) collection to be assigned to.
Assigns rhs (source) to lhs (target). The lhs collection may be decreased or increased depending upon the size of rhs. If the lhs collection contains any elements, then the elements are deleted before 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 the lhs collection is less than the current number of elements in the rhs collection
sword OCICollAssignElem ( OCIEnv *env,
OCIError *err,
sb4 index,
const void *elem,
const void *elemind,
OCIColl *coll );
The OCI environment handle initialized in object mode.
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 of the element to which the element is assigned.
Source element from which the element is assigned.
Pointer to the element's NULL indicator information; if (elemind == NULL), then the NULL indicator information of the assigned element is set to non-NULL.
Collection to be updated.
If the collection is of type nested table, the element at the given index might not exist, as 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.
sword OCICollGetElem ( OCIEnv *env,
OCIError *err,
const OCIColl *coll,
sb4 index,
boolean *exists,
void **elem,
void **elemind );
The OCI environment handle initialized in object mode.
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().
Pointer to the element in this collection to be returned.
Index of the element whose pointer is returned.
Set to FALSE if the element at the specified index does not exist; otherwise, set to TRUE.
Address of the element to be returned.
Address of the NULL indicator information is returned. If (elemind == NULL), then the NULL indicator information is not returned.
Gets the address of the element at the given position. Optionally, this function also returns the address of the element's NULL indicator information.
Table 19-3 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 |
|
|
Date ( |
|
|
Datetime ( |
|
|
Interval ( |
|
|
Variable-length string ( |
|
|
Variable-length raw ( |
|
|
Object reference ( |
|
|
Lob locator ( |
|
|
Object type (such as person) |
|
The element pointer returned by OCICollGetElem() is in a form that can be used not only to access the element data but also to serve 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 the pointer to a reference handle (OCIRef**). After getting the pointer to the collection element, you may want to modify it by assigning a new reference.
Example 19-1 shows how this can be accomplished with the OCIRefAssign() function.
Example 19-1 Assigning a New Reference to the Pointer to the Collection Element
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 is allocated by OCIRefAssign() and returned in the target parameter.
Similarly, if the collection element was of type string (OCIString*), OCICollGetElem() returns the pointer to the 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*. Example 19-2 shows the prototype of the OCINumberAssign() call.
sword OCICollGetElemArray ( OCIEnv *env,
OCIError *err,
const OCIColl *coll,
sb4 index,
boolean *exists,
void **elem,
void **elemind,
uword *nelems );
The OCI environment handle initialized in object mode.
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().
Pointers to the elements in this collection to be returned.
Starting index of the elements.
Is set to FALSE if the element at the specified index does not exist; otherwise, it is set to TRUE.
Address of the desired elements to be returned.
Address of the NULL indicator information to be returned. If (elemind == NULL), then the NULL indicator information is not returned.
Maximum number of pointers to both elem and elemind.
Gets the address of the elements from the given position.
For index by integer collections, OCICollGetElemArray() gets the elements beginning at the given index, but loses the index information for each element in the process. Users are able to get the element data beginning at that index as an array, but cannot get the index for each element in the array. This behavior is similar to what happens for the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions.
Optionally, this function also returns the address of the element's NULL indicator information.
The OCI environment handle initialized in object mode.
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().
A collection item.
Returns TRUE if the collection item is locator-based, FALSE otherwise.
Returns TRUE in the result parameter if the collection item is locator-based; otherwise, it returns FALSE.
The OCI environment handle initialized in object mode.
Collection whose number of elements is returned. The coll parameter must point to a valid collection descriptor.
Returns the maximum number of elements that the given collection can hold. A value of zero indicates that the collection has no upper bound.
For collections that do not support negative indexes, the largest index number is also the maximum size of the collection. However, this is not true for index-by integer collections because some of the elements can have negative indexes, so the largest index numbered element is not the same as the maximum collection size.
The upper bound of the given collection.
The return value is always 0 (no upper bound) for index-by integer collections.
The OCI environment handle initialized in object mode.
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().
Collection whose number of elements is returned. Must point to a valid collection descriptor.
Current number of elements in the collection.
Returns the current number of elements in the given collection. For a nested table, this count is not decremented when elements are deleted. So, this count includes any holes created by deleting elements. A trim operation (OCICollTrim()) decrements 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
The OCICollSize() function returns an error if an error occurs during the loading of the collection into the object cache or if any of the input parameters is NULL.
The OCI environment handle initialized in object mode.
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().
Number of elements to trim.
Removes (frees) trim_num of elements from the end of the collection coll.
The OCI environment handle initialized in object mode.
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().
Collection that is scanned. For Oracle8i or later, valid collection types include varrays and nested tables.
Address to the allocated collection iterator to be returned by this function.
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 an "at beginning of collection" error is returned.
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.
The OCI environment handle initialized in object mode.
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().
The allocated collection iterator that is destroyed and set to NULL before returning.
Deletes an iterator that was previously created by a call to OCIIterCreate().
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.
sword OCIIterGetCurrent ( OCIEnv *env,
OCIError *err,
const OCIIter *itr,
void **elem,
void **elemind );
The OCI environment handle initialized in object mode.
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().
Iterator that points to the current element.
Address of the element pointed to by the iterator to be returned.
Address of the element's NULL indicator information to be returned; if (elem_ind == NULL) then the NULL indicator information is not returned.
Returns the pointer to the current iterator collection element and its corresponding NULL information.
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.
The OCI environment handle initialized in object mode.
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().
Collection that is scanned. For Oracle8i or later, valid collection types include varrays and nested tables.
Pointer to an allocated collection iterator.
Initializes at the given iterator to point to the beginning of the given collection. You can use this function to perform either of the following tasks:
Reset an iterator to point back to the beginning of the collection.
Reuse an allocated iterator to scan a different collection.
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.
sword OCIIterNext ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
void **elem,
void **elemind,
boolean *eoc);
The OCI environment handle initialized in object mode.
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().
Iterator that is updated to point to the next element.
Address of the next element; returned after the iterator is updated to point to it.
Address of the element's NULL indicator information; if (elem_ind == NULL), then the NULL indicator information is not returned.
TRUE if the iterator is at the end of the collection (that is, the next element does not exist); otherwise, FALSE.
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 before you execute this function, then calling this function sets the eoc flag to TRUE. The iterator is left unchanged in that case.
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.
sword OCIIterPrev ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
void **elem,
void **elemind,
boolean *boc );
The OCI environment handle initialized in object mode.
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().
Iterator that is updated to point to the previous element.
Address of the previous element; returned after the iterator is updated to point to it.
Address of the element's NULL indicator information; if (elemind == NULL), then the NULL indicator information is not returned.
TRUE if iterator is at the beginning of the collection (that is, the previous element does not exist); otherwise, FALSE.
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 before you execute this function, then calling this function sets boc to TRUE. The iterator is left unchanged in that case.
For index-by integer collections, the OCIIterCreate(), OCIIterDelete(), OCIIterGetCurrent(), OCIIterInit(), OCIIterNext(), and OCIIterPrev() functions all ignore the index for each element in the collection. That is, OCIIterGetCurrent() returns only the element value and not the index of the element.