[Installation] [Palm database] [Usage] [Importing] [Similar Programs] [History] [License] [Feedback]


palm2ical — Palm Databook/Calendar export to iCalendar

The palm2ical program reads a PalmOS Datebook or Calendar database file (DatebookDB.PDB or CalendarDB-PDat.PDB) and writes complete information from all entries as an iCalendar (.ics or RFC 2445/RFC 5545) file, suitable for import to Microsoft Outlook, Apple iCal, Google Calendar, Mozilla Sunbird, and many other calendar applications.

Entries can also be selected by date, category, or number. This allows, for example, the export of different categories into separate Google Calendars.

Download and Installation

palm2ical should work on most systems (Windows, Linux, MacOS, etc). For Windows users, I provide a stand-alone executable program that can be used on its own. For other operating systems, you will also need Perl and the CPAN packages listed below.

The downloads also include fixpdb, which displays or changes Palm Database file headers (see extraction method 2 for a possible use).

Windows stand-alone version

palm2ical-1.9-win.zip contains a Windows command-line executable program. You should extract it to a directory and run palm2ical.exe from a Command Prompt (use perl2ical -h, or see below, for help).

There will be a delay the first time you run the command, as the required Perl Archive files are extracted into a temporary directory, but you should not otherwise notice that Perl is being run behind the scenes.

Note that this program does not install anything else on your computer, so it can be removed by deleting the zip file, the files you extracted from the zip file, and (if you are being thorough) the par-USERNAME cache directory in your Temp directory.

Perl version

For the Perl version, palm2ical-1.9.zip, you will also need to install CPAN packages Palm::Datebook, Data::ICal, DateTime::Format::ICal, Data::ICal::TimeZone, and their dependencies. This can be done with the CPAN package. If the cpan command is set up, you can do
cpan Palm::Datebook Data::ICal DateTime::Format::ICal Data::ICal::TimeZone
from an administrator account.

Alternatively, you can invoke CPAN directly with

perl -MCPAN -e shell
and then from the prompt
cpan> install Palm::Datebook Data::ICal DateTime::Format::ICal Data::ICal::TimeZone
Or if you don't want to use CPAN at all, you can download the package tar files (see the link on the right-hand side of the page for each package), unpack, and follow the README instructions. However you will need the packages' dependencies as well, and there are a lot of them (eg. 26 packages in Perl 5.10.1, probably a few more in earlier versions).

Note that in order to support the newer Calendar-format file (CalendarDB-PDat.PDB), you need the latest version of Palm::Datebook, version 1.011 (21 Sep 2009) or later (note that old-style releases numbered 1.2.4 and 1.3.0 are older). This should be the default if you download now.

Assuming that is all set up correctly, ./perl2ical -h should display the help text.

Obtaining the Palm Databook/Calendar PDB file

The input file should be a PalmOS database (PDB) file, usually called DatebookDB.PDB or CalendarDB-PDat.PDB. This should not be confused with a Palm Desktop DateBook or Calendar Archive (eg. datebook.dat, datebook.bak, or Anything.DBA), which are in a different format that palm2ical cannot read (sorry: I couldn't find any description of the Calendar Archive format, and the older Datebook Archive, doesn't record the location field).

Recent versions of PalmOS include both DatebookDB.PDB and CalendarDB-PDat.PDB files. You can use either, but the DatebookDB.PDB will not include the event location field, so you probably want to get CalendarDB-PDat.PDB if it's there.

The PalmOS Datebook/Calendar database file is not normally backed up with HotSync. If you use a transfer tool like BackupBuddy on Windows or MacOS or pilot-xfer (part of pilot-link, used by KPilot etc) on Unix/Linux, then you probably already have the file on your PC in your backup directory. Otherwise you have to extract it from your Palm (or a Simulator) by hand.

Extracting the PDB file from your Palm

First make sure your Palm's Calendar is up-to-date by performing a HotSync with your desktop (see method 3, below, if you don't any more have access to your Palm). You might want to make an extra backup of your Palm Desktop Calendar file, just in case something goes wrong: use FileExport, select Export type = "Calendar Archive (*.dba)", Range = All, and enter a file name.

1. Easy method — using an SD Card or LifeDrive

