A converter for Palm Pilot PDB files

This program converts PDB files to a human-readable, human-editable, ASCII form, and back again. In fact, the ASCII form is designed to be more than just editable by humans; it's also easily editable by programs, provided the programs are written in a little language called Lua. The converter translates between PDB files and Lua data values.

The converter is generic in the sense that it can translate any PDB file to ASCII and back again. However, to make the most sensible results, you need a converter module that knows how to interpret the particular binary data inside the PDB file. The converter module supplies interpretations for the ``application info'' part of the PDB file, as well as an interpretation for the data in each ``record.'' The converter was written based on PDB documentation found at Road Coders.

The converter has two operations: ``unpacking'' converts a binary PDB file into an ASCII Lua value. ``packing'' takes the Lua value called Database and converts it into a binary PDB file. Internally, these operations are usually split into two parts (although they don't have to be). The converter will normally ``read'' binary data into a C struct before unpacking it, and it will normally pack binary data into a C struct before ``writing'' it out.

The converter ships with these conversion modules:

jfile.nwThe JFile database program.
mobile.nwThe MobileDB database program.
shop.nwThe HandyShop freeware shopping-list program, which is available from Pilot Gear HQ.
todo.nwThe Palm ToDo database (converts one direction only).
expense.nwThe Palm Expense database (converts one direction only).

The converter chooses the proper module based on the ``type'' and ``creator ID'' of the database. If it doesn't recognize the type and creator ID, it falls back on a generic conversion module that works for any PDB file, but the results aren't always terribly enlightening.

The remaining modules are used either for the common parts of the PDB format or as auxiliary stuff to help build new converters.

pushchar.nwThis is a little hack that makes it easy to null-terminate a string temporarily, so you can use printf with it. This hack is helpful because not all PDB formats use null termination.
pdbio.nwThis module defines a bunch of functions and macros that help you do I/O with the correct byte order, regardless of the byte order of the machine on which the conversion tool runs. This module defines the Text abstraction, which is sort of like a file, except it represents a string. These strings can contains zeroes, however, and they can be read incrementally.
pdblua.nwThis module contains a slew of ``helper'' functions and macros that make it easier to convert binary data to Lua values and back again.
pdbrep.nwThis module defines the representation of standard information found in most or all PDB files. The data structures defined in the interface are sort of interesting if you're curious about the Pilot. If you make new converter modules, you might be interested in PDBCategoryAppInfo and in the packing, unpacking, reading, and writing functions for category info. Otherwise, you won't need to explore this module---the implementation is deadly dull.
pdbconv.nwThis module explains what a converter module has to provide, and it provides some generic support functions.
pdb.nwThis rather mixed module contains both the main program, with its selection of function, and also the packing and unpacking (but not the reading and writing) for the standard information defined in pdbrep.nw.

Adding a new converter

Define a converter data structure as defined in pdbconv.nw. This means packing and unpacking functions and documentation for application info, sort info (if any), and records. A good strategy is to start with unpacking, and to use generic functions for things you haven't written yet. If all goes well, you should be able to convert binary to ASCII back to binary and get the exact same information:

: nr@flatcoat 371 ; pdb unpack Siskel.pdb | pdb pack > new.pdb        
: nr@flatcoat 372 ; cmp Siskel.pdb new.pdb
: nr@flatcoat 373 ; 

Converting one database to another

m2j and j2m are sample converters written as shell/Lua scripts. They convert MobileDB databases to JFile databases and back again.

Example creation of a database from ASCII

See the code I used to build the Locus Poll database.

Download the source code

This zipfile contains Noweb source, C source, and a couple of examples. To compile the source, set LUA to the directory where you installed Lua, and try

  cc -I$LUA/include -L$LUA/lib *.c -llua -llualib

Back to Norman Ramsey's Pilot page or home page.