Pimlical Android Help

Handling Timezones

Any time entered into Pimlical can be associated with a specific timezone. Timezones are defined in an editable file called WorldTimezones.txt which is stored in the Pimlical folder on the phone. This file contains all the timezone information - and can be freely edited provided that is done with reasonable care as any syntax errors in this file will of course cause odd things to happen.

The advantage of having an editable file is that you can (a) reorganize the timezones to only include those one's that you frequently use and also place them in an order of your choosing, and (b) you can edit Daylight Savings Rules to accommodate changes (useful for countries like Australia where they change quite often).

There are three primary timezone preferences which are normally set automatically, but which can also be manually set if desired. The preference AutoSetTimezoneFromPhone will normally set the current/create timezones automatically. This preference must be set to false if you want to manually set the timezone information. When you first launch Pimlical, the Home Time Zone is defaulted to the current timezone you are in. From that point on, whenever you change timezones, the Create and Current timezones are set automatically.

Home Time Zone

This is the timezone you are in most of the time and would typically be where you live. It is not normally ever changed, unless you move to a new location. Any event that is entered without any explicit timezone designation will be set for the Home Time Zone. The reason for having a Home timezone is so you can make a permanent move from one timezone to another without having every time in the database adjusted (which would be the case otherwise if every event had an explicit timezone associated wiith it.

Current Time Zone

The current time zone reflects where you are currently located. It is normally set to Home Time Zone so that the timezone of the event will be whatever your home time zone is. When you travel around, this is the timezone setting that you would change, and the one that gets automatically changed for you on an Android device if the preference AutosetTimezoneFromPhone is set to true (and the default value of this preference is true). If your phone messes up and sets the wrong timezone (and this does happen on some Android phones!) - you can turn that preference to false and then manually set the timezone in preferences.

Create Time Zone

This is the timezone used by default for the creation of new events. In most cases it would be set to Home Time Zone when you are in the Home time zone and to the current timezone when you are travelling. However, you may wish to set the Create time zone to some other time zone (example, you are normally in New York, have just arrived in  Denver, but need to add a whole list of events in the Pacific timezone). As with CurrentTimeZone, this preference is one that gets automatically changed for you on an Android device if the preference AutosetTimezoneFromPhone is set to true.

Other issues with timezones

Timezones can be set separately for the start time and end time of an event, so if you have an airplane flight that starts in one time zone and ends in another, it can be set up properly in Pimlical/Android. Unlike Google, there is no restriction in using this feature on repeat events and the displayable instances of the repeat are adjusted based upon the Daylight Savings rules in effect at the time that repeat instance occurs.

Timezones do not have to be coordinated between the platforms. It is quite ok to have Pimlical/Android set to one timezone, Google calendar set to another and Pimlical/Desktop set to yet a third timezone - events will display properly in all cases.

To ensure that events display properly in Google or any other calendar server that may sync with the Android calendar database, Pimlical/Android normalizes all events to the timezone of the calendar whenever possible. Timezone information is stored in tags in the note field since Google does not support the ExtendedProperties field properly at this time.

If all events are suddenly appearing at the wrong time, off by a set number of hours - this is usually a give away that there is some problem with the timezones that are being set on events. Some phones do not properly record the local timezone - in that case, the ability to set the timezone preference manually is very useful! (But remember to set the preference AutosetTimezoneFromPhone to false as otherwise the phone will override any change that you make).

All Time Zones

This is a special setting which you can choose that says that the event occurs at the designated time in all locations, without adjustment. For example, you might use this for a reminder at 7am to take a pill - you want to do that at 7am no matter what timezone you are in. Note that most calendars have no support for this feature, and so these events may display at other, unexpected times in other calendars.

If you don't like to see events displaying at their adjusted times, you can simply enter those events in AllTimeZones and then they will always display at that time. Seeing items at their adjusted times is more useful when there is an event that you won't be present at (say you are putting in the date/time for a conference call and you are in the US and your UK office has the conference set for 2pm).

Missing timezones

When Pimlical is installed, a table is included of about three dozen timezones which comprise the most common timezones that travelers will encounter. However, there are some 430 timezones around the world, so if you travel to a country that has an unusual timezones, you may get an error similar to the one below:


The solution is to add the missing timezone. By way of example, suppose you travel to Costa Rica. Costa Rica is in US Central Standard time but without Daylight savings time. The only entry for Central Standard time in the basic timezone set includes the standard US rule for Daylight Savings (rule A).

There are two ways to address this issue:

#1 – go into menu | Preferences | RESTORE| RESET and check the box to install All TimeZones (WorldTimezones_all.txt) – that will install all 430+ timezones, including Costa Rica. Of course, you will then be wading through a HUGE list of timezones to find the one that you want, whenever you need to select a timezone).

#2 Or to keep things simpler, just edit the file: Worldtimezones.txt and look for these lines:

-07:00  America/Phoenix [Ariz]
-06:00A America/Chicago [CST]
-05:00A America/New_York [EST]

And insert a new line (shown below in bold) as shown below:

-07:00  America/Phoenix [Ariz]
-06:00  America/Costa_Rica [Cost]
-06:00A America/Chicago [CST]
-05:00A America/New_York [EST]

Without the letter A (Daylight Savings Rule A), the -06:00 entry for Costa Rica avoids changing anything for Daylight Savings. Before modifying the Worldtimezones.txt file, it's always a good idea to make a backup copy of it. Also, after making a change to that file, be sure to go into menu | Preferences | Date/Time Settings and then just exit out of that dialog (entering that section ensures that Pimlical re-reads the Worldtimezones.txt file, as the information there is normally cached into the SystemPreferences.dat file). Note that rules that do not have rule letter (no DST) must precede the entry that does have a DST specification (as shown above with -06:00 preceding -06:00A). Failure to observe that rule will cause DST rules to be mishandled.

Fixing timezone problems

If you end up with a large number of events in the wrong timezone, or want to change the timezone of many events, this can be accomplished easily in the Pimlical/Desktop application. Just use the Advanced Find function to select the events that you want to change, tap the Find button, then Change and by changing the timezone setting in the Change dialog, you can have that change applied to all the selected items.

Editing and Syntax of the Worldtimezones.txt File

Always use caution when editing the Worldtimezones.txt file as if you corrupt the file Pimlical will not display items at the correct time and may even refuse to launch properly. The file consists of two sections: Rule Letters for DST and the UTC offsets. You can also intersperse comment lines anywhere in the file provided that the line begins with a semicolon (;).

After you make a change to the Worldtimezones.txt file, it is recommended that (a) you save a copy under a DIFFERENT name, just in case your preferences are reset for some reason (in which case the built-in default worldltimezones.txt file would overwrite the one you had created), and (b) you need to go into menu | Preferences and tap the Date/Time button to force Pimlical to read in the new Worldtimezones.txt file.


A Rule Letter specification looks like this:

.B L103 L110 {time-switch} W Europe London, Paris

The Rule letter specification always starts with a period, immediately followed by a letter from A-Z. The DST rule that follows is assigned to that letter which can then be used in conjunction with a UTC offset. This is followed by a space and then a four-character string that defines when Daylight Savings takes effect, another space and then another four-character string that defines when Daylight Savings ends.  After another space is an optional specification to indicate when DST takes effect during the day. The default value is 2am (Standard for USA) if nothing is specified. Otherwise, there can be a {time-switch} designation such as an asterisk ('*') to indicate that DST takes effect at 1am (Standard for Europe), or there can be the letter 't' followed by a duration value (a value in the form 1h or 1h30m etc.) to indicate at what time after midnight DST is to take effect. For example, Eastern Europe changes DST at 3:00am instead of 1:00 am, so the rule is:

.M L103 L110 t3h Eastern Europe Greece, Finland

After the optional indication of when DST takes effect there must be at least one space and then a freeform comment indicating what this rule is for.

The four-character string that designates the start/end of Daylight savings has this format:

WDMM

where W = the week of the month - can be 1,2,3,4 or L (L or l = Last week of month)
D = Day of week - 1 = Sunday, 2 = Monday, 3 = Tuesday.... 7 = Saturday
MM is a two-digit number indicating the Month when the rule takes effect (use leading zero for Jan-Sep, so Jan = 01)

For example, in the above rule, L103 would be the Last Sunday in March, and L110 would be the last Sunday in October.

Timezone rules may change in some countries, so there may be multiple Rule Letter specifications. Also some countries may have rules that cannot be specified by the four-character specification - such as Israel. In those cases, you can follow the four-character string with a slash and then a Date specification indicating WHEN that particular rule takes effect. The Date is specified in a fixed YYYYMMDD format. For example, presently the Worldtimezones.txt file has this for Israel:

.E L603/20190101 L110/20190101 Israel
.E 4603/20170101 L110/20170101 Israel
.E L603/20130101 L110/20130101 Israel
.E L603/20120101 4109/20120101 Israel
.E 1604/20110101 1110/20110101 Israel
.E L603/20100101 2109/20100101 Israel

The reason for this more complicated rule set is that while Israel normally uses the last Friday in March to start DST, there's an exception in 2011 where it was the first Friday in April, and then again in 2017 when it will be the fourth (not the last) Friday in March. Because Pimlical rules assume DST starts on a particular week of the month (since the vast majority of the world does that), it requires a different specification for those years.

So starting in January 1, 2010, DST starts on the last Friday in March and ends on the second Sunday in September. Then in 2011, DST starts on the first Friday in April, and ends on the first Sunday in October. Additional rules may need to be added for future years beyond 2025 or so (just for Israel presuming it continues its current schedule).

There can be up to 26 rule letter specifications (one for each letter of the alphabet). It would be theoretically possible for a country to have a Daylight Savings rule that changed the time by something other than an hour, but at the present time, Pimlical does not cater to that possibility, and there are no countries which have or are contemplating such a change at this time.


A UTC Offset specification looks like this:

-05:00A America/New_York [EST]

The first character is either a minus sign (hyphen) if the Timezone is WEST of GMT, or a plus sign (+) if the timezone is EAST of GMT. Next is the timezone offset specified as HH:MM (two digit hour, colon and two-digit minutes offset from GMT/UTC).. This is optionally followed by a DST rule letter if this timezone has Daylight savings. If there is no Daylight savings, a space immediately follows the Timezone offset. Next is the Olson Database description of the timezone - this must match the standard usage in the Olson Database of timezones if you are syncing with any other calendar application such as Google Calendar. A Pimlical installation includes the complete list of all the Olson timezones in the world.  This is then optionally followed by a space and then a timezone abbreviation in square brackets. The timezone abbreviation does not need to follow any standardized definition, although it is obviously recommended to use a standard abbreviation when such exists. Note that Pimlical does not use DIFFERENT timezone abbreviations depending on Daylight Savings, so instead of using both EST and EDT for America/New_York, Pimlical always uses the abbreviation EST.

Timezone offsets from UTC are limited to 15 minute intervals (there is one country in the world that has a 15-minute offset from UTC, although most countries have offsets only in hours (and a few with 30 minutes).

For more information about how different parts of the world handle local timezones, there's a wealth of information available at www.timeanddate.com and this forms the basis for the values in Worldtimezones.txt.