UseHourOffsetForUnsupportedTimezone

This property specifies whether the hour offset can be used for the session time zone, when the Oracle time zone region name that is associated with the .NET locale is not supported by the Oracle Database being used.

Declaration

// C#
public bool UseHourOffsetForUnsupportedTimezone { get; set; }

Property Type

System.Boolean

Exceptions

InvalidOperationException – This exception will be thrown if this property is set when the Connection is in an Open state.

Remarks

ODP.NET is built to support the latest available time zones the Oracle database client supports. However, older Oracle database server versions may not have the latest time zone files that support all the same time zones the client supports. Thus, the client could request a connection time zone the Oracle database does not support. In these situations, the connection request returns an “ORA-01882: timezone region not found” error.

When the UseHourOffsetForUnsupportedTimezone property is set to true, then ODP.NET will initialize the connection/session time zone using a "hour offset" instead of a time zone region name only if the Oracle Database cannot support the Oracle time zone associated with the .NET locale. ODP.NET can then successfully connect and avoid the ORA-01882 error. This also means if the Oracle Database does support the Oracle time zone associated with the .NET locale, then the connection/session will be initialized with an Oracle time zone region name, regardless of the UseHourOffsetForUnsupportedTimezone property setting.

By default, the UseHourOffsetForUnsupportedTimezone property is set to false.

Oracle does not recommend using the hour offset since datetimes with time zone values will not be daylight savings time sensitive. Even when the hour offset is enabled, ODP.NET first attempts to use the Oracle time zone region name associated with the .NET locale. Only when the ORA-01882 error is encountered will ODP.NET use the hour offset as the session time zone during a second connection attempt. Thus, there can be two connection requests if the first connection attempt fails with the ORA-01882 error.

The UseHourOffsetForUnsupportedTimezone property value specified for the first successfully created connection is used for all subsequent connections in that pool. When pooling is not used, the property’s value will be specific for the particular OracleConnection.Open() invocation.

Oracle recommends resolving ORA-01882 errors by upgrading the Oracle database with the latest time zone/DST files. Oracle also recommends using the time zone region name for the session time zone so that datetime conversions with time zone values are daylight savings time sensitive.

If the Oracle Database time zone / DST files cannot be upgraded, the application should then set the UseHourOffsetForUnsupportedTimezone property to true.

Sample Code

using System;
using Oracle.ManagedDataAccess.Client;

class Test
{
  static void Main(string[] args)
  {
    string constr = "user id=hr;password=<password>;data source=oracle;”

    OracleConnection con = new OracleConnection(constr);

    // Have the connection created with the ‘hour offset’ being used as the session time zone
    // if the Oracle Database does not support the Oracle Time Zone associated with the 
    // .NET application’s locale
    con.UseHourOffsetForUnsupportedTimezone = true;

    // Establish a connection to Oracle
    con.Open();
    con.Dispose();
  }
}