# OCI Date, Datetime, and Interval Functions

Table 20-4 describes the OCI date and interval functions that are described in this section.

Table 20-4 Date Functions

Function Purpose

Assign date

Check if the given date is valid

Compare dates

Get number of days between two dates

Convert string to date

Get the date portion of a date

Get the time portion of a date

Get date of last day of month

Get date of next day

Set the date portion of a date

Set the time portion of a date

Get the current system date and time

Perform a datetime assignment

Check if the given date is valid

Compare two datetime values

Construct a datetime descriptor

Convert one datetime type to another

Convert an array of size `OCI_DT_ARRAYLEN` to an `OCIDateTime` descriptor

Convert the given string to Oracle datetime type in the `OCIDateTime` descriptor, according to the specified format

Get the date (year, month, day) portion of a datetime value

Get the time (hour, min, second, fractional second) of a datetime value

Get the time zone name portion of a datetime value

Get the time zone (hour, minute) portion of a datetime value

Add an interval to a datetime to produce a resulting datetime

Subtract an interval from a datetime and store the result in a datetime

Take two datetimes as input and store their difference in an interval

Get the system current date and time as a time stamp with time zone

Convert an `OCIDateTime` descriptor to an array

Convert the given date to a string according to the specified format

Convert date to string

Convert date from one time zone to another zone

Add two intervals to produce a resulting interval

Copy one interval to another

Check the validity of an interval

Compare two intervals

Divide an interval by an Oracle `NUMBER` to produce an interval

Convert an Oracle `NUMBER` to an interval

When given an interval string, return the interval represented by the string

Return an `OCI_DTYPE_INTERVAL_DS`

Get values of day, hour, minute, and second from an interval

Get year and month from an interval

Multiply an interval by an Oracle `NUMBER` to produce an interval

Set day, hour, minute, and second in an interval

Set year and month in an interval

Subtract two intervals and stores the result in an interval

Convert an interval to an Oracle NUMBER

When given an interval, produce a string representing the interval

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

Returns

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

Related Functions

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

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 30 – 3 months = August 31. Otherwise the `result` date has the same day component as `date`.

Returns

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

Related Functions

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

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

Related Functions

## 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, it returns the logical operator OR combination of all error bits specified in Table 20-5.

Table 20-5 Error Bits Returned by the valid Parameter for OCIDateCheck()

Macro Name Bit Number Error

`OCI_DATE_INVALID_DAY`

0x1

`OCI_DATE_DAY_BELOW_VALID`

0x2

`OCI_DATE_INVALID_MONTH`

0x4

`OCI_DATE_MONTH_BELOW_VALID`

0x8

`OCI_DATE_INVALID_YEAR`

0x10

`OCI_DATE_YEAR_BELOW_VALID`

0x20

`OCI_DATE_INVALID_HOUR`

0x40

`OCI_DATE_HOUR_BELOW_VALID`

0x80

`OCI_DATE_INVALID_MINUTE`

0x100

`OCI_DATE_MINUTE_BELOW_VALID`

0x200

`OCI_DATE_INVALID_SECOND`

0x400

`OCI_DATE_SECOND_BELOW_VALID`

0x800

`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

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 is:

```OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID | OCI_DATE_INVALID_HOUR |
OCI_DATE_INVALID_MINUTE.
```

Returns

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

Related Functions

## 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 as listed in Table 20-6.

Table 20-6 Comparison Results

Comparison Result Output in result Parameter

`date1` < `date2`

-1

`date1` = `date2`

0

`date1` > `date2`

1

Returns

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

Related Functions

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

When the number of days between `date1` and `date2` is computed, the time is ignored.

Returns

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

Related Functions

## OCIDateFromText()

Purpose

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

Syntax

```sword OCIDateFromText ( OCIError           *err,
const OraText      *date_str,
ub4                d_str_length,
const OraText      *fmt,
ub1                fmt_length,
const OraText      *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.

See the `TO_DATE` conversion function described in the Oracle Database SQL Language Referencefor a description of format and multilingual arguments.

Returns

This function returns an error if it receives an invalid format, language, or input string.

Related Functions

## OCIDateGetDate()

Purpose

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

None.

Related Functions

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

Returns

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

Related Functions

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

Returns

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

Related Functions

## OCIDateNextDay()

Purpose

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

Syntax

```sword OCIDateNextDay ( OCIError            *err,
const OCIDate       *date,
const OraText       *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 the 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` that is later than `date`.

Returns

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

Example

The following code example shows how to get the date of the next Monday after April 18, 1996 (a Thursday).

Getting the Date for a Specific Day After a Specified Date

```OCIDate one_day, next_day;
/* Add code here to set one_day to be '18-APR-96' */
OCIDateNextDay(err, &one_day, "MONDAY", strlen("MONDAY"), &next_day);
```

`OCIDateNextDay()` returns "22-APR-96".

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

Related Functions

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

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.

None.

Related Functions

OCIDateGetTime()

## OCIDateSysDate()

Purpose

Gets the current system date and time of the client.

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 of the client.

None.

Related Functions

OCIErrorGet()

## OCIDateTimeAssign()

Purpose

Performs a datetime assignment.

Syntax

```sword OCIDateTimeAssign ( void                *hndl,
OCIError            *err,
const OCIDateTime   *from,
OCIDateTime         *to );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle. If a user session handle is passed, the conversion occurs in the session's `NLS_LANGUAGE` and the session's `NLS_CALENDAR`; otherwise, the default is used.

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)

Source, right-hand side (`rhs`) datetime to be assigned.

to (OUT)

Target, left-hand side (`lhs`) of assignment.

This function performs an assignment from the `from` datetime to the `to` datetime for any of the datetime types listed in the description of the `type` parameter.

The `type` of the output is the same as that of the input.

Returns

`OCI_SUCCESS`; or OCI_ERROR.

Related Functions

## OCIDateTimeCheck()

Purpose

Checks if the given date is valid.

Syntax

```sword OCIDateTimeCheck ( void                *hndl,
OCIError            *err,
const OCIDateTime   *date,
ub4                 *valid );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle. If a user session handle is passed, the conversion occurs in the session's `NLS_LANGUAGE` and the session's `NLS_CALENDAR`, otherwise, the default is used.

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 date to be checked.

valid (OUT)

Returns zero for a valid date; otherwise, it returns the logical operator OR combination of all the error bits specified in Table 20-7.

Table 20-7 Error Bits Returned by the valid Parameter for OCIDateTimeCheck()

Macro Name Bit Number Error

`OCI_DT_INVALID_DAY`

0x1

`OCI_DT_DAY_BELOW_VALID`

0x2

`OCI_DT_INVALID_MONTH`

0x4

`OCI_DT_MONTH_BELOW_VALID`

0x8

`OCI_DT_INVALID_YEAR`

0x10

`OCI_DT_YEAR_BELOW_VALID`

0x20

`OCI_DT_INVALID_HOUR`

0x40

`OCI_DT_HOUR_BELOW_VALID`

0x80

`OCI_DT_INVALID_MINUTE`

0x100

`OCI_DT_MINUTE_BELOW_VALID`

0x200

`OCI_DT_INVALID_SECOND`

0x400

`OCI_DT_SECOND_BELOW_VALID`

0x800

`OCI_DT_DAY_MISSING_FROM_1582`

0x1000

Day is one of those missing from 1582

`OCI_DT_YEAR_ZERO`

0x2000

Year may not equal zero

`OCI_DT_INVALID_TIMEZONE`

0x4000

`OCI_DT_INVALID_FORMAT`

0x8000

So, for example, if the date passed in was 2/0/1990 25:61:10 in (month/day/year hours:minutes:seconds format), the error returned is:

``` OCI_DT_INVALID_DAY | OCI_DT_DAY_BELOW_VALID |
OCI_DT_INVALID_HOUR | OCI_DT_INVALID_MINUTE.
```

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if err is a `NULL` pointer; `OCI_ERROR`, if `date` or `valid` is a `NULL` pointer.

Related Functions

OCIDateTimeAssign()

## OCIDateTimeCompare()

Purpose

Compares two datetime values.

Syntax

```sword OCIDateTimeCompare ( void               *hndl,
OCIError           *err,
const OCIDateTime  *date1,
const OCIDateTime  *date2,
sword              *result );
```

Parameters

hndl (IN/OUT)

The OCI user session handle or environment handle.

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 as listed in Table 20-8.

Table 20-8 Comparison Results Returned by the result Parameter for OCIDateTimeCompare()

Comparison Result Output in result Parameter

`date1` < `date2`

-1

`date1` = `date2`

0

`date1` > `date2`

1

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if err is a `NULL` pointer; `OCI_ERROR`, if an invalid date is used or if the input date arguments are not of mutually comparable types.

Related Functions

OCIDateTimeConstruct()

## OCIDateTimeConstruct()

Purpose

Constructs a datetime descriptor.

Syntax

```sword OCIDateTimeConstruct ( void          *hndl,
OCIError      *err,
OCIDateTime   *datetime,
sb2           year,
ub1           month,
ub1           day,
ub1           hour,
ub1           min,
ub1           sec,
ub4           fsec,
OraText       *timezone,
size_t        timezone_length );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor.

year (IN)

Year value.

month (IN)

Month value.

day (IN)

Day value.

hour (IN)

Hour value.

min (IN)

Minute value.

sec (IN)

Second value.

fsec (IN)

Fractional second value.

timezone (IN)

Time zone string. A string representation of time zone displacement is the difference (in hours and minutes) between local time and UTC (Coordinated Universal Time—formerly Greenwich Mean Time) in the format "[+|-][HH:MM]". For example, "-08:00".

timezone_length (IN)

Length of the time zone string.

The type of the datetime is the type of the `OCIDateTime` descriptor. Only the relevant fields based on the type are used. For types with a time zone, the date and time fields are assumed to be in the local time of the specified time zone.

If the time zone is not specified, then the session default time zone is assumed.

Returns

`OCI_SUCCESS`; or `OCI_ERROR`, if datetime is not valid.

Related Functions

## OCIDateTimeConvert()

Purpose

Converts one datetime type to another.

Syntax

```sword OCIDateTimeConvert ( void         *hndl,
OCIError     *err,
OCIDateTime  *indate,
OCIDateTime  *outdate );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

indate (IN)

A pointer to the input date.

outdate (OUT)

A pointer to the output datetime.

This function converts one datetime type to another. The result type is the type of the `outdate` descriptor. The session default time zone (`ORA_SDTZ`) is used when converting a datetime without a time zone to one with a time zone.

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE` if `err` is `NULL`; or `OCI_ERROR`, if the conversion is not possible with the given input values.

Related Functions

OCIDateTimeCheck()

## OCIDateTimeFromArray()

Purpose

Converts an array containing a date to an `OCIDateTime` descriptor.

Syntax

```sword OCIDateTimeFromArray ( void               *hndl,
OCIError           *err,
const ub1          *inarray,
ub4                *len
ub1                type,
OCIDateTime        *datetime,
const OCIInterval  *reftz,
ub1                fsprec );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

inarray(IN)

Array of ub1, containing the date.

len (IN)

Length of `inarray`.

type (IN)

Type of the resulting datetime. The array is converted to the specific SQLT type.

datetime (OUT)

Pointer to an `OCIDateTime` descriptor.

reftz (IN)

Descriptor for `OCIInterval` used as a reference when converting a `SQLT_TIMESTAMP_LT``Z` type.

fsprec (IN)

Fractional second precision of the resulting datetime.

Returns

`OCI_SUCCESS`; or `OCI_ERROR` if `type` is invalid.

Related Functions

## OCIDateTimeFromText()

Purpose

Converts the given string to an Oracle datetime type in the `OCIDateTime` descriptor, according to the specified format.

Syntax

```sword OCIDateTimeFromText ( void               *hndl,
OCIError           *err,
const OraText      *date_str,
size_t             dstr_length,
const OraText      *fmt,
ub1                fmt_length,
const OraText      *lang_name,
size_t             lang_length,
OCIDateTime        *datetime );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle. If a user session handle is passed, the conversion occurs in the session's NLS_LANGUAGE and the session's NLS_CALENDAR; otherwise, the default is used.

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)

The input string to be converted to an Oracle datetime.

dstr_length (IN)

The size of the input string. If the length is –1, then `date_str` is treated as a `NULL`-terminated string.

fmt (IN)

The conversion format. If `fmt` is a `NULL` pointer, then the string is expected to be in the default format for the datetime type.

fmt_length (IN)

The length of the `fmt` parameter.

lang_name (IN)

Specifies the language in which the names and abbreviations of months and days are specified. The default language of the session is used if `lang_name` is `NULL` (`lang_name` = `(text *)0`).

lang_length (IN)

The length of the `lang_name` parameter.

datetime (OUT)

The given string converted to a date.

See the description of the `TO_DATE` conversion function in the Oracle Database SQL Language Reference for a description of the format argument.

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE` if `err` is `NULL`; or `OCI_ERROR`, if any of the following is true:

• An invalid format is used.

• An unknown language is used.

• An invalid input string is used.

Related Functions

## OCIDateTimeGetDate()

Purpose

Gets the date (year, month, day) portion of a datetime value.

Syntax

```sword OCIDateTimeGetDate ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
sb2                *year,
ub1                *month,
ub1                *day );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor from which date information is retrieved.

year (OUT)
month (OUT)
day (OUT)

The retrieved year, month, and day values.

This function gets the date (year, month, day) portion of a datetime value.

Returns

`OCI_SUCCESS` or `OCI_ERROR`.

Related Functions

OCIDateTimeGetTime()

## OCIDateTimeGetTime()

Purpose

Gets the time (hour, min, second, fractional second) of a datetime value.

Syntax

```sword OCIDateTimeGetTime ( void          *hndl,
OCIError      *err,
OCIDateTime   *datetime,
ub1           *hour,
ub1           *min,
ub1           *sec,
ub4           *fsec );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor from which time information is retrieved.

hour (OUT)

The retrieved hour value.

min (OUT)

The retrieved minute value.

sec (OUT)

The retrieved second value.

fsec (OUT)

The retrieved fractional second value.

This function gets the time portion (hour, min, second, fractional second) from a given datetime value.

This function returns an error if the given datetime does not contain time information.

Returns

`OCI_SUCCESS`; or `OCI_ERROR`, if datetime does not contain time (`SQLT_DATE`).

Related Functions

OCIDateTimeGetDate()

## OCIDateTimeGetTimeZoneName()

Purpose

Gets the time zone name portion of a datetime value.

Syntax

```sword OCIDateTimeGetTimeZoneName ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
ub1                *buf,
ub4                *buflen, );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor.

buf (OUT)

Buffer to store the retrieved time zone name.

buflen (IN/OUT)

The size of the buffer (IN). The size of the name field (OUT)

This function gets the time portion (hour, min, second, fractional second) from a given datetime value.

This function returns an error if the given datetime does not contain time information.

Returns

`OCI_SUCCESS`; or `OCI_ERROR`, if datetime does not contain a time zone (`SQLT_DATE`, `SQLT_TIMESTAMP`).

Related Functions

## OCIDateTimeGetTimeZoneOffset()

Purpose

Gets the time zone (hour, minute) portion of a datetime value.

Syntax

```sword OCIDateTimeGetTimeZoneOffset ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
sb1                *hour,
sb1                *min, );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor.

