Setting and Maintaining Time Zones

This chapter provides an overview of time zones and discusses how to:

• Set the base time zone.

• Maintain time zones.

• Update time zones to reflect the Energy Policy Act of 2005.

• Control the time zone display when you develop PeopleSoft application objects.

Understanding Time Zones

PeopleSoft applications store times based on a system-wide base time zone and support the display of times relative to a user’s local time zone or relative to the time zone in which a transaction is entered (called a specified time zone).

For example, if the base time zone is universal coordinated time (UTC, also known as Greenwich mean time or GMT), a time entered as 10 a.m. in U.S. eastern standard time (EST) is stored as 3 p.m., because of the time difference between the two locations. This allows for easy comparison and manipulation of times, so that PeopleCode developers do not have to worry about time zone differences. Additionally, all batch processes, such as Structured Query Reports and COBOL, operate in the base time zone of the system.

However, although the time is stored as 3 p.m., it can still appear to the user as 10 a.m. EST, or as the appropriate time for any time zone that you choose. You can also set up the system to enable users to choose the time zone for specific time or datetime displays.

To support display in alternate time zones, the PeopleSoft system delivers an initial global list of time zones, including information about daylight savings time observances. When a time zone begins or ends in daylight savings time, both the description of the zone and the times that are associated with that zone are adjusted to reflect the change. This approach ensures chronological consistency throughout an organization’s geographically dispersed locations, while allowing for flexibility in how users see times.

Base Time Zone Details

This time zone is used for display when no other time zone is specified. The base time zone must match the time zone in which the database server is operating, specifically the time zone to which the meta-SQL %CurrentDateTime token returns. For example, in an Oracle database, the base time zone is the time zone in which the SYSDATE system variable is returned. You must enter this time zone on the PeopleTools Options page for your system to function correctly.

The base time zone is also used for the following:

• All effective-date processing.

  Rows become effective when midnight passes on the effective date according to the base time zone of the system.

• Internal processing in PeopleCode and all batch processes.

• Display on pages and in reports, if no other time zone information is specified or available.

User Time Zone Details

The user time zone is read from the operating system of the user’s web browser in the PeopleSoft Pure Internet Architecture.

Specified Time Zone Details

Specified time zones are useful for applications where users must see the same time and time zone as those who enter transactions, such as in call processing systems. To implement a specified time zone field, your record must contain a time zone control field.

Setting the Base Time Zone

Select PeopleTools, Utilities, Administration, PeopleTools Options to access the PeopleTools Options page.

The base time zone that you define for PeopleTools must match the time zone used by your database. Any discrepancy between the two leads to inaccurate time processing.

To set the base time zone:

1. Select a time zone from the Base Time Zone field.

   Values are maintained in the Time Zones component (TIMEZONEPNLGRP).

   See Maintaining Time Zones.

2. Click the Save button.

   Note. After selecting a base time zone during installation, avoid changing it. There is no automated processing to translate existing time information in the database to a new base time zone, and if you change the time zone defined on the PeopleTools Options page, no adjustment is made to existing time data in your database.

Maintaining Time Zones

This section provides an overview of time zone maintenance and discusses how to:

• View time zone definitions.

• Generate time zone offsets.

• View daylight savings start and end dates.

Understanding Time Zone Maintenance

PeopleSoft delivers an initial list of time zones; including information about daylight savings time observances. The PeopleSoft system does not maintain time zone data. You are responsible to ensure the time zone data is kept updated. Use the Time Zone component to manage time zone data.

Viewing Time Zone Definitions

Select PeopleTools, Utilities, International, Time Zones to access the Time Zone Data page.

Time Zone Tab

Daylight Savings Tab

Select the Daylight Savings tab to view daylight savings offset information.

Daylight Savings Offset	Displays the number of minutes by which the time is offset during daylight savings time.
Daylight Saving Time Start	Displays the day that daylight savings time begins. This field prompts against values from the Daylight Savings page.
Daylight Savings Time End	Displays the day that daylight savings time ends. This field prompts against values from the Daylight Savings page.

Generating Time Zone Offsets

