OracleDate Structure

The OracleDate structure represents the Oracle DATE data type to be stored in or retrieved from a database. Each OracleDate stores the following information: year, month, day, hour, minute, and second.

Class Inheritance

System.Object

  System.ValueType

    Oracle.DataAccess.Types.OracleDate

Declaration

// ADO.NET 2.0: C#
public struct OracleDate : IComparable, INullable, IXmlSerializable

Thread Safety

All public static methods are thread-safe, although instance methods do not guarantee thread safety.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
using Oracle.DataAccess.Client;
 
class OracleDateSample
{
  static void Main(string[] args)
  {
    // Initialize the dates to the lower and upper boundaries
    OracleDate date1 = OracleDate.MinValue;
    OracleDate date2 = OracleDate.MaxValue;
    OracleDate date3 = new OracleDate(DateTime.MinValue);
    OracleDate date4 = new OracleDate(DateTime.MaxValue);
    
    // Set the thread's DateFormat for output
    OracleGlobalization info = OracleGlobalization.GetClientInfo();
    info.DateFormat = "DD-MON-YYYY BC";
    OracleGlobalization.SetThreadInfo(info);
 
    // Print the lower and upper boundaries
    Console.WriteLine("OracleDate ranges from\n{0}\nto\n{1}\n", 
      date1, date2);
    Console.WriteLine(".NET DateTime ranges from\n{0}\nto\n{1}\n", 
      date3, date4);
  }
}

Requirements

Namespace: Oracle.DataAccess.Types

Assembly: Oracle.DataAccess.dll

ODP.NET Version: ODP.NET for .NET Framework 2.0 or ODP.NET for .NET Framework 4

---

OracleDate Members

OracleDate members are listed in the following tables:

OracleDate Constructors

OracleDate constructors are listed in Table 14-14

OracleDate Static Fields

The OracleDate static fields are listed in Table 14-15.

OracleDate Static Methods

The OracleDate static methods are listed in Table 14-16.

OracleDate Static Operators

The OracleDate static operators are listed in Table 14-17.

OracleDate Static Type Conversions

The OracleDate static type conversions are listed in Table 14-18.

OracleDate Properties

The OracleDate properties are listed in Table 14-19.

OracleDate Methods

The OracleDate methods are listed in Table 14-20.

---

OracleDate Constructors

The OracleDate constructors instantiates a new instance of the OracleDate structure.

Overload List:

• OracleDate(DateTime)

  This constructor creates a new instance of the OracleDate structure and sets its value for date and time using the supplied DateTime value.

• OracleDate(string)

  This constructor creates a new instance of the OracleDate structure and sets its value using the supplied string.

• OracleDate(int, int, int)

  This constructor creates a new instance of the OracleDate structure and set its value for date using the supplied year, month, and day.

• OracleDate(int, int, int, int, int, int)

  This constructor creates a new instance of the OracleDate structure and set its value for time using the supplied year, month, day, hour, minute, and second.

• OracleDate(byte [ ])

  This constructor creates a new instance of the OracleDate structure and sets its value to the provided byte array, which is in the internal Oracle DATE format.

OracleDate(DateTime)

This constructor creates a new instance of the OracleDate structure and sets its value for date and time using the supplied DateTime value.

Declaration

// C#
public OracleDate (DateTime dt);

Parameters

• dt

  The provided DateTime value.

Remarks

The OracleDate structure only supports up to a second precision. The time value in the provided DateTime structure that has a precision smaller than second is ignored.

OracleDate(string)

This constructor creates a new instance of the OracleDate structure and sets its value using the supplied string.

Declaration

// C#
public OracleDate (string dateStr);

Parameters

• dateStr

  A string that represents an Oracle DATE.

Exceptions

ArgumentException - The dateStr is an invalid string representation of an Oracle DATE or the dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents the Oracle NLS_DATE_FORMAT parameter.

ArgumentNullException - The dateStr is null.

Remarks

The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
using Oracle.DataAccess.Client;
 
class OracleDateSample
{
  static void Main(string[] args)
  {
    // Set the thread's DateFormat for the OracleDate constructor
    OracleGlobalization info = OracleGlobalization.GetClientInfo();
    info.DateFormat = "YYYY-MON-DD";
    OracleGlobalization.SetThreadInfo(info);
    
    // construct OracleDate from a string using the DateFormat specified.
    OracleDate date = new OracleDate("1999-DEC-01");
    
    // Set a different DateFormat for the thread
    info.DateFormat = "MM/DD/YYYY";
    OracleGlobalization.SetThreadInfo(info);
 
    // Print "12/01/1999"
    Console.WriteLine(date.ToString()); 
  }
}

OracleDate(int, int, int)

This constructor creates a new instance of the OracleDate structure and set its value for date using the supplied year, month, and day.

Declaration

