Release 8.1.5
A67846-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Call Interface Programmer's Guide Release 8.1.5 A67846-01 |
|
This chapter describes the OCI datatype mapping and manipulation functions, which is Oracle's external C Language interface to Oracle predefined types. The following sections are included in this chapter:
Note: The functions described in this chapter are only available if you have installed the Oracle8i Enterprise Edition with the Objects Option.
This chapter describes the OCI datatype mapping and manipulation functions in detail.
See Also: For more information about the functions listed in this chapter, refer to Chapter 11, "Object-Relational Datatypes".
The entries for each function contain the following information:
A brief statement of the purpose of the function.
A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.
Detailed information about the function if available. This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.
A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described below:
A description of what value is returned by the function if the function returns something other than the standard return codes listed in Table 17-1, "Function Return Values".
A list of related functions.
The OCI datatype mapping and manipulation functions typically return one of the following values:
Function-specific return information follows the description of each function in this chapter. For more information about return codes and error handling, see the section "Error Handling".
Some functions return values other than those listed in Table 17-1. When using these function be sure to take into account that they return a value directly from the function call, rather than through an OUT parameter.
For a table showing the number of server roundtrips required for individual OCI datatype mapping and manipulation functions, refer to Appendix C, "OCI Function Server Roundtrips".
For more information about these functions, including some code examples, refer to Chapter 11, "Object-Relational Datatypes".
This section describes the Collection and Iterator functions.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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:
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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().
The element pointer returned by OCICollGetElem() is in a form such that it can not 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 via 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 via the target parameter.
Similarly, if the collection element was of type string (OCIString*), OCICollGetElem() returns pointer to string handle (i.e. OCIString**). If a new string is assigned, via 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()
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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.
Set the update status of a collection.
sword OCICollSetUpdateStatus ( OCIEnv *env, OCIError *err, OCIColl *coll, ub1 status );
The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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 collection whose update-status is to be set.
The status of the collection:
This function sets the status of the collection to indicate whether it should be marked updated (dirty) or should be marked as not dirty.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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 above example:
OCITableSize(...) // 'size' returned is equal to 4
A trim operation (OCICollTrim()) decrements the count by the number of trimmed elements. Continuing the above 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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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 release 8i, 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:
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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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 (i.e. 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. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
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 (elem_ind == NULL) then the NULL indicator will not be returned.
TRUE if iterator is at beginning of collection (i.e. 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.
OCIErrorGet(), OCIIterGetCurrent(), OCIIterNext()
This section describes the OCI Date functions.
Adds or subtracts days from a given date.
sword OCIDateAddDays ( OCIError *err, CONST OCIDate *date, sb4 num_days, OCIDate *result );
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 given date from which to add or subtract.
Number of days to be added or subtracted. A negative value is subtracted.
Result of adding days to, or subtracting days from, date.
This function returns and error if an invalid date is passed to it.
OCIErrorGet(), OCIDateAddMonths()
Adds or subtracts months from a given date.
sword OCIDateAddMonths ( OCIError *err, CONST OCIDate *date, sb4 num_months, OCIDate *result );
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 given date from which to add or subtract.
Number of months to be added or subtracted. A negative value is subtracted.
Result of adding days to, or subtracting days from, date.
If the input date is the last day of a month, then the appropriate adjustments are made to ensure that the output date is also the last day of the month. For example, Feb. 28 + 1 month = March 31, and November 303 months = August 31. Otherwise the result date has the same day component as date.
This function returns an error if invalid date is passed to it.
OCIErrorGet(), OCIDateAddDays()
Performs a date assignment.
sword OCIDateAssign ( OCIError *err, CONST OCIDate *from, OCIDate *to );
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().
Date to be assigned.
Target of assignment.
This function assigns a value from one OCIDate variable to another.
Checks if the given date is valid.
sword OCIDateCheck ( OCIError *err, CONST OCIDate *date, uword *valid );
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().
Date to be checked
Returns zero for a valid date. Otherwise, the OR'ed combination of all error bits specified as follows:
For example, if the date passed in was 2/0/1990 25:61:10 in (month/day/year hours:minutes:seconds format), the error returned would be:
OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID | OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE.
This function returns an error if date or valid pointer is NULL.
OCIErrorGet(), OCIDateCompare()
Compares two dates.
sword OCIDateCompare ( OCIError *err, CONST OCIDate *date1, CONST OCIDate *date2, sword *result );
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().
Dates to be compared.
Comparison result:
| Comparison result | Output in result parameter |
|---|---|
|
date1 < date2 |
-1 |
|
date1 = date2 |
0 |
|
date1 > date2 |
1 |
This function returns and error if an invalid date is passed to it.
Gets the number of days between two dates.
sword OCIDateDaysBetween ( OCIError *err, CONST OCIDate *date1, CONST OCIDate *date2, sb4 *num_days );
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().
Input date.
Input date.
Number of days between date1 and date2.
When the number of days between date1 and date2 is computed, the time is ignored.
This function returns an error if invalid date is passed to it.
Converts a character string to a date type according to the specified format.
sword OCIDateFromText ( OCIError *err, CONST text *date_str, ub4 d_str_length, CONST text *fmt, ub1 fmt_length, CONST text *lang_name, ub4 lang_length, OCIDate *date );
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().
Input string to be converted to Oracle date.
Size of the input string, if the length is -1 then date_str is treated as a NULL terminated string.
Conversion format. If fmt is a null pointer, then the string is expected to be in 'DD-MON-YY' format.
Length of the fmt parameter.
Language in which the names and abbreviations of days and months are specified. If lang_name is a NULL string, (text *) 0, then the default language of the session is used.
Length of the lang_name parameter.
Given string converted to date.
Refer to the TO_DATE conversion function described in Chapter 3 of the Oracle8i SQL Reference for a description of format and NLS arguments.
This function returns an error if it receives an invalid format, language, or input string.
OCIErrorGet(), OCIDateToText()
Get the year, month, and day stored in an Oracle date.
void OCIDateGetDate ( CONST OCIDate *date, sb2 *year, ub1 *month, ub1 *day );
Oracle date whose year, month, day data is retrieved.
Year value returned.
Month value returned.
Day value returned.
None.
OCIDateSetDate(), OCIDateGetTime()
Gets the time stored in an Oracle date.
void OCIDateGetTime ( CONST OCIDate *date, ub1 *hour, ub1 *min, ub1 *sec );
Oracle date whose time data is retrieved.
Hour value returned.
Minute value returned.
Second value returned.
Returns the time information returned in the form: hour, minute and seconds.
OCIDateSetTime(), OCIDateGetDate()
Gets the date of the last day of the month in a specified date.
sword OCIDateLastDay ( OCIError *err, CONST OCIDate *date, OCIDate *last_day );
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().
Input date.
Last day of the month in date.
This function returns an error if invalid date is passed to it.
OCIErrorGet(), OCIDateGetDate()
Gets the date of next day of the week, after a given date.
sword OCIDateNextDay ( OCIError *err, CONST OCIDate *date, CONST text *day, ub4 day_length, OCIDate *next_day );
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().
Returned date should be later than this date.
First day of week named by this is returned.
Length in bytes of string day.
First day of the week named by day later than date.
Returns the date of the first day of the week named by day that is later than date.
Get the date of the next Monday after April 18, 1996 (a Thursday).
OCIDateNextDay(&err, '18-APR-96', 'MONDAY', strlen('MONDAY'), &next_day)
OCIDateNextDay() returns '22-APR-96'.
This function returns and error if an invalid date or day is passed to it.
OCIErrorGet(), OCIDateGetDate()
Set the values in an Oracle date.
void OCIDateSetDate ( OCIDate *date, sb2 year, ub1 month, ub1 day );
Oracle date whose time data is set.
Year value to be set.
Month value to be set.
Day value to be set.
None.
Sets the time information in an Oracle date.
void OCIDateSetTime ( OCIDate *date, ub1 hour, ub1 min, ub1 sec );
Oracle date whose time data is set.
Hour value to be set.
Minute value to be set.
Second value to be set.
None.
Gets the current system date and time.
sword OCIDateSysDate ( OCIError *err, OCIDate *sys_date );
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().
Current system date and time.
None.
Converts a date type to a character string.
sword OCIDateToText ( OCIError *err, CONST OCIDate *date, CONST text *fmt, ub1 fmt_length, CONST text *lang_name, ub4 lang_length, ub4 *buf_size, text *buf );
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().
Oracle date to be converted.
Conversion format, if NULL string pointer, (text *) 0, then the date is converted to a character string in the default date format, DD-MON-YY.
Length of the fmt parameter.
Specifies the language in which names and abbreviations of months and days are returned; default language of session is used if lang_name is NULL ((text *) 0).
Length of the lang_name parameter.
Buffer into which the converted string is placed.