This class provides data members, member functions, and operators to manage dates and times as objects. More...

#include <ildblink/ilidtime.h>

Public Member Functions
	IldDateTime (IlEnvironment *envt)
	This constructor creates an empty instance of `IldDateTime` that will refer to the given environment. More...

	IldDateTime (IlEnvironment *envt, IldDateTime &dt)
	This constructor creates an instance of `IldDateTime` that will refer to the given environment using the value of the `IldDateTime` argument. More...

	IldDateTime (IlEnvironment *envt, short year, IlUShort month, IlUShort day, IlUShort hour=0, IlUShort minute=0, IlUShort second=0, IlUShort msecond=0)
	This constructor creates and returns an instance of `IldDateTime` in which the data members are initialized to the integer values passed as parameters. More...

	IldDateTime (IlEnvironment *envt, UnicodeString ustr)
	This constructor creates and returns an instance of `IldDateTime` in which the data members are initialized using the contents of the given Unicode string. More...

virtual	~IldDateTime ()
	This destructor cleans up the internal ICU structure. More...

IlBoolean	get (short &y, IlUShort &mth, IlUShort &d, IlUShort &h, IlUShort &m, IlUShort &s, IlUShort &ms)
	Get all date and time values. More...

IlUShort	getDay () const
	Get the day. More...

IlUShort	getHour () const
	Get the hour. More...

IlUShort	getMinute () const
	Get the minutes. More...

IlUShort	getMonth () const
	Get the month. More...

IlUShort	getMSecond () const
	Get the milliseconds. More...

IlUShort	getSecond () const
	Get the seconds. More...

IlInt	getTime () const
	Get the time. More...

short	getYear () const
	Get the year. More...

	operator IlInt () const
	Get the time. More...

void	set (short year, IlUShort month, IlUShort day, IlUShort hour, IlUShort minute, IlUShort second, IlUShort msecond=0)
	Set date and time. More...

void	setDate (short year, IlUShort month, IlUShort day)
	Set the date. More...

void	setDay (IlUShort day)
	Assign the day. More...

void	setHour (IlUShort hour)
	Assign the hour. More...

void	setMinute (IlUShort minute)
	Assign the minute. More...

void	setMonth (IlUShort month)
	Assign the month. More...

void	setMSecond (IlUShort msecond)
	Assign the milliseconds. More...

IlBoolean	setNow ()
	Set the date and time values to be those of the exact moment this function is called. More...

void	setSecond (IlUShort second)
	Assign the seconds. More...

void	setTime (IlUShort hour, IlUShort minute, IlUShort second, IlUShort msecond=0)
	Set the time specification. More...

void	setYear (short year)
	Assign the year. More...

Detailed Description

This class provides data members, member functions, and operators to manage dates and times as objects.

Library: dbkernel

By default, DB Link handles dates and times as character strings. But this choice creates dependence upon the way the client API of the particular RDBMS formats dates and times as data values. To achieve independence from the configuration of the RDBMS, DB Link defines the class IldDateTime to handle DATE, TIME, DATETIME, INTERVAL, and TIMESTAMP values (whichever of these exist in the RDBMS that you are accessing).

Compared to previous versions, this class has been enhance to provide internationalization capabilities. Most methods existing in former versions have been redefined to support the internationalization constraints.

Note: The former methods, that do not make use of the internationalization context, have been kept for compatibility but are deprecated and will be removed from the library in a future version. When developing a globalized application these methods should be avoided and preference should be given to the new methods.

The constructors and methods of the IldDateTime class are redefined but do not take into account the environment (time zone and locale); New, but equivalent, constructors are defined that take an IlEnvironment object as first argument. These constructors do make use, and keep a reference to, the time zone and locale set in this environment object.

Note: The environment reference should be valid during the whole life-time of the date/time object.

If the "date as string" feature is turned off, DB Link sends dates and times to the database, or retrieves dates and times from the database, using instances of this class.

Warning: When you use an instance of IldDateTime as input, beware that DB Link does no checking to enforce the correctness of the value. In fact, none of the modifiers in this class check the value of their arguments. You must make sure that the value of a month is between 1 and 12, the value of a day is between 1 and 31, and so on.

The range of valid years for DB Link is from -32767 to 32767. However, the range of the valid years in the particular RDBMS that you are using probably differs.

