Oracle Call Interface Programmer's Guide
Release 8.1.5

A67846-01

Library

Product

Contents

Index

Prev Next

17
OCI Datatype Mapping and Manipulation Functions

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:

Introduction

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 Function Syntax

The entries for each function contain the following information:

Purpose

A brief statement of the purpose of the function.

Syntax

A code snippet showing the syntax for calling the function, including the ordering and types of the parameters.

Comments

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.

Parameters

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:

Mode   Description  

IN  

A parameter that passes data to Oracle  

OUT  

A parameter that receives data from Oracle on this or a subsequent call  

IN/OUT  

A parameter that passes data on the call and receives data on the return from this or a subsequent call.  

Returns

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".

Related Functions

A list of related functions.

Datatype Mapping and Manipulation Function Return Values

The OCI datatype mapping and manipulation functions typically return one of the following values:

Table 17-1 Function Return Values
Return Value  Meaning 

OCI_SUCCESS  

The operation succeeded  

OCI_ERROR  

The operation failed. The specific error can be retrieved by calling OCIErrorGet() on the error handle passed to the function.  

OCI_INVALID_HANDLE  

The environment or error handle passed to the function is NULL.  

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".

Functions Returning Other Values

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.

Server Roundtrips for Datatype Mapping and Manipulation Functions

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".

Examples

For more information about these functions, including some code examples, refer to Chapter 11, "Object-Relational Datatypes".

OCI Collection and Iterator Functions

This section describes the Collection and Iterator functions.

Table 17-2 OCI Collection and Iterator Functions Quick Reference
Function/Page  Purpose 

OCICollAppend()  

Collection append element  

OCICollAssign()  

Assign collection  

OCICollAssignElem()  

Collection assign element  

OCICollGetElem()  

Get pointer to an element  

OCICollIsLocator()  

Indicates whether a collection is locator-based or not  

OCICollMax()  

Return maximum number of elements in collection  

OCICollSetUpdateStatus()  

Set the update status of a collection  

OCICollSize()  

Get current size of collection (in number of elements)  

OCICollTrim()  

Trim elements from the collection  

OCIIterCreate()  

Create iterator to scan the varray elements  

OCIIterDelete()  

Delete iterator  

OCIIterGetCurrent()  

Get current collection element  

OCIIterInit()  

Initialize iterator to scan the given collection  

OCIIterNext()  

Get next collection element  

OCIIterPrev()  

Get previous collection element,  


OCICollAppend()

Purpose

Appends an element to the end of a collection.

Syntax

sword OCICollAppend ( OCIEnv              *env,
                      OCIError            *err,
                      CONST dvoid         *elem, 
                      CONST dvoid         *elemind,
                      OCIColl             *coll );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

elem (IN)

Pointer to the element which is appended to the end of the given collection.

elemind (IN) [optional]

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.

coll (IN/OUT)

Updated collection.

Comments

Appending an element is equivalent to increasing the size of the collection by 1 element and updating (deep-copying) the last element's data with the given element's data. Note that the pointer to the given element elem is not saved by this function, which means that elem is strictly an input parameter.

This function returns an error if the current size of the collection is equal to the max size (upper-bound) of the collection prior to appending the element. This function also returns an error if any of the input parameters is NULL.

Related Functions

OCIErrorGet()


OCICollAssign()

Purpose

Assigns (deep-copies) one collection to another.

Syntax

