# OCI NUMBER Functions

Lists and describes the OCI `NUMBER` functions.

Table 19-11 describes the OCI `NUMBER` functions that are described in this section.

See Also:

OCINumber Examples

Table 19-11 NUMBER Functions

Function Purpose

OCINumberAbs()

Compute the absolute value

OCINumberAdd()

Add a `NUMBER` to a `NUMBER`

OCINumberArcCos()

Compute the arc cosine

OCINumberArcSin()

Compute the arc sine

OCINumberArcTan()

Compute the arc tangent

OCINumberArcTan2()

Compute the arc tangent given two arguments for `NUMBER`

OCINumberAssign()

Assign one `NUMBER` to another

OCINumberCeil()

Compute the ceiling of `NUMBER`

OCINumberCmp()

Compare one `NUMBER` with another `NUMBER`

OCINumberCos()

Compute the cosine

OCINumberDec()

Decrement a `NUMBER`

OCINumberDiv()

Divide a `NUMBER` by a `NUMBER`

OCINumberExp()

Raise e to the specified Oracle `NUMBER` power

OCINumberFloor()

Compute the floor value of a `NUMBER`

OCINumberFromInt()

Convert an integer to an Oracle `NUMBER`

OCINumberFromReal()

Convert a real type to an Oracle `NUMBER`

OCINumberFromText()

Convert a string to an Oracle `NUMBER`

OCINumberHypCos()

Compute the hyperbolic cosine

OCINumberHypSin()

Compute the hyperbolic sine

OCINumberHypTan()

Compute the hyperbolic tangent

OCINumberInc()

Increment an Oracle `NUMBER`

OCINumberIntPower()

Raise a given base to an integer power

OCINumberIsInt()

Test if a `NUMBER` is an integer

OCINumberIsZero()

Test if a `NUMBER` is zero

OCINumberLn()

Compute the natural logarithm

OCINumberLog()

Compute the logarithm to an arbitrary base

OCINumberMod()

Gets the modulus (remainder) of the division of two Oracle `NUMBER`s

OCINumberMul()

Multiply one Oracle `NUMBER` by another Oracle `NUMBER`

OCINumberNeg()

Negates an Oracle `NUMBER`

OCINumberPower()

Raises a given base to a given exponent

OCINumberPrec()

Round a `NUMBER` to a specified number of decimal places

OCINumberRound()

Round an Oracle `NUMBER` to a specified decimal place

OCINumberSetPi()

Initialize a `NUMBER` to pi

OCINumberSetZero()

Initialize a `NUMBER` to zero

OCINumberShift()

Multiply by 10, shifting a specified number of decimal places

OCINumberSign()

Obtain the sign of an Oracle `NUMBER`

OCINumberSin()

Compute the sine

OCINumberSqrt()

Compute the square root of a `NUMBER`

OCINumberSub()

Subtract a `NUMBER` from a `NUMBER`

OCINumberTan()

Compute the tangent

OCINumberToInt()

Convert an Oracle `NUMBER` to an integer

OCINumberToReal()

Convert an Oracle `NUMBER` to a real type

OCINumberToRealArray()

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

OCINumberToText()

Convert an Oracle `NUMBER` to a string

OCINumberTrunc()

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

Returns

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

Related Functions

OCIErrorGet()

## OCINumberAdd()

Adds a `NUMBER` to another `NUMBER`.

Purpose

Adds a `NUMBER` to another `NUMBER`.

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)

The first `NUMBER` to be added to the second `NUMBER`.

result (OUT)

Result of adding `number1` to `number2`.

Returns

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

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

Returns

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

Related Functions

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

Returns

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

Related Functions

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

Returns

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

Related Functions

## OCINumberArcTan2()

Takes the arc tangent given two arguments for Oracle `NUMBER`.

Purpose

Takes the arc tangent given two arguments for Oracle `NUMBER`.

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.

Returns

This function returns an error if any of the `NUMBER` arguments is `NULL` or if `number2` equals 0.

## 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` identified by `from` to the `NUMBER` identified by `to`.

Returns

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

Related Functions

## 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 that contains the ceiling value of the input `NUMBER`.

Returns

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

Related Functions

## OCINumberCmp()

Compares one Oracle `NUMBER` with another Oracle `NUMBER`.

Purpose

Compares one Oracle `NUMBER` with another Oracle `NUMBER`.

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)

The first `NUMBER` to compare with the second `NUMBER`.

result (OUT)

Comparison result as specified in Table 19-12.

Table 19-12 Comparison Results Returned by the result Parameter for OCINumberCmp()

Comparison Result Output in result Parameter

`number1` < `number2`

negative

`number1` = `number2`

`0`

`number1` > `number2`

positive

Returns

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

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

Returns

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

Related Functions

## OCINumberDec()

Purpose

Decrements an Oracle `NUMBER` in place.

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.

Comments

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

Returns

This function returns an error if the input `NUMBER` is `NULL`.

Related Functions

OCINumberInc()

## OCINumberDiv()

Divides one Oracle `NUMBER` by another Oracle `NUMBER`.

Purpose

Divides one Oracle `NUMBER` by another Oracle `NUMBER`.

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 the result in `result`.

