Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
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 |
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
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.
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
Purpose
Assigns (deep-copies) one collection to another.
Syntax
sword OCICollAssign ( OCIEnv *env, OCIError *err, CONST OCIColl *rhs, OCIColl *lhs );
Parameters
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.
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()
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
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.
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()
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
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.
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 |
|
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
.
Related Functions
OCIErrorGet(), OCICollAssignElem()
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
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
.
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()
Purpose
Indicates whether a collection is locator-based or not.
Syntax
sword OCICollIsLocator ( OCIEnv *env, OCIError *err, CONST OCIColl *coll, boolean *result );
Parameters
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.
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
Purpose
Gets the maximum size in number of elements of the given collection.
Syntax
sb4 OCICollMax ( OCIEnv *env, CONST OCIColl *coll );
Parameters
The OCI environment handle initialized in object mode.
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
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
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.
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
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
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
.
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
Purpose
Creates an iterator to scan the elements or the collection.
Syntax
sword OCIIterCreate ( OCIEnv *env, OCIError *err, CONST OCIColl *coll, OCIIter **itr );
Parameters
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.
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()
Purpose
Deletes a collection iterator.
Syntax
sword OCIIterDelete ( OCIEnv *env, OCIError *err, OCIIter **itr );
Parameters
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.
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()
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
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.
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()
Purpose
Initializes an iterator to scan a collection.
Syntax
sword OCIIterInit ( OCIEnv *env, OCIError *err, CONST OCIColl *coll, OCIIter *itr );
Parameters
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.
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
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
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.
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()
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
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
.
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