hour (OUT)

The retrieved time zone hour value.

min (OUT)

The retrieved time zone minute value.

This function gets the time zone hour and the time zone minute portion from a given datetime value.

This function returns an error if the given datetime does not contain time information.

Returns

`OCI_SUCCESS`; or `OCI_ERROR`, if datetime does not contain a time zone (`SQLT_DATE`, `SQLT_TIMESTAMP`).

Related Functions

Purpose

Adds an interval to a datetime to produce a resulting datetime.

Syntax

```sword OCIDateTimeIntervalAdd ( void         *hndl,
OCIError     *err,
OCIDateTime  *datetime,
OCIInterval  *inter,
OCIDateTime  *outdatetime );
```

Parameters

hndl (IN)

The user session or environment handle. If a session handle is passed, the addition occurs in the session default calendar.

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

datetime (IN)

Pointer to the input datetime.

inter (IN)

Pointer to the input interval.

outdatetime (OUT)

Pointer to the output datetime. The output datetime is of same type as the input datetime.

Returns

`OCI_SUCCESS`, if the function completes successfully; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if the resulting date is before Jan 1, -4713 or is after Dec 31, 9999.

Related Functions

OCIDateTimeIntervalSub()

## OCIDateTimeIntervalSub()

Purpose

Subtracts an interval from a datetime and stores the result in a datetime.