sword OCICollAssign ( OCIEnv              *env, 
                      OCIError            *err, 
                      CONST OCIColl       *rhs, 
                      OCIColl             *lhs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

rhs (IN)

Right-hand side (source) collection to be assigned from.

lhs (OUT)

Left-hand side (target) collection to be assigned to.

Comments

Assigns rhs (source) to lhs (target). The lhs collection may be decreased or increased depending upon the size of rhs. If the lhs contains any elements then the elements will be deleted prior to the assignment. This function performs a deep copy. The memory for the elements comes from the object cache.

An error is returned if the element types of the lhs and rhs collections do not match. Also, an error is returned if the upper-bound of the lhs collection is less than the current number of elements in the rhs collection. An error is also returned if:

Related Functions

OCIErrorGet(), OCICollAssignElem()


OCICollAssignElem()

Purpose

Assigns the given element value elem to the element at coll[index].

Syntax

sword OCICollAssignElem ( OCIEnv           *env, 
                          OCIError         *err, 
                          sb4              index, 
                          CONST dvoid      *elem, 
                          CONST dvoid      *elemind, 
                          OCIColl          *coll );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

Index of the element whose is assigned to.

elem (IN)

Element which is assigned from (source element).

elemind (IN) [optional]

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.

coll (IN/OUT)

Collection to be updated.

Comments

If the collection is of type nested table, the element at the given index may not exist, as in the case when an element has been deleted. In this case, the given element is inserted at index. Otherwise, the element at index is updated with the value of elem.

Note that the given element is deep-copied and elem is strictly an input parameter.

This function returns an error if any input parameter is NULL or if the given index is beyond the bounds of the given collection.

Related Functions

OCIErrorGet(), OCICollAssign()


OCICollGetElem()

Purpose

Gets a pointer to the element at the given index.

Syntax

sword OCICollGetElem ( OCIEnv           *env, 
                       OCIError         *err, 
                       CONST OCIColl    *coll, 
                       sb4              index, 
                       boolean          *exists, 
                       dvoid            **elem, 
                       dvoid            **elemind );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

Pointer to the element in this collection is returned.

index (IN)

Index of the element whose pointer is returned.

exists (OUT)

Set to FALSE if the element at the specified index does not exist; otherwise, set to TRUE.

elem (OUT)

Address of the desired element is returned.

elemind (OUT) [optional]

Address of the null indicator information is returned. If (elemind == NULL), then the null indicator information will NOT be returned.

Comments

Gets the address of the element at the given position. Optionally this function also returns the address of the element's null indicator information.

The following table describes for each collection element type what the corresponding element pointer type is. The element pointer is returned with the elem parameter of OCICollGetElem().

Element Type   *elem is set to  

Oracle Number (OCINumber)  

OCINumber*  

Date (OCIDate)  

OCIDate*  

Variable-length string (OCIString*)  

OCIString**  

Variable-length raw (OCIRaw*)  

OCIRaw**  

object reference (OCIRef*)  

OCIRef**  

lob locator (OCILobLocator*)  

OCILobLocator**  

object type (such as person)  

person*  

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.

Related Functions

OCIErrorGet(), OCICollAssignElem()


OCICollIsLocator()

Purpose

Indicates whether a collection is locator-based or not.

Syntax

sword OCICollIsLocator ( OCIEnv *env, 
                         OCIError *err,
                         CONST OCIColl *coll, 
                         boolean *result ); 

Parameters

env (IN)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

A collection item.

result (OUT)

Returns TRUE if the collection item is locator-based, FALSE otherwise.

Comments

This function tests to see whether or not a collection is locator-based. Returns TRUE in the result parameter if the collection item is locator-based, otherwise it returns FALSE.

Related Functions

OCIErrorGet()


OCICollMax()

Purpose

Gets the maximum size in number of elements of the given collection.

Syntax

sb4 OCICollMax ( OCIEnv           *env,
                 CONST OCIColl    *coll );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

coll (IN)

Collection whose number of elements is returned. coll must point to a valid collection descriptor.

Comments

Returns the maximum number of elements that the given collection can hold. A value of zero indicates that the collection has no upper bound.

Returns

The upper bound of the given collection.

Related Functions

OCIErrorGet(), OCICollSize()


OCICollSetUpdateStatus()

Purpose

Set the update status of a collection.

Syntax

sword OCICollSetUpdateStatus ( OCIEnv *env,
                               OCIError *err, 
                               OCIColl *coll,
                               ub1 status );

Parameters

env (IN)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

The collection whose update-status is to be set.

status (IN)

The status of the collection:

Comments

This function sets the status of the collection to indicate whether it should be marked updated (dirty) or should be marked as not dirty.

Related Functions

OCIErrorGet()


OCICollSize()

Purpose

Gets the current size in number of elements of the given collection.

Syntax

sword OCICollSize ( OCIEnv           *env,
                    OCIError         *err,
                    CONST OCIColl    *coll 
                    sb4              *size );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

Collection whose number of elements is returned. Must point to a valid collection descriptor.

size (OUT)

Current number of elements in the collection.

Comments

Returns the current number of elements in the given collection. For the case of nested table, this count will NOT be decremented upon deleting elements. So, this count includes any holes created by deleting elements. A trim operation (OCICollTrim()) will decrement the count by the number of trimmed elements. To get the count minus the deleted elements use OCITableSize().

The following pseudocode shows some examples:

OCICollSize(...); 
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCICollSize(...);
// 'size' returned is still 5

To get the count minus the deleted elements use OCITableSize(). Continuing the 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.

Related Functions

OCIErrorGet(), OCICollMax()


OCICollTrim()

Purpose

Trims the given number of elements from the end of the collection.

Syntax

sword OCICollTrim ( OCIEnv         *env, 
                    OCIError       *err, 
                    sb4            trim_num, 
                    OCIColl        *coll );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

trim_num (IN)

Number of elements to trim.

coll (IN/OUT)

This function removes (frees) trim_num elements from the end of coll.

Comments

The elements are removed from the end of the collection. An error is returned if trim_num is greater than the current size of the collection.

Related Functions

OCIErrorGet(), OCICollSize()


OCIIterCreate()

Purpose

Creates an iterator to scan the elements or the collection.

Syntax

sword OCIIterCreate ( OCIEnv               *env, 
                      OCIError             *err, 
                      CONST OCIColl        *coll, 
                      OCIIter              **itr );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

Collection which will be scanned. For this release, valid collection types include varrays and nested tables.

itr (OUT)

Address to the allocated collection iterator is returned by this function.

Comments

The iterator is created in the object cache. The iterator is initialized to point to the beginning of the collection.

If OCIIterNext() is called immediately after creating the iterator then the first element of the collection is returned. If OCIIterPrev() is called immediately after creating the iterator then a "at beginning of collection" error is returned.

This function returns an error if any of the input parameters is NULL.

Related Functions

OCIErrorGet(), OCIIterDelete()


OCIIterDelete()

Purpose

Deletes a collection iterator.

Syntax

sword OCIIterDelete ( OCIEnv           *env, 
                      OCIError         *err, 
                      OCIIter          **itr );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

itr (IN/OUT)

The allocated collection iterator which is destroyed and set to NULL prior to returning.

Comments

Deletes an iterator which was previously created by a call to OCIIterCreate().

This function returns an error if any of the input parameters is null.

Related Functions

OCIErrorGet(), OCIIterCreate()


OCIIterGetCurrent()

Purpose

Gets a pointer to the current iterator collection element.

Syntax

sword OCIIterGetCurrent ( OCIEnv            *env, 
                          OCIError          *err, 
                          CONST OCIIter     *itr, 
                          dvoid             **elem, 
                          dvoid             **elemind );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

itr (IN)

Iterator which points to the current element.

elem (OUT)

Address of the element pointed by the iterator is returned.

elemind (OUT) [optional]

Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.

Comments

Returns pointer to the current iterator collection element and its corresponding NULL information. This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterNext(), OCIIterPrev()


OCIIterInit()

Purpose

Initializes an iterator to scan a collection.

Syntax

sword OCIIterInit ( OCIEnv              *env, 
                    OCIError            *err, 
                    CONST OCIColl       *coll, 
                    OCIIter             *itr );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

coll (IN)

Collection which will be scanned. For release 8i, valid collection types include varrays and nested tables.

itr (IN/OUT)

Pointer to an allocated collection iterator.

Comments

Initializes given iterator to point to the beginning of given collection. Returns an error if any input parameter is NULL. This function can be used to:

Related Functions

OCIErrorGet()


OCIIterNext()

Purpose

Gets a pointer to the next iterator collection element.

Syntax

sword OCIIterNext ( OCIEnv            *env,
                    OCIError          *err, 
                    OCIIter           *itr, 
                    dvoid             **elem,
                    dvoid             **elemind,
                    boolean           *eoc);

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

itr (IN/OUT)

Iterator is updated to point to the next element.

elem (OUT)

After updating the iterator to point to the next element, address of the element is returned.

elemind (OUT) [optional]

Address of the element's NULL indicator information is returned; if (elem_ind == NULL) then the NULL indicator information will not be returned.

eoc (OUT)

TRUE if iterator is at End of Collection (i.e. next element does not exist); otherwise, FALSE.

Comments

This function returns a pointer to the next iterator collection element and its corresponding NULL information. It also updates the iterator to point to the next element.

If the iterator is pointing to the last element of the collection prior to executing this function, then calling this function will set the eoc flag to TRUE. The iterator will be left unchanged in that case.

This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterGetCurrent(), OCIIterPrev()


OCIIterPrev()

Purpose

Gets a pointer to the previous iterator collection element.

Syntax

sword OCIIterPrev ( OCIEnv            *env, 
                    OCIError          *err, 
                    OCIIter           *itr, 
                    dvoid             **elem, 
                    dvoid             **elemind,
                    boolean           *boc );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

itr (IN/OUT)

Iterator which is updated to point to the previous element.

elem (OUT)

Address of the previous element; returned after the iterator is updated to point to it.

elemind (OUT) [optional]

Address of the element's NULL indicator; if (elem_ind == NULL) then the NULL indicator will not be returned.

boc (OUT)

TRUE if iterator is at beginning of collection (i.e. previous element does not exist); otherwise, FALSE.

Comments

This function returns a pointer to the previous iterator collection element and its corresponding NULL information. The iterator is updated to point to the previous element.

If the iterator is pointing to the first element of the collection prior to executing this function, then calling this function will set boc to TRUE. The iterator is left unchanged in that case.

This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCIIterGetCurrent(), OCIIterNext()

OCI Date Functions

This section describes the OCI Date functions.

Table 17-3 OCI Date Functions Quick Reference
Function/Page  Purpose 

OCIDateAddDays()  

Add or subtract days  

OCIDateAddMonths()  

Add or subtract months  

OCIDateAssign()  

Assign date  

OCIDateCheck()  

Check if the given date is valid  

OCIDateCompare()  

Compare dates  

OCIDateDaysBetween()  

Get number of days between two dates  

OCIDateFromText()  

Convert string to date  

OCIDateGetDate()  

Get the date portion of a date  

OCIDateGetTime()  

Get the time portion of a date  

OCIDateLastDay()  

Get date of last day of month  

OCIDateNextDay()  

get date of next day  

OCIDateSetDate()  

Set the date portion of a date  

OCIDateSetTime()  

Set the time portion of a date  

OCIDateSysDate()  

Get current system date and time  

OCIDateToText()  

Convert date to String  

OCIDateZoneToZone()  

Convert date from one time zone to another zone  


OCIDateAddDays()

Purpose

Adds or subtracts days from a given date.

Syntax

sword OCIDateAddDays ( OCIError          *err,
                       CONST OCIDate     *date, 
                       sb4               num_days,
                       OCIDate           *result );

Parameters

err (IN/OUT)

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 (IN)

The given date from which to add or subtract.

num_days (IN)

Number of days to be added or subtracted. A negative value is subtracted.

result (IN/OUT)

Result of adding days to, or subtracting days from, date.

Comments

This function returns and error if an invalid date is passed to it.

Related Functions

OCIErrorGet(), OCIDateAddMonths()


OCIDateAddMonths()

Purpose

Adds or subtracts months from a given date.

Syntax

sword OCIDateAddMonths ( OCIError            *err,
                         CONST OCIDate       *date,
                         sb4                 num_months,
                         OCIDate             *result );

Parameters

err (IN/OUT)

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 (IN)

The given date from which to add or subtract.

num_months (IN)

Number of months to be added or subtracted. A negative value is subtracted.

result (IN/OUT)

Result of adding days to, or subtracting days from, date.

Comments

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.

Related Functions

OCIErrorGet(), OCIDateAddDays()


OCIDateAssign()

Purpose

Performs a date assignment.

Syntax

sword OCIDateAssign ( OCIError         *err,
                      CONST OCIDate    *from, 
                      OCIDate          *to );

Parameters

err (IN/OUT)

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().

from (IN)

Date to be assigned.

to (OUT)

Target of assignment.

Comments

This function assigns a value from one OCIDate variable to another.

Related Functions

OCIErrorGet(), OCIDateCheck()


OCIDateCheck()

Purpose

Checks if the given date is valid.

Syntax

sword OCIDateCheck ( OCIError          *err,
                     CONST OCIDate     *date, 
                     uword             *valid );

Parameters

err (IN/OUT)

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 (IN)

Date to be checked

valid (OUT)

Returns zero for a valid date. Otherwise, the OR'ed combination of all error bits specified as follows:

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  

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.

Comments

This function returns an error if date or valid pointer is NULL.

Related Functions

OCIErrorGet(), OCIDateCompare()


OCIDateCompare()

Purpose

Compares two dates.

Syntax

sword OCIDateCompare ( OCIError           *err, 
                       CONST OCIDate      *date1, 
                       CONST OCIDate      *date2,
                       sword              *result );

Parameters

err (IN/OUT)

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().

date1, date2 (IN)

Dates to be compared.

result (OUT)

Comparison result:

Comparison result   Output in result parameter  

date1 < date2  

-1  

date1 = date2  

0  

date1 > date2  

1  

Comments

This function returns and error if an invalid date is passed to it.

Related Functions

OCIErrorGet(), OCIDateCheck()


OCIDateDaysBetween()

Purpose

Gets the number of days between two dates.

Syntax

sword OCIDateDaysBetween ( OCIError            *err, 
                           CONST OCIDate       *date1, 
                           CONST OCIDate       *date2, 
                           sb4                 *num_days );

Parameters

err (IN/OUT)

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().

date1 (IN)

Input date.

date2 (IN)

Input date.

num_days (OUT)

Number of days between date1 and date2.

Comments

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.

Related Functions

OCIErrorGet(), OCIDateCheck()


OCIDateFromText()

Purpose

Converts a character string to a date type according to the specified format.

Syntax

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 );