RDBMS	Range of Valid Years
IBM DB2	0001 through 9999
Informix	0001 through 9999
MS SQL	1753 through 9999
ODBC	0 through 9999 (depending on the target RDBMS)
Oracle	-4712 through 9999
Sybase	1753 through 9999

The accessors (member functions that begin with get) have a range of valid values. For example, the range of valid values for getHour is 0 to 23. The parameter values passed to the modifiers (member functions that begin with set) must be within the appropriate range because DB Link does not check their validity.

See Also: IldColumnType, "Date As String" feature and "Handling Date and Time Values" in the Rogue Wave Views DB Link User's Manual.

Constructor & Destructor Documentation

IldDateTime::IldDateTime ( IlEnvironment * envt )

This constructor creates an empty instance of IldDateTime that will refer to the given environment.

Parameters

envt	A valid environment object.

Initially the value is set to the epoch origin following the UNIX convention (1970/01/01 00:00:00.000).

When retrieving the display form of the date and time object, the locale and time zone of the current environment are used.

See Also: IldDateTime::getString().

IldDateTime::IldDateTime	(	IlEnvironment *	envt,
		IldDateTime &	dt
	)

This constructor creates an instance of IldDateTime that will refer to the given environment using the value of the IldDateTime argument.

Parameters

envt	A valid environment object.
dt	An existing date time object.

When retrieving the display form of the date and time object, the locale and time zone of the current environment are used.

See Also: IldDateTime::getString().

IldDateTime::IldDateTime	(	IlEnvironment *	envt,
		short	year,
		IlUShort	month,
		IlUShort	day,
		IlUShort	hour = `0`,
		IlUShort	minute = `0`,
		IlUShort	second = `0`,
		IlUShort	msecond = `0`
	)

This constructor creates and returns an instance of IldDateTime in which the data members are initialized to the integer values passed as parameters.

Parameters

envt	A valid environment object.
year	The value for the year field of the date.
month	The value for the month field of the date.
day	The value for the day field of the date.
hour	The value for the hour field of the time.
minute	The value for the minute field of the time.
second	The value for the second field of the time.
msecond	The value for the millisecond field of the time.

Any data member for which a parameter is not passed is initialized to 0 (zero). The given values are supposed to be relative to the time zone from the environment.

Note

The value for the month number is 1-based following the usual convention; that is the month number for January is 1.
The hour value is the hour in the day, that is ranges from 0 to 24.

IldDateTime::IldDateTime	(	IlEnvironment *	envt,
		UnicodeString	ustr
	)

This constructor creates and returns an instance of IldDateTime in which the data members are initialized using the contents of the given Unicode string.

Parameters

envt	A valid environment object
ustr	A string containing the textual value of the date and time for the object.

The string contents must conform to the format of the locale and timezone from the environment.

virtual IldDateTime::~IldDateTime ( )

virtual

This destructor cleans up the internal ICU structure.

The set environment value is not altered.

Member Function Documentation

IlBoolean IldDateTime::get	(	short &	y,
		IlUShort &	mth,
		IlUShort &	d,
		IlUShort &	h,
		IlUShort &	m,
		IlUShort &	s,
		IlUShort &	ms
	)

Get all date and time values.

Parameters

y	On ouptut, will contain the year number.
mth	On ouptut, will contain the month number.
d	On ouptut, will contain the day number in month.
h	On ouptut, will contain the number of hours.
m	On ouptut, will number of minutes.
s	On ouptut, will contain the number of seconds.
ms	On ouptut, will contain the number of millisecond.

Returns: IlTrue if all values retrieval succeeded.

It will alter the values of out arguments.

If the number of milliseconds was not set, the returned value is 0.

Note: In case an error happened, the object will be set in the bogus state (isBad() call will return IlTrue).

IlUShort IldDateTime::getDay ( ) const

Get the day.

Returns: The day or the maximum unsigned short integer (USHRT_MAX).

IlUShort IldDateTime::getHour ( ) const

Get the hour.

Returns: The hour or the maximum unsigned short integer (USHRT_MAX).

The range of valid hours is 0 through 23.

Note: The hour is always relative to the day, thus the returned value is not in the range 0-12 but 0-23.

IlUShort IldDateTime::getMinute ( ) const

