Dialect Description : OnixS .NET Framework FIX Engine

Dialect Description

To show how to define a FIX variant Dialect using the XML-based description, there is a step-by-step explanation below. It is used by the OnixS .NET Framework FIX Engine.NET Framework FIX Engine. For a complete reference of the definition capabilities, refer to dialects 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 FIX message in the dialect description file.

Note
Inclusion of a <Field> element for the already registered (e.g. standard) field or group causes OnixS .NET Framework FIX Engine to override its attribute. In this way, the existing field attributes can be modified. This behavior allows you to make a mandatory field or an optional group, and vice versa. As a separate action, the same approach gives the opportunity to replace existing FIX repeating groups with regular fields, and vice versa.

Note

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

As a separate action, the same approach gives the opportunity to replace existing FIX repeating groups with regular fields, and vice versa.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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 dialect. -->
      <Field ctag="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 dialect 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 (i.e. the tag which separates repeating groups entries). If the current definition describes the changes to an existing group, then the original leading tag remains operative.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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 dialect description.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.xsd">

  <FIX version="4.0">
    <Message type="UserDefinedMessage_1">
      <Field tag="100" isRequired="true"/>
      <Field tag="101"/>
    </Message>
  </FIX>
</Dialect>

Copy

Message userDefinedMsg = new Message("UserDefinedMessage_1", ProtocolVersion.FIX40);

userDefinedMsg.Set(100, "Field 100");
userDefinedMsg.Set(101, "Field 101");

userDefinedMsg.Validate();

Console.WriteLine("UDM: {0}", userDefinedMsg);

Copy

Dim userDefinedMsg As New Message("UserDefinedMessage_1", FIXForge.NET.FIX.ProtocolVersion.FIX44)

userDefinedMsg.Set(100, "Field 100")
userDefinedMsg.Set(101, "Field 101")

userDefinedMsg.Validate()

Console.WriteLine("UDM: {0}", userDefinedMsg)

Such a user-defined message can be used in exactly the same way as the standard FIX Message.

Note
OnixS .NET Framework FIX Engine allows to send and receive unknown messages by manipulating validation settings. However, defining custom messages, using the dialect definition, have important benefits: OnixS .NET Framework FIX Engine doesn't differentiate between messages that are defined using custom FIX dialect definitions, from messages that are defined by the FIX Protocol. This gives the opportunity to use strict message validation to check the validity of incoming and outgoing messages. Using custom dialect definitions allows making manipulation of messages of the same complexity as messages that are defined by the Standard and in the same way. This includes messages with repeating groups of any arbitrary nesting level.

Note

OnixS .NET Framework FIX Engine allows to send and receive unknown messages by manipulating validation settings. However, defining custom messages, using the dialect definition, have important benefits:

OnixS .NET Framework FIX Engine doesn't differentiate between messages that are defined using custom FIX dialect definitions, from messages that are defined by the FIX Protocol. This gives the opportunity to use strict message validation to check the validity of incoming and outgoing messages.
Using custom dialect definitions allows making manipulation of messages of the same complexity as messages that are defined by the Standard and in the same way. This includes messages with repeating groups of any arbitrary nesting level.

Removing Fields, Repeating Groups and Messages

As it was previously described, the presence of a field definition in a dialect description file overrides and substitutes any entity of the same tag number which is already available in the message or outer repeating group. In this way, repeating groups can be replaced with regular fields and vice versa. However, sometimes there is a requirement to exclude completely certain fields and/or repeating groups from messages or another repeating group. Moreover, sometimes it is necessary to exclude completely certain messages from use. To satisfy this requirement, the dialect description syntax offers the mode attribute, which allows the removal of a single field, repeating group or an entire message from the dialect. To achieve this result, the "remove" value must be specified for the attribute in the corresponding dialect entry for <Field>, <Group> or <Message>.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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 tag="136" mode="remove"/>
    </Message>

    <!-- "New Order - List" is not supported. -->
    <Message type="E" mode="remove"/>

  </FIX>
</Dialect>

Overriding Existent Definitions of FIX standard dictionary

Using the mode attribute FIX standard dictionary can be overridden. If override mode is defined for either FIX version, FIX Engine will replace the entire definition of FIX version with the new one. In this case, the FIX version will contain only messages, repeating groups and files defined by the description. For example, the description of FIX version 5.0 below will be empty and not contain any definitions at all.

Example

Copy

<?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 use of the mode attribute, fields can be removed from repeating groups and messages. It is also possible to redefine the structure of the message and/or repeating group. It is not necessary to redefine completely the message structures, as this would require detailed knowledge of FIX message and/or repeating group structure and syntax. Therefore, to simplify this task, the dialect description language supports the "override" value for the mode attribute. When the override mode is defined for either a message or repeating group, the FIX Engine will replace the specified definition of the message or repeating group. In this case, the message and/or repeating group will consist only of the fields and inner repeating groups defined by the description.

Note
Once a repeating group is overridden, its leading tag will be changed in the same way as if it is a new group definition, i.e. the first field, defined within the overridden group, will be considered as the leading one.

Note
Message overriding impacts the basic message structure. Only 4 fields will always be present in the overridden message structure: BeginString (8) BodyLength (9) CheckSum (10) MsgType (35) All other fields should be added to the overridden message structure manually.

Note
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 a standard definition of a message is as follows: Copy <?xml version="1.0" encoding="utf-8"?> <Message type="7"> <Field tag="1"/> <Field tag="2"/> <Field tag="3"/> </Message> And the user has defined their custom definition of this message as follows: Copy <?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: Copy <?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.

Note

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 a standard definition of a message is as follows:

Copy

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

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

Copy

<?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:

Copy

<?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.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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>

Using Component Block

You can use the <Component> entity to describe common components in order to use it in all necessary messages. There is a 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.

Example

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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>

Example

Example of a custom FIX Dialect description file:

Copy

<?xml version="1.0" encoding="utf-8"?>
<Dialect
  xmlns="https://ref.onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://ref.onixs.biz/fix/dialects https://ref.onixs.biz/fix/dialects/dialects-2.18.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>

  <!-- Dialect 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>

  <!-- Dialect 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>

Other Resources

Dialect parameter in the Engine configuration file