PDBMake

Embed Text or Binary File in a
Palm Computing Platform Database

by John Walker


Once you've developed an application for the Palm Computing Platform you may ask yourself, "Now how do I get the database it needs from the desktop machine onto the handheld?". You could, of course, develop a full fledged HotSync conduit, but that's a lot of work, and in many cases far more elaborate than what's needed; simply getting data, whether in text or binary form, physically from the desktop to the handheld.

For example, suppose you've written a restaurant guide application for the handheld, and you wish to download a restaurant database for your region which you've already made on the desktop. Since the database is never changed by the handheld, only the desktop, there's no need for bidirectional HotSync functionality; you simply want to transfer the database to the handheld so your application can read it there.

PDBMake is a generic (non-application specific) desktop program which permits you to accomplish this. It takes an arbitrary desktop file: text or binary (but if it's binary the responsibility of coping with byte order and alignment differences between the desktop platform and handheld is up to you, so be careful) and embeds it into a Palm Program DataBase .pdb file. Text files are embedded with one record per line, zero terminated, while binary files are embedded as a single record, optionally preceded by the length of the original input file.

Once you've created a PDB file with PDBMake you install it on the handheld (or emulator) just like any other application or database. When you next HotSync the handheld to the desktop, the database will be installed on it, where your application can access it through the usual Data Manager mechanisms.

PDBMake runs on Windows and Unix, and is insensitive to the byte order and structure padding conventions of its host platform. Complete source code and a ready-to-run WIN32 executable are included. The program is in the public domain and may be used and in any way without any restrictions whatsoever; this means you can freely reuse the code which creates PDB files in your own application-specific utilities.

Documentation for PDBMake follows, in Unix manual page style.

NAME

pdbmake - embed text or binary file in Palm Computing database

SYNOPSIS

pdbmake [-abruw] [-c CreatorID] [-n Name] [-t Type] infile [ outfile ]

DESCRIPTION

pdbmake embeds infile into a Palm Computing Program Database (.pdb) suitable for installation onto the handheld platform. Binary files are embedded as a single record, optionally preceded with the length, while text (ASCII or ISO) files can be embedded with one record per line, null terminated. pdbmake runs on both Windows and Unix platforms, is insensitive to byte order and structure padding conventions, and can embed text files in any of the following end of line sequences: Unix, DOS/Windows/TOPS/CP-M, Macintosh, and VAX/VMS.

OPTIONS

-a
Embed text file, one record per line. Line terminator character(s) are removed and each line is terminated by a zero byte.

-b
Set backup bit in the output .pdb file. HotSync will automatically back up the database to the user's BACKUP directory on the desktop.

-c CreatorID
Set the database's creator ID to the specified value (maximum 4 characters). Each application should register a unique Creator ID in the Palm Computing Creator ID Database. If no CreatorID is specified, "PdbM" is used, which is registered to pdbmake itself.

-n Name
Set the database's name to the given value (maximum 32 characters). Since database names must be unique across all applications on the handheld, by convention one appends a hyphen and the unique Creator ID to each database name. If no Name is given, "Database-PdbM" is used.

-r
Set read-only bit in the output .pdb file.

-t Type
Set the database's type to the specified value (maximum 4 characters). The type is assigned by the application, which can retrieve its databases by Creator ID and type. If no Type is given, "PdbM" is used.

-u
Print how-to-call information.

-w
Binary databases (those created when the -a option is not present) are written as a single record containing the entire contents of infile, preceded by four bytes containing the length of the following data (in Palm byte order: MSB first). Specifying the -w option suppresses this length field; the Palm record will contain just the data from infile; if you need the length, you'll have to figure it out yourself from the database structures on the handheld.

FILES

If no outfile is named, an output file name is synthesised from infile by replacing the extension with ".pdb" or appending ".pdb" to the name if it contains no period.

BUGS

When you embed a binary file, pdbmake simply takes the bytes from infile and hammers them into a record in the PDB file (preceded by the number of bytes as a long unless the -w option was specified). If the binary file was created on a platform with different byte order or structure padding conventions, it's up to the desktop program which wrote the binary file to conform to the conventions of the handheld, or else the handheld application to decipher what the desktop wrote. While pdbmake is itself insensitive to these issues, the responsibility to deal with them in the binary data embedded is that of the user.

Source code assumes that "rb" and "wb" mode specifications to fopen will open files in binary mode on platforms which (unlike Unix) distinguish between text and binary files and that the presence of the "b" in the mode string will not cause problems on platforms which make no such distinction. I know of no platform on which this would create a problem, but you never know.

SEE ALSO

fopen(3), palmdump(1)

Download

PDBMake is supplied as a Zipped archive containing complete source code and pdbmake.exe, a ready-to-run 32-bit Windows (WIN32) command-line utility built with Visual C++ 5.0. A Makefile is included which should build an executable on most Unix platforms.

Download pdbmake.zip

Support

This software is utterly unsupported; you're entirely on your own. If you're developing software for the Palm Computing Platform, you should probably sign up for the Palm Solution Provider program.

Other Palm Computing Resources at Fourmilab

Fourmilab Home Page


by John Walker
Moon Day, 1999