Date/time manipulation

Detailed Description

OcilibCApiOracleNumber

OCILIB encapsulates the Oracle SQL Date data type within the OCI_Date structure.

The OCI_Date routines are wrappers around the Oracle OCIDate APIs.

Example

#include "ocilib.h"
 
#define SIZE_STR 260
 
void err_handler(OCI_Error *err)
{
    printf("%s\n", OCI_ErrorGetString(err));
}
 
int main(void)
{
    OCI_Date *d1, *d2;
 
    char str[SIZE_STR + 1];
 
    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
    {
        return EXIT_FAILURE;
    }
 
    d1 = OCI_DateCreate(NULL);
    d2 = OCI_DateCreate(NULL);
 
    strcpy(str, "13041978 20:20:12");
 
    OCI_DateFromText(d1, str, "DDMMYYYY HH24:MI:SS");
    OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
    printf("\nDate is %s\n", str);
 
    OCI_DateSysDate(d1);
    OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
    printf("\nSysdate is %s\n", str);
 
    OCI_DateAddDays(d1, 5);
    OCI_DateAddMonths(d1, 2);
    OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
    printf("\nDate + 5 days and 2 months is %s\n", str);
 
    OCI_DateAssign(d2, d1);
    OCI_DateLastDay(d1);
    OCI_DateToText(d1, "DD/MM/YYYY HH24:MI:SS", SIZE_STR, str);
    printf("\nLast day of the month : %s\n", str);
 
    printf("\nNumber of days until the end of the months : %i\n", OCI_DateDaysBetween(d1, d2));
 
    OCI_DateFree(d1);
    OCI_DateFree(d2);
 
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Functions
OCI_SYM_PUBLIC OCI_Date *OCI_API	OCI_DateCreate (OCI_Connection *con)
	Create a local date object.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateFree (OCI_Date *date)
	Free a date object.
OCI_SYM_PUBLIC OCI_Date **OCI_API	OCI_DateArrayCreate (OCI_Connection *con, unsigned int nbelem)
	Create an array of Date objects.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateArrayFree (OCI_Date **dates)
	Free an array of date objects.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateAddDays (OCI_Date *date, int nb)
	Add or subtract days to a date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateAddMonths (OCI_Date *date, int nb)
	Add or subtract months to a date handle.
OCI_SYM_PUBLIC int OCI_API	OCI_DateAssign (OCI_Date *date, OCI_Date *date_src)
	Assign the value of a date handle to another one.
OCI_SYM_PUBLIC int OCI_API	OCI_DateCheck (OCI_Date *date)
	Check if the given date is valid.
OCI_SYM_PUBLIC int OCI_API	OCI_DateCompare (OCI_Date *date, OCI_Date *date2)
	Compares two date handles.
OCI_SYM_PUBLIC int OCI_API	OCI_DateDaysBetween (OCI_Date *date, OCI_Date *date2)
	Return the number of days between two dates.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateFromText (OCI_Date *date, const otext *str, const otext *fmt)
	Convert a string to a date and store it in the given date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateToText (OCI_Date *date, const otext *fmt, int size, otext *str)
	Convert a Date value from the given date handle to a string.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateGetDate (OCI_Date *date, int *year, int *month, int *day)
	Extract the date part from a date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateGetTime (OCI_Date *date, int *hour, int *min, int *sec)
	Extract the time part from a date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateGetDateTime (OCI_Date *date, int *year, int *month, int *day, int *hour, int *min, int *sec)
	Extract the date and time parts from a date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateSetDate (OCI_Date *date, int year, int month, int day)
	Set the date portion of the given date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateSetTime (OCI_Date *date, int hour, int min, int sec)
	Set the time portion of the given date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateSetDateTime (OCI_Date *date, int year, int month, int day, int hour, int min, int sec)
	Set the date and time portions of the given date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateLastDay (OCI_Date *date)
	Set the given date to the last day of its month.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateNextDay (OCI_Date *date, const otext *day)
	Get the date of the next specified day of the week, after a given date.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateSysDate (OCI_Date *date)
	Return the current system date/time into the date handle.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateZoneToZone (OCI_Date *date, const otext *zone1, const otext *zone2)
	Convert a date from one zone to another zone.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateToCTime (OCI_Date *date, struct tm *ptm, time_t *pt)
	Convert an OCI_Date handle value to ISO C time data types.
OCI_SYM_PUBLIC boolean OCI_API	OCI_DateFromCTime (OCI_Date *date, struct tm *ptm, time_t t)
	Convert ISO C time data type values to an OCI_Date handle.

Function Documentation

OCI_DateCreate()

OCI_SYM_PUBLIC OCI_Date *OCI_API OCI_DateCreate

(

OCI_Connection *

con

)

#include <api.h>

Create a local date object.

Parameters

con	- Connection handle

Note

From version 2.5.0, parameter 'con' can be NULL in order to manipulate dates independently from database connections.

Returns

The Date handle on success, or NULL on failure.

OCI_DateFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateFree

(

OCI_Date *

date

)

#include <api.h>

Free a date object.

Parameters

date	- Date handle

Warning

Only dates created with OCI_DateCreate() should be freed by OCI_DateFree().

Returns

TRUE on success, otherwise FALSE.

OCI_DateArrayCreate()

OCI_SYM_PUBLIC OCI_Date **OCI_API OCI_DateArrayCreate	(	OCI_Connection *	con,
		unsigned int	nbelem
	)

#include <api.h>

Create an array of Date objects.

Parameters

con	- Connection handle
nbelem	- Number of elements in the array

Note

See OCI_DateCreate() for more details.

Returns

The Date handle array on success, or NULL on failure.

OCI_DateArrayFree()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateArrayFree

(

OCI_Date **

dates

)

#include <api.h>

Free an array of date objects.

Parameters

dates

- Array of date objects

Warning

Only arrays of dates created with OCI_DateArrayCreate() should be freed by OCI_DateArrayFree().

Returns

TRUE on success, otherwise FALSE.

OCI_DateAddDays()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateAddDays	(	OCI_Date *	date,
		int	nb
	)

#include <api.h>

Add or subtract days to a date handle.

Parameters

date	- Date handle
nb	- Number of days to add/remove

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::AddDays().

OCI_DateAddMonths()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateAddMonths	(	OCI_Date *	date,
		int	nb
	)

#include <api.h>

Add or subtract months to a date handle.

Parameters

date	- Date handle
nb	- Number of months to add/remove

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::AddMonths().

OCI_DateAssign()

OCI_SYM_PUBLIC int OCI_API OCI_DateAssign	(	OCI_Date *	date,
		OCI_Date *	date_src
	)

#include <api.h>

Assign the value of a date handle to another one.

Parameters

date	- Destination Date handle
date_src	- Source Date handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::Clone(), and ocilib::Date::operator=().

OCI_DateCheck()

OCI_SYM_PUBLIC int OCI_API OCI_DateCheck

(

OCI_Date *

date

)

#include <api.h>

Check if the given date is valid.

Parameters

date	- Date handle

Returns

• Zero if the date is valid.
• Any other value means the date is invalid.

Referenced by ocilib::Date::IsValid().

OCI_DateCompare()

OCI_SYM_PUBLIC int OCI_API OCI_DateCompare	(	OCI_Date *	date,
		OCI_Date *	date2
	)

#include <api.h>

Compares two date handles.

Parameters

date	- Date1 handle
date2	- Date2 handle

Returns

• -1 if date1 is smaller than date2,
• 0 if they are equal
• 1 if date1 is greater than date2.

OCI_DateDaysBetween()

OCI_SYM_PUBLIC int OCI_API OCI_DateDaysBetween	(	OCI_Date *	date,
		OCI_Date *	date2
	)

#include <api.h>

Return the number of days between two dates.

Parameters

date	- Date1 handle
date2	- Date2 handle

The number of days is the difference of (date2 - date).

Returns

The number of days on success, or OCI_ERROR on failure.

Referenced by ocilib::Date::DaysBetween().

OCI_DateFromText()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateFromText	(	OCI_Date *	date,
		const otext *	str,
		const otext *	fmt
	)

#include <api.h>

Convert a string to a date and store it in the given date handle.

Parameters

date	- Destination Date handle
str	- Source date string
fmt	- Date format

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::FromString().

OCI_DateToText()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateToText	(	OCI_Date *	date,
		const otext *	fmt,
		int	size,
		otext *	str
	)

#include <api.h>

Convert a Date value from the given date handle to a string.

Parameters

date	- Source Date handle
fmt	- Date format
size	- Destination string size in characters
str	- Destination date string

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::ToString().

OCI_DateGetDate()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateGetDate	(	OCI_Date *	date,
		int *	year,
		int *	month,
		int *	day
	)

#include <api.h>

Extract the date part from a date handle.

Parameters

date	- Date handle
year	- Place holder for year value
month	- Place holder for month value
day	- Place holder for day value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::GetDate().

OCI_DateGetTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateGetTime	(	OCI_Date *	date,
		int *	hour,
		int *	min,
		int *	sec
	)

#include <api.h>

Extract the time part from a date handle.

Parameters

date	- Date handle
hour	- Place holder for hour value
min	- Place holder for minute value
sec	- Place holder for second value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::GetTime().

OCI_DateGetDateTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateGetDateTime	(	OCI_Date *	date,
		int *	year,
		int *	month,
		int *	day,
		int *	hour,
		int *	min,
		int *	sec
	)

#include <api.h>

Extract the date and time parts from a date handle.

Parameters

date	- Date handle
year	- Place holder for year value
month	- Place holder for month value
day	- Place holder for day value
hour	- Place holder for hour value
min	- Place holder for minute value
sec	- Place holder for second value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::GetDateTime().

OCI_DateSetDate()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateSetDate	(	OCI_Date *	date,
		int	year,
		int	month,
		int	day
	)

#include <api.h>

Set the date portion of the given date handle.

Parameters

date	- Date handle
year	- Year value
month	- Month value
day	- Day value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::SetDate().

OCI_DateSetTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateSetTime	(	OCI_Date *	date,
		int	hour,
		int	min,
		int	sec
	)

#include <api.h>

Set the time portion of the given date handle.

Parameters

date	- Date handle
hour	- Hour value
min	- Minute value
sec	- Second value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::SetTime().

OCI_DateSetDateTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateSetDateTime	(	OCI_Date *	date,
		int	year,
		int	month,
		int	day,
		int	hour,
		int	min,
		int	sec
	)

#include <api.h>

Set the date and time portions of the given date handle.

Parameters

date	- Date handle
year	- Year value
month	- Month value
day	- Day value
hour	- Hour value
min	- Minute value
sec	- Second value

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::SetDateTime().

OCI_DateLastDay()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateLastDay

(

OCI_Date *

date

)

#include <api.h>

Set the given date to the last day of its month.

Parameters

date	- Date handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::LastDay().

OCI_DateNextDay()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateNextDay	(	OCI_Date *	date,
		const otext *	day
	)

#include <api.h>

Get the date of the next specified day of the week, after a given date.

Parameters

date	- Date handle
day	- Day of the week

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::NextDay().

OCI_DateSysDate()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateSysDate

(

OCI_Date *

date

)

#include <api.h>

Return the current system date/time into the date handle.

Parameters

date	- Date handle

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::SysDate().

OCI_DateZoneToZone()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateZoneToZone	(	OCI_Date *	date,
		const otext *	zone1,
		const otext *	zone2
	)

#include <api.h>

Convert a date from one zone to another zone.

Parameters

date	- Date handle
zone1	- Source zone
zone2	- Destination zone

Returns

TRUE on success, otherwise FALSE.

Referenced by ocilib::Date::ChangeTimeZone().

OCI_DateToCTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateToCTime	(	OCI_Date *	date,
		struct tm *	ptm,
		time_t *	pt
	)

#include <api.h>

Convert an OCI_Date handle value to ISO C time data types.

Parameters

date	- Date handle
ptm	- Pointer to a structure tm to receive date/time values
pt	- Pointer to a time_t to hold the date/time in the time_t format

Note

Both parameters 'ptm' and 'pt' are optional but one of them has to be provided.

Returns

TRUE on success, otherwise FALSE.

OCI_DateFromCTime()

OCI_SYM_PUBLIC boolean OCI_API OCI_DateFromCTime	(	OCI_Date *	date,
		struct tm *	ptm,
		time_t	t
	)

#include <api.h>

Convert ISO C time data type values to an OCI_Date handle.

Parameters

date	- Date handle
ptm	- Pointer to a structure tm that holds the date/time value
t	- Value (time_t) that holds the date/time in the time_t format

Note

Both parameters 'ptm' and 't' are optional but one of them has to be provided. If 'ptm' is not null, its value is assigned to the OCI_Date handle, otherwise the value of 't' is used.

Returns

TRUE on success, otherwise FALSE.