Parameters

err (IN/OUT)

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_str (IN)

Input string to be converted to Oracle date.

d_str_length (IN)

Size of the input string, if the length is -1 then date_str is treated as a NULL terminated string.

fmt (IN)

Conversion format. If fmt is a null pointer, then the string is expected to be in 'DD-MON-YY' format.

fmt_length (IN)

Length of the fmt parameter.

lang_name (IN)

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.

lang_length (IN)

Length of the lang_name parameter.

date (OUT)

Given string converted to date.

Comments

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.

Related Functions

OCIErrorGet(), OCIDateToText()


OCIDateGetDate()

Purpose

Get the year, month, and day stored in an Oracle date.

Syntax

void OCIDateGetDate ( CONST OCIDate    *date,
                      sb2              *year,
                      ub1              *month, 
                      ub1              *day ); 

Parameters

date (IN)

Oracle date whose year, month, day data is retrieved.

year (OUT)

Year value returned.

month (OUT)

Month value returned.

day (OUT)

Day value returned.

Comments

None.

Related Functions

OCIDateSetDate(), OCIDateGetTime()


OCIDateGetTime()

Purpose

Gets the time stored in an Oracle date.

Syntax

void OCIDateGetTime ( CONST OCIDate    *date,
                      ub1              *hour,
                      ub1              *min, 
                      ub1              *sec );

Parameters

date (IN)

Oracle date whose time data is retrieved.

hour (OUT)

Hour value returned.

min (OUT)

Minute value returned.

sec (OUT)

Second value returned.

Comments

Returns the time information returned in the form: hour, minute and seconds.

Related Functions

OCIDateSetTime(), OCIDateGetDate()


OCIDateLastDay()

Purpose

Gets the date of the last day of the month in a specified date.

Syntax

sword OCIDateLastDay ( OCIError            *err,
                       CONST OCIDate       *date,
                       OCIDate             *last_day );

Parameters

err (IN/OUT)

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 (IN)

Input date.

last_day (OUT)

Last day of the month in date.

Comments

This function returns an error if invalid date is passed to it.

Related Functions

OCIErrorGet(), OCIDateGetDate()


OCIDateNextDay()

Purpose

Gets the date of next day of the week, after a given date.

Syntax

sword OCIDateNextDay ( OCIError            *err,
                       CONST OCIDate       *date,
                       CONST text          *day, 
                       ub4                 day_length,
                       OCIDate             *next_day );

Parameters

err (IN/OUT)

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 (IN)

Returned date should be later than this date.

day (IN)

First day of week named by this is returned.

day_length (IN)

Length in bytes of string day.

next_day (OUT)

First day of the week named by day later than date.

Comments

Returns the date of the first day of the week named by day that is later than date.

Example

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.

Related Functions

OCIErrorGet(), OCIDateGetDate()


OCIDateSetDate()

Purpose

Set the values in an Oracle date.

Syntax

void OCIDateSetDate ( OCIDate    *date, 
                      sb2        year, 
                      ub1        month, 
                      ub1        day );

Parameters

date (OUT)

Oracle date whose time data is set.

year (IN)

Year value to be set.

month (IN)

Month value to be set.

day (IN)

Day value to be set.

Comments

None.

Related Functions

OCIDateGetDate()


OCIDateSetTime()

Purpose

Sets the time information in an Oracle date.

Syntax

void OCIDateSetTime ( OCIDate    *date,
                      ub1        hour, 
                      ub1        min, 
                      ub1        sec ); 

Parameters

date (OUT)

Oracle date whose time data is set.

hour (IN)

Hour value to be set.

min (IN)

Minute value to be set.

sec (IN)

Second value to be set.

Comments

None.

Related Functions

OCIDateGetTime()


OCIDateSysDate()

Purpose

Gets the current system date and time.

Syntax

sword OCIDateSysDate ( OCIError       *err,
                       OCIDate        *sys_date );

Parameters

err (IN/OUT)

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().

sys_date (OUT)

Current system date and time.

Comments

None.

Related Functions

OCIErrorGet()


OCIDateToText()

Purpose

Converts a date type to a character string.

Syntax

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 );

Parameters

err (IN/OUT)

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 (IN)

Oracle date to be converted.

fmt (IN)

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.

fmt_length (IN)

Length of the fmt parameter.

lang_name (IN)

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).

lang_length (IN)

Length of the lang_name parameter.

buf_size (IN/OUT)
buf (OUT)

Buffer into which the converted string is placed.

Comments

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 Oracle8i 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.

Related Functions

OCIErrorGet(), OCIDateFromText()


OCIDateZoneToZone()

Purpose

Converts a date from one time zone to another.

Syntax

sword OCIDateZoneToZone ( OCIError           *err, 
                          CONST OCIDate      *date1, 
                          CONST text         *zon1,
                          ub4                zon1_length, 
                          CONST text         *zon2, 
                          ub4                zon2_length, 
                          OCIDate            *date2 );

Parameters

err (IN/OUT)

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().

date1 (IN)

Date to convert.

zon1 (IN)

