Overview

B2BITS provides FIXAntenna QF add-on package for FIX Antenna™ C++ library which helps to migrate from QuickFIX to FIX Antenna™ C++. The package includes C++ classes that implement the QuickFIX interface. The migration to the FIX Antenna™ engine essentially becomes a replacement of the library. The package also contains tools that help to deal with QuickFIX FIX protocol definition in XML.

FIXAntenna QF Adaptor supports the import of customized dictionaries from QuickFIX. This is done by using an XML conversion tool which is part of the migration package (see Converting customized QuickFIX protocol dictionaries ).

The user migrating to FIX Antenna™ can leverage Certified FIX Connections to major exchanges and ECNs still using the QuickFIX business object model. This is achieved by using a C++ code generator, which is part of the migration package, that can convert B2BITS provided FIX custom protocol definitions into the typed C++ business messages in QuickFIX style (see Generating C++ business objects for standard or customized FIX protocol versions).

Supported QuickFIX features

• Typed C++ message objects and MessageCracker interface
• Transient and persistent FIX session storage 
• FIX Session management (schedules) 
• 4.x and 5.x FIX protocol versions
• FIX protocol customizations 

Features that are not part of the QF adaptor package

The following features are not part of the QF adaptor package. You may consider using the QuickFIX classes instead:

• Database persistence
• Built-in HTTP remote administration. But it is possible to use a rich GUI tool for remote administration: FIXICC
• QuickFIX property names in SessionSettings class. FIX Antenna™ property syntax is supported instead. The static configuration files from QuickFIX are supported (through a conversion tool).
• Dynamic loading of XML dictionaries. The dictionary files should be specified in the configuration file before the engine start.
• The following configuration properties currently not fully supported: StartDay, EndDay , MillisecondsInTimeStamps=N, CheckCompID, CheckLatency, MaxLatency. The options StartTime and EndTime are supported though. 
• A number of low-level QuickFIX C++ interfaces related to message store or logging details. The FIX Antenna™ engine library encapsulates its own optimized implementation of these interfaces and hides such low-level details from the user. 

Performance Comparison

This section describes performance scenarios and numbers obtained using PerformanceTest application that is part of the migration package (please find the source code at: ...\QFAdaptor\examples\PerformanceTest). The application code is written using the QuickFIX interface, the same source code is used when running the test with QuickFIX and FIX Antenna™ library.

Latency Test

The test application establishes a FIX session on a local host using an instance of ThreadedSocketAcceptor/Initiator class. A FIX message (NewOrderSignle) is repeatedly sent within the session. The time of the FIX message traveling from the sending endpoint to the receiving endpoint is measured and reported. This is the time which is spent between Session::send() call and MessageCracker::onMessage(). FIX session uses a persistent disk message store.

CPU: AMD Phenom II X4 3.0 GHz

Average message latency with FIX Antenna™: 38 mcs (min: 34, max: 276)

Average message latency with QuickFIX: 146 mcs (min: 141, max: 14528)

Conclusion: The message delivery time with FIX Antenna™ QF Adaptor is 3.7 times less than that of the QuickFIX library.

Throughput Test

The test application establishes FIX sessions on a local host using an instance of SocketAcceptor/Initiator class. A FIX message (NewOrderSignle) is repeatedly sent into each of the created sessions. The test ends once all of the 1,000,000 messages are delivered to the receiving endpoint. The test calculates the throughput which is the number of messages delivered per 1 second.

Conclusion: The message throughput of FIX Antenna™ with QF adaptor is over 7 times more than that of the QuickFIX using the single instance of SocketAcceptor/Initiator class that hosts the sessions. With FIX Antenna™ you don’t need to decide how many of the SocketAcceptor instances to launch in order to load your CPU cores with enough work. The scalability is achieved automatically regardless of how the session grouping within particular acceptor/initiator instances.

Migration Step-by-Step

Overview

Typically in order to migrate, you need to do the following steps:

1. Install FIX Antenna™
2. FIX Antenna™ QF adaptor
3. Update your project to include QF adaptor source files and add a QF adaptor initialization call
4. Convert QuickFIX configuration files into FIX Antenna™ format
5. Compile and run
   If you used custom FIX dictionaries:
6. Convert the dictionaries into FIXDIC format
7. An optional extra step: Generate C++ business objects for custom FIX protocol

1. Migration Package Installation

Pre-requisites

In order to use the tools included with the package, ensure the following is installed:

1. Perl version 5.6 or later. Under Windows, we recommend using the ActivePerl distribution. In order to check that Perl is available, use the following command line:

   perl -version

