AGN:
------------------------------------------------------------
               Series 3 Agenda file format

Agenda field structure

   Integer:    DayNumber
   Integer:    Duration
   Integer:    Time
   Integer:    AlarmTime
   String:     Text


Timed and Untimed items

-  DayNumber is the number of days since 1/1/1900 (=day
   0). The first legal day is 1/1/1980, the last legal
   day is 31/12/2049.

-  Duration, Time, and AlarmTime are all stored in
   minutes.

-  The MSB of Time (i.e. 8000 Hex) is a flag that
   indicates whether the item is Timed or Untimed. If the
   MSB is set then the item is Untimed, if its clear then
   the item is Timed.

-  To extract the time from the Time field it must be
   ANDed with 7fff Hex to remove the MSB (i.e. Timed and
   Untimed indicator).

-  The LSB of Duration (i.e. 1 Hex) is a flag that
   indicates whether the item has an alarm attached. If
   the LSB is set then no alarm is attached, if its clear
   then an alarm is attached.

-  To extract the duration from the Duration field,
   divide by 2 (thus removing the LSB and shifting down
   the duration).

-  If the item is untimed then the Time field contains
   the day note slot number i.e. 1 to n and its MSB must
   be set (i.e. OR in 8000 Hex). The Duration field
   contains zero if an alarm is attached or one if no
   alarm is attached.

-  The end time of a timed item i.e. Time+Duration, must
   be less than 1440 (24*60) minutes.

-  For timed items the AlarmTime is an alarm pre time and
   is calculated as follows:

   Pre time to Agenda internal alarm format:

          (23*60+59) + Alarm pre time - Time

   Agenda internal alarm format to pre time:

          Time - (23*60+59) + AlarmTime

-  For untimed items the AlarmTime is calculated as
   follows:

   Pre time to Agenda internal alarm format:

          (Days previous * (24*60)) - ((23*60+59) - Alarm time)

   Agenda internal alarm format to days previous:

          AlarmTime / (24*60)

   Agenda internal alarm format to alarm time:

          (23*60+59) - (AlarmTime modulus (24*60))

-  If the item does not have an alarm the AlarmTime field
   should contain -1.

-  The Text field is stored as a leading byte count
   string and its length must be less than 64 characters.


ToDo items

-  ToDo items have a DayNumber of 65535 (ffff Hex), and
   must be stored as timed items and so the MSB of the
   Time field must be clear.

-  The Time field contains the item priority i.e. 1 to 9.

-  The Duration field contains a secondary key 0 to n,
   which orders the ToDo items within priority.

-  ToDo items cannot have alarms attached.



Repeat items

-  Timed and Untimed repeat items are stored in exactly
   the same way as normal timed and untimed items, except
   that they have a DayNumber of 65534 (fffe Hex).

-  The specific repeat details are stored at the end of
   the Text field and have the following format:

   Byte:      Type
   Byte:      Interval
   Integer:   StartDayNumber
   Integer:   EndDayNumber

-  The Type field can take the following values:

   Repeat Yearly                = 0
   Repeat Monthly By Date       = 1
   Repeat Monthly By Day        = 2
   Repeat Weekly                = 3
   Repeat Daily                 = 4
   Repeat Workdays              = 5


-  The StartDayNumber and EndDayNumber are stored as the
   number of days since 1/1/1900 (=day 0).

-  Setting the EndDayNumber field to zero will mean the
   item will repeat forever.
------------------------------------------------------------------

SERIES 3A AGENDA FILE FORMAT








Introduction

Series 3a Agenda files are binary files containing typed
variable length records. They use the same basic file and
record structure as DBF files, but the file signature and
internal record structure are NOT the same.



Basic structure of Agenda files

The basic file structure for Agenda files is as follows:

  <standard header>  Used to identify the file type and the
                     version of the file structure.

  <extended header>  For future use, currently omitted.

  <data records>     The main body of the file, containing
                     entries and preferences.


The standard header

The standard header is present at the start of all Agenda
files and is always 32 bytes long.

  AGD_SIG_SIZE 16
  AGD_SPARE_SIZE 12

  typedef struct
      {
      UBYTE sig[AGD_SIG_SIZE];
      UWORD version;
      UWORD hSize;
      UBYTE spare[AGD_SPARE_SIZE];
      } AGD_FILE_HEADER;

The first 16 bytes of the file are always the zero
terminated string AgendaFileType*. This is used to identify
the file as an Agenda file.

The two byte parameter version at file offset 0x100f should
be interpreted as a hexadecimal word that gives the version
of the file format. This is currently always 0x100F. The
most significant nibble (the version number is in the format
described in the General System Services chapter of the Plib
Reference manual) is the major version number and any change
in this indicates that the file format may not be backwards
compatible.

The two byte parameter hSize gives the combined size of the
standard and extended header. This effectively gives the
file offset of the first data record within the file.
Currently this is always 0x0020.

The array spare should not be used and is reserved for
future use.


The extended header

At present this is never used and is reserved for future
expansion.


The data records

As in DBF files all data is stored as variable length, typed
records, with the type and length combined into a single
word (two bytes). The most significant nibble of the word
gives the record type. The type determines how the contents
of the record are to be interpreted. The remainder of the
word gives the length of the data that follows. This file
structure is designed to be flash friendly in that deleted
records are not normally removed from the file but are
marked with record type 0 which can be done in place.

This structure allows 16 record types 0x0 to 0xf, each of
which are allowed to be up to 0xffe (4094) bytes long.
Although a record length of 0xfff is not explicitly illegal
it is not used.



Record Types

There are sixteen record types as follows.

  Type         Record

  0            Deleted

  1            Appointments (timed day entries)

  2            Day notes (un-timed day entries)

  3            Anniversaries

  4            To-do entries

  5            Repeat records

  6            Anonymous data

  7            Reserved

  8            Reserved

  9            To-do list information

  10           Descriptive records 1

  11           Descriptive records 2

  12           Descriptive records 3

  13           Descriptive records 4

  14           Descriptive records 5

  15           Illegal (used to mark write failure)

Currently record types 6, 7 & 8 are never generated by the
Series 3a Agenda.

A number of the records contain day numbers and times.
Unless stated otherwise all dates are given as a daynum. A
daynum is the number of days from 1 Jan. 1970. For technical
reasons dates before 1 Jan. 1980 (daynum 3652) or after 31
Dec. 2049 (daynum 29219) are ignored by the Agenda and where
appropriate will be 'clipped' to one or other of these dates
(for example a repeating entry that starts on 10 June 1970
will have its start date 'clipped' to 1 Jan. 1980).



Type 0: deleted record.

As for DBF files, deleted records are not normally removed
from the file but have their record type changed to type 0.
As any of the above record types may be converted to a type
0 record, there is nothing that can usefully be said about
the contents of such a record (indeed the record may not
even have been a valid Agenda record before it was deleted).
Records of this type should be ignored except to calculate
the amount of space that would be freed by compressing the
file.

There may be any number of such records in the file.



Types 1 to 4: entry records.

Records of type 1 to 4 contain details of individual Agenda
entries. Each has the same conceptual structure as follows:

  <Entry details      This is dependent on the entry type.
  field>

  <Title field>       Obligatory, variable length field
                      containing the text of the entry.

  <Alarm field>       Optional, fixed length field
                      containing alarm time and sound.

  <Memo field>        Optional variable length field
                      containing any memo for the entry.

The record type is used to determine the length and meaning
of the first field. Although these have some similarities
all four are individually described in details below.


Entry details field

This field contains most of the non-textual information
describing when an entry occurs, what other fields it has
and various bits of type specific information, such as the
duration for timed appointments.


Type 1 (timed day entry/appointment)

A type 1 record stores details of entries that occur at a
specific time on a specific day. In the Series 3a Agenda
these are called timed day entries.

The details field for a timed day entry consists of eight
bytes structured as follows:

  UWORD day;
  UWORD time;
  UBYTE attr;
  UBYTE code;
  UWORD dur;

day            is the daynum of the day on which the entry
               appears.

time           is the time of the start of the appointment
               in minutes from midnight.

attr           is a byte containing flags for attributes the
               entry may or may not have (see below).

code           is the ASCII character code for the symbol
               that is to be associated with the entry when
               it is visible in the Year view. Values less
               than 32 are ignored and treated as if the
               entry should not appear in the Year view.

dur            is the duration of the appointment measured
               in minutes. It is constrained such that the
               appointment cannot end after 11:59 PM. i.e.
               this field is between 0 and 1439 - time
               (inclusive).


Type 2 (untimed day entry/note)

A type 2 record stores details of entries that appear on a
specific day but do not have a time associated with them. In
the Series 3a Agenda these are called untimed day entries.

