Convert To/From Palm Databases

Mobile Logo

See the download page to obtain this program

Description

This collection of programs provides:

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 Palm
piload/dt>
restore all database files to the Palm
piload -a
restore all files to the Palm
piload MyProg.prc MyProg.pdb
load the code and database for MyProg to the Palm/dd>
pisave
backup all database files from the Palm
pisave -a
backup all files from the Palm
pisave MyProg.prc MyProg.pdb
save the code and database for MyProg from the Palm
from_pi
upload and convert standard Palm databases (address, date, expense, memo, todo)
from_pi -t -e
upload and convert Palm todo and expense databases
to_pi
convert and download standard Palm databases (address, date, expense, memo, todo)
to_pi -a -m
convert and download Palm address and memo databases

The relationship between the utilities is as follows:

PiConv Relationships

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, 5th November 1997

Version 1.1: Compiled quad-fat for NEXTSTEP 3.3, Ken Turner, 22nd December 1997

Version 1.2: Bug fix, Ken Turner, 20th April 1998

Version 1.3: Bug fix, Ken Turner, 3rd June 1998

Version 1.4: Bug fix, Ken Turner, 20th July 1998

Version 1.5: Bug fix, Ken Turner, 17th September 1999

Version 1.6: Minor changes, Ken Turner, 2nd May 2001


Interface to pilot-link

pilist

This program uses pilot-xfer to list the files held on the Palm. 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 Palm 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 Palm. 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 Palm 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 Palm 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 Palm 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 Palm 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 Palm 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:

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)

Up Arrow Up one level to Mobile Utilities

Web Ken Turner Home   Email    Search Search Web Pages

Last Update: 3rd August 2011
URL: http://www.cs.stir.ac.uk/~kjt/software/mobile/piconv.html