2. Java 1.5 or higher. In order to check that java is available, use the following command line:

   java -version

   Note: for Linux the Sun Java or OpenJDK packages are recommended. The “gij (GNU libgcj) 1.4 ” was found to show significantly slower performance with the XML conversion tool.

Microsoft Visual Studio™ and GNU C++ compilers are supported. The version of the compiler should be the same as used by your FIX Antenna™ C++ package.

Installation

1. Install FIX Antenna™ C++ package. For information on how to get it please refer to the website.
2. Unpack and place the “QFAdaptor” folder with FIX Antenna™ QF adaptor into the FIX Antenna™ installation at "\B2BITS\FIX Antenna C++\<version>".

In the FIX Antenna™ QF Adaptor package, the C++ classes are placed in the “QFA::” namespace. Additional define redirects FIX:: namespace definitions used in user programs to QFA::.

To check that everything works OK, you may compile and run the example application found at "\B2BITS\FIX Antenna C++\<version>\QFAdaptor\examples\PerformanceTest\”. Please follow the instructions below:

Sample Project - Windows

1. Open PerformanceTest_vs2010.sln in Microsoft Visual Studio 2010
2. Build the solution
3. Go to PerformanceTest\bin\config and run config_convert_1session.cmd and config_convert_10session.cmd command files. These commands convert 1session.cfg and 10sessions.cfg configuration files from QuickFIX to FIXAntenna™ format. Output files are placed in the folder “converted”
4. Go to the “bin” folder and run run_latency_test.bat, run_throughput_1session.bat, run_throughput_10sessions.bat.

Sample Project - Linux

1. Go to the PerformanceTest folder and run ‘make’
2. Go to PerformanceTest\bin\config and run config_convert_1session.sh and config_convert_10session.sh command files. These commands convert 1session.cfg and 10sessions.cfg configuration files from QuickFIX to FIXAntenna™ format. Output files are placed in the folder “converted”
3. Go to “bin” folder and run run_latency_test.sh, run_throughput_1session.sh, run_throughput_10sessions.sh

2. Updating Your Development Project 

This chapter provides step-by-step instructions for changing a project that used QuickFIX C++ library and was created in Microsoft Visual Studio 2010. Similar steps will be necessary in the case of other IDEs or platforms (for example, updating the project’s makefile on Linux).

1. Follow the general FIX Antenna™ installation instructions
2. Remove the references to QuickFIX include and library folders from your project
3. Add the "\B2BITS\FIX Antenna C++\<version>\QFAdaptor\include” and "\B2BITS\FIX Antenna C++\<version>\headers” to your project’s include paths
   
   
   
4. Add new library path to the project: "\B2BITS\FIX Antenna C++\<version>\lib”
   
   
   
5. Add the all_cpp.cpp file that is located in the folder "\B2BITS\FIX Antenna C++\<version>\QFAdaptor\include\qfa\cpp\all_cpp.cpp” to your project so that they are compiled together with the rest of your project files.
   
   
   
6. Link the project with one of the FIX Antenna™ libs in the lib folder depending on release/debug configuration
   
   You may refer to the sample project that is under "\B2BITS\FIX Antenna C++\<version>\QFAdaptor\examples\PerformanceTest\” to see how a project may be set up.
   
   

7. Insert a call to initialize the QF adaptor and the instance of the FIX Antenna™ library used by this adaptor before making further calls to it:

   QFA::InitializeEngineAdaptor("<path>/qfa.adaptor.properties","<path>/engine.properties");

   See the next chapter for the details on producing the .properties files. 

8. At the end of the program, insert a call to shut down the adaptor and the instance of FIX Antenna™ library:

   QFA::ShutdownEngineAdaptor();

3. Converting QuickFIX configuration files

The QuickFIX session configuration files are converted into B2BITS format using the "<path>\B2BITS\FIX Antenna C++\<version>\QFAdaptor\tools\migrate_config\qfa_migrate_config.pl” script. In order to use this script, Perl interpreter version 5.6 or later has to be available. Under Windows, we recommend using the ActivePerl distribution.

In order to check the presence and version of Perl, use the following command line:

perl --version

The migration tool consists of the following files:

• qfa_migrate_config.pl  – Perl script
• engine.properties.template, qfa.adaptor.properties.template – Template files that are used to produce appropriate output files.

Tool invocation

To convert a QuickFIX.CFG file go to the folder where it resides and invoke the following command:

<path>\QFAdaptor\tools\migrate_config\qfa_migrate_config.pl <command like parameters>

Refer to the “example_conversion.cmd” file in the migrate_config folder to see how the command is used.

Below are the qfa_migrate_config.pl command line parameters:

Usage: qfa_migrate_config.pl <QuickFIX config file> <Engine RootDir setting> [Output directory]
Mandatory parameters:
	"QuickFIX config file" 		Source file to be converted
	"RootDir setting" 			Path to the fix engine root directory where the message store and log files will reside


Optional parameters:
	"Output directory" 			Where to put the generated configuration files. If omitted, a new folder in current directory will be created.

The script parses the QuickFIX configuration file, maps the QuickFIX settings to the FIX Antenna™ settings, and creates the output file. Notice the ERRORs or WARNINGs messages that may be generated by the conversion script when it fails to produce proper mapping and try to correct the cause.

The conversion script will create the following three files¹:

• engine.properties – FIX Antenna™ engine global settings. The path to this file is then passed to the QFA::InitializeEngineAdaptor() call.
• qfa.adaptor.properties – The settings used specifically by the adaptor classes that provide the QuickFIX interface for the user application. The path to this file is passed to the QFA::InitializeEngineAdaptor() call.
• example.qfa.sessions² – This is the FIX session definition file. There can be multiple files of such kind used by an application. The path to the file is passed to an instance of FIX::SessionSettings class.

Note that two of the files, engine.properties, and qfa.adaptor.properties, are used globally and are to be passed to the adaptor initialization call. There can be multiple *.qfa.sessions files used by your program and each conversion would produce the engine.properties and qfa.adaptor.properties files. If this is the case, review the produced engine.properties and qfa.adaptor.properties files (compare the file content) and chose the files for the QFA::InitializeEngineAdaptor() call.

IMPORTANT: The following properties of the global engine.properties file are updated by the migration script and are shared between all FIX connections:

• ListenPort – this is the setting copied from SocketAcceptorPort of the QuickFIX configuration file
• EngineRoot – the path used to resolve the log and message store relative paths
• Log.File.RootDir – the path to the additional log folder (set to be <EngineRoot>/logs)
• LogonTimeFrame, LogoutTimeFrame, AllowEmptyFieldValue, MessageMustBeValidated
• standard FIX XML files listed in DictionariesFilesList of engine.properties file

The following properties of the global qfa.adaptor.properties file are updated by the migration script and are shared between all FIX connections:

• Log.File.RootDir – the path to the folder where the QF adaptor stores its own logs (set to be <EngineRoot>/logs)

The following properties in qfa.adaptor.properties are to be set up by the user if necessary:

• new FIX dictionaries (besides standard ones in engine.properties) are listed in QFA.CustomVersion.<name> properties of qfa.adaptor.properties file

Backup FIX Connection

If the QuickFIX configuration file specifies SocketConnectHost1/ SocketConnectPort1 pair, this is converted to the Backup connection properties of the FIX Antenna™ thus enabling to switch to this connection if the primary connection breaks.

Log files to be watched on run-time

After starting the engine, the following log files will be created:

• <EngineRoot>/logs/qfa_engine_<digits>.log – the FIX Antenna™ engine log
• <EngineRoot>/logs/qfa_engine_adaptor.log – the QF adaptor log
• <EngineRoot>/logs/SENDER-TARGET_<digits>.conf – this file will contain the list of actual FIX Antenna™ session settings used when creating particular FIX session identified by <SENDER, TARGET>

4. Converting customized QuickFIX protocol dictionaries for use with FIX Antenna C++ engine

If your project uses customized FIX protocol definitions, you may convert them into FIXDIC format by using the utility “<path>\QFAdaptor\tools\xml_dict_conversion\dict_convert.cmd”.

After conversion, you can replace the old dictionary with a new one in DictionariesFilesList the engine.properties.

Note that by replacing the standard FIXT11 dictionary all other FIX50 protocol versions are getting affected.

“FIX42 “ and “FIX50SP2“ are the FIX version identifiers that can be passed in string format to API functions that accept “const char* customFIXVersion” parameters, such as FIX::DataDictionary, FIX::Message, etc.

Besides that, the Engine::FIXVersion enumeration can be used to pass constants like FIX42, and FIX50SP2 to functions that accept Engine::FIXVersion parameter type.

Pass the path to QuickFIX XML in the “input_file” parameter and the path to the output file in the “out” parameter.

The produced XML file should then be mentioned in the qfa.adaptor.properties file like below:

# Enumerates custom protocol definitions (this is a comma-separated list)
QFA.CustomVersions = FIXcustom
# Base FIX version of custom protocol. Required.
QFA.CustomVersion.FIXcustom.BaseProtocol = FIX42
# XML additional fields file that provides protocol customization
QFA.CustomVersion.FIXcustom.AdditionalFieldsFileName = <path>/ customdict44_engine.xml

