| EM datagrams on *.kmall format Reg.no. 410224 rev G

Datagram format philosophy

### Philosophy

One of the motivations for implementing the *.kmall format is to be able to add additional data fields to the datagrams without breaking existing decoders. At the same time, the datagram format shall be backwards compatible when future versions of the specific datagrams (e.g. MRZ, MWC) are released. The datagrams need to be decoded in a specific way to be able to support the two mentioned specifications.

### How to decode the datagrams

To support backwards compatibility, some of the datagrams start with the number of bytes in the current struct. Let us take the datagram EMdgmMRZ_def as an example. The third struct in EMdgmMRZ_def is EMdgmMbody_def. The first data field in EMdgmMbody_def contains numBytesCmnPart which is described as denoting the size of current struct. This value tells us how far we shall "jump" to get to the next struct, EMdgmMRZ_pingInfo_def. If new data fields are added to EMdgmMbody_def, the numBytesCmnPart will always make sure we "jump over" the new data fields. If this method is not applied, the first part of EMdgmMRZ_pingInfo_def will contain data from the new data fields, which will cause the decoding to fail.
This decoding methodology is also used for EMdgmMRZ_pingInfo_def. The first data field is numBytesInfoData which is described as number of bytes in current struct. By applying the method previously presented, we will always get safely to EMdgmMRZ_txSectorInfo_def even if new data fields are added to EMdgmMRZ_pingInfo_def.
For EMdgmMRZ_txSectorInfo_def there a slightly other method. EMdgmMRZ_pingInfo_def also contains numTxSectors (Number of transmit sectors) and numBytesPerTxSector (number of bytes in the struct EMdgmMRZ_txSectorInfo). This tells us how far we shall jump from the first byte of EMdgmMRZ_txSectorInfo_def to get safely to EMdgmMRZ_rxInfo_def. And again, in EMdgmMRZ_rxInfo_def starts with numBytesRxInfo (Bytes in current struct).
EMdgmMRZ_extraDetClassInfo_def contains the extra detections data, and contains data if extra detections is enabled, and if so, the number of classes. The size of EMdgmMRZ_extraDetClassInfo_def and the number of classes in EMdgmMRZ_rxInfo_def. To get to EMdgmMRZ_sounding_def, we need to jump numBytesPerClass X numExtraDetectionClasses bytes.
The size of EMdgmMRZ_sounding_def is found in EMdgmMRZ_rxInfo_def in the data field numBytesPerSounding (Bytes per loop of sounding (per depth point)). The number of sounding is found in numSoundingsMaxMain.
The last data in EMdgmMRZ_def is the seabed image sample amplitude SIsample_desidB. The number of samples is found in SInumSamples in EMdgmMRZ_sounding_def.

See the links below an implementation of the decoding of #MRZ:
Example of how to decode #MRZ in C++ or download KMALL_reader.cpp.