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 139 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 159 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 187 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 212 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 224 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 250 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 276 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 303 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 329 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 356 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 384 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 662 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 426 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 462 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 498 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 576 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 597 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 618 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 517 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 542 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 637 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 716 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 758 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 799 of file date.c.