// C#
public OracleDate (int year, int month, int day);

Parameters

• year

  The supplied year. Range of year is (-4712 to 9999).

• month

  The supplied month. Range of month is (1 to 12).

• day

  The supplied day. Range of day is (1 to 31).

Exceptions

ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range.

ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleDate (that is, the day is out of range for the month).

OracleDate(int, int, int, int, int, int)

This constructor creates a new instance of the OracleDate structure and set its value for time using the supplied year, month, day, hour, minute, and second.

Declaration

// C#
public OracleDate (int year, int month, int day, int hour, int minute, int second);

Parameters

• year

  The supplied year. Range of year is (-4712 to 9999).

• month

  The supplied month. Range of month is (1 to 12).

• day

  The supplied day. Range of day is (1 to 31).

• hour

  The supplied hour. Range of hour is (0 to 23).

• minute

  The supplied minute. Range of minute is (0 to 59).

• second

  The supplied second. Range of second is (0 to 59).

Exceptions

ArgumentOutOfRangeException - The argument value for one or more of the parameters is out of the specified range.

ArgumentException - The argument values of the parameters cannot be used to construct a valid OracleDate (that is, the day is out of range for the month).

OracleDate(byte [ ])

This constructor creates a new instance of the OracleDate structure and sets its value to the provided byte array, which is in the internal Oracle DATE format.

Declaration

// C#
public OracleDate(byte [] bytes);

Parameters

• bytes

  A byte array that represents Oracle DATE in the internal Oracle DATE format.

Exceptions

ArgumentException - bytes is null or bytes is not in internal Oracle DATE format or bytes is not a valid Oracle DATE.

---

OracleDate Static Fields

The OracleDate static fields are listed in Table 14-21.

MaxValue

This static field represents the maximum valid date for an OracleDate structure, which is December 31, 9999 23:59:59.

Declaration

// C#
public static readonly OracleDate MaxValue;

MinValue

This static field represents the minimum valid date for an OracleDate structure, which is January 1, -4712.

Declaration

// C#
public static readonly OracleDate MinValue;

Null

This static field represents a null value that can be assigned to the value of an OracleDate instance.

Declaration

// C#
public static readonly OracleDate Null;

---

OracleDate Static Methods

The OracleDate static methods are listed in Table 14-22.

Equals

Overloads Object

This method determines if two OracleDate values are equal.

Declaration