Syntax

```sword OCIDateTimeIntervalSub ( void         *hndl,
OCIError     *err,
OCIDateTime  *datetime,
OCIInterval  *inter,
OCIDateTime  *outdatetime );
```

Parameters

hndl (IN)

The user session or environment handle. If a session handle is passed, the subtraction occurs in the session default calendar. The interval is assumed to be in the session calendar.

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

datetime (IN)

Pointer to the input datetime value.

inter (IN)

Pointer to the input interval.

outdatetime (OUT)

Pointer to the output datetime. The output datetime is of same type as the input datetime.

Returns

`OCI_SUCCESS`, if the function completes successfully; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if the resulting date is before Jan 1, -4713 or is after Dec 31, 9999.

Related Functions

## OCIDateTimeSubtract()

Purpose

Takes two datetimes as input and stores their difference in an interval.

Syntax

```sword OCIDateTimeSubtract ( void         *hndl,
OCIError     *err,
OCIDateTime  *indate1,
OCIDateTime  *indate2,
OCIInterval  *inter );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

indate1 (IN)

Pointer to the subtrahend (number to be subtracted).

indate2 (IN)

Pointer to the minuend (number to be subtracted from).

inter (OUT)

Pointer to the output interval.

Returns

`OCI_SUCCESS`, if the function completes successfully; `OCI_INVALID_HANDLE` if `err` is `NULL` pointer; or `OCI_ERROR`, if the input datetimes are not of comparable types.

Related Functions

OCIDateTimeCompare()

## OCIDateTimeSysTimeStamp()

Purpose

Gets the system current date and time as a time stamp with time zone.

Syntax

```sword OCIDateTimeSysTimeStamp ( void           *hndl,
OCIError       *err,
OCIDateTime    *sys_date );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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)

Pointer to the output time stamp.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIDateSysDate()

## OCIDateTimeToArray()

Purpose

Converts an `OCIDateTime` descriptor to an array.

Syntax

```sword OCIDateTimeToArray ( void               *hndl,
OCIError           *err,
const OCIDateTime  *datetime,
const OCIInterval  *reftz,
ub1                *outarray,
ub4                *len
ub1                fsprec );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle.

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

datetime (IN)

Pointer to an `OCIDateTime` descriptor.

reftz (IN)

Descriptor for the `OCIInterval` used as a reference when converting the `SQL_TIMESTAMP_LTZ` type.

outarray(OUT)

Array of bytes containing the date.

len (OUT)

Length of `outarray`.

fsprec (IN)

Fractional second precision in the array.

The array is allocated by OCI and its length is returned.

Returns

`OCI_SUCCESS`; or `OCI_ERROR`, if datetime is invalid.

Related Functions

## OCIDateTimeToText()

Purpose

Converts the given date to a string according to the specified format.

Syntax

```sword OCIDateTimeToText ( void                *hndl,
OCIError            *err,
const OCIDateTime   *date,
const OraText       *fmt,
ub1                 fmt_length,
ub1                 fsprec,
const OraText       *lang_name,
size_t              lang_length,
ub4                 *buf_size,
OraText             *buf );
```

Parameters

hndl (IN)

The OCI user session handle or environment handle. If a user session handle is passed, the conversion occurs in the session's `NLS_LANGUAGE` and the session's `NLS_CALENDAR`; otherwise, the default is used.

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 datetime value to be converted.

fmt (IN)

The conversion format. If it is a `NULL` string pointer, `(text*)0`, then the date is converted to a character string in the default format for that type.

fmt_length (IN)

The length of the `fmt` parameter.

fsprec (IN)

Specifies the precision in which the fractional seconds value is returned.

lang_name (IN)

Specifies the language in which the names and abbreviations of months and days are returned. The default language of the session is used if `lang_name` is `NULL` (`lang_name` = `(OraText *)0`).

lang_length (IN)

The length of the `lang_name` parameter.

buf_size (IN/OUT)

The size of the `buf` buffer (IN).

The size of the resulting string after the conversion (OUT).

buf (OUT)

The buffer into which the converted string is placed.

See the description of the `TO_DATE` conversion function in the Oracle Database SQL Language Reference for a description of format and multilingual arguments. The converted NULL-terminated date string is stored in the buffer `buf`.

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is `NULL`; or `OCI_ERROR`, if any of the following statements is true:

• The buffer is too small.

• An invalid format is used.

• An unknown language is used.

• There is an overflow error.

Related Functions

OCIDateTimeFromText()

## OCIDateToText()

Purpose

Converts a date type to a character string.

Syntax

```sword OCIDateToText ( OCIError                  *err,
const OCIDate             *date,
const OraText             *fmt,
ub1                       fmt_length,
const OraText             *lang_name,
ub4                       lang_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().

date (IN)

Oracle date to be converted.

fmt (IN)

Conversion format. If `NULL`, `(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; the default language of the session is used if `lang_name` is `NULL` (`(text *)0`).

lang_length (IN)

Length of the `lang_name` parameter.

buf_size (IN/OUT)

Size of the buffer (IN). Size of the resulting string is returned with this parameter (OUT).

buf (OUT)

Buffer into which the converted string is placed.

Converts the given date to a string according to the specified format. The converted `NULL`-terminated date string is stored in `buf`.

See the `TO_DATE` conversion function described in the Oracle Database SQL Language Reference for a description of format and multilingual arguments.

Returns

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

## OCIDateZoneToZone()

Purpose

Converts a date from one time zone to another.

Syntax

```sword OCIDateZoneToZone ( OCIError           *err,
const OCIDate      *date1,
const OraText      *zon1,
ub4                zon1_length,
const OraText      *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 the 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`).

Converts a given date `date1` in time zone `zon1` to a date `date2` in time zone `zon2`. Works only with North American time zones.

For a list of valid zone strings, see the description of the `NEW_TIME` function in the Oracle Database SQL Language Reference. Examples of valid zone strings include:

• AST, Atlantic Standard Time

• BST, Bering Standard Time

• BDT, Bering Daylight Time

Returns

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

Related Functions

Purpose

Adds two intervals to produce a resulting interval.

Syntax

```sword OCIIntervalAdd ( void         *hndl,
OCIError     *err,
OCIInterval  *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

result (OUT)

The resulting interval (`addend1` + `addend2`).

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if any of the following statements is true:

• The two input intervals are not mutually comparable.

• The resulting year is greater than `SB4MAXVAL`.

• The resulting year is less than `SB4MINVAL`.

Related Functions

OCIIntervalSubtract()

## OCIIntervalAssign()

Purpose

Copies one interval to another.

Syntax

```void OCIIntervalAssign ( void              *hndl,
OCIError          *err,
const OCIInterval *inpinter,
OCIInterval       *outinter );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

inpinter (IN)

Input interval.

outinter (OUT)

Output interval.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalCompare()

## OCIIntervalCheck()

Purpose

Checks the validity of an interval.

Syntax

```sword OCIIntervalCheck ( void               *hndl,
OCIError            *err,
const OCIInterval   *interval,
ub4                 *valid );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

interval (IN)

Interval to be checked.

valid (OUT)

Returns zero if the interval is valid; otherwise, it returns the logical operator OR combination of the codes specified in Table 20-9.

Table 20-9 Error Bits Returned by the valid Parameter for OCIIntervalCheck()

Macro Name Bit Number Error

`OCI_INTER_INVALID_DAY`

0x1

`OCI_INTER_DAY_BELOW_VALID`

0x2

`OCI_INTER_INVALID_MONTH`

0x4

`OCI_INTER_MONTH_BELOW_VALID`

0x8

`OCI_INTER_INVALID_YEAR`

0x10

`OCI_INTER_YEAR_BELOW_VALID`

0x20

`OCI_INTER_INVALID_HOUR`

0x40

`OCI_INTER_HOUR_BELOW_VALID`

0x80

`OCI_INTER_INVALID_MINUTE`

0x100

`OCI_INTER_MINUTE_BELOW_VALID`

0x200

`OCI_INTER_INVALID_SECOND`

0x400

`OCI_INTER_SECOND_BELOW_VALID`

0x800

`OCI_INTER_INVALID_FRACSEC`

0x1000

`OCI_INTER_FRACSEC_BELOW_VALID`

0x2000

Bad fractional second low/high bit (1=low)

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, on error.

Related Functions

OCIIntervalCompare()

## OCIIntervalCompare()

Purpose

Compares two intervals.

Syntax

```sword OCIIntervalCompare (void          *hndl,
OCIError      *err,
OCIInterval   *inter1,
OCIInterval   *inter2,
sword         *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

inter1 (IN)

Interval to be compared.

inter2 (IN)

Interval to be compared.

result (OUT)

Comparison result as specified in Table 20-10.

Table 20-10 Comparison Results Returned by the result Parameter for OCIIntervalCompare()

Comparison Result Output in result Parameter

`inter1` < `inter2`

-1

`inter1` = `inter2`

0

`inter1` > `inter2`

1

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if the input values are not mutually comparable.

Related Functions

OCIIntervalAssign()

## OCIIntervalDivide()

Purpose

Divides an interval by an Oracle `NUMBER` to produce an interval.

Syntax

```sword OCIIntervalDivide ( void         *hndl,
OCIError     *err,
OCIInterval  *dividend,
OCINumber    *divisor,
OCIInterval  *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

dividend (IN)

Interval to be divided.

divisor (IN)

Oracle `NUMBER` dividing `dividend`.

result (OUT)

The resulting interval ( `dividend` / `divisor`).

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalMultiply()

## OCIIntervalFromNumber()

Purpose

Converts an Oracle `NUMBER` to an interval.

Syntax

```sword OCIIntervalFromNumber ( void               *hndl,
OCIError           *err,
OCIInterval        *interval,
OCINumber          *number );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

interval (OUT)

Interval result.

number (IN)

Oracle `NUMBER` to be converted (in years for YEAR TO MONTH intervals and in days for DAY TO SECOND intervals).

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalToNumber()

## OCIIntervalFromText()

Purpose

When given an interval string, returns the interval represented by the string. The type of the interval is the type of the `result` descriptor.

Syntax

```sword OCIIntervalFromText ( void           *hndl,
OCIError       *err,
const OraText  *inpstring,
size_t         str_len,
OCIInterval    *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

inpstring (IN)

Input string.

str_len (IN)

Length of the input string.

result (OUT)

Resultant interval.

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if any of the following statements is true:

• There are too many fields in the literal string.

• The year is out of range (–4713 to 9999).

• The month is out of range (1 to 12).

• The day of month is out of range (1 to 28...31).

• The hour is out of range (0 to 23).

• The hour is out of range (0 to 11).

• The minutes are out of range (0 to 59).

• The seconds in the minute are out of range (0 to 59).

• The seconds in the day are out of range (0 to 86399).

• The interval is invalid.

Related Functions

OCIIntervalToText()

## OCIIntervalFromTZ()

Purpose

Returns an `OCI_DTYPE_INTERVAL_DS` of data type `OCIInterval` with the region ID set (if the region is specified in the input string) and the current absolute offset, or an absolute offset with the region ID set to 0.

Syntax

```sword OCIIntervalFromTZ ( void           *hndl,
OCIError       *err,
const oratext  *inpstring,
size_t         str_len,
OCIInterval    *result ) ;
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

inpstring (IN)

Pointer to the input string.

str_len (IN)

Length of `inpstring`.

result (OUT)

Output interval.

Returns

`OCI_SUCCESS`, on success; `OCI_INVALID_HANDLE`, if err is `NULL`; or `OCI_ERROR`, if there is a bad interval type or there are time zone errors.

The input string must be of the form [+/-]TZH:TZM or 'TZR [TZD]'

Related Functions

OCIIntervalFromText()

## OCIIntervalGetDaySecond()

Purpose

Gets values of day, hour, minute, and second from an interval.

Syntax

```sword OCIIntervalGetDaySecond (void               *hndl,
OCIError           *err,
sb4                *dy,
sb4                *hr,
sb4                *mm,
sb4                *ss,
sb4                *fsec,
const OCIInterval  *interval );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

dy (OUT)

Number of days.

hr (OUT)

Number of hours.

mm (OUT)

Number of minutes.

ss (OUT)

Number of seconds.

fsec (OUT)

Number of nano seconds.

interval (IN)

The input interval.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalSetDaySecond()

## OCIIntervalGetYearMonth()

Purpose

Gets year and month from an interval.

Syntax

```sword OCIIntervalGetYearMonth ( void               *hndl,
OCIError           *err,
sb4                *yr,
sb4                *mnth,
const OCIInterval  *interval );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

yr (OUT)

Year value.

mnth (OUT)

Month value.

interval (IN)

The input interval.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalSetYearMonth()

## OCIIntervalMultiply()

Purpose

Multiplies an interval by an Oracle `NUMBER` to produce an interval.

Syntax

```sword OCIIntervalMultiply ( void               *hndl,
OCIError           *err,
const OCIInterval  *inter,
OCINumber          *nfactor,
OCIInterval        *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

inter (IN)

Interval to be multiplied.

nfactor (IN)

Oracle `NUMBER` to be multiplied.

result (OUT)

The resulting interval (`inter` * `nfactor`).

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if any of the following statements is true:

• The resulting year is greater than `SB4MAXVAL`.

• The resulting year is less than `SB4MINVAL`.

Related Functions

OCIIntervalDivide()

## OCIIntervalSetDaySecond()

Purpose

Sets day, hour, minute, and second in an interval.

Syntax

```sword OCIIntervalSetDaySecond ( void               *hndl,
OCIError           *err,
sb4                dy,
sb4                hr,
sb4                mm,
sb4                ss,
sb4                fsec,
OCIInterval        *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

dy (IN)

Number of days.

hr (IN)

Number of hours.

mm (IN)

Number of minutes.

ss (IN)

Number of seconds.

fsec (IN)

Number of nano seconds.

result (OUT)

The resulting interval.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalGetDaySecond()

## OCIIntervalSetYearMonth()

Purpose

Sets year and month in an interval.

Syntax

```sword OCIIntervalSetYearMonth ( void               *hndl,
OCIError           *err,
sb4                yr,
sb4                mnth,
OCIInterval        *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

yr (IN)

Year value.

mnth (IN)

Month value.

result (OUT)

The resulting interval.

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if any of the following statements is true:

• The resulting year is greater than `SB4MAXVAL`.

• The resulting year is less than `SB4MINVAL`.

Related Functions

OCIIntervalGetYearMonth()

## OCIIntervalSubtract()

Purpose

Subtracts two intervals and stores the result in an interval.

Syntax

```sword OCIIntervalSubtract ( void         *hndl,
OCIError     *err,
OCIInterval  *minuend,
OCIInterval  *subtrahend,
OCIInterval  *result );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

minuend (IN)

The interval to be subtracted from.

subtrahend (IN)

The interval subtracted from `minuend`.

result (OUT)

The resulting interval (`minuend` - `subtrahend`).

Returns

`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if any of the following statements is true:

• The resulting year is greater than `SB4MAXVAL`.

• The resulting year is less than `SB4MINVAL`.

• The two input intervals are not mutually comparable.

Related Functions

## OCIIntervalToNumber()

Purpose

Converts an interval to an Oracle `NUMBER`.

Syntax

```sword OCIIntervalToNumber ( void               *hndl,
OCIError           *err,
OCIInterval        *interval,
OCINumber          *number );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

interval (IN)

Interval to be converted.

number (OUT)

Oracle `NUMBER` result (in years for `YEARMONTH` interval and in days for `DAYSECOND`).

Fractional portions of the date (for instance, minutes and seconds if the unit chosen is hours) are included in the Oracle `NUMBER` produced. Excess precision is truncated.

Returns

`OCI_SUCCESS`; or `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer.

Related Functions

OCIIntervalFromNumber()

## OCIIntervalToText()

Purpose

When given an interval, produces a string representing the interval.

Syntax

```sword OCIIntervalToText ( void               *hndl,
OCIError           *err,
const OCIInterval  *interval,
ub1                lfprec,
ub1                fsprec,
OraText            *buffer,
size_t             buflen,
size_t             *resultlen );
```

Parameters

hndl (IN)

The OCI user session handle or the environment handle.

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

interval (IN)

Interval to be converted.

lfprec (IN)

Leading field precision. (The number of digits used to represent the leading field.)

fsprec (IN)

Fractional second precision of the interval (the number of digits used to represent the fractional seconds).

buffer (OUT)

Buffer to hold the result.

buflen (IN)

The length of `buffer`.

resultlen (OUT)

The length of the result placed into `buffer`.

The interval literal is output as 'year' or '[year-]month' for `INTERVAL YEAR TO MONTH` intervals and as 'seconds' or 'minutes[:seconds]' or 'hours[:minutes[:seconds]]' or 'days[ hours[:minutes[:seconds]]]' for `INTERVAL` `DAY` `TO` `SECOND` intervals (where optional fields are surrounded by brackets).
`OCI_SUCCESS`; `OCI_INVALID_HANDLE`, if `err` is a `NULL` pointer; or `OCI_ERROR`, if the buffer is not large enough to hold the result.