OCILIB (C Driver for Oracle) 3.9.1
Functions
Date/time manipulation

Detailed Description

OCILIB encapsulates Oracle SQL Date datatype within OCI_Date structure

Basically, the OCI_Date routines are wrappers around the Oracle OCIDate APIs

Example
#include "ocilib.h"

#define SIZE_STR 260

int main(void)
{
    OCI_Date *d1, *d2;

    char str[SIZE_STR+1];
   
    if (!OCI_Initialize(NULL, 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_EXPORT OCI_Date *OCI_API OCI_DateCreate (OCI_Connection *con)
 Create a local date object.
OCI_EXPORT boolean OCI_API OCI_DateFree (OCI_Date *date)
 Free a date object.
OCI_EXPORT OCI_Date **OCI_API OCI_DateArrayCreate (OCI_Connection *con, unsigned int nbelem)
 Create an array of date object.
OCI_EXPORT boolean OCI_API OCI_DateArrayFree (OCI_Date **dates)
 Free an arrray of date objects.
OCI_EXPORT boolean OCI_API OCI_DateAddDays (OCI_Date *date, int nb)
 Add or subtract days to a date handle.
OCI_EXPORT boolean OCI_API OCI_DateAddMonths (OCI_Date *date, int nb)
 Add or subtract months to a date handle.
OCI_EXPORT int OCI_API OCI_DateAssign (OCI_Date *date, OCI_Date *date_src)
 Assign the value of a date handle to another one.
OCI_EXPORT int OCI_API OCI_DateCheck (OCI_Date *date)
 Check if the given date is valid.
OCI_EXPORT int OCI_API OCI_DateCompare (OCI_Date *date, OCI_Date *date2)
 Compares two date handles.
OCI_EXPORT int OCI_API OCI_DateDaysBetween (OCI_Date *date, OCI_Date *date2)
 Return the number of days betWeen two dates.
OCI_EXPORT boolean OCI_API OCI_DateFromText (OCI_Date *date, const mtext *str, const mtext *fmt)
 Convert a string to a date and store it in the given date handle.
OCI_EXPORT boolean OCI_API OCI_DateToText (OCI_Date *date, const mtext *fmt, int size, mtext *str)
 Convert a Date value from the given date handle to a string.
OCI_EXPORT boolean OCI_API OCI_DateGetDate (OCI_Date *date, int *year, int *month, int *day)
 Extract the date part from a date handle.
OCI_EXPORT boolean OCI_API OCI_DateGetTime (OCI_Date *date, int *hour, int *min, int *sec)
 Extract the time part from a date handle.
OCI_EXPORT 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_EXPORT boolean OCI_API OCI_DateSetDate (OCI_Date *date, int year, int month, int day)
 Set the date portion if the given date handle.
OCI_EXPORT boolean OCI_API OCI_DateSetTime (OCI_Date *date, int hour, int min, int sec)
 Set the time portion if the given date handle.
OCI_EXPORT 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 if the given date handle.
OCI_EXPORT boolean OCI_API OCI_DateLastDay (OCI_Date *date)
 Place the last day of month (from the given date) into the given date.
OCI_EXPORT boolean OCI_API OCI_DateNextDay (OCI_Date *date, const mtext *day)
 Gets the date of next day of the week, after a given date.
OCI_EXPORT boolean OCI_API OCI_DateSysDate (OCI_Date *date)
 Return the current system date/time into the date handle.
OCI_EXPORT boolean OCI_API OCI_DateZoneToZone (OCI_Date *date, const mtext *zone1, const mtext *zone2)
 Convert a date from one zone to another zone.
OCI_EXPORT boolean OCI_API OCI_DateToCTime (OCI_Date *date, struct tm *ptm, time_t *pt)
 Affect an OCI_Date handle value to ISO C time datatypes.
OCI_EXPORT boolean OCI_API OCI_DateFromCTime (OCI_Date *date, struct tm *ptm, time_t t)
 Affect ISO C time datatypes values to an OCI_Date handle.

Function Documentation

OCI_EXPORT OCI_Date* OCI_API OCI_DateCreate ( OCI_Connection con)

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:
Return the date handle on success otherwise NULL on failure

Definition at line 149 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateFree ( OCI_Date date)

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

Definition at line 169 of file date.c.

Referenced by OCI_ElemFree().

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

Create an array of date object.

Parameters:
con- Connection handle
nbelem- number of elements in the array
Note:
see OCI_DateCreate() for more details
Returns:
Return the date handle array on success otherwise NULL on failure

Definition at line 197 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateArrayFree ( OCI_Date **  dates)

Free an arrray 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

Definition at line 220 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateAddDays ( OCI_Date date,
int  nb 
)

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

Definition at line 232 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateAddMonths ( OCI_Date date,
int  nb 
)

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

Definition at line 258 of file date.c.

OCI_EXPORT int OCI_API OCI_DateAssign ( OCI_Date date,
OCI_Date date_src 
)

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

Definition at line 284 of file date.c.

Referenced by OCI_ElemSetDate().

OCI_EXPORT int OCI_API OCI_DateCheck ( OCI_Date date)

Check if the given date is valid.

Parameters:
date- Date handle
Returns:
  • Zero if date is valid
  • Any other value means the date is invalid

Definition at line 311 of file date.c.

OCI_EXPORT int OCI_API OCI_DateCompare ( OCI_Date date,
OCI_Date date2 
)

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.

Definition at line 337 of file date.c.

OCI_EXPORT int OCI_API OCI_DateDaysBetween ( OCI_Date date,
OCI_Date date2 
)

Return the number of days betWeen two dates.

Parameters:
date- Date1 handle
date2- Date2 handle
Returns:
Number of days on success otherwise OCI_ERROR on failure

Definition at line 364 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateFromText ( OCI_Date date,
const mtext *  str,
const mtext *  fmt 
)

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

Definition at line 392 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateToText ( OCI_Date date,
const mtext *  fmt,
int  size,
mtext *  str 
)

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

Definition at line 667 of file date.c.

Referenced by OCI_GetString().

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

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

Definition at line 434 of file date.c.

Referenced by OCI_DateGetDateTime().

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

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

Definition at line 470 of file date.c.

Referenced by OCI_DateGetDateTime().

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

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

Definition at line 506 of file date.c.

References OCI_DateGetDate(), and OCI_DateGetTime().

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

Set the date portion if the given date handle.

Parameters:
date- Date handle
year- Year value
month- Month value
day- Day value
Returns:
TRUE on success otherwise FALSE

Definition at line 582 of file date.c.

Referenced by OCI_DateSetDateTime().

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

Set the time portion if the given date handle.

Parameters:
date- Date handle
hour- Hour value
min- Minute value
sec- Second value
Returns:
TRUE on success otherwise FALSE

Definition at line 603 of file date.c.

Referenced by OCI_DateSetDateTime().

OCI_EXPORT 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 if 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

Definition at line 624 of file date.c.

References OCI_DateSetDate(), and OCI_DateSetTime().

OCI_EXPORT boolean OCI_API OCI_DateLastDay ( OCI_Date date)

Place the last day of month (from the given date) into the given date.

Parameters:
date- Date handle
Returns:
TRUE on success otherwise FALSE

Definition at line 524 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateNextDay ( OCI_Date date,
const mtext *  day 
)

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

Parameters:
date- Date handle
day- Day of the week
Returns:
TRUE on success otherwise FALSE

Definition at line 549 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateSysDate ( OCI_Date date)

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

Parameters:
date- Date handle
Returns:
TRUE on success otherwise FALSE

Definition at line 642 of file date.c.

OCI_EXPORT boolean OCI_API OCI_DateZoneToZone ( OCI_Date date,
const mtext *  zone1,
const mtext *  zone2 
)

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

Definition at line 721 of file date.c.

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

Affect an OCI_Date handle value to ISO C time datatypes.

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 'p' are optional but one of them has to be provided.
Returns:
TRUE on success otherwise FALSE

Definition at line 763 of file date.c.

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

Affect ISO C time datatypes values to an OCI_Date handle.

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

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

Returns:
TRUE on success otherwise FALSE

Definition at line 808 of file date.c.