The same identifier (e.g. FIXcustom) will be used later in a session configuration file to specify that this particular session is using the FIX dialect, for example, consider example.qfa.sessions file with the following setting:

QFA.Session.CLIENT1@EXECUTOR@FIX42.Version=FIXcustom

Creating Messages in C++ using customized FIX dictionaries

The following are examples of how to create messages using custom dictionaries. The syntax is different compared with QuickFIX.

Example 1. Creating an ExecutionReport message using the session’s FIX dictionary. Depending on what was configured for this session it might be a custom dictionary.

FIX::Session* session = FIX::Session::lookupSession(sessionID);
FIX::Message msg( *session, QFA::MsgType_ExecutionReport);

Example 2. Creating an ExecutionReport message using the FIXcustom dictionary configured in the qfa.adaptor.properties file.

FIX::Message msg( "FIXcustomVersion", QFA::MsgType_ExecutionReport);
FIX50::Message msg( “FIX50SP2JSE”, QFA::MsgType_ExecutionReport);

Example 3. Creating an ExecutionReport message using the FIXcustom dictionary configured in the qfa.adaptor.properties file and C++ classes generated for this dictionary. See the following chapters for more info:
Generate Message Classes that bind to Custom FIX Protocols and New C++ namespace for custom FIX protocols

FIXcustom::Message msg( QFA::MsgType_ExecutionReport);
FIXcustom::ExecutionReport msg( … );
FIX42::ExecutionReport msg( … );

5. Converting customized QuickFIX protocol dictionaries for CPP code generator

Use the utility “<path>\QFAdaptor\tools\xml_dict_conversion\dict_convert_for_cpp.cmd” to convert QuickFIX XML definition into XML format suitable for further use with CPP code generator tool. This .CMD file is an example how to invoke the conversion tool.

6. Generating C++ business objects for standard or customized FIX protocol versions

Note: the CppGenerator.exe application is a Windows executable. When using the Linux version of the QF adaptor package, please unpack it on Windows and run the tool there.

Alternative 1. QuickFIX dictionary XML to CPP conversion

This method is the recommended way of generating CPP classes, it uses QuickFIX dictionaries as the source.

1. Go to <path>\QFAdaptor\tools\cpp_code_generator\quickfix-dict folder
2. Copy FIX40.xml, FIX41.xml, FIX42.xml, FIX43.xml, FIX44.xml, FIX50.xml, FIX50SP1.xml, FIX50SP2.xml, FIXT11.xml from quickfix/spec folder of your QuickFIX/C++ distribution to quickfix-input folder.
3. Add any custom dictionary files you would like to convert to the quickfix-input folder
4. Edit the quickfix-to-qfa-to-cpp.cmd file if any custom XMLs are used. Typically you would replace one of the existing FIXnn files with a custom one. Please refer to the following chapter if you would like to keep the base FIXnn version untouched and see your custom FIX protocol as a separate version of FIX protocol with new C++ message classes for business messages: Generate Message Classes that bind to Custom FIX Protocol.
5. New C++ namespace for custom FIX protocol
6. Run quickfix-to-qfa-to-cpp.cmd command (on Linux use the .sh script)
7. Copy the contents of generated “qfa” folder to <path>\QFAdaptor\include\qfa. This will overwrite existing files in this folder.

Alternative 2. FIX Antenna XML to CPP conversion

This method is recommended in the case when one wants to generate the C++ classes for business messages directly out of the FIX Antenna FIXDIC XML dictionaries rather than out of the QuickFIX dictionaries.

The business message C++ classes can be generated from FIX Antenna ™ dictionaries using the <path>\QFAdaptor\tools\cpp_code_generator\qfa-generate.cmd utility (or .sh script on Linux). This command file can be further modified by the user who wants to produce the classes for customized FIX protocols. For example, consider changing the following command line in this .cmd file:

bin\CodeGenerator.exe fixdic-input\fixdic40.xml fixdic-input\fixdic41.xml fixdicinput\
fixdic42.xml fixdic-input\fixdic43.xml fixdic-input\fixdic44.xml fixdicinput\
fixdic50.xml fixdic-input\fixdic50sp1.xml fixdic-input\fixdic50sp2.xml fixdicinput\
fixdict11.xml

and replace the text fixdic-input\fixdic44.xml with a path to a custom FIX protocol definition. Such a definition can be produced from QuickFIX XML, refer to this chapter for the instructions: Converting customized QuickFIX protocol dictionaries for CPP code generator.

