FIX Configuration

FIX configuration is the most crucial task for controlling behavior of FIX sessions. This section of the FF.FIX Engine Knowledgebase introduces you to FIX sessions, the types of applications from FF.FIX Engine's perspective and FIX configuration in details.

• FIX sessions
• Initiator and Acceptor applications
• FIX configuration file
• FAQ

FIX sessions

The bidirectional exchange of sequential messages between two trading parties in the FIX Protocol specified manner is referred to as a FIX session. A FIX session gets established when a Sell-side party successfully authenticates and validates the session initiating Logon message from its Buy-side party and responds it with a counter-Logon message.

Practically, trading parties are rarely fully FIX compliant. They follow different FIX Protocol versions and implement customizations as required. Hence, the FIX session logic differs from party to party. The FIX session attributes also differ from party to party. For example: SenderCompID, TargetCompID, sub IDs, IP addresses, port addresses, policy for message recovery etc.

For having a smooth FIX session, parties to the session mutually agree to certain specifications called as Rules of Engagement. Practically, a Buy-side party accepts the Sell-side party's norms for connecting to it. The Rules of Engagement include information like FIX Protocol version, allowed FIX messages, message customizations, allowed fields in messages, allowed fields in message Headers etc. Party's own session logic includes message recovery mechanism, message latency checks, Message Throttling settings, event logging etc

Initiator and Acceptor applications

A FIX Protocol based messaging and order processing solution requires a software application that can:

• Manage messaging connectivity with counterparties in a robust and scalable manner and with speed.
• Hold several simultaneous FIX sessions with different counterparties.
• Provide persistence for messages and events during sessions.
• Process FIX messages based on the business logic of the organization and the FIX Protocol specifications.
• Allow customization of standard message types, custom message types and fields, customized field value enumerations etc.
• Integrate seamlessly with an existing Order Management System or trading application of the organization so that its user can trade without ever knowing the FIX Protocol and concentrate on business rather than the communication process.

FF.FIX Engine enables you develop solutions or required programmatic components and integrate them with your existing trading application. The rich API library and supplementary tools in FF.FIX Engine enable you to easily develop your application and deploy it quickly.

In the real-time scenario, there are purely Buy-side organizations, purely Sell-side organizations and a combination of both. Hence, the role of your application in managing FIX sessions may differ depending on your counterparties. An Initiator (Buy-side) application always sends a session initiating Logon message to its Sell-side counterparty. On the contrary, an Acceptor (Sell-side) application listens to session initiating Logon messages from several Buy-side counterparties, authenticates and validates them against the Rules of Engagement allows a session after successful validation and authentication. Your actual application can be a combination of Initiator and Acceptor types.

Due to two distinct modes of FIX session creation by instances of Initiator and Acceptor classes, FF.FIX Engine documentation categorizes FF.FIX Engine based applications as Initiator and Acceptor applications only. Further, from the FF.FIX Engine's perspective, FIX sessions are of two types: FIX Initiator sessions held by an Initiator (Buy-side) application and FIX Acceptor sessions held by an Acceptor (Sell-side) application.

FIX configuration file

Each instance of the Initiator class behaves like a Buy-side party and deals with a single Sell-side counterparty. An Initiator instance implements its counterparty dependent session logic and rules using its FIX configuration file of Initiator type.

On the contrary, a single instance of the Acceptor class behaves like a Sell-side party and accepts connections from several registered Buy-side counterparties. It implements counterparty dependent session logic and rules using FIX configuration files of Acceptor type. It uses separate configuration files for each of its counterparties.

Since FIX configuration files are merely declarative files in XML format, they let you use the same code for different counterparties rather than hard coding each counterparty's requirements separately. Their XML format makes it easy for users to edit them and change the session behavior whenever required and without a need to update the code. This feature of FIX configuration files makes your application flexible and customizable. All you need to do is to define the XML file name and location in your code. After that real-time users can replace it with a modified file having the same name and control the session behavior as required.

The following block shows structure of typical FIX configuration files for Initiator and Acceptor instances. The first line of the configuration file is the declaration of XML version and encoding style. Different elements, sub elements and keys thereafter specify the functional behavior of the associated FIX session.

::FAQ::

1. Which elements and attributes does a typical FIX configuration file for an Initiator application contain?
2. Which elements and attributes does a typical FIX configuration file for an Acceptor application contain?
3. How do I set an FIX configuration file for an Initiator or Acceptor application?
4. What are the common attributes and elements that define the session behavior in Acceptors and Initiators?
5. Which preliminary message validations does FF.FIX Engine perform?
6. Which Inbound and Outbound Message validation levels are available to me? Can I implement my own custom validation level?
7. What are GapFill situations? How do I deal with them?
8. If there is a GapFill situation on my side, how can I react? If I send a ResendRequest message to my counterparty, what are the possible responses?
9. How does the FF.FIX Engine implementation respond to GapFill situations?
10. What are the different settings in the <MessageRecoveryRule> element?
11. How do I set standard Header fields from the configuration file?
12. How do I set the FIX session activation schedule?
13. How do I select the persistence media and customize events to be logged during a session?
14. Can I define custom attributes for internal use and for programming convenience?
15. Which specific attributes and elements are required in the configuration file for a session Initiator application?
16. How can I conduct a FIX session using a secured socket connection?
17. How do I control the session logic in Initiator and Acceptor applications based on FF.FIX Engine?
18. Which specific attributes and elements are required in the configuration file for a session Acceptor application?
19. How do I specify a FIX configuration file programmatically?
    

A FIX configuration file zaxInitiator.config for a sample Initiator application 'zaxInitiator' is presented below. It contains different attributes and elements required by a typical Initiator application. In addition to the FF.FIX Engine supported attributes and depending on your programming requirements, you may add your own custom attributes in the <CustomAttribute> element.

A FIX configuration file zaxAcceptor.config for a sample Acceptor application 'zaxAcceptor' is presented below. It contains different attributes and elements required by a typical Acceptor application. In addition to the FF.FIX Engine supported attributes and depending on your programming requirements, you may add your own custom attributes in the <CustomAttribute> element.

In the <Session> element of the configuration file, set the ConnectionType key value depending on the application type, Acceptor or Initiator. If your application shall perform as an Acceptor, use the Acceptor value. Otherwise, use the Initiator value.

For example, in the FIX configuration file for an Acceptor application, you need to set this value as:

The configuration file for Initiator includes <Initiator> element that defines attributes specific to the Initiator applications. The configuration file for Acceptor includes <Acceptor> element that defines attributes specific to the Acceptor applications. Other elements and keys are common to both types of applications.

The <Session> element appears in Initiator as well as Acceptor configuration files. It defines the FIX session behavior in different situations.

The <Session> element includes:

• <MessageRecoveryRule> element: It includes keys to control the FIX session behavior in GapFill situations.
• <StandardHeaderFieldValue> element: It includes the keys which define Header fields in Outbound FIX Messages, as required by you. These fields appear in the Header of each message you send to the counterparty. After setting Header fields by configuring this element, you can proceed to remaining FIX Message construction tasks, that is, the construction of Body parts of FIX Messages as per your business requirements. FF.FIX Engine relieves you from intricacies of FIX Protocol related to Header fields and helps you concentrate on your business logic.

The <Session> element also includes the following attributes (keys).

• ConnectionType: A mandatory key. The possible values are Initiator and Acceptor. To configure your application as an Initiator or Acceptor application, select the corresponding value.

For example:

<add key="ConnectionType" value="Initiator" />

• MillisecondInTimeStamp: An optional key. It specifies whether the value of the SendingTime field (tag 52) shall include milliseconds or not. The possible values are Y and N. If you do not define this key, FF.FIX Engine assumes N as the default value.

  For example

  With the following setting, the tag=value pair can look like 52=20060516-09:12:59.408.

  <add key="MillisecondInTimeStamp" value="Y" />

  With the following setting, the tag=value pair can look like 52=20060516-09:12:59.

  <add key="MillisecondInTimeStamp" value="N" />

• DataDictionary: An optional key. It specifies the path (including the name) of the Data Dictionary file. The path should be relative to the XML configuration file. If the path is unspecified, the application uses the application directory path as the default path. For example:

  <add key="DataDictionary" value="XYZDataDictionary.xml" />

  If you do not define this key, FF.FIX Engine uses no Data Dictionary.

  However, the Data Dictionary is essential if your FIX application is required to support Repeating Groups of fields, custom fields, data type fields, custom messages etc. In the absence of Data Dictionary, your application will not be able to parse Inbound Message strings properly, if they contain such items. The Data Dictionary plays an important role in parsing FIX Messages and in their validation. Hence, it is desirable to create counterparty-specific separate Data Dictionaries.

  FF.FIX Engine includes FF.FIX ROE tool. It is a graphical user interface for quick creation of Data Dictionary files in XML format. The FF.FIX ROE tool lets you define custom fields, customized messages and perform other Data Dictionary related tasks.

• SocketBufferSize: A physical connection with the counterparty occurs through a socket connection interface. The socket maintains two kinds of buffers: A send buffer and a receive buffer. Before delivering the data to the destination, it is stored in the send buffer. Similarly, the data received from the sender is stored in the receive buffer and then it is submitted to the receiving application.

  The optional key SocketBufferSize defines the size of socket buffers in bytes. If you do not define this key, FF.FIX Engine takes 1024 bytes as the default value. However, the actual FIX Messages are often larger than this size. For a better throughput, it is desirable that you increase the socket buffer size appropriately using this key. If you set a value smaller than 1024, FF.FIX Engine takes the minimum default value of 1024 bytes.

  For example:

  <add key="SocketBufferSize" value="2048" />

• HeartBtInt: An optional key. It represents the time interval in seconds between two successive Heartbeat messages sent by a party. If you do not define this key, FF.FIX Engine assumes a default value of 30 seconds. The HeartBtInt time counter starts from the time of sending the last message. After sending the last message, if a party has no other message to send in the subsequent period of 'HeartBtInt' seconds, it must send a Heartbeat message, as an indication that it is alive in the session.

  To avoid unnecessary GapFill situations, the parties to a session mutually agree to a suitable HeartBtInt value prior to the session start. They include this agreed value in their Logon and counter-Logon messages at the beginning of the session. This value is typically 30 seconds for most parties. The FIX Protocol allows a value of zero for the HeartBtInt, though it is not common in use. If HeartBtInt = 0, the parties send no regular Heartbeat messages to each other. HeartBtInt cannot be negative.

  For example:

  <add key="HeartBtInt" value="30" />

• HeartBtIntDelta: The FIX Protocol specifies that if a trading party does not receive any message from its counterparty for a sufficiently long period, it can send a TestRequest message to check if the counterparty is alive in the session. The FIX Protocol allows terminating the connection if the counterparty still fails to reply with a Heartbeat message in response to the TestRequest message within a reasonable time.

  FF.FIX Engine allows you to set this reasonable time in terms of number of TestRequest messages (using the MaxTestRequestGeneratedInRow key in the <SessionLogic> element) and the 'HeartBtIntDelta' period.

  The optional key HeartBtIntDelta defines the waiting period in seconds before sending a TestRequest message.

  The waiting period begins since the time of missing a Heartbeat from the counterparty. FF.FIX Engine sends a first TestRequest message after a period of 'HeartBtInt + HeartBtIntDelta' seconds, counted from the time of receipt of the last Inbound Message from the counterparty. Thereafter it regularly sends TestRequest messages after each 'HeartBtIntDelta' seconds, until it receives the response from the counterparty or until it exhausts the MaxTestRequestGeneratedInRow limit, whichever occurs earlier.

  The 'HeartBtIntDelta' period acts as a time interval between two successive TestRequest messages too. The HeartBtIntDelta value must less than the HeartBtInt value. If you do not define the HeartBtIntDelta key, FF.FIX Engine assumes a default value of 20 seconds.

  You can set the HeartBtInt and HeartBtIntDelta key values suitably depending on your experience with network latency. Too small values for HeartBtIntDelta key can result into unnecessarily large number of TestRequest messages and GapFill situations. The typical value for HeartBtIntDelta key can be 20 seconds, if the HeartBtInt key value is set to 30 seconds.

  For example:

  <add key="HeartBtIntDelta" value="20" />

• PersistHeartBtInt: To comply with GapFill requests from the counterparty and for having internal records of Inbound and Outbound Messages, a party needs to store those messages in some persistence medium.
  

  However, if two parties in an ongoing session do not exchange business messages for a long time, their persistence medium would get flooded with a huge number of Heartbeat messages. The persisted Heartbeat messages are of no further use.

  FF.FIX Engine offers you an option of not recording Heartbeat messages in your persistence medium and save disk space using the optional key PersistHeartBtInt. The possible values for this key are Y and N. Select the value N, if you do not wish to store Heartbeat messages in the persistence medium. If you do not define this key, FF.FIX Engine assumes Y as the default value and stores Heartbeat messages in the persistence medium.

  For example:

  <add key="PersistHeartBtInt" value="N" />

• MaxMessageSize: It is possible to construct huge FIX Messages which may contain images, junk information etc. In the real-time business scenario, it is always desirable to have short messages (typically in kilobytes) for achieving high processing speeds. If your counterparty tends to slow down your application by unnecessarily long messages (typically in megabytes), the FIX Protocol specifies an optional field MaxMessageSize (tag 383) in the Logon message to take care of such situations.

  FF.FIX Engine implements this provision using the optional key MaxMessageSize. If the Inbound Message size exceeds the set value of MaxMessageSize key, FF.FIX Engine rejects the message with the appropriate reason.

  The minimum value for this key is 1024 bytes. If you set a lower value, FF.FIX Engine treats it as 1024 bytes. When you set this key, FF.FIX Engine automatically adds this value at the tag number 383 of the Logon or counter-Logon message, depending on its role as the Initiator or Acceptor respectively. If you do not define this key, there is no restriction on the size of Inbound Messages.

  For example:

  <add key="MaxMessageSize" value="2048" />

  If your counterparty sets a similar limit on its Inbound Messages (and your Outbound Messages), it has to communicate the same to you through its Logon message. A mutual agreement on the MaxMessageSize field value is desirable. You can suitably respond to such restrictions through your application.

• InboundMessageValidationLevel: By default, FF.FIX Engine validates each Inbound Message for its BodyLength and CheckSum field values and rejects it if found erroneous.

  Accordingly, the optional key InboundMessageValidationLevel has five possible values: NO, LOW, MEDIUM, HIGH and CUSTOM. If you do not define this key, FF.FIX Engine takes LOW as the default value.

  Higher validation levels reduce the processing speed. It is reasonable to select a validation level depending on your experience with the counterparty and your own FIX implementation. When an Inbound Message fails on validation tests, FF.FIX Engine sends a Reject message to the counterparty with an appropriate reason in it.

  For example:

  <add key="InboundMessageValidationLevel" value="LOW" />

• OutboundMessageValidationLevel: The entire description for the InboundMessageValidationLevel key also applies to the optional key OutboundMessageValidationLevel. The only difference is that FF.FIX Engine does not send an Outbound Message to the counterparty, if it fails against the set Outbound Message validation level.

  In the real-time trading activities, it is a good practice to set the Outbound Message validation level to the value NO and increase performance of your FF.FIX Engine based application. This is logical because it is your own application that would generate the message strings and those stings would be flawless if your application performs well. Hence there is no point in revalidating the same message and compromise on the processing speed. However, you may set higher validation levels for Outbound Messages during the testing phase to verify that your application generates correct message strings.

  For example:

  <add key="OutboundMessageValidationLevel" value="NO" />

• MessageThrottleValue: Message Throttling enables you to limit the rate of receipt of Inbound Messages during a FIX session. The optional key MessageThrottleValue specifies the maximum number of Inbound Messages that your application can receive from the counterparty in one second in a non-GapFill situation. If you do not define this key, the Message Throttling feature becomes unavailable.

  For example:

  <add key="MessageThrottleValue" value="1000" />

  When the message receiving rate exceeds the set MessageThrottleValue value, the FIX Session intimates the user to take a suitable action through a call back routine InBoundQueueThrottleValueReached defined in the FixSessionHandler class.

• ResetOnLogon: The FIX Protocol allows mutual resetting of message sequence numbers to zero after specific events like Logon, Logout and disconnect. Sequence number resetting does not affect the earlier messages in the persistence media. The earlier orders stand as they are. However, the sequence number resetting affects the GapFill process. The messages recoverable in a GapFill situation are the messages exchanged after the last sequence number reset operation. The messages prior to the last sequence number resetting are not recoverable during the GapFill process.

  You and your counterparty may agree to treat each Logon message as a new beginning and reset message sequence numbers to zero. Such a Logon message can be sent during an ongoing session too. For example, if you send a Logon message with the ResetSeqNumFlag field (tag 141) equal to a value Y, then your counterparty must reset its outbound and inbound sequence numbers to zero. After this, the next Outbound Message from you or your counterparty would bear the message sequence number 1.

  FF.FIX Engine implements this logic automatically using the optional key ResetOnLogon. Select the value Y, if you wish to reset message sequence numbers with every Logon message. Otherwise, select the value N. If you do not define this key, FF.FIX Engine assumes N as the default value.

  For example:

  <add key="ResetOnLogon" value="Y" />

• ResetOnLogout: You and your counterparty may agree to treat each Logout message as a new beginning and reset message sequence numbers to zero. When a FIX session begins after this, both parties would send their first Outbound Message with the sequence number '1'.

  FF.FIX Engine implements this logic using the optional key ResetOnLogout. Select the value Y, if you wish to reset message sequence numbers with every Logout message. Otherwise, select the value N. If you do not define this key, FF.FIX Engine assumes N as the default value.

  For example:

  <add key="ResetOnLogout" value="Y" />

• ResetOnDisconnect: The FIX Protocol treats the abnormal disconnection of a FIX connection as an error. You and your counterparty may agree to begin afresh after each abnormal disconnection of the FIX connection. While reestablishing a FIX session after an abnormal disconnection, both parties would send their first Outbound Message (Logon and counter-Logon messages) with the sequence number '1'.

  FF.FIX Engine implements this logic automatically using the optional key ResetOnDisconnect. Select the value Y, if you wish to reset message sequence numbers with every abnormal disconnection during a FIX session. Otherwise, select the value N. If you do not define this key, FF.FIX Engine assumes N as the default value.

  For example:

  <add key="ResetOnDisconnect" value="Y" />

Prior to validating an Inbound Message against the set Inbound Message validation level, FF.FIX Engine performs the following preliminary message validation tests:

• Message syntax validation: A FIX Message is a sequence of field tags and their values in the <tag>=<value><SOH> syntax. If an Inbound Message does not follow this syntax, it indicates a serious application error on the counterparty's side. FF.FIX Engine terminates the connection with the counterparty when it encounters such a message.
• Garbled message and tag 34 test: If the Inbound Message has a proper syntax, FF.FIX Engine proceeds to test it against the criteria for garbled messages and presence of tag 34 (MsgSeqNum field).

A garbled message is the message that satisfies any of the following conditions:

• BeginString (tag 8) is not the first tag in the message or not in the 8=FIX.m.n format, where m and n represent the major and minor FIX Protocol version respectively.
• BodyLength (tag 9) is not the second tag in the message or does not contain the correct byte count.
• MsgType (tag 35) is not the third tag in the message.
• CheckSum (tag 10) is not the last tag or contains an incorrect value.

The FIX Protocol presumes garbled messages as transmission errors rather than as a problem with the FIX system. It recommends to ignore such messages without incrementing the Inbound Message sequence number. This results in a GapFill situation on receiving the next valid message and the FIX implementation then automatically generates a ResendRequest message to recover the earlier garbled/unparsed message.

If the counterparty sends a series of garbled messages, the ignorance of such messages is not a sufficient action. By default, FF.FIX Engine terminates the FIX session after 5 successive garbled messages. You can change this default behavior of FF.FIX Engine by overwriting the default implementation in the associated callback.

The absence of tag 34 in the message indicates a serious application error on the counterparty's side. FF.FIX Engine sends a Logout message and terminates the FIX connection in that case.

By default, FF.FIX Engine validates all FIX Messages for their BodyLength and CheckSum and rejects them if found erroneous. In addition to these default validations, FF.FIX Engine provides five levels of Inbound and Outbound Message validation. Accordingly, the five values for the optional keys InboundMessageValidationLevel and OutboundMessageValidationLevel are NO, LOW, MEDIUM, HIGH and CUSTOM. If you do not define any of these keys, FF.FIX Engine assumes LOW as the default value.

When an Inbound Message fails against the set validation level, FF.FIX Engine rejects it with an appropriate reason in the Reject message to the counterparty. When an Outbound Message fails against the set validation level, FF.FIX Engine does not send it to the counterparty.

Since higher validation levels reduce the processing speed, you should set the validation level depending on your FIX implementation and your experience with the counterparty.

It is a good practice to set the Outbound Message validation level to the value NO and increase performance of your FIX implementation. This is logical because it is your own application that would generate the message strings and those stings would be flawless if your application performs well. Hence there is no point in revalidating the same message and compromise on the processing speed. However, you may set higher validation levels for Outbound Messages during the testing phase to verify that your application generates correct message strings.

FF.FIX Engine also allows you to override the message validation levels in the configuration file programmatically, so that you can deal with specific situations.

The five message validation levels are:

• NO Message Validation: FF.FIX Engine performs no message validation beyond the default BodyLength and CheckSum checks. Defining the DataDictionary key in the configuration file is not essential if you select this option.
• LOW Message Validation: In addition to the default validation, FF.FIX Engine performs validation of three more fields: BeginString (tag 8), SenderCompID (tag 49) and TargetCompID (tag 56). Defining the DataDictionary key in the configuration file is not essential if you select this option.
• MEDIUM Message Validation: In addition to the default validation, FF.FIX Engine performs the validation of four more fields: BeginString (tag 8), SenderCompID (tag 49), TargetCompID (tag 56) and MsgType (tag 35). For selecting this option, you must define the DataDictionary key in the configuration file.
• HIGH Message Validation: For selecting this option, you must define the DataDictionary key in the configuration file. In this option, in addition to the default validation, FF.FIX Engine performs the validation of:
  
  • Four important fields: BeginString (tag 8), SenderCompID (tag 49), TargetCompID (tag 56) and MsgType (tag 35).
  • Presence of all required (mandatory) fields as per the message definition in the Data Dictionary.
  • Data types of field values.
  • Values of enumerated fields for allowed values.
• CUSTOM Message Validation: For selecting this option, you must define the DataDictionary key in the configuration file. In this option, you can select some important attributes from the FF.Fix.Core.FixMessageValidationRule class for validation.

Each Outbound Message from you or your counterparty must bear a message sequence number in the natural number sequence. A GapFill situation occurs when a party misses one or more Inbound Messages.

For example, if you received a message with sequence number 25 and the next Inbound Message bears the sequence number 45, it becomes a GapFill situation for you. The messages you missed may be important for you. You can send a ResendRequest message to your counterparty to recover the messages in the message gap from 26 to 44. FF.FIX Engine implementation on your side performs this task for you.

A GapFill situation can also occur on the counterparty side and it may send a ResendRequest message to you to recover the lost messages. FF.FIX Engine offers you different message recovery rule options in the <MessageRecoveryRule> sub element of the <Session> element of the configuration file.

During a FIX session, a GapFill situation occurs whenever the sequence number in an Inbound Message differs from the next expected sequence number. Depending on the party's session logic, it can respond to the GapFill situation in different ways:

1. On detecting a gap in Inbound Message sequence numbers, a party sends a ResendRequest message to the counterparty to recover the messages in the gap. This is a common behavior. FF.FIX Engine implementation on your side does the same.
2. On detecting a gap in Inbound Message sequence numbers, a party may respond with a SequenceReset-Reset message to its counterparty and force the counterparty to reset the sequence number to a number specified at tag 36. Then the messages in the gap are lost and the GapFill situation ends through forced resetting of the sequence number.

   However, such a behavior is rare. No party would prefer to lose messages that way. When the GapFill situation occurs on your side, FF.FIX Engine implementation on your side does not send a SequenceReset-Reset message and make you lose the non-received messages which may be important to you.

Your counterparty may respond to your ResendRequest message in three ways:

1. The counterparty resends the messages requested by you. You lose no messages then.
2. The counterparty may decide not to send some original messages for some reason. It then replies to you with a SequenceReset message having the GapFillFlag field (tag 123) set to the value Y. It is an indication to you that you must accept the SequenceReset message as the gap-filling message over one or more requested messages in a sequence and reset your inbound sequence number to a new number specified by the counterparty at tag 36 of the message.

   A SequenceReset message of this type is called SequenceReset-GapFill message. It is useful to fill a gap over Admin Messages in a row, which need not be resent. (Note: Admin Messages have no business contents and need not be resent.)

   For example, in the message gap from 26 to 98, messages from 52 to 64 are Admin Messages. Then your counterparty would send a SequenceReset-GapFill message having 34=52, 123=Y and 36=65. It indicates that the resent message no 52 is a replacement for messages from 52 to 64 and the next message would be sent with sequence number 65.
3. The counterparty may decide to ignore the past messages and rather force you to continue with the current message number only.

   For example, the message gap is from 26 to 98 and you sent a ResendRequest message for the same. Then the counterparty would respond to you with a SequenceReset message having 123=N (or no tag 123 at all) and 36=99. It means that your counterparty dictated you to continue with new sequence number 99 without resending the lost messages.

   Such a SequenceReset message is known as SequenceReset-Reset message. It does not contain tag 123 or it has tag 123=N.

1. On detecting gaps in the Inbound Message sequence numbers, FF.FIX Engine sends a ResendRequest message to the counterparty to recover the lost messages.
2. If your counterparty detects gaps in its Inbound Message sequence numbers and sends a SequenceReset-Reset message, FF.FIX Engine complies with the message and sets the Inbound Message sequence number to the new value dictated by the counterparty at tag 36.
3. If your counterparty detects gaps in its Inbound Message sequence numbers and sends ResendRequest message, FF.FIX Engine complies with that message according to the message recovery rules you specified in the <MessageRecoveryRule> sub element of the <Session> element of the configuration file.

   The mandatory key RuleType in the <MessageRecoveryRule> element has three possible values, corresponding to the three situations given below:

   • AlwaysSequenceResetReset: FF.FIX Engine forces the counterparty to ignore earlier sequence numbers and synchronize its Inbound Message sequence number to the new sequence number specified by FF.FIX Engine at the tag 36 of its SequenceReset message. FF.FIX Engine internally assigns the current outbound sequence number value to the tag 36.
   • AlwaysGapFill: FF.FIX Engine complies with the counterparty's ResendRequest message by resending the requested messages with PossDupFlag field (tag 43) value set to Y. For Admin Messages it sends an appropriate SequenceReset-GapFill message.
   • AlwaysGapFillOverBusinessMessages: Instead of resending a business message (Application Message), FF.FIX Engine sends a SequenceReset message to the counterparty with 123=Y (GapFillFlag field). It indicates that the requested business message would not be sent and the SequenceReset message is replacing it. Then the counterparty has to reset its inbound sequence number to the new value of tag 36 in the SequenceReset message sent by FF.FIX Engine.

The mandatory sub element <MessageRecoveryRule> in the <Session> element defines how your application responds to GapFill situations. The following code shows the typical structure of this element.

The following keys decide the message recovery mechanism:

• RuleType: A mandatory key. The allowed values are: AlwaysSequenceResetReset, AlwaysGapFill and AlwaysGapFillOverBusinessMessages.
• MaximumMessageAllowedInResendRequest: An optional key. It is relevant only when you select AlwaysGapFill or AlwaysGapFillOverBusinessMessages as the value of the RuleType key.

  If your counterparty burdens your FIX implementation with a ResendRequest message for arbitrarily large number of messages, this key is the excellent solution to avoid it. Using this key, you can set the maximum number of messages allowed in a ResendRequest. If your counterparty requests to resend more messages than the value of this key, FF.FIX Engine sends a reject message with an appropriate reason.

  You can disable this option by assigning the '*' value to this key. Then there is no restriction on number of resent messages. If you do not define this key, FF.FIX Engine assumes '*' as the default value.

  For example:

  add key="MaximumMessageAllowedInResendRequest" value="*" />

• ApplicationMessageTypeNotToBeSendAsGapFill: An optional key. It is relevant only when you select set AlwaysGapFill as the value for the RuleType key. For some reason, you may not wish to resend certain types of Application Messages while complying with a ResendRequest message from your counterparty.

  For example, if you decide not to resend Application Messages of types D and F, you need to define the ApplicationMessageTypeNotToBeSendAsGapFill key as follows:

  add key="ApplicationMessageTypeNotToBeSendAsGapFill" value="D, F" />

  The value of ApplicationMessageTypeNotToBeSendAsGapFill is the comma-separated list of Application Message types (tag 35 values) that you do not wish to resend. If you do not define this key, FF.FIX Engine resends all types of Applications Messages while responding to the counterparty's ResendRequest messages.

• OrigSendingTimeInGapFillMessage: An optional key. While resending a message, you can include its original sending time as the value of the optional field OrigSendingTime (tag 122) in the Header of the resent message. FF.FIX Engine automatically inserts the original sending time at tag 122 of the resent messages when you set this key to the value Y. If you set the value of this key to N, the OrigSendingTime field is absent in the resent messages. If you do not define this key, FF.FIX Engine assumes Y as the default value.

As the Header fields are common to all messages, FF.FIX Engine simplifies their setting using the <StandardHeaderFieldValue> sub element in the <Session> element of the configuration file. Later FF.FIX Engine picks up these values from the configuration file and inserts them in the message Header before sending it.

The FIX Protocol specifies several fields in a standard Header. Of these, the following seven fields are mandatory:

FF.FIX Engine internally generates the values of tag 9, 34 and 52 at the time of sending the message. A user specifies the tag 35 value while creating a FIX Message structure. To set the remaining three fields, the three mandatory keys are as follows:

• BeginString: Specifies the FIX Protocol version to be followed. It is in the FIX.<MajorVersion>.<MinorVersion> format. The valid values are FIX.4.0, FIX.4.1, FIX.4.2, FIX.4.3, and FIX.4.4. For example, you select the FIX Protocol version 4.2, the key would be defined as:

  <add key="BeginString" value="FIX.4.2" />

• SenderCompID: Specifies the ID of the sender's (your) computer.

  <add key="SenderCompID" value="ABC" />

• TargetCompID: Specifies the ID of the computer of your counterparty (target).

  <add key="TargetCompID" value="XYZ" />

To include other optional Header fields, you can add a separate key for each additional field and set its value. However, you should not include keys for the fields that are assigned values internally. For example, you should not include a key for the OrigSendingTime field (tag 122). FF.FIX Engine internally includes it in the resent messages as per your settings. You can also add keys for custom Header fields that you and your counterparty mutually agreed to use and define their values. FF.FIX Engine inserts these fields and their set values in the Header of each Outbound Message. You can also override the set key values programmatically.

Some examples of optional Header fields are:

The Sell-side rules make it mandatory to activate FIX sessions on weekly or daily basis. Each new session requires to begin with the message sequence numbers in reset state.

The mandatory sub element <SessionActivationSchedule> in the <Session> element of the configuration file lets you automate these routine tasks.

The <SessionActivationSchedule> element for weekly type schedules appears as follows:

The <SessionActivationSchedule> element for daily type schedules appears as follows:

Though the StartDay and EndDay keys are not applicable to daily type schedules, all five keys in above code snippets are mandatory in their respective schedule types.

• SessionActivationSchedule: A mandatory key. Specifies whether the FIX session schedule shall activate on daily or weekly basis.
• StartTime: A mandatory key in both, daily and weekly schedules. Its value is the local time in HH:MM:SS format without the millisecond stamp. For daily type schedules, FF.FIX Engine starts a new session every day at the StartTime. For weekly type schedules, FF.FIX Engine starts a new session on every StartDay at the StartTime.
• EndTime: A mandatory key in both, daily and weekly schedules. Its value is the local time in HH:MM:SS format without the millisecond stamp. For daily type schedules, FF.FIX Engine ends the session every day at the EndTime. For weekly type schedules, FF.FIX Engine ends the session on every EndDay at the EndTime. After ending the session, FF.FIX Engine resets Inbound and Outbound Message sequence numbers.
• StartDay: A mandatory key for weekly schedules only. FF.FIX Engine starts a new session on every StartDay at the StartTime.
• EndDay: A mandatory key for weekly schedules only. FF.FIX Engine ends the session on every EndDay at the EndTime and resets Inbound and Outbound Message sequence numbers.

The valid values for the StartDay and EndDay keys are Monday, Tuesday, Wednesday, Thursday, Friday, Saturday and Sunday. The FIX Session automatically intimates about the scheduled session start and session end events using the following callbacks defined in the FIXInitiatorHandler class:

The default behavior is to reset the sequence numbers. However, you can override the default behavior in these callbacks.

FF.FIX Engine can record different session events into its own log file or the event log of the operating system. Accordingly, the optional key LoggerType has two possible values: File and Event. If you do not define this key, FF.FIX Engine takes File as the default value and records the events in its own log file.

The optional key LogAttributes allows you to select the types of session events to be logged into log files or event logs of the operating system. The allowed options for the session event types are: IM (Inbound Message), OM (Outbound Message), INFO (information event), WARNING, ERROR and DEBUG. You can select one or more options and assign them as the value of the LogAttributes key. The value should be a '|' separated list of options if you selected more than one option. If you do not define the LogAttributes key, FF.FIX Engine logs only the WARNING and ERROR events.

The LoggerType and LogAttributes keys are defined in the <Logger> element of the configuration file for both, Acceptors and Initiators.

For example:

Yes, you can introduce any number of custom attributes for your internal use and programming convenience. You can define the keys for these attributes in the <CustomAttribute> element of the configuration file. This element occurs in configuration files for Acceptors as well as Initiators.

For example:

A FF.FIX Engine application behaves either as an Initiator or Acceptor. Hence, a FIX configuration file contains either an <Initiator> or <Acceptor> element. A typical <Initiator> element in an Initiator application looks as given below:

• <SessionLogic> element: An optional element. Specifies the session logic based on the optional keys:
  
  • MaxTestRequestGeneratedInRow
  • SendTestRequestBeforeSendingLogonWithResetSeqNumFlag
• <SecureSSLProtocol> element: An optional element. Specifies whether the FIX session will use a secure socket connection or not.
• SocketInterfaceIP: A mandatory key. Typically, the machine on which your Initiator application runs may have several network interfaces with different IP addresses. This key specifies the IP address of your application server, published to your counterparty. You require to communicate this IP address to your counterparty as a part of mutual agreement before establishing the connectivity.

• SocketConnectHostPrimary and SocketConnectPortPrimary: The mandatory keys SocketConnectHostPrimary and SocketConnectPortPrimary specify the primary IP address and the primary port address of the TCP socket on the Acceptor (counterparty) server where your Initiator application establishes a socket connection. Your counterparty publishes/communicates these values to you as a part of mutual agreement before establishing the connectivity.

• SocketConnectHostFailover and SocketConnectPortFailover: Typically, the Acceptor (Sell-side) assigns you a primary IP and port address for initiating the physical connection. It may also provide you the failover IP and the failover port address, in case the connection attempt to the primary IP and the primary port address fails.

  The optional keys SocketConnectHostFailover and SocketConnectPortFailover specify the failover IP address and the failover port address of the TCP socket on the Acceptor (counterparty) server where your Initiator application shall establish a physical connection, if the connection to the primary IP address and port address fails. Your counterparty publishes/communicates these values to you as a part of mutual agreement before establishing the connectivity.
• ConnectionTimeOut: The optional key ConnectionTimeOut represents the number of seconds of an idle connection, after which the Initiator application shall terminate the physical connection with the counterparty. This automatically terminates the FIX session too. Idle connection means the connection with no exchange of data packets in either direction. The allowed values for this key range from 2 to 30 seconds. If you do not define this key, FF.FIX Engine assumes the default value of 30 seconds.
• ReConnectAttempts and ReConnectInterval: For establishing a FIX session, establishing a physical (TCP socket) connection with the counterparty is the first step. If the Initiator application fails to establish a physical connection in the first attempt, it can automatically retry as per the ReConnectAttempts and ReConnectInterval key value settings.

  The optional key ReConnectAttempts specifies the number of reconnection attempts the Initiator application shall make for establishing a physical connection with the Acceptor server. Its value must be a positive integer. If you do not define this key, the Initiator makes no reconnection attempts.

  The ReConnectInterval key is mandatory only if you define the ReConnectAttempts key. It specifies the time interval in seconds from the connection failure to the subsequent attempt for establishing a physical connection. The allowed values for this key range from 5 to 60 seconds.

  If there is no failover IP address (specified by the SocketConnectHostFailover key), all reconnection attempts occur at primary IP address (specified by the SocketConnectHostPrimary key). If the failover IP address exists, the reconnect attempts toggle between these two IP addresses.
• LogonTimeOut: The optional key LogonTimeOut specifies the time interval in seconds, for which the Initiator application shall wait for an acknowledgement of the Logon message it sent. The Initiator application drops the connection to the Acceptor counterparty if it receives no acknowledgement of its Logon message within a period of 'LogonTimeOut' seconds. The allowed values for this key range from 1 to 60 seconds. It you do not define this key, FF.FIX Engine assumes 30 seconds as the default value.
• LogoutTimeOut: The optional key LogoutTimeOut specifies the time interval in seconds, for which the Initiator application shall wait for an acknowledgement of the Logout message it sent. The Initiator application drops the connection to the Acceptor counterparty if it receives no acknowledgement of its Logout message within a period of 'LogoutTimeOut' seconds. The allowed values for this key range from 1 to 60 seconds. It you do not define this key, FF.FIX Engine assumes 30 seconds as the default value.
• InBoundQueueSizeThreshold: An Initiator application based on FF.FIX Engine puts unprocessed real-time Inbound Messages into the Inbound Message queue and processes them in sequential manner. Depending on the message traffic, you can set the message queue size as required. The mandatory key InboundQueueSizeThreshold represents the maximum number of unprocessed messages it can hold. On reaching this limit, FF.FIX Engine intimates the user using the following callback:

  public abstract void InBoundQueueSizeThresholdValueReached(FixSession fixSession);

  After receiving such a call back, the user can take a situation dependent decision.

• CheckLatency and MaxLatencyTime: Latency is the time interval measured from time recorded in the SendingTime field (tag 52) in an Inbound Message to the actual time of its receipt. The latency should never be negative because the message receiving time has to be a later time then the message sending time. If the latency is negative, it is a fatal error. Large latency values are an indication of possibility of problems with the network or with the system processing speed.

  The optional key CheckLatency allows your Initiator application to check latency of each Inbound Message. If you do not define this CheckLatency key or set its value to N, there are no latency checks.

  The MaxLatencyTime key is mandatory only if you assign the value Y to the CheckLatency key. The MaxLatencyTime key specifies the maximum allowed latency for Inbound Messages. If the latency exceeds this value, your application would intimate the user using the following callback method:

  public virtual void OnInboundMesssageMaximumLatencyTimeReached(FixSession fixSession, int latencyTime);

  The user may take suitable action on this callback.

The optional element <SecureSSLProtocol> in the <Initiator> element of the configuration file lets you specify whether the FIX session will use a secured socket connection or not.

For example:

• If you do not include the <SecureSSLProtocol> element in the configuration file, the FIX session uses ordinary socket connection for connecting to the counterparty.
• If you assign the value N to the UseSSLProtocol key then the other two keys become irrelevant and the FIX session uses ordinary socket connection for connecting to the counterparty.
• You must include the <SecureSSLProtocol> element in the configuration file and set the UseSSLProtocol key to the value Y, if you wish to connect to your counterparty using a secure socket connection. In that case the CNName and CertificateFile keys in the <SecureSSLProtocol> element become mandatory keys.
• CNName: Specifies the common name of the certificate provided by the Acceptor (counterparty) application.
• CertificateFile: Specifies the path and name of the certificate file of your (Initiator) application.

The <SessionLogic> element has a similar structure in the configuration files for the Initiator as well as Acceptor applications. It appears in the <Acceptor> element in Acceptor configuration file and in the <Initiator> element in Initiator configuration file. It specifies a mechanism for:

• Testing whether the counterparty is alive in the session using TestRequest messages.
• Confirming if there are lost messages and recovering them before resetting the sequence numbers through a Logon message.

  The following code snippet presents a typical <SessionLogic> element:

  <SessionLogic>
      <add key="MaxTestRequestGeneratedInRow" value="2" />
      <add key="SendTestRequestBeforeSendingLogonWithResetSeqNumFlag" value="N" />
  </SessionLogic>

• MaxTestRequestGeneratedInRow: An optional key. It specifies the maximum number of TestRequest messages in a row that your application shall send to your counterparty to check if it alive in the FIX session. The allowed values for this key range from 1 to 10. If you do not define this key, FF.FIX Engine assumes 2 as the default value.

  Your counterparty is 'X'. In your configuration file you set HeartBtInt = 30 second, HeartBtIntDelta = 20 second, MaxTestRequestGeneratedInRow = 2. Your application received the last Inbound Message from X at 12:00:00. Thereafter there is no further message from X.

  In this situation, you application may conduct the FIX session as follows:

  Time	Action
  12:00:00	Your application receives a message from X.
  12:00:18	Your application sends some message to X.
  12:00:30	No further message from X is received in past 30 seconds from 12:00:00 to 12:00:30. Your application begins the HeartBtIntDelta timer of 20 second for the first time.
  12:00:48	Your application has no new Application Messages to be sent during the 30 seconds from 12:00:18 to 12:00:48. Hence, your application sends a Heartbeat message to indicate that it is alive in the session.
  12:00:50	No further message from X is received in past 20 seconds from 12:00:30 to 12:00:50. Hence, your application sends a TestRequest message to X. It is the first TestRequest in a row. Your application simultaneously begins the HeartBtIntDelta timer of 20 seconds again.
  12:01:10	No further message from X is received in past 20 seconds from 12:00:50 to 12:01:10. Hence, your application sends a TestRequest message to X. It is the second TestRequest in a row. Your application simultaneously begins the HeartBtIntDelta timer of 20 seconds again.
  12:01:18	Your application has no new Application Messages to be sent during the 30 seconds from 12:00:48 to 12:01:18. Hence, your application sends a Heartbeat message to indicate that it is alive in the session.
  Case 1: 12:01:21	Your application receives a message from X. The message came 11 seconds after 12:01:10 and before the expiry of the 20 seconds from 12:01:10. It confirms that X is still alive in the session. Depending on the message sequence number, you proceed to GapFill process or to regular business.
  Case 2: 12:01:30	No message comes from X until 12:01:30. The 20 seconds of HeartBtIntDelta timer from 12:01:10 are over. All TestRequest attempts specified by the MaxTestRequestGeneratedInRow are exhausted. Your application becomes sure that X is dead in the session and drops the physical connection with it. This ends the FIX session too. No Logout message is sent. It is an abnormal termination of the FIX session.

  
  
• SendTestRequestBeforeSendingLogonWithResetSeqNumFlag: The FIX Protocol allows to send a Logon message having 141=Y (ResetSeqNumFlag field) during an ongoing session if a party wishes to ignore all earlier messages and start afresh. Then the counterparty also requires to reset its sequence numbers.

  You can use this feature to force your counterparty reset the sequence numbers and start afresh. However, before resetting the sequence numbers using a Logon message, you may wish to confirm that there is no GapFill situation and you are not missing any important message from your counterparty. For this purpose, you need to send a TestRequest message to the counterparty. The counterparty has to reply to the TestRequest with a Heartbeat message, as specified in the FIX Protocol. From the message sequence number of this Heartbeat reply, you can confirm whether you have lost any messages in between. You can assign the value Y to the optional key SendTestRequestBeforeSendingLogonWithResetSeqNumFlag and make FF.FIX Engine perform this entire process automatically as follows:

  • If there is no message gap (GapFill situation), FF.FIX Engine sends a Logon message with 141=Y for resetting the message sequence numbers.
  • If there is a message gap, FF.FIX Engine first recovers the messages in the gap and then only sends the Logon message with 141=Y for resetting the message sequence numbers.
  If you do not define this key, the FIX session proceeds by assigning a default value N to this key internally.

An application behaves either as an Initiator or Acceptor. Hence, a FIX configuration file contains either an <Initiator> or <Acceptor> element. A typical <Acceptor> element in an Acceptor application is as given below:

• <SessionLogic> element: An optional element. It specifies the session logic based on the optional keys:
  • MaxTestRequestGeneratedInRow.
  • SendTestRequestBeforeSendingLogonWithResetSeqNumFlag.
  It works in the same manner, for both Acceptors and Initiators.
• SocketConnectPort: A mandatory key. It represents the numeric address of the TCP port at which an Acceptor application listens for new connection requests and new messages from the Buy-side counterparties. A single port serves to multiple counterparties simultaneously.
• LogonTimeOut: After a Buy-side counterparty establishes a socket (physical) connection, an Acceptor application waits for the time interval in seconds specified by the LogonTimeOut key. If the counterparty fails to send a Logon message within this period, the Acceptor closes the socket connection.

The allowed values for this key are range 1 to 60 seconds. If you do not define this key, FF.FIX Engine assumes 30 seconds as the default value.

• InBoundQueueSizeThreshold: An Acceptor application based on FF.FIX Engine puts unprocessed real-time Inbound Messages into the Inbound Message queue and processes them in sequential manner. Depending on the message traffic, you can set the message queue size as required. The mandatory key InboundQueueSizeThreshold represents the maximum number of unprocessed messages it can hold. On reaching this limit, FF.FIX Engine intimates the user using the following callback:
  
  

  public abstract void InBoundQueueSizeThresholdValueReached(FixSession fixSession);

  After receiving such a call back, the user can take a situation dependent decision.

• CheckLatency and MaxLatencyTime: Latency is the time interval measured from time recorded in the SendingTime field (tag 52) in an Inbound Message to the actual time of its receipt. The latency should never be negative because the message receiving time has to be a later time then the message sending time. If the latency is negative, it is a fatal error. Large latency values are an indication of possibility of problems with the network or with the system processing speed.

  The optional key CheckLatency allows your Initiator application to check latency of each Inbound Message. If you do not define this CheckLatency key or set its value to N, there are no latency checks.

  The MaxLatencyTime key is mandatory only if you assign the value Y to the CheckLatency key. The MaxLatencyTime key specifies the maximum allowed latency for Inbound Messages. If the latency exceeds this value, your application would intimate the user using the following callback method:

  public virtual void OnInboundMesssageMaximumLatencyTimeReached(FixSession fixSession, int latencyTime);

  The user may take suitable action on this callback.

The FixConfig class in the FF.FIX namespace provides a programmatic access to the configuration file in XML format. It has a rich API collection that provides an access to the information in the configuration file. A valid XML file is used to create a FixConfig object.

For example:

This code throws the FixConfigException exception, if it fails to create a FixConfig object. The initialization of Initiator and Acceptor applications is based on the respective FixConfig objects.