The Pilot Record Database Format
This document is based on information derived from experiences with PalmOS 1.0.6, PalmOS 2.0, CoPilot, POSE, the Macintosh simulator and other utilities that read or create PDB files. Future versions of software may behave differently from what is describe below.
The PDB File Format
The PDB file format is also used to store databases from the PalmPilot on the Macintosh/PC. Pilot databases contain an attribute bit called the Backup Bit. Setting this bit indicates that no custom conduit will be backing up the database and that the database should be backed up during the HotSync process. If you create a database on the PalmPilot and set the Backup Bit, you will find a copy of the database in PDB format in the Backup directory on the computer with which the HotSync was performed.
There is a direct correlation between what is described here, and the PalmPilot record database format as described in Developing PalmOS 3.0 Applications. See Part III, Chapter 1 for further details. Specifically, pages 37 to 41 of that document (pages 34 to 38 of the version for PalmOS 2.0) will give you an overview of the PalmPilot database structure and help you understand the meaning of some of the record attributes and database header fields.
No mnemonics are provided for named constants in this document. If you are using "C" you may wish to review the header file DataMgr.h for public constants for bit flags. Constants are shown using the "C" language convention for hexadecimal numbers (e.g., 0x0A), followed by decimal values where they are not obvious.
Major Sections of the PDB
The Header supplies the basics of the file format: file name (on the PalmPilot), various time stamps, version numbers, file attributes, creator and type information, etc.
The Record List enumerates all the records of the file, their attributes and locations within the PDB file.
The Data portion of the PDB file contains the actual AppInfoArea, SortInfoArea and data records. The AppInfoArea and the SortInfoArea are application-specific areas that are optional elements of the PDB file. A PDB file may contain neither, one or both of these areas. The PDB file need not contain any records for HotSync to install the file, however the unsupported FTP code that comes the Metrowerks development tools does not support the installation of files with zero records. Current Palm-supported tools that read PDB files include the Palm Install Tool (to install via HotSync), the Macintosh-only Simulator (via interactive console commands), and the PalmOS Emulator (POSE).
*Please note that the PalmPilot's processor is a member of the Motorola 68000 family. The processor expect Numeric fields to be arranged with the Most Significant Byte coming first as you move through the file. If you are creating your file on a processor family that does not follow this byte ordering, notably Intel processors, pay attention or you will not have the expected results.
Note A: Because of differences between the behavior of software provided on the Macintosh and PC platforms, and bugs which are present, but different, between those platforms, the following advice is given. If you are going to have an AppInfoArea, the safest prospect, between the two platforms is to have an AppInfoArea of exactly 512 bytes. If you need a larger area, it is recommended by Palm's Developer Support that you dedicate a record or resource to that purpose. Macintosh users will experience problems if the AppInfoArea is longer than 512. For Windows-based users, the AppInfoArea will be padded with garbage to be exactly 512 bytes, if it is shorter than that. Windows users should not encounter problems when installing an AppInfoArea longer than 512 bytes.
Note B: Various statements have been made about the UniqueID Seed, but they do not appear to be possible to verify. As of PalmOS 2, UniqueIDs are not preserved through the process of backing up and re-installing a database to the Pilot. Changes may come about that will make this work in the expected way, but for now, if you want to count on a known value to uniquely identify a record, the developer should assign that number and store it within the data portion of the record. The UniqueID Seed should be set to zero.
Note C: Backup and downloading of the SortInfoArea is not supported by PalmOS. While it is possible to attach a piece of memory to the SortInfoArea pointer within the PalmPilot, the PDB loading and PDB backup process that occurs when the Backup Bit is set to do not support the SortInfoArea. The best solution is to dedicate a record or resource to the storage of whatever information you might want to keep in the SortInfoArea and avoid using the SortInfoArea.
The Record List
*See note after first table for Numeric field types.