NotesdateTime.merge / @TimeMerge

[Michael DELIQUE]

Question

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?
Answer

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.

Parameters
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
Time-date
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")


Source => http://www-01.ibm.com/support/docview.w ... wg21219768