OnixS C++ FIX Engine  3.24.0
API Documentation
Editing Dictionaries Descriptions

Below is a step-by-step explanation of how a dictionary can be defined, using the XML-based description that is used by C++ FIX Engine. For a complete reference of the definition capabilities, take a look at dictionaries definition XML schema.

Enhancing Message with New Field

To add a new field to a FIX Message, add the corresponding <Field> entity to the description of the FIX message in the dictionaries descriptions file.

Note
Inclusion of <Field> element, for the already registered (e.g. standard) field or Group, causes OnixS C++ FIX Engine to overwrite its attribute. In this way, existing field attributes can be modified. This behavior allows to make a mandatory field or group to be optional, and vice versa.

Separately, the same approach gives the opportunity to replace existing FIX repeating groups with regular fields, and vice versa.

<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.0">
<Message type="D">
<!-- Field #526 does not belong to the Standard FIX 4.0. -->
<Field tag="526" name="SecondaryClOrdID" isRequired="true"/>
<!-- Field #21 is required in Standard FIX 4.0, but will be optional in this FIX dictionary. -->
<Field tag="21" name="HandlInst" isRequired="false"/>
</Message>
</FIX>
</Dialect>

Enhancing Message with Repeating Group

To add a new repeating group to a FIX message, add the corresponding <Group> entity to the FIX dictionary description file. The same approach is used to add new fields into an existing repeating group.

Note
In the case of a new group definition, the first field (subgroup) will be used as a leading tag (tag which separates repeating groups entries). If the current definition describes changes to an existing group, then the original leading tag remains operative.
<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.0">
<Message type="D">
<!-- Repeating group for pre-trade allocation (does not belong to the Standard FIX 4.0). -->
<Group numberOfInstancesTag="78" name="NoAllocs">
<Field tag="79" name="AllocAccount"/>
<Field tag="661" name="AllocAcctIDSource"/>
<Field tag="736" name="AllocSettlCurrency"/>
<!-- Other group fields go here. -->
</Group>
</Message>
</FIX>
</Dialect>

Adding Definition of New Message

To define a custom (user-defined) message, add the corresponding <Message> entity to the FIX dictionary description. Such a user-defined message can be used exactly the same way as the standard FIX Message.

Note
OnixS C++ FIX Engine allows to send and receive unknown messages by manipulating validation settings. However, defining custom messages, using the dictionaries definitions, has important benefits:
  • OnixS C++ FIX Engine doesn't differentiate between messages, defined using custom FIX dictionaries definitions, from messages, defined by the FIX Protocol. It gives the opportunity to use a strict message validation to check the correctness of incoming and outgoing messages.
  • Using custom dictionaries definitions allows to manipulation of messages of the same complexity, as messages, defined by the Standard and in the same way. This includes messages with repeating groups of an arbitrary nesting level.
<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.0">
<Message type="UserDefinedMessage_1">
<Field tag="100" isRequired="true"/>
<Field tag="101"/>
</Message>
</FIX>
</Dialect>

In code:

Message udm_1("UserDefinedMessage_1", ProtocolVersion::FIX_40);
udm_1.set(100, "Field 100");
udm_1.set(101, "Field 101");
udm_1.validate();
clog << "UDM: " << udm_1 << endl;

Removing Fields, Repeating Groups and Messages

As it was noted previously, the presence of field definition in a dictionary description file substitutes any entity of the same tag number, which is already available in the message, or in an outer repeating group. In such way, repeating groups can be replaced with regular fields, and vice versa. However, sometimes there's a need to completely exclude a certain field and/or repeating group from a message or another repeating group. Moreover, sometimes it's necessary to completely exclude a certain message from the use. To satisfy the needs, a dictionary description language offers modeattribute which allows to remove a single field, a repeating group or even the entire message from the dictionary. To achieve the results, "remove" value must be specified for this attribute in corresponding dictionary entity like <Field>, <Group> and <Message>.

<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.0">
<Message type="8">
<!-- Partial fill not supported, order is either
filled or canceled. Thus, CumQty not needed. -->
<Field tag="14" mode="remove"/>
<!-- No need in MiscFees group as well. -->
<Group numberOfInstancesTag="136" mode="remove"/>
</Message>
<!-- "New Order - List" is not supported. -->
<Message type="E" mode="remove"/>
</FIX>
</Dialect>

Overriding Existent Definitions of a Standard FIX Dictionary

A standard FIX dictionary can be overridden using the mode attribute . Once override mode is defined for the either FIX version, FIX Engine will replace the entire definition of FIX version with the new one.

In this case, FIX Dictionary will contain the described application-level messages only. For example, the description of the FIX Dictionary with id="Custom_FIX_5.0" below will not contain any application-level messages at all.

<?xml version="1.0" encoding="utf-8"?>
<Dialect>
<FIX version="5.0" mode="override" id="Custom_FIX_5.0">
</FIX>
</Dialect>

Overriding Existent Definitions of Messages and Repeating Groups

With the help of mode attribute fields, it can be removed from repeating groups and messages. However, it's often necessary to completely redefine the structure of message and/or repeating group. Removing standard fields and repeating groups on one-by-one basis doesn't sound as a simple way to achieve the results. In addition to syntax overhead, this way supposes the knowledge of message and/or repeating group structure. Therefore, to simplify the task, a dictionary description language offers "override" value for the previously noted mode attribute. Once an override mode is defined for either a message or a repeating group, FIX Engine will replace the entire definition of the message or the repeating group with a new one. In such case, the message and/or the repeating group will consist only of fields and inner repeating groups, defined by the description.

Note
Once repeating group is overridden, its leading tag will be changed in the same manner, as if it's a new defined group. That is the first field, defined within overridden group, will be considered as the leading one.
Message overriding doesn't affect a basic message structure. That is all fields, from standard message header and trailer (like field which defines type of message), remain untouched. Therefore, there's no need to include definitions for all such fields, when completely overriding structure of the existent message.
<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.4">
<!-- Advertisement is now only text info. -->
<Message type="7" mode="override">
<Field tag="58" name="Text" isRequired="true"/>
</Message>
<Message type="S">
<!-- Completely redefines group to do not use Legs component. -->
<Group numberOfInstancesTag="555" name="NoLegs" mode="override">
<!-- Now tag #588 will be as leading tag in the group. -->
<Field tag="588"/>
<Field tag="8000"/>
</Group>
</Message>
</FIX>
</Dialect>
Warning
If the append mode is used and if the declared element has been already presented in the description of the message, it will be removed from its current position and added to the end of the message.

For example, if standard definition of message is as follows:

<?xml version="1.0" encoding="utf-8"?>
<Message type="7">
<Field tag="1"/>
<Field tag="2"/>
<Field tag="3"/>
</Message>

And user has defined their custom definition of this message as follows:

<?xml version="1.0" encoding="utf-8"?>
<Message type="7">
<Field tag="1"/>
<Field tag="4"/>
</Message>

The result message definition will be as follows:

<?xml version="1.0" encoding="utf-8"?>
<Message type="7">
<Field tag="2"/>
<Field tag="3"/>
<Field tag="1"/>
<Field tag="4"/>
</Message>

In order to control tags order you need to create a custom dialect and describe all tags in a Message or Repeating group in the necessary order with the override mode.

Using Component Block

You can use the <Component> entity to describe common components in order to use it in all necessary messages. There is need to add the name attribute by which you can identify a particular component and use it in all necessary messages. Component Block can contain <Field>, <Group> and even other <Component> entities. When a Component Block occurs in a message description, all described fields from this component are considered as fields directly described in this message.

<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.0">
<!-- Header component description. -->
<Component name="Header">
<Field tag="8" name="BeginString" isRequired="true" />
<Field tag="9" name="BodyLength" isRequired="true" />
<Field tag="35" name="MsgType" isRequired="true" />
<Field tag="49" name="SenderCompID" isRequired="true" />
<Field tag="56" name="TargetCompID" isRequired="true" />
<Field tag="115" name="OnBehalfOfCompID" />
<Field tag="128" name="DeliverToCompID" />
<Field tag="90" name="SecureDataLen" />
<Field tag="91" name="SecureData" />
<Field tag="34" name="MsgSeqNum" isRequired="true" />
<Field tag="50" name="SenderSubID" />
<Field tag="57" name="TargetSubID" />
<Field tag="116" name="OnBehalfOfSubID" />
<Field tag="129" name="DeliverToSubID" />
<Field tag="43" name="PossDupFlag" />
<Field tag="97" name="PossResend" />
<Field tag="52" name="SendingTime" isRequired="true" />
<Field tag="122" name="OrigSendingTime" />
</Component>
<!-- Trailer component description. -->
<Component name="Trailer">
<Field tag="93" name="SignatureLength" />
<Field tag="89" name="Signature" />
<Field tag="10" name="CheckSum" isRequired="true" />
</Component>
<Message type="A">
<!-- Using fields from Header component. -->
<Component name="Header" />
<Field tag="98" name="EncryptMethod" isRequired="true" />
<Field tag="108" name="HeartBtInt" isRequired="true" />
<Field tag="95" name="RawDataLength" />
<Field tag="96" name="RawData" />
<!-- Using fields from Trailer component. -->
<Component name="Trailer" />
</Message>
</FIX>
</Dialect>

FIX Dictionary Description Example

An example of a custom FIX Dictionary description file:

<?xml version="1.0" encoding="utf-8"?>
<Dialect
xmlns="http://ref.onixs.biz/fix/dialects"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://ref.onixs.biz/fix/dialects http://ref.onixs.biz/fix/dialects/dialects-2_14.xsd">
<FIX version="4.3">
<Message type="W">
<!-- Optional field which may present in the message. -->
<Field tag="64" name="FutSettDate"/>
</Message>
<Message type="y">
<Group numberOfInstancesTag="146" name="NoRelatedSym">
<!-- An additional field in the existing repeating group. -->
<Field tag="64" isRequired="true" name="FutSettDate"/>
</Group>
</Message>
</FIX>
<!-- Dictionary to be used locally by single or more sessions. -->
<FIX version="4.3" id="ForTradeWithNewXMessage">
<Message type="X">
<Field tag="55" name="Symbol"/>
<Field tag="64" name="FutSettDate"/>
</Message>
</FIX>
<!-- Dictionary for simplified trading. -->
<FIX version="4.0">
<!-- All orders are of market type. -->
<Message type="D" mode="override">
<Field tag="54" name="Side" isRequired="true"/>
<Field tag="55" name="Symbol" isRequired="true"/>
<Field tag="53" name="Quantity" isRequired="true"/>
</Message>
<!-- "New Order - List" is not supported. -->
<Message type="E" mode="remove"/>
<!-- Partial fill is not supported. -->
<Message type="8">
<Field tag="14" mode="remove"/>
</Message>
</FIX>
</Dialect>