Controlling Time Zone Display When Developing PeopleSoft Application Objects
This section provides an overview of time zone display settings and discusses steps to set time zones in record field and page field properties.
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 or
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
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:
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.
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.
Select which related date field in the current record stores the calendar date to which this field should be adjusted.
Click OK.
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:
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.
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.
Click OK.
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.