Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

1    Introduction to File Formats

Palm OS® File Formats

Exploring Palm OS®

There are two types of file formats that are commonly used in the Palm OS® platform:

  • Palm database (PDB)
  • Palm resource (PRC)

Files with a .pdb extension are record databases. Files with a .prc extension are resource databases. Please note, however, that the filename and extension on the desktop do not determine the name or type of database created on the handheld. The database header information inside the file determines a database name and type.


NOTE: Resource databases contain resources, not records; however, in some places the documentation and structure types use the term record generically to refer to the individual data entities stored inside of databases, including resource databases.

This chapter provides an overview of the file format types, including the database header that is used for each format.

Chapter 2, "PDB and PRC Database Formats," takes an in-depth look at the PDB and PRC file formats, which are almost identical.

About the File Format Types ^TOP^

This section provides an introduction to the two file format types that are described in this book. Each file format type is stored as a database.

In general, a database contains header information and a sequential list of records or resources. In addition, each database can contain one or two pieces of free-form data whose format is defined by the application that created it. The records within a database are similarly structured with record header information and record data.

File Formats Versus Memory Formats ^TOP^

This book describes the format of Palm databases that are stored in files on desktop computers. When one of these databases is loaded into a Palm Powered handheld, the database is stored in memory in a format that is similar to, but different than the format described in this book. The in-memory format of Palm databases is subject to change and is not documented by PalmSource, Inc.

Databases are typically imported into handheld devices when a user performs a HotSync® operation that installs an application. When a database is imported into a Palm Powered handheld, the Palm OS converts the database into standard Memory Manager objects. The Memory Manager tracks the size of each record or resource, and thus adds memory overhead; this means that the size of a database on the device is larger than its size on the desktop computer.


NOTE: The databases stored in ROM on Palm Powered handhelds are stored in a memory format, not in the file formats described in this book.

Palm Database (PDB) Files ^TOP^

A PDB is a record database generally used to store data for an application.

Palm Resource (PRC) Files ^TOP^

A Palm resource file contains a different type of data (resources instead of records), but has an almost identical structure to a PDB file. Palm OS applications are resource databases. A Palm OS application contains code resources as well as user interface resource elements.

Data Structures ^TOP^

The objects in Palm Database files can be represented by C structures, which are described in the chapters that follow.

About Records and Resources ^TOP^

Records and resources are both blocks of memory that contain any data you want. The exact definition of a record or resource is up to the application. From a low-level perspective, the difference between records and resources is the size and contents of the header for each object.

Records and resources are used for different purposes:

  • Records are used to store application data such as memos or address book entries.
  • Resources are used to store the code and user interface objects for an application.

You can treat records and resources as ordered or unordered databases. You can use a callback function to sort record databases; however, you cannot sort resources on a device. You can compare two records to determine the order in which they belong; however, an index does not exist.

About Database Formats ^TOP^

Each database is stored in a file on a desktop computer in sequential format, as shown in Figure 1.1. The format of each database file is logically structured as shown in Figure 1.2.

Each database contains the following component parts:

  • a database header that describes the database, references the appInfo and sortInfo blocks, and contains the record list, which references each record in the database
  • an optional application information (appInfo) block in which you can store information specific to your application
  • an optional sorting information (sortInfo) block in which you can store unique ID cross-reference tables or other meta information
  • raw record or resource data

NOTE: All structure elements in all headers are byte-packed in network (big-endian) order.

Figure 1.1  Database Storage Format

Figure 1.2 shows the logical representation of a record database file, with the header referencing the application information and sort information blocks, and with each record list referencing the raw data for the records stored in the database. The logical representation of a resource database file is the same, except that the record lists that refer to raw record data are replaced by resource lists that refer to raw resource data. The logical representation of a web clipping application database is also very similar.

Figure 1.2  Logical Database Format for a Record Database

The Palm Database Header ^TOP^

The Palm database header is a standard DatabaseHdrType structure that is used to represent the header in PDB and PRC database files. The format of the header is shown in Figure 1.3. The byte values shown are offsets, in hexadecimal, from the beginning of the database (and of the header).

Figure 1.3  Palm database header

Note that the structure shown in Figure 1.3 is how the header of a Palm Database is represented in a file on a desktop computer.

Palm Database Header Structure ^TOP^

The following structure represents a database file header:

Prototype

typedef struct {
   UInt8 name[dmDBNameLength];
   UInt16 attributes;
   UInt16 version;
   UInt32 creationDate;
   UInt32 modificationDate;
   UInt32 lastBackupDate;
   UInt32 modificationNumber;
   LocalID appInfoID;
   LocalID sortInfoID;
   UInt32 type;
   UInt32 creator;
   UInt32 uniqueIDSeed;
   RecordListType recordList;
} DatabaseHdrType;

Fields

