Structs Buffer Format
Structs buffer files can contain mnemonic and/or event data. They are only intended to be imported with the STRUCT BUFFER IMPORT API action. They may either use the structs DSV format or the XBin format. As with both of these formats, the structs buffer file is essentially a set of time-key-value mappings. By default keys are interpretted as mnemonics, unless they start with the dollar sign ($) character, in which case they are interpretted according to the rules of this document. Currently this is only used to embed event data, but additional features may be added in the future.
Mnemonics
Mnemonic data may either be denoted by the numeric mnemonic ID, or text mnemonic name. The value will be interpretted as a numeric ID if it is numeric (in XBin encoding), or if it is a string containing only digit characters. If the ID is used, it must already be associated with an existing mnemonic, or an error will be thrown. Otherwise the text will be parsed as follows:
mnemonic = name [ ';' subname ] [ ( '::' unit-enums ) | ( '(' unit-enums ')' ) ]
unit-enums = unit [ ';' enums ]
enums = enum | ( enums [ '|' enum ] )
enum = [ integer '=' ] label
The parsed mnemonic has four elements: the name, subname, unit, and enum map. Only the name is required. The combination of name, subname, and unit are used to lookup an existing mnemonic. The comparison is case insensitive and any whitespace is treated as a single underscore. If a matching mnemonic is not found, a new mnemonic is created automatically. Note that the overall name cannot contain the colon (:), semicolon (;), or dollar sign ($) characters.
The enum map specifies a one-to-one map of integer values to text labels. This is optional and unlike the other parameters, not interpretted as a key component of the mnemonic. They will be included in the generated mnemonic definition if it doesn't exist.
Events
Event operations may also be embedded in structs buffer files. These are indicated by keys which start with the $event macro. The supported operations are inserting, opening, and closing events. Additionally, events may specify a "name" instead of "e_id", which can be used to lookup a corresponding event definition ID, or create a new event definition if one does not exist with the provided name.
For the purposes of the following examples, assume a model "m" contains a pipe "p" with 3 event databases, "e", "ef" (single file per event), and "efs" (multi-file per event).
Insert Event
The insert event macro uses the key $event.insert.<database name>, where the database name must becorrespond presentto an event database in the associated pipe. The value must be a JSON object in the standard record format, with fields appropriate to the specified database. Tthe event must omit the "t_end" value, and may omit the "t_start" value, to be populated by the time value from the corresponding row in the buffer file.
Open Event
Creates a single open event (interval with a start time and no end time). Uses the key $event.open.<database name>. The value must be a single JSON object, defining the content of the event record. It may not include an end time.