ADB: appointment book database format

latest update: 1999-05-24 9:31:22 CET
compiled by: g.gonter@ieee.org

Foreword

All information here is based on the careful examination of sample HP 200LX databases, especially ADB files which are used by the built-in appointment book application. This examination was done to find a way to exchange data with other application, thus enhancing the usability value of HP 200LX-class devices. Use this at your own risk! Comments and further examples are welcome.

DB records

The appointment book implements a number of application specific record types and interprets a few items differently than the generic database engine:

USER14

USER14, first occurance

In all my examples sofar, the first record had a payload of exactly 29 bytes.
OffsetTypeDescription
0x00Datehead date
0x01
0x02
0x03flags 1Raster
0x04flags 2Last View, raster
0x05flags 3signals
0x06  ???
0x07flags 4options for the date view
0x08flags 4options for the to-do view
0x09INTRaster: first date shown
0x0A
0x0BINTdates: duration in minutes
0x0C
0x0DINTdates: leadtime in minutes
0x0E
0x0FU22To-Do: default priority
0x10
0x11INT?? index ??
0x12
0x13INT?? index ??
0x14
0x15INTalways 3 ?
0x16

head date

The head date is the date that is stored as the current date.

flags 1: raster

Defines raster and defaults for new date entries
bitfunction
0Raster 
    value | function
        1 | 15 minutes
        2 | 30 minutes
        4 | 60 minutes
        8 | raster off
1
2
3
4weeks start on Monday
5weeks start on Sunday
6new date entries set alarm (Meldung an)
7show date in month view
flags 2: last view Defines defaults for new date, event, and to-do entries as well as last view shown.
bitfunction
0show date in week view
1show event in month view
2show event in week view
3carry-over of new to-do entries
4last view shown (bit field, values shifted 4 bits) 
    value | function
        0 | date
        1 | to-do
        2 | week
        3 | month
        4 | 6 months
5
6
7 

flags 3: signal

Bitfunction
0signal volume 
    value | volume
        1 | low
        2 | middle
        4 | loud
1
2
3signal off
4signal type 
    value | english | german
        1 | peep    | Piepton
        2 | trumpet | Trompete
        4 | bell    | Glocke
        8 | special | Spezial
5
6
7

flags 4: options

The option flags define the appearance of the date and event view (byte offset 0x07) and of the to-do view (byte offset 0x08):
Bitfunction
0show list with 
    value | combination
        0 | nothing
        1 | clock
        2 | calendar
        3 | (undefined)
1
2show next date
3show graphic bar
4 
5 
6 
7 

USER14, second occurance

This is very possibly a kind of view point table for the head date for the to-do list view and the date and event view.

The view point table consists of repeating blocks of date/number pairs in the format:
relative OffsetTypeDescription
0x00DateDate of Event or Date?
0x01
0x02
0x03Indexdata record index???
0x04
The dates seem to be always pointing to some date or event and not to to-do type entries. The last entry always contains date=1990-01-01 num=65535.

data fields

The usual data fields are also slightly different to regular GDB files, there are a number of application specific types and also overlapping fields which depend on the entry type:

format of data records

The format of the data records varies slightly depending on the entry type:
OffsetTypeVorhabenTermin/Event
0x00INTlength of record
0x01
0x02OffsetCategory
0x03
0x04OffsetLocation
0x05
0x06OffsetPointer to recurrence status descriptor block.
0x07
0x08NoteNumber of note
0x09
0x0AINTprevious record on same day
0x0B
0x0CINTnext record on same day
0x0D
0x0EBYTEBOOLEntry Type and Flags
0x0FDateBegin Date (U19)
0x10
0x11
0x12 Priority (U22) Begin Time (TIME)
0x13
0x14 Due Date (U20) #Consecutive Days (U23)
0x15
0x16 End Date (DATE) End Time (TIME)
0x17
0x18Leadtime (U24)
0x19
0x1AU18 recurrence type (RADIO_BUTTON *and* U18)
0x1BString/mod.Description
...
varStringCategory
...
varStringLocation
...
varBinaryRecurrence data
...
Notes: The category field is not used anywhere!

Entry Type and Flags

The type of an ADB entry can be determined by examining the upper 4 bits of the byte at offset 0x0E. The lower 4 bits are flags that have different meanings for the to-do list and schedule and event entries, respectively.

valuemodeEnglishDeutsch
0x01eventsAlarmMeldung aktiv
0x02to-doCompleted ToDoVorhaben erledigt
eventsShows in Month ViewMonatsansicht
0x04to-doCarry ForwardÜbertrag
eventsShows in Week ViewWochenansicht
0x10selView/To-DoAnsicht/Vorhaben
0x20selView/EventAnsicht/Ereignis
0x80selView/DateAnsicht/Termin

Check Boxes are mapped to check box fields

FeldnameAnsichtenfield nameview
Zeigt WochenplanWocheShows in Week ViewWeek
Zeigt MonatsplanMonatShows in Month ViewMonth

U20: date due (Faelligkeitsdatum)

valueEnglishGerman
0nonekeine
1at the same dayam selben Tag
2next dayam naechsten Tag
.........

U22: priority (Prioritaet)

defined fields

The following fields are defined in the ADB file with field definition records in the same way as in other GDB files. Due to the fact that they partially overlap and/or have application specific types, the are not all used or interpreted slightly different in the HP200LX::DB Perl module.
IDXTo-DoEventsTypeTTypeSizeFIDOffResFlgEnglishDeutsch
0XX2STRING200x1B00x00'Description''Beschreib.'
1XX19U19300x0F00x00'Start Date ''Beginndatum'
2 X7TIME200x1200x00'Start Time ''Beginnzeit'
3 X7TIME200x1600x00'End Time ''Endzeit '
4 X2STRING200x0400x20'Location ''Ort '
5 X23U23200x1400x00'#Consecutive Days''# aufein'folg. Tage'
6 X0BYTEBOOL100x0E10x00'Alarm''Meldung'
7 X24U24200x1800x00'Leadtime''Vorlauf'
8X 20U20200x1400x00'Due Date ''Fälligkeitstermin '
9X 8DATE300x1600x00'Completion Date''Abschlußdatum'
10X 22U22200x1200x00'Priority ''Priorität '
11X 0BYTEBOOL100x0E40x00'Carry Forward''Übertrag'
12XX10NOTE200x0800x00'Note''Notiz'
13XX18U18100x1A00x00'Repeat Status: ''Wiederholung: '
14 X0BYTEBOOL100x0E40x00'Shows in Week View''Zeigt Wochenplan'
15 X0BYTEBOOL100x0E20x00'Shows in Month View''Zeigt Monatsplan'
16  6CATEGORY200x0200x20'Category''Kategorie'
17mod.mod.9RADIO_BUTTON100x1A00x00'None ''Keine '
18  9RADIO_BUTTON100x1A10x00'Daily ''Täglich'
19  9RADIO_BUTTON100x1A20x00'Weekly ''Wöchentlich'
20  9RADIO_BUTTON100x1A30x00'Monthly''Monatlich'
21  9RADIO_BUTTON100x1A40x00'Yearly ''Jährlich'
22  9RADIO_BUTTON100x1A50x00'Custom ''Spezial '
23  0BYTEBOOL100x0E320x00'Event''Ereignis'
24  0BYTEBOOL100x0E1280x00'Appointment''Termin'
25  0BYTEBOOL100x0E160x00'ToDo''Vorhaben'
26  0BYTEBOOL100x0E20x00'Completed ToDo''Erledigtes Vorhaben'
Note: Category is not used anywhere!

undefined fields

These fields are not described by field definition records.
To-DoEventsTTypeSizeOffDescription
XXINT20x00record length
XXINT40x06recurrence data pointer
XXINT20x0Aprevious record on same day
XXINT20x0Cnext record on same day

Recurrence

Recurrence is a difficult matter to explain, especially when conflicting terminology is used and database items are used for different things. Until a better solution is found, I will try to stick to the terminology used in the vCalendar as closely as possibly.

Terminology Overview

Recurrence Class (HP-LX>
HP-LX specific definition of the recurrence rule. (english "Repeat Status", german "Wiederholung")
Recurrence Rule (vCalendar)
describes patterns of recurring events
Recurrence Status (vCalendar)
describes instances of recurring events, e.g. their completion
Recurrence Exception Rule (vCalendar)
describes patterns of exceptions to recurring events
Recurrence Exception (vCalendar)
singular exceptions
The ADB uses a data field of type U18 to describe the basice recurrence class which defines the recurrence rule. Remaining details about the recurrence rule, status and exceptions are lumped together into an variably sized binary block, "recurrence status".

U18: Recurrence Class (Repeat Factor, Wiederholung)

The recurrence factor (U18) points to the same positionas the radio button field so it must basically work like the the group data type. The display shows the names for the radio buttons.
BitValueEnglishGermanindicators
00x01noneKeinenone
10x02dailyTaeglichcycle
20x04weeklyWoechentlichcycle day
30x08monthlyMonatlichcycle day
40x16yearlyJaehrlichcycle day month{1}
50x32specialSpezialday month

Recurrence Status

This block is used for two different purposes and hence has different structures. In the first case, it appears in the main entry of a recurring entry, in the second case it appears in those entries which are already checked-off as completed. Checked-off entries appear as separate entries in the data base, the extension block is then used to point to the next and previous checked-off records and the main entry. Deleted entries are of course not stored as separate records in the ADB file.

The first 0x0A bytes of the recurrence status block have the same format in both cases:
OffsetTypeDescription
0x00INTcycle, values 1..99
0x01INTrecurrence indicator "days"
0x02
0x03INTrecurrence indicator "months"
0x04
0x05DateDuration: Begin
0x06
0x07
0x08DateDuration: End
0x09
0x0A
...UnionRecurrence Exceptions or check-off pointers

Notes:

monthly recurrence

Entries recurring every month allow specification of cycle and a days indicator.

yearly recurrence

Entries recurring every year allow specification of cycle, a days indicator, and a month idicator.

recurrence day indicator

The recurrence day indicator is encoded in a 16 bit integer. If bit 7 is not set, bits 0..6 represent the day number, otherwise the integer represents a bit field:
bitmaskrepresents
0x010x0001Monday
0x020x0002Tuesday
0x030x0004Wednesday
0x040x0008Thursday
0x050x0010Friday
0x060x0020Saturday
0x070x0040Sunday
0x080x0080Bitfield indicator
0x090x01001st day in month
0x0A0x02002nd day in month
0x0B0x04003rd day in month
0x0C0x08004th day in month
0x0D0x1000last day in month

Note: Apparently, the bit for the week day is not set unless the recurrence is defined as "special".
Examples:
0x1084
last Wed in month

recurrence month indicator

The recurrence month indicator is encoded in a 16 bit integer bit field. Bit 0 represents January, bit 12 represents december.

Recurrence Exception List

The recurrence exception list is a variable size block that follows the first part of the recurrence status record and contain the number of exceptions followed by this number of 4-byte exception description blocks:

OffsetTypeDescription
0x0BINTNumber of recurrence exception entries
...StructRecurrence Exception, appearing 0..n times
relative OffsetTypeDescription
0x00DateException Date
0x01
0x02
0x03INT?Exception Status

Exception status values 0x00 and 0x01 were observed sofar. 0x00 indicates that the item was deleted. 0x01 indicates that an recurring to-do item was checked-off. Checked-off entries are kept as unique records in the database, their recurrence status extension block is described below.

Checked-Off item pointers

Checked-off items have a fixed size data block containing pointers to the main entry and other checked-off items. The recurrence exception index is the number of the exception description in the main entry's recurrence exception list.

This is used to indicate that the entry at the given date was checked off at that day. This is not used at the main entry of a recurring entry.

OffsetTypeDescription
0x0BINTrecurrence exception index in the main entry
0x0CINTrecord index of previous checked-off item
0x0D
0x0EINTrecord index of next checked-off item
0x0F
0x10INTrecord index of main entry
0x11

References

GDB format
Description of the GDB file format, found on S.U.P.E.R.
adbio.c
C sources used for dumping and loading ADB files, found on S.U.P.E.R.
vCalendar
vCalendar - The Electronic Calendaring and Scheduling Exchange Format - Version 1.0
RFC 2445
Internet Calendaring and Scheduling Core Object Specification (iCalendar)