.KEYWORD dompalm
.FLYINGHEAD ENTERPRISE CONNECTIONS
.TITLE How to generate Doc files for Palm devices from Notes
.OTHER
.SUMMARY If you’ve ever used a Palm Computing device, you’re probably familiar with Doc files. Files saved in this format can be easily downloaded and viewed on your Palm device using one of many popular Doc viewer applications. This article by Mark Lawson shows you how to easily create uncompressed Doc e-text databases using just LotusScript. Pretty soon, all your Notes notes will be in the palm of your hand.
.AUTHOR Mark Lawson
If you’ve ever used a Palm Computing device, you’re probably familiar with Doc files. Files saved in this format can be easily downloaded and viewed on your Palm device using one of many popular Doc viewer applications.
This article shows you how to easily create uncompressed Doc e-text databases using just LotusScript. For many users this well-supported format, derived from the original program by Rick Bram, is their first choice for storing reference information, articles and even whole books on the Palm device. Once installed, Doc databases can be read by a variety of programs such as AportisDoc or TealDoc and can include formatting, bookmarks and even pictures depending on the chosen reader. Now there is even an editor called QED. A word of warning however: as you know, Palm devices have small amount of memory (1-4Mb) and little 160×160 screens; you may have to be inventive.
.H1 Doc database structure
A Doc database is actually a format-within-a-format, wrapped up inside a standard Palm device PDB database. To keep this article short we’ve omitted a detailed account of the PDB and Doc header fields but we’ve included a more detailed description in the accompanying example. After the PDB header and the offset list (easy in this case as the records are all defined lengths) the first record in the database is the Doc header. This simply holds the version; 1 for uncompressed in our case, and the number of 4096-byte records which then follow in successive records.
A simplified view of the Doc-PDB format as shown in Table A. An interesting feature to note is the 2-byte padding. Although not actually part of the format, the 2-byte pad is necessary for the file to install properly.
.BEGIN_TAB_TABLE A Doc formatted PDB file
.TAB_TABLE_HEADER Pdb Section Bytes
.TAB_TABLE_ROW Pdb Title 32
.TAB_TABLE_ROW Pdb Header 48
.TAB_TABLE_ROW Record Offset 1 8
.TAB_TABLE_ROW Record Offset 2 8
.TAB_TABLE_ROW Record Offset N 8
.TAB_TABLE_ROW Padding 2
.TAB_TABLE_ROW Record 1 Doc Header 16
.TAB_TABLE_ROW Record 2 Doc Data 1 4096
.TAB_TABLE_ROW Record N Doc Data N-1 4096
.END_TAB_TABLE
.H1 LotusScript and Palm device idiosyncrasies
There are a couple of hurdles to overcome before writing the file:
.BEGIN_LIST
.BULLET The DragonBall processor in any Palm unit expects data to be presented in a byte-swapped (MSB) format, so on Intel PC’s you need to do a reversal (e.g. B2-EB-77-F4 is reversed to become F4-77-EB-B2). I’ve written Back4() and Back2() to handle this for 4 and 2 byte values using the simple Hex$() and CLng() functions rather than binary math. If you own a Mac, you’ll have to change the code for Back4() and Back2() in the script library since the Mac’s processors (also Motorola devices like in the Palm device) don’t need the reversal.
.END_LIST
.BEGIN_LIST
.BULLET The PDB header has date fields based on seconds from January 1, 1904. These are used in the HotSync process. I’ve written GetSecs() to handles this properly using a known seed value.
.END_LIST
.BEGIN_LIST
.BULLET Be aware that there’s a problem opening our file in binary mode. We need to write out the binary data in the headers. Unfortunately, in this mode Notes writes out all strings in Unicode; that’s two bytes per character rather than one. So, we need to write text data in output mode. The solution is to create our file in three parts, closing and re-opening each time as you can see in Table B.
.END_LIST
.BEGIN_TAB_TABLE B File modes for PDB file
.TAB_TABLE_HEADER Mode Action
.TAB_TABLE_ROW Output Write PDB Title. 32 bytes, 0 terminated.
.TAB_TABLE_ROW Binary Write PDB header, record list and Doc header.
.TAB_TABLE_ROW Output Write Doc records.
.END_TAB_TABLE
.H1 Doc format example
With the above problems sorted out and structures for the various headers created, we’re ready to go. As an example we’ve created a small database that creates a PDB file from a Rich Text field using GetFormattedText and attaches it to the document. There is a design limit of 32K per PDB as that is the limit for a singlestring with the given code.
.BEGIN_KEEP
.H1 A final word about formatting
Once you’ve gotten past the basics of creating a Doc file, you can go on to the niceties of formatting. You may find yourself experimenting with the format to get the result to look right on the Palm organizer’s small screen — especially where it may wrap text followed by your carriage return. Also worth noting is that RichText bullets do not convert, so replace them with the Chr(95) block instead. Happily most of the Doc viewers support HTML-like tags of some degree of complexity in the pre-converted text. This will help with formatting and navigation. As with browsers, the support varies and you can end up tied to a particular viewer if you make heavy use of particular features. Figure A shows a simple example of tags from the Notes database.
.FIGPAIR A Here’s a poem with a simple tag in the Notes database.
Figure B shows how that Notes field translates onto the Palm device..
.FIG B Here’s the converted poem as seen on a Palm device using TealDoc.
.BEGIN_SIDEBAR
.H1 Product availability and resources
Aportis Doc is available from http://www.aportis.com.
TealDoc is available from http://www.tealpoint.com.
QED is available from http://www.visionary2000.com/qed.
You can download the sample database from ftp://ftp.palmpower.com/palmpower/outgoing/issues/pp0599-palmdoc.zip. It is not normally our practice at PalmPower to provide download samples. However, at the request of the author, we have posted this file. If you have problems using this file, please contact the author directly or post a message on the PowerBoards. The editorial staff at PalmPower is not able to provide technical support.
.END_SIDEBAR
.BIO Mark Lawson is a consultant with Electric Memo Ltd. He can be reached at markl@electricmemo.com.
.DISCUSS http://powerboards.zatz.com/cgi-bin/webx?13@@.ee6cf81
.END_KEEP
