Below is a step-by-step explanation of how a dialect can be defined using the XML-based description used by the OnixS C++ FIX Engine. For a complete reference of the definition capabilities take a look at 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 dialects descriptions file.

Note:

Inclusion of <Field> element for 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 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://onixs.biz/fix/dialects" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://onixs.biz/fix/dialects http://onixs.biz/fix/dialects/dialects-2_8.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 class="attribute">tag="21" isRequired="false" name="HandlInst"/> 
      </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 (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://onixs.biz/fix/dialects" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://onixs.biz/fix/dialects http://onixs.biz/fix/dialects/dialects-2_8.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. Such a user-defined message can be used exactly the same way as the standard FIX Message.

Note:

OnixS C++ FIX Engine allows you to send and receive unknown messages by manipulating validation settings. However, defining custom messages using the dialects definitions has important benefits:

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

<?xml version="1.0" encoding="utf-8"?>
<Dialect 
  xmlns="http://onixs.biz/fix/dialects"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://onixs.biz/fix/dialects http://onixs.biz/fix/dialects/dialects-2_8.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", FIX_43);

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, presence of field definition in dialect description file substitutes any entity of same tag number which is already available in the message or 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 certain field and/or repeating group from message or another repeating group. Moreover, sometimes it's necessary to completely exclude certain message from the use. To satisfy the needs, dialect description language offers mode attribute which allows to remove single field, repeating group or even entire message from the dialect. To achieve the results, "remove" value must be specified for this attribute in corresponding dialect entity like <Field>, <Group> and <Message>.

<?xml version="1.0" encoding="utf-8"?>
<Dialect 
  xmlns="http://onixs.biz/fix/dialects" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://onixs.biz/fix/dialects http://onixs.biz/fix/dialects/dialects-2_8.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 Messages and Repeating Groups

With help of mode attribute fields can be removed from repeating groups and messages. However, it's often necessary to completely redefine structure of message and/or repeating group. Removing standard fields and repeating groups on one-by-one basis doesn't sound as simple way to achieve the results. In addition to syntax overhead this way supposes knowledge of message and/or repeating group structure. Therefore, to simplify the task, dialect description language offer "override" value for previously noted mode attribute. Once override mode is defined for either message or repeating group, FIX Engine will replace entire definition of message or repeating group with new one. In such case message and/or 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 same manner as if it's a new group defined. That is first field defined within overridden group will be considered as leading one.; Message overriding doesn't affect 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 existent message.

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

FIX Dialect Description Example

Example of a custom FIX Dialect description file:

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