home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / developmen / agformat / AGNFILE.TXT
Text File  |  1993-09-15  |  43KB  |  1,205 lines
  1. SERIES 3A AGENDA FILE FORMAT
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10. Introduction
  11.  
  12. Series 3a Agenda files are binary files containing typed
  13. variable length records. They use the same basic file and
  14. record structure as DBF files, but the file signature and
  15. internal record structure are NOT the same.
  16.  
  17.  
  18.  
  19. Basic structure of Agenda files
  20.  
  21. The basic file structure for Agenda files is as follows:
  22.  
  23.   <standard header>  Used to identify the file type and the
  24.                      version of the file structure.
  25.  
  26.   <extended header>  For future use, currently omitted.
  27.  
  28.   <data records>     The main body of the file, containing
  29.                      entries and preferences.
  30.  
  31.  
  32. The standard header
  33.  
  34. The standard header is present at the start of all Agenda
  35. files and is always 32 bytes long.
  36.  
  37.   AGD_SIG_SIZE 16
  38.   AGD_SPARE_SIZE 12
  39.  
  40.   typedef struct
  41.       {
  42.       UBYTE sig[AGD_SIG_SIZE];
  43.       UWORD version;
  44.       UWORD hSize;
  45.       UBYTE spare[AGD_SPARE_SIZE];
  46.       } AGD_FILE_HEADER;
  47.  
  48. The first 16 bytes of the file are always the zero
  49. terminated string AgendaFileType*. This is used to identify
  50. the file as an Agenda file.
  51.  
  52. The two byte parameter version at file offset 0x100f should
  53. be interpreted as a hexadecimal word that gives the version
  54. of the file format. This is currently always 0x100F. The
  55. most significant nibble (the version number is in the format
  56. described in the General System Services chapter of the Plib
  57. Reference manual) is the major version number and any change
  58. in this indicates that the file format may not be backwards
  59. compatible.
  60.  
  61. The two byte parameter hSize gives the combined size of the
  62. standard and extended header. This effectively gives the
  63. file offset of the first data record within the file.
  64. Currently this is always 0x0020.
  65.  
  66. The array spare should not be used and is reserved for
  67. future use.
  68.  
  69.  
  70. The extended header
  71.  
  72. At present this is never used and is reserved for future
  73. expansion.
  74.  
  75.  
  76. The data records
  77.  
  78. As in DBF files all data is stored as variable length, typed
  79. records, with the type and length combined into a single
  80. word (two bytes). The most significant nibble of the word
  81. gives the record type. The type determines how the contents
  82. of the record are to be interpreted. The remainder of the
  83. word gives the length of the data that follows. This file
  84. structure is designed to be flash friendly in that deleted
  85. records are not normally removed from the file but are
  86. marked with record type 0 which can be done in place.
  87.  
  88. This structure allows 16 record types 0x0 to 0xf, each of
  89. which are allowed to be up to 0xffe (4094) bytes long.
  90. Although a record length of 0xfff is not explicitly illegal
  91. it is not used.
  92.  
  93.  
  94.  
  95. Record Types
  96.  
  97. There are sixteen record types as follows.
  98.  
  99.   Type         Record
  100.  
  101.   0            Deleted
  102.  
  103.   1            Appointments (timed day entries)
  104.  
  105.   2            Day notes (un-timed day entries)
  106.  
  107.   3            Anniversaries
  108.  
  109.   4            To-do entries
  110.  
  111.   5            Repeat records
  112.  
  113.   6            Anonymous data
  114.  
  115.   7            Reserved
  116.  
  117.   8            Reserved
  118.  
  119.   9            To-do list information
  120.  
  121.   10           Descriptive records 1
  122.  
  123.   11           Descriptive records 2
  124.  
  125.   12           Descriptive records 3
  126.  
  127.   13           Descriptive records 4
  128.  
  129.   14           Descriptive records 5
  130.  
  131.   15           Illegal (used to mark write failure)
  132.  
  133. Currently record types 6, 7 & 8 are never generated by the
  134. Series 3a Agenda.
  135.  
  136. A number of the records contain day numbers and times.
  137. Unless stated otherwise all dates are given as a daynum. A
  138. daynum is the number of days from 1 Jan. 1970. For technical
  139. reasons dates before 1 Jan. 1980 (daynum 3652) or after 31
  140. Dec. 2049 (daynum 29219) are ignored by the Agenda and where
  141. appropriate will be 'clipped' to one or other of these dates
  142. (for example a repeating entry that starts on 10 June 1970
  143. will have its start date 'clipped' to 1 Jan. 1980).
  144.  
  145.  
  146.  
  147. Type 0: deleted record.
  148.  
  149. As for DBF files, deleted records are not normally removed
  150. from the file but have their record type changed to type 0.
  151. As any of the above record types may be converted to a type
  152. 0 record, there is nothing that can usefully be said about
  153. the contents of such a record (indeed the record may not
  154. even have been a valid Agenda record before it was deleted).
  155. Records of this type should be ignored except to calculate
  156. the amount of space that would be freed by compressing the
  157. file.
  158.  
  159. There may be any number of such records in the file.
  160.  
  161.  
  162.  
  163. Types 1 to 4: entry records.
  164.  
  165. Records of type 1 to 4 contain details of individual Agenda
  166. entries. Each has the same conceptual structure as follows:
  167.  
  168.   <Entry details      This is dependent on the entry type.
  169.   field>
  170.  
  171.   <Title field>       Obligatory, variable length field
  172.                       containing the text of the entry.
  173.  
  174.   <Alarm field>       Optional, fixed length field
  175.                       containing alarm time and sound.
  176.  
  177.   <Memo field>        Optional variable length field
  178.                       containing any memo for the entry.
  179.  
  180. The record type is used to determine the length and meaning
  181. of the first field. Although these have some similarities
  182. all four are individually described in details below.
  183.  
  184.  
  185. Entry details field
  186.  
  187. This field contains most of the non-textual information
  188. describing when an entry occurs, what other fields it has
  189. and various bits of type specific information, such as the
  190. duration for timed appointments.
  191.  
  192.  
  193. Type 1 (timed day entry/appointment)
  194.  
  195. A type 1 record stores details of entries that occur at a
  196. specific time on a specific day. In the Series 3a Agenda
  197. these are called timed day entries.
  198.  
  199. The details field for a timed day entry consists of eight
  200. bytes structured as follows:
  201.  
  202.   UWORD day;
  203.   UWORD time;
  204.   UBYTE attr;
  205.   UBYTE code;
  206.   UWORD dur;
  207.  
  208. day            is the daynum of the day on which the entry
  209.                appears.
  210.  
  211. time           is the time of the start of the appointment
  212.                in minutes from midnight.
  213.  
  214. attr           is a byte containing flags for attributes the
  215.                entry may or may not have (see below).
  216.  
  217. code           is the ASCII character code for the symbol
  218.                that is to be associated with the entry when
  219.                it is visible in the Year view. Values less
  220.                than 32 are ignored and treated as if the
  221.                entry should not appear in the Year view.
  222.  
  223. dur            is the duration of the appointment measured
  224.                in minutes. It is constrained such that the
  225.                appointment cannot end after 11:59 PM. i.e.
  226.                this field is between 0 and 1439 - time
  227.                (inclusive).
  228.  
  229.  
  230. Type 2 (untimed day entry/note)
  231.  
  232. A type 2 record stores details of entries that appear on a
  233. specific day but do not have a time associated with them. In
  234. the Series 3a Agenda these are called untimed day entries.
  235.  
  236. The details field for an untimed day entry consists of six
  237. bytes structured as follows:
  238.  
  239.   UWORD day;
  240.   UWORD slot;
  241.   UBYTE attr;
  242.   UBYTE code;
  243.  
  244. day            is the daynum of the day on which the entry
  245.                appears.
  246.  
  247. slot           is the time slot (in minutes from midnight)
  248.                in which the entry will appear in the Day and
  249.                Week views. For example a slot value of 780
  250.                would show the entry at the start of the 1pm
  251.                slot. If this is 0xffff then the anniversary
  252.                will appear in the default slot.
  253.  
  254. attr           is the attributes byte (see below).
  255.  
  256. code           is the ASCII character code for the symbol
  257.                that is to be associated with the entry when
  258.                it is visible in the Year view. Values less
  259.                than 32 are ignored and treated as if the
  260.                entry should not appear in the Year view.
  261.  
  262.  
  263. Type 3 details (anniversaries)
  264.  
  265. A type 3 record stores details of anniversaries (entries
  266. which appear in the Anniversary view). Although these are
  267. usually repeated there are cases where a single anniversary
  268. entry will exist. For details of repeated