Zone of input date.

zon1_length (IN)

Length in bytes of zon1.

zon2 (IN)

Zone to be converted to.

zon2_length (IN)

Length in bytes of zon2.

date2 (OUT)

Converted date (in zon2).

Comments

Converts a given date date1 in time zone zon1 to a 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 Oracle8i SQL Reference. Examples of valid zone strings include:

This function returns and error if an invalid date or time zone is passed to it.

Related Functions

OCIErrorGet(), OCIDateCheck()

OCI Number Functions

This section describes the OCI Number functions.

Table 17-4 OCI Number Functions Quick Reference
Function/Page  Purpose 

OCINumberAbs()  

Computes the absolute value  

OCINumberAdd()  

Adds numbers  

OCINumberArcCos()  

Computes the arc cosine  

OCINumberArcSin()  

Computes the arc sine  

OCINumberArcTan()  

Computes the arc tangent  

OCINumberArcTan2()  

Computes the arc tangent of two numbers  

OCINumberAssign()  

Assigns one number to another  

OCINumberCeil()  

Computes the ceiling of number  

OCINumberCmp()  

Compares numbers  

OCINumberCos()  

Computes the cosine  

OCINumberDec()  

Decrements an OCI number  

OCINumberDiv()  

Divides two numbers  

OCINumberExp()  

Raises e to the specified Oracle number power  

OCINumberFloor()  

Computes the floor of a number  

OCINumberFromInt()  

Converts an integer to an Oracle number  

OCINumberFromReal()  

Convert a real to an Oracle number  

OCINumberFromText()  

Convert a string to an Oracle number  

OCINumberHypCos()  

Computes the hyperbolic cosine  

OCINumberHypSin()  

Computes the hyperbolic sine  

OCINumberHypTan()  

Computes the hyperbolic tangent  

OCINumberInc()  

Increments an Oracle number  

OCINumberIntPower()  

Raises a given base to an integer power  

OCINumberIsInt()  

Tests if a number is an integer  

OCINumberIsZero()  

Tests if a number is zero  

OCINumberLn()  

Computes the natural logarithm  

OCINumberLog()  

Computes the logarithm to an arbitrary base  

OCINumberMod()  

Modulo division  

OCINumberMul()  

Multiplies numbers  

OCINumberNeg()  

Negates a number  

OCINumberPower()  

Exponentiation to base e  

OCINumberPrec()  

Rounds a number to a specified number of decimal places  

OCINumberRound()  

Rounds an Oracle number to a specified decimal place  

OCINumberSetPi()  

Initializes a number to Pi  

OCINumberSetZero()  

Initializes a number to zero  

OCINumberShift()  

Multiplies by 10, shifting specified number of decimal places  

OCINumberSign()  

Obtains the sign of an Oracle number  

OCINumberSin()  

Computes the sine  

OCINumberSqrt()  

Computes the square root of a number  

OCINumberSub()  

Subtracts numbers  

OCINumberTan()  

Computes the tangent  

OCINumberToInt()  

Converts an Oracle number to an integer  

OCINumberToReal()  

Converts an Oracle number to a real  

OCINumberToText()  

Converts an Oracle number to a string  

OCINumberTrunc()  

Truncates an Oracle number at a specified decimal place  


OCINumberAbs()

Purpose

Computes the absolute value of an Oracle number.

Syntax