The PDB file can be extracting using FileZ. If you don't already have it, get FileZ, free from Nosleep Software, and install on your Palm. Open FileZ and select "View and Edit Files", open "Internal" (tap on the triangle) and scroll down to DateBookDB or, preferably, CalendarDB-PDat and select it. If you have a device that can be mounted on your PC (SD Card or LifeDrive etc), then you can copy this file to the device using the Copy option in the Item menu. Then mount the device on your PC and copy the file from there.

2. Harder method — using HotSync

Alternatively, when you select DateBookDB or CalendarDB-PDat in FileZ (see above), tap the "Details" button. Then change the Creator field to another 4-character name (make a note of its original value: it should be "date" or "PDat"), eg. "ABCD". Then on the "Attrs" tab, select the "Backup" option. Then select "Save" and perform a HotSync (NB. do not try to run the Calendar application at this point — it will crash). The altered attributes prevents HotSync excluding the PDB from being backed up by HotSync. After this, the file will be in the "Backup" subdirectory of your PC's user folder. You should then restore its Creator setting on the Palm using FileZ, or else delete the file, run Calendar to create a new empty one, and restore your data from the Palm Desktop with another HotSync.

You should also restore the Creator field of the PC copy. This can be done with a hex editor or with my fixpdb command:

fixpdb -c PDat CalendarDB-PDat.PDB

3. Extracting the PDB file without your Palm

If you don't have your Palm device any more, but still have the Palm Desktop Archive, you can use the PalmOS Simulator to make a Palm database file. The Simulator can be downloaded from the Palm Developer Network (you will need to create an account to download). Select your Palm device (or similar model) and download the "release" version of the simulator (actually it doesn't really matter which model you use, as long as you don't use a version with the old Datebook application if you have data from a model with the new Calendar application, so any of these Palm Centro Simulators should be fine). Documentation for the generic Simulator is available from the ACCESS Developer Network in the Documentation for Garnet OS Development Tools (the generic ACCESS Simulator itself has the old Datebook application).

Follow the instructions for performing a HotSync with the Simulator to get your data into the Calendar application. You can quickly install FileZ by dragging Filez.prc into the Simulator window. Then follow the instructions above for extracting the PDB file.

palm2ical program usage

Syntax

palm2ical [OPTIONS] [FILENAME]

When run with no arguments, tries to read CalendarDB-PDat.PDB or DatebookDB.PDB from the current directory and write an iCalendar file with extension .ics (this will only work if the local time zone can be automatically determined). If the .PDB file is not found, the help is printed instead.

If a FILENAME is specified, then that is read as a PDB file, and an iCalendar file is written to standard output (or the file specified with -o). With the -p option, the Calendar information is summarised in a more human-readable and compact form than the iCalendar format.

When run with the -T option, lists the supported time zones.

Options

-h -?    display this help and exit
-v       verbose running (use -V for additional debugging)
-o FILE  write output to FILE instead of standard output.
-p       print events, one per line (with -p, options -t -l -k -s are ignored)
-n       don't include informational data, X-PALM-* and DTSTAMP fields.
         With -p, don't print unknown-format data.
-L       don't include location    from the Calendar file (not in Datebook)
-Z       include time zone entries from the Calendar file (not in Datebook)
-t TZ    specify the local time zone to write to the iCalendar file.
         Use the "zoneinfo" name, eg. "Europe/London" for the UK.
         Use palm2ical -T to list the supported time zones. If not specified
         (and not -z or -l), then the local time zone is used. Note that
         palm2ical may not be able to determine the time zone automatically,
         in which case you should specify it with the -t option.
-z       convert all times from the local time zone to UTC for the iCalendar
         file. With -p, excludes time zone entries.
-l       do not specify a time zone. The iCalendar specification says that
         this means that times will be interpreted as floating times (ie. not
         bound to any time zone).
-k       keep spurious events. Otherwise we remove repeating events with no
         undeleted occurrences and instances at start or end of repeat period.
-s       Replace new-lines with spaces in summary and location fields
         (Outlook concatenates multiple lines into one).
-c NAME  select only the specified category NAME
-d DATE  select only the specified DATE or or date range
         (DATE1-DATE2 or DATE1- or -DATE2).
         DATE is of the form 2009/07/30:21:07 with optional time.
         You can also specify 2009/07/30:21:07-23:00.
