IBM Support

How to programmatically convert the timezone property of a date/time value

Technote (FAQ)


The IBM Lotus Notes Client is able to automatically represent date/time values in the local time zone, but in some cases it made be desirable to reset the TimeZone property of a date/time value. Is there a way to programmatically convert the timezone property of a date/time value?


Programmatically this can be done using the Formula language as well as the LotusScript language. Both languages provide the means to convert a current date/time value to the corresponding date/time value in a different time zone.

Formula language:
In Notes/Domino 6.0 the Formula language introduced a new function called @TimeMerge. The function returns a date/time value which has date, time and timezone values converted relative to the time zone specified.

Note: The third parameter of the method contains a lengthy text string which represents the relative time zone (for example the string for Easter Daylight Time is "Z=5$DO=1$DL=4 1 1 10 -1 1$ZX=25$ZN=Eastern"). There is no documentation on these parameters, and in order to determine the correct string for the time zone you would like to use it is suggested that you create a sample form with a field with the type 'Timezone'. Create a sample document with the form and set the field to the desired time zone. Next, copy the field's content using the Document properties, and use this string in the code.
    @TimeMerge( date ; time ; timeZone )
    Builds a time-date value from separate date, time, and time zone values.

    date - Time-date value. The date you want to include in the new date-time value.
    time - Time-date value. The time you want to include in the new date-time value.
    timeZone - String. Optional. The canonical time zone value you want to apply to the new date-time value. You can use a Time zone field to create this value.

    Return value
    A new time-date value made up of the date, time, and zone supplied as function parameters.

LotusScript language:
The ConvertToZone method (of the NotesDateTime class) allows you to modify a date/time value of the current NotesDateTime object.
    For example the following code, when executed on a system in the PDT will convert the NotesDateTime object to EDT such that the ZoneTime value will have a time portion of 2 PM and the zone portion EDT.

Dim dtA As New NotesDateTime("10/28/2005 11:00 AM")
Call dtA.converttozone(5, True)

The LotusScript language also contains an undocumented method named Merge (of the NotesDateTime class) which can perform similar functionality. The method has two parameters. The first parameter is a NotesDateTime object. The second is a string value representing the Timezone, which is similar in structure to the third parameter used in the @TimeMerge function - see the note above for details.
    This example converts a date/time value of 10/28/2005 11am to EDT. If the original time zone was PDT then the resulting date/time value would have a time of 2pm.

    Dim sTimeZone As String
    sTimeZone = "Z=5$DO=1$DL=4 1 1 10 -1 1$ZX=25$ZN=Eastern"
    Dim dtB as New NotesDateTime("10/28/2005 11:00 AM")
    Call dtB.merge( dtB, sTimeZone )

In addition, LotusScript also allows you to specify a Timezone property when declaring a new NotesDateTime object. By default the Timezone property defaults to the value set on the current system, but if one is specified it will be observed. This functionality is not currently documented.
    This example demonstrates creating a date/time value based on Eastern Daylight Time:

    Dim dtC as New NotesDateTime("10/28/2005 2:00 PM EDT")

Supporting Information
The Notes Client automatically converts date/time values to local time zones, so in many cases converting a date/time value may not actually be necessary. For example, in LotusScript the LSGMTtime property (of the NotesDateTime) can easily be used in a comparison or conditional.

In a form design, date/time fields can be specified to display with three different options:
    - Always time to local zone
    - Always show time zone
    - Show only if zone is not local

Documentation for the time zone attributes is available in the topic "Time-date constants" in the Domino Designer Help. Below is the relevant excerpt from that the document:

Notes converts and saves human-readable time zone values using the following time zone attributes:
Z Time zone offset from GMT.
DO Daylight Saving Time (DST) observed flag. 1 means DST is in effect; 0 means it is not. If equal to 1, a value should be supplied for DL.
DL DST law identifying the <StartMonth> <StartWeek> <StartDayOfWeek> <EndMonth> <EndWeek> <EndDayOfWeek>.
ZX (Optional) Host-specific time zone index.
ZN (Optional) Time zone name.
For example, if you select "(GMT -05:00) Eastern Time (US & Canada)" from the Time zone drop-down list, Notes saves the value as:

Z=5$DO=1$DL=4 1 1 10 -1 1$ZX=25$ZN=Eastern

This indicates that the time zone is 5 hours before Greenwich Mean Time (-5). DST is in effect and starts in the month of April(4), during week 1, on day 1 of the week, which is a Sunday, and ends in October(10), during the last week (-1), also on a Sunday(1). The ZX and ZN attributes are values used exclusively by Notes.

    Cross reference information
    Segment Product Component Platform Version Edition
    Messaging Applications Lotus End of Support Products Lotus Notes

Document information

More support for: Lotus End of Support Products
Lotus Domino Designer

Software version: 6.0, 6.5, 7.0

Operating system(s): Windows

Reference #: 1219768

Modified date: 22 February 2010