Release 8.0
A58234-01
 Library |
 Product |
 Contents |
 Index |
| Oracle Call Interface Programmer's Guide, Volumes 1 & 2 Release 8.0 A58234-01 |
|
This chapter describes the OCI datatype mapping and manipulation functions, which is Oracle's external C Language interface to Oracle8 predefined types.
The following sections are included in this chapter:
Note: The functions described in this chapter are only available if you have purchased the Oracle8 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 9, "Object-Relational Datatypes".
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" on page 2-25.
Some functions return values other than those listed in Table 15-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 E, "OCI Function Server Roundtrips".
For more information about these functions, including some code examples, refer to Chapter 9, "Object-Relational Datatypes".
This section is intended to help you figure out which function you need to use in a given situation.
This chapter describes the OCI datatype mapping and manipulation functions. 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 the table above.
A list of related functions.
Appends an element to 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 OCIInitialize() in Chapter 13 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.
Appends the given element to the end of the given collection.
Appending an element is equivalent to:
Note that the pointer to the given element elem will not be saved by this function. So 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 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 OCIInitialize() in Chapter 13 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.
This function returns an error if:
Assign an element to a collection
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 OCIInitialize() in Chapter 13 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.
Assigns the given element value elem to the element at coll[index].
If the collection is of type nested table, the element at the given index may not exist (i.e. may have been deleted). In this case, the given element is inserted at index index. Otherwise, the element at index 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.
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 OCIInitialize() in Chapter 13 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 via 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 (i.e., 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 (i.e. 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 shown below:
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 shown below:
sword OCINumberAssign(OCIError *err, CONST OCINumber *from,
OCINumber *to);
This function returns an error if any of the input parameters is NULL.
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 OCIInitialize() in Chapter 13 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
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 OCIInitialize() in Chapter 13 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 OCIInitialize() in Chapter 13 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.
Trim the collection by the given number of elements. 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.
This function returns an error if trim_num is greater than the current size of the collection.
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().
This function adds or subtracts num_days from date.
Number of days to be added or subtracted (a negative value will be subtracted).
Result of adding days to, or subtracting days from, date.
Adds or subtracts num_days from the date date.
This function returns and error if an invalid date is passed to it.
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().
This function adds or subtracts num_months from date.
Number of months to be added or subtracted (a negative value is subtracted).
Result of adding days to, or subtracting days from, date.
Adds or subtracts num_months from the date 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.
Performs 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 ORed combination of all error bits specified below:
Macro name Bit number Error ---------- ---------- ----------------------------- OCI_DATE_INVALID_DAY 0x1 Bad day OCI_DATE_DAY_BELOW_VALID 0x2 Bad day low/high bit (1=low) OCI_DATE_INVALID_MONTH 0x4 Bad month OCI_DATE_MONTH_BELOW_VALID 0x8 Bad month low/high bit (1=low) OCI_DATE_INVALID_YEAR 0x10 Bad year OCI_DATE_YEAR_BELOW_VALID 0x20 Bad year low/high bit (1=low) OCI_DATE_INVALID_HOUR 0x40 Bad hour OCI_DATE_HOUR_BELOW_VALID 0x80 Bad hour low/high bit (1=low) OCI_DATE_INVALID_MINUTE 0x100 Bad minute OCI_DATE_MINUTE_BELOW_VALID 0x200 Bad minute Low/high bit (1=low) OCI_DATE_INVALID_SECOND 0x400 Bad second OCI_DATE_SECOND_BELOW_VALID 0x800 Bad second Low/high bit (1=low) OCI_DATE_DAY_MISSING_FROM_1582 0x1000 Day is one of those "missing" from 1582 OCI_DATE_YEAR_ZERO 0x2000 Year may not equal zero OCI_DATE_INVALID_FORMAT 0x8000 Bad date format input
So, 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
Checks if the given date is valid.
This function returns an error if date or valid pointer is NULL.
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 |
Compares two dates.
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.
Returns the number of days between date1 and date2. The time is ignored in this computation.
This function returns an error if invalid date is passed to it.
Converts a character string to a date type.
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.
Converts the given string to Oracle date according to the specified format.
Refer to the TO_DATE conversion function described in Chapter 3 of the Oracle8 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.
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.
Returns year, month, day information stored in the given date.
Get 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 time information stored in the given date. The time information returned is: hour, minute and seconds.
Gets the date of the last day of the month.
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.
Returns the date of the last day of the month specified in date.
This function returns an error if invalid date is passed to it.
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 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.
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.
Sets the date with the given information.
Set 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.
Sets the date with the given time information.
Gets 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.
Returns the current system date and time.
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.
Converts the given date to a string according to the specified format. The converted NULL-terminated date string is stored in buf.
Refer to the TO_DATE conversion function described in Chapter 3 of the Oracle8 SQL Reference for a description of format and NLS arguments.
This function returns an error if the buffer is too small, or if the function is passed an invalid format or unknown language. Overflow also causes an error. For example, converting a value of 10 into format '9' causes an error.
Converts a date from one time zone to another.
sword OCIDateZoneToZone ( OCIError *err, CONST OCIDate *date1, CONST text *zon1, ub4 zon1_length, CONST text *zon2, ub4 zon2_length, OCIDate *date2 );
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 convert.
Zone of input date.
Length in bytes of zon1.
Zone to be converted to.
Length in bytes of zon2.
Converted date (in zon2).
Converts date from one time zone to another. Given date date1 in time zone zon1, returns date date2 in time zone zon2.
For a list of valid zone strings, refer to the description of the "NEW_TIME" function in Chapter 3 of the Oracle8 SQL Reference. Examples of valid zone strings include:
This function returns and error if an invalid date or time zone is passed to it.
Creates an iterator to scan collection elements.
sword OCIIterCreate ( OCIEnv *env, OCIError *err, CONST OCIColl *coll, OCIIter **itr );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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 8.0, valid collection types include varrays and nested tables.
Address to the allocated collection iterator is returned by this function.
Creates an iterator to scan the elements of the collection. 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 "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 OCIInitialize() in Chapter 13 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 OCIInitialize() in Chapter 13 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.
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 OCIInitialize() in Chapter 13 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 8.0, 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 OCIInitialize() in Chapter 13 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.
Returns a pointer to the next iterator collection element and its corresponding NULL information. 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.
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 OCIInitialize() in Chapter 13 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.
Returns 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.
Computes the absolute value of an Oracle number.
sword OCINumberAbs ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Input number.
The absolute value of the input number.
Computes the absolute value of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Adds two Oracle numbers together.
sword OCINumberAdd ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
Numbers to be added.
Result of adding number1 to number2.
Adds number1 to number2 and returns result in result.
This function returns an error if any of the number arguments is NULL.
Takes the arc cosine of an Oracle number.
sword OCINumberArcCos ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the arc cosine.
Result of the arc cosine in radians.
Takes the arc cosine in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL, or if number < -1 or if number > 1.
Takes the arc sine of an Oracle number.
sword OCINumberArcSin ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the arc sine.
Result of the arc sine in radians.
Takes the arc sine in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL, or if number < -1 or if number > 1.
Takes the arc tangent of an Oracle number.
sword OCINumberArcTan ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the arc tangent.
Result of the arc tangent in radians.
Takes the arc tangent in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Takes the arc tangent of two Oracle numbers.
sword OCINumberArcTan2 ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
Argument 1 of the arc tangent.
Argument 2 of the arc tangent.
Result of the arc tangent in radians.
Takes the atan2(number1, number2).
This function returns an error if any of the number arguments is NULL, or if number2 = 0.
Assigns one Oracle number to another Oracle number.
sword OCINumberAssign ( OCIError *err, CONST OCINumber *from, OCINumber *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().
Number to be assigned.
Number copied into.
Assigns number from to to.
This function returns an error if any of the number arguments is NULL.
Computes the ceiling value of an Oracle number.
sword OCINumberCeil ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Input number.
Output which will contain the ceiling value of the input number.
Computes the ceiling value of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Compares two Oracle numbers.
sword OCINumberCmp ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, 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().
Numbers to compare.
Comparison result:
| Comparison result | Output in result parameter |
|---|---|
|
number1 < number2 |
negative |
|
number1 = number2 |
0 |
|
number1 > number2 |
positive |
Compares two Oracle numbers.
This function returns an error if any of the number arguments is NULL.
Takes the cosine of an Oracle number.
sword OCINumberCos ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the cosine in radians.
Result of the cosine.
Takes the cosine in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Divides two Oracle numbers.
sword OCINumberDiv ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
Pointer to the numerator.
Pointer to the denominator.
Division result.
Divides number1 by number2 and returns result in result.
This function returns an error if:
Raises e to the specified Oracle number power.
sword OCINumberExp ( OCIError *err, CONST OCINumber *number, OCINumber *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().
This function raises e to this Oracle number power.
Output of exponentiation.
Raises e to a given power, specified by an Oracle number.
This function returns an error if any of the number arguments is NULL.
Computes the floor value of an Oracle number.
sword OCINumberFloor ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Input number.
The floor value of the input number.
Computes the floor value of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Converts integer to Oracle number.
sword OCINumberFromInt ( OCIError *err, CONST dvoid *inum, uword inum_length, uword inum_s_flag, OCINumber *number );
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 integer to convert.
Size of the integer.
Flag that designates the sign of the integer, as follows:
::
| Predefined Constant | Use |
|---|---|
|
OCI_NUMBER_UNSIGNED |
Unsigned values |
|
OCI_NUMBER_SIGNED |
Signed values |
Given integer converted to Oracle number.
This is a native type conversion function. It converts any Oracle standard machine-native integer type (e.g. ub4, sb2) to an Oracle number.
This function returns an error if the number is too big to fit into an Oracle number, if number or inum is NULL, or if an invalid sign flag value is passed in inum_s_flag.
Converts a real (floating-point) type to an Oracle number.
sword OCINumberFromReal ( OCIError *err, CONST dvoid *rnum, uword rnum_length, OCINumber *number );
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 floating point number to convert.
The size of the desired result. Will be equal to sizeof({float | double | long double}).
Given float converted to Oracle number.
This is a native type conversion function. It converts a machine-native floating point type to an Oracle number.
This function returns an error if number or rnum is NULL, or if rnum_length equals zero.
Converts character string to Oracle number.
sword OCINumberFromText ( OCIError *err, CONST text *str, ub4 str_length, CONST text *fmt, ub4 fmt_length, CONST text *nls_params, ub4 nls_p_length, OCINumber *number );
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 convert to Oracle number.
Size of the input string.
Conversion format.
Length of the fmt parameter.
NLS format specification, if NULL string ("") then the default parameters for the session is used.
Length of the nls_params parameter.
Given string converted to number.
Converts the given string to a number according to the specified format. Refer to the TO_NUMBER conversion function described in the Oracle8 SQL Reference for a description of format and NLS parameters.
This function returns an error if there is an invalid format, an invalid NLS format, or an invalid input string, if number or str is NULL, or if str_length is zero.
Takes the hyperbolic cosine of an Oracle number.
sword OCINumberHypCos ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the cosine hyperbolic.
Result of the cosine hyperbolic.
Takes the hyperbolic cosine of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Takes the hyperbolic sine of an Oracle number.
sword OCINumberHypSin ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the sine hyperbolic.
Result of the sine hyperbolic.
Takes the hyperbolic sine of an Oracle number.
This function returns an error if any of the number arguments is NULL.
OCIErrorGet(), OCINumberHypCos(), OCINumberHypTan()
Takes the hyperbolic tangent of an Oracle number.
sword OCINumberHypTan ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the tangent hyperbolic.
Result of the tangent hyperbolic.
Takes the hyperbolic tangent of an Oracle number.
This function returns an error if any of the number arguments is NULL.
OCIErrorGet(), OCINumberHypCos(), OCINumberHypSin()
Raises a given base to a given integer power.
sword OCINumberIntPower ( OCIError *err, CONST OCINumber *base, CONST sword exp, OCINumber *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().
Base of the exponentiation.
Exponent to which the base is raised.
Output of exponentiation.
Raises an arbitrary base to an arbitrary integer power.
This function returns an error if any of the number arguments is NULL.
Tests if the given number is equal to zero.
sword OCINumberIsZero ( OCIError *err, CONST OCINumber *number, boolean *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().
Number to compare.
Set to TRUE if equal to zero; otherwise, set to FALSE.
Tests if the given number is equal to zero.
This function returns an error if any of the number arguments is NULL.
Takes the natural logarithm (base e) of an Oracle number.
sword OCINumberLn ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Logarithm of this number is computed.
Logarithm result.
Takes the logarithm (base e) of the given Oracle number.
This function returns an error if any of the number arguments is NULL, or if numberI is less than or equal to zero.
Takes the logarithm, to any base, of an Oracle number.
sword OCINumberLog ( OCIError *err, CONST OCINumber *base, CONST OCINumber *number, OCINumber *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().
Base of the logarithm.
Operand.
Logarithm result.
Takes the logarithm with the specified base of an Oracle number.
This function returns an error if:
Gets the modulus (remainder) of the division of two Oracle numbers.
sword OCINumberMod ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
Pointer to the numerator.
Pointer to the denominator.
Remainder of the result.
Finds the remainder of the division of two Oracle numbers.
This function returns an error if number1 or number2 is NULL, or if there is a divide-by-zero error.
Multiplies two Oracle numbers
sword OCINumberMul ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
Number to multiply.
Number to multiply.
Multiplication result.
Multiplies number1 with number2 and returns result in result.
This function returns an error if any of the number arguments is NULL.
Negates an Oracle number.
sword OCINumberNeg ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Number to negate.
Contains negated value of number.
Negates an Oracle number.
This function returns an error if any of the number arguments is NULL.
Raises a given base to a given exponent.
sword OCINumberPower ( OCIError *err, CONST OCINumber *base, CONST OCINumber *number, OCINumber *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().
Base of the exponentiation.
Exponent to which the base is to be raised.
Output of exponentiation.
Raises an arbitrary base to an arbitrary power.
This function returns an error if any of the number arguments is NULL.
Rounds an Oracle number to a specified decimal place.
sword OCINumberRound ( OCIError *err, CONST OCINumber *number, sword decplace, OCINumber *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().
Number to round.
Number of decimal digits to the right of the decimal point to round to. Negative values are allowed.
Output of rounding.
Rounds an Oracle number to a specified decimal place.
This function returns an error if any of the number arguments is NULL.
Initializes an Oracle number to zero
void OCINumberSetZero ( OCIError *err OCINumber *num );
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 to initialize to zero value.
Initializes the given number to value 0.
Gets sign of an Oracle number.
sword OCINumberSign ( OCIError *err, CONST OCINumber *number, 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().
Number whose sign is returned.
Possible values:
| Value of number | Output in result parameter |
|---|---|
|
number < 0 |
-1 |
|
number == 0 |
0 |
|
number > 0 |
1 |
Obtains the sign of an Oracle number.
This function returns an error if number or result is NULL.
Takes the sine of an Oracle number.
sword OCINumberSin ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the sine in radians.
Result of the sine.
Takes the sine in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Computes the square root of an Oracle number.
sword OCINumberSqrt ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Input number.
Output which will contain the square root of the input number.
Computes the square root of an Oracle number.
This function returns an error if number is NULL or number is negative.
Subtract two Oracle numbers.
sword OCINumberSub ( OCIError *err, CONST OCINumber *number1, CONST OCINumber *number2, OCINumber *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().
This function subtracts number2 from number1.
Subtraction result.
Subtracts number2 from number1 and returns result in result.
This function returns an error if any of the number arguments is NULL.
Takes the tangent of an Oracle number.
sword OCINumberTan ( OCIError *err, CONST OCINumber *number, OCINumber *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().
Argument of the tangent in radians.
Result of the tangent.
Takes the tangent in radians of an Oracle number.
This function returns an error if any of the number arguments is NULL.
Converts an Oracle number type to integer.
sword OCINumberToInt ( OCIError *err, CONST OCINumber *number, uword rsl_length, uword rsl_flag, dvoid *rsl );
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 to convert.
Size of the desired result.
Flag denoting the desired sign of the output; set as follows:
| Predefined Constant | Use |
|---|---|
|
OCI_NUMBER_UNSIGNED |
Unsigned values |
|
OCI_NUMBER_SIGNED |
Signed values |
Pointer to space for the result.
This is a native type conversion function. It converts the given Oracle number into an integer of the form xbn (e.g. ub2, ub4, sb2, etc.)
This function returns an error if number or rsl is NULL, if number is too big (overflow) or too small (underflow), or if an invalid sign flag value is passed in rsl_flag.
Converts an Oracle number type to Real.
sword OCINumberToReal ( OCIError *err, CONST OCINumber *number, uword rsl_length, dvoid *rsl );
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 to convert.
The size of the desired result. This will be equal to sizeof({ float | double | long double}).
Pointer to space for storing the result.
This is a native type conversion function. It converts an Oracle number into a machine-native real type. This function only converts numbers up to LDBL_DIG, DBL_DIG, or FLT_DIG digits of precision and removes trailing zeroes. The above constants are defined in float.h.
This function returns an error if number or rsl is NULL, or if rsl_length = 0.
OCIErrorGet(), OCINumberFromReal()
Converts an Oracle number to a character string.
sword OCINumberToText ( OCIError *err, CONST OCINumber *number, CONST text *fmt, ub4 fmt_length, CONST text *nls_params, ub4 nls_p_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 number to convert.
Conversion format.
Length of the fmt parameter.
NLS format specification. If NULL string (i.e., (text *)0 ), then the default parameters for the session is used.
Length of the nls_params parameter.
Size of the buffer.
Buffer into which the converted string is placed.
Converts a given number to a character string according to a specified format. Refer to the TO_NUMBER conversion function described in the Oracle8 SQL Reference for a description of format and NLS parameters.
The converted number string is stored in buf, up to a maximum of buf_size bytes. This function returns an error if:
Truncates an Oracle number at a specified decimal place.
sword OCINumberTrunc ( OCIError *err, CONST OCINumber *number, sword decplace, OCINumber *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().
Input number.
Number of decimal digits to the right of the decimal point at which to truncate. Negative values are allowed.
Output of truncation.
Truncates an Oracle number at a specified decimal place.
This function returns an error if any of the number arguments is NULL.
Gets allocated size of raw memory in bytes.
sword OCIRawAllocSize ( OCIEnv *env, OCIError *err, CONST OCIRaw *raw, ub4 *allocsize );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
Raw data whose allocated size in bytes is returned. This must be a non-NULL pointer.
The allocated size of raw memory in bytes is returned.
Retrieves the allocated size of the raw memory in bytes. The allocated size is greater than or equal to the actual raw size.
Assigns raw bytes of type ub1* to Oracle OCIRaw* datatype.
sword OCIRawAssignBytes ( OCIEnv *env, OCIError *err, CONST ub1 *rhs, ub4 rhs_len, OCIRaw **lhs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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) of the assignment, of datatype ub1.
Length of the rhs raw bytes.
Left-hand side (target) of the assignment OCIRaw data.
Assigns rhs raw bytes to lhs raw datatype. The lhs raw may be resized depending upon the size of the rhs. The raw bytes assigned are of type ub1.
Assign one Oracle raw datatype to another Oracle raw datatype.
sword OCIRawAssignRaw ( OCIEnv *env, OCIError *err, CONST OCIRaw *rhs, OCIRaw **lhs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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) of the assignment; OCIRaw data.
Left-hand side (target) of the assignment; OCIRaw data.
Assigns rhs raw to lhs raw. The lhs raw may be resized depending upon the size of the rhs.
Gets pointer to raw data.
ub1 *OCIRawPtr ( OCIEnv *env, CONST OCIRaw *raw );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
Pointer to the data of a given raw is returned.
pointer to the data of a given raw.
Returns a pointer to the data of a given raw.
Resizes the memory of a given variable-length raw.
sword OCIRawResize ( OCIEnv *env, OCIError *err, ub2 new_size, OCIRaw **raw );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
New size of the raw data in bytes.
Variable-length raw pointer; the raw is resized to new_size.
This function resizes the memory of the given variable-length raw in the object cache. The previous contents of the raw are not preserved. This function may allocate the raw in a new memory region in which case the original memory occupied by the given raw will be freed. If the input raw is NULL (raw == NULL), then this function will allocate memory for the raw data.
If the new_size is 0, then this function frees the memory occupied by raw and a NULL pointer value is returned.
Gets the size of a given raw.
ub4 OCIRawSize ( OCIEnv *env, CONST OCIRaw *raw );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
Raw whose size is returned.
size of the raw in bytes.
Returns the size of the given raw in bytes.
Assigns one REF to another, such that both reference the same object.
sword OCIRefAssign ( OCIEnv *env, OCIError *err, CONST OCIRef *source, OCIRef **target );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
REF to copy from.
REF to copy to.
Copies source REF to target REF; both then reference the same object. If the target REF pointer is NULL (i.e. *target == NULL), then OCIRefAssign() will allocate memory for the target REF in the OCI object cache prior to the copy.
Clears or nullifies a REF
void OCIRefClear ( OCIEnv *env, OCIRef *ref );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
REF to clear.
Clears or nullifies the given REF. A REF is considered to be a NULL REF if it no longer points to an object. Logically, a NULL REF is a dangling REF.
Note that a null ref is still a valid SQL value and is not SQL-ly null. It can be used as a valid non-null constant ref value for NOT NULL column or attribute of a row in a table.
If a NULL pointer value is passed as a REF, then this function is a no-op.
Converts the given hexadecimal string into a REF.
sword OCIRefFromHex ( OCIEnv *env, OCIError *err, CONST OCISvcCtx *svc, CONST text *hex, ub4 length, OCIRef **ref );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
OCI service context handle; if the resulting ref is initialized with this service context.
Hexadecimal text string (previously output by OCIRefToHex() ) to convert into a REF.
Length of the hexadecimal text string.
The REF into which the hexadecimal string is converted. If *ref is NULL on input, then space for the REF is allocated in the object cache, otherwise the memory occupied by the given REF is re-used.
Converts the given hexadecimal text string into a REF. This function ensures that the resulting REF is well formed. It does not ensure that the object pointed to by the resulting REF exists or not.
Returns the size of the hex representation of a REF.
ub4 OCIRefHexSize ( OCIEnv *env, CONST OCIRef *ref );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
REF whose size in hexadecimal representation in bytes is returned.
The size of the hexadecimal representation of the REF.
Returns the size of the buffer in bytes required for the hexadecimal representation of the ref. A buffer of at least this size must be passed to the ref-to-hex (OCIRefToHex()) conversion function.
Compares two REFs to determine if they are equal.
boolean OCIRefIsEqual ( OCIEnv *env, CONST OCIRef *x, CONST OCIRef *y );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
REF to compare.
REF to compare.
TRUE if the two REFs are equal
FALSE if the two REFs are not equal, or x is NULL, or y is NULL
Compares the given REFs for equality.
Two REFs are equal if and only if they are both referencing the same object, whether persistent or transient.
Tests if a REF is NULL
boolean OCIRefIsNull ( OCIEnv *env, CONST OCIRef *ref );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
REF to test for NULL.
TRUE if the given REF is NULL.
FALSE if the given REF is not NULL.
Returns TRUE if the given REF is NULL; otherwise, returns FALSE.
A REF is NULL if and only if:
Note: A REF is a dangling REF if the object that it points to does not exist.
Converts a REF to a hexadecimal string
sword OCIRefToHex ( OCIEnv *env, OCIError *err, CONST OCIRef *ref, text *hex, ub4 *hex_length );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
REF to be converted into a hexadecimal string; if ref is a NULL REF (i.e. OCIRefIsNull(ref) == TRUE) then zero hex_length value is returned.
Buffer that is large enough to contain the resulting hexadecimal string; the contents of the string is opaque to the caller.
On input specifies the size of the hex buffer on output specifies the actual size of the hexadecimal string being returned in hex.
Converts the given REF into a hexadecimal string, and returns the length of the string. The resulting string is opaque to the caller.
This function returns an error if the given buffer is not big enough to hold the resulting string.
OCIErrorGet(), OCIRefHexSize(), OCIRefIsNull()
Gets allocated size of string memory in bytes.
sword OCIStringAllocSize ( OCIEnv *env, CONST OCIString *vs, ub4 *allocsize );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
String whose allocated size in bytes is returned. vs must be a non-NULL pointer.
The allocated size of string memory in bytes is returned.
Returns the allocated size of the string memory in bytes. The allocated size is greater than or equal to the actual string size.
Assigns one string to another string.
sword OCIStringAssign ( OCIEnv *env, OCIError *err, CONST OCIString *rhs, OCIString **lhs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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) of the assignment.
Left-hand side (target) of the assignment.
Assigns rhs string to lhs string. The lhs string may be resized depending upon the size of the rhs. The assigned string is NULL-terminated.
The length field will not include the extra byte needed for null termination.
This function returns an error if the assignment operation runs out of space.
Assigns the source text string to the target string.
sword OCIStringAssignText ( OCIEnv *env, OCIError *err, CONST text *rhs, ub2 rhs_len, OCIString **lhs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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) of the assignment, a text string.
Length of the rhs string.
Left-hand side (target) of the assignment.
Assigns rhs string to lhs string. The lhs string may be resized depending upon the size of the rhs. The assigned string is NULL-terminated.
The length field will not include the extra byte needed for null termination.
Gets a pointer to a given string.
text *OCIStringPtr ( OCIEnv *env, CONST OCIString *vs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
Pointer to the text of this string is returned.
pointer to the text of the string.
Returns the pointer to the text of the given string.
Resizes the memory of a given string.
sword OCIStringResize ( OCIEnv *env, OCIError *err, ub4 new_size, OCIString **str );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
New memory size of the string in bytes. new_size must include space for the NULL character ('\0') as string terminator.
Allocated memory for the string which is freed from the OCI object cache.
This function resizes the memory of the given variable-length string in the object cache. Contents of the string are not preserved. This function may allocate the string in a new memory region, in which case the original memory occupied by the given string is freed. If str is NULL, this function allocates memory for the string. If new_size is 0, this function frees the memory occupied by str and a NULL pointer value is returned.
Gets string size.
ub4 OCIStringSize ( OCIEnv *env, CONST OCIString *vs );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 for more information.
String whose size is returned.
size of the string in bytes.
Returns the size of the given string in bytes. The returned size does not include an extra byte for NULL termination.
Deletes the element at the specified index.
sword OCITableDelete ( OCIEnv *env, OCIError *err, sb4 index, OCITable *tbl );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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 which must be deleted.
Table whose element is deleted.
Deletes the element at the given index.
Note: The position ordinals of the remaining elements of the table are not changed by OCITableDelete(). The delete operation creates "holes" in the table.
This function returns an error if the element at the given index has already been deleted or if the given index is not valid for the given table. It is also an error if any input parameter is NULL.
Tests whether an element exists at the given index.
sword OCITableExists ( OCIEnv *env, OCIError *err, CONST OCITable *tbl, sb4 index, boolean *exists );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
Table in which the given index is checked.
Index of the element which is checked for existence.
Set to TRUE if element at given index exists; otherwise, it is set to FALSE.
Tests whether an element exists at the given index, index.
This function returns an error if any input parameter is NULL.
Returns the first index of an existing element in a given table.
sword OCITableFirst ( OCIEnv *env, OCIError *err, CONST OCITable *tbl, sb4 *index );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
Table to scan.
First index of the element which exists in the given table is returned.
Returns the index of the first element which exists in a given table.
For example, if OCITableDelete() deleted the first 5 elements of a table, OCITableFirst() returns 6.
See OCITableDelete() for information regarding non-data "holes" in tables.
This function returns an error if the table is empty.
OCIErrorGet(), OCITableDelete()
Returns the index of the last existing element of a table.
sword OCITableLast ( OCIEnv *env, OCIError *err, CONST OCITable *tbl, sb4 *index );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
Table to scan.
Index of the last existing element in the table.
Returns the index of the last existing element in the given table.
This function returns an error if the table is empty.
Returns the index of the next existing element of a table.
sword OCITableNext ( OCIEnv *env, OCIError *err, sb4 index, CONST OCITable *tbl, sb4 *next_index boolean *exists );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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 for starting point of scan.
Table to scan.
Index of the next existing element after tbl(index).
FALSE if no next index is available, else TRUE.
Returns the smallest position j, greater than index, such that exists(j) is TRUE
See Also: Refer to the description of OCIStringAllocSize() on page 15-109, regarding the existence of non-data "holes" in tables.
Returns the index of the previous existing element of a table.
sword OCITablePrev ( OCIEnv *env, OCIError *err, sb4 index, CONST OCITable *tbl, sb4 *prev_index boolean *exists );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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 for starting point of scan.
Table to scan.
Index of the previous existing element before tbl(index).
FALSE if no previous index is available, else TRUE.
Return the largest position j, less than index, such that exists(j) is TRUE
See Also: Refer to the description of OCIStringAllocSize() on page 15-109, regarding the existence of non-data "holes" in tables.
Return size of the given table (not including deleted elements).
sword OCITableSize ( OCIEnv *env, OCIError *err, CONST OCITable *tbl sb4 *size );
The OCI environment handle initialized in object mode. See the description of OCIInitialize() in Chapter 13 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().
Nested table whose number of elements is returned.
Current number of elements in the nested table. The count does not include deleted elements.
Returns the count of elements in the given table.
This count will be decremented upon deleting elements from the nested table. So this count does not include any "holes" created by deleting elements. To get the count not including the deleted elements, use OCICollSize().
For example:
OCITableSize(...); // assume 'size' returned is equal to 5 OCITableDelete(...); // delete one element OCITableSize(...); // 'size' returned is equal to 4
To get the count plus the count of deleted elements use OCICollSize(). Continuing the above example:
OCICollSize(...) // 'size' returned is still equal to 5
This function returns an error if an error occurs during the loading of the nested table into the object cache, or if any of the input parameters is NULL.