Click the Generate Query Offsets button on the Time Zone Data page to access the Time Zone Offset Generation page.

To generate query offsets:

1. Enter a start date and an end date.

   Select a reasonable range of dates. With the time zones delivered with the PeopleSoft system, more than 100 rows are generated for each year.

2. Click OK.

   The data is generated for the table. Any existing data for the same range of dates is overwritten.

For example, the following data from the PSTZOFFSET table represents one time zone, EST, for a two-year period, from January 1, 1999, to January 1, 2001. It is based on a system with PST as the base time zone. When you generate query offsets, the PSZOFFSET table contains similar data for all the time zones.

PSTZOFFSET table

The first row of data shows that from January 1, 1999, at midnight, until April 3, 1999, at 11 p.m., (base time—PST, in this case), the offset between EST and the base time zone is 180 minutes, meaning that EST is 180 minutes ahead of PST. The label for EST during this period is EST.

The second row shows that from April 3, 1999, at 11 p.m., until April 4, 1999, at 2 a.m., there is a three-hour time period during which EST is 240 minutes ahead of PST. This is because EST has changed to daylight savings time, but PST hasn’t changed yet. The label for EST during this period is EDT, for eastern daylight time.

Viewing Daylight Savings Start and End Dates

Select PeopleTools, Utilities, International, Time Zones, Daylight Savings to access the Daylight Savings page.

Daylight Savings Time ID	Displays a unique identifier for the date.
Absolute	Clear this check box to indicate a relative date, such as Last Sunday in October.
Day	For absolute dates, displays the day of the month. For relative dates, the numbers 1, 2, 3, and 4 represent the first, second, third, and fourth occurrence of the day of the week; for example, to describe the second Sunday in February, enter 2. The number 5 for a relative date indicates the last occurrence of the specified day of the week, even if that day of the week occurs only four times in the month.

Complying with the Energy Policy Act of 2005

As a result of the Energy Policy Act of 2005, Daylight Saving Time will start earlier and end later, beginning in 2007. In the US and Canada, Daylight Saving Time will start the second Sunday in March and end the first Sunday in November.

To comply with this change, you need to add two new Daylight Saving Time IDs, set your affected time zones to use the new Daylight Saving Time IDs, and regenerate your offset data. Depending on your business needs, you may also want to define new time zones and associate them with Daylight Saving Time IDs.

Separately, you should apply operating system patches according to your vendor’s directions so that file system time stamps will also be in compliance.

Adding New Daylight Savings Time IDs

To add new Daylight Savings Time IDs:

1. Go to PeopleTools, Utilities, International, Time Zones, Daylight Savings

2. Click the Add button and add the following information:

   Option	Value
   Daylight Savings Time ID	22ndSunMar
   Absolute	Unchecked
   Month	Mar
   Day	2
   Day of Week	Sunday
   Hour	2
   Minute	0
   Description	Second Sunday in March, 2:00am

3. Click the Add button again and add the following information:

   Option	Value
   Daylight Savings Time ID	2FirstSunNov
   Absolute	Unchecked
   Month	Nov
   Day	1
   Day of Week	Sunday
   Hour	2
   Minute	0
   Description	First Sunday in Nov, 2:00am

4. Click Save to save your changes.

Update Affected Time Zones

To update affected time zones:

1. Go to PeopleTools, Utilities, International, Time Zones, Time Zone Data, Daylight Savings

2. Choose the Daylight Saving Time Start and Daylight Saving Time End IDs for your affected time zones.

   In the US and Canada, the affected time zones that PeopleTools delivers are the following:

   • AKST Alaska Time (US)

   • AST Atlantic Time (Canada)

   • CST Central Time (US)

   • EST Eastern Time (US)

   • MST Mountain Time (US)

   • NST Newfoundland Time (Canada)

   • PST Pacific Time (US)

3. Enter start and end dates for the time range to generate, for instance, 1/1/2007 to 1/1/2008, and click OK.

   This updates the time zone offset table (PSTZOFFSET) to reflect the current time zone and DST definitions. This data can be re-generated as needed.

   Note. To generate offsets earlier than 2007, set the time zone data accordingly first, then update the time zone data to the new values for offsets later than 2007. Do not generate offsets for a Start Date before 2007 and an End Date after 2007 in one run, since the offset data would only be correct for one time range or the other.

   See the additional time zone documentation available on PeopleSoft Customer Connection.

