Control of SBE Coding Process

The custom coding library allows to manage particular aspects of encoding or decoding without creating of custom coders.

Such control is provided via single entry point: OnixS::FIX::SBE::ISbeCustomCoderLibrary::queryCodingControl. This method is called for each FIX field of all messages in the SBE template and has two arguments:

• Metadata of the field which encoding settings are requested (OnixS::FIX::SBE::SbeFieldMetaData);
• Object of the OnixS::FIX::SBE::SbeFieldCodingSettings type that provides the ability to change and read encoding parameters for the field.

The OnixS::FIX::SBE::SbeFieldCodingSettings object provides access to the following settings:

UseFormattedDateTime (Setting date and time encoding)

Methods: OnixS::FIX::SBE::SbeFieldCodingSettings::useFormattedDateTime(bool) and OnixS::FIX::SBE::SbeFieldCodingSettings::useFormattedDateTime().

This setting is suitable for the cases when the time-aware field represented on the wire level as a number of particular "time units" since particular "epoch".

Natural examples of such fields are fields with one of the following semantic types: UTCTimestamp, UTCDateOnly, UTCTimeOnly, LocalMktDate. These fields are often encoded using a simple binary field or a composite field consisting of only one OnixS::FIX::SBE::SbePresence::Required field and one OnixS::FIX::SBE::SbePresence::Constant field.

When the setting is true (default)

When the value is true the FIX field must appear in one of the valid date&time format: YYYYMMDD-HH:mm:SS, HH:mm:SS.sss, etc. Exact format depends on the semantic type of the field and on the time unit that are specified in the SBE template.

• Encoding: the string value of the FIX field is scanned and converted into a binary value in accordnace to the field's epoch;
• Decoding: the wire-level binary value is formatted in accordance to the field specification. The formatted value is placed to the FIX message or posted via callback of the event-based decoder.

When the setting is false

When the value is false the FIX field does not converted to/from formatted string presentation, i.e. it must be an integer value.

• Encoding: the encoder expects the field is an integer value.
• Decoding: the wire-level value is used without additional conversion: it is assigned to the field of the FIX message or reported via callback of the event-based decoder.

UseValueNamesExternally (Setting for multivalue types encoding)

This setting is available via the methods: OnixS::FIX::SBE::SbeFieldCodingSettings::useValueNamesExternally(bool) and OnixS::FIX::SBE::SbeFieldCodingSettings::useValueNamesExternally(). It is suitable for the cases of <enum> and <set> fields that has a number of named values that can (for <set>) or can not (for <enum>) be combined.

Such fields are encoded using a simple wire-level numeric value that can be composed from separate bits (for <set>) or chosen from a list of known values (for <enum>).

Default value for the setting is false.

When the setting is true

When the setting is true the appropriate FIX field should use value names that are specified in the SBE template (the "name" attribute of the corresponding XML node that describes the value).

The exact use of names depends on the field type and the operation:

Type	Operation	Usage of the value name and raw value
<enum>	Encoding	The FIX field must contain exactly one name of the value from the list of valid ones.
<set>	Encoding	The FIX field must consist of valid value names delimited with spaces.
<enum>	Decoding	The resulting FIX field will contain exactly single value name that corresponds to the wire-level data.
<set>	Decoding	The resulting FIX field will be composed from names of the set elements that appear in the decoding value. These names will be delimited with spaces.

Note

The term "Resulting FIX field" refers to the portion of the FIX message or the value reported via the event-based decoder callback.

The following tables explain the encoding, assuming we have the following definitions for set and enum:

<set name="Fruits" encodingType="uInt8">
   <choice name="Apple">0</choice>
   <choice name="Orange">1</choice>
   <choice name="Peach">2</choice>
</set>
<enum name="Colors" encodingType="uInt8">
   <validValue name="Red" description="Red color">7</validValue>
   <validValue name="Green" description="Green color">5</validValue>
   <validValue name="Blue" description="Blue color">2</validValue>
</enum>

Encoding:

Type	FIX field value	Resulting raw value (hex)	Notes
<set>	"Apple Orange"	0x03	The value is composed by the bitwise OR operation between bits that correspond to the "Apple" (bit0 that is 0x1) and "Orange" (bit1 that is 0x2) choices. The result value is: 0x1+0x2=0x3.
<enum>	"Red"	0x07	This is the value of the corresponding validValue node.

Decoding:

Type	Raw value (hex)	Resulting FIX field value	Notes
<set>	0x03	"Apple Orange"	Non-zero bits are used as keys to search the proper choices. The result value is concatenation of corresponding choice names via the single space. In the case there are two bits used (bit0 and bit1) that correspond to the Apple and Orange choice names. The result value is: "Apple" + " " + "Orange".
<enum>	0x07	"Red"	The raw value 7 is used as a key of the corresponding validValue node, which name ("Red") is the result of the operation.

When the setting is false (default)

If set to false, there is no name-value mapping, but the encoder or decoder still validates the FIX field or the raw value (respectively).

• Encoding: the field value is expected to contain a single valid value (for <enum>) or a bitwise combination of valid choices (for <set>);
• Decoding: the raw value after validation is assigned to the FIX field, or posted via callback of the event-based decoder.

Default values

Setting	value
useFormattedDateTime	true
useValueNamesExternally	false