Note that the XMLs for all the FIX versions should be passed to this utility for processing at once (i.e. all files to be passed in the single command line, the code generator is not to be invoked for one individual file) because the code generator has to collect the definitions from all versions of the files to create consolidated lists in output files. This includes definitions for FIX tag numbers, message field values, etc.

After running the command, the “qfa” folder with the .H files is created. Copy the contents to the qfa folder located at: <path>\QFAdaptor\include\qfa

Generate Message Classes that bind to Custom FIX Protocols

When custom FIX protocol XML dictionaries are used, it may be desired to generate CPP message classes that will support the custom fields and groups defined in that dictionary. Then it will be possible to access these fields using get/set methods, for example, message.get( FIX42::MyNewField ).

In contrast to standard FIX 4.x and 5.x protocols, the custom protocols are loaded from XML and registered in the FIX Antenna engine and QFA adaptor. The message classes need also to know how to find the custom dictionary when the message object is created.

The custom FIX protocols are defined in qfa.adaptor.properties file in QFA.CustomVersion… properties. Refer to the chapter for more info: 4. Converting customized QuickFIX protocol dictionaries for use with FIX Antenna C++ engine. The custom protocol is identified by an ID, which is a string, e.g. “CustomFIX44”.

In order to pass this information to the CPP code generator, the “customFIXVer” attribute should be specified for the XML dictionary file that is passed to the tool in <path>\QFAdaptor\tools\cpp_code_generator\quickfix-to-qfato-cpp.cmd:

fixdic-input\fixdic44.xml@customFIXVer=MY_Custom_FIX44@param2=....

where MY_Custom_FIX44 is the name of the custom protocol defined in qfa.adaptor.properties file.

New C++ namespace for custom FIX protocols

By default, the business message C++ classes are created in FIXnn namespace which corresponds to the FIX base protocol version taken from the XML. If you’d like to place your customized protocol classes into a separate distinct namespace, pass the XML file to bin\CodeGenerator.exe command as follows:

fixdicinput\fixdic44.xml@namespace=MY_Custom_FIX44@param2=....

As long as the MessageCracker class cannot distinguish between the base FIX version and your custom version since the BeginString field of the message will contain the base FIX version number, you would have to do the message class conversion on your own, for example, consider modifying <path>\QFAdaptor\include\qfa\MessageCracker.h like follows:

#include  // add this include

class MessageCracker :
	 public FIX40::MessageCracker,
	 public FIX41::MessageCracker,
	 public FIX42::MessageCracker,
	 public FIX43::MessageCracker,
	 public FIX44::MessageCracker,
	 public FIX50::MessageCracker,
	 public FIX50SP1::MessageCracker,
	 public FIX50SP2::MessageCracker,
	 public FIXT11::MessageCracker,
	 public MY_Custom_FIX44::MessageCracker 	// add new class inheritance
{
public:
	 virtual void crack( const Message& message, const SessionID& sessID)
	 {
		 Engine::FIXVersion ver = message.getMsgVer();
		 switch(ver)
		 {
			 case Engine::FIX40:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX41:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX42:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX43:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX44:
				 if( sessID.sessionQualifier_ == " || sessID.senderCompID_ == "" ) 		// or put any other appropriate condition here...
				 return static_cast< MY_Custom_FIX44::MessageCracker*>(this)->
					 crack( static_cast(message),
sessID );
			 else
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX50:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX50SP1:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIX50SP2:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
			 case Engine::FIXT11:
				 return static_cast(this)->
					 crack( static_cast(message), sessID );
 		}
}

7. Converting existing B2BITS FIX protocol customizations into QuickFIX C++ business objects

B2BITS can provide you with FIX protocol customizations used to connect to various destinations. Let’s consider the MICEX exchange as an example. There will be the micex_fix.xml file which defines additional fields used in some FIX messages. This file is to be mentioned in QFA.CustomVersions property of qfa.adaptor.properties file.

In order to obtain the C++ classes for customized business messages follow these steps:

1. Merge the micex_fix.xml customization with the base protocol, for example FIX44. Use the <path>\QFAdaptor\tools\xml_dict_conversion\dict_merge.cmd command line to do the merging.
2. Take the merged XML file and follow the instructions specified in the chapter Generating C++ business objects for standard or customized FIX protocol versions

APPENDIX A. Configuration Reference

engine.properties File

Also refer to the latest version of documentation on the B2BITS web site: engine.properties or documentation in your FIX Antenna™ distribution: <path>\B2Bits\FIX Antenna C++\<version>\doc\index.html

qfa.adaptor.properties File

qfa.sessions File