| Oracle® Call Interface Programmer's Guide, 11g Release 2 (11.2) Part Number E10646-02 |
|
|
View PDF |
| Oracle® Call Interface Programmer's Guide, 11g Release 2 (11.2) Part Number E10646-02 |
|
|
View PDF |
This section describes the OCI Date and Interval functions.
Table 19-5 Date Functions
| Function/Page | Purpose |
|---|---|
|
Adds or subtracts days |
|
|
Adds or subtracts months |
|
|
Assigns date |
|
|
Checks if the given date is valid |
|
|
Compares dates |
|
|
Gets number of days between two dates |
|
|
Converts string to date |
|
|
Gets the date portion of a date |
|
|
Gets the time portion of a date |
|
|
Gets date of last day of month |
|
|
Gets date of next day |
|
|
Sets the date portion of a date |
|
|
Sets the time portion of a date |
|
|
Gets current system date and time |
|
|
Converts date to string |
|
|
Performs datetime assignment |
|
|
Checks if the given date is valid |
|
|
Compares two datetime values |
|
|
Constructs a datetime descriptor |
|
|
Converts one datetime type to another |
|
|
Converts an array of size |
|
|
Converts the given string to Oracle datetime type in the |
|
|
Gets the date (year, month, day) portion of a datetime value |
|
|
Gets the time (hour, min, second, fractional second) out of a datetime value |
|
|
Gets the time zone name portion of a datetime value |
|
|
Gets the time zone (hour, minute) portion of a datetime value |
|
|
Adds an interval to a datetime to produce a resulting datetime |
|
|
Subtracts an interval from a datetime and stores the result in a datetime |
|
|
Takes two datetimes as input and stores their difference in an interval |
|
|
Gets the system current date and time as a timestamp with time zone |
|
|
Converts a |
|
|
Converts the given date to a string according to the specified format |
|
|
Converts date from one time zone to another zone |
|
|
Adds two intervals to produce a resulting interval |
|
|
Copies one interval to another |
|
|
Checks the validity of an interval |
|
|
Compares two intervals |
|
|
Divides an interval by an Oracle NUMBER to produce an interval |
|
|
Converts an Oracle NUMBER to an interval |
|
|
Given an interval string, returns the interval represented by the string |
|
|
Returns an |
|
|
Gets values of day, hour, minute, and second from an interval |
|
|
Gets year and month from an interval |
|
|
Multiplies an interval by an Oracle NUMBER to produce an interval |
|
|
Sets day, hour, minute, and second in an interval |
|
|
Sets year and month in an interval |
|
|
Subtracts two intervals and stores the result in an interval |
|
|
Converts an interval to an Oracle NUMBER |
|
|
Given an interval, produces 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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The given date from which to add or subtract.
Number of days to be added or subtracted. A negative value is subtracted.
Result of adding days to, or subtracting days from, date.
Comments
This function returns and error if an invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateAddMonths()
Purpose
Adds or subtracts months from a given date.
Syntax
sword OCIDateAddMonths ( OCIError *err,
const OCIDate *date,
sb4 num_months,
OCIDate *result );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The given date from which to add or subtract.
Number of months to be added or subtracted. A negative value is subtracted.
Result of adding days to, or subtracting days from, date.
Comments
If the input date is the last day of a month, then the appropriate adjustments are made to ensure that the output date is also the last day of the month. For example, Feb. 28 + 1 month = March 31, and November 30 - 3 months = August 31. Otherwise the result date has the same day component as date.
This function returns an error if invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateAddDays()
Purpose
Performs a date assignment.
Syntax
sword OCIDateAssign ( OCIError *err,
const OCIDate *from,
OCIDate *to );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Date to be assigned.
Target of assignment.
Comments
This function assigns a value from one OCIDate variable to another.
Related Functions
Purpose
Checks if the given date is valid.
Syntax
sword OCIDateCheck ( OCIError *err,
const OCIDate *date,
uword *valid );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Date to be checked
Returns zero for a valid date. Otherwise, the ORed combination of all error bits specified as follows:
Table 19-6 Error Bits
| Macro Name | Bit Number | Error |
|---|---|---|
|
|
0x1 |
Bad day |
|
|
0x2 |
Bad day low/high bit (1=low) |
|
|
0x4 |
Bad month |
|
|
0x8 |
Bad month low/high bit (1=low) |
|
|
0x10 |
Bad year |
|
|
0x20 |
Bad year low/high bit (1=low) |
|
|
0x40 |
Bad hour |
|
|
0x80 |
Bad hour low/high bit (1=low) |
|
|
0x100 |
Bad minute |
|
|
0x200 |
Bad minute low/high bit (1=low) |
|
|
0x400 |
Bad second |
|
|
0x800 |
Bad second low/high bit (1=low) |
|
|
0x1000 |
Day is one of those missing from 1582 |
|
|
0x2000 |
Year may not equal zero |
|
|
0x8000 |
Bad date format input |
For example, if the date passed in was 2/0/1990 25:61:10 in (month/day/year hours:minutes:seconds format), the error returned is:
OCI_DATE_INVALID_DAY | OCI_DATE_DAY_BELOW_VALID | OCI_DATE_INVALID_HOUR | OCI_DATE_INVALID_MINUTE.
Comments
This function returns an error if date or valid pointer is NULL.
Related Functions
OCIErrorGet(), OCIDateCompare()
Purpose
Compares two dates.
Syntax
sword OCIDateCompare ( OCIError *err,
const OCIDate *date1,
const OCIDate *date2,
sword *result );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Dates to be compared.
Comparison result:
Table 19-7 Comparison Results
| Comparison result | Output in result parameter |
|---|---|
|
date1 < date2 |
-1 |
|
date1 = date2 |
0 |
|
date1 > date2 |
1 |
Comments
This function returns and error if an invalid date is passed to it.
Related Functions
Purpose
Gets the number of days between two dates.
Syntax
sword OCIDateDaysBetween ( OCIError *err,
const OCIDate *date1,
const OCIDate *date2,
sb4 *num_days );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Input date.
Input date.
Number of days between date1 and date2.
Comments
When the number of days between date1 and date2 is computed, the time is ignored.
This function returns an error if invalid date is passed to it.
Related Functions
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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Input string to be converted to Oracle date.
Size of the input string, if the length is -1 then date_str is treated as a NULL-terminated string.
Conversion format. If fmt is a NULL pointer, then the string is expected to be in "DD-MON-YY" format.
Length of the fmt parameter.
Language in which the names and abbreviations of days and months are specified. If lang_name is a NULL string, (text *)0, then the default language of the session is used.
Length of the lang_name parameter.
Given string converted to date.
Comments
Refer to the TO_DATE conversion function described in the Oracle Database SQL Language Reference for a description of format and multilingual arguments.
This function returns an error if it receives an invalid format, language, or input string.
Related Functions
OCIErrorGet(), OCIDateToText()
Purpose
Get the year, month, and day stored in an Oracle date.
Syntax
void OCIDateGetDate ( const OCIDate *date,
sb2 *year,
ub1 *month,
ub1 *day );
Parameters
Oracle date whose year, month, day data is retrieved.
Year value returned.
Month value returned.
Day value returned.
Comments
None.
Related Functions
OCIDateSetDate(), OCIDateGetTime()
Purpose
Gets the time stored in an Oracle date.
Syntax
void OCIDateGetTime ( const OCIDate *date,
ub1 *hour,
ub1 *min,
ub1 *sec );
Parameters
Oracle date whose time data is retrieved.
Hour value returned.
Minute value returned.
Second value returned.
Comments
Returns the time information returned in the form: hour, minute and seconds.
Related Functions
OCIDateSetTime(), OCIDateGetDate()
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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Input date.
Last day of the month in date.
Comments
This function returns an error if invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateGetDate()
Purpose
Gets the date of 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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Returned date should be later than this date.
First day of week named by this is returned.
Length in bytes of string day.
First day of the week named by day later than date.
Comments
Returns the date of the first day of the week named by day that is later than date.
Example
Get the date of the next Monday after April 18, 1996 (a Thursday).
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 and error if an invalid date or day is passed to it.
Related Functions
OCIErrorGet(), OCIDateGetDate()
Purpose
Set the values in an Oracle date.
Syntax
void OCIDateSetDate ( OCIDate *date,
sb2 year,
ub1 month,
ub1 day );
Parameters
Oracle date whose time data is set.
Year value to be set.
Month value to be set.
Day value to be set.
Comments
None.
Related Functions
Purpose
Sets the time information in an Oracle date.
Syntax
void OCIDateSetTime ( OCIDate *date,
ub1 hour,
ub1 min,
ub1 sec );
Parameters
Oracle date whose time data is set.
Hour value to be set.
Minute value to be set.
Second value to be set.
Comments
None.
Related Functions
Purpose
Gets the current system date and time of the client.
Syntax
sword OCIDateSysDate ( OCIError *err,
OCIDate *sys_date );
Parameters
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Current system date and time of the client.
Comments
None.
Related Functions
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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Oracle date to be converted.
Conversion format, if NULL, (text *)0, then the date is converted to a character string in the default date format, DD-MON-YY.
Length of the fmt parameter.
Specifies the language in which names and abbreviations of months and days are returned; default language of session is used if lang_name is NULL ((text *)0).
Length of the lang_name parameter.
Size of the buffer (IN). Size of the resulting string is returned with this parameter (OUT).
Buffer into which the converted string is placed.
Comments
Converts the given date to a string according to the specified format. The converted NULL-terminated date string is stored in buf.
Refer to the TO_DATE conversion function described in the Oracle Database SQL Language Reference for a description of format and multilingual arguments.
This function returns an error if the buffer is too small, or if the function is passed an invalid format or unknown language. Overflow also causes an error. For example, converting a value of 10 into format '9' causes an error.
Related Functions
OCIErrorGet(), OCIDateFromText()
Purpose
Performs datetime assignment.
Syntax
sword OCIDateTimeAssign ( void *hndl,
OCIError *err,
const OCIDateTime *from,
OCIDateTime *to );
Parameters
The OCI user session handle or environment handle. If a user session handle is passed, the conversion takes place in the session's NLS_LANGUAGE and the session's NLS_CALENDAR, otherwise the default is used.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Source (rhs) datetime to be assigned.
Target (lhs) of assignment.
Comments
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,
OCI_ERROR
Related Functions
OCIDateTimeCheck(), OCIDateTimeConstruct()
Purpose
Checks if the given date is valid.
Syntax
sword OCIDateTimeCheck ( void *hndl,
OCIError *err,
const OCIDateTime *date,
ub4 *valid );
Parameters
The OCI user session handle or environment handle. If a user session handle is passed, the conversion takes place in the session's NLS_LANGUAGE and the session's NLS_CALENDAR, otherwise the default is used.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The date to be checked.
Returns zero for a valid date, otherwise it returns the ORed combination of all the error bits specified next:
Table 19-8 Error Bits
| Macro Name | Bit Number | Error |
|---|---|---|
|
|
0x1 |
Bad day |
|
|
0x2 |
Bad day low/high bit (1=low) |
|
|
0x4 |
Bad month |
|
|
0x8 |
Bad month low/high bit (1=low) |
|
|
0x10 |
Bad year |
|
|
0x20 |
Bad year low/high bit (1=low) |
|
|
0x40 |
Bad hour |
|
|
0x80 |
Bad hour low/high bit (1=low) |
|
|
0x100 |
Bad minute |
|
|
0x200 |
Bad minute low/high bit (1=low) |
|
|
0x400 |
Bad second |
|
|
0x800 |
Bad second low/high bit (1=low) |
|
|
0x1000 |
Day is one of those missing from 1582 |
|
|
0x2000 |
Year may not equal zero |
|
|
0x4000 |
Bad time zone |
|
|
0x8000 |
Bad date format input |
So, for example, if the date passed in was 2/0/1990 25:61:10 in (month/day/year hours:minutes:seconds format), the error returned 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
Purpose
Compares two datetime values.
Syntax
sword OCIDateTimeCompare ( void *hndl,
OCIError *err,
const OCIDateTime *date1,
const OCIDateTime *date2,
sword *result );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Dates to be compared.
Comparison result:
Table 19-9 Comparison Results
| 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
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
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor.
Year value.
Month value.
Day value.
Hour value.
Minute value.
Second value
Fractional second value.
Time zone string. A string representation of the time zone offset from GMT in the format "[+|-][HH:MM]". For example, "-08:00".
Length of the time zone string.
Comments
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 time zone, the date and time fields are assumed to be in the local time of the specified time zone.
If time zone is not specified, then session default time zone is assumed.
Returns
OCI_SUCCESS,
OCI_ERROR, if datetime is not valid.
Related Functions
OCIDateTimeAssign(), OCIDateTimeConvert()
Purpose
Converts one datetime type to another.
Syntax
sword OCIDateTimeConvert ( void *hndl,
OCIError *err,
OCIDateTime *indate,
OCIDateTime *outdate );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
A pointer to the input date.
A pointer to the output datetime.
Comments
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 time zone to one with time zone.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE if err is NULL,
OCI_ERROR, if the conversion is not possible with the given input values.
Related Functions
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
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Array of ub1, containing the date.
Length of inarray.
Type of the resulting datetime. The array will be converted to the specific SQLT type.
Pointer to an OCIDateTime descriptor.
Descriptor for OCIInterval used as a reference when converting a SQLT_TIMESTAMP_LTZ type.
Fractional second precision of the resulting datetime.
Returns
OCI_SUCCESS,
OCI_ERROR if type is invalid.
Related Functions
OCIDateTimeFromText(),OCIDateTimeToArray().
Purpose
Converts the given string to 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
The OCI user session handle or environment handle. If a user session handle is passed, the conversion takes place in the session's NLS_LANGUAGE and the session's NLS_CALENDAR, otherwise the default is used.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The input string to be converted to an Oracle datetime.
The size of the input string. If the length is -1 then date_str is treated as a NULL-terminated string.
The conversion format. If fmt is a NULL pointer, then the string is expected to be in the default format for the datetime type.
The length of the fmt parameter.
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).
The length of the lang_name parameter.
The given string converted to a date.
Comments
Refer to the description of the TO_DATE conversion function in the SQL Reference for a description of the format argument.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE if err is NULL,
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
OCIDateTimeToText(), OCIDateTimeFromArray().
Purpose
Gets the date (year, month, day) portion of a datetime value.
Syntax
void OCIDateTimeGetDate ( void *hndl,
OCIError *err,
const OCIDateTime *datetime,
sb2 *year,
ub1 *month,
ub1 *day );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor from which date information is retrieved.
The retrieved year, month, and day values.
Comments
This function gets the date (year, month, day) portion of a datetime value.
Returns
OCI_SUCCESS,
OCI_ERROR if the input type is SQLT_TIME or OCI_TIME_TZ.
Related Functions
Purpose
Gets the time (hour, min, second, fractional second) out of a datetime value.
Syntax
void OCIDateTimeGetTime ( void *hndl,
OCIError *err,
OCIDateTime *datetime,
ub1 *hour,
ub1 *min,
ub1 *sec,
ub4 *fsec );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor from which time information will be retrieved.
The retrieved hour value.
The retrieved minute value.
The retrieved second value.
The retrieved fractional second value.
Comments
This function gets the time portion (hour, min, second, fractional second) out of a given datetime value.
This function returns an error if the given datetime does not contain time information.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime does not contain time (SQLT_DATE).
Related Functions
Purpose
Gets the time zone name portion of a datetime value.
Syntax
void OCIDateTimeGetTimeZoneName ( void *hndl,
OCIError *err,
const OCIDateTime *datetime,
ub1 *buf,
ub4 *buflen, );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor.
Buffer to store the retrieved time zone name.
The size of the buffer (IN). The size of the name field (OUT)
Comments
This function gets the time portion (hour, min, second, fractional second) out of a given datetime value.
This function returns an error if the given datetime does not contain time information.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime does not contain time zone (SQLT_DATE, SQLT_TIMESTAMP).
Related Functions
OCIDateTimeGetDate(), OCIDateTimeGetTimeZoneOffset().
Purpose
Gets the time zone (hour, minute) portion of a datetime value.
Syntax
void OCIDateTimeGetTimeZoneOffset ( void *hndl,
OCIError *err,
const OCIDateTime *datetime,
sb1 *hour,
sb1 *min, );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor.
The retrieved time zone hour value.
The retrieved time zone minute value.
Comments
This function gets the time zone hour and the time zone minute portion out of a given datetime value.
This function returns an error if the given datetime does not contain time information.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime does not contain time zone (SQLT_DATE, SQLT_TIMESTAMP).
Related Functions
OCIDateTimeGetDate(), OCIDateTimeGetTimeZoneName().
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
The user session or environment handle. If a session handle is passed, the addition takes place in the session default calendar.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to the input datetime.
Pointer to the input interval.
Pointer to the output datetime. The output datetime will be of same type as the input datetime.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if the resulting date is before Jan 1, -4713, or is after Dec 31, 9999.
Related Functions
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
The user session or environment handle. If a session handle is passed, the subtraction takes place in the session default calendar. The interval is assumed to be in the session calendar.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to the input datetime value.
Pointer to the input interval.
Pointer to the output datetime. The output datetime will be of same type as the input datetime.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if the resulting date is before Jan 1, -4713, or is after Dec 31, 9999.
Related Functions
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
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to the subtrahend.
Pointer to the minuend.
Pointer to the output interval.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE if err is NULL pointer,
OCI_ERROR, if the input datetimes are not of comparable types.
Related Functions
Purpose
Gets the system current date and time as a timestamp with time zone.
Syntax
sword OCIDateTimeSysTimeStamp ( void *hndl,
OCIError *err,
OCIDateTime *sys_date );
Parameters
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to the output timestamp.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
Converts a 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
The OCI user session handle or environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to an OCIDateTime descriptor.
Descriptor for the OCIInterval used as a reference when converting SQL_TIMESTAMP_LTZ type.
Array of bytes containing the date.
Length of outarray.
Fractional second precision in the array.
Comments
The array is allocated by OCI and its length is returned.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime is invalid.
Related Functions
OCIDateTimeToText(), OCIDateTimeFromArray().
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
The OCI user session handle or environment handle. If a user session handle is passed, the conversion takes place in the session's NLS_LANGUAGE and the session's NLS_CALENDAR, otherwise the default is used.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Oracle datetime value to be converted
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.
The length of the fmt parameter.
Specifies the precision in which the fractional seconds is returned.
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).
The length of the lang_name parameter.
The size of the buf buffer (IN).
The size of the resulting string after the conversion (OUT).
The buffer into which the converted string is placed.
Comments
Refer to the description of the TO_DATE conversion function in the SQL 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,
OCI_ERROR, if any of the following is true:
The buffer is too small.
An invalid format is used.
An unknown language is used.
There is an overflow error.
Related Functions
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
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Date to convert.
Zone of input date.
Length in bytes of zon1.
Zone to be converted to.
Length in bytes of zon2.
Converted date (in zon2).
Comments
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, refer to the description of the NEW_TIME function in the Oracle Database SQL Language Reference. Examples of valid zone strings include:
AST, Atlantic Standard Time
ADT, Atlantic Daylight Time
BST, Bering Standard Time
BDT, Bering Daylight Time
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 *addend1,
OCIInterval *addend2,
OCIInterval *result );
Parameters
The OCI user session handle or the environment handle.
The OCI 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 to be added.
Interval to be added.
The resulting interval (addend1 + addend2).
Returns
OCI_SUCCESS,
OCI_ERROR, if:
the two input intervals are not mutually comparable,
or, the resulting year is greater than SB4MAXVAL,
or, the resulting year is less than SB4MINVAL,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
Copies one interval to another.
Syntax
void OCIIntervalAssign ( void *hndl,
OCIError *err,
const OCIInterval *inpinter,
OCIInterval *outinter );
Parameters
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Input interval.
Output interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
Checks the validity of an interval.
Syntax
sword OCIIntervalCheck ( void *hndl,
OCIError *err,
const OCIInterval *interval,
ub4 *valid );
Parameters
The OCI user session handle or the environment handle.
The OCI 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 to be checked.
Zero if the interval is valid, else returns an ORed combination of the following codes:
Table 19-10 Error Bits
| Macro Name | Bit Number | Error |
|---|---|---|
|
|
0x1 |
Bad day |
|
|
0x2 |
Bad day low/high bit (1=low) |
|
|
0x4 |
Bad month |
|
|
0x8 |
Bad month low/high bit (1=low) |
|
|
0x10 |
Bad year |
|
|
0x20 |
Bad year low/high bit (1=low) |
|
|
0x40 |
Bad hour |
|
|
0x80 |
Bad hour low/high bit (1=low) |
|
|
0x100 |
Bad minute |
|
|
0x200 |
Bad minute low/high bit (1=low) |
|
|
0x400 |
Bad second |
|
|
0x800 |
Bad second low/high bit (1=low) |
|
|
0x1000 |
Bad fractional second |
|
|
0x2000 |
Bad fractional second low/high bit (1=low) |
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, on error.
Related Functions
Purpose
Compares two intervals.
Syntax
sword OCIIntervalCompare (void *hndl,
OCIError *err,
OCIInterval *inter1,
OCIInterval *inter2,
sword *result );
Parameters
The OCI user session handle or the environment handle.
The OCI 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 to be compared.
Interval to be compared.
Comparison result:
Table 19-11 Comparison Results
| 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,
OCI_ERROR, if the input values are not mutually comparable.
Related Functions
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
The OCI user session handle or the environment handle.
The OCI 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 to be divided.
Oracle NUMBER dividing dividend.
The resulting interval ( dividend / divisor).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
Converts an Oracle NUMBER to an interval.
Syntax
sword OCIIntervalFromNumber ( void *hndl,
OCIError *err,
OCIInterval *interval,
OCINumber *number );
Parameters
The OCI user session handle or the environment handle.
The OCI 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 result.
Oracle NUMBER to be converted (in years for YEAR TO MONTH intervals and in days for DAY TO SECOND intervals).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
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
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Input string.
Length of the input string.
Resultant interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following 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)
if hour is out of range (0 to 11)
if minute is out of range (0 to 59)
if seconds in minute out of range (0 to 59)
if seconds in day out of range (0 to 86399)
if the interval is invalid
Related Functions
Purpose
Returns an OCI_DTYPE_INTERVAL_DS of datatype 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
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Pointer to the input string.
Length of inpstring.
Output interval.
Returns
OCI_SUCCESS, on success,
OCI_INVALID_HANDLE, if err is NULL,
OCI_ERROR, if there is a bad interval type or time zone errors.
Comments
The input string must be of the form [+/-]TZH:TZM or 'TZR [TZD]'
Related Functions
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
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Number of days.
Number of hours.
Number of minutes.
Number of seconds.
Number of fractional seconds.
The input interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
Related Functions
Purpose
Gets year and month from an interval.
Syntax
sword OCIIntervalGetYearMonth ( void *hndl,
OCIError *err,
sb4 *yr,
sb4 *mnth,
const OCIInterval *interval );
Parameters
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Year value.
Month value.
The input interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
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
The OCI user session handle or the environment handle.
The OCI 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 to be multiplied.
Oracle NUMBER to be multiplied.
The resulting interval (inter * nfactor).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following is true:
the resulting year is greater than SB4MAXVAL
the resulting year is less than SB4MINVAL
Related Functions
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
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Number of days.
Number of hours.
Number of minutes.
Number of seconds.
Number of fractional seconds.
The resulting interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
Related Functions
Purpose
Sets year and month in an interval.
Syntax
sword OCIIntervalSetYearMonth ( void *hndl,
OCIError *err,
sb4 yr,
sb4 mnth,
OCIInterval *result );
Parameters
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
Year value.
Month value.
The resulting interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
the resulting year is greater than SB4MAXVAL
the resulting year is less than SB4MINVAL
Related Functions
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
The OCI user session handle or the environment handle.
The OCI error handle. If there is an error, it is recorded in err and this function returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
The interval to be subtracted from.
The interval subtracted from minuend.
The resulting interval (minuend - subtrahend).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following are 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
Purpose
Converts an interval to an Oracle NUMBER.
Syntax
sword OCIIntervalToNumber ( void *hndl,
OCIError *err,
OCIInterval *interval,
OCINumber *number );
Parameters
The OCI user session handle or the environment handle.
The OCI 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 to be converted.
Oracle NUMBER result (in years for YEARMONTH interval and in days for DAYSECOND).
Comments
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,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
Purpose
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
The OCI user session handle or the environment handle.
The OCI 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 to be converted.
Leading field precision. (The number of digits used to represent the leading field.)
Fractional second precision of the interval (the number of digits used to represent the fractional seconds).
Buffer to hold the result.
The length of buffer.
The length of the result placed into buffer.
Comments
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).
Returns
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.
Related Functions
|
 Copyright © 1996, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|