ConvertTimeStamp

(Engine-Level Function)

Description:	Converts a time stamp from one time zone to another.
Returns:	Numeric (double)
Usage:	Script only.
Function Groups:	Time and Date
Related to:	TimeZone \| TimeZoneList
Format:	ConvertTimeStamp(Timestamp, SourceTZ, InDST, DestTZ)
Parameters:

Timestamp

Required The timestamp (in seconds) to be converted since midnight of January 1, 1970. The timestamp parameter is limited to a minimum of 0, and a maximum of 34359738367. Values outside this range will cause Invalid to be returned.

SourceTZ

Required. The name, in English, of the time zone from which Timestamp originated. The name must be a name in the list returned by the TimeZoneList function. May also be a structure - see Comments.
If Invalid, or not a valid time zone name, then UTC is used as the source time zone. If set to "0", the local server's time zone is used.

InDST

Required. A flag that indicates whether daylight savings time (DST) was in use in the source time zone at the moment defined by Timestamp. This flag is used only for the period at the end of DST where a local time may appear twice. You must write your own expressions to determine this for your region
If true (non-0), DST is in effect. If false (0), DST is not in effect.
If INVALID, the default value is false. INVALID is recommended for most situations.

If the source time zone does not observe DST (as is the case with values stored using UTC, which is everything that the Historian saves), then this flag has no effect.

DestTZ

Required The name, in English, of the time zone to which Timestamp is to be converted. The name must be a name in the list returned by the TimeZoneList function. May also be a structure - see comments.
If invalid, or not a valid time zone name, then UTC is used as the destination time zone. If set to "0", the local server's time zone is used.

Comments:

The function returns the converted timestamp as a number indicating the number of seconds since midnight of January 1, 1970. The SourceTZ and DestTZ parameters must use names as returned by the TimeZoneList function.
The function uses the time zone information in the registry to determine local time zone bias, DST bias, and starting and ending dates of DST. If the information in the registry is incorrect, then it may be updated using the TZEdit tool available from Microsoft.

Be aware that the local server's time zone may differ from the geographic time zone. Client workstations (and thin clients) may have time zones that differ from the local server's configuration. Timezone(3) is a thin client safe approach to converting to or from the local time. Timezone is thin client aware, and adjusts the returned timezone as appropriate for converting for the session under which it is run.

Timezone names must be provided only in English, using the same names as reported by TimeZone(2), TimeZone(3), and TimeZoneList().

Both the SourceTZ and DestTZ parameters may be provided as structures. These structures will have two members

StdTimeZone - a string that represents the standard name for the time zone
ObservesDST - a Boolean, where 0 indicates that the time zone does not observe daylight savings time and a 1 indicates that it does

The purpose of this structure is to handle systems that are set to a time zone that does normally observe DST, but the users have configured Windows™ to not adjust for daylight savings time. This structure is the same as that used by option 3 of the TimeZone function.

Example:

Init [
  If 1 Main; 
  [ 
    { Convert from UK to Atlantic Standard Time } 
    Timestamp = ConvertTimeStamp(CurrentTime(), 
                                 "GMT Standard Time" { Specify source TZ    },
                                 0                   { Not daylight savings },
                                 "Atlantic Standard Time" { Destination TZ  }); 
  ] 
]

To convert the timestamp stored in SomeStartTime to GMT time:

  TimeStamp = ConvertTimeStamp(SomeStartTime, TimeZone(3), 0, Invalid);

Converting from server timezone to the client session specified timezone:

  ConvertTimestamp(ServerTime, "0" { Server local time }, 
                   Invalid, 
                   Timezone(3) { Thin client aware local time });