Timestamp Class

This class conforms to the SQL92 TIMESTAMP and TIMESTAMPTZ types, and works with all database TIMESTAMP types: TIMESTAMP, TIMESTAMP WITH TIME ZONE, and TIMESTAMP WITH LOCAL TIME ZONE.

Timestamp time components, such as hour, minute, second and fractional section are in the time zone specified for the Timestamp. This is new behavior for the 10g release; previous versions supported GMT values of time components. Time components were only converted to the time zone specified by Timestamp when they were stored in the database. For example, the following Timestamp() call constructs a Timestamp value 13-Nov 2003 17:24:30.0 in timezone +5:30.

Timestamp ts(env, 2003, 11, 13, 17, 24, 30, 0, 5, 30);

The behavior of this call in previous releases would interpret the timestamp components as GMT, resulting in a timestamp value of 13-Nov 2003 11:54:30.0 in timezone +5:30. Users were forced to convert the timestamps to GMT before invoking the constructor.

This behaviour change also applies to setDate() and setTime() methods.

The fields of Timestamp class and their legal ranges are provided in Table 12-48. An SQLException will occur if a parameter is out of range.

Timestamp()

Timestamp class constructor.

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);

Timestamp();

Timestamp(
   const Environment *env,
   int year,
   unsigned int month,
   unsigned int day,
   unsigned int hour,
   unsigned int min,
   unsigned int sec,
   unsigned int fs,
   const string &timezone);

Timestamp(
   const Environment *env,
   int year,
   unsigned int month,
   unsigned int day,
   unsigned int hour,
   unsigned int min,
   unsigned int sec,
   unsigned int fs,
   const UString &timezone);

Timestamp(
   const Timestamp &src);

year

month

day

hour

minute

second

fs

tzhour

tzmin

src

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);

Environment *env = Environment::createEnvironment();

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

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())
{
   string tsstr=ts.toText(           //get the timestamp value in string format
      "dd/mm/yyyy hh:mi:ss [tzh:tzm]",0);
   if(reft<ts                        //compare timestamps
      IntervalDS ds=reft.subDS(ts);  //get difference between timestamps
}

fromText()

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, Globalization Support parameters are obtained from the environment associated with the instance, if any.

Sets Timestamp object to value represented by a string or UString.

The value is interpreted based on the fmt and nlsParam parameters. In cases where nlsParam is not passed, the Globalization Support settings of the envp parameter are used.

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

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

timestmpStr

fmt

nlsParam

env

getDate()

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

Syntax

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

year

month

day

getTime()

Returns the hour, minute, second, and fractional second components

Syntax

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

hour

minute

second

fs

getTimeZoneOffset()

Returns the time zone offset in hours and minutes.

Syntax

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

hour

minute

intervalAdd()

Adds an interval to timestamp.

const Timestamp intervalAdd(
   const IntervalDS& val) const;

const Timestamp intervalAdd(
   const IntervalYM& val) const;

val

intervalSub()

Subtracts an interval from a timestamp and returns the result as a timestamp. Returns a Timestamp with the value of this - val.

const Timestamp intervalSub(
   const IntervalDS& val) const;

const Timestamp intervalsUB(
   const IntervalYM& val) const;

val

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);

src

operator==()

Compares the timestamps specified. If the timestamps are equal, returns TRUE, FALSE otherwise. If either a or b is NULL then FALSE is returned.

Syntax

bool operator==(
   const Timestamp &first,
   const Timestamp &second);

first

second

operator!=()

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 &first,
   const Timestamp &second);

first

second

operator>()

Returns TRUE if first is greater than second, FALSE otherwise. If either is NULL then FALSE is returned.

Syntax

bool operator>(
   const Timestamp &first,
   const Timestamp &second);

first

second

operator>=()

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 &first,
   const Timestamp &second);

first

second

operator<()

Returns TRUE if first is less than second, FALSE otherwise. If either a or b is NULL then FALSE is returned.

Syntax

bool operator<(
   const Timestamp &first,
   const Timestamp &second);

first

second

operator<=()

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 &first,
   const Timestamp &second);

first

second

setDate()

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

Syntax

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

year

month

day

setNull()

Sets 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);

setTimeZoneOffset()

Sets the hour and minute offset for time zone.

Syntax

void setTimeZoneOffset(
   int hour,
   int minute);

subDS()

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

Syntax

const IntervalDS subDS(
   const Timestamp& val) const; 

subYM()

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

Syntax

const IntervalYM subYM(
   const Timestamp& val) const;

val

toText()

Returns a string or UString 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.

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

UString toText(
   const UString &fmt,
   unsigned int fsprec,
   const UString &nlsParam) const;

fmt

fsprec

nlsParam