The details field for an untimed day entry consists of six
bytes structured as follows:

  UWORD day;
  UWORD slot;
  UBYTE attr;
  UBYTE code;

day            is the daynum of the day on which the entry
               appears.

slot           is the time slot (in minutes from midnight)
               in which the entry will appear in the Day and
               Week views. For example a slot value of 780
               would show the entry at the start of the 1pm
               slot. If this is 0xffff then the anniversary
               will appear in the default slot.

attr           is the attributes byte (see below).

code           is the ASCII character code for the symbol
               that is to be associated with the entry when
               it is visible in the Year view. Values less
               than 32 are ignored and treated as if the
               entry should not appear in the Year view.


Type 3 details (anniversaries)

A type 3 record stores details of anniversaries (entries
which appear in the Anniversary view). Although these are
usually repeated there are cases where a single anniversary
entry will exist. For details of repeated entries see type 5
records below.

The details field for an anniversary record consists of nine
bytes structured as follows:

  UWORD day;
  UWORD slot;
  UBYTE attr;
  UBYTE code;
  UWORD baseYear;
  UBYTE displayAs;

day            is the daynum for the day the anniversary
               entry will appear on.

slot           is the time slot (in minutes from midnight)
               in which the entry will appear in the Day and
               Week views. For example a slot value of 780
               would show the entry at the start of the 1pm
               slot. If this is 0xffff then the anniversary
               will appear in the default slot.

attr           is the attributes byte (see below).

code           is the ASCII code for the character to
               display when the entry is visible in the Year
               view. Values less than 32 are illegal and
               cause the entry not to appear in the Year
               view.

baseYear       is the year of the event that the anniversary
               commemorates. Positive values indicate AD
               years e.g. 55  means 55 AD and negative
               values indicate BC e.g. -5 means 5 BC. A
               value of zero indicates that there is no
               baseYear.

displayAs      contains flags detailing how the entry is to
               be displayed. The flags are as follows: 0x01
               for baseYear displayed, 0x02 for elapsed
               years displayed, 0x03 for both of the
               preceding options and 0x00 for none of them.


Type 4 details (To-do)

A type 4 record holds details of to-do entries.

These are entries which usually have an associated due date
and a display from date. They appear in the corresponding
to-do list, and depending on the preference settings will
appear in the Day view from the display from date until they
are crossed out or deleted.

The details field for a to-do entry consists of 14 bytes
structured as follows:

  UWORD displayFrom;
  UWORD slot;
  UBYTE attr;
  UBYTE code;
  UWORD dueDate;
  UBYTE listNo;
  UBYTE priDisp;
  ULONG order;

displayFrom    is the daynum of the day on which the entry
               first appears in the Day/Week views of the
               Agenda. This must normally be the same or
               less than the dueDate value.
               If the entry is crossed out (see the
               description of the attr byte below) this is
               the daynum of the day on which the entry was
               crossed out. In this case, and only in this
               case, the displayFrom can be later than the
               dueDate.
               If the displayFrom daynum is 0xffff, then
               this is an un-dated to-do i.e. one that
               always appears on today. In this case the
               dueDate will also be 0xffff.

slot           is the time slot (in minutes from midnight)
               in which the entry will appear in the Day and
               Week views. If this is 0xffff then the entry
               will appear in the default slot of the
               appropriate to-do list.

attr           is the attributes byte (see below).

code           is the ASCII code for the character to
               display when the entry is visible in the Year
               view. Values less than 32 are illegal and
               cause the entry not to appear in the Year
               view.

dueDate        is the daynum of the day the to-do should be
               done by. If this value is 0xffff the record
               is an undated to-do (i.e. one which always
               appears on today when it appears in the
               Day/Week views).

listNo         is the internal number (0-255) of the to-do
               list on which the entry will appear. Note
               that a value of zero does not necessarily
               mean that the entry appears on the first to-
               do list in the To-do view. See type 9 records
               for further details of the meaning of this
               byte.

priDisp        this byte consists of two nibbles that give
               the priority and the method of displaying the
               to-do.
               The least significant nibble (bottom four
               bits) has a value one less than the priority
               of the to-do. Thus a priority one to-do has
               value zero, priority two has value one etc.
               This will currently always be in the range
               zero to eight inclusive and all other values
               are illegal.
               The most significant nibble (top four bits),
               determines how the due date should be
               displayed there are currently four legal
               values:
               0 - automatic, shown as date until within a
               week then shown as e.g. Next wed.
               1 - Always shown as date.
               2 - Shown as number of days until due date.
               3 - Due date never shown.

order          this determines the position of the entry in
               its to-do list when the list is displayed in
               manual order. This field is not assigned
               consecutively. Thus a value of 3 for example
               in this field does not necessarily mean that
               the entry appears third (or fourth) on the
               to-do list.


The attributes byte 'attr'.

The above record types (1 to 4) contain an attributes byte
as the fifth byte within the record data. This byte contains
flags which indicate which of the two optional fields are
present in the record, whether or not the entry is repeated
etc. The following flags are currently defined for the
attributes byte (all other bits should be 0).

  Bit          Meaning

  00000001     Once only: if this bit is set the entry
               appears only once in the Agenda. If it is
               clear the entry is repeating and there will
               be an associated type 5 repeat record
               elsewhere in the file.
               

  00000010     Pending: this bit is set if the entry has not
               been crossed out. If it is clear the entry
               has been crossed out. In the case of to-do
               entries this alters the meaning of the
               displayFrom field of the details.

  00000100     Display code: if this bit is set the entry
               should be displayed in the Year view
               (providing it has a legal code field): if it
               is clear the entry should not appear in the
               Year view, regardless of the value of the
               code field.

  00001000     No alarm: this bit is set if the entry does
               not have an associated alarm in which case
               there will be no alarm field at the end of
               the record. If it is clear there is an alarm
               field immediately after the title field.

  00010000     No memo: this bit is set if there is no memo
               associated with the entry, in which case
               there will be no memo field at the end of the
               record.


The title field

The title field must be present for entry records of all
four types. This field follows immediately after the details
field and contains the text for the entry as well as flag
for how that text should be displayed e.g. bold, italic etc.

The format of the title field is:

  UBYTE style;
  UBYTE len;
  title text.

style          contains flags indicating how the text should
               appear. The flags are as follows: 0x01 for
               bold, 0x02 for underline, 0x20 for italic.

len            is the length of the text comprising the
               title, and the number of bytes following.
               This may take any value from 0 - 254.

title text     is len bytes of the title. Note that this
               text is not zero terminated.


The alarm field

This fixed length field is only present if the attributes
byte does not have bit 3 (0x08) set, i.e. there is an alarm
set for the entry.

When present this entry immediately follows the title field
and has the following format:

  UWORD preTime;
  UBYTE len;
  UBYTE sound[8];

preTime        is the time at which the alarm should occur
               given in minutes before 11.59 on the day the
               entry appears on. (in the case of a type-4
               to-do record this is the due date). This
               field can be between 0 and 46079 (midnight
               before, 31 days before the entry).

len            this gives the length of the text in the
               sound element.

sound          is always eight bytes long the first len of
               which contain the name of the WVE file for
               the alarm. A number of WVE files having names
               of the form SYS$ALnn are built-in to the ROM.
               In addition the strings "one" to "sixteen"
               inclusive are reserved: currently only "one",
               "two" and "three" are used corresponding to
               the rings, chimes and silent alarms. If the
               name of the file is less than eight bytes
               long, all remaining bytes should be zero.


The memo field

This variable length field is only present if the attributes
byte (in the details field) does not have bit 4 (0x10) set,
i.e. there is a memo attached to the entry.

When present this field comes at the end of the record
immediately after the alarm field if there is one, and after
the title field if there is not. The field has the following
format:

  UWORD dataLength;
  UBYTE data[];

dataLength     is the length (in bytes) of the data in the
               memo field. This can be between 0 and 3600
               (inclusive).

data           is a block of data consisting of dataLength
               bytes containing the memo - details of the
               memo are beyond the scope of this manual.



Type 5: repeats.

When an entry is set to repeat in the Agenda a second record
is written to the file, in addition to the type 1 - 4 entry
record. This record contains the date to repeat until, the
days to repeat on and a list of those dates for which the
repeat should be suppressed.

Repeat records are always paired with an entry record which
has bit 0 (0x01) of the attributes byte clear. Because of
the way the Series3a Agenda writes the file a type 5 repeat
record will always occur after the associated entry record,
but this is not necessary and there is no reason why it
should not occur earlier in the file. If a repeat record is
missing its associated entry record, or if a repeated entry
record exists for which there is no associated repeat
record, then the record in the file will be ignored.