name
A 32-byte long, null-terminated string containing the name of the database on the Palm Powered handheld. The name is restricted to 31 bytes in length, plus the terminator byte.
This name is also used to create the file name of the PDB when it is backed up during the HotSync process.
attributes
The attribute flags for the database.
version
The application-specific version of the database layout.
creationDate
The creation date of the database, specified as the number of seconds since 12:00 A.M. on January 1, 1970. (The defined base date is January 1, 1970, but for legacy reasons, it might be either January 1, 1900 or January 1, 1904 if the file was created on non-Windows platforms.)
modificationDate
The date of the most recent modification of the database, specified as the number of seconds since 12:00 A.M. on January 1, 1970. (The defined base date is January 1, 1970, but for legacy reasons, it might be either January 1, 1900 or January 1, 1904 if the file was created on non-Windows platforms.)
lastBackupDate
The date of the most recent backup of the database, specified as the number of seconds since 12:00 A.M. on January 1, 1970. (The defined base date is January 1, 1970, but for legacy reasons, it might be either January 1, 1900 or January 1, 1904 if the file was created on non-Windows platforms.)
modificationNumber
The modification number of the database.
appInfoID
The local offset from the beginning of the database header data to the start of the optional, application-specific appInfo block.
This value is set to NULL for databases that do not include an appInfo block.
sortInfoID
The local offset from the beginning of the PDB header data to the start of the optional, application-specific sortInfo block.
This value is set to NULL for databases that do not include a sortInfo block
type
The database type identifier.
For PDB databases, the value of this field depends on the creator application.
For PRC databases, this field usually has the value 'appl'.
creator
The database creator identifier.
uniqueIDSeed
Used internally by the Palm OS to generate unique identifiers for records on the Palm device when the database is loaded into the device.
For PRC databases, this value is normally not used and is set to 0.
recordList
A list of the records or resources in the database, as described in the next section.

IMPORTANT: There is always a gap between the final record list in the header and the first block of data in the database, where the first block might be one of the following: the appInfo block, the sortInfo block, raw record or resource data, or the end of the file. The gap is traditionally two bytes long; however, if you write code to parse a database, your code should be able to handle any size gap, from zero bytes long and up.

The Record List ^TOP^

The Palm database header ends with a record list. The record list has its own header, followed by 0 or more record entries. Each record entry describes a single record in the file.

The record list has a variable length. When the database is loaded into a Palm Powered handheld, the Palm OS attempts to grow the list. If it cannot grow the list, the OS creates another record list and links it to the previous one by filling in the nextRecordListID field with the location of the new list. This capability is rarely used, and its use is discouraged by Palm. For more information, see "About Multiple Record or Resource Lists in a Database.""

Each record entry references the location of the raw data for the record or resource and contains the attribute and ID information for that record or resource.

The remainder of this chapter describes the record list structure. However, the format of the record entries is different for different Palm database types. The record entry format for PDB databases and the resource entry format for PRC databases are shown in Chapter 2, "PDB and PRC Database Formats."

Figure 1.4 shows the structure of a record list.

Figure 1.4  Palm Database record list

Palm Database Record List Structure ^TOP^

The following structure declaration represents a Palm Database record list:

Prototype

typedef struct {
   LocalID nextRecordListID;
   UInt16 numRecords;
   UInt16 firstEntry;
} RecordListType;

NOTE: The placeholder bytes shown in Figure 1.4 appear at the end of the record list, if there is one. If there is no list, these bytes appear just after the list header; otherwise, they appear after the last entry in the list.

Fields

nextRecordListID
The local chunk ID of the next record list in this database. This is 0 if there is no next record list, which is almost always the case.
For more information, see "About Multiple Record or Resource Lists in a Database."
numRecords
The number of record entries in this list.
firstEntry
The start of an array of record entry structures, each of which represents a single record in the list.

About Multiple Record or Resource Lists in a Database ^TOP^

The structure of Palm databases allows for multiple record lists in a single database; the record lists are chained together by setting the nextRecordListID field of the first record list to the offset of the next list in the database.

In practice, this capability is very rarely used, and the nextRecordListID field in the database header is almost always set to 0, which indicates that there is only one record list in the database. Since a single record list can be used to describe the maximum number of records (64K) in a file, multiple record lists are never required.

PalmSource, Inc. recommends against building databases with chained headers, and that your parsing code reject databases that have a non-zero value in the nextRecordListID field, to avoid potentially truncating such a database if your code encounters one.

A database with chained record lists might be encountered under very specific circumstances:

  • when a huge database (one containing more than approximately 6000 records that has caused the headers to fragment) is beamed to a desktop OBEX stack from a Palm handheld device running version 3.5 or earlier of the Palm OS
  • when code on a Palm handheld device uses the ExgDBWrite() function to produce a PRB or PRC file image from such a database

NOTE: Version 4.0 and later of the Palm OS never produces chained record lists.

The Application and Sort Information Blocks ^TOP^

The database header can reference two optional application-specific blocks of information:

  • The sort information (sortInfo) block
  • The application information (appInfo) block

The sortInfo block is under your control. The OS does not use sortInfo. You can use it to store meta information about the database.

You are free to include whatever data you want in the appInfo block. However, there are restrictions on how you use this block if one of the following applies:

About Third Party Tools ^TOP^

There are a number of third party tools available for creating Palm databases on desktop computers, and for converting images in various formats into Palm image format. Rather than include a partial list, PalmSource, Inc. encourages you to search on the Internet for these tools, and recommends the following search terms:

  • convert pdb
  • convert prc