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.

• 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, PeopleSoft 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. PeopleSoft 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 Savings 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.

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’s 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.

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

Two PeopleCode function convert times to their base time zone equivalent: ConvertTimeToBase and ConvertDatetimeToBase. 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

Date and Time