The repeat record is structured as follows:

  UBYTE alg;
  UBYTE ival;
  UWORD endDate;
  UBYTE type;
  UBYTE tags[n];
  ULONG filePos;
  UWORD exceptions[];

alg            is the repeat algorithm and various flags.
               The bottom three bits of this byte may take
               one of the following values: 0 - repeat
               daily, 1 - repeat weekly, 2 - monthly by
               date, 3 - monthly by days, 4 - repeat
               annually.
               If bit 3 (0x08), of this byte is set, the
               repeat should only appear once in the dated
               views on the first occurrence after today.
               Otherwise all valid occurrences are shown.
               All other bits in this byte should be 0.

ival           is the daily repeat interval. This is zero if
               the entry repeats daily, 1 if the entry
               repeats every other day etc. A value of 255
               is not valid.

endDate        this is the daynum of the last day on which
               the entry can repeat. This is not necessarily
               the last day on which it will appear. The
               start date is taken from the day value at the
               start of the details field in the entry
               record. In the case of a repeating to-do this
               is the displayFrom field that is normally
               used to give the date from which to display
               the entry. Here it is used to determine the
               start date of the repeat algorithm and hence
               determine which due dates will be associated
               with the todos. To work out the display from
               dates for each instance of the repeated to-do
               use the dueDate-displayFrom in the entry
               record to determine the number of days
               warning for each instance of the repeat.

type           is the type (1-4) of the associated entry
               record. This information is actually
               redundant since it can be determined by
               reading it directly once the associated
               record has been found but is a useful
               optimisation internally to the Agenda.

tags           is n bytes that determine which days occur in
               the repeat sequence. The number of bytes n
               and their meaning is determined by the repeat
               algorithm. For repeat daily/annually there
               are no tag bytes since the start date and
               ival determine which dates to repeat over.
               For weekly repeats there are two tag bytes.
               The first has a bit set for each day of the
               week on which the repeat occurs. Bit 0 for
               Monday, bit 1 for Tuesday etc. Bit 8 is not
               used and should always be 0. The second byte
               determines which is the first day of the
               week, 0 for Monday, 1 for Tuesday etc. This
               is significant when the repeat does not occur
               every week. A repeat which occurs on say,
               Tuesday and Thursday of every other week,
               occurs on different dates if the week starts
               on Monday than it does if the week starts on
               Wednesday.
               For monthly by date repeats there are four
               tag bytes. Each bit in these bytes represents
               a different day of the month. Bit 0 in the
               first byte is the 1st of the month, bit 1 the
               second and bit 7 the eighth of the month. Bit
               0 of the second tag byte is set if the repeat
               occurs on the 9th and so on. Bit 7 of the
               fourth byte is not used and should be 0.
               Monthly by days repeats have the full five
               tag bytes. Bytes 0 to 3 correspond to the
               first, second, third and fourth occurrences
               of each day, for example bit 1 of byte 2 is
               set if the algorithm repeats on the 3rd
               Tuesday of each month. The last tag byte
               contains bits set if the repeat should occur
               on the last Monday, say, of the month.

filePos        is the offset from the start of the file  at
               which the corresponding entry record can be
               found. This is given in bytes from the start
               of the file (not the start of the data
               records), and gives the position of the type
               length word at the start of the record. Note
               that this mechanism of associating repeat
               records with the underlying entry relies on
               the deleted entries not being removed from
               the file: they are just marked with the
               deleted record type. Removing such records
               would require all FilePos fields to be
               recalculated.

exceptions     The remainder of the record consists of
               words, each of which is the daynum of a day
               on which the repeat should be suppressed. The
               number of exceptions is determined by the
               length of the record. Although the Series 3a
               Agenda currently always writes these
               exceptions in strictly increasing order,
               there is no guarantee that this will always
               be the case. Any illegal values (either
               outside the valid range for the Agenda or on
               a day which is not normally a repeat
               instance) should be ignored but preserved.



Type 6: anonymous data.

This record type is currently not used and is set aside for
storing non-displayable text carried with the Agenda. It is
intended that this information will be used by, say,
conversion programs that convert other Agenda file formats
to that of the Series 3a. This allows the file to be
converted back without losing information from the original
file. These records are ignored by the series 3a engine
except when merging files. In this case incoming anonymous
data records are added to the file into which data is being
merged.



Types 7 and 8: reserved

These record types are reserved for future expansion and
should not be used.



Type 9: to-do list information

There is one record of this type for each to-do list in the
Agenda. Each contains the setting for the to-do list and the
to-do list number (as in type 4 to-do records) that
corresponds to the list.

The format for these records is as follows:

  UBYTE sig;
  UBYTE data[]

sig            a signature byte which determines the format
               of the rest of the record. Currently the only
               legal value is 0xff.

data           is data for the to-do list: the details of
               the data are beyond the scope of this manual.


Types 10 to 14: descriptive records.

Type 10 to 14 records contain the preferences settings for
the Agenda (these may be set via the preferences dialog).
Only one record of each type is allowed per Agenda file. If
there is more than one record of any type, only the last
record is significant.

A descriptive record consists of the usual header word
followed by the record body. The record body contains either
simple data or a set of type/length/value (TLV) fields. A
TLV field consists of a one word header followed by the
field body. The top four bits of the field header contain
the field type. The bottom 12 bits contain the length of the
field body. No more than one of each of the specified fields
can be present in a given record.

The structure of these records should not be extended (extra
TLV fields should not added even though these would be
ignored).

Type 10 to 14 records are described in greater detail below.



Type 10: styles descriptive record.

The styles record contains the Memo editor preferences and
its styles and emphases.

The styles record gets written after a memo has been created
for the first time, and thereafter whenever its content has
changed.

The details of this record are beyond the scope of this
manual.



Type 11: to-do manager descriptive record.

This record is written on creation of a new Agenda and so is
always present. It gets rewritten whenever changes have been
made.

This record contains the information that the Agenda needs
to determine which position each to-do list has in the To-do
view. The record consists of a header word followed by a
body of three bytes structured as follows:

  UBYTE sig;
  UBYTE ncats;
  UBYTE catid[ncats]

sig            is the signature and is always 0x6c.

ncats          is the number of categories.

catid[ncats]   contains ids for each category (i.e. to-do
               list) in the display order. Thus catid[0]
               holds the id of the first displayed category,
               catid[1] the id of the second, and so on up
               to a maximum of catid[98]. These are used to
               identify each record as coming from a given
               category in a record.



Type 12: frequently changing data descriptive record.

This record is written on creation of a new Agenda and so is
always present. However, as it contains data that changes
frequently, it is only rewritten when the file is closed
down.

This record contains zoom, wrap and status window settings
for each view. It consists of a header word followed by six
VIEW_SCREEN_CFG structures for the Day, Week, Year, To-do,
Anniversary and List views respectively. A VIEW_SCREEN_CFG
structure consists of three bytes and is structured as
follows:

  UBYTE statmode;
  UBYTE wrapmode;
  UBYTE zoom;

statmode       this field is a flag for the status window.
               It is 0 if a status window is not visible, 1
               if the small status window is visible and 2
               if the large status window is visible. This
               flag applies to all views.

wrapmode       in all views except the Year view the
               wrapmode field is 1 if wrap is on, and is
               otherwise 0. In the Year view (which does not
               use wrapping) the wrapmode field contains the
               index of the month that is displayed in the
               first row of the planner (0 = January, 11 =
               December).

zoom           this field takes the value 0 to 3
               corresponding to Roman fonts of height 8, 11,
               13 and 16 respectively. It is relevant for
               the Day, Week, To-do, Anniversary and List
               views. The zoom field is unused in the Year
               view entry and is set to 0.



Type 13: general descriptive record.

This record is written on creation of a new Agenda and so is
always present. It stores data shown in the dialogs under
the Preferences menu. It gets written whenever the values
shown in one of these dialogs are changed.

This record contains entry defaults and all individual view
preferences (to-do entry defaults are stored in to-do
records). Each record has the normal Agenda type/length
header followed by one or more TLV fields. There are sixteen
possible type fields only some of which are currently used:
the rest are reserved for future use. If a field is not
found the Agenda will use the corresponding default values.
The fields can be in any order.

  Type         Field

  4            Diamond list setup

  5            Day entry defaults

  6            Anniversary defaults

  7            General defaults

  9            Day view settings

  10           Week view settings

  11           Year view settings

  12           To-do view settings

  13           Anniversary view settings

  14           List view settings


Diamond list setup field

The diamond list setup field indicates which views should be
included in the diamond list. It consists of six bytes
structured as follows:

  UBYTE fnbar[6];

fnbar          contains six bytes corresponding to the Day,
               Week, Year, To-do, List and Anniversary views
               respectively. Each byte is either TRUE or
               FALSE depending on whether or not the view is
               to be included in the diamond list.


Day entry defaults field

The day entry defaults field contains the defaults for
entries in the Day view. The field consists of 38 bytes
structured as follows:

  UWORD DefUntimedEntViewTime;
  UWORD DefTimedEntTime;
  UWORD DefTimedEntDuration;
  UBYTE DefTimedByDefault;
  UBYTE DefYearSym;
  AGPREF_ALARM UntimedAlarmDefs;
  AGPREF_ALARM TimedAlarmDefs;
  UBYTE style;
  UBYTE spare;

DefUntimedEntViewTime is the default display time for untimed
                      entries in minutes since 00:00.

DefTimedEntTime       is the default display time for timed entries
                      in minutes since 00:00.

DefTimedEntDuration   is the default duration for a timed entry in
                      minutes.

DefTimedByDefault     is 1 if entries are timed by default,
                      otherwise it is 0.

DefYearSym            is the character code for the default year
                      symbol.

UntimedAlarmDefs      contains details of the default alarm for
                      untimed entries (see below for a description
                      of the AGPREF_ALARM structure).

TimedAlarmDefs        contains details of the default alarm for
                      timed entries (see below for a description of
                      the AGPREF_ALARM structure).

style                 is the style of the font used for the entry.
                      It is 0x00 for normal, 0x01 for bold and/or
                      0x02 for underline (note: these are the Wserv
                      G_STY_XXX flags).

spare                 is reserved and is set to 0.

An AGPREF_ALARM structure contains default alarm details. It
consists of 14 bytes structured as follows:

  UBYTE on;
  UBYTE ndays;
  UWORD minutes;
  SE_SND snd;

on             is 1 if an entry has an alarm by default and
               0 otherwise.

minutes        for timed entries minutes is the time
               interval in minutes between the alarm going
               off and the start of the entry. For untimed
               entries minutes is the default alarm time in
               minutes from midnight.

ndays          for timed entries ndays is unused but should
               be set to 0. For untimed entries ndays is the
               default number of days between the alarm
               going off and the start of the entry.

snd            contains details of the default alarm sound
               (see below for a description of the SE_SND
               structure).

The SE_SND structure contains details of the default alarm
sound. It consists of ten bytes structured as follows:

  UBYTE len;
  TEXT name[8];
  UBYTE zero_term;

len            is the length of the name of the alarm.

name           contains the name of the alarm stored as a
               sequence of len characters. When len is less
               than eight the first unused byte contains a
               NULL character. Any remaining unused bytes
               can take any value.

zero_term      contains the NULL character.


Anniversary entry defaults field

An anniversary entry defaults field contains the defaults
for entries in the Anniversary view. It consists of 20 bytes
structured as follows:

  UWORD DefEntViewTime;
  UBYTE AutoApplyYearSym;
  UBYTE DefYearSym;
  AGPREF_ALARM AlarmDefs;
  UBYTE style;
  UBYTE spare;

DefEntViewTim  is the default display time for anniversaries
e              in minutes since midnight.

AutoApplyYear  is 1 if the year symbol is on by default,
Sym            otherwise it is 0.

DefYearSym     is the character code of the default year
               symbol.

AlarmDefs      contains the default alarm details for timed
               and untimed entries (see the Day entry
               defaults field for details of the
               AGPREF_ALARM structure).

style          is the style of the font used for the entry.
               It is 0x00 for normal, 0x01 for bold and/or
               0x02 for underline (note: these are the Wserv
               G_STY_XXX flags).

spare          is reserved and is set to 0.


General defaults field

  UBYTE p_psion_enter;
  UBYTE timesep;

p_psion_enter  is set to TRUE if PSION+ENTER is used to
               complete an entry without going into the
               Entry details dialog. Otherwise p_psion_enter
               is FALSE.

timesep        is the character code for the Agenda time
               separator character.


Day view settings field

  UWORD agnv_flags;
  ADENTVU_PREF left;  /* left view's preference */
  ADENTVU_PREF right; /* right view's preference */

agnv_flags     this field contains both general view flags
               and Day view flags (all bits not used are
               reserved). The general view flags are as
               follows:
                 0x01 for show appointment duration (Day,
               List, Week and Year views),
                 0x02 for show appointment end time (Day,
               List, Week and Year views only),
                 0x100 for show untimed day notes (Day, List
               and Week views only),
                 0x200 for show anniversaries (Day, List and
               Week views only),
                 0x400 for show to-dos (Day, List and Week
               views only) and
                 0x800 for show timed day notes (Day, List
               and Week views only).
               The Day view flags are as follows:
                 0x04 for title to go on right hand side,
                 0x08 for slot compression off,
                 0x10 for duration arrows off and
                 0x20 for show overlap bars off.

left           contains the preferences for the left hand
               side of the Day view (see below for a
               description of the ADENTVU_PREF structure).

right          contains the preferences for the right hand
               side of the Day view (see below for a
               description of the ADENTVU_PREF structure).

An ADENTVU_PREF structure consists of 12 bytes structured as
follows:

  UWORD flags;
  UWORD begintime;
  UWORD beginvis;
  UWORD endvis;
  UWORD endtime;
  UWORD slotdur;

flags          contains a combination of the slot lines on
               flag (0x01) and the slot times on flag
               (0x02).

begintime      is 0 for the left hand side and beginvis for
               the right hand side.

beginvis       is the start time of the first slot in
               minutes from midnight.

endvis         is the start time of the last slot in minutes
               from midnight.

endtime        is right.beginvis for the left hand side and
               1440 for the right hand side.

slotdur        is the slot duration in minutes.


Week view settings field

The Week view settings field consists of two bytes as
follows:

  UWORD pref_flags;

pref_flags     contains both general view flags (see above
               under the Day view settings field), and Week
               view flags. Currently there is only one Week
               view flag: 0x4 for show title on right hand
               side.


Year view settings field

The Year view settings field consists of two bytes as
follows:

  UWORD pref_flags;

pref_flags     contains a combination of the general flags
               (see under the Day view settings field above)
               for showing appointment duration and/or end
               time or neither.


To-do view settings field

The To-do view settings field consists of two bytes
structured as follows:

  UWORD ncols;

ncols          contains the number of columns to be shown in
               the To-do view. The value of ncols should not
               be more than the number of existing
               categories.


Anniversary view settings field

The Anniversary view settings field consists of two bytes
structured as follows:

  UWORD ncols;

ncols          contains the number of columns to be shown in
               the Anniversary view (1 to 4).


List view settings field

The List view settings field consists of two bytes
structured as follows:

  UWORD pref_flags;

pref_flags     contains a combination of general view and
               Day view flags (see under the Day view
               settings field above) and the show-repeats-
               once flag (0x04).



Print setup descriptive record - Type 14

This record does not initially exist. It is
created/rewritten to contain a new copy of the data for the
Agenda print setup after using the Agenda Print setup
dialog. It is also created/rewritten after a memo has been
created or edited and Print setup data has been changed.
Hence it is possible that the record will only contain
Agenda Print setup data or Memo Print setup data.

The record consists of a one word header followed by a
series of TLV fields.

Field types 0 to 3 and 6 to 9 are allowed. Field types 0 to
3 are used for the main Agenda print setup. Field types 6 to
9 are identical to field types 0 to 3 and are used for the
memo print setup.


Field type 0 and 6

Contains printer parameters in a PRINTER_PARAMS structure as
returned by the PR_GET_PARAMS method of the printer active
object of the FORM dyl.


Field types 1 and 7

Contain printer model data from the PR_SENSE_MODEL method of
the printer active object. The first byte is the model
number as returned by PR_SENSE_MODEL, followed by the name,
up to and including the NULL.


Field types 2 and 8

Contain printer header text from the PR_GET_HD method of the
printer active object including the terminating NULL.


Field types 3 and 9

Contain printer footer text from the PR_GET_HD method of the
printer active object including the terminating NULL.



Type 15: illegal.

This record type is illegal and is used to protect the
Agenda against write failures on a flash SSD. Writing to a
flash SSD can fail at any time due to, say, a low battery.
To protect as much as possible against this the Agenda will
write the whole of the rest of the record before 'blowing
down' the byte containing the record type to its correct
value. This means that any file which contains a record with
type 15 (0xf) has suffered a write failure and data beyond
this point cannot be trusted.

This record type is probably best thought of as an End Of
File record, and any program finding a file with a type 15
record should start by setting the end of the file to the
start (the type length word) of the record.
---------------------------------------------------------
