RunnersLog file format

This document describes my reverse engineering results. It is based on my personal findings and hasn’t been verified by anyone.

Acknowledgements

I’d like to thank Martin Rice for taking the time of answering my questions and his permission to release this document to the public.

About PDB files

Globally, a PDB(Palm DataBase) file consists of three parts:

  • a header, which is the same for each and every PDB file, containing general information about the file;
  • a list of record entries, containing the record offsets and the records’ category;
  • the actual records, which are application specific.

Palm, Inc. has done a great job with their documentation of their file formats. For more information about the internals of Palm “databases”, check out [1].

For the actual records, Palm doesn’t specify anything leaving much freedom to the application developers. In the next section, the record format of RunnersLog will be described in some detail allowing other people to take advantage of this format.

I must note that Martin Rice has warned me about (potential) minor changes in the record format in upcoming releases.

Record Format

The records of RunnersLog are optimized for size by bitpacking some fields into one single byte. Furthermore, because the PalmPilot uses a Motorola processor, several fields are in “Big Endian” (network order) format which generally means that the bytes appear in reverse order. The format of a single record of RunnersLog is displayed in the following table.

   name       | length  | description
   -----------+---------+--------------------------------------
   conditions | 1 byte  | bitpacked conditions, temperature and dist. unit
   month      | 1 byte  | month
   day        | 1 byte  | day
   year       | 1 byte  | # of years after 1904
   distance   | 2 bytes | distance ran
   hours      | 1 byte  | hours 
   minutes    | 1 byte  | minutes 
   seconds    | 1 byte  | seconds 
   place      |22 bytes | the place of event
   cmt.length | 1 byte  | length of the (optional) comment
   activity   | 1 byte  | bitpacked activity & weight unit
   heartrate  | 1 byte  | heart rate (bpm)
   weight     | 1 byte  | weight minus 20 in kilogram
   unknown    | 1 byte  | ? (always zero) / used for weight unit
   equipment  | 2 bytes | used equipment (0=none)
   event      | 2 bytes | event type
   custom     | 6 bytes | custom field
   comment    | ? bytes | comment
   
   Table - RunnersLog record format

In the following subsections, each field is described in more detail.

Conditions

This bitpacked field contains the following information:

   bit:  8 | 7 6 5 | 4 3 | 2 | 1
        ---+-------+-----+---+---
         x | a a a | b b | c | x 

In which:

  x = unused
  a = the weather condition, which could be:
          0 = ``clear''
	  1 = ``cloudy''
	  2 = ``rainy''
	  3 = ``snowy''
	  4 = ``foggy''
	  5 = ``indoor''
	  6 = ``humid''
	  7 = ``windy''
  b = the temperature, which could be:
          0 = ``hot''
	  1 = ``warm''
	  2 = ``cool''
	  3 = ``cold''
  c = the unit of the distance
          0 = the distance is entered in ``miles''
	  1 = the distance is entered in ``kilometers'' 

Month, day & year

These three fields contain the date for which the entry was made. Both the month and day field are literal values. The year field is a little different: it is presented as the number of years after 1 January 1904 (= the first epoch of the PalmPilot).

Distance

The distance you’ve ran/walked/biked/whatever. The unit of this field is bitpacked in the “conditions” field. This 16 bit value is in network order!

Hours, minutes and seconds

The literal time values of your entry.

Place

The place in which the activity did occur. Literal ASCII value, zero-terminated.

Cmt.length

The length of the “comment” field.

Activity

This bitpacked field contains: the activity index-number and wheter the weight you’ve entered is in kilogramm or in pounds.

   bit:  8 7 6 | 5 | 4 3 2 1
        -------+---+--------
	 x x x | a | b b b b

In which:

  x = unused
  a = the ``weight unit'':
          0 = the weigth entered is in ``lbs''
          1 = the weigth entered is in ``kg''
  b = the ``activity index number'', with only one (1) constant value:
          0 = ``Run''
	  1..15 = see below.

All other values can be different, if you changed them in RunnersLog, but by default they are:

  1 = Hike/Walk
  2 = Bike
  3 = Other

The precise values can be found by parsing the application information block of the PDB file, see [1].

Heartrate

The literal rate entered in BPM.

Weight

The weight you’ve entered _minus 20_! The unit in which this field was entered can be found in the “activity” field.

Unknown

This byte is found to be always zero… If anyone has more information about this byte, please let me know!

Equipment

The index number of the equipment you’ve used. A value of zero (0) means “None”. All other values depend on the ones you’ve entered. These can be found in the application information block, see [1]. This 16 bit value is in network order!

Event

The index number of the exact event you’ve entered. A value of zero (0) means “None”. All other values depend on the ones you’ve entered. Again, these can be found in the application information block, see [1]. This 16 bit value is in network order!

Custom

What value does the “custom” field have? The name of the custom field can be found in the application information block, see [1].

Comment

This ASCII string contains the comment of the entry. Its length is described by the “cmt.length” field. NOTE: this string is _not_ zero terminated!

Application Information Block

In some of the described fields above, a reference is made to the application information block. This is a chunk of data containing some information about the categories and some program specific information. More information about this, see [1].

The “program specific” data contain all literal values of the “events”, “activities” and “equipment”. The name of the “custom” field can also be found in this block.

References

  1. http://www.palmos.com/dev/support/docs/fileformats/FileFormatsTOC.html (link dead).