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 Basics
The Pilot Database (PDB) File format can be used to transfer files to the PalmPilot. It is possible to install PDB files to create either resource or record databases through this mechanism. This document only reviews the record database capabilities of 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 File
The PDB file (from this point forward that term refers to the record database format exclusively) is made up of the following sections: Header, Record List and Data. They are each described in the following paragraphs.

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).

The Header
The header is made up of the following fields.

Field	Bytes	Type	Notes
Name	32	Null-terminated string	This is the name of the database on the PalmPilot device. It need not match the name of the PDB file in the environment in which it is created.
File Attributes	2	Numeric*	0x0002 Read-Only 0x0004 Dirty AppInfoArea 0x0008 Backup this database (i.e. no conduit exists) 0x0010 (16 decimal) Okay to install newer over existing copy, if present on PalmPilot 0x0020 (32 decimal) Force the PalmPilot to reset after this database is installed 0x0040 (64 decimal) Don't allow copy of file to be beamed to other Pilot.
Version	2	Numeric*	Defined by the application.
Creation Date	4	Numeric*	Expressed as the number of seconds since January 1, 1904. The database will not install if this value is zero. (PalmOS 1.0.6)
Modification Date	4	Numeric*	Expressed as the number of seconds since January 1, 1904. The database will not install if this value is zero. (PalmOS 1.0.6)
Last Backup Date	4	Numeric*	Expressed as the number of seconds since January 1, 1904. This can be left at zero and the database will install.
Modification Number	4	Numeric*	Set to zero.
AppInfoArea	4	Numeric*	The byte number in the PDB file (counting from zero) at which the AppInfoArea is located. This must be the first entry in the Data portion of the PDB file. If this database does not have an AppInfoArea, set this value to zero. See Note A below.
SortInfoArea	4	Numeric	The byte number in the PDB file (counting from zero) at which the SortInfoArea is located. This must be placed immediately after the AppInfoArea, if one exists, within the Data portion of the PDB file. If this database does not have a SortInfoArea, set this value to zero. Do not use this. See Note C below for further details.
Database Type	4	String	Set this to the desired value. Generally it should match the Database Type used by the corresponding application This is 4 characters long and does not have a terminating null.
Creator ID	4	String	Set this to the desired value. Generally it should match the Creator ID used by the corresponding application. In all cases, you should always register your Creator ID before using it. This is 4 characters long and does not have a terminating null.
Unique ID Seed	4	Numeric*	This is used to generate the Unique ID number of subsequent records. This should be set to zero. See Note B below.
NextRecordList ID	4	Numeric*	Set this to zero. The element is used only in the in-memory representation of a PDB file, but exists in the external version for consistency.
Number of Records	2	Numeric*	This contains the number of records

*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
The Record List is made up "n" structures, where "n" represents the number of records in the PDB file. Each structure has the following format.

Field	Bytes	Type	Notes
Record Data Offset	4	Numeric*	The byte number in the PDB file (counting from zero) at which the record is located.
Record Attributes	1	Numeric	0x10 (16 decimal) Secret record bit. 0x20 (32 decimal) Record in use (busy bit). 0x40 (64 decimal) Dirty record bit. 0x80 (128, unsigned decimal) Delete record on next HotSync. The least significant four bits are used to represent the category values.
UniqueID	3	Numeric*	Set this to zero and do not try to second-guess what PalmOS will do with this value. See Note B above.

*See note after first table for Numeric field types.

Assembling the File
To create the PDB file, you must assemble the components in this order.

Area	Description
Database Header	The complete header format, as described above.
Record List	Must contain at least one entry.
Filler	Upon transferring a database from the PalmPilot to the desktop environment, the PDB file will have two bytes of filler here. It does not appear to be necessary to insert these two bytes here when creating a PDB file for installation on the PalmPilot. However, if you read a PDB file created by the backup conduit (setting the Backup Bit), you will find that there are two bytes of data in this location.
Data Area	It must be in this order: AppInfoArea (if present), SortInfoArea (if present), and records, sequentially. The order is important because each element's size is computed based on the location of the following element.

Advice
With each release of desktop or device software from Palm, the behavior of the software changes slightly. In an attempt to keep this document up-to-date, please advise the author of any discrepancies or inaccuracies you may observe.