Define New Time Zones

You may want to define new time zones. For instance, Canada has decided to follow the US standard, while Mexico has decided to stay with the older definition. This means that for several weeks each year, PST in Los Angeles will be different from PST in Tijuana.

You can define a new time zone, such as PSTM (for PST Mexico) with the older Daylight Saving Time ID, to distinguish it from the PST (for PST US and Canada) with the new Daylight Saving Time ID.

After defining your new time zones, run Generate Query Offsets again so that the offsets include the new time zones.

Controlling Time Zone Display When Developing PeopleSoft Application Objects

This section provides an overview of time zone display settings and discusses how to:

• Set time zone options in record field properties.

• Set time zone options in page field properties.

• Use PeopleCode time functions.

Understanding Time Zone Display Settings

Although times are always stored in the base time zone, you can choose whether a page displays a time in the base time or in another time zone.

Time zone display and processing functions operate only on time or datetime fields, not on date fields. This is because all time zone processing requires the knowledge of the time component of the field, which is not provided in date fields. Even if some databases store PeopleSoft date fields internally as datetime fields, the PeopleSoft system does not use the time component of these fields.

Two settings work together to control the time display on pages in the PeopleSoft Pure Internet Architecture:

• Record field properties.

  Choose whether the time display is based on the base time zone or on another time zone. If you base the display on another time zone, you can specify a time zone control field, which determines the time zone.

• Page field properties.

  Choose whether to automatically include the time zone abbreviation in a field that displays time or datetime values.

Use these guidelines to help decide how to implement time zone displays:

• If the record field properties option specifies that time appears in the base time zone, setting the page field properties to show the time zone helps users interpret the time shown on the page.

• If the record field properties option specifies that the time zone of a particular time or datetime field is determined by the time zone control field, then put that control field directly on the page, to enable the user to manually select the time zone for a field.

• If you put the time zone control field on the page where users are permitted to enter a time zone, disable the page field properties option that includes the time zone abbreviation in the time field.

  It is redundant to show the time zone in both places.

• If you do not permit users to enter a time zone manually, for example, if you use the %ClientTimeZone or %BaseTimeZone system variables to set the time zone, then display the time zone either by including the control field on the page or by setting the page field properties appropriately—not both.

In the Microsoft Windows client, users can display time values in their local time zones or in the system’s base time zone, regardless of how the record field properties and page field properties are set. By default, all Microsoft Windows client time and datetime fields appear in the base time zone, but each user can override this option by selecting View, Time Display, Local Time or View, Time Display, Database Time.

Understanding Time Zone Precedence

Time zone displays can be controlled at three levels.

• Field-specific time zone.

  Set field-specific time zone options in Record Field Properties in PeopleSoft Application Designer.

• User-specific time zone.

  Set user-specific time zone options in My Personalization in the PeopleSoft Pure Internet Architecture. To access the options, select My Personalizations, Regional Settings.

• System base time zone.

  Set System base time zone options using the PeopleTools Options page in the PeopleSoft Pure Internet Architecture. To access the page, select PeopleTools, Utilities, Administration, PeopleTools Options.

PeopleTools checks for time zone preferences in the order of field-specific, then user-specific, then system base time zone.

A display control can be set for a specific field. The time zone display is controlled for a field via the Time Zone settings in Record Field Properties. The time zone control field overrides the user-specific time zone.

For example: you have four time values on a page, one of which has a time zone control field. This field will display in the time zone specified in the control field. The other three time fields will display in the user-specific time zone if set, and otherwise in the system base time zone.

Users can specify a time zone preference using Use Local Timezone and Local Time Zone options in the PeopleSoft Pure Internet Architecture. To access time zone preference settings, select My Personalizations, Regional Settings.

The Use Local Timezone option means to display all times and datetimes in the time zone specified in the Local Time Zone option

Setting Time Zone Options and Related Date Fields in Record Field Properties

When a record includes a time or datetime field, choose whether the PeopleSoft system displays the time in the system’s base time zone, or in another time zone such as a time zone that corresponds to the user’s location. Set this option for all time and datetime fields.

Understanding Related Date Fields

The purpose of a related date field is for accounting for daylight savings. Related date fields only apply to time fields, not datetime fields. If the user has set their personalization to show times in their local time zone, then the runtime engine calculates the offset of the local time zone from the database time zone and applies that offset to the value before displaying it.

Similarly it does the reverse when converting a user entered time back to database time. To calculate the offset between time zones the system must know if daylight savings is in effect, so you must provide the date. For a datetime field this is no problem, but for a time field the system needs only the current date. This can lead to some problems where someone enters data, then comes back to look at it at a later date and sees it has shifted by an hour because daylight savings has gone into affect in the meantime. Related dates resolve this problem.

When there is a related date, that date value is used to calculate the offset between the local and database time zones, therefore the calculation will always be the same and the time value won't change depending on when you look at it. Furthermore the related date field will look at the time field that is related to it to determine if it needs to be offset.

For example, lets say the database time zone is pacific standard time (PST), and the local time zone is eastern standard time (EST). If you enter 1:00 a.m. into a time field and 01/01/2000 into the date field related to that time, the time will be converted to 10:00 p.m. PST internally and for saving to the database, and the date will be converted to 12/31/1999, because 1:00 a.m. EST is 10 p.m. PST of the previous day. The offset is minus three hours.

Setting the Time Zone to Control Display Times

To set the time zone that controls the display time:

1. In the record, open the Record Field Properties dialog box for the time field by double-clicking the field that displays the time.

   The Use tab appears.

2. In the Time Zone group box, set the time zone property.

   If you leave the Specified Time Zone check box clear, the time appears in the database's base time zone, unless a user selects View, Time Display in the Microsoft Windows client to display in the user’s local time zone.

   If you select the Specified Time Zone check box, the system converts the time according to the time zone that is specified in the Time Zone Control Field field. You must specify a time zone control field in this record

   A single time zone control field can control multiple time and datetime fields on the record. Using a single control field causes all times to appear in the same time zone. If you want multiple time or datetime fields to appear in different time zones, you need separate control fields for each of them.

   You may want to set the default value of the time zone field to %ClientTimeZone or %BaseTimeZone. However, the default time zone is used only when the transaction is created. Because the time zone is saved along with the transaction itself, future users who access the transaction will see the time relative to that time zone.

3. Select which related date field in the current record stores the calendar date to which this field should be adjusted.

4. Click OK.

Setting Time Zone Options in Page Field Properties

When you place a time or datetime field on a page, you can choose whether to display the time zone in the same field where the time appears.

You would normally want to display the time zone this way when you want users to be aware of the time zone of a field without changing the time zone.

If, on the other hand, you want users to be able to set the time zone, don't display the time zone in the time field. Instead, design your page so that it includes a separate drop-down list box referencing the time zone control field. With this design, users can both see and change the time zone.

To show the time zone in the time field:

1. On the page, open the Page Field Properties dialog box for the time field by double-clicking the page control that displays the time.

   The Record tab appears.

2. Select the Display Time Zone box.

   When you select this box, the page displays the time zone in the same field as the time and resizes the edit box to allow space for up to 10 additional characters.

   This option has no affect on data entry. Users cannot override the time zone. Users who see the time in GMT must enter the time in GMT.

   If the field that is associated with this page control is not a time or datetime field, selecting the Display Time Zone box has no effect.

3. Click OK.

Using PeopleCode Time Functions

Three PeopleCode functions convert times to their base time zone equivalent: ConvertTimeToBase, ConvertDatetimeToBase and DayTimeToTimeZone. Another function, IsDaylightSavings, establishes whether daylight savings time is in effect on a particular date.

Additionally, you can use system variables %clienttimezone and %basetimezone in PeopleCode programs or as field default values. The %clienttimezone variable returns the current user’s local time zone, and %basetimezone returns the base time zone of the database.

See Also

PeopleCode Built-in Functions

System Variables