Positron Developer's Guide: MDB File Format

This document explains the format of the MDB files. MDB files store the actual contents of a database record. The MDB file begins with a variable length header describing the overall database configuration. The header is followed by one or more variable length records. Every MDB file must have (generally as its first record, though it is not clear if this location is a requirement) a null record. This record is used by parent databases, if they exist, to specify a null value for one of their access keys.

MDB Header

The names given in the table below are sometimes used in implementations, but are not normative in any way.

NameWord OffsetSize (words)Description
LengthOfHeader01Length of header in words, including this word.
Attributes11Attribute bits:
  • Bit 0 (isRoot) = 0 if this is a child DB, 1 if this is a root DB
  • Bit 1 (isRemovableChildDB) = 0 if non-removable, 1 if removable.

    • Records in a removable DB can be deleted even if there are records in the parent DB still referring to them. In a non-removable DB, this is not allowed.

  • Bits 2-15 = Reserved, zero by default
Status21Status bits:
  • Bit 0 (isModified) = 0 if not modified since last sync, 1 if not modified.
  • Bits 1-15 = Reserved, zero by default
NumOfKeys311 + the number of access keys, sometimes called "rules," per record. Essentially, the primary data field is being counted here, even though it is not an access key. (M)
NumOfFieldsPerRecord41Number of Fields per record. Includes the primary data field, access keys, and extra info fields.
RecordStart52Word pointer to start of first record in this file
pXIM72Word pointer to the XIM data
Reserved96Reserved
DB_ID151Database ID assigned by device DB server
pDB_Name162Word pointer to DB name
pParentDBFilename182Word pointer to DB filename
pRuleName1202Word pointer to name of access key #1
pRuleFilename1222Word pointer to filename of child MDB for access key #1
............
pRuleNameM20+4*(M-1)2Word pointer to name of access key #M
pRuleFilenameM22+4*(M-1)2Word pointer to filename of child MDB for access key #M
............
DB_NameVariableDB name (dd format)
ParentDBFilenameVariableDB filename (sz format)
RuleName1VariableName of access key #1 (dd format)
RuleFilename122VariableFilename of child MDB file for access key #1 (sz format)
............
pRuleNameMVariableName of access key #M (dd format)
pRuleFilenameMVariableFilename of child MDB for access key #M (sz format)
............
XIMVariableXIM data
............
SignatureLengthOfHeader - 22Signature, "WOID"

XIM Data

XIM data is used to control the menu system on the Neuros. Various databases are often associated with particular menus, and the XIM data stored in the MDB header controls what menu options are available and what they do. This documentation does not cover the structure of the XIM data block.

MDB Records

MDB Records are composed of three types of fields (always occuring in this order):

Primary Data
There is exactly one of these fields per record. Often, in a child database, this is the only field. The data is always stored in sz format.
Access Keys
There can be zero or more access keys per database. Rather than store the actual data (like "Rock" or "FM Radio"), a pointer to the MDB record holding this data in the child database is stored. Null values are recorded by pointing at the null record in the child database.
Extra Info
These can be zero or more extra info fields. The format of these fields depends on the particular database. They are usually integers or null-terminated strings.

The number of each of these fields is fixed by the MDB header. There is one primary data field, (NumOfKeys - 1) access keys, and (NumOfFieldsPerRecord - NumOfKeys) extra info fields.

Fields are permitted to be multi-valued. This is used to support fields like "Playlist" in the audio database, which can have several values if a track is in multiple playlists.

Record Layout

Since fields can have variable length, some method must be used to mark where each field begins and ends. The method used in the MDB format is special delimiter words:

0x0023
# - Field delimiter
0x0025
% - End of record
0x0024
$ - Bag delimeter. This word is used to separate values in a field that has multiple values.
0x002F
/ - Escaper. If any field value contains one of these special words (including the escaper itself), it must be escaped using this word. For example, to store the pointer 0x00000023 in a field, you would have to write 0x0000,0x002F,0x0023.

Normal Record

An example record in a database with all three types of fields, but without any multivalued fields, would have the following form:

Record Flag - 16-bit flag
  • Bit 0 (isDeleted) - 0 if an active record, 1 if a deleted record
  • Bits 1-14 - Reserved (default to 0)
  • Bit 15 - ID, always set to 1. Use this to verify you are looking a legitimate record.
Primary Record Data (sz format)
0x0023, Field delimiter
Access Key #1 (pointer)
0x0023, Field delimiter
Access Key #2 (pointer)
0x0023, Field delimiter
Extra Info #1 (integer)
0x0023, Field delimiter
Extra Info #2 (sz data)
0x0025, End of Record

Record with Multivalued Field

An example record in a database with all three types of fields, but with a multivalued fields, would have the following form:

Record Flag
Primary Record Data (sz format)
0x0023, Field delimiter
Access Key #1, Value #1 (pointer)
0x0024, Bag delimiter
Access Key #1, Value #2 (pointer)
0x0023, Field delimiter
Access Key #2 (pointer)
0x0023, Field delimiter
Extra Info #1 (integer)
0x0023, Field delimiter
Extra Info #2 (sz data)
0x0025, End of Record

Typical Child DB Record

Most child databases only have a primary data field, so they look like:

Record Flag
Primary Record Data (sz format)
0x0025, End of Record

Null Record

Every database is required to have a null record, generally the first record. This is a degenerate record with no fields used to represent null values in child databases. A parent will point to this record when the associated access key has a null (or empty) value:

0x8000, Record Flag (this record must not be deleted)
0x0025, End of Record