Returns

This function returns an error if any of the following statements is true:

• Any of the `NUMBER` arguments is `NULL`.

• There is an underflow error.

• There is a divide-by-zero error.

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

Returns

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

Related Functions

## OCINumberFloor()

Purpose

Computes the floor (round down) 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 (round down) value of the input `NUMBER`.

Returns

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

Related Functions

## OCINumberFromInt()

Purpose

Converts an integer to an Oracle `NUMBER`.

Syntax

```sword OCINumberFromInt ( OCIError            *err,
const void          *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`.

Comments

This is a native type conversion function. It converts any Oracle standard system-native integer type, such as `ub4` or `sb2`, to an Oracle `NUMBER`.

Returns

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

## OCINumberFromReal()

Purpose

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

Syntax

```sword OCINumberFromReal ( OCIError           *err,
const void         *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 system-native floating-point type to an Oracle `NUMBER`.

Returns

This function returns an error if `number` or `rnum` is `NULL`, or if `rnum_length` equals zero.

Related Functions

## OCINumberFromText()

Converts a character string to an Oracle `NUMBER`.

Purpose

Converts a character string to an 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)

Globalization support format specification. If it is the `NULL` string (""), then the default parameters for the session are 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. See the `TO_NUMBER` conversion function described in the Oracle Database SQL Language Reference for a description of format and multilingual parameters.

Returns

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.

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

Returns

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

Note:

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

Related Functions

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

Returns

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

Note:

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

Related Functions

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

Returns

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

Note:

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

Related Functions

## OCINumberInc()

Purpose

Increments an Oracle `NUMBER`.

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.

Comments

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

Returns

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.

Returns

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

Related Functions

## 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; otherwise, `FALSE`

Returns

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

Related Functions

## OCINumberIsZero()

Purpose

Tests if the given `NUMBER` equals 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`.

Returns

This function returns an error if the `NUMBER` argument is `NULL`.

Related Functions

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

Returns

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

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

Returns

This function returns an error if:

• Any of the `NUMBER` arguments is `NULL`

• The value of `number` <= 0

• The value of `base` <= 0

Related Functions

## OCINumberMod()

Purpose

Gets the modulus (remainder) of the division of two Oracle `NUMBER`s.

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.

Returns

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

Related Functions

## OCINumberMul()

Multiplies one Oracle `NUMBER` by another Oracle `NUMBER`.

Purpose

Multiplies one Oracle `NUMBER` by another Oracle `NUMBER`.

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 the result in `result`.

Returns

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

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

Returns

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

Related Functions

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

Returns

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

Related Functions

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

Returns

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

Related Functions

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

Returns

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

Related Functions

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

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

num (IN/OUT)

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

Returns

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)

Oracle `NUMBER` whose sign is returned.

result (OUT)

Table 19-13 lists the possible return values.

Table 19-13 Values of result

Value of number Output in result Parameter

`number` < 0

-1

`number` == 0

0

`number` > 0

1

Returns

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

Related Functions

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

Returns

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

Related Functions

## 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 that contains the square root of the input `NUMBER`.

Returns

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

Related Functions

## OCINumberSub()

Subtracts one Oracle `NUMBER` from another Oracle `NUMBER`.

Purpose

Subtracts one Oracle `NUMBER` from another Oracle `NUMBER`.

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 the result in `result`.

Returns

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

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

Returns

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

Related Functions

## OCINumberToInt()

Purpose

Converts an Oracle `NUMBER` type to integer.

Syntax

```sword OCINumberToInt ( OCIError              *err,
const OCINumber       *number,
uword                 rsl_length,
uword                 rsl_flag,
void                  *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)

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

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

Returns

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

## OCINumberToReal()

Purpose

Converts an Oracle `NUMBER` type to a real type.

Syntax

```sword OCINumberToReal ( OCIError            *err,
const OCINumber     *number,
uword               rsl_length,
void                *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)

Oracle `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 system-native real type. This function only converts `NUMBER`s up to LDBL_DIG, DBL_DIG, or FLT_DIG digits of precision and removes trailing zeros. These constants are defined in `float.h`.

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

Related Functions

## OCINumberToRealArray()

Purpose

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

Syntax

```sword OCINumberToRealArray ( OCIError         *err,
const OCINumber  **number,
uword            elems,
uword            rsl_length,
void             *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.

Comments

Native type conversion function that converts an Oracle `NUMBER` into a system-native real type. This function only converts numbers up to `LDBL_DI``G`, `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`, if the function completes successfully; `OCI_INVALID_HANDLE`, if `err` is `NULL`; or `OCI_ERROR`, if `number` or `rsl` is `NULL` or `rsl_length` is 0.

Related Functions

## OCINumberToText()

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

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,
OraText              *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)

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

Comments

See the `TO_NUMBER` conversion function described in the Oracle Database SQL Language Referencefor a description of format and globalization support parameters.

The converted number string is stored in `buf`, up to a maximum of `buf_size` bytes.

Returns

This function returns an error if:

• The value of `number` or `buf` is `NULL`

• The buffer is too small

• An invalid format or invalid multibyte format is passed

• A number to text translation for given format causes an overflow

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

Returns

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

Related Functions