Except for those Fast session developers, regular applicatio0n developers don't have to have in-depth knowledge about Fast, they can only deal with Fast messages and fields in the API level.
In QWFIX fast implementation, both Fast message or Fast sequence instance are represented as an instance of "FastSegment".
Top level of FastSegment is also called Fast message, which can be created by calling FastSessionContext.CreateSegment. FastSegment is a collection of fast fields.
Each FastSegment contains a reference to a read only instance of FastSegmentInfo. FastSegmentInfo can be used to query the meta data of the segment (message) definition such as information about fields, etc.
There is another class FastFieldInfo that encapsulates the information about a field in a FastSegment. FastFieldInfo is local to FastSegment and should only be retrieve by calling API on FastSegment.
FastFieldInfo can be used as an "access token" to get or set field values in a FAST message. In order to do so, instances of FastFieldInfo should be retrieved and cached after the FastSessionContext is created.
Life Cycle of FastFieldInfo
FastFieldInfo has the same life cycle as the corresponding FastSessionContext. The FastFieldInfo can be retrieved from individual FastSegmentInfo and used to access the content of field later on. However, two different FastSessionContext don't share FastFieldInfo. It has to be retrieved from individual FastSessionContext.
Field Access
QWFIX provides the getter/setter API to get and set the value of fields in a FastSegment. For example: FastSegment.SetValue, FastSegment.GetFieldPresence, FastSegment.SetConstantFieldPresence, FastSegment.ResetFieldPresence, FastSegment.GetIntValue, FastSegment.GetUIntValue, FastSegment.GetDecimalValue, FastSegment.GetStringValue, FastSegment.GetByteVectorValue, FastSegment.GetSequenceValue, and FastSegment.GetReferenceValue.
For more information please refer to the API documentation.
The content of a field can be accessed by Name, ID or FastFieldInfo of that field. Note FastFieldInfo is the most efficient way to access a field.
Data Types
The following table shows the conversion between the Fast data types and the corresponding .Net native data types:
int32, int64 long
uint32, uint64 ulong
decimal double
ascii/unicode string string
byte vector byte[]
sequence FastSegment[]
Type Conversion
If the data type used in FastSegment.SetValue or GetXXXXValue is different than the native data type, a type conversion will be performed. The general rule of type conversion is defined in "8 Type Conversion" in "FAST Specification 1.x.1". For example, if a field has a FAST type of "int32", SetValue(fieldID, "100") will convert the string value to the integer and sent the value of the field as 100.
QWFIX has additional rules regarding the conversion between decimal and integer types. A GetIntValue() on a decimal field will return successfully only if the decimal value does not have fraction; otherwise an exception will be thrown out. The same rule applies for SetValue as well.
In fast specification, each field may have a name and an optional ID. The ID should be an unique unsigned integer.
In QWFIX API, both names and IDs can be used to access fields. In general, using IDs is more efficient than using names.
Uniqueness of Field Identification (Name and ID)
Fast specification requires that the name of the field must be unique inside of a group. However, a dynamic template field doesn't have a name, which makes it an exception. We will discuss how to access those fields below.
Note: Even though we use the combination of both local name and namespace internally to uniquely identify a field (for example, in dictionary handling), we only use the local name in field access API for simplicity reason. Local name of each field in a segment group definition is required to be unique. It is not a lot to ask and should be common sense anyway.
Fast Group Definition
QWFIX is fully Fast specification compliant. Group definition is supported in template definition and GUI based Fast schema editor.
However, for simplicity reason, the Fast Segment API deliberately eliminated the concept of group. In QWFIX, the fields inside a group is "flattened" into the same segment group.
Fast specification only requires the uniqueness of the field names inside a group. So field names in a group may collide with the field names in the parent group. To avoid the potential name conflict we introduced the concept of "Full Name".
If a field is not "directly" defined under a "group", the "Full Name" of the field is the same as the name of the field. However, if it is directly defined under a group, the full name will be in the format of GroupName/FieldName.
For example, considering the following definition:
<template name="CompositeDecimalInstr"
id="16017">
<typeRef name="CompositeDecimalInstr"/>
<templateRef name="FieldBase"/>
<group name="Exponent" presence="optional">
<group name="Operator"> <templateRef/> </group>
<int32 name="InitialValue" presence="optional"/>
<templateRef name="Other"/>
</group>
<group name="Mantissa" presence="optional">
<group name="Operator"> <templateRef/> </group>
<int64 name="InitialValue" presence="optional"/>
<templateRef name="Other"/>
</group>
</template>
Both the "Exponent" group and the "Mantissa" group has the field "Operator". In application, user has to use the full name "Exponent/Operator" or "Mantissa/Operator" to access two different fields. FastFieldInfo.CreateFullName helper method can be used to create full name of a field.
Simplified Group Name Support
In most of the cases, the names defined in a group does not collide with the names in the parent segment group. In that case, both field name and full named can be used to access the same field.
For example, in the following definition:
<template name="TypeRef">
<group name="TypeRef" presence="optional">
<templateRef name="NsName"/>
<templateRef name="Other"/>
</group>
</template>
Both "NsName" or "TypeRef/NsName" can be used to access the same field in the fast segment.
Uniqueness Access Rule for ID
Usually ID is used with the Fast templates derived from FIX schemas. In that case the ID will be guaranteed to be unique within a group.
If there exists ID collide inside a template definition, only the first field in group with the specific ID can be accessed by that ID.
Dynamic Template Reference Field
Dynamic template reference field does not have a name. We provide a special collection FastSegmentInfo.DynamicReferenceFields to list all such fields inside a segment. Application developer should figure out the exact order of field in the list in order to get the correct field.
Special Treatment for Dynamic Reference Field Name
Fast SCP author implicitly suggested a trick to define nameless dynamic reference fields. Such field is better wrapped in an optional group and should be the only field in the group.
For example, in the definition below:
<template name="PrimFieldBase">
<templateRef name="FieldBase"/>
<group name="Operator" presence="optional"> <templateRef/> </group>
</template>
In QWFIX FastSegment API, the dynamic reference field can be accessed with the name (or full Name) of the group name, "Operator".
Please note only the nameless dynamic reference field that is also the ONLY field of a group can be accessed by the group name.
Special Treatment for Sequence Field
It is a common practice to derive a FAST template from a FIX schema. The sequence instruction is FAST message will be derived from a "FIX repeating group".
However, in FIX protocol, only number field of a repeating field is defined (which usually have a name with prefix of "No", such as "NoSides").
To facilitate the field access of such fields, QWFIX FAST API provides a member method FastSegmentInfo.GetFieldInfoBySequenceLengthId.
In this chapter we introduced the fast message and message field access API in QWFIX system. We specially concentrated the unique design features in QWFIX Fast system: