Skip Headers

Oracle® C++ Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10778-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

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


Note:

For GMT timezone, both hour and minute equal 0.

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

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

Table 10-41 Fields of Timestamp and Their Legal Ranges

Field Type Minimum Value Maximum value
year int -4713 9999
month unsigned int 1 12
day unsigned int 1 31
hour unsigned int 0 23
min unsigned int 0 59
sec unsigned int 0 61
tzhour int -12 14
tzmin int -59 59

Table 10-42 Summary of Timestamp Methods

Method Summary
Timestamp()
Timestamp class constructor.
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()
Returns a string representation for the timestamp in the format specified.


Timestamp()

Timestamp class constructor.

Syntax Description
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);
Returns a default Timestamp object. Time components are understood to be in the specified time zone.
Timestamp();
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(
   const Environment *env,
   int year,
   unsigned int month,
   unsigned int day,
   unsigned int hour,
   unsigned int min,
   unsigned int sec,
   unsigned int fs,
   const OCCI_STD_NAMESPACE::string &timezone);
Multibyte support. The timezone can be passed as region, "US/Eastern", or as an offset from GMT, "+05:30". If an empty string is passed, then the time is considered to be in the current session's time zone. Used for constructing values for TIMESTAMP WITH LOCAL TIME ZONE types.
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);
UTF16 (UString) support. The timezone can be passed as region, "US/Eastern", or as an offset from GMT, "+05:30". If an empty string is passed, then the time is considered to be in the current session's time zone. Used for constructing values for TIMESTAMP WITH LOCAL TIME ZONE types.

Example 10-9 Using Default Timestamp Constructor

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

Example 10-10 Using fromText() method to Initialize a NULL Timestamp Instance

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

Example 10-11 Comparing Timestamps Stored in the Database

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())
{
   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
}
Parameter Description
year
Year component.
month
Month component.
day
Day component.
hour
Hour component.
minute
Minute component.
second
Second component.
fs
Fractional second component.
tzhour
Time zone difference hour component.
tzmin
Timezone difference minute component.


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.

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


See Also:

Oracle Database SQL Reference for information on TO_DATE

Syntax Description
void fromText(
   const string &timestampStr,
   const string &fmt = "",
   const string &nlsParam = "",
   const Environment *env = NULL);
Set Timestamp object to value represented by a string.
void fromText(
   const UString &timestampStr,
   const UString &fmt,
   const UString &nlsParam,
   const Environment *env = NULL);
Set Timestamp object to value represented by a UString; globalization enabled.

Parameter Description
timestampStr
The timestamp string or UString to be converted to a Timestamp object.
fmt
The format string.
nlsParam
The nls parameters string. If nlsParam is specified, this determines the nls parameters to be used for the conversion. If nlsParam is not specified, the nls parameters are picked up from envp.
env
The OCCI environment. In globalization enabled version of the method, used to determine NLS_CALENDAR for interpreting timestampStr. If env is not passed, the environment associated with the object controls the setting. Should be a non-NULL value if called on a NULL Timestamp object.


getDate()

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


Syntax
void getDate(
   int &year,
   unsigned int &month,
   unsigned int &day) const;
Parameter Description
year
Year component.
month
Month component.
day
Day component.


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;
Parameter Description
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;
Parameter Description
hour
Time zone hour.
minute
Time zone minute.


intervalAdd()

Adds an interval to timestamp.

Syntax Description
Timestamp intervalAdd(
   const IntervalDS& val) const;
Adds an IntervalDS interval to the timestamp.
Timestamp intervalAdd(
   const IntervalYM& val) const;
Adds an IntervalYM interval to the timestamp.

Parameter Description
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 Description
Timestamp intervalSub(
   const IntervalDS& val) const;
Subtracts an IntervalDS interval to the timestamp.
Timestamp intervalsUB(
   const IntervalYM& val) const;
Subtracts an IntervalYM interval to the timestamp.

Parameter Description
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);
Parameter Description
src
Value to be assigned.

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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp to be compared.


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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp to be compared.


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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp to be compared.


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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp to be compared.


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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp to be compared.


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);
Parameter Description
first
First timestamp to be compared.
second
Second timestamp 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);
Parameter Description
year
Year component. Valid values are -4713 through 9999.
month
Month component. Valid values are 1 through 12.
day
Day component. 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);
Parameter Description
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);
Parameter Description
hour Time zone hour. Valid values are -12 through 12.
minute Time zone minute. Valid values are -59 through 59.


subDS()

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


Syntax
IntervalDS subDS(
   const Timestamp& val) const; 

Parameter Description
val Timestamp to be subtracted.

subYM()

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


Syntax
IntervalYM subYM(
   const Timestamp& val) const;
Parameter Description
val
Timestamp to be subtracted.


toText()

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


See Also:

Oracle Database SQL Reference for information on TO_DATE

Syntax Description
string toText(
   const string &fmt,
   unsigned int fsprec,
   const string &nlsParam = "") const;
Return a string representation for the timestamp in the format specified.
UString toText(
   const UString &fmt,
   unsigned int fsprec,
   const UString &nlsParam) const;
Return a UString representation for the timestamp in the format specified; globalization enabled.

Parameter Description
fmt
The format string.
fsprec
The precision for the fractional second component of Timestamp.
nlsParam
The nls parameters string. If nlsParam is specified, this determines the nls parameters to be used for the conversion. If nlsParam is not specified, the nls parameters are picked up from envp.