This section describes the Collection and Iterator functions.
Table 18-3 Collection and Iterator Functions
| Function/Page | Purpose |
|---|---|
|
Collection appends element |
|
|
Assigns collection |
|
|
Collection assigns element |
|
|
Gets pointer to an element |
|
|
Gets an array of elements from a collection. |
|
|
Indicates whether a collection is locator-based or not |
|
|
Returns maximum number of elements in collection |
|
|
Gets current size of collection (in number of elements) |
|
|
Trims elements from the collection |
|
|
Creates iterator to scan the varray elements |
|
|
Deletes iterator |
|
|
Gets current collection element |
|
|
Initializes iterator to scan the given collection |
|
|
Gets next collection element |
|
|
Gets previous collection element |
Appends an element to the end of a collection.
sword OCICollAppend ( OCIEnv *env,
OCIError *err,
CONST dvoid *elem,
CONST dvoid *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 which is 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 will be set to non-NULL.
Updated collection.
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.
Assigns (deep-copies) one collection to another.
sword OCICollAssign ( OCIEnv *env,
OCIError *err,
CONST OCIColl *rhs,
OCIColl *lhs );
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 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
OCIErrorGet(), OCICollAssignElem()
Assigns the given element value elem to the element at coll[index].
sword OCICollAssignElem ( OCIEnv *env,
OCIError *err,
sb4 index,
CONST dvoid *elem,
CONST dvoid *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 whose is assigned to.
Element which is assigned from (source element).
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.
Collection to be updated.
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.
OCIErrorGet(), OCICollAssign()
Gets a pointer to the element at the given index.
sword OCICollGetElem ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
sb4 index,
boolean *exists,
dvoid **elem,
dvoid **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 is 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 desired element is returned.
Address of the NULL indicator information is returned. If (elemind == NULL), then the NULL indicator information will not be 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.
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 |
|
|
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 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.
OCIErrorGet(), OCICollAssignElem()
Gets an array of elements from a collection given a starting index.
sword OCICollGetElemArray ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
sb4 index,
boolean *exists,
dvoid **elem,
dvoid **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, else it is set to TRUE.
Address of the desired elements to be returned.
[optional] Address of the NULL indicators information to be returned. If (elemind == NULL) then the NULL indicator information will not be returned.
Maximum number of pointers to both elem and elemind.
Gets the address of the elements from the given position. Optionally, this function also returns the address of the element's NULL indicator information.
OCIErrorGet(), OCICollGetElem()
Indicates whether a collection is locator-based or not.
sword OCICollIsLocator ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
boolean *result );
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.
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.
Gets the maximum size in number of elements of the given collection.
sb4 OCICollMax ( OCIEnv *env,
CONST OCIColl *coll );
The OCI environment handle initialized in object mode.
Collection whose number of elements is returned. coll 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.
The upper bound of the given collection.
Gets the current size in number of elements of the given collection.
sword OCICollSize ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll
sb4 *size );
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 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.
Trims the given number of elements from the end of the collection.
sword OCICollTrim ( OCIEnv *env,
OCIError *err,
sb4 trim_num,
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().
Number of elements to trim.
This function removes (frees) trim_num elements from the end of coll.
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.
Creates an iterator to scan the elements or the collection.
sword OCIIterCreate ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
OCIIter **itr );
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 which will be scanned. For this release, valid collection types include varrays and nested tables.
Address to the allocated collection iterator is 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 a "at beginning of collection" error is returned.
This function returns an error if any of the input parameters is NULL.
OCIErrorGet(), OCIIterDelete()
Deletes a collection iterator.
sword OCIIterDelete ( OCIEnv *env,
OCIError *err,
OCIIter **itr );
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 which is destroyed and set to NULL prior to returning.
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.
OCIErrorGet(), OCIIterCreate()
Gets a pointer to the current iterator collection element.
sword OCIIterGetCurrent ( OCIEnv *env,
OCIError *err,
CONST OCIIter *itr,
dvoid **elem,
dvoid **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 which points to the current element.
Address of the element pointed by the iterator is returned.
Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.
Returns pointer to the current iterator collection element and its corresponding NULL information. This function returns an error if any input parameter is NULL.
OCIErrorGet(), OCIIterNext(), OCIIterPrev()
Initializes an iterator to scan a collection.
sword OCIIterInit ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
OCIIter *itr );
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 which will be scanned. For Oracle8i or later, valid collection types include varrays and nested tables.
Pointer to an allocated collection iterator.
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.
Gets a pointer to the next iterator collection element.
sword OCIIterNext ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
dvoid **elem,
dvoid **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 is updated to point to the next element.
After updating the iterator to point to the next element, address of the element is returned.
Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.
TRUE if iterator is at End of Collection (that is, 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 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.
OCIErrorGet(), OCIIterGetCurrent(), OCIIterPrev()
Gets a pointer to the previous iterator collection element.
sword OCIIterPrev ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
dvoid **elem,
dvoid **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 which 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; if (elemind == NULL) then the NULL indicator will not be returned.
TRUE if iterator is at beginning of collection (that is, 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 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.