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 zone definitions to comply with legislative and other changes.

• 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 U.S. Pacific time (PST), a time entered as 10 a.m. in U.S. eastern time (EST) is stored as 7 a.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 7 a.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 saving time (DST) observances. When a time zone begins or ends in daylight saving 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.

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:

• Define time zones.

• Generate time zone offsets.

• Define daylight saving time IDs (DST IDs).

Understanding Time Zone Maintenance

Oracle delivers a subset of time zone data including information about daylight saving time observances in the Time Zone table (PSTIMEZONE). The Oracle-provided subset of time zone data is consistent with current law at the time of the PeopleTools GA release. Oracle does not provide patches or updates to this time zone data once it is released—for example, to bring it up to date with recently enacted legislation. Therefore, you are responsible for two tasks: the creation of all time zone data not included in the Oracle-provided subset that is required by your global operations, and the maintenance and update of all time zone data whenever local regulations change the definition for a time zone—for example, changes to the daylight saving time start or end date.

Defining Time Zones

Access the Time Zone IDs page (PeopleTools, Utilities, International, Time Zones).

Time Zone Data Tab

Daylight Saving Data Tab

Select the Daylight Saving Data tab to view daylight saving offset information and the IDs specified for daylight saving time start and daylight saving time end.

Observes DST	Indicates whether the time zone observes daylight saving times. If this check box is cleared, the other DST values have no effect.
DST Offset	Displays the number of minutes by which the time is offset during daylight saving time.
DST Start ID	Displays the ID for when daylight saving time begins. This field prompts against values from the PSDSTTIME table (the DST IDs page).
DST End ID	Displays the ID for when daylight saving time ends. This field prompts against values from the PSDSTTIME table (the DST IDs page).

Generating Time Zone Offsets

Access the Time Zone Offset Generation page (click the Generate Query Offsets button on the Time Zone IDs 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.

   Note. If you receive an error about missing daylight saving time IDs, the error can be corrected by adding entries to the PSDSTTIME table on the DST IDs page.

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 PSTZOFFSET table contains similar data for all the time zones defined in the PSTIMEZONE 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 saving time, but PST hasn’t changed yet. The label for EST during this period is EDT, for eastern daylight time.

Defining DST IDs

Access the DST IDs page (PeopleTools, Utilities, International, Time Zones, DST IDs).

DST ID	Displays a unique identifier for the combination of date and daylight saving start time. For example, 22ndSunFeb represents the second Sunday in February at 2:00 am.
Absolute	Clear this check box to indicate a relative date, such as the last Sunday in October.
Month	Displays the month.
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. Use the number 5 for a relative date to indicate the last occurrence of the specified day of the week, even if that day of the week occurs only four times in the month.
Hour	Displays the hour at which the time switch occurs.
Minute	Displays the minute at which the time switch occurs.
Description	Provides a description of the DST ID.

Updating Time Zone Definitions to Comply with Legislative and Other Changes

From time to time, legislative changes can impact the definitions of time zones, such as whether a time zone observes daylight saving time and the start or end date for daylight saving time observance. The PeopleSoft system provides updated time zone definitions in the next release following such a legislative change, and new customers as of that release receive the updated time zone data. However, existing customers upgrading to that new release do not receive the benefit of updated time zone data because customer time zone data is not changed during upgrade. In these cases, you can manually modify your time zone definitions to comply with changing rules.

As a specific example, the U.S. Energy Policy Act of 2005 changed time zone definitions in the U.S. and Canada. PeopleSoft-delivered data in the current PeopleTools release already reflects these changes. An appendix provides the procedure that you would use if you needed to update your time zone definitions to comply with this act.

See Updating Time Zone Definitions.

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 Application Designer, 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 Application Designer 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 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. Click the Personalize Option button for 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 saving time. 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 saving time 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 saving time 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 Application Designer, open the record, and 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 by default, unless a user specifies a local time zone in My Personalizations, Regional Options to display times in the user’s local time zone.

   If you select the Specified Time Zone check box, the field displays 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 saving 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

AddToDate

System Variables