Timestamp Class

This class conforms to the SQL92 TIMESTAMP and TIMESTAMPTZ types.

OCCI expects the SQL data type corresponding to the Timestamp class to be of type TIMESTAMP WITH TIME ZONE.

Timestamp(const Environment *env,
   int year = 1,
   unsigned int month = 1,
   unsigned int day = 1,
   unsigned int hour = 0,
   unsigned int min = 0,
   unsigned int sec = 0,
   unsigned int fs = 0,
   int tzhour = 0
   int tzmin=0

A SQLException will occur if a parameter is out of range.

year - -4713 to 9999

month 1 to 12

day - 1 to 31

hour - 0 to 23

min - 0 to 59

sec - 0 to 61

tzhour - -12 to 14

tzmin - -59 to 59

Returns a null Timestamp object. A null timestamp can be initialized by assignment or calling the fromText method. Methods that can be called on null timestamp objects are setNull, isNull and operator=().

Timestamp();

Assigns the values found in a.

Timestamp(const Timestamp &src);

The following code example demonstrates that the default constructor creates a null value, and how you can assign a non null value to a timestamp and perform operations on it:

Environment *env = Environment::createEnvironment();

//create a null timestamp
Timestamp ts;
if(ts.isnull())
   cout << "\n ts is Null";

//assign a non null value to ts
Timestamp notNullTs(env, 2000, 8, 17, 12, 0, 0, 0, 5, 30);
ts = notNullTs;

//now all operations are valid on ts...
int yr;
unsigned int mth, day;
ts.getDate(yr, mth, day);

The following code example demonstrates how to use the fromText method to initialize a null timestamp:

Environment *env = Environment::createEnvironment();

Timestamp ts1;
ts1.fromText("01:16:17.12 04/03/1825", "hh:mi:ssxff dd/mm/yyyy", "", env);

The following code example demonstrates how to get the timestamp column from a result set, check whether the timestamp is null, get the timestamp value in string format, and determine the difference between 2 timestamps:

Timestamp reft(env, 2001, 1, 1);
ResultSet *rs=stmt->executeQuery("select order_date from orders
                                  where customer_id=1");
rs->next();

//retrieve the timestamp column from result set
Timestamp ts=rs->getTimestamp(1);

//check timestamp for null
if(!ts.isNull())
{
   //get the timestamp value in string format
   string tsstr=ts.toText("dd/mm/yyyy hh:mi:ss [tzh:tzm]",0);

   if(reft<ts //compare timestamps
   {
      IntervalDS ds=reft.subDS(ts); //get difference between timestamps
   }
}

Summary of Timestamp Methods

Table 8-22 Timestamp Methods  

Method	Summary
fromText()	Sets the time stamp from the values provided by the string.
getDate()	Gets the date from the Timestamp object.
getTime()	Gets the time from the TimeStamp object.
getTimeZoneOffset()	Returns the time zone hour and minute offset value.
intervalAdd()	Returns a Timestamp object with value (this + interval).
intervalSub()	Returns a Timestamp object with value (this - interval).
isNull()	Check if Timestamp is null.
operator=()	Simple assignment.
operator==()	Check if a and b are equal.
operator!=()	Check if a and b are not equal.
operator>()	Check if a is greater than b.
operator>=()	Check if a is greater than or equal to b.
operator<()	Check if a is less than b.
operator<=()	Check if a is less than or equal to b.
setDate()	Sets the year, month, day components contained for this timestamp.
setNull()	Sets the value of Timestamp to null
setTime()	Sets the day, hour, minute, second and fractional second components for this timestamp.
setTimeZoneOffset()	Sets the hour and minute offset for time zone.
subDS()	Returns a IntervalDS representing this - val.
subYM()	Returns a IntervalYM representing this - val.
toText()	Return string representation for the timestamp in the format specified.

fromText()

This method sets the timestamp value from the string. The string is expected to be in the format specified. If nlsParam is specified, this will determine the nls parameters to be used for the conversion. If nlsParam is not specified, the nls parameters are picked up from the environment which has been passed. In case environment is not passed, NLS parameters are obtained from the environment associated with the instance, if any.

Syntax

void fromText(const string &timestmpStr,
   const string &fmt,
   const string &nlsParam = "",
   const Environment *env = NULL);

Parameters

timestmpStr

input string

fm

format string

nlsParam

language name

current support for English and American

env

environment whose nls params will be used.

getDate()

Return the year, day, and month values of the Timestamp.

Syntax

void getDate(int &year,
   unsigned int &month,
   unsigned int &day) const;

Parameters

year

year component

month

month component

day

day component

getTime()

Return the hour, minute, second, and fractional second (fs) components

Syntax

void getTime(unsigned int &hour,
   unsigned int &minute,
   unsigned int &second,
   unsigned int &fs) const;

Parameters

hour

hour component

minute

minute component

second

second component

fs

fractional second component

getTimeZoneOffset()

Returns the time zone offset in hours and minutes.

Syntax

void getTimeZoneOffset(int &hour,
   int &minute) const;

Parameters

hour

time zone hour

minute

time zone minute

intervalAdd()

Adds an interval to timestamp .

Syntax

There are variants of syntax:

Timestamp intervalAdd(const IntervalDS& val) const;

Timestamp intervalAdd(const IntervalYM& val) const;

Parameters

val

interval to be added

intervalSub()

Subtracts an interval from a timestamp and returns the result as a timestamp.

Returns a Timestamp with the value of this - val.

Syntax

There are variants of syntax:

Timestamp intervalSub(const IntervalDS& val) const;

Timestamp intervalSub(const IntervalYM& val) const;

Parameters

val

interval to be subtracted

isNull()

Returns true if Timestamp is null or false otherwise.

Syntax

bool isNull() const;

operator=()

Assigns a given timestamp object to this object.

Syntax

Timestamp & operator=(const Timestamp &src);

Parameters

src

value to be assigned

operator==()

This method compares the timestamps specified. If the timestamps are equal Returns true if a is the same as b, false otherwise. If either a or b is null then false is returned.

Syntax

bool operator==(const Timestamp &a,
   const Timestamp &b);

Parameters

a, b

Timestamps to be compared.

operator!=()

This method compares the timestamps specified. If the timestamps are not equal then true is returned; otherwise, false is returned. If either timestamp is null then false is returned.

Syntax

bool operator!=(const Timestamp &a,
   const Timestamp &b);

Parameters

a, b

Timestamps to be compared.

operator>()

Returns true if a is greater than b, false otherwise. If either a or b is null then false is returned.

Syntax

bool operator>(const Timestamp &a,
   const Timestamp &b);

Parameters

a

a, b

Timestamps to be compared.

operator>=()

This method compares the timestamps specified. If the first timestamp is greater than or equal to the second timestamp then true is returned; otherwise, false is returned. If either timestamp is null then false is returned.

Syntax

bool operator>=(const Timestamp &a,
   const Timestamp &b);

Parameters

a, b

Timestamps to be compared.

operator<()

Returns true if a is less than b, false otherwise. If either a or b is null then false is returned.

Syntax

bool operator<(const Timestamp &a,
   const Timestamp &b);

Parameters

a, b

Timestamps to be compared.

operator<=()

This method compares the timestamps specified. If the first timestamp is less than or equal to the second timestamp then true is returned; otherwise, false is returned. If either timestamp is null then false is returned

Syntax

bool operator<=(const Timestamp &a,
   const Timestamp &b);

Parameters

a, b

Timestamps to be compared.

setDate()

Sets the year, month, day components contained for this timestamp

Syntax

void setDate(int year,
   unsigned int month,
   unsigned int day);

Parameters

year

year component to be set.

Valid values are -4713 through 9999.

month

month component to be set.

Valid values are 1 through 12.

day

day component to be set.

Valid values are 1 through 31.

setNull()

Set the timestamp to null.

Syntax

void setNull();

setTime()

Sets the day, hour, minute, second and fractional second components for this timestamp.

Syntax

void setTime(unsigned int hour,
   unsigned int minute,
   unsigned int second,
   unsigned int fs);

Parameters

hour

hour component.

Valid values are 0 through 23.

minute

minute component.

Valid values are 0 through 59.

second

second component.

Valid values are 0 through 59.

fs

fractional second component.

setTimeZoneOffset()

Sets the hour and minute offset for time zone.

Syntax

void setTimeZoneOffset(int hour,
   int minute);

Parameters

hour

time zone hour.

Valid values are -12 through 14.

minute

time zone minute.

Valid values are -59 through 59.

subDS()

Compute the difference between this timestamp and the specified timestamp and return the difference as an IntervalDS.

Syntax

IntervalDS subDS(const Timestamp& val) const; 

Parameters

val

Tmestamp to be subtracted.

subYM()

Compute the difference between timestamp values and return the difference as an IntervalYM.

Syntax

IntervalYM subYM(const Timestamp& val) const;

Parameters

val

Timestamp to be subtracted.

toText()

Return string representation for the timestamp in the format specified. If nlsParam is specified, this will determine the nls parameters to be used for the conversion. If nlsParam is not specified, the nls parameters are picked up from the environment associated with the instance, if any.

Syntax

string toText(const string &fmt,
   unsigned int fsprec,
   const string &nlsParam = "") const;

Parameters

fmt

Format string.

fsprec

Precision required for the fractional seconds component.

nlsParam

Current support only for English, American.