// C#
public static bool Equals(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if two OracleDate values are equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

GreaterThan

This method determines if the first of two OracleDate values is greater than the second.

Declaration

// C#
public static bool GreaterThan(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is greater than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

GreaterThanOrEqual

This method determines if the first of two OracleDate values is greater than or equal to the second.

Declaration

// C#
public static bool GreaterThanOrEqual(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is greater than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

LessThan

This method determines if the first of two OracleDate values is less than the second.

Declaration

// C#
public static bool LessThan(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is less than the second. Otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

LessThanOrEqual

This method determines if the first of two OracleDate values is less than or equal to the second.

Declaration

// C#
public static bool LessThanOrEqual(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is less than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

NotEquals

This method determines if two OracleDate values are not equal.

Declaration

// C#
public static bool NotEquals(OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if two OracleDate values are not equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

GetSysDate

This method gets an OracleDate structure that represents the current date and time.

Declaration

// C#
public static OracleDate GetSysDate ();

Return Value

An OracleDate structure that represents the current date and time.

Parse

This method gets an OracleDate structure and sets its value for date and time using the supplied string.

Declaration

// C#
public static OracleDate Parse (string dateStr);

Parameters

• dateStr

  A string that represents an Oracle DATE.

Return Value

An OracleDate structure.

Exceptions

ArgumentException - The dateStr is an invalid string representation of an Oracle DATE or the dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents the Oracle NLS_DATE_FORMAT parameter.

ArgumentNullException - The dateStr is null.

Remarks

The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used.

Example

// C#
 
using System;
using Oracle.DataAccess.Types;
using Oracle.DataAccess.Client;
 
class ParseSample
{
  static void Main(string[] args)
  {
    // Set the thread's DateFormat for the OracleDate constructor
    OracleGlobalization info = OracleGlobalization.GetClientInfo();
    info.DateFormat = "YYYY-MON-DD";
    OracleGlobalization.SetThreadInfo(info);
    
    // Construct OracleDate from a string using the DateFormat specified
    OracleDate date = OracleDate.Parse("1999-DEC-01");
    
    // Set a different DateFormat on the thread for ToString() 
    info.DateFormat = "MM-DD-YY";
    OracleGlobalization.SetThreadInfo(info);
 
    // Print "12-01-1999"
    Console.WriteLine(date.ToString()); 
  }
}

---

OracleDate Static Operators

The OracleDate static operators are listed in Table 14-23.

operator ==

This method determines if two OracleDate values are the same.

Declaration

// C#
public static bool operator == (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if they are the same; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

operator >

This method determines if the first of two OracleDate values is greater than the second.

Declaration

// C#
public static bool operator > (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is greater than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

operator >=

This method determines if the first of two OracleDate values is greater than or equal to the second.

Declaration

// C#
public static bool operator >= (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is greater than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

operator !=

This method determines if the two OracleDate values are not equal.

Declaration

// C#
public static bool operator != (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the two OracleDate values are not equal; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

operator <

This method determines if the first of two OracleDate values is less than the second.

Declaration

// C#
public static bool operator < (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is less than the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

operator <=

This method determines if the first of two OracleDate values is less than or equal to the second.

Declaration

// C#
public static bool operator <= (OracleDate value1, OracleDate value2);

Parameters

• value1

  The first OracleDate.

• value2

  The second OracleDate.

Return Value

Returns true if the first of two OracleDate values is less than or equal to the second; otherwise, returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

---

OracleDate Static Type Conversions

The OracleDate static type conversions are listed in Table 14-24.

explicit operator DateTime

This method converts an OracleDate structure to a DateTime structure.

Declaration

// C#
public static explicit operator DateTime(OracleDate val);

Parameters

• val

  An OracleDate structure.

Return Value

A DateTime structure.

explicit operator OracleDate

explicit operator OracleDate converts the provided structure to an OracleDate structure.

Overload List:

• explicit operator OracleDate(DateTime)

  This method converts a DateTime structure to an OracleDate structure.

• explicit operator OracleDate(OracleTimeStamp)

  This method converts an OracleTimeStamp structure to an OracleDate structure.

• explicit operator OracleDate(string)

  This method converts the supplied string to an OracleDate structure.

explicit operator OracleDate(DateTime)

This method converts a DateTime structure to an OracleDate structure.

Declaration

// C#
public static explicit operator OracleDate(DateTime dt);

Parameters

• dt

  A DateTime structure.

Return Value

An OracleDate structure.

explicit operator OracleDate(OracleTimeStamp)

This method converts an OracleTimeStamp structure to an OracleDate structure.

Declaration

// C#
public explicit operator OracleDate(OracleTimeStamp ts);

Parameters

• ts

  OracleTimeStamp

Return Value

The returned OracleDate structure contains the date and time in the OracleTimeStamp structure.

Remarks

The precision of the OracleTimeStamp value can be lost during the conversion.

If the OracleTimeStamp structure has a null value, the returned OracleDate structure also has a null value.

explicit operator OracleDate(string)

This method converts the supplied string to an OracleDate structure.

Declaration

// C#
public explicit operator OracleDate (string dateStr);

Parameters

• dateStr

  A string representation of an Oracle DATE.

Return Value

The returned OracleDate structure contains the date and time in the string dateStr.

Exceptions

ArgumentNullException - The dateStr is null.

ArgumentException - This exception is thrown if any of the following conditions exist:

• The dateStr is an invalid string representation of an Oracle DATE.

• The dateStr is not in the date format specified by the thread's OracleGlobalization.DateFormat property, which represents the Oracle NLS_DATE_FORMAT parameter.

Remarks

The names and abbreviations used for months and days are in the language specified by the DateLanguage and Calendar properties of the thread's OracleGlobalization object. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class OracleDateSample
{
  static void Main(string[] args)
  {
    // Set the thread's DateFormat to a specific format
    OracleGlobalization info = OracleGlobalization.GetClientInfo();
    info.DateFormat = "YYYY-MON-DD";
    OracleGlobalization.SetThreadInfo(info);
    
    // Construct OracleDate from a string using the DateFormat specified
    OracleDate date = (OracleDate)"1999-DEC-01";
    
    // Set a different DateFormat on the thread for ToString() 
    info.DateFormat = "MON DD YY";
    OracleGlobalization.SetThreadInfo(info);
 
    // Prints "DEC 01 99"
    Console.WriteLine(date.ToString()); 
  }
}

---

OracleDate Properties

The OracleDate properties are listed in Table 14-25.

BinData

This property gets a array of bytes that represents an Oracle DATE in Oracle internal format.

Declaration

// C#
public byte[] BinData{get;}

Property Value

An array of bytes.

Exceptions

OracleNullValueException - OracleDate has a null value.

Day

This property gets the day component of an OracleDate.

Declaration

// C#
public int Day{get;}

Property Value

A number that represents the day. Range of Day is (1 to 31).

Exceptions

OracleNullValueException - OracleDate has a null value.

IsNull

This property indicates whether or not the current instance has a null value.

Declaration

// C#
public bool IsNull{get;}

Property Value

Returns true if the current instance has a null value; otherwise, returns false.

Hour

This property gets the hour component of an OracleDate.

Declaration

// C#
public int Hour {get;}

Property Value

A number that represents Hour. Range of Hour is (0 to 23).

Exceptions

OracleNullValueException - OracleDate has a null value.

Minute

This property gets the minute component of an OracleDate.

Declaration

// C#
public int Minute {get;}

Property Value

A number that represents Minute. Range of Minute is (0 to 59).

Exceptions

OracleNullValueException - OracleDate has a null value.

Month

This property gets the month component of an OracleDate.

Declaration

// C#
public int Month {get;}

Property Value

A number that represents Month. Range of Month is (1 to 12).

Exceptions

OracleNullValueException - OracleDate has a null value.

Second

This property gets the second component of an OracleDate.

Declaration

// C#
public int Second {get;}

Property Value

A number that represents Second. Range of Second is (0 to 59).

Exceptions

OracleNullValueException - OracleDate has a null value.

Value

This property specifies the date and time that is stored in the OracleDate structure.

Declaration

// C#
public DateTime Value {get;}

Property Value

A DateTime.

Exceptions

OracleNullValueException - OracleDate has a null value.

Year

This property gets the year component of an OracleDate.

Declaration

// C#
public int Year {get;}

Property Value

A number that represents Year. Range of Year is (-4712 to 9999).

Exceptions

OracleNullValueException - OracleDate has a null value.

---

OracleDate Methods

The OracleDate methods are listed in Table 14-26.

CompareTo

This method compares the current OracleDate instance to an object, and returns an integer that represents their relative values.

Declaration

// C#
public int CompareTo(object obj);

Parameters

• obj

  An object.

Return Value

The method returns:

• Less than zero: if the current OracleDate instance value is less than that of obj.

• Zero: if the current OracleDate instance and obj values are equal.

• Greater than zero: if the current OracleDate instance value is greater than obj.

Implements

IComparable

Exceptions

ArgumentException - The obj parameter is not an instance of OracleDate.

Remarks

The following rules apply to the behavior of this method.

• The comparison must be between OracleDates. For example, comparing an OracleDate instance with an OracleBinary instance is not allowed. When an OracleDate is compared with a different type, an ArgumentException is thrown.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

Equals

This method determines whether or not an object has the same date and time as the current OracleDate instance.

Declaration

// C#
public override bool Equals( object obj);

Parameters

• obj

  An object.

Return Value

Returns true if obj has the same type as the current instance and represents the same date and time; otherwise returns false.

Remarks

The following rules apply to the behavior of this method.

• Any OracleDate that has a value compares greater than an OracleDate that has a null value.

• Two OracleDates that contain a null value are equal.

GetHashCode

Overrides Object

This method returns a hash code for the OracleDate instance.

Declaration

// C#
public override int GetHashCode();

Return Value

A number that represents the hash code.

GetDaysBetween

This method calculates the number of days between the current OracleDate instance and the supplied OracleDate structure.

Declaration

// C#
public int GetDaysBetween (OracleDate val);

Parameters

• val

  An OracleDate structure.

Return Value

The number of days between the current OracleDate instance and the OracleDate structure.

Exceptions

OracleNullValueException - The current instance or the supplied OracleDate structure has a null value.

ToOracleTimeStamp

This method converts the current OracleDate structure to an OracleTimeStamp structure.

Declaration

// C#
public OracleTimeStamp ToOracleTimeStamp();

Return Value

An OracleTimeStamp structure.

Remarks

The returned OracleTimeStamp structure has date and time in the current instance.

If the OracleDate instance has a null value, the returned OracleTimeStamp structure has a null value.

ToString

Overrides ValueType

This method converts the current OracleDate structure to a string.

Declaration

// C#
public override string ToString();

Return Value

A string.

Remarks

The returned value is a string representation of the OracleDate in the format specified by the thread's OracleGlobalization.DateFormat property. The names and abbreviations used for months and days are in the language specified by the thread's OracleGlobalization.DateLanguage and OracleGlobalization.Calendar properties. If any of the thread's globalization properties are set to null or an empty string, the client computer's settings are used.

Example

// C#
 
using System;
using Oracle.DataAccess.Client;
using Oracle.DataAccess.Types;
 
class ToStringSample
{
  static void Main(string[] args)
  {
    // Set the thread's DateFormat to a specific format
    OracleGlobalization info = OracleGlobalization.GetClientInfo();
    info.DateFormat = "YYYY-MON-DD";
    OracleGlobalization.SetThreadInfo(info);
    
    // Construct OracleDate from a string using the DateFormat specified
    OracleDate date = (OracleDate)"1999-DEC-01";
    
    // Set a different DateFormat on the thread for ToString() 
    info.DateFormat = "YYYY/MM/DD";
    OracleGlobalization.SetThreadInfo(info);
 
    // Prints "1999/12/01"
    Console.WriteLine(date.ToString()); 
  }
}