Get the minutes.

Returns: The minute or the maximum unsigned short integer (USHRT_MAX).

IlUShort IldDateTime::getMonth ( ) const

Get the month.

Returns: The month or the maximum unsigned short integer (USHRT_MAX).

The range of valid month number starts from 1.

IlUShort IldDateTime::getMSecond ( ) const

Get the milliseconds.

Returns: The millisecond or the maximum unsigned short integer (USHRT_MAX).

IlUShort IldDateTime::getSecond ( ) const

Get the seconds.

Returns: The second or the maximum unsigned short integer (USHRT_MAX).

IlInt IldDateTime::getTime ( ) const

Get the time.

Returns: An integer indicating the time of day in number of seconds elapsed since midnight.

short IldDateTime::getYear ( ) const

Get the year.

Returns: The year value or the smallest short number (SHRT_MIN).

IldDateTime::operator IlInt ( ) const

Get the time.

Returns: An integer indicating the time of day in number of seconds elapsed since midnight.

That is, it returns the same value as getTime.

void IldDateTime::set	(	short	year,
		IlUShort	month,
		IlUShort	day,
		IlUShort	hour,
		IlUShort	minute,
		IlUShort	second,
		IlUShort	msecond = `0`
	)

Set date and time.

Parameters

year	An assumed valid year number.
month	An assumed valid month number.
day	An assumed valid day number in month.
hour	An assumed valid number of hours.
minute	An assumed valid number of minutes.
second	An assumed valid number of seconds.
msecond	An assumed valid number of millisecond. This argument is optional.

See Also: setYear(), setMonth(), setDay(), setHour(), setMinute(), setSecond(), setMSecond()

void IldDateTime::setDate	(	short	year,
		IlUShort	month,
		IlUShort	day
	)

Set the date.

Parameters

year	An assumed valid year number.
month	An assumed valid month number.
day	An assumed valid day number in month.

Note: The preexisting values of hour, minute, second and milli-second are not altered.

See Also: setYear(), setMonth(), setDay().

void IldDateTime::setDay ( IlUShort day )

Assign the day.

Parameters

day	An assumed valid day number in month.

Note: Valid day number ranges from 1 to 31. No internal check is made to ensure the day number is actually valid with respect to the month or year.

void IldDateTime::setHour ( IlUShort hour )

Assign the hour.

Parameters

hour	An assumed valid hour number.

Note: The range is relative to the day; that is ranges from 0 to 23. Giving a value lesser than 12 will always set an AM hour.

void IldDateTime::setMinute ( IlUShort minute )

Assign the minute.

Parameters

minute An assumed valid minute number.

The range of valid minutes is 0 through 59.

void IldDateTime::setMonth ( IlUShort month )

Assign the month.

Parameters

month An assumed valid month number.

Note: Valid month number range starts from 1. This is not the convention of the underlying ICU Calendar class for which month numbering starts from 0. No internal check is made to enforce the validity of the month number.

See Also: getMonth(), setYear().

void IldDateTime::setMSecond ( IlUShort msecond )

Assign the milliseconds.

Parameters

msecond An assumed valid number of milliseconds.

The range of valid milliseconds is 0 through 999.

IlBoolean IldDateTime::setNow ( )

Set the date and time values to be those of the exact moment this function is called.

Returns: IlTrue if the assignment succeeded.

void IldDateTime::setSecond ( IlUShort second )

Assign the seconds.

Parameters

second An assumed valid number of seconds.

The range of valid seconds is 0 through 59.

void IldDateTime::setTime	(	IlUShort	hour,
		IlUShort	minute,
		IlUShort	second,
		IlUShort	msecond = `0`
	)

Set the time specification.

Parameters

hour	An assumed valid number of hours.
minute	An assumed valid number of minutes.
second	An assumed valid number of seconds.
msecond	An assumed valid number of millisecond. This argument is optional.

Note: The preexisting values of year, month and day are not altered.

See Also: setHour(), setMinute(), setSecond(), setMSecond().

void IldDateTime::setYear ( short year )

Assign the year.

Parameters

year	An, assumed valid, year number.

Note: Beware no internal check is made on the validity of this number. This is intentional as it allows you to use calendars different from the Gregorian one.

Rogue Wave DBLink API Reference Guide

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation