# ADB: appointment book database format

$Id: adb-format.html,v 1.6 2001/01/01 20:13:59 gonter Exp $ latest update: 1999-10-11 10:20:55 CET
compiled by: g.gonter@ieee.org

### Contents

- Foreword
- DB records
- USER14
  - USER14, first occurance
  - USER14, second occurance
- format of data records
- format of data fields
  - U18: Recurrence Class and States
  - U19:
  - U20: date due
  - U22:
  - U23:
  - U24:

### 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:

- there is no card definition record
- there are no viewpoint definitions
- the application specific record (USER14) is present twice and seems to contain some header information as well as a view point table table.

## USER14

There are two special components of the "USER14" which contain application specific data.

### USER14, first occurance

In all my examples sofar, the first record has a payload of exactly 29 bytes.

Offset | Type | Description
--- | --- | ---
0x00 | Date | head date
0x01
0x02
0x03 | flags 1 | Raster
0x04 | flags 2 | Last View, raster
0x05 | flags 3 | signals
0x06 |  | ???
0x07 | flags 4 | options for the date view
0x08 | flags 4 | options for the to-do view
0x09 | INT | Raster: first date shown
0x0A
0x0B | INT | dates: duration in minutes
0x0C
0x0D | INT | dates: leadtime in minutes
0x0E
0x0F | U22 | To-Do: default priority
0x10
0x11 | INT | ?? index ??
0x12
0x13 | INT | ?? index ??
0x14
0x15 | INT | always 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

bit | function
--- | ---
0 | Raster
        value | function
            1 | 15 minutes
            2 | 30 minutes
            4 | 60 minutes
            8 | raster off
1
2
3
4 | weeks start on Monday
5 | weeks start on Sunday
6 | new date entries set alarm (Meldung an)
7 | show date in month view

flags 2: last view Defines defaults for new date, event, and to-do entries as well as last view shown.

bit | function
--- | ---
0 | show date in week view
1 | show event in month view
2 | show event in week view
3 | carry-over of new to-do entries
4 | last 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

Bit | function
0 | signal volume
        value | volume
            1 | low
            2 | middle
            4 | loud
1
2
3 | signal off
4 | signal 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):

Bit | function
0 | show list with
        value | combination
            0 | nothing
            1 | clock
            2 | calendar
            3 | (undefined)
1
2 | show next date
3 | show 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 Offset | Type | Description
--- | --- | ---
0x00 | Date | Date of Event or Date?
0x01
0x02
0x03 | Index | data 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`.

## format of data records

The format of the data records varies slightly depending on the entry type:

Offset | Type | To-Do | Termin/Event
--- | --- | --- | ---
0x00 | INT | length of record
0x01
0x02 | Offset | Category
0x03
0x04 | Offset | (not used) | Location
0x05
0x06 | Offset | Pointer to recurrence status descriptor block.
0x07
0x08 | Note | Number of note
0x09
0x0A | INT | previous record on same day
0x0B
0x0C | INT | next record on same day
0x0D
0x0E | BYTEBOOL | Entry Type and Flags
0x0F | Date | Begin 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
0x18 | Leadtime (U24)
0x19
0x1A | U18 | recurrence class (RADIO_BUTTON *and* U18)
0x1B | String/mod. | Description
...
var | String | Category
...
var | String | Location
...
var | Binary | Recurrence data
...

## 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:

- Type 2: STRING (field name=Description; Feldname=Beschreibung)
  A string is usually implemented as a pointer to the real beginning of the string, however, in this case, the string actually begins always at the offset position (0x1B).
- Type 6: CATEGORY (field name=Category; Feldname=Kategorie)
  This looks like a perfectly normal category item, however, there does not seem to by any way to use this field. Was it defined for a future upgrade of the database application?

### 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.

value | mode | English | Deutsch
--- | --- | --- | ---
0x01 | events | Alarm | Meldung aktiv
0x02 | to-do | Completed ToDo | Vorhaben erledigt
events | Shows in Month View | Monatsansicht
0x04 | to-do | Carry Forward | Übertrag
events | Shows in Week View | Wochenansicht
0x10 | sel | View/To-Do | Ansicht/Vorhaben
0x20 | sel | View/Event | Ansicht/Ereignis
0x80 | sel | View/Date | Ansicht/Termin

Check Boxes are mapped to check box fields

Feldname | Ansichten | field name | view
--- | --- | --- | ---
Zeigt Wochenplan | Woche | Shows in Week View | Week
Zeigt Monatsplan | Monat | Shows in Month View | Month

### U18: Recurrence Class (Repeat Factor, Wiederholung)

1 Byte, references the radio-button field which is used to hold the entry type The recurrence factor (U18) points to the same positionas as the radio button field so it must basically work like the group data type. The display shows the names for the radio buttons.

Bit | Value | English | German | indicators
--- | --- | --- | --- | ---
0 | 0x01 | none | Keine | none
1 | 0x02 | daily | Taeglich | cycle
2 | 0x04 | weekly | Woechentlich | cycle day
3 | 0x08 | monthly | Monatlich | cycle day
4 | 0x16 | yearly | Jaehrlich | cycle day month{1}
5 | 0x32 | special | Spezial | day month

### U19: Begin Date (Beginndatum?)

Works like a DATE field

### U20: date due (Faelligkeitsdatum)

2 Bytes interpreted as INT; Semantics: maybe the number of days after the begin? latest possible date seems to be 2099-12-31

value | English | German
--- | --- | ---
0 | none | keine
1 | at the same day | am selben Tag
2 | next day | am naechsten Tag
... | ... | ...

### U22: priority (Prioritaet)

- This field is used by the appointment book application for to-do entries.
- data representation: 2 byte ASCII characters
  possible values: [ A-Z0-9]{2}
- For events and dates it has the value \xFF{2}

### U23: #Consecutive Days (# aufeinanderfolgende Tage)

### U24: Leadtime (Vorlauf)

## 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.

IDX | To-Do | Events | Type | TType | Size | FID | Off | Res | Flg | English | Deutsch
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
0 | X | X | 2 | STRING | 2 | 0 | 0x1B | 0 | 0x00 | 'Description' | 'Beschreib.'
1 | X | X | 19 | U19 | 3 | 0 | 0x0F | 0 | 0x00 | 'Start Date ' | 'Beginndatum'
2 |  | X | 7 | TIME | 2 | 0 | 0x12 | 0 | 0x00 | 'Start Time ' | 'Beginnzeit'
3 |  | X | 7 | TIME | 2 | 0 | 0x16 | 0 | 0x00 | 'End Time ' | 'Endzeit '
4 |  | X | 2 | STRING | 2 | 0 | 0x04 | 0 | 0x20 | 'Location ' | 'Ort '
5 |  | X | 23 | U23 | 2 | 0 | 0x14 | 0 | 0x00 | '#Consecutive Days' | '# aufein'folg. Tage'
6 |  | X | 0 | BYTEBOOL | 1 | 0 | 0x0E | 1 | 0x00 | 'Alarm' | 'Meldung'
7 |  | X | 24 | U24 | 2 | 0 | 0x18 | 0 | 0x00 | 'Leadtime' | 'Vorlauf'
8 | X |  | 20 | U20 | 2 | 0 | 0x14 | 0 | 0x00 | 'Due Date ' | 'Fälligkeitstermin '
9 | X |  | 8 | DATE | 3 | 0 | 0x16 | 0 | 0x00 | 'Completion Date' | 'Abschlußdatum'
10 | X |  | 22 | U22 | 2 | 0 | 0x12 | 0 | 0x00 | 'Priority ' | 'Priorität '
11 | X |  | 0 | BYTEBOOL | 1 | 0 | 0x0E | 4 | 0x00 | 'Carry Forward' | 'Übertrag'
12 | X | X | 10 | NOTE | 2 | 0 | 0x08 | 0 | 0x00 | 'Note' | 'Notiz'
13 | X | X | 18 | U18 | 1 | 0 | 0x1A | 0 | 0x00 | 'Repeat Status: ' | 'Wiederholung: '
14 |  | X | 0 | BYTEBOOL | 1 | 0 | 0x0E | 4 | 0x00 | 'Shows in Week View' | 'Zeigt Wochenplan'
15 |  | X | 0 | BYTEBOOL | 1 | 0 | 0x0E | 2 | 0x00 | 'Shows in Month View' | 'Zeigt Monatsplan'
16 |  |  | 6 | CATEGORY | 2 | 0 | 0x02 | 0 | 0x20 | 'Category' | 'Kategorie'
17 | mod. | mod. | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 0 | 0x00 | 'None ' | 'Keine '
18 |  |  | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 1 | 0x00 | 'Daily ' | 'Täglich'
19 |  |  | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 2 | 0x00 | 'Weekly ' | 'Wöchentlich'
20 |  |  | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 3 | 0x00 | 'Monthly' | 'Monatlich'
21 |  |  | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 4 | 0x00 | 'Yearly ' | 'Jährlich'
22 |  |  | 9 | RADIO_BUTTON | 1 | 0 | 0x1A | 5 | 0x00 | 'Custom ' | 'Spezial '
23 |  |  | 0 | BYTEBOOL | 1 | 0 | 0x0E | 32 | 0x00 | 'Event' | 'Ereignis'
24 |  |  | 0 | BYTEBOOL | 1 | 0 | 0x0E | 128 | 0x00 | 'Appointment' | 'Termin'
25 |  |  | 0 | BYTEBOOL | 1 | 0 | 0x0E | 16 | 0x00 | 'ToDo' | 'Vorhaben'
26 |  |  | 0 | BYTEBOOL | 1 | 0 | 0x0E | 2 | 0x00 | 'Completed ToDo' | 'Erledigtes Vorhaben'

Note: Category is not used anywhere!

## undefined fields

These fields are not described by field definition records.

To-Do | Events | TType | Size | Off | Description
--- | --- | --- | --- | --- | ---
X | X | INT | 2 | 0x00 | record length
X | X | INT | 4 | 0x06 | recurrence data pointer
X | X | INT | 2 | 0x0A | previous record on same day
X | X | INT | 2 | 0x0C | next 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".

### 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:

Offset | Type | Description
--- | --- | ---
0x00 | INT | cycle, values 1..99
0x01 | INT | recurrence indicator "days"
0x02
0x03 | INT | recurrence indicator "months"
0x04
0x05 | Date | Duration: Begin
0x06
0x07
0x08 | Date | Duration: End
0x09
0x0A
... | Union | Recurrence Exceptions or check-off pointers

Notes:

- daily recurrence does not allow a cycle specification ????
- Unexplained encoding method: boolean "Nach Datum" and "Nach Tagesstellung" with detailed specification.
- Also unexplained is the encoding of the "special" recurrence rule.

#### 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:

bit | mask | represents
--- | --- | ---
0x01 | 0x0001 | Monday
0x02 | 0x0002 | Tuesday
0x03 | 0x0004 | Wednesday
0x04 | 0x0008 | Thursday
0x05 | 0x0010 | Friday
0x06 | 0x0020 | Saturday
0x07 | 0x0040 | Sunday
0x08 | 0x0080 | Bitfield indicator
0x09 | 0x0100 | 1st day in month
0x0A | 0x0200 | 2nd day in month
0x0B | 0x0400 | 3rd day in month
0x0C | 0x0800 | 4th day in month
0x0D | 0x1000 | last 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:

Offset | Type | Description
--- | --- | ---
0x0B | INT | Number of recurrence exception entries
... | Struct | Recurrence Exception, appearing 0..n times

relative Offset | Type | Description
--- | --- | ---
0x00 | Date | Exception Date
0x01
0x02
0x03 | INT? | 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.

Offset | Type | Description
--- | --- | ---
0x0B | INT | recurrence exception index in the main entry
0x0C | INT | record index of previous checked-off item
0x0D
0x0E | INT | record index of next checked-off item
0x0F
0x10 | INT | record 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)