-r NUM   only output specified record numbers: comma separated and can include
         ranges (eg. 10-20,30-). The first record is number 0.
-i ID    only output the specified record ids (comma separated).

Examples

palm2ical
palm2ical -o CalendarDB-PDat.ics CalendarDB-PDat.PDB
palm2ical CalendarDB-PDat.PDB > CalendarDB-PDat.ics
These three examples all do the same thing — assuming the file CalendarDB-PDat.PDB exists and the time zone can be determined.
palm2ical -c Personal -t America/Los_Angeles CalendarDB-PDat.PDB > personal.ics
This writes all Personal entries to personal.ics. The Pacific time zone is specified.

Time Zone

The time zone is required because the PalmOS Datebook/Calendar application does not always record time zone information. By default, all events are taken to be in your local time zone and not changed as you move between time zones. This is similar to iCalendar's concept of floating times, but applications that use the iCalendar file may not handle this correctly (and Outlook 2007 doesn't support this). Use palm2ical -l to output floating times.

The default is to include the current local time zone identifier (where this can be determined, or else as specified with the palm2ical -t option) in the iCalendar file. This allows an application to perform time zone conversions as it sees fit. Alternatively, with the palm2ical -z option, times are converted to UTC (GMT) from the current local time. I don't know if that's useful.

You can also use palm2ical -T to list all supported time zones and show the default time zone (if it can be determined) at the end of the list.

In fact, the PalmOS Calendar application can record time zone information for events if explicitly set when the event was created (or the "New events use time zones" preference is set), although the Palm Desktop does not display this information. You can output this information to the iCalendar file with the palm2ical -Z option. This will only affect events with explicit time zone settings. The parameters for any used time zones (offset from UTC and DST changes) will be specified in the iCalendar file, since Palm defines its own set of time zones — and indeed the user can edit or add to them. This option is not the default, because many applications don't do anything useful with the time zone information, so it's usually simplest to import everything with the local time zone.

Output

palm2ical does not export birthdays from the Contacts list (even though they are displayed in the PalmOS and Palm Desktop Calendar). All other Palm Datebook or Calendar information should be preserved in the output iCalendar file. Unlike some other converters, this includes repeating events of all types and exceptions to repeating events (cancelled or modified events that are part of a series).

Each event's iCalendar UID (unique identifier) is made up of the database creation time and record id. Rerunning palm2ical on the same database, even after a HotSync update, will give the same UIDs for the same events. Some applications (eg. Google Calendar) reading an updated iCalendar file can recognise this and not duplicate events that had been imported on a previous occasion.

Unless the palm2ical -n option is specified, a few palm2ical properties are included in the iCalendar file for informational purposes: X-PALM-DBNAME, X-PALM-CREATED, X-PALM-MODIFIED, X-PALM-BACKUP, and X-PALM-MODNUM. These record the Palm Database name ("DatebookDB" or "CalendarDB-PDat"), creation date, last modification date, date of last backup, and modification number respectively. Also, each event includes an X-PALM-RECORD property to save the record number. These should be ignored when the iCalendar file is read in by another program.

If any textual data includes non-ASCII (eg. accented) characters, then the X-PALM--UTF8 property is included. The value is just a comment with an example (the first) such character. This helps parsers quickly identify the file as UTF-8, since this property is near the beginning. In particular, Google Calendar does not correctly import UTF-8 characters if there isn't one in the first 8000 bytes of the iCalendar file. The UTF-8 character in the X-PALM--UTF8 property ensures that Google Calendar handles UTF-8 characters later on.

Use of iCalendar Files

I have tested exports to Outlook, Google Calendar, and Mozilla Sunbird, and checked that events are transferred correctly. There are a few minor issues with how these programs interpret the iCalendar file.

Outlook

When importing, Outlook concatenates multi-line summaries to make a single-line "subject" (also for location, but Palm only has single-line locations). Use -s to make new-lines into spaces, which is a bit neater.

When importing into the default Calendar, Outlook forgets all alarms for past events, once they have been dismissed. It forgets all alarms, past and future, if creating a new calendar with the import.

Outlook complains about recurring events with no occurrences remaining undeleted. palm2ical removes these, unless you specify the -k option.