sword OCINumberAbs ( OCIError              *err,
                     CONST OCINumber       *number, 
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Input number.

result (OUT)

The absolute value of the input number.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberSign()


OCINumberAdd()

Purpose

Adds two Oracle numbers together.

Syntax

sword OCINumberAdd ( OCIError              *err,
                     CONST OCINumber       *number1, 
                     CONST OCINumber       *number2,
                     OCINumber             *result );

Parameters

err (IN/OUT)

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().

number1, number2 (IN)

Numbers to be added.

result (OUT)

Result of adding number1 to number2.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberSub()


OCINumberArcCos()

Purpose

Takes the arc cosine in radians of an Oracle number.

Syntax

sword OCINumberArcCos ( OCIError            *err, 
                        CONST OCINumber     *number, 
                        OCINumber           *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the arc cosine.

result (OUT)

Result of the arc cosine in radians.

Comments

This function returns an error if any of the number arguments is NULL, or if number is less than -1 or if number is greater than 1.

Related Functions

OCIErrorGet(), OCINumberCos()


OCINumberArcSin()

Purpose

Takes the arc sine in radians of an Oracle number.

Syntax

sword OCINumberArcSin ( OCIError              *err,
                        CONST OCINumber       *number, 
                        OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the arc sine.

result (OUT)

Result of the arc sine in radians.

Comments

This function returns an error if any of the number arguments is NULL, or if number is less than -1 or if number is greater than 1.

Related Functions

OCIErrorGet(), OCINumberSin()


OCINumberArcTan()

Purpose

Takes the arc tangent in radians of an Oracle number.

Syntax

sword OCINumberArcTan ( OCIError             *err, 
                        CONST OCINumber      *number, 
                        OCINumber            *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the arc tangent.

result (OUT)

Result of the arc tangent in radians.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberTan()


OCINumberArcTan2()

Purpose

Takes the arc tangent of two Oracle numbers.

Syntax

sword OCINumberArcTan2 ( OCIError              *err, 
                         CONST OCINumber       *number1, 
                         CONST OCINumber       *number2,
                         OCINumber             *result );

Parameters

err (IN/OUT)

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().

number1 (IN)

Argument 1 of the arc tangent.

number2 (IN)

Argument 2 of the arc tangent.

result (OUT)

Result of the arc tangent in radians.

Comments

This function returns an error if any of the number arguments is NULL, or if number2 is equal to 0.

Related Functions

OCIErrorGet(), OCINumberTan()


OCINumberAssign()

Purpose

Assigns one Oracle number to another Oracle number.

Syntax

sword OCINumberAssign ( OCIError              *err,
                        CONST OCINumber       *from, 
                        OCINumber             *to );

Parameters

err (IN/OUT)

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().

from (IN)

Number to be assigned.

to (OUT)

Number copied into.

Comments

Assigns the number idenitified by from to the number identified by to.

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberCmp()


OCINumberCeil()

Purpose

Computes the ceiling value of an Oracle number.

Syntax

sword OCINumberCeil ( OCIError              *err, 
                      CONST OCINumber       *number, 
                      OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Input number.

result (OUT)

Output which will contain the ceiling value of the input number.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberFloor()


OCINumberCmp()

Purpose

Compares two Oracle numbers.

Syntax

sword OCINumberCmp ( OCIError            *err,
                     CONST OCINumber     *number1, 
                     CONST OCINumber     *number2,
                     sword               *result );

Parameters

err (IN/OUT)

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().

number1, number2 (IN)

Numbers to compare.

result (OUT)

Comparison result:

Comparison result   Output in result parameter  

number1 < number2  

negative  

number1 = number2  

0  

number1 > number2  

positive  

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberAssign()


OCINumberCos()

Purpose

Computes the cosine in radians of an Oracle number.

Syntax

sword OCINumberCos ( OCIError              *err,
                     CONST OCINumber       *number, 
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the cosine in radians.

result (OUT)

Result of the cosine.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberArcCos()


OCINumberDec()

Purpose

Decrements an OCINumber.

Syntax

OCINumberInc ( OCIError *err, 
               OCINumber *number );

Parameters

err (IN/OUT)

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 (IN/OUT)

A positive Oracle number to be decremented.

Comments

Decrements an Oracle number in place. It is assumed that the input is an integer between 0 and 100^21-2. If the is input too large, it will be treated as 0 - the result will be an Oracle number 1. If the input is not a positive integer, the result will be unpredictable.

This function returns an error if the input number is NULL.

Related Functions

OCINumberInc(), OCINumberInc()


OCINumberDiv()

Purpose

Divides two Oracle numbers.

Syntax

sword OCINumberDiv ( OCIError               *err,
                     CONST OCINumber        *number1, 
                     CONST OCINumber        *number2,
                     OCINumber              *result );

Parameters

err (IN/OUT)

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().

number1 (IN)

Pointer to the numerator.

number2 (IN)

Pointer to the denominator.

result (OUT)

Division result.

Comments

Divides number1 by number2 and returns result in result.

This function returns an error if:

Related Functions

OCIErrorGet(), OCINumberMul()


OCINumberExp()

Purpose

Raises e to the specified Oracle number power.

Syntax

sword OCINumberExp ( OCIError              *err, 
                     CONST OCINumber       *number,
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

This function raises e to this Oracle number power.

result (OUT)

Output of exponentiation.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberLn()


OCINumberFloor()

Purpose

Computes the floor value of an Oracle number.

Syntax

sword OCINumberFloor ( OCIError              *err,
                       CONST OCINumber       *number, 
                       OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Input number.

result (OUT)

The floor value of the input number.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberCeil()


OCINumberFromInt()

Purpose

Converts an integer to an Oracle number.

Syntax

sword OCINumberFromInt ( OCIError            *err,
                         CONST dvoid         *inum, 
                         uword               inum_length,
                         uword               inum_s_flag,
                         OCINumber           *number );

Parameters

err (IN/OUT)

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().

inum (IN)

Pointer to the integer to convert.

inum_length (IN)

Size of the integer.

inum_s_flag (IN)

Flag that designates the sign of the integer, as follows:

number (OUT)

Given integer converted to Oracle number.

Comments

This is a native type conversion function. It converts any Oracle standard machine-native integer type, such as ub4 or 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.

Related Functions

OCIErrorGet(), OCINumberToInt()


OCINumberFromReal()

Purpose

Converts a real (floating-point) type to an Oracle number.

Syntax

sword OCINumberFromReal ( OCIError           *err,
                          CONST dvoid        *rnum,
                          uword              rnum_length,
                          OCINumber          *number );

Parameters

err (IN/OUT)

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().

rnum (IN)

Pointer to the floating point number to convert.

rnum_length (IN)

The size of the desired result, which equals sizeof({float | double | long double}).

number (OUT)

Given float converted to Oracle number.

Comments

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.

Related Functions

OCIErrorGet(), OCINumberToReal()


OCINumberFromText()

Purpose

Converts character string to Oracle number.

Syntax

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 );

Parameters

err (IN/OUT)

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().

str (IN)

Input string to convert to Oracle number.

str_length (IN)

Size of the input string.

fmt (IN)

Conversion format.

fmt_length (IN)

Length of the fmt parameter.

nls_params (IN)

NLS format specification, if NULL string ("") then the default parameters for the session is used.

nls_p_length (IN)

Length of the nls_params parameter.

number (OUT)

Given string converted to number.

Comments

Converts the given string to a number according to the specified format. Refer to the TO_NUMBER conversion function described in the Oracle8i 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.

Related Functions

OCIErrorGet(), OCINumberToText()


OCINumberHypCos()

Purpose

Computes the hyperbolic cosine of an Oracle number.

Syntax

sword OCINumberHypCos ( OCIError              *err, 
                        CONST OCINumber       *number, 
                        OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the cosine hyperbolic.

result (OUT)

Result of the cosine hyperbolic.

Comments

This function returns an error if any of the number arguments is NULL.

Warning: An Oracle number overflow causes an unpredictable result value.

Related Functions

OCIErrorGet(), OCINumberHypSin(), OCINumberHypTan()


OCINumberHypSin()

Purpose

Computes the hyperbolic sine of an Oracle number.

Syntax

sword OCINumberHypSin ( OCIError              *err,
                        CONST OCINumber       *number, 
                        OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the sine hyperbolic.

result (OUT)

Result of the sine hyperbolic.

Comments

This function returns an error if any of the number arguments is NULL.

Warning: An Oracle number overflow causes an unpredictable result value.

Related Functions

OCIErrorGet(), OCINumberHypCos(), OCINumberHypTan()


OCINumberHypTan()

Purpose

Computes the hyperbolic tangent of an Oracle number.

Syntax

sword OCINumberHypTan ( OCIError              *err,
                        CONST OCINumber       *number,
                        OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the tangent hyperbolic.

result (OUT)

Result of the tangent hyperbolic.

Comments

This function returns an error if any of the number arguments is NULL.

Warning: An Oracle number overflow causes an unpredictable result value.

Related Functions

OCIErrorGet(), OCINumberHypCos(), OCINumberHypSin()


OCINumberInc()

Purpose

Increments an OCINumber.

Syntax

OCINumberInc ( OCIError   *err, 
               OCINumber  *number );

Parameters

err (IN/OUT)

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 (IN/OUT)

A positive Oracle number to be incremented.

Comments

Increments an Oracle number in place. It is assumed that the input is an integer between 0 and 100^21-2. If the is input too large, it will be treated as 0 - the result will be an Oracle number 1. If the input is not a positive integer, the result will be unpredictable.

This function returns an error if the input number is NULL.

Related Functions

OCINumberDec()


OCINumberIntPower()

Purpose

Raises a given base to a given integer power.

Syntax

sword OCINumberIntPower ( OCIError             *err, 
                          CONST OCINumber      *base, 
                          CONST sword          exp,
                          OCINumber            *result );

Parameters

err (IN/OUT)

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 (IN)

Base of the exponentiation.

exp (IN)

Exponent to which the base is raised.

result (OUT)

Output of exponentiation.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberPower()


OCINumberIsInt()

Purpose

Tests if an OCINumber is an integer.

Syntax

sword OCINumberIsInt ( OCIError         *err, 
                       CONST OCINumber  *number,
                       boolean          *result );

Parameters

err (IN/OUT)

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 (IN)

number to be tested

result (OUT)

set to TRUE if integer value else FALSE

Comments

This function returns an error if number or result is NULL.

Related Functions

OCIErrorGet(), OCINumberRound(), OCINumberTrunc()


OCINumberIsZero()

Purpose

Tests if the given number is equal to zero.

Syntax

sword OCINumberIsZero ( OCIError            *err,
                        CONST OCINumber     *number,
                        boolean             *result );

Parameters

err (IN/OUT)

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 (IN)

Number to compare.

result (OUT)

Set to TRUE if equal to zero; otherwise, set to FALSE.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberSetZero()


OCINumberLn()

Purpose

Takes the natural logarithm (base e) of an Oracle number.

Syntax

sword OCINumberLn ( OCIError              *err,
                    CONST OCINumber       *number,
                    OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Logarithm of this number is computed.

result (OUT)

Logarithm result.

Comments

This function returns an error if any of the number arguments is NULL, or if numberI is less than or equal to zero.

Related Functions

OCIErrorGet(), OCINumberExp(), OCINumberLog()


OCINumberLog()

Purpose

Takes the logarithm, to any base, of an Oracle number.

Syntax

sword OCINumberLog ( OCIError              *err, 
                     CONST OCINumber       *base, 
                     CONST OCINumber       *number, 
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Base of the logarithm.

number (IN)

Operand.

result (OUT)

Logarithm result.

Comments

This function returns an error if:

Related Functions

OCIErrorGet(), OCINumberLn()


OCINumberMod()

Purpose

Gets the modulus (remainder) of the division of two Oracle numbers.

Syntax

sword OCINumberMod ( OCIError              *err,
                     CONST OCINumber       *number1, 
                     CONST OCINumber       *number2,
                     OCINumber             *result );

Parameters

err (IN/OUT)

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().

number1 (IN)

Pointer to the numerator.

number2 (IN)

Pointer to the denominator.

result (OUT)

Remainder of the result.

Comments

This function returns an error if number1 or number2 is NULL, or if there is a divide-by-zero error.

Related Functions

OCIErrorGet(), OCINumberDiv()


OCINumberMul()

Purpose

Multiplies two Oracle numbers.

Syntax

sword OCINumberMul ( OCIError              *err,
                     CONST OCINumber       *number1, 
                     CONST OCINumber       *number2,
                     OCINumber             *result );

Parameters

err (IN/OUT)

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().

number1 (IN)

Number to multiply.

number2 (IN)

Number to multiply.

result (OUT)

Multiplication result.

Comments

Multiplies number1 with number2 and returns result in result.

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberDiv()


OCINumberNeg()

Purpose

Negates an Oracle number.

Syntax

sword OCINumberNeg ( OCIError              *err, 
                     CONST OCINumber       *number, 
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Number to negate.

result (OUT)

Contains negated value of number.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberAbs(), OCINumberSign()


OCINumberPower()

Purpose

Raises a given base to a given exponent.

Syntax

sword OCINumberPower ( OCIError              *err,
                       CONST OCINumber       *base, 
                       CONST OCINumber       *number, 
                       OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Base of the exponentiation.

number (IN)

Exponent to which the base is to be raised.

result (OUT)

Output of exponentiation.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberExp()


OCINumberPrec()

Purpose

Rounds an OCINumber to a specified number of decimal digits.

Syntax

sword OCINumberPrec ( OCIError *err, 
                      CONST OCINumber *number,
                      eword nDigs, 
                      OCINumber *result );

Parameters

err (IN/OUT)

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 (IN)

The number for which to set precision.

nDigs (IN)

The number of decimal digits desired in the result.

result (OUT)

The result.

Comments

Performs a floating point round with respect to the number of digits.

This function returns an error any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberRound()


OCINumberRound()

Purpose

Rounds an Oracle number to a specified decimal place.

Syntax

sword OCINumberRound ( OCIError              *err,
                       CONST OCINumber       *number,
                       sword                 decplace,
                       OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Number to round.

decplace (IN)

Number of decimal digits to the right of the decimal point to round to. Negative values are allowed.

result (OUT)

Output of rounding.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberTrunc()


OCINumberSetPi()

Purpose

Sets an OCINumber to Pi.

Syntax

void OCINumberSetPi ( OCIError *err, 
                      OCINumber *num );

Parameters

err (IN/OUT)

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().

num (OUT)

Number set to the value of Pi.

Comments

Initializes the given number to the value of Pi.

Related Functions

OCIErrorGet()


OCINumberSetZero()

Purpose

Initializes an Oracle number to zero.

Syntax

void OCINumberSetZero ( OCIError      *err
                        OCINumber     *num ); 

Parameters

err (IN/OUT)

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().

num (IN/OUT)

Number to initialize to zero value.

Comments

None.

Related Functions

OCIErrorGet()


OCINumberShift()

Purpose

Multiplies a number by a power of 10 by shifting it a specified number of decimal places.

Syntax

sword OCINumberShift ( OCIError         *err, 
                       CONST OCINumber  *number,
                       CONST sword      nDig,
                       OCINumber        *result );

Parameters

err (IN/OUT)

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 (IN)

Oracle Number to be shifted.

nDig (IN)

Number of decimal places to shift.

result (OUT)

Shift result.

Comments

Multiplies number by 10^nDig and sets product to the result.

This function returns an error if the input number is NULL.

Related Functions

OCIErrorGet()


OCINumberSign()

Purpose

Gets sign of an Oracle number.

Syntax

sword OCINumberSign ( OCIError             *err, 
                      CONST OCINumber      *number, 
                      sword                *result );

Parameters

err (IN/OUT)

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 (IN)

Number whose sign is returned.

result (OUT)

Possible values:

Value of number   Output in result parameter  

number < 0  

-1  

number == 0  

0  

number > 0  

1  

Comments

This function returns an error if number or result is NULL.

Related Functions

OCIErrorGet(), OCINumberAbs()


OCINumberSin()

Purpose

Computes the sine in radians of an Oracle number.

Syntax

sword OCINumberSin ( OCIError              *err, 
                     CONST OCINumber       *number, 
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the sine in radians.

result (OUT)

Result of the sine.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberArcSin()


OCINumberSqrt()

Purpose

Computes the square root of an Oracle number.

Syntax

sword OCINumberSqrt ( OCIError           *err,
                     CONST OCINumber     *number, 
                     OCINumber           *result );

Parameters

err (IN/OUT)

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 (IN)

Input number.

result (OUT)

Output which will contain the square root of the input number.

Comments

This function returns an error if number is NULL or number is negative.

Related Functions

OCIErrorGet(), OCINumberPower()


OCINumberSub()

Purpose

Subtract two Oracle numbers.

Syntax

sword OCINumberSub ( OCIError             *err,
                     CONST OCINumber      *number1, 
                     CONST OCINumber      *number2, 
                     OCINumber            *result );

Parameters

err (IN/OUT)

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().

number1, number2 (IN)

This function subtracts number2 from number1.

result (OUT)

Subtraction result.

Comments

Subtracts number2 from number1 and returns result in result.

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberAdd()


OCINumberTan()

Purpose

Computes the tangent in radians of an Oracle number.

Syntax

sword OCINumberTan ( OCIError              *err, 
                     CONST OCINumber       *number,
                     OCINumber             *result );

Parameters

err (IN/OUT)

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 (IN)

Argument of the tangent in radians.

result (OUT)

Result of the tangent.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberArcTan(), OCINumberArcTan2()


OCINumberToInt()

Purpose

Converts an Oracle number type to integer.

Syntax

sword OCINumberToInt ( OCIError              *err,
                       CONST OCINumber       *number,
                       uword                 rsl_length,
                       uword                 rsl_flag, 
                       dvoid                 *rsl );

Parameters

err (IN/OUT)

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 (IN)

Number to convert.

rsl_length (IN)

Size of the desired result.

rsl_flag (IN)

Flag that designates the sign of the output, as follows:

rsl (OUT)

Pointer to space for the result.

Comments

This is a native type conversion function. It converts the given Oracle number into an integer of the form xbn, such as ub2, ub4, or sb2.

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.

Related Functions

OCIErrorGet(), OCINumberFromInt()


OCINumberToReal()

Purpose

Converts an Oracle number type to Real.

Syntax

sword OCINumberToReal ( OCIError            *err,
                        CONST OCINumber     *number,
                        uword               rsl_length,
                        dvoid               *rsl );

Parameters

err (IN/OUT)

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 (IN)

Number to convert.

rsl_length (IN)

The size of the desired result, which equals sizeof({ float | double | long double}).

rsl (OUT)

Pointer to space for storing the result.

Comments

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.

Related Functions

OCIErrorGet(), OCINumberFromReal()


OCINumberToText()

Purpose

Converts an Oracle number to a character string according to a specified format.

Syntax

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 );

Parameters

err (IN/OUT)

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 (IN)

Oracle number to convert.

fmt (IN)

Conversion format.

fmt_length (IN)

Length of the fmt parameter.

nls_params (IN)

NLS format specification. If a NULL string ((text *)0 ), then the default parameters for the session is used.

nls_p_length (IN)

Length of the nls_params parameter.

buf_size (IN)

Size of the buffer.

buf (OUT)

Buffer into which the converted string is placed.

Comments

Refer to the TO_NUMBER conversion function described in the Oracle8i 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:

Related Functions

OCIErrorGet(), OCINumberFromText()


OCINumberTrunc()

Purpose

Truncates an Oracle number at a specified decimal place.

Syntax

sword OCINumberTrunc ( OCIError             *err,
                       CONST OCINumber      *number, 
                       sword                decplace,
                       OCINumber            *result );

Parameters

err (IN/OUT)

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 (IN)

Input number.

decplace (IN)

Number of decimal digits to the right of the decimal point at which to truncate. Negative values are allowed.

result (OUT)

Output of truncation.

Comments

This function returns an error if any of the number arguments is NULL.

Related Functions

OCIErrorGet(), OCINumberRound()

OCI Raw Functions

This section describes the OCI Raw functions.

Table 17-5 OCI Raw Functions Quick Reference
Function/Page  Purpose 

OCIRawAllocSize()  

Get allocated size of raw memory in bytes  

OCIRawAssignBytes()  

Assign raw bytes to raw  

OCIRawAssignRaw()  

Assign raw to raw  

OCIRawPtr()  

Get raw data Pointer  

OCIRawResize()  

Resize memory of variable-length raw  

OCIRawSize()  

Get raw size  


OCIRawAllocSize()

Purpose

Gets allocated size of raw memory in bytes.

Syntax

sword OCIRawAllocSize ( OCIEnv             *env,
                        OCIError           *err,
                        CONST OCIRaw       *raw,
                        ub4                *allocsize );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

Raw data whose allocated size in bytes is returned. This must be a non-NULL pointer.

allocsize (OUT)

The allocated size of raw memory in bytes is returned.

Comments

The allocated size is greater than or equal to the actual raw size.

Related Functions

OCIErrorGet(), OCIRawResize(), OCIRawSize()


OCIRawAssignBytes()

Purpose

Assigns raw bytes of type ub1* to Oracle OCIRaw* datatype.

Syntax

sword OCIRawAssignBytes ( OCIEnv             *env,
                          OCIError           *err, 
                          CONST ub1          *rhs,
                          ub4                rhs_len,
                          OCIRaw             **lhs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

rhs (IN)

Right-hand side (source) of the assignment, of datatype ub1.

rhs_len (IN)

Length of the rhs raw bytes.

lhs (IN/OUT)

Left-hand side (target) of the assignment OCIRaw data.

Comments

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.

Related Functions

OCIErrorGet(), OCIRawAssignRaw()


OCIRawAssignRaw()

Purpose

Assign one Oracle raw datatype to another Oracle raw datatype.

Syntax

sword OCIRawAssignRaw ( OCIEnv             *env,
                        OCIError           *err, 
                        CONST OCIRaw       *rhs, 
                        OCIRaw             **lhs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

rhs (IN)

Right-hand side (source) of the assignment; OCIRaw data.

lhs (IN/OUT)

Left-hand side (target) of the assignment; OCIRaw data.

Comments

Assigns rhs raw to lhs raw. The lhs raw may be resized depending upon the size of the rhs.

Related Functions

OCIErrorGet(), OCIRawAssignBytes()


OCIRawPtr()

Purpose

Gets the pointer to raw data.

Syntax

ub1 *OCIRawPtr ( OCIEnv             *env,
                 CONST OCIRaw       *raw );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

raw (IN)

Pointer to the data of a given raw is returned.

Comments

None.

Related Functions

OCIErrorGet(), OCIRawAssignRaw()


OCIRawResize()

Purpose

Resizes the memory of a given variable-length raw.

Syntax

sword OCIRawResize ( OCIEnv          *env, 
                     OCIError        *err,
                     ub2             new_size, 
                     OCIRaw          **raw );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

New size of the raw data in bytes.

raw (IN)

Variable-length raw pointer; the raw is resized to new_size.

Comments

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.

Related Functions

OCIErrorGet(), OCIRawAllocSize(), OCIRawSize()


OCIRawSize()

Purpose

Returns the size of a given raw in bytes.

Syntax

ub4 OCIRawSize ( OCIEnv             *env,
                 CONST OCIRaw       *raw );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

raw (IN/OUT)

Raw whose size is returned.

Comments

None.

Related Functions

OCIErrorGet(), OCIRawAllocSize(), OCIRawSize()

OCI Ref Functions

This section describes the OCI Ref functions.

Table 17-6 OCI Datatype Mapping and Manipulation Functions Quick Reference
Function/Page  Purpose 

OCIRefAssign()  

Assign one REF to another  

OCIRefClear()  

Clear or nullify a REF  

OCIRefFromHex()  

Convert hexadecimal string to REF  

OCIRefHexSize()  

Return size of hexadecimal representation of REF  

OCIRefIsEqual()  

Compare two REFs for equality  

OCIRefIsNull()  

Test if a REF is NULL  

OCIRefToHex()  

Convert REF to hexadecimal string  


OCIRefAssign()

Purpose

Assigns one REF to another, such that both reference the same object.

Syntax

sword OCIRefAssign ( OCIEnv             *env, 
                     OCIError           *err, 
                     CONST OCIRef       *source, 
                     OCIRef             **target );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

source (IN)

REF to copy from.

target (IN/OUT)

REF to copy to.

Comments

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.

Related Functions

OCIErrorGet(), OCIRefIsEqual()


OCIRefClear()

Purpose

Clears or nullifies a given REF.

Syntax

void OCIRefClear ( OCIEnv        *env,
                   OCIRef        *ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

ref (IN/OUT)

REF to clear.

Comments

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 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 non-operational.

Related Functions

OCIErrorGet(), OCIRefIsNull()


OCIRefFromHex()

Purpose

Converts the given hexadecimal string into a REF.

Syntax

sword OCIRefFromHex ( OCIEnv              *env, 
                      OCIError            *err, 
                      CONST OCISvcCtx     *svc, 
                      CONST text          *hex, 
                      ub4                 length, 
                      OCIRef              **ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

svc (IN)

OCI service context handle; if the resulting ref is initialized with this service context.

hex (IN)

Hexadecimal text string, previously output by OCIRefToHex(), to convert into a REF.

length (IN)

Length of the hexadecimal text string.

ref (IN/OUT)

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.

Comments

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.

Related Functions

OCIErrorGet(), OCIRefToHex()


OCIRefHexSize()

Purpose

Returns the size of the hex representation of a REF.

Syntax

ub4 OCIRefHexSize ( OCIEnv            *env,
                    CONST OCIRef      *ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

ref (IN)

REF whose size in hexadecimal representation in bytes is returned.

Returns

The size of the hexadecimal representation of the REF.

Comments

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.

Related Functions

OCIErrorGet(), OCIRefFromHex()


OCIRefIsEqual()

Purpose

Compares two REFs to determine if they are equal.

Syntax

boolean OCIRefIsEqual ( OCIEnv              *env,
                        CONST OCIRef        *x,
                        CONST OCIRef        *y );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

x (IN)

REF to compare.

y (IN)

REF to compare.

Returns

TRUE if the two REFs are equal

FALSE if the two REFs are not equal, or x is NULL, or y is NULL

Comments

Two REFs are equal if and only if they are both referencing the same object, whether persistent or transient.

Related Functions

OCIErrorGet(), OCIRefAssign()


OCIRefIsNull()

Purpose

Tests if a REF is NULL.

Syntax

boolean OCIRefIsNull ( OCIEnv           *env,
                       CONST OCIRef     *ref );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

ref (IN)

REF to test for NULL.

Returns

Returns TRUE if the given REF is NULL; otherwise, returns FALSE.

Comments

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.

Related Functions

OCIErrorGet(), OCIRefClear()


OCIRefToHex()

Purpose

Converts a REF to a hexadecimal string.

Syntax

sword OCIRefToHex ( OCIEnv            *env,
                    OCIError          *err, 
                    CONST OCIRef      *ref, 
                    text              *hex, 
                    ub4               *hex_length );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

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.

hex (OUT)

Buffer that is large enough to contain the resulting hexadecimal string; the contents of the string is opaque to the caller.

hex_length (IN/OUT)

On input specifies the size of the hex buffer on output specifies the actual size of the hexadecimal string being returned in hex.

Comments

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.

Related Functions

OCIErrorGet(), OCIRefFromHex(), OCIRefHexSize(), OCIRefIsNull()

OCI String Functions

This section describes the OCI string functions.

Table 17-7 OCI String Functions Quick Reference
Function/Page  Purpose 

OCIStringAllocSize()  

Get allocated size of string memory in bytes  

OCIStringAssign()  

Assign string to string  

OCIStringAssignText()  

Assign text string to string  

OCIStringPtr()  

Get string pointer  

OCIStringResize()  

Resize string memory  

OCIStringSize()  

Get string size  


OCIStringAllocSize()

Purpose

Gets allocated size of string memory in bytes.

Syntax

sword OCIStringAllocSize ( OCIEnv              *env,
                           CONST OCIString     *vs,
                           ub4                 *allocsize ); 

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

vs (IN)

String whose allocated size in bytes is returned. vs must be a non-NULL pointer.

allocsize (OUT)

The allocated size of string memory in bytes is returned.

Comments

The allocated size is greater than or equal to the actual string size.

Related Functions

OCIErrorGet(), OCIStringResize(), OCIStringSize()


OCIStringAssign()

Purpose

Assigns one string to another string.

Syntax

sword OCIStringAssign ( OCIEnv               *env, 
                        OCIError             *err, 
                        CONST OCIString      *rhs, 
                        OCIString            **lhs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

rhs (IN)

Right-hand side (source) of the assignment.

lhs (IN/OUT)

Left-hand side (target) of the assignment.

Comments

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.

Related Functions

OCIErrorGet(), OCIStringAssignText()


OCIStringAssignText()

Purpose

Assigns the source text string to the target string.

Syntax

sword OCIStringAssignText ( OCIEnv           *env,
                            OCIError         *err, 
                            CONST text       *rhs, 
                            ub2              rhs_len,
                            OCIString        **lhs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

rhs (IN)

Right-hand side (source) of the assignment, a text string.

rhs_len (IN)

Length of the rhs string.

lhs (IN/OUT)

Left-hand side (target) of the assignment.

Comments

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.

Related Functions

OCIErrorGet(), OCIStringAssign()


OCIStringPtr()

Purpose

Gets a pointer to the text of a given string.

Syntax

text *OCIStringPtr ( OCIEnv               *env,
                     CONST OCIString      *vs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

vs (IN)

Pointer to the text of this string is returned.

Comments

None.

Related Functions

OCIErrorGet(), OCIStringAssign()


OCIStringResize()

Purpose

Resizes the memory of a given string.

Syntax

sword OCIStringResize ( OCIEnv          *env,
                        OCIError        *err,
                        ub4             new_size,
                        OCIString       **str );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

New memory size of the string in bytes. new_size must include space for the NULL character ('\0') as string terminator.

str (IN/OUT)

Allocated memory for the string which is freed from the OCI object cache.

Comments

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.

Related Functions

OCIErrorGet(), OCIStringAllocSize(), OCIStringSize()


OCIStringSize()

Purpose

Gets the size of the given string in bytes.

Syntax

ub4 OCIStringSize ( OCIEnv              *env,
                    CONST OCIString     *vs );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

vs (IN)

String whose size is returned.

Comments

The returned size does not include an extra byte for NULL termination.

Related Functions

OCIErrorGet(), OCIStringResize()

OCI Table Functions

This section describes the OCI Table functions.

Table 17-8 OCI Table Functions Quick Reference
Function/Page  Purpose 

OCITableDelete()  

Delete element  

OCITableExists()  

Test whether element exists  

OCITableFirst()  

Return first index of table  

OCITableLast()  

Return last index of table  

OCITableNext()  

Return next available index of table  

OCITablePrev()  

Return previous available index of table  

OCITableSize()  

Return current size of table  


OCITableDelete()

Purpose

Deletes the element at the specified index.

Syntax

sword OCITableDelete ( OCIEnv          *env, 
                       OCIError        *err, 
                       sb4             index, 
                       OCITable        *tbl );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

Index of the element which must be deleted.

tbl (IN)

Table whose element is deleted.

Comments

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.

Note: The position ordinals of the remaining elements of the table are not changed by OCITableDelete(). The delete operation creates holes in the table.

Related Functions

OCIErrorGet(), OCITableExists()


OCITableExists()

Purpose

Tests whether an element exists at the given index.

Syntax

sword OCITableExists ( OCIEnv              *env,
                       OCIError            *err, 
                       CONST OCITable      *tbl,
                       sb4                 index, 
                       boolean             *exists );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

tbl (IN)

Table in which the given index is checked.

index (IN)

Index of the element which is checked for existence.

exists (OUT)

Set to TRUE if element at given index exists; otherwise, it is set to FALSE.

Comments

This function returns an error if any input parameter is NULL.

Related Functions

OCIErrorGet(), OCITableDelete()


OCITableFirst()

Purpose

Returns the index of the first existing element in a given table.

Syntax

sword OCITableFirst ( OCIEnv             *env, 
                      OCIError           *err,
                      CONST OCITable     *tbl, 
                      sb4                *index  );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

tbl (IN)

Table to scan.

index (OUT)

First index of the element which exists in the given table is returned.

Comments

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.

Related Functions

OCIErrorGet(), OCITableDelete(), OCITableLast()


OCITableLast()

Purpose

Returns the index of the last existing element of a table.

Syntax

sword OCITableLast ( OCIEnv              *env, 
                     OCIError            *err, 
                     CONST OCITable      *tbl, 
                     sb4                 *index );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

tbl (IN)

Table to scan.

index (OUT)

Index of the last existing element in the table.

Comments

This function returns an error if the table is empty.

Related Functions

OCIErrorGet(), OCITableFirst(), OCITableNext(), OCITablePrev()


OCITableNext()

Purpose

Returns the index of the next existing element of a table.

Syntax

sword OCITableNext ( OCIEnv             *env, 
                     OCIError           *err, 
                     sb4                index, 
                     CONST OCITable     *tbl, 
                     sb4                *next_index
                     boolean            *exists );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

Index for starting point of scan.

tbl (IN)

Table to scan.

next_index (OUT)

Index of the next existing element after tbl(index).

exists (OUT)

FALSE if no next index is available, else TRUE.

Comments

Returns the smallest position j, greater than index, such that exists(j) is TRUE.

See Also: Refer to the description of OCIStringAllocSize(), regarding the existence of non-data holes in tables.

Related Functions

OCIErrorGet(), OCITablePrev()


OCITablePrev()

Purpose

Returns the index of the previous existing element of a table.

Syntax

sword OCITablePrev ( OCIEnv             *env, 
                     OCIError           *err, 
                     sb4                index,
                     CONST OCITable     *tbl,
                     sb4                *prev_index
                     boolean            *exists );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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 (IN)

Index for starting point of scan.

tbl (IN)

Table to scan.

prev_index (OUT)

Index of the previous existing element before tbl(index).

exists (OUT)

FALSE if no previous index is available, else TRUE.

Comments

Return the largest position j, less than index, such that exists(j) is TRUE.

See Also: Refer to the description of OCIStringAllocSize(), regarding the existence of non-data holes in tables.

Related Functions

OCITableNext()


OCITableSize()

Purpose

Returns the size of the given table, not including deleted elements.

Syntax

sword OCITableSize ( OCIEnv             *env,
                     OCIError           *err,
                     CONST OCITable     *tbl
                     sb4                *size );

Parameters

env (IN/OUT)

The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

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().

tbl (IN)

Nested table whose number of elements is returned.

size (OUT)

Current number of elements in the nested table. The count does not include deleted elements.

Comments

The 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 previous 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.

Related Functions

OCICollSize()




Prev

Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index