The Hacker's Diet®

Eat Watch® for the Palm Computing® Platform

by John Walker

Palm Computing resources at Fourmilab


The central component of the computer tools which accompany The Hacker's Diet is the Eat Watch--the weight monitoring, charting, and trend analysis software originally developed as Microsoft Excel macros in 1990. By the standards of the time, it was pretty cool to be able to enter weight and exercise log entries into a spreadsheet which automatically calculated the daily trend and variance, and then press a button and have a pretty, full-colour chart pop up complete with weight trend and calorie balance analysis.

But that was then, and this is now (2000). Never did I imagine when writing the original macros that Microsoft's unique blend of incompetence and contempt for their customers' investment would cause those macros (like virtually every other Excel macro package all around the world, except for the most trivial) to break on almost every successive release of Excel, all along the tedious, tear-drenched trudge from Excel 2.1 to Excel 2000; that ever steepening spiral into the foul pit of intellectual corruption from the days of "386 Enhanced Mode" to the era of the talking paper clip.

But I digress. Due numerous experiences with shoddy quality and incessant incompatibilities in Microsoft products, in 1996 I abandoned all new software development for that platform. But the computer tools for The Hacker's Diet remained wedded to Excel, a proprietary platform which history had proven notoriously shaky and likely to continue to degrade since Microsoft abandoned the macro language in which I developed the tools in favour of an even worse one based on Visual Basic. Today, Microsoft provides little or no documentation of or support for the original macro language in current releases of Excel.

Eat Watch in your Palm

When I realised in April of 1999 that I simply could not maintain my credentials as a nerd unless I owned a PalmPilot (or whatever they're calling it this week) and developed some useful software for it, it dawned on me that the weight logging, charting, and analysis package for The Hacker's Diet was an ideal Palm application. Here was a totally non-Microsoft platform with a good record for upward application compatibility and excellent developer support. Further, the job was a perfect fit for the platform. Most people don't want to turn on their computer and fire up Excel every day to just enter daily log entries, so they keep a log on paper and then transfer the data to the computer every week or perhaps at the end of each month. But keyboarding a block of log entries is tedious and, like most tedious things, invites procrastination. And if you put off maintaining the log and charts for month after month, you may miss a creep in the trend, easily fixed when it begins, but which may require more distasteful dieting if discovered too late.

With a PalmPilot version of the Eat Watch, there's no need to keep a paper log at all! If you're a proper geek like myself, your PalmPilot is never far from reach (just like a slide rule in days of yore), especially since it, unlike the slide rule, can serve as an alarm clock. What could be simpler? Get up, weigh yourself, write the weight into the PalmPilot and get instant feedback, including an up to date chart. The ability to synchronise data on the handheld with your desktop computer allows backing up log data against the inevitable day the dog eats your PalmPilot or some other mishap befalls it, and having the data on the desktop allows deploying an application there which produces permanent logs and charts in HTML, an open standard which can be examined with any Web browser or even (if you're particularly vain and/or proud of your progress), posted on a Web site!

Just a simple matter of programming...months voilà! Like most Palm applications, the Eat Watch is organised into a collection of forms, each of which is discussed in the following sections. The program contains a number of Palm-style shortcuts and gimmicks to reduce the number of taps and characters you have to write; they are highlighted in the text with the * icon.

Monthly Log

Monthly Log form This form is used to enter items in a monthly log. When you launch the Eat Watch application, the current month's log appears with today's date (highlighted in bold) scrolled into view.

When you enter a weight and close the field (by writing Return or tapping in a different field) the trend is calculated for that day and the Variance (difference between today's weight and the trend) appears in the "Var" field, positive if the weight is above the trend, negative if below. Weight and variance are displayed to one decimal place for kilograms and pounds. When stones (a predominantly British unit of weight equal to 14 pounds) are chosen as the weight unit, weight is shown in stones and pounds separated by a space; for example, a weight of 152 pounds would appear as "10 12". No decimal places are shown for pound weights accompanying stones but you may enter them when making log entries. When you display the log in pounds or kilograms, you'll see the decimals. When weight is set to stones, variance continues to be shown in pounds--a variance of one or more stones would indicate something seriously amiss! You can enter weight with up to two decimal places (one when using stones), but it's rare to find a scale which shows weight to a resolution better than 100 grams, nor are such tiny increments in daily weight at all relevant to achieving and maintaining your weight goal.

If you're following the exercise program presented in The Hacker's Diet, use the "Rung" field to record which rung on the exercise ladder you completed that day. You can use the Flag ("Flg") field to mark any recurrent event you're interested in keeping track of on an ongoing basis, for example, whether you found the time for a game of tennis or had an ice cream snack before turning in for the night. The "Comments" field can be used record any text you like (up to 80 characters, just like a punch card). In this example the user observes that on the 23rd and 24th of September she was in Paris, explaining the missing weight and exercise entries as well as, perhaps, the positive variance recorded upon her return.

The navigation arrows at the top right of the form permit you to scroll to prior and subsequent months (if any). In the example, the month displayed is the current month and hence only the previous month button is shown. Tapping the "Year" button at the bottom displays the Year View form which provides quick navigation to other months and years in the database. The "Chart" button shows a weight, trend, and exercise chart along with a trend analysis for the month. The "Trend" button displays longer-term trend analyses.

* To duplicate the previous nonblank item in a column, write a period in the field (just "tap-tap" with the stylus followed by a return). This is handy for entering exercise rung entries, which change infrequently and rarely at all once you've reached your goal. If you use the comments field to note when you're out of town, you can just double tap when you're in the same place as the day before. If you must enter a comment consisting of a single period, just write a space after it.

* Abbreviated Weight Entry. Weight generally changes little from day to day, but if your scale reads to the nearest 100 or 200 grams (or the equivalent in pounds), a given day's weight will rarely be identical to that of the day preceding. This limits the utility of the field copying trick discussed in the last paragraph. The monthly log form permits you to abbreviate weight entries which differ slightly from the last. If you write the decimal character (period or comma, as selected on the Formats page of the Preferences application) followed by a single digit, the previous weight entry will be copied with the decimal digit replaced by the digit you wrote. For example, if yesterday's weight was 73.8 kg and you write ".6", today's weight will be entered as 73.6 kg. Similarly, writing a single digit followed by the decimal character and a second digit copies the previous weight, replacing its units and decimal place with those you entered. If yesterday you weighed 158.2 pounds and today you tipped the scale at a mere 157.9, you need only write "7.9" to enter today's weight. If the decimal place is zero, you need not write it--simply write the units digit followed by the decimal character.

When the weight unit is set to stones you may use the abbreviations
11   9 6. 11   6
11   6 4.8 11   5
10   11 2. 10   12
10   11 9. 10   9
10   9 10.2 10   10
above to change the pounds and decimal place of the previous stone and pound display (note that while lack of screen space precludes showing decimal pounds in stones and pounds mode, they are retained in the log and will be shown if you change the display unit to pounds). In addition, when the display unit is set to stones, if the previous entry has a pounds field between 10 and 13 and you enter a single digit, decimal character, and optional decimal digit, the action taken depends on the units digit you enter. If it's between 0 and 3, it replaces the last digit of the pounds in the last entry, but if the digit is 4 or greater (which is invalid in a stones and pounds display), that digit replaces the two digit pounds field in the previous entry. This reduces the scribbling required if your weight happens to fluctuate around X stones 10. In addition, when the display unit is stones, you may enter two digits followed by the decimal character and an optional decimal digit to replace the pounds field of the last stones and pounds entry; you must enter the decimal character to distinguish the entry from one denoting an even number of stones. The examples in the table at the right should clarify how this works in practice.

* If you haven't yet written in today's weight, writing a number into the Graffiti area opens today's Weight field for editing and places the character into it. Thus you can enter the weight without having to first tap in the field. You can also open today's weight field for editing by tapping the "Today" button when no weight has been entered for the day.

* Tapping the heading of the "Rung" column takes you directly to the Exercise Ladder reference form, showing the daily exercises for your current rung. When you've completed the exercises, tap the "Record" button on that form to fill in today's rung field and return to the log form.

* View menu on monthly log form Would you like to see your weight in different units than the one you've chosen for your logs in the Preferences form? Tap the Menu button to the left of the Graffiti area, drop down the View menu and tap the unit you wish: Kilograms, Pounds, or Stones. The log will be re-displayed in the chosen unit and you can, if you wish, make additional entries in that unit (handy when visiting a country where a different unit is prevalent and you don't want to convert every day's weight by hand). The chosen display unit is also used by the Chart or Trend Analysis forms, both of which may be reached from the View menu. Changing the display unit only affects how weight is displayed and entered: entries in the log continue to be kept in the "Log Unit" you've selected on the Preferences form. The View menu also permits direct navigation to the calendar-like Year View form, a list of all years for which logs exist, an exhaustive list of logs by year and month, the exercise ladder reference, and the diet calculator. The Chart menu allows you to display historical charts of various durations.

* If you've enabled "Protect Log Entries" in the Preferences form (enabled by default, and recommended), nonblank log entries for days prior to the current date and entries for dates in the future are protected against being opened for editing by accidental taps; taps in them are ignored. If you discover an error in a past entry and wish to correct it, you could use the Edit menu to display the Preferences form, turn off protection, correct the entry, then enable protection again, but that's a bit tedious, and you might forget to turn protection back on after correcting the error. Instead, you can temporarily disable protection for a prior (but not future) date simply by tapping twice in succession in its day and weekday field at the left of the table; the field is inverted to indicate the day is unlocked. You can then tap any single field of that day for editing and correct the entry. When you close the field, protection is restored for the day and its label is redrawn non-inverted. (If you need to correct more than one item in a day's entry, simply unlock it as many times as required.)

Monthly Chart

Chart form The Monthly Chart form is displayed by tapping the "Chart" button on the Monthly Log form. The weight and trend are plotted in the "Floats and Sinkers" form described in the book: the trend is drawn as a solid line with each day's weight shown as a diamond attached to the trend by a line which shows the extent to which it is above or below the trend. Days for which the "Flag" box is checked in the log are shown as solid diamonds; days not flagged are drawn as open diamonds. The vertical axis at the left gives the weight scale and the days of the month are shown on the horizontal axis. Below the chart, a snapshot analysis of last week's weight gain/loss and calorie excess/deficit is given; for a longer term analysis tap the Trend button. If one or more days of the month have the Flag box checked, the percentage of flagged days follows the calorie balance.

If the monthly log contains any entries in the exercise Rung column, a dotted line is plotted showing daily exercise level (blank for any day the Rung is not filled in) with a Rung scale from 1 to 48 at the right of the chart. The scale is adjusted so the last rung in the chart is explicitly labeled.

If the month displayed is within or after the conclusion of a diet plan created by the Diet Calculator, and the user has indicated the plan should appear in the chart, the plan is drawn as a dashed line, with dates after the end of the plan shown as a horizontal dashed line at the plan's goal weight. By comparing the actual trend as it evolves with the plan, you can evaluate your progress toward the goal. After arriving at the goal, the constant goal weight provides a reference for evaluating the subsequent evolution of the trend.

You can navigate to earlier and later months by tapping the navigation buttons at the upper right of the form (in this case the user is viewing the most recent month in the database so only the previous month button is shown). The "Log" button returns you to the log for the month shown in the chart, while the "Year" button displays the Year View of that containing the chart.

Menus similar to those in the Monthly Log permit direct navigation from a monthly chart to other forms.

* Tap on a day within the chart to display the log for that month with the day you tapped on visible in the log.

Historical Charts

Historical chart form Chart menu on monthly log form Historical charts, covering periods of 30 days, a quarter (three months), six months, one year, or the entire history since you began keeping log entries may be displayed by choosing the corresponding items in the Chart menu from either the Monthly Log or Monthly Chart forms. An historical chart showing the trend over the requested duration (assuming the requisite log entries are present) is plotted and a trend analysis for the period charted is shown at the bottom of the chart. As with monthly charts, the exercise rung (if used) is plotted as a grey line and the Diet Plan (if it covers any portion of the charted period and the user has checked the box to request it be plotted) as a dashed line.

Historical charts covering a 30 day interval differ from Monthly Charts in that the latter always show days of a single month, while 30 day historical charts display a 30 day period which may span month boundaries. In the early days of a month a 30 day historical chart may give you a better perspective on the evolution of the trend than a monthly chart which only shows a handful of days. 30 day historical charts plot weight and flag entries as "floats and sinkers" in the same form as monthly charts, but these are excluded from longer-term charts in which they would create such clutter as to render them useless. Over periods of a quarter or longer, only the trend really matters anyway.

Historical charts displayed from the Monthly Log or Chart forms cover a period ending on the last day of the month or today's date if the current month is displayed and not yet completed. You can navigate to earlier and later periods in the database by tapping the left and right arrows at the right in the title bar. If the present chart contains the first or last date present in the logs, the arrow buttons will not appear. The duration of the chart is shown both by the title and by the box checked at the bottom right of the form. Tapping a different duration box shows a chart of that duration ending at the same date as the present chart. (When a chart of the entire database is shown, none of the duration buttons are checked, but you may still tap them to select different duration charts ending at the current date.)

The "Year" button shows the Year View form to provide quick navigation to other months and years in the database. The "Today" button displays the Monthly Log with today's date scrolled into view, and the "Trend" button shows the trend analysis form. Menus provide navigation to all the other forms.

* Tapping within the chart area displays the Monthly Log for the date you tapped.

Trend Analysis

Trend Analysis form The Trend Analysis form uses information in current and prior monthly logs to calculate your average weekly weight loss or gain and the corresponding average daily calorie deficit or excess. For each time period linear regression is used to fit a straight-line trend and the rate of change in weight and calorie balance are determined from its slope as described in the book.

The calculations required to fit a trend to the log data are substantial and take a while--about 12 seconds on a Palm IIIx. If there aren't enough monthly logs in the database to compute the trend for a given period, its row in the Trend Analysis form is left blank.

The "Today" button takes you back to the monthly log entry for the current day, while the "Done" button returns you to the top of the current Monthly Log.

Diet Calculator

Diet calculator The Diet Calculator allows you to plan a change in weight, either loss or gain, exploring the relationship between the calorie deficit or excess and the duration of the diet. The resulting diet plan can optionally be shown in the Monthly Charts, allowing you to monitor your progress and to display a constant target weight at the conclusion of the diet.

The Diet Calculator is displayed from the View menu of the Monthly Log, Monthly Chart, or Historical Charts forms. When you first display the Diet Calculator, the daily calorie balance is set to -500 calories per day (which results in the loss of about a pound per week, as discussed in the book), and the initial weight to the most recent trend value, rounded to the nearest whole number. Weights are shown in the display unit selected in the Preferences form, and may be changed by tapping the units shown to the right of the form title. The initial goal weight is arbitrarily set to 5 kilograms or 10 pounds less than the starting weight; adjust this to your personal weight goal. The default starting date of the diet is the current date; The "Weeks to go" and "Months to go" fields will then show the duration of the diet and the "End date" when you may expect to achieve the goal weight.

This form is fully associative--you may change any quantity and the form will recalculate the others accordingly. Setting the daily calorie balance adjusts the weight change per week, duration, and end date of the diet. The calorie balance should be negative if you wish to lose weight and positive if your intention is to gain weight. You may change the initial weight and goal weight to any values you wish, which adjusts the desired weight change and recomputes the duration of the diet. If you change the desired weight change, the goal weight is modified to reflect the new difference from the initial weight and the diet duration recalculated. Changing the start date adjusts the end date based on the estimated duration of the diet. Adjusting the weight change per week, weeks or months to go, or the end date modifies the daily calorie balance to achieve the desired weight change in the specified period of time.

The values you specify in the Diet Calculator are saved and reappear when you return to the Diet Calculator. If you check the "Show plan in chart" box, the course of the planned diet is shown as a dashed line in the Monthly Chart displays for the duration of the diet and subsequently as a horizontal dashed line representing your weight maintenance goal. If you find this distracting, simply uncheck the box. The Done button takes you back to the current month's log.

* To plot the goal weight in charts without the sloping diet plan, set the initial and goal weights to the same value and the start date before the first month in the log.

Exercise Ladder Reference

Exercise ladder The Hacker's Diet includes an optional exercise program, organised as a ladder of 48 rungs representing ascending levels of physical fitness with two sets of exercises: an introductory series for the first 16 rungs, and a more demanding "lifetime" set for the balance of the program. Anybody not on the verge of physical collapse should be able to complete the first rung, while the rungs at the top of the table will prove challenging to Olympic athletes and deep-end fitness nuts. You progress at whatever pace suits you, toward whichever level of fitness you wish to achieve and maintain.

The Palm tools include a concise exercise ladder table. There's no need to keep a print-out of the table from the book, and you'll always have the table at hand even when you're on the road. No description of the exercises is given; if you're doing them every day, as recommended, the column headings will suffice. For more details, consult the exercise chapter in the book.

You can display the exercise ladder by choosing it from the View menu of the Monthly Log form or by writing its shortcut letter "E", but it's easier by far to just tap the title of the "Rung" column in the Monthly Log form, which brings you directly here. Once the exercise ladder is displayed, scroll to your current rung and tap it--it changes to bold type and when you return to the form it will automatically be scrolled into view.

After you've completed the exercises for a given a day, tap the "Record" button; it will enter the current rung, shown in bold, into the "Rung" field in today's log entry and take you back to the Monthly Log form with today scrolled into view. The "Today" button returns you to the Monthly Log item for the current date. The "Chart" button shows a weight, trend, and exercise chart along with a trend analysis for the month. The "Trend" button displays longer-term trend analyses.

Year View

Year View form The Monthly Log and Chart forms contain a "Year" button which brings you here. This form shows a calendar of months in the year of the log or chart you were viewing. Months for which a log exists are shown in bold face; those with no log in normal type. Tapping on any box with a bold face month displays the log for that month. The navigation buttons to the left and right of the year at the top of the form take you to the previous and next year in the database, respectively. If this is the first or last year in the database, the corresponding navigation button will not be shown.

The "Today" button returns you to the Monthly Log item for the current date; the "Years" button displays the Year List form.

* To enter historical data for months in the past not present in the database, navigate to the year and tap the month you wish to create (which will be shown in normal type, as it is not yet in the database). An alert pops up which asks you whether you wish to create a new blank log for the month you tapped; choosing "Yes" creates the log and displays it in the Monthly Log form.

Year List

Year List form If you don't feel like scrolling through the years with the navigation buttons in the Year View form, tap the "Years" button and this form will present you with a list box showing every year for which a monthly log exists. A scroll bar is shown if necessary. Tap on a year to show its Year View.

To view a list of each and every monthly log in the database, tap the "Months" button. The "Trend" button displays the Trend Analysis form; the "Today" button returns you to the Monthly Log showing today's date.

Month List

Month List form This form shows the contents of the monthly log database at the lowest level--the month and year of every log in the database. The first month of each year is left-indented to make year boundaries more evident when scrolling. Scroll to the month you wish to view, tap on its entry in the list box, and its Monthly Log will appear. The "Years" button takes you back to the Year List which shows years for which logs exist. The "Trend" button displays the Trend Analysis form; the "Today" button returns you to the Monthly Log showing today's date.

Special menu in month list form The trend at the start of a month depends upon the trend at the end of the preceding month, and so on all the way back to the first month in the database. Because trend computation is a computationally intensive task for a handheld platform, the Eat Watch application stores the trend carried forward from the previous month with the log data for each month, avoiding the need to compute the trend for previous months except in unusual situations (for example, if you import a CSV file containing data for a month in the past, or enter or modify data for a prior month). This is all handled automatically.

These stored trend values are "fragile" in the sense that if a hardware or software error should manage to clobber the trend, it will result in incorrect trend and variance computation for all entries for the month, and there's no direct way to enter the correct trend carry forward to replace the bad value. To guard against such an eventuality, Eat Watch provides the ability to completely recompute all trends from the fundamental log entries. To perform this, drop down the "Special" menu (available only on the Month List form) and tap "Recompute Trend". The title of the form changes to "Recomputing Trend - Wait" while the computation is in progress, then returns to the normal "Monthly Logs" title when it is complete. This recomputation can take a while--a minute or more for a decade's worth of logs. You'll probably never need to use this feature, but it's there just in case.

Setting Preferences

Preferences form Edit menu on monthly log form The Preferences form allows you choose among various options as to how you'd like log items stored and shown. To display this form, press the Menu button while the Monthly Log form is displayed (the default when you launch the Eat Watch application), then drop down the "Edit" menu and tap "Preferences". The preferences you can express are as follows:

Private Log Data
Weight and exercise log data will be marked as "private". Private records are not shown when the Security application has been used to hide private records, optionally with a password. Check this if you're concerned about your weight and exercise history falling into the hands of evil space aliens from planet Zorgon.

Protect Log Entries
It's easy to accidentally tap in the wrong field and wreck an existing log entry, requiring one to tediously re-enter it. If this box is checked (as it is by default), any tap in a non-blank Weight, Rung, or Comment field in the Monthly Log field is ignored, as are taps in dates after the present (no "precognitive weigh-ins"). If you need to change a prior entry (for example, you discover you mis-transcribed it from a paper log), uncheck this box, fix it, then (to be safe) re-activate protection.

Use Colour
Use Colour Use Colour If the handheld has a colour display, variances in Monthly Log entries are, by default, colour coded: red for positive, green for negative, and Monthly and Historical
Use Colour charts use colour to distinguish the various elements. If you prefer monochrome, uncheck the "Use Colour" box in the Preferences form. This item appears only on devices with colour displays.

Log Unit
This item selects the unit of weight in which monthly logs are kept. Set it to the unit you use most frequently. You're free to change the log unit at any time, but the change only affects logs created subsequent to the change. Existing logs remain in the unit in effect at the time of their creation.

Display Unit
Regardless of the log unit, you can display weight in the Monthly Log, Chart, and Trend Analysis forms in any of the available units. Changing the Display Unit does not convert the log to that unit, so you may change it as often as you wish without fear of losing precision. When the Display Unit differs from the Log Unit, be sure to enter weight in the Monthly Log form in the Display Unit--it wouldn't make sense to write a number in kilograms at the end of a table displayed in pounds! Your entry is stored, however, in the log unit. Since two decimal places are used when storing weight, the conversion entails negligible loss of precision.

Energy Unit
European food label In Europe, the energy content of food is often given in kilojoules, the SI unit of energy, instead of (kilogram) calories; one kilogram calorie is equal to about 4.18 kilojoules. If you're used to thinking in kilojoules instead of calories, set the energy unit accordingly. When the energy unit is set to kilojoules (abbreviated "kJ"), energy balance values in the Monthly Log, Chart, Trend Analysis, and Diet Calculator will use that unit. (When a kJ value is entered in the diet calculator, it will be rounded to the nearest integral calorie equivalent.) Changing the energy unit only affects how food values are displayed in the various forms--you may change it as frequently as you wish without loss of precision in the database.

Finding Items by Comment

Find screen The Eat Watch application supports the Palm OS global find mechanism, searching the comment field of log entries and responding with links to logs which contain the search target. If you use the comments field to note travel destinations, you can quickly answer such questions as "When was I in Paris?" as the user here has done. Tapping on the "September 1999" item displays that month's log, scrolled so the first day whose comment included the text "paris" is visible.

If you've marked log data private in the Preferences form, Find will search Eat Watch logs only if private records are not marked hidden by the Security application.

Importing CSV Files

CSV Import form If you've been keeping Hacker's Diet logs in Excel or another spreadsheet or database package, you may want to transfer your existing logs to the handheld so you'll always have them at hand. (Logs on the handheld are stored in a highly compressed form; unless you enter a lot of long comments, a decade's worth of logs consumes less than 20 Kb of memory on the Palm.) To do this, save the logs you wish to transfer to the handheld in Comma Separated Value (.csv) format. If you're using a different program to keep your logs, be careful the columns in the CSV file are the same as those used by the Excel macros. Only the Date, Weight, and Rung columns are transferred to the handheld--the other fields are recomputed as required. Following the convention of the Excel macros, comments appear as non-numeric entries in the Weight column; it isn't possible to attach a comment to a day for which a weight is entered. (This restriction is lifted in the Palm application, which provides a separate comment field.)

Let's assume you've exported your Excel log for the year 1997 into a file named weight97.csv. Now you need to embed that file in a Palm database so the Eat Watch application can digest it. The PDBMake desktop utility, available for downloading from this site, allows you accomplish this. From the command line, navigate to the directory in which you've placed the .csv file and enter the command:

    pdbmake -a -c HkDt -t Wcsv -n weight97 weight97.csv

If your .csv file has a name other than weight97.csv, enter that name after the -n option and as the input file name which follows it. Be careful to enter the -c and -t option arguments exactly as shown above including upper and lower case (Palm developers will recognise these as the creator code and database type, which an application uses to identify files belonging to it.)

If all goes well, you'll now have a weight97.pdb (or whatever you called it) in the directory containing the original CSV file which consists of the contents of the CSV file embedded line by line as successive records in the database. (If you'd like to look inside this or other Palm database and application files, download a copy of the Palmdump desktop utility from this site.)

Now use your desktop installer utility to copy the .pdb file to the Palm desktop install directory and HotSync your handheld to the desktop. This will transfer the database containing the CSV file to the handheld. When the HotSync is complete, launch the Eat Watch application. Whenever launched, it checks for CSV files transferred since it was last run. If one or more are present, the CSV Import form is automatically displayed. This form reads each CSV file in succession, adding valid entries to the handheld log database. A progress display shows the CSV file currently being imported (the name you gave after the -n option when you ran PDBmake) and the line in the file. After completing each CSV file, it is deleted from memory in the handheld. You can import as many different CSV files as you like in one session as long as there is enough free memory on the handheld to store them and you remember to give each file a different name with the PDBmake -n option so they don't delete one another when they're installed. When all CSV files have been imported, the "Cancel" button changes to "Done" which, when pressed, takes you to the Year List form from which you can navigate to examine the logs you've just imported.

New-format CSV

In addition to assimilating CSV files in the rather eccentric form used by the Excel macros, the CSV import mechanism also accepts the new CSV log representation introduced with the HDread desktop utility described later in this document. If you wish to transfer logs from a different application, it's easier to convert them to this more straightforward format instead of trying to mimic Excel. Each entry in a new format log consists of the following comma-separated fields:
Complete date of the entry, which may be expressed in any of the following forms, using July 20th, 1999 for the examples:
Format Example(s)
ISO 8601 1999-07-20
European 20.07.1999 20.7.99
North America 7/20/1999 07/20/99

Leading zeroes may be supplied or omitted in all formats. Two-digit year numbers 70 or greater are interpreted as 1970-1999 while those 69 or less denote 2000-2069. Any line in the CSV file which does not begin with a valid date in one of these formats is silently ignored. This allows processing CSV files which contain headings or other material in addition to log entries. Dates need not be in ascending order, but CSV importing is faster if all the entries for a given month appear as a block of consecutive lines.

Daily weight, as a decimal number. Decimal places beyond two are truncated (not rounded). If no weight was recorded for the day, this field may be blank. Weights are stored in the log using the Log unit you've chosen in the Preferences. If you need to import a log recorded in different units, you must convert it to the log unit on the handheld before importing it.

Exercise Rung
Rung in the exercise program completed for this day. This is a whole number between 1 and 48 (this is validated and the log entry ignored if outside this range--you can't use this field as an arbitrary number), or blank if you're not using the program or didn't exercise that day.

This field sets the "Flag" checkbox in the Monthly Log, which you can use to record any significant daily yes or no item (for example, did you work out at the gym that day, or have pizza for lunch?). If the field is blank or the first character is "0" the flag is not set; any other value sets it.

This field supplies arbitrary text to appear in the comment field in the day's Monthly Log entry. Comments are limited to 80 characters, with longer comments in the CSV file truncated to this length. If the comment contains a comma, you must enclose the comment field in double quotes ("). To include a quote within a quoted comment, use two adjacent quotes. Within a quoted comment you can use "\" followed by three octal digits to insert an arbitrary character or "\\" to include a backslash itself.

- The "Cancel" button doesn't work, and I haven't the slightest idea why not. I've tried all kinds of twiddling with the event queue to no avail. So unless you want to muck around in the source code and figure some way to fix it, you'll just have to be patient and let every CSV import run to completion whether you like it or not. Fortunately, CSV import is something you'll normally only do once when you first start using the Palm application, and then only if you've been keeping logs with a different application.

Desktop Utilities

An essential part of the formula responsible for the success of the PalmPilot when so many other similar gizmos have failed was the comprehension that a handheld hardly ever exists in isolation as an individual's sole computing device. I mean, nobody's likely to write the Great American Novel (or that of any other country) character-by-character in the Graffiti box on a Palm! No, one of the many things the Palm designers got right was the necessity of tight integration between desktop and handheld platforms and applications, and the HotSync mechanism to achieve that goal.

If you view your weight and exercise log as something worth keeping as a memoir of your own progress toward, and maintenance of, your personal weight and fitness goals, you'll feel better knowing there's a backup on your desktop computer and its own backup media every time Rover looks enviously at your Palm and drools a little when you're paying attention to it rather than petting (or better yet, feeding) your Best Friend.

Automatic Backup to Desktop

The Eat Watch application for the Palm automatically and unconditionally marks the database containing your log entries for "Backup". Every time you HotSync it will be copied to the Backup directory on your desktop machine if it's been modified since the last HotSync. (This might appear, at first glance, to be inefficient since the entire database is backed up even if you've only changed a few items since the last sync. In practice, log databases are so compact that it's just as fast to copy the whole thing, even if you have decades of logs on the handheld, as to launch a conduit application to sort through the differences and transfer only modified records. Further, conduits are platform-specific; by using database backup, desktop tools which work on any vaguely POSIX-compatible C implementation can be supplied.)

After performing a HotSync with the Eat Watch application installed, you'll find a binary copy of your log database on the handheld as a Months-HkDt.PDB file in the Backup directory of the Palm user name assigned to the handheld. For a typical installation on a Windows machine for user "Bugbert", the file might be found at:


When Rover is caught, flagrante delicto, with the shattered remains of your Palm and fixes you with a slobbery grin and blames it on the cat, it's nice to know you've only lost any log entries you made since the last HotSync; you need only re-install the Eat Watch application and your backed-up database and you're back in business. Of course, bad things befall desktop computers as well, so be sure you regularly back up that machine to removable media (ideally kept off-site periodically, in case of catastrophe such as fire or a bad asteroid day) so you can restore it should the need arise. (Machines at Fourmilab are backed up nightly to DLT tape on a backup server, with full dumps of each performed every Friday which are stored off-site and kept forever. All Web site content is backed up nightly to two local backup servers configured to take over should the principal Web server fail, and across the Net to a mirror site located in the other hemisphere as a hedge against Really Bad Days. "Paranoid!", you exclaim. Damn straight, and I always appreciate compliments--got any more?)

Now that there's a copy of your Eat Watch log database on the desktop, updated every time you HotSync, it almost cries out, read me, read me! on to discover how to use HDread to export data from the backup of your handheld's log database in a variety of formats, including illustrated log and chart documents you can view with any graphical Web browser. HDread can also export handheld databases in comma-separated value (CSV) format, which most spreadsheets and database programs can read. You can dump the CSV output from HDread with the csvread utility, whose source code includes everything you need to build your own analysis programs to process the Eat Watch databases.


HDread is an application which runs on any platform with a standard C language environment that reads Eat Watch databases transferred from the handheld and exports them in a variety of formats, including illustrated HTML documents which can be viewed with any graphical Web browser.

Documentation for HDread follows, in Unix manual page style.


HDread - export Palm Eat Watch database to desktop database files


hdread [ -c -d -h -j -u -v -x ] [ -o ocsvfile ] [ -p hrfile ] infile


HDread exports Eat Watch Palm databases (Months-HkDt.pdb) files in a variety of formats, including illustrated HTML which can be viewed with any graphical Web browser.


Export the database as new-format CSV suitable for importing into spreadsheet and database programs. A separate CSV file is created for each month in the database. For example, the CSV file for July 1999 would be named 1999-07.csv. View sample CSV output.

When HDread is run, it updates a database cache in the file eatwatch.dbc which records the time and date of the last modification to each of the files output. If, in a subsequent run, the database from which the output file was generated has not been modified, HDread skips re-generating it, saving time in the normal case where only the current month's log changes from run to run. If, for some reason (most likely, if you're modifying HDread and a test version has generated bad output) you wish to regenerate all output files, you can delete eatwatch.dbc before running the program or, easier, specify the -d option which causes the cache file to be ignored. After you run HDread, a new cache file will be created, synchronised with the database it processed.

Output the log as illustrated HTML documents. For each month in the log an HTML format log including a GIF image chart of weight and exercise is generated, all linked to a master calendar.html document and to each other. All files are created in the current directory when HDread was run. The HTML logs and charts may be viewed by any graphical Web browser with a "file:" URL pointing to the location of the calendar.html document. If you install the HTML log documents in a different directory, be sure to copy the .gif navigation button and chart legend images supplied in the HDread archive to that directory. View sample HTML output.

Display the energy balance in the the monthly chart captions in kilojoules (kJ) instead of the default of kilogram calories.

-o ocsvfile
Output the log as a CSV database in the format used by the Excel macros. The CSV file contains all months in the database; if you wish to transfer the data back to Excel, you'll have to cut and paste individual months' data into yearly log spreadsheets. This may come in handy if, for some bizarre reason, you decide to regress from the Palm platform to Windows. (Consider the Nightmare Scenario: Microsoft buys Palm and the drones they install to assimilate the place embrace Windows CE as the Wave of the Future.) If ocsvfile is a minus sign, "-", Excel CSV output is written to standard output. View sample Excel CSV output.

-p prfile
Print the log as a primate-readable text file in prfile. This is primarily intended for debugging, but may be easier to read in some programming languages than a CSV file. If prfile is a minus sign, "-", the primate-readable log is written to standard output. View sample text log output.

Print how-to-call information.

Verbose: PDB record header information is included in the output file produced by the -p option. This option has no effect on other output formats.

Include a hexadecimal dump of each database record in the -p option output file. This option implies the -v option.


If YYYY is the year and MM the month, CSV files written by the -c option are named YYYY-MM.csv. HTML output from the -h option generates log and chart files named YYYY-MM.html and YYYY-MM.gif, respectively, which are linked to an index file named calendar.html. All -c and -h option output files are created in the current directory.


Some folks will undoubtedly natter that a stand-alone, command-line conversion program is a dinosaur in the age of conduit plug-ins and graphical user interfaces. But consider, you already have a powerful graphical interface tool on your computer--the very Web browser you're using to read this document! By exporting log data as HTML, with accompanying charts in GIF images, HDread allows you to use your browser, with which you're already familiar, to view the log data on the desktop, instead of having to learn another special-purpose application. Further, since HDread is written in portable C, it can be made to run on almost any computer and operating system--even those for which Palm Computing provides no conduit support. As long as you can physically transfer the Months-HkDt.PDB database to your computer (tools for accomplishing this task exist for most variants of Unix and other widely-used operating systems), HDread and a Web browser are all you need on the desktop side.

Character codes greater than 127 in comments are output assuming the host system displays them in the ISO-8859 or (equivalently) Unicode character set. If you're running on a system with a different native character set, for example a DOS window in Windows using the original DOS "code page", these characters will display as whatever the system's code page defines them to be, not the standard values. Further, fonts on the Palm are not completely compliant with ISO or Unicode, so some characters may display with different glyphs than they do on the handheld.

Source code assumes an "rb" mode specification to fopen will open a file 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 am aware of no platform on which this would create a problem, but you never know.

The name is easily mispronounced. It's intended to be read as "H. D. Read" but some folks pronounce it as "H. Dread". Johnny, you're too bad.


palmdump(1), fopen(3)


csvread is an application which runs on almost any platform with a standard C language environment which reads Eat Watch databases exported in comma-separated value (CSV) form. Such databases are exported by HDread, and are compatible with most spreadsheet and database applications. While csvread is usable as a stand-alone application, its primary raison d'être is as a point of departure and model for your own applications which process Eat Watch data exported as CSV files.

Documentation for csvread follows, in Unix manual page style.


csvread - print Palm Eat Watch database exported in CSV format


csvread [ -u ] [ ofile ]


csvread reads CSV files containing data exported from Eat Watch databases by HDread and prints them in a primate-readable format.


Print how-to-call information.


Output is written to the specified ofile. If no ofile is given, output is written to standard output.




fopen(3), HDread(1)

Downloading and Installation

The following links allow you to download the Eat Watch software for the Palm and the desktop utilities. Source code is available for both Palm and desktop programs.

Palm Software

Download the current version of the Palm Eat Watch utility with the following link:

Download Eat Watch 1.11 for PalmOS

Use any Zip utility to extract the contents of this archive, eatwatch.prc, a PalmOS executable resource file. Use your desktop Palm application installer to mark this file for installation on your handheld, then HotSync the handheld to the desktop, which will install the application on the handheld. (The precise details of this process vary from one desktop client to another--consult the documentation for the one you're using if you need additional information on how to install applications.)

Eat Watch Icon When you go back to the Application Launcher, you should see the Eat Watch icon shown to the right. If you don't see it, you may have to scroll it into view and/or switch to the "Unfiled" category into which new applications are placed. Tap the Eat Watch icon to launch the application. The first time it's launched, you'll see the Preferences form; use the list items to choose the weight unit in which you'd like to store and view your log entries (you should set both to the unit in which your scale at home uses--you can change the display unit when you travel to a region where a different unit is commonplace). When you tap OK, a blank log for the current month is shown with today's date scrolled into view; this is the view you'll see from now on when you launch Eat Watch. If you have existing logs kept with a different application, you can now use the CSV import facility to transfer them to your handheld.

Source Code

Palm developers who wish to modify the Eat Watch program or are simply curious to see how it was implemented are invited to download source code. The program was developed using CodeWarrior for Palm Computing and project definition files are included to build the program with Release 6 of that environment. I've included callback macros in the code with the intent that it can be built with the GCC cross-development tools for the Palm, but I've not yet tested whether it actually can be built with GCC. In the words of Kelvin R. Throop, "If you haven't tested it, it doesn't work.", so if you're using GCC, be prepared for some tweaking. In addition, the resource file containing the form, menu, etc. definitions is supplied in the binary format used by Constructor. In order to build with GCC you'll need to convert this file to an .rcp file which can be compiled by PilRC; this issue is discussed on page 38 of the O'Reilly Palm Programming book by Neil Rhodes and Julie McKeehan. A variety of tools exist to perform the required resource file conversion. As they come and go and their locations on the Web change, it's best to consult the Web resources for Palm developers for current information when the need arises.

Download Eat Watch 1.11 Source Code for PalmOS

Source code is supplied as a Zipped archive containing subdirectories. When you unzip, be sure to specify the option which preserves directory structure in the archive. Otherwise the directory tree will be flattened and none of the definition files included will work. You're welcome to use this source code in any way you like, but absolutely no support is provided; you're entirely on your own.

Desktop Software

The companion desktop utilities, HDread and csvread may be downloaded as ready-to-run binary executable files for a variety of hardware and software platforms, or as C source code you can build for your own environment and modify, if you wish.

Ready-to-Run Binaries

Ready-to-run binary executables for HDread and csvread may be downloaded for a variety of platforms using the links below. If you plan to make HTML logs, be sure to also download the HTML icon image archive and unpack it in the directory where you keep your HTML logs.


Windows 95/98/NT (WIN32)
Windows binaries are delivered in a Zipped archive containing the two .exe files.


All Unix binaries are supplied as Gzipped TAR archives; the operating system and compiler used to build them is identified in the comment. Each was built using the oldest operating system available for the platform; since Unix programs are almost always upward compatible (run on later versions) but not downward compatible (run on earlier versions) this maximises the number of operating system versions on which the binaries will run. Unix binaries have been statically linked wherever possible to avoid potential shared library incompatibilities. Static-linked binaries are, however, larger than those which use dynamic shared libraries; if disc space is a premium, you may prefer to download the source code and build a shared library version on your system.

Linux/Intel x86
Built on Red Hat Linux 5.1 (2.0.34 kernel) with GCC version, statically linked. This release was tested on that system and a second Linux system running Red Hat 6.0 GPL with kernel 2.2.5-15.

Sun Solaris/SPARC
Built on a Sun Ultra 2 workstation running Solaris 5.7 with Sun WorkShop C compiler version 4.2 (32 bit code), statically linked.

Built on an SGI (formerly Silicon Graphics) Indigo² (MIPS R4400 processor) using MIPSpro C compiler version 7.2.1. I don't have static library support installed on this system, so the binaries are dynamically linked. If they don't work on your SGI box, you'll have to rebuild from the source.

HTML Icon Images

If you use HDread to make HTML logs, you'll need to also download the following small archive containing GIF images of navigation icons and chart legends used in the HTML documents. Unpack the archive in the directory in which you place your HTML logs. If you don't download and install this archive, your HTML logs will show "broken image" icons. These files are included in the source code archive; if you build from source code you don't need to download the icons separately--just copy them from the source code directory to your HTML log directory.

Download HTML Log Icon Images

Source Code

If a binary release isn't available for your system, or you prefer to rebuild from source and/or modify the programs, you can download complete C source code for HDread and csvread from the following link.

Download Eat Watch Desktop Utilities Source Code

Source code is supplied as a Zipped archive without any subdirectories. Source files use the Unix end-of-line convention (line feed without carriage return); most DOS/Windows C compilers accept such files without problems, but if your compiler is picky you may have to convert them to DOS carriage return / line feed format. Unix users should examine the Makefile and set the C compiler and options suitably for their system. The Windows version was built using Monkey C: Microsoft Visual C 5.0 (with "service pack" 3 installed). The archive contains Monkey C "workspace" (.dsw) and "project" (.dsp) for this compiler. Microsoft being Microsoft, all bets are off if you use these files with a later version of the compiler. If you're using a different compiler, you'll have to create a make file or IDE project definition by hand--refer to the Unix Makefile for a list of which components are included in each program. You're welcome to use this source code in any way you like, but absolutely no support is provided; you're entirely on your own.

Back to The Hacker's Diet

Other Palm Computing resources at Fourmilab

Fourmilab Home Page

by John Walker
November, MMII