File: README

PHP 5.3+ Based Palm data file conversion
designed and written by CPKS

1. Introduction:

The classes in this package are designed to read Palm Desktop address book,
date-book and memo files in the .ABA, .DBA and .MPA formats, which are related.

The principal difference between the three families of files is that whereas
address book and memo items were categorized, date-book (calendar) items were
not. In the case of the categorized data, early versions of the Palm Desktop
wrote each category to a separate category.ABA or category.MPA file; and
datebook items were written to Unfiled.DBA because "unfiled" was the default
category. Later versions of the software wrote all three types of item to
a single file: address.dat, datebook.dat and memopad.dat. The classes in
this package will work with all of these.

2. Acknowledgments:

The palm file formats were documented at

http://www.notsofaqs.com/palmrecs.php

at which site is a Python script by Aleks Totic which I used for inspiration,
particularly for the datebook iterator logic (which I have not tested).

Further, but limited, inspiration was provided by

http://hepunx.rl.ac.uk/~adye/software/palm/palm2ical/

3. Licensing:

On licensing, please see the LICENCE file issued with this package.

4. Files in this package:

4.1 binfile.php: a completely general binary file reading class

4.2 palmfile.php: basic Palm data file parser, extends binfile

4.3 datebookfile.php: classes to handle datebook files and records

4.4 cat_file.php: general palm file parser with added category handling

4.5 adrbookfile.php: classes to handle address book files and records

4.6 memofile.php: classes to handle memopad files and records

4.7 cvt_adrbook.php: simple program to dump an address book file in XML

4.8 cvt_datebook.php: program to dump datebook files to XML

4.9 cvt_memopad.php: program to dump memopad files to XML

4.10 icalevent.php: classes to enable dumping datebook records to iCalendar format

4.11 cvt_ical.php: program to dump datebook files to iCalendar format

4.12 LICENCE: licensing details

4.13 README: this file

4.14 phpdoc.dist.xml:
Assists the phpdoc documentation-generating package in producing documentation
for this package.

5. Documentation

I have elected to tailor this package to the PEAR phpdoc documentation system.
This produces good interactive HTML browsing capabilities together with an
SVG class diagram showing package and namespace relationships as well as
the object inheritance/implementation tree. See http://phpdoc.org/
for installation instructions.

6. Historical remarks on this package

This project was born when my last Windows machine died, and I found myself
hindered in getting the Windows system to boot on a new machine. Instead, I
resolved to move my old Palm data into a non-legacy format (XML).

My quest therefore was to find some free software that could parse the Palm
data files. In due course I found the sample parsing program by Aleks Totic.

Totic's Python program was ill-conceived in that it provided a function
to iterate over N data records, processing their contents directly. However,
a palm data file counted as a data record for this purpose, and all its
data records were read in recursively; so that instead of iterating over
the data, the effect of reading one record was to read the whole file.

To save memory, the present implementation uses two types of object: one to
represent the data file, which stores header information; and one to represent
the data record. The file object works as an Iterator that delivers one
data record object at a time. So, to process for example a datebook file
one event at a time, all one need do is the following:

<?php
$datebook = new palmdata\datebookFile('datebook.dat');
foreach ($datebook as $event) $event->convert_to_something();
?>

Several example programs are provided to illustrate the principles of use.

CPKS