|
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. Write to
bobf@ilx.com or mailto:bobf@jhu.edu. |