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
.