The time zone information, and the Foundation classes that use it, have been updated in WebObjects 4 to the information published by the U.S. Government, current as of October 1998. This document describes the changes to the system time zone information that have occurred since the release of WebObjects 3.5.1.

General Information Regarding Time Zone Changes

In brief, the update of time zone data underlying the NSTimeZone class cluster in WebObjects 4 includes:

• Addition of new time zones across the world
• Changes in the names of previously-existing time zones
• Addition of new time zone abbreviations across the world
• Changes to daylight saving time algorithms for named time zones, both current and historical.
• Change in notation of time offsets from Greenwich Mean Time to the POSIX minutes-west-of-GMT convention

For additional general information on time zones, see also:

http://www.cl.cam.ac.uk/~mgk25/iso-time.html

Changes in Foundation's NSTimeZone Class Cluster

The NSTimeZone class cluster was reimplemented between OpenStep 4.2 and WebObjects 4:

• Some methods in NSTimeZone have been deprecated, some have changed.
• New methods have been added to NSTimeZone--refer to the class documentation for details.
• The NSTimeZoneDetail class has been deprecated.
• NSTimeZone and NSCalendarDate objects created in OPENSTEP 4.2/WebObjects 3.5.1 can be unarchived and transmitted via DO to WebObjects 4.x, but the reverse is not true.

NSTimeZone

+abbreviationDictionary

Returns an NSDictionary of the new mapping of time zone abbreviations to named time zones. See sections below on mapping of abbreviations to zones.

+localTimeZone

Returns the new time zone object for the local named time zone. For example, if your machine is set to "US/Central" (old) or "America/Chicago" (new), this method will return the NSTimeZone object for the America/Chicago zone. See NSTimeZone class documentation for further details on this method.

+defaultTimeZone

Returns the new time zone object for the local named time zone. See NSTimeZone class documentation for further details on this method.

+setDefaultTimeZone:

No change in behaviour.

+timeZoneForSecondsFromGMT:

Returns the GMT offset object for the time value, in seconds, represented by the integer argument. See section "Named Time Zones versus GMT Offsets", below, for important information on changes since OpenStep.

Due to a known problem, this method does not work in currently shipping versions of WebObjects 4. No workaround is currently available.

+timeZoneArray

No change in behaviour.

Deprecated. There is no replacement for this method.

+timeZoneWithName:

Returns the new time zone object for any old or new time zone name that Foundation recognizes.

Due to a known problem, this method does not work on the Windows NT version of WebObjects 4. For a workaround, see TIL article 70013 .

+timeZoneWithAbbreviation:

Returns the new time zone object for the named zone associated with the abbreviation argument in the Abbreviation.table resource. Use+abbreviationDictionary to get the current association of abbreviation to zone. See sections below on mapping of abbreviations to zones.

-timeZoneName

Returns the new name for the time zone instance. For example, a time zone object created via +timeZoneWithAbbreviation: with an argument of "US/Mountain" will return a name value of "America/Denver".

Deprecated. Replace with -[NSTimeZone name].

-timeZoneDetailArray

Returns an empty NSDictionary.

Deprecated. There is no replacement for this method.

-timeZoneDetailForDate:

No change in behaviour; class of return valued changed from NSTimeZoneFileDetail to NSConcreteTimeZone.

Deprecated. Replace with -[NSTimeZone abbreviationForDate:].

NSTimeZoneDetail

-isDaylightSavingTimeZone:

No change in behaviour.

Deprecated. Replace with -[NSTimeZone isDaylightSavingTime]

-timeZoneAbbreviation

No change in behaviour;

Deprecated. Replace with -[NSTimeZone abbreviation]

-timeZoneSecondsFromGMT

No change in behaviour - correctly handles old and new time zone names.

Deprecated. Replace with -[NSTimeZone secondsFromGMT]

The reimplementation of NSTimeZone cluster classes has altered the encoding and archiving of NSTimeZone and NSCalendarDate objects. WebObjects 4.x is able to unarchive and decode (transmit over DO) objects of the classes from OpenStep 4.2 / WebObjects 3.x. However, OpenStep and WebObjects 3.x can not unarchive or receive over DO NSTimeZone or NSCalendarDate objects from WebObjects 4.x.

Regardless of whether archiving or DO is used, mixed testing or deployment environments using both old and new time zone data and classes will be problematic and should be avoided. If the software stores time zone information in a database, old applications reading that database will be unable to interpret the new time zone names stored there by applications converted to YellowBox or WebObjects 4.x.

Named Time Zones versus GMT Offsets

A crucial concept for developers to grasp when working with time zone data is the difference between named time zones and GMT offsets. These are two fundamentally different concepts which can not be used interchangeably.

GMT offsets are absolute distances from Greenwich, England. Although a GMT offset can be constructed with any value, the usual usage divides the globe into 24 whole-hour units - twelve east of Greenwich and twelve west. The NSTimeZone class constructs GMT offsets from integer arguments representing the number of seconds east (positive integers) or west (negative integers) of Greenwich. GMT offsets do not vary with season, historical year, or political boundary.

Named time zones, such as "US/Eastern" or "Europe/London", do vary with season (daylight saving), historical year (the rules for daylight saving may change for a given time zone, over time), and political boundary (as political boundaries shift and laws change, the date calculations for a particular geographic location may change). The data for named time zones have changed for WebObjects 4--there are numerous corrections and additions to daylight saving rules resulting from improved accuracy in political and historical information and in daylight saving transition formulae.

