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

palm2ical — Palm Datebook/Calendar export to iCalendar

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

• Download palm2ical-1.9.zip — for any OS, Perl source code requires Perl and extra packages
• Download palm2ical-1.9-win.zip — for Windows only, includes all required software

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

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

cpan Palm::Datebook Data::ICal DateTime::Format::ICal Data::ICal::TimeZone

Alternatively, you can invoke CPAN directly with

perl -MCPAN -e shell

cpan> install Palm::Datebook Data::ICal DateTime::Format::ICal Data::ICal::TimeZone

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 Datebook/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 File → Export, 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

palm2ical -c Personal -t America/Los_Angeles CalendarDB-PDat.PDB > personal.ics

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

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

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

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

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):

• Fix UTF-8 encoding so that multi-byte characters are not broken over two lines. This generated invalid UTF-8, rendering the whole file unreadable by some programs (eg. Sunbird). Bug reported by Miha Ambrož and Alan Cibils.

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

• Update Windows version to include Palm::Datebook 1.012.
• Minor help fix

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

• Fix fixpdb Perl to use Unix, rather than Windows, line endings.
• License under the Artistic License. (Both changes suggested by Giovanni Bechis.)

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

• Include time zone entries from the Calendar file with palm2ical -Z.
• Don't give errors on empty deleted records. Don't include deleted records in iCalendar output. (This was only a problem when converting a database that had not been HotSynced.)
• palm2ical -p shows control characters etc as \n etc.

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

• Reorder INTERVAL and FREQ in iCalendar RRULE properties. This works round a bug in Apple iCal (in Mac OS X 10.6.2, iCal 4.0.1 at least), which requires the FREQ parameter to come first. (Problem reported by Brian Stradale.)

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

• Improve error checking on dates and times.
• Print record number and id for all errors.
• Allow Unix time in database creation, modification, or backup time. Palm::PDB assumes these times are offset from 1/1/1904. Jesup sent me an example from a Treo 755p which seems to use the Unix epoch of 1/1/1970.

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

• Windows executable includes all timezones. Previously only worked in Europe/London timezone. (Problem reported by jesup.)
• Include official p5-Palm-1.011 release in Windows executable.

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

• First public release.

License

Feedback