Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part Number B10779-01

## OCI NUMBER Functions

This section describes the OCI `NUMBER` functions.

##### Table 18-12 NUMBER Functions
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 `NUMBER`s

`OCINumberAssign()`

Assigns one `NUMBER` to another

`OCINumberCeil()`

Computes the ceiling of `NUMBER`

`OCINumberCmp()`

Compares `NUMBER`s

`OCINumberCos()`

Computes the cosine

`OCINumberDec()`

Decrements a `NUMBER`

`OCINumberDiv()`

Divides two `NUMBER`s

`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 `NUMBER`s

`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 `NUMBER`s

`OCINumberTan()`

Computes the tangent

`OCINumberToInt()`

Converts an Oracle `NUMBER` to an integer

`OCINumberToReal()`

Converts an Oracle `NUMBER` to a real

`OCINumberToRealArray()`

Converts an array of `NUMBER` to a real array.

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

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

### Related Functions

`OCIErrorGet()`, `OCINumberSign()`

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

result (OUT)

Result of adding `number1` to `number2`.

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.

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.

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.

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.

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.

Assigns the number identified 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.

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)

`NUMBER`s to compare.

result (OUT)

Comparison result:

##### Table 18-13 Comparison Results
Comparison result Output in result parameter

number1 < number2

negative

number1 = number2

0

number1 > number2

positive

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.

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

### Related Functions

`OCIErrorGet()`, `OCINumberArcCos()`

## OCINumberDec()

### Purpose

Decrements an OCINumber.

### Syntax

```sword OCINumberDec ( 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.

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

## OCINumberDiv()

### Purpose

Divides two Oracle `NUMBER`s.

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

Divides `number1` by `number2` and returns result in `result`.

This function returns an error if:

• any of the number arguments is `NULL`
• there is an underflow error
• there is a divide-by-zero error

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

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

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:

• OCI_`NUMBER`_UNSIGNED - Unsigned values
• OCI_`NUMBER`_SIGNED - Signed values
number (OUT)

Given integer converted to Oracle number.

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

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 OraText      *str,
ub4                str_length,
CONST OraText      *fmt,
ub4                fmt_length,
CONST OraText      *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)

Global Support format specification. If it is the `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`.

Converts the given string to a `NUMBER` according to the specified format. Refer to the TO_NUMBER conversion function described in the Oracle Database SQL Reference for a description of format and multilingual parameters.

This function returns an error if there is an invalid format, an invalid multibyte 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.

This function returns an error if either of the NUMBER arguments is `NULL`.

 Caution: 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.

This function returns an error if either of the `NUMBER` arguments is `NULL`.

 Caution: 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.

This function returns an error if either of the `NUMBER` arguments is `NULL`.

 Caution: An Oracle `NUMBER` overflow causes an unpredictable result value.

### Related Functions

`OCIErrorGet()`, `OCINumberHypCos()`, `OCINumberHypSin()`

## OCINumberInc()

### Purpose

Increments an OCINumber.

### Syntax

```sword 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.

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.

This function returns an error if either 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`

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

This function returns an error if the `NUMBER` argument 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.

This function returns an error if either of the `NUMBER` arguments is `NULL`, or if `number` 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.

This function returns an error if:

• any of the `NUMBER` arguments is `NULL`
• `number` <= 0
• `base` <= 0

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

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.

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

This function returns an error if either 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.

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.

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.

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.

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)

A valid OCI error handle. This function does not check for errors because the function will never produce an error.

num (IN/OUT)

NUMBER to initialize to zero value.

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.

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:

##### Table 18-14 Values of result
Value of number Output in result parameter

number < 0

-1

number == 0

0

number > 0

1

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.

This function returns an error if either 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`.

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

### Related Functions

`OCIErrorGet()`, `OCINumberPower()`

## OCINumberSub()

### Purpose

Subtract two Oracle `NUMBER`s.

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

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.

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:

• OCI_NUMBER_UNSIGNED - Unsigned values
• OCI_NUMBER_SIGNED - Signed values
rsl (OUT)

Pointer to space for the result.

This is a native type conversion function. It converts the given Oracle `NUMBER` into an integer of the form `xbn`, 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.

This is a native type conversion function. It converts an Oracle `NUMBER` into a machine-native real type. This function only converts `NUMBER`s up to LDBL_DIG, DBL_DIG, or FLT_DIG digits of precision and removes trailing zeroes. These constants are defined in `float.h`.

You must pass a valid `OCINumber` to this function. Otherwise, the result is undefined.

### Related Functions

`OCIErrorGet()`, `OCINumberFromReal()`

## OCINumberToRealArray()

### Purpose

Converts an array of `NUMBER` to an array of real.

### Syntax

```sword OCINumberToRealArray ( OCIError         *err,
CONST OCINumber  **number,
uword            elems,
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)

Pointer to array of `NUMBER` to be converted.

elems (IN)

Maximum number of `NUMBER` pointers.

rsl_length (IN)

The size of the desired result, that is, `sizeof({ float | double | long double` }`)`.

rsl (OUT)

Pointer to array of space for storing the result.

Native type conversion function that 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 constants are defined in the `float.h` header file.

You must pass a valid `OCINumber` to this function. Otherwise, the result is undefined.

### Returns

• OCI_SUCCESS - the function completes successfully.
• OCI_INVALID_HANDLE - if `err` is `NULL`.
• OCI_ERROR - if `number` or `rsl` is `NULL`, or `rsl_length` is 0.

### Related Functions

`OCIErrorGet()`, `OCINumberToReal()`

## OCINumberToText()

### Purpose

Converts an Oracle `NUMBER` to a character string according to a specified format.

### Syntax

```sword OCINumberToText ( OCIError             *err,
CONST OCINumber      *number,
CONST OraText        *fmt,
ub4                  fmt_length,
CONST OraText        *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)

Global Support format specification. If it is 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.

Refer to the TO_NUMBER conversion function described in the Oracle Database SQL Reference for a description of format and Global Support parameters.

The converted number string is stored in `buf`, up to a maximum of `buf_size` bytes. This function returns an error if:

• `number` or `buf` is `NULL`
• buffer is too small
• invalid format or invalid multibyte format is passed
• number to text translation for given format causes an overflow

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

This function returns an error if any of the `NUMBER` arguments is `NULL`.
`OCIErrorGet()`, `OCINumberRound()`