For named time zones that observe daylight savings, the GMT offset which corresponds to the zone changes at different times of the year. For example, during the observation of standard time, the named time zone which encompasses most of the west coast of the United States (formerly called "US/Pacific", now "America/Los_Angeles") corresponds to the offset seven hours west of GMT. During the observation of daylight savings, this named zone corresponds to the offset eight hours west of GMT. Daylight savings shifts are not always whole hours - some named time zones shift by only one-half hour, some shift by some other fraction of an hour (like 50 minutes).

Not all named time zones observe daylight savings. For these, the GMT offset remains constant throughout the year.

Change in GMT Offset Notation

A key change in the time zone data which customers should understand before converting their applications to YellowBox / WebObjects 4.x is the change in the way that GMT offsets are denoted. The convention followed by the U.S. Government time zone data underlying Foundation in OpenStep 4.2 subtracted hours as one moved west of Greenwich and added hours as one moved east of Greenwich. Therefore, the offset five hours east of Greenwich was denoted as "GMT+5" or "GMT+0500" and the offset five hours west of Greenwich was denoted as "GMT-5" or "GMT-0500".

In the current time zone data received from the U.S. Government, the notation for GMT offsets has been changed to to the POSIX minutes-west-of-GMT convention, which adds hours west of Greenwich and subtracts hours east of Greenwich. This is OPPOSITE of the notation in OpenStep 4.2, so that the offset which used to be designated as "GMT-8" or "GMT-0800" is now designated "Etc/GMT+8".

The Foundation in WebObject 4.x can correctly map the old GMT offsets onto the new ones. However, if a customer is extracting the hour value from the offset and doing math calculations with it, they will need to take this into account or their software will return the opposite result from that obtained in OpenStep 4.2 / WebObjects 3.x.

Mapping of Old Time Zone Names to New Time Zone Names

A large number of named time zones have been added since the original release of OpenStep 4.2. Many reflect political changes in Europe and the former Soviet Union, but there are also many new named time zones for Pacific, Asian, Latin American, and African nations.

In addition, many previously-existing named time zones now have different names. For example, ALL of the named time zones in Canada, the U.S., and Australia have changed names. Here are some examples of the old and new time zone names from those countries:

Microsoft Windows uses different time zone names than either old or new UNIX names. In order to provide consistent behavior across platforms, the Foundation framework translates Windows' time zone names to UNIX names, using the WindowsName.table in both OpenStep and YellowBox.

Time Zone Abbreviation to Time Zone Name Mapping

For each named time zone, several time zone abbreviations may be used to designate different local time types, that is, sets of rules for the behaviour of local time in that zone. For example, the America/Los_Angeles time zone (formerly called US/Pacific) has three local time types with associated abbreviations: PST, PDT, and PWT. A single named zone may contain a number of local time zones which reuse the same abbreviation. For example, the Pacific/Niue time zone covers three local time types which all use the abbreviation NUT. The Africa/Ceuta zone covers seven local time types, of which two use the abbreviation WET, two use WEST, two use CET, and one uses CEST.

Conversely, any number of different named time zones may reuse the same abbreviation. For instance, the abbreviation NST is used by the America/Adak, America/Goose_Bay, America/Nome, America/St_Johns, Pacific/Midway, and Pacific/Pago_Pago time zones. The abbreviation CET is used by 30 named time zones in the Atlantic, Europe, and Africa regions! As a result, there are very few time zones or time zone abbreviations for which the mapping from name to abbreviation is unambiguous. This ambiguity existed with the old time zone information but is much more pronounced with the greatly increased number of named time zones in the new data.

Foundation limits the ambiguity of mapping between time zone name and abbreviation for the NSTimeZone class by maintaining a dictionary which associates a single named time zone (the value) with a single abbreviation (the key). This file, Abbreviation.table, is located in the Foundation.framework/Resources/TimeZoneInfo directory. The list of abbreviations in the file is not comprehensive and the choice of time zone name associated with each is necessarily arbitrary. The NSTimeZone class in both WebObject 4 and OpenStep includes a class method, +abbreviationDictionary , which returns a dictionary containing the current association of time zone with abbreviation.

Changing the Time Zone Abbreviation to Time Zone Name Mapping

The Abbreviation.table file is a Unicode persistent property list. It may be edited by users, if needed, to achieve a different association of abbreviation with named time zone. Root permission is needed to edit this file. Anyone editing this file should be sure to use a Unicode-capable editor and save the edited file as Unicode. It is strongly recommended that a back-up copy of the original file be made before editing. Also, customers should keep in mind that if the abbreviation-to-named-zone mapping is changed on one machine and not on others which operate on the same data, inconsistent results will occur.

Foundation Time Zones versus Operating System Time Zones

All of the operating systems on which OpenStep and WebObjects ship include time zone information as part of the OS. The time zone information on different operating systems, and operating system versions, varies. In order to provide consistent behaviour of applications across the various platforms, Foundation encapsulates the time zone data on which its time zone classes operate.

Thus, in many cases, the time zone names, time zone data, and/or GMT conventions in Foundation and applications utilizing the Foundation time zone classes is different from the time zone names, daylight saving data, and /or GMT conventions of the operating system. Customers should particularly keep this in mind if they have non-OpenStep/WebObjects applications which manipulate or store time zone information in a database or other persistent storage.