Convert To/From (Palm)Pilot Databases

Description

This collection of programs provides:

a possibly more convenient command-line interface to the pilot-xfer utility for driving the Pilot; these might be useful to any user of pilot-xfer
programs to convert between private database formats and the formats used by pilot-xfer; these may be useful if the user is prepared to accept the author's private formats, is prepared to adapt the code for other private formats, or can use the code as examples of how to use the pilot-xfer libraries

Usage

Here are some examples of how to use the tools. It is assumed that files are stored in the directories given by the environment variables described under Installation.

pilist: list the files currently held on the Pilot
piload: restore all database files to the Pilot
piload -a: restore all files to the Pilot
piload MyProg.prc MyProg.pdb: load the code and database for MyProg to the Pilot
pisave: backup all database files from the Pilot
pisave -a: backup all files from the Pilot
pisave MyProg.prc MyProg.pdb: save the code and database for MyProg from the Pilot
from_pi: upload and convert standard Pilot databases (address, date, expense, memo, todo)
from_pi -t -e: upload and convert Pilot todo and expense databases
to_pi: convert and download standard Pilot databases (address, date, expense, memo, todo)
to_pi -a -m: convert and download Pilot address and memo databases

The relationship between the utilities is as follows:

Installation of `piconv`

It is essential to get hold of the pilot-link package. The tools in the piconv were built against pilot-link version 0.9.3. piconv has been built and tested on OPENSTEP 4.2 running on a Pentium PC. The piconv utilities should be reasonably portable to other Unix environments such as Linux and Solaris.

Run gunzip to decompress the distribution, then tar xvf to extract the archive. The files will end up in directory piconv-1.0. Edit the Makefile for a suitable installation directory. Type make to compile the C programs. Type make install to install the executables in the chosen directory.

The executables (pilist, piload, pisave, from_pi, to_pi, get_pi, put_pi) need to be installed in a directory on the search path for executables. Depending on the installation directory for piconv, the PATH environment variable may need to be changed.

The following additional environment variables should be set up:

CLAIMDIR: used by from_pi and to_pi to define where private expenses files are kept
DATADIR: used by from_pi and to_pi to define where private data files (address book, date book, todo list) are kept
MEMODIR: used by from_pi and to_pi to define where private memo files are kept
PILOTDIR: used by all the utilities to define where pilot-xfer databases are kept
PILOTPORT: used by pilot-xfer to define the serial device
PILOTRATE: used by pilot-xfer to define the serial device bit rate

Licence

piconv is free software, distributed under the GNU Public License Version 2. You may re-distribute this software provided you preserve this README file.

Acknowledgements

piconv builds on the robust and comprehensive pilot-link utilities by Kenneth Albanowski, whom the author thanks for prompt and helpful advice.

History

Version 1.0: First public version, Ken Turner <kjt@cs.stir.ac.uk>, 5th November 1997

Version 1.1: Compiled quad-fat for NEXTSTEP 3.3, Ken Turner <kjt@cs.stir.ac.uk>, 22nd December 1997

Version 1.2: Bug fix, Ken Turner <kjt@cs.stir.ac.uk>, 20th April 1998

Corrected bug in put_pi that could cause failure due to unitialised DBInfo structure (reported by Mike Ford)

Version 1.3: Bug fix, Ken Turner <kjt@cs.stir.ac.uk>, 3rd June 1998

Allowed get_pi to handle empty expense amount

Version 1.4: Bug fix, Ken Turner <kjt@cs.stir.ac.uk>, 20th July 1998

Handle year 2000 correctly on output

Version 1.5: Bug fix, Ken Turner <kjt@cs.stir.ac.uk>, 17th September 1999

Build against pilot-link version 0.9.3
Retrieve Datebook alarm times correctly even though pilot-link does not set GMT offset
Handle year 2000 correctly in getting todos and expenses

Version 1.6: Minor changes, Ken Turner <kjt@cs.stir.ac.uk>, 2nd May 2001

Mobile telephone numbers supported
Telex number support ("Other Number") removed

Interface to `pilot-link`

pilist

This program uses pilot-xfer to list the files held on the Pilot. Note that file suffixes such as pdb and prc are not printed. The command-line options are:

-h: print usage help

piload

This program uses pilot-xfer to load the Pilot from files in the directory given by environment variable PILOTDIR. The command-line options are:

-a: load all files (i.e. restore)
-d: load database (PDB) files only (default option)
-h: print usage help
-p: load program (PRC) files only
file ...: load named files only (use quotes for names with spaces, omit suffix such as pdb or prc)

Note that some system files cannot be loaded back into the Pilot. Filenames can be shortened as long as they do not become ambiguous (e.g AddressDB.pdb might be given on the command-line as Address).

pisave

This program uses pilot-xfer tosave files from the Pilot in the directory given by environment variable PILOTDIR. The command-line options are:

-a: save all files (i.e. backup)
-d: save database (PDB) files only (default option)
-h: print usage help
-p: save program (PRC) files only
file ...: save named files only (use quotes for names with spaces, omit suffix such as pdb or prc)

Conversion to/from `pilot-link`

Private Formats

The formats are peculiar to the author, though it should not be too difficult to use some other private format. The author can provide other utilities that work with his formats if anyone is interested. Code for the private formats has been confined to specific functions to ease changes. See get_pi and put_pi for an indication of what to change. The code is extensively commented, so hopefully any changes will not be too difficult.

Address Book Format

The pilot-xfer address book is held in AddressDB.pdb. The private format address books are held in <category>.addr files. Fields are separated by tabs, and sub-fields by "~". Within a sub-field, "~" denotes a newline (except in a web address) and "^" denotes a space (in first/last name). A double quote must appear as \" in an entry. The generic format is:

  T<title> p<first> s<last> t<work>~<fax>~<home> x<telex>
    a<work addr> A<home addr> e<email1>~<email2>~<web> <l>links

Example (fictitious):

  TDr.  pIan    sBrown  t413-420~923-602~413-551        x823445 JOHNS US
    aComputing Department~Johnsons~Smithville~IL 98021~USA
      A6 Green Street~Pleasance~IL 90822~USA
	ei.brown@johnsons.net~IB~http://www.johnsons.net/
	  lSquash~Sailing

It is assumed that the Pilot address fields have been customised as follows:

Other: telex number
Email 2: alternative email address (Custom 1)
Web: web address (Custom 2)
Links: project links (Custom 3)
Home Addr: home address (Custom 4)

Apart from this customisation it is assumed that phone number and record categories have not been altered by the Pilot user.

When converting from pilot-xfer to private format, a number of fields such as Company, Town, ... are just incorporated into the work address. Other fields such as Note, Mobile, Pager, ... are appended to the links. In the reverse direction, none of these fields is generated.

Date Book Format

The pilot-xfer date book is held in DatebookDB.pdb. The private format date book is held in calendar - a specialisation of the Unix format. Fields are separated by tabs; sub-field separators vary.

  <month> <day> <year> <start>-<finish> <description> <alarm>

The finish time is omitted for an event without a specified end. The start and finish times are omitted for an untimed event. The alarm time is optional. The description begins with "@" for private appointments.

Example:

  Jul 16 1997                   @Celebrate Anniversary
  Jul 16 1997	08.00           Breakfast Meeting       07.30
  Jul 16 1997	15.00-16.30     *Project Review, Board Room

When converting from pilot-xfer to private format, repeated appointments are expanded to literal repetitions. In the reverse direction, repetition is not used. From private format to pilot-xfer, alarm times more than 99 minutes in advance are converted to the nearest number of whole hours.

Expenses Format

The pilot-xfer expenses are held in ExpenseDB.pdb. The private format expenses are held in files called <category>.exp. Main fields are separated by tabs:

  <day>-<month>-<year> <expense type>
    (<payment type> <vendor> <city> <attendees>)
      <currency><amount> [note]

Example:

  31-Aug-97     Dinner (Visa)   US$     254
  31-Aug-97     Hotel   US$	893.63  [1]
  01-Sep-97     Breakfast       US$     952
  01-Sep-97     Other (Commission)      CN$     2.50    [5]

Memo Format

The pilot-xfer memos are held in MemoDB.pdb. The private format memos are held in files called <title>.memo[s]. When a memo is created, the title is taken from the first line of the memo (file name limited to 32 characters, spaces converted to underscores). If a memo has a blank first line, the title is set to "memo1", etc. The suffix may be extended with "s(ecret)".The contents of a memo (including the first line as title) are copied literally. The default is a business, non-secret memo.

Todo List Format

The pilot-xfer todo list is held in ToDoDB.pdb. The private format todo list is held in todo. The header is terminated by a blank line. Fields are separate by tabs; sub-field separators vary.

    <status> <priority> <due> <description>

The status is "*" (completed) and B(usiness)/P(ersonal)/U(nfiled). The default is uncompleted business. The priority is in the range 1 to 5. The due date is in the form MMM DD YYYY (default is a tab if no due date). A tilde is used in the description in lieu of a newline.