Google Calendar

Google Calendar does not save the category information. Instead, you can export each category into a separate file (using the -c option) and import them into separate calendars.

When importing, Google Calendar ignores tabs in the event text.

Google Calendar sometimes does not seem to correctly handle recurring events where the first occurrence has been deleted. Unless you specify the -k option, palm2ical gets round this by adjusting the start and end dates of the recurring event to be the first and last extant occurrences, respectively.

Mozilla Sunbird

This seemed to interpret the iCalendar file correctly, though reading in (and subsequently working with) a large number of events was very slow.

Similar Programs

I made extensive use of Datebook on my Palm V and Calendar on my Treo 650 and was keen to retain the history of old events (it's the closest thing I have to a diary) as well as transferring future events to my new Android phone (HTC Hero). I have more than 4500 events (not counting repeats) going back more than ten years, so a reliable transfer was crucial for me.

There are a number of programs available to extract Palm Datebook or Calendar data, some writing iCalendar files directly, some going via other programs or formats (sometimes in several steps!). I could not find one that looked like it would reliably convert all my Calendar data (including Categories, Location, and all types of repeating event). My palm2ical was written to transfer everything.

Anyway, for reference, here is a list of the programs I found. I haven't tried many of them, so I'm mostly just going by hearsay or what I could glean from their web sites.

doctor.whom's palm2ical
PHP program that reads Palm Desktop datebook.dat and outputs an iCalendar file. Does not handle all types of repeating events.
Patrick Mueller's palm2ical
Java program that converts Palm databases as stored on Windows into ical/ics files per RFC 2445, and specifically for the Apple iCal product. Does not work for new-format Palm Desktop files, which implies that it does not make the location field available.
KPilot
KPilot is a Linux replacement for the Palm Desktop software. It uses pilot-link to sync with the Palm. As far as I could tell from the source code, it does not handle all forms of repeating events.
Evolution
Evolution provides mail, addressbook, and calendaring functionality for the Linux GNOME desktop. It also uses pilot-link.
Palm2CSV
Converts your Palm Desktop Calendar to CSV Format. Easy to use (just upload to the web page), but doesn't handle repeating events or the location field.
dtbk2csv
Datebook to CSV conversion, and then convert CSV to iCalendar as described here. All repeating events are converted to (multiple?) one-off events.
Dba2Csv
Another Datebook to CSV converter, but you have to pay for this one. All repeating events are converted to multiple one-off events.
PocketCopy
Copies Palm Desktop AddressBook/Contacts, DateBook/Calendar, ToDo/Tasks, and Memos into Microsoft Outlook Contacts, Calendar, Tasks, and Notes. Outlook can than export the Calendar data as an iCalendar file. In principle, this transfers everything, except that Outlook cancels all old alarms, so that information is lost if exported elsewhere. Reportedly PocketCopy did not handle repeating events well: many deleted occurrences reappeared in Outlook, modified occurrences gave duplicates, and a few occurrences were lost. Maybe they've now fixed this problem, but since it's commercial software, I can't check without paying.
CompanionLink for Google
Syncs your desktop software with Google and your phone. Google Calendar can then export an iCalendar file, as described here. This is a full two-way sync, but is expensive ($100). Since it uses Google Calendar, Palm categories are probably not preserved.

History

14th February 2012: version 1.9 (Perl, Windows):

10th March 2010: version 1.8 (Perl, Windows):

1st February 2010: version 1.7 (Perl, Windows):

2nd January 2010: version 1.6 (Perl, Windows):

11th December 2009: version 1.5 (Perl, Windows):

15th November 2009: version 1.4 (Perl, Windows):

9th November 2009: version 1.3 (Perl, Windows):

20th September 2009: version 1.2 (Perl, Windows):

License

palm2ical is copyright © 2009-2010, Tim Adye. It is free software; you may redistribute it under the terms of the Artistic License.

Feedback

If you have any questions, comments, or just want to let me know that you found this useful (I would like to hear!), please let me know either by e-mail or with a comment on this TreoCentral discussion thread.
Valid HTML 4.01! http://hepunx.rl.ac.uk/~adye/software/palm/palm2ical/ last modified 14th February 2012 by
Tim Adye, <T.J.Adye@rl.ac.uk>