positron/doc/mdb.html

   1 <html>
   2 <head>
   3   <link rel="stylesheet" type="text/css" href="style.css" />
   4   <style type="text/css">
   5     table.recordlayout, table.recordlayout td,
   6     table.recordlayout th {border: 2px black solid;
   7                            border-collapse: collapse;}
   8
   9     table.recordlayout {margin-left: auto; margin-right: auto}
  10     table.recordlayout td.delim{background-color: rgb(85%,85%,85%);}
  11     table.recordlayout td.specialdelim{background-color: rgb(95%,85%,85%);}
  12   </style>
  13   <title>Positron Developer's Guide: MDB File Format</title>
  14 </head>
  15 <body>
  16 <h1>Positron Developer's Guide: MDB File Format</h1>
  17
  18 <p>
  19 This document explains the format of the MDB files.  MDB files store
  20 the actual contents of a database record.  The MDB file begins with a
  21 variable length header describing the overall database configuration.
  22 The header is followed by one or more variable length records.  Every
  23 MDB file must have (generally as its first record, though it is not
  24 clear if this location is a requirement) a <a href="#nullrec">null record</a>.
  25 This record is used by parent databases, if they exist, to specify a
  26 null value for one of their access keys.
  27 </p>
  28
  29
  30 <h2>MDB Header</h2>
  31
  32 <p>The names given in the table below are sometimes used in
  33 implementations, but are not normative in any way.</p>
  34
  35 <table class="fielddef">
  36 <tr><th>Name</th><th>Word Offset</th><th>Size (words)</th><th>Description</th></tr>
  37 <tr><td>LengthOfHeader<td>0</td><td>1</td><td>Length of header in words, including this word.</td></tr>
  38 <tr><td>Attributes</td><td>1</td><td>1</td><td>Attribute bits:
  39 <ul>
  40   <li>Bit 0 (isRoot) = 0 if this is a child DB, 1 if this is a root DB</li>
  41   <li>Bit 1 (isRemovableChildDB) = 0 if non-removable, 1 if removable.</li>
  42   <p>Records in a removable DB can be deleted even if there are records in
  43      the parent DB still referring to them.  In a non-removable DB, this
  44      is not allowed.</p>
  45   <li>Bits 2-15 = Reserved, zero by default</li>
  46 </td></tr>
  47 <tr><td>Status</td><td>2</td><td>1</td><td>Status bits:
  48 <ul>
  49   <li>Bit 0 (isModified) = 0 if not modified since last sync, 1 if not modified.</li>
  50   <li>Bits 1-15 = Reserved, zero by default</li>
  51 </td></tr>
  52 <tr><td>NumOfKeys</td><td>3</td><td>1</td><td>1 + the number of access keys, sometimes
  53    called "rules," per record.  Essentially, the primary data field is being counted here,
  54    even though it is not an access key.  (M)</td></tr>
  55 <tr><td>NumOfFieldsPerRecord</td><td>4</td><td>1</td><td>Number of Fields per record.
  56    Includes the primary data field, access keys, and extra info fields.</td></tr>
  57 <tr><td>RecordStart</td><td>5</td><td>2</td><td>Word pointer to start of first record in this file</td></tr>
  58 <tr><td>pXIM</td><td>7</td><td>2</td><td>Word pointer to the <a href="#xim">XIM data</a></td></tr>
  59 <tr><td>Reserved</td><td>9</td><td>6</td><td>Reserved</td></tr>
  60 <tr><td>DB_ID</td><td>15</td><td>1</td><td>Database ID assigned by device DB server</td></tr>
  61 <tr><td>pDB_Name</td><td>16</td><td>2</td><td>Word pointer to DB name</td></tr>
  62 <tr><td>pParentDBFilename</td><td>18</td><td>2</td><td>Word pointer to DB filename</td></tr>
  63 <tr><td>pRuleName1</td><td>20</td><td>2</td><td>Word pointer to name of access key #1</td></tr>
  64 <tr><td>pRuleFilename1</td><td>22</td><td>2</td><td>Word pointer to filename of
  65     child MDB for access key #1</td></tr>
  66 <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr>
  67 <tr><td>pRuleNameM</td><td>20+4*(M-1)</td><td>2</td><td>Word pointer to name of access key #M</td></tr>
  68 <tr><td>pRuleFilenameM</td><td>22+4*(M-1)</td><td>2</td><td>Word pointer to filename of
  69     child MDB for access key #M</td></tr>
  70 <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr>
  71 <tr><td>DB_Name</td><td></td><td>Variable</td><td>DB name (dd format)</td></tr>
  72 <tr><td>ParentDBFilename</td><td></td><td>Variable</td><td>DB filename (sz format)</td></tr>
  73 <tr><td>RuleName1</td><td></td><td>Variable</td><td>Name of access key #1 (dd format)</td></tr>
  74 <tr><td>RuleFilename1</td><td>22</td><td>Variable</td><td>Filename of child MDB file for access key #1 (sz format)</td></tr>
  75 <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr>
  76 <tr><td>pRuleNameM</td><td></td><td>Variable</td><td>Name of access key #M (dd format)</td></tr>
  77 <tr><td>pRuleFilenameM</td><td></td><td>Variable</td><td>Filename of
  78     child MDB for access key #M (sz format)</td></tr>
  79 <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr>
  80 <tr><td>XIM</td><td></td><td>Variable</td><td><a href="#xim">XIM data</a></td>
  81 <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr>
  82 <tr><td>Signature</td><td>LengthOfHeader - 2</td><td>2</td><td>Signature, "WOID"</td>
  83 </table>
  84
  85 <h3 id="xim">XIM Data</h3>
  86
  87 <p>
  88 XIM data is used to control the menu system on the Neuros.  Various
  89 databases are often associated with particular menus, and the XIM data
  90 stored in the MDB header controls what menu options are available and
  91 what they do.  This documentation does not cover the structure of the
  92 XIM data block.
  93 </p>
  94
  95 <h2>MDB Records</h2>
  96
  97 <p>
  98 MDB Records are composed of three types of fields (always occuring in this order):
  99 </p>
 100
 101 <dl>
 102
 103   <dt>Primary Data</dt><dd>There is exactly one of these fields per
 104   record.  Often, in a child database, this is the only field.  The
 105   data is always stored in sz format.</dd>
 106
 107   <dt>Access Keys</dt><dd>There can be zero or more access keys per
 108   database.  Rather than store the actual data (like "Rock" or "FM
 109   Radio"), a pointer to the MDB record holding this data in the child
 110   database is stored.  Null values are recorded by pointing at the
 111   <a href="#nullrec">null record</a> in the child database.</dd>
 112
 113   <dt>Extra Info</dt><dd>These can be zero or more extra info fields.
 114   The format of these fields depends on the particular database.  They
 115   are usually integers or null-terminated strings.</dd>
 116
 117 </dl>
 118
 119 <p>
 120 The number of each of these fields is fixed by the MDB header.  There
 121 is one primary data field, (NumOfKeys - 1) access keys, and
 122 (NumOfFieldsPerRecord - NumOfKeys) extra info fields.
 123 </p>
 124
 125 <p>
 126 Fields are permitted to be multi-valued.  This is used to support
 127 fields like "Playlist" in the <a href="database.html#audio">audio
 128 database</a>, which can have several values if a track is in multiple
 129 playlists.
 130 </p>
 131
 132 <h3>Record Layout</h3>
 133
 134 <p>
 135 Since fields can have variable length, some method must be used to
 136 mark where each field begins and ends.  The method used in the MDB
 137 format is special delimiter words:
 138 <dl>
 139   <dt>0x0023</dt><dd># - Field delimiter</dd>
 140   <dt>0x0025</dt><dd>% - End of record</dd>
 141
 142   <dt>0x0024</dt><dd>$ - Bag delimeter.  This word is used to separate
 143   values in a field that has multiple values.</dd>
 144
 145   <dt>0x002F</dt><dd>/ - Escaper.  If any field value contains one of
 146   these special words (including the escaper itself), it must be
 147   escaped using this word.  For example, to store the pointer
 148   0x00000023 in a field, you would have to write 0x0000,0x002F,0x0023.</dd>
 149 </dl>
 150 </p>
 151
 152 <h4>Normal Record</h4>
 153
 154 <p>
 155 An example record in a database with all three types of fields, but
 156 without any multivalued fields, would have the following form:
 157 </p>
 158
 159 <table class="recordlayout">
 160 <tr><td class="descriptive">Record Flag - 16-bit flag
 161 <ul>
 162   <li>Bit 0 (isDeleted) - 0 if an active record, 1 if a deleted record</li>
 163   <li>Bits 1-14 - Reserved (default to 0)</li>
 164   <li>Bit 15 - ID, always set to 1. Use this to verify you are looking a legitimate record.</li>
 165 </ul>
 166 </td></tr>
 167 <tr><td>Primary Record Data (sz format)</td></tr>
 168 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 169 <tr><td>Access Key #1 (pointer)</td></tr>
 170 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 171 <tr><td>Access Key #2 (pointer)</td></tr>
 172 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 173 <tr><td>Extra Info #1 (integer)</td></tr>
 174 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 175 <tr><td>Extra Info #2 (sz data)</td></tr>
 176 <tr><td class="delim">0x0025, End of Record</td></tr>
 177 </table>
 178
 179 <h4>Record with Multivalued Field</h4>
 180
 181 <p>
 182 An example record in a database with all three types of fields, but
 183 with a multivalued fields, would have the following form:
 184 </p>
 185
 186 <table class="recordlayout">
 187 <tr><td>Record Flag</td></tr>
 188 <tr><td>Primary Record Data (sz format)</td></tr>
 189 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 190 <tr><td>Access Key #1, Value #1 (pointer)</td></tr>
 191 <tr><td class="specialdelim">0x0024, Bag delimiter</td></tr>
 192 <tr><td>Access Key #1, Value #2 (pointer)</td></tr>
 193 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 194 <tr><td>Access Key #2 (pointer)</td></tr>
 195 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 196 <tr><td>Extra Info #1 (integer)</td></tr>
 197 <tr><td class="delim">0x0023, Field delimiter</td></tr>
 198 <tr><td>Extra Info #2 (sz data)</td></tr>
 199 <tr><td class="delim">0x0025, End of Record</td></tr>
 200 </table>
 201
 202 <h4>Typical Child DB Record</h4>
 203
 204 <p>
 205 Most child databases only have a primary data field, so they look like:
 206 </p>
 207
 208 <table class="recordlayout">
 209 <tr><td>Record Flag</td></tr>
 210 <tr><td>Primary Record Data (sz format)</td></tr>
 211 <tr><td class="delim">0x0025, End of Record</td></tr>
 212 </table>
 213
 214 <h4 id="nullrec">Null Record</h4>
 215
 216 <p>
 217 Every database is required to have a null record, generally the first
 218 record.  This is a degenerate record with no fields used to represent
 219 null values in child databases.  A parent will point to this record
 220 when the associated access key has a null (or empty) value:
 221 </p>
 222
 223 <table class="recordlayout">
 224 <tr><td>0x8000, Record Flag (this record must not be deleted)</td></tr>
 225 <tr><td class="delim">0x0025, End of Record</td></tr>
 226 </table>
 227
 228 </body>
 229 </html>