Times, time-zones and DST corrections.

The two time-zones:

• The first thing to realize is that there are two time-zones involved in the times in your final EPG, each with its own DST rules:
- the time-zone for which the times of the guide is provided (the 'source' time-zone) and
- the time-zone of the user (the 'target' time-zone).
In the majority of cases these two are equal, but that doesn't change the fact that there are two to consider.
• In principle, the guide times must be corrected for UTC offset and DST changes for both these two time-zones: The first correction, the one for the 'source' time-zone, is done by WG++ and the second, for the 'target' (should be done) by some piece of software at the viewers side, probably the PVR xmltv importer.

The wrong way:

• In earlier versions of WG++ (before version 1.1.1.53) the program was unable to identify the 'source' time-zone correctly, the only info available about it was the time-zone value in the SiteIni. But that value was limited to just an UTC offset, not the proper time-zone_id and the DST rules for that. (The reason for that limitation lies in the fact that timezone_id's are not standardised among the varies computer platforms, Windows, Linux, OSX, for which WG++ should work) Therefore the DST correction that WG++ applied for the 'source' time-zone was done with the DST rules of the 'target' time-zone. Consequently, the DST changeover dates applied for the source time-zone were the DST changeover dates of the target time-zone. Although wrong in principle, it is only a problem if these DST changeover dates of source and target time-zones are different, which is possible but unlikely. (no problem if the user lives in the 'source' time-zone).
• Situations when this goes wrong? Examples:
- If a user in Europe wants to use a guide from the US (they have different DST changeover dates), or any other mismatch of DST changeover dates. Or,
- if the source time-zone has no DST rules (no DST in that zone) and the user lives in a time-zone with DST rules. Or the opposite. Or,
- if the source time-zone is UTC (the guide times are not in any particular time-zone, just plain UTC or GMT). Any user living in a time-zone with DST rules will run into problems because WG++ will apply the DST rules of the viewer to the xmltv startime which was meant to be UTC without any DST rule.
• The problems explained above can be 'corrected', temporary, by either changing the time-zone value in the siteini or by using the small utility xmltv_time_correct, (available @ http://www.webgrabplus.com/sites/default/files/download/utility/xmltv_ti... on the download page) for the period of the mismatch of the DST rules.

The right way:

• To solve these problems, later versions of WG++ include an integrated international 'cross platform' time-zone database that correctly identifies the source time-zone and the DST rule for that.

With that, WG++ doesn't use the target time-zone any more. The two above mentioned DST corrections are completely separated, WG++ for the source, and the PVR's xmltv importer at the user end for the target.

How to interpret the times in the xmltv file created by WG++? :

• By definition, the XMLTV TIMES ARE IN UTC (GMT) !!

• The xmltv specification allows several formats for that and WG++ uses the one with an UTC offset, format yearmonthdayhourminutesecond +/-utcoffset or yyyyMMddhhmmss +/-hhmm. The first part of that is (in most cases) the date and time presented in the tvguide of the source site, the second part is the actual offset of that with respect to UTC. E.g start="20140602141500 -0500" represents a local time at the source of 2014/06/02 14:15 (or 2:15pm) in a time-zone that is 5 hours behind (-) UTC. So, because the result is UTC by definition, this is 2014/06/02 19:15 UTC .
• The eventual DST correction for the source time-zone is done by WG++ through changing the UTC offset with the effect that the result always remains the correct UTC source time for the start of this tv-program.

What about the start-time for the viewer in his time-zone? :

• The calculation, to be carried out by some piece of program at the viewer's side, probably the xmltv importer of the PVR program, must simply correct for the actual local UTC offset (corrected for DST if necessary). As example, a few cases:
- Suppose the viewer is in the same time-zone as that of the source, which is quite normal. Then the start-time value of 2014/06/02 19:15 UTC will be corrected back to 2014/06/02 14:15.
- Suppose the viewer's actual UTC offset is +8:00 (Singapore or there about), then this start-time is corrected to 2014/06/03 3:15 (early morning, next day)

What if the times in your EPG appear to be wrong?

• Make sure you have the latest WG++ version that has the integrated time-zone database.
• Check if the time-zone in the SiteIni you are using is the correct one for the epg source site.
• Check if the times in the xmltv file created by WG++ are indeed as described above (local epg source time and UTC offset)
• Make sure your computer is set to the correct time-zone of your location, enable DST and check the time and date setting
• Try to figure out if the xmltv importer of the PVR you are using works as described above (correct for the actual local UTC offset). (Some importers have problems with xmltv files containing different UTC offsets, reading only the first one found and assuming this to be the only one). In that case a small utility WG2MP can help.
http://webgrabplus.com/sites/default/files/download/utility/WG2MP/WG2MP.zip
• Some other importers use the UTC offset in the xmltv rather than the target timezone offset, in that case there is only : the final resort, temporary offset the guide times by using http://www.webgrabplus.com/sites/default/files/download/utility/xmltv_ti...