Example:

  State	Pri     Due             Description

  U	1       Jul 17 1997     Write to John Smith~(order form)
  *S	2       Jul 24 1997     Send off book review
  P	5                       Finish program write-up

When converting from pilot-xfer to private format, a note is appended to the description. In the reverse direction, a note is not generated.

from_pi

This program uses get_pi to load Pilot files into the directory given by environment variable PILOTDIR. Expense files are held in the directory given by environment variable CLAIMDIR, data files (address, date, todo) in DATADIR, and memo files in MEMODIR. The command-line options are:

-a: upload address book
-d: upload date book
-e: upload expenses
-f: upload full set of files (default)
-h: print usage help
-m: upload memos
-t: upload todo lists

to_pi

This program uses put_pi to load the Pilot from the directory given by environment variable PILOTDIR. Expense files are held in the directory given by environment variable CLAIMDIR, data files (address, date, todo) in DATADIR, and memo files in MEMODIR. The command-line options are:

-a: download address book
-d: download date book
-e: download expenses (not currently implemented)
-f: download full set of files (default)
-h: print usage help
-m: download memos
-t: download todo lists

get_pi

This program converts the pilot-xfer database files in the current directory to a private format in the same directory. If the output files already exist, they will be overwritten. The command-line options are:

-a: AddressDB.pdb is converted to <category>.addr files
-d: DatebookDB.pdb is converted to Datebook
-e: ExpenseDB.pdb is converted to <category>.exp files
-h: print usage help
-m: MemoDB.pdb is converted to <title>.memo[s] files
-t: ToDoDB.pdb is converted to ToDo

To handle different private formats from the ones generated by this program, customise the following functions:

Address: get_addr_ent
Datebook: get_appt_ent
Expense: get_exp_ent
Memo: get_memo_ent
ToDo: get_todo_ent

put_pi

This program converts the private format files in the current directory to pilot-xfer format in the same directory. If the output files already exist, they will be overwritten.The command-line options are:

-a: <category>.addr files are combined/converted to AddressDB.pdb
-d: Datebook is converted to DatebookDB.pdb
-e: <category>.exp files are combined/converted to ExpenseDB.pdb (not yet implemented)
-h: print usage help
-m: <title>.memo[s] files are combined/converted to MemoDB.pdb
-t: ToDoDB is converted to ToDo.pdb

To handle different private formats from the ones generated by this program, customise the following functions:

Address: put_addr_ent
Datebook: put_appt_ent
Expense: put_exp_ent
Memo: put_memo_ent
ToDo: put_todo_ent

Installation of `pilot-link` on OPENSTEP

piconv relies on pilot-link, which fortunately is really quite portable. However, OPENSTEP users might wish to note the following hints about building pilot-link version 0.9.3 on OPENSTEP 4.2:

Run configure; this should go smoothly. (Make sure you have first installed Rex Dieter's libgxx distribution from the archives if you wish to compile the C++ utilities.)
Adjust the directory in the top-level Makefile if desired. (I set prefix to /usr/local/pilot so as to keep all the files together. This is a matter of taste.)
Add lines in include/pi-socket.h to say:
```
#ifdef __NeXT__
#define ENOSYS EOPNOTSUPP
#endif
```
to allow the return of a valid (but not very important) error number in some functions.

Add lines in include/pi-source.h to say:

#ifdef __NeXT__
struct utimbuf {
        time_t actime;          /* access time */
        time_t modtime;         /* modification time */
};
#endif

This is a slightly untidy work-around that gives an apparently harmless warning when compiling pilot-xfer.c.

For the convenience of OPENSTEP users who do not have the developer version, I have pre-compiled Version 0.9.3 of pilot-link with the above changes. Precompiled source for Intel only is available for file transfer. I built with /usr/local/pilot as the installation directory, though you can probably change this to your preference. Note that I have tested only on OPENSTEP 4.2/Intel. And of course, all the hard work was done by pilot-link author Kenneth Albanowski.

On my OPENSTEP/Intel system I have the following environment variables set up:

PILOTPORT: /dev/cub (i.e. the second serial port)
PILOTRATE: 57600 (i.e. 57,600 bits/sec)

Convert To/From (Palm)Pilot Databases

Description

Usage

Installation of piconv

Licence

Acknowledgements

History

Interface to pilot-link

pilist

piload

pisave

Conversion to/from pilot-link

Private Formats

Address Book Format

Date Book Format

Expenses Format

Memo Format

Todo List Format

from_pi

to_pi

get_pi

put_pi

Installation of pilot-link on OPENSTEP

Installation of `piconv`

Interface to `pilot-link`

Conversion to/from `pilot-link`

Installation of `pilot-link` on OPENSTEP