FIX Initiator

A FIX Initiator application is a Buy-side application that initially establishes a communication link with the FIX Acceptor application server (Sell-side) of the counterparty and then sends a session initiating Logon message to the FIX Acceptor application via the established communication link.

The FF.FIX Engine API makes it easy for you to develop an application that can act as a FIX Initiator and connect to the counterparty (Acceptor application's server) and conduct sessions as per mutually agreed FIX specifications.

The following diagram presents an architectural view of a FF.FIX Engine based Initiator application:

A FIX Initiator application based on FF.FIX Engine has the following components:

Component details	Role in the Initiator application
Component name: Callback handler Class: FixInitiatorHandler Namespace: FF.Fix.Initiator	Provides a callback interface to listen to important events and exchanged messages during a FIX session. You can process the events you receive as per your needs using different methods of the FixInitiatorHandler class. For details, see FIX Initiator Handler.
Component name: FIX session configuration Class: FixConfig Namespace: FF	The FixConfig class represents an object model for the declarative FIX configuration file in XML format. It contains the parameters you defined for controlling a FIX session.
Component name: Persistence layer Class: FixDBConfig Namespace: FF	The persistence layer for a FIX session uses a RDBMS. The FixDBConfig class provides details of the same.
Component name: FIX session Class: FixSession Namespace: FF.Fix	The FixSession class manages a FIX connection with the counterparty. Each FIX session is represented by a separate object of the FixSession class.
Component name: Alert manager Class: FixAlertManager Namespace: FF.Fix	The FixAlertManager class provides an entry point for managing various alerts during a FIX session.

::FAQ::

What is an Initiator?
How do I define my own callback handling mechanism in my Initiator application?
How do I configure my Initiator application for different FIX sessions?
How do I create a persistence layer for my entire Initiator application?
How do I extract a FixSession object associated with an instance of the Initiator?
How do I register to different session alerts from the list of available FIX session alerts?
How do I write my Initiator application? What steps do I need to follow?
How do I pass Logon credentials to my counterparty through my Initiator application?
How do I handle exceptions thrown by the FF.FIX Engine library?
Can I block a callback method of the AlertManager for a lengthy processing?
How do I use SSL to connect to my counterparty?

What is an Initiator?

The implementation of FIX Protocol occurs through FixSession objects. The Initiator class in the FF.Fix.Initiator namespace offers an abstraction over a FixSession object.

The three important functions that control the behavior of an Initiator application are:

Init(…): The Init() call initializes the Initiator application with some initial information that is specifically required before a Start() call. For a given Initiator instance, the Init(…) call occurs only once.
Start(): The Start() call provides a valid FIX session over a physical connection so that the parties to the session can exchange messages. This method can be called several times, whenever you wish to establish a valid FIX session with your counterparty.
Stop(): The Stop() call can occur after a Start() call in order to end a FIX session with the counterparty.

How do I define my own callback handling mechanism in my Initiator application?

The FixInitiatorHandler class provides a callback interface to listen important events and exchanged messages during a FIX session. You can create your own customized callback listening and processing mechanism as shown below:

public class MyInitiatorCallbackListner : FF.Fix.Initiator.FixInitiatorHandler
{
//Override the different base class methods to listen to and act on important events, as you require.
}

How do I configure my Initiator application for different FIX sessions?

An instance of the Initiator class needs a FixConfig object to manage the FIX session it holds. You can provide the required FixSession object by loading a FIX configuration file (XML) as follows:

//Load a FIX configuration file
string configFile =".../..//Initiator.config";
FixConfig fixConfig = new FixConfig(configFile);

How do I create a persistence layer for my entire Initiator application?

The initialization of persistence layer for the entire Initiator application is a one time process. It does not depend on the number of instances of the Initiator class.

The FixDBConfig class provides the persistence layer the entire application. The following code snippet demonstrates creation of the persistence layer:

string dbName = "FFFix";
string dbHostName = Dns.GetHostName();
string dbConnectionString = string.Format("Data Source={0};Initial Catalog={1};Integrated Security=SSPI;Pooling=true;Min Pool Size=0;Max Pool Size=100;Connect Timeout=30", dbHostName, dbName);

/*FIX persistence database layer initialization (for MSSQL) using a valid connection string.*/
FixDBConfig dbConfig = new FixDBConfig(eDBProvider.SqlServer, dbConnectionString);

//Initialize the persistence layer for an application

//This method has to be called once for an entire application.
FixProcess.Instance.Init(dbConfig);

How do I extract a FixSession object associated with an instance of the Initiator?

Different instances of the Initiator class deal with different FIX connections (sessions). While initializing an instance of the Initiator class, the FixSession object appears in the parameter list for the Init() call. The following code shows how to extract a FixSession object associated with an instance of the Initiator class:

/*A user can retrieve a valid FixSession object after a successful initialization of Initiator.*/
using FF.Fix;
using FF.Fix.Initiator;
...

Initiator _initiator = null;
FixSession _fixSession = null;
...

_initiator = new Initiator();
_initiator.Init(...); //Initialization.
_fixSession = _initiator.GetFixSession(); //Extracting the FIX session.

How do I register to different session alerts from the list of available FIX session alerts?

The FixAlertManager class contains a list of all FIX session alerts. You need to register to alerts of your choice for using them in FIX sessions held by your application.

For example:

//Register to listen to different session alerts.
_fixSession.GetAlertManager().RegisterAlertCallback(FF.Fix.Core.eAlertType.All, new AlertCallbackRoutine(OnFIXSessionAlertMessage));
...
...

private void OnFIXSessionAlertMessage(SessionInfo fixSessionInfo, eAlertType alertType, string alertMessage, string additionalMessage)
{
    if (alertType == eAlertType.InboundMessageSeqNumber)
    {
        SetControlText(this.txtInboundSequenceNumber, alertMessage);
    }

    else if (alertType == eAlertType.OutboundMessageSeqNumber)
    {
        SetControlText(this.txtOutboundSequenceNumber, alertMessage);
    }

    else if (alertType == eAlertType.InboundMessage)
    {
        SetControlText(this.rtbMessageLog, "INBOUND MESSAGE: " + alertMessage);
    }

    else if (alertType == eAlertType.OutboundMessage)
    {
        SetControlText(this.rtbMessageLog, "OUTBOUND MESSAGE: " + alertMessage);
    }

    else if (alertType == eAlertType.SessionStateChange)
    {
        SetControlText(this.txtSessionState, alertMessage);
    }

    else if (alertType == eAlertType.Info || alertType == eAlertType.Error || alertType
    == eAlertType.Warning)
    {
        SetControlText(this.rtbLog, alertType.ToString().ToUpper() + ": " + alertMessage);
    }
}

How do I write my Initiator application? What steps do I need to follow?

The steps for creating an Initiator application are as follows:

Create a callback listener.
Create a FIX Data Dictionary.
Create a FIX configuration file of Initiator type.
Specify the FIX Data Dictionary in the FIX configuration.
Start coding the Initiator application.

Step 1: Callback listener
The FixInitiatorHandler class from the FF.Fix.Initiator namespace provides you important callbacks methods. You need to derive your own callback handler class from the FixInitiatorHandler class. This derived class provides you an interface to listen to all important events and Inbound/Outbound Message exchanged during a FIX session.
The following code snippet shows a sample Initiator callback listener:

using System;
using System.Collections.Generic;
using System.Text;
using FF.Fix;
using FF.Fix.Initiator;
using FF.Fix.Core.Message;
namespace InitiatorApplication
{
//Create your customized callback handling mechanism by adding the appropriate code.
internal sealed class InitiatorCallbackListner: FF.Fix.Initiator.FixInitiatorHandler

    {
        public InitiatorCallbackListner()
        {
        }

        public override void OnSessionInitialize(FixSession fixSession)
        {
        }

        public override void OnEnrichSessionFixMessageHeader(FixSession fixSession,FixMessageHeader fixMessageHeader)
        {
        }

        public override void OnConnect(FixSession fixSession)
        {
        }

        public override void OnConnectionTimeOut(FixSession fixSession)
        {
        }

        public override void OnConnectionFailed(FixSession fixSession, string failedReason)
        {
        }

        public override void OnConnectionBreak(FixSession fixSession, string failReason)
        {
        }

        public override void OnInboundMessageMaximumLatencyTimeReached(FixSession fixSession, int latencyTime)
        {
        }

        public override void OnLogonTimeOut(FixSession fixSession)
        {
        }

        public override void SendingLogonMessage(FixSession fixSession, FixMessage logonMessage)
        {
        }

        public override void OnLogonMessage(FixSession fixSession, FixMessage message)
        {
        }

        public override void OnLogonMessageRejected(FixSession fixSession, FixMessage message)
        {
        }

        public override void OnLogoutMessage(FixSession fixSession, FixMessage message)
        {
        }

        public override void OnRejectMessage(FixSession fixSession, FixMessage message, int rejectedMessageSeqNum)
        {
        }

        public override void OnApplicationMessage(FixSession fixSession, FixMessage message)
        {
        }

        public override void InBoundQueueSizeThresoldValueReached(FixSession fixSession)
        {
        }

        public override void OnSessionTransmissionFail(FixSession fixSession, DateTime lastMessageRecvAt)
        {
        }
    }
}

Step 2: FIX Data Dictionary
Depending on the mutual agreement with your counterparty, create a FIX Data Dictionary that provides the information on allowed FIX Messages, FIX fields, customized messages, custom fields, custom message types and custom enumerations. The following code snippet shows a sample FIX Data Dictionary:

<?xml version="1.0" standalone="yes"?>
<fixDataDictionary version="FIX.4.2">

        ...
        ...
        </fixmessages>

Step 3: FIX configuration file of Initiator type
A FIX configuration file is a declarative statement in XML format that specifies how the Initiator instance shall control a FIX session. The parameters in the FIX configuration file implement your session logic and the agreed specifications with your counterparty. The following code snippet shows a sample FIX configuration file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>

Step 4: Specify the FIX Data Dictionary in the FIX Configuration
Implement the FIX Data Dictionary you created in the FIX configuration file as follows:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <Session>
        <add key="ConnectionType" value="Initiator" />
        ...
        ...
        <add key="DataDictionary" value="\...\InitiatorDataDictionary.xml" />
        ...
        ...
    </Session>

...
...
</configuration>

Step 5: Start coding the Initiator application
After completing above steps, you can proceed to write code for your Initiator application. See the sample code below:

//Initializations and assignments.
private Initiator _initiator = null;
private FixSession _initiatorFixSession = null;
private InitiatorCallbackListner _initiatorCallbackListner = null;
...
...
_initiator = new Initiator();
_initiatorCallbackListner = new InitiatorCallbackListner();
...
...

//Load a FIX configuration file.
string configPath = InitiatorConfig.ConfigFileName;
FixConfig fixConfig = new FixConfig(configPath);

//creating a username for the user of the Initiator instance.
string userID = "Initiator1";

//Create a FIX persistence connection string.
string dbName = "FFFix";
string hostName = Dns.GetHostName();
string dbConnectionString = string.Format("Data Source={0};
Initial Catalog={1};Integrated Security=SSPI;Pooling=true;Min Pool Size=0;Max Pool
Size=100;
Connect Timeout=30", hostName, dbName);

//FIX persistence database layer Initialization (MSSQL) with a valid connection string.
FixDBConfig dbConfig = new FixDBConfig(eDBProvider.SqlServer, dbConnectionString);

//Creating the Body part of the session initiating Logon message
FixMessageBody logonMessageBody = new FixMessageBody();
logonMessageBody.SetField(FixFieldTag.Username_553, "Initiator1");
logonMessageBody.SetField(FixFieldTag.Password_554, "ABC"));
string acceptorServerIP = "127.1.0.1";
int acceptorServerListenPort = 6666;
string senderCompID = "Initiator1";
string targetCompID = "FFAcceptor";
string beginString = "FIX.4.2"; //FIX Protocol version 4.2 shall be followed.

//Initialize the Initiator.
_initiator.Init(userID, fixConfig, dbConfig, _initiatorCallbackListner, logonMessageBody,
acceptorServerIP, acceptorServerListenPort, beginString, senderCompID, targetCompID);
_initiatorFixSession = _initiator.GetFixSession();
...
...
...

//Start the Initiator.
_initiator.Start();
...
...
...

//Stop the Initiator.
_initiator.Stop();

How do I pass Logon credentials to my counterparty through my Initiator application?

You can pass Logon credentials to your counterparty in two ways:

Method 1:
The Init() call on the Initiator instance is available with many overloads. Refer to FF.FIX Engine API Guide for details. The Body of the Logon message includes the UserName and Password fields. You can set their values through the FixMessageBody parameter that you use during the Init() call. While executing a Start () call, these values are inserted in the Logon message that the Initiator instance sends to the counterparty.

For example:

Initiator initiator = new Initiator();
...
...

FixMessageBody logonMsgBody = new FixMessageBody();
logonMsgBody.SetField(FixFieldTag.Password_554, "Pwd");
initiator.Init(userName, fixConfig, persistConfig, callbackHandler, logonMsgBody);
...
...

initiator.Start();

Method 2:
Alternatively, you can include Logon credentials at the time of actually sending a Logon message. This option also lets you override the default Logon credentials or make last moment changes in those credentials.

The public virtual void SendingLogonMessage(FixSession fixSession, FixMessage logonMessage) method produces a callback before sending a Logon message. You may customize this callback method to set Logon credentials at the time of sending a Logon message to the counterparty. For details, see FIX Session Handler.

The following code snippet shows how to customize SendingLogonMessage method for sending Logon credentials:

class InitiatorCallbackListner: FixInitiatorHandler
{
    public override void SendingLogonMessage(FixSession fixSession, FixMessage logonMessage)
    {
        logonMessage.SetField(FixFieldTag.Password_554, "Pwd");
    }

...
...
}

How do I handle exceptions thrown by the FF.FIX Engine library?

The object oriented APIs in FF.FIX Engine use exception handling mechanism compliant with .NET compatible programming languages. They report all errors by raising a FixException. This enables you write the code that may look as follows (using C# syntax):

try
{
//Your code using FF.FIX API.
}

catch (FixException ex)
{
System.Console.WriteLine("Exception " + ex.Message);
}

This exception handling mechanism facilitates centralized error checking, keeps your mainline code readable and ensures that no error condition is ever ignored.

Can I block a callback method of AlertManager for a lengthy processing?

The AlertManager sends alerts about important events to the user registered callback methods using the threadPool thread. This thread is designed to use in short and focused tasks that shall not block. To prevent potential performance degradation of the overall system, all alert callback methods should be non-blocked or short lived.

How do I use SSL to connect to my counterparty?

To connect to your counterparty (Acceptor) over a SSL, make the following changes in the FIX configuration file.

Set the UseSSLProtocol key to the value Y.
Provide a value for CNName key. This value should be the common name for the Acceptor's certificate file.
If the Initiator (your application) is using a SSL certificate, provide a value for the CertificateFile key. This value should be the path of the Initiator certificate file.

For example: