Description
In earlier versions of FIX Antenna (2.10.14 and earlier) any session object could be uniquely identified by SenderCompId/TargetCompId pair.There were number of methods in external interface of FIX Antenna (like Engine::createSession) which took SenderCompId and TargetCompId parameters to identify session.
Starting from version 2.10.15.5 extra string identifier - SessionQualifier has been introduced in addition to SenderCompId/TargetCompId pair. The idea is to give user ability to create several sessions with the same SenderCompId and TargetCompId and to give ability to address these session by unique ID. To achieve this goal, SessionId structure was introduced. The structure consists of three string properties - sender_, target_ and qualifier_. Many of external methods still can be called with only SenderCompId and TargetCompId parameters. However, if user needs to create several sessions with the same SenderCompId/TargetCompId pair they first need to create SessionId structure by passing SenderCompId, TargetCompId and unique SessionQualifier to its constructor, and then call overloaded method which takes SessionId structure as one of arguments.
To establish several sessions with the same SenderCompId and TargetCompId, both Initiator and Acceptor should create several session objects which differ from each other by SessionQualifier property. SessionQualifier property on Initiator side must be the same as SessionQualifier property of the corresponding session on acceptor side. When Initiator connects to Acceptor, it sends SessionQualifier along with SenderCompId and TargetCompId in logon message. The SessionQualifier tag in logon message is optional and can be configured in engine.properties file. When Acceptor receives logon message with the SessionQualifier it searches for registered session with SessionId corresponding to received TargetCompId, SenderCompId and SessionQualifier. If the session is found it is associated with the incoming connection, otherwise connection is rejected
If user creates session by passing only SenderCompId and TargetCompId parameters (without SessionQualifier), the SessionId structure is created and stored internally with empty qualifier_ property. If Acceptor registers a session without session qualifier it won't accept any incoming connection with session qualifier defined in logon message. And vice versa, if Acceptor has registered a session or several sessions with qualifiers, it won't accept connections from Initiators without SessionQualifier.
The FIX engine will automatically insert SessionQualifier tag into logon message if user creates session with qualifier on initiator side and SessionQualifier tag is appropriately configured in engine.properties. To configure SessionQualifier tag user needs to add the lines like below to config file -
Session.Default.LogonMessageSessionQualifierTag = 9012
User can also overload LogonMessageSessionQualifierTag property for any particular session like below
Session.Sender1/Target1.LogonMessageSessionQualifierTag = 9015
If user wish to define or overload some other properties for any session with session qualifier they can add a configuration line like in example below
Session.Sender1/Target1/Q1.StorageType=null
Wherever possible, if SessionQualifier is defined for a session, the string representation of the session's identifier will consist of Sender, Target and SessionQualifier (separated by a delimiter). If SessionQualifier qualifier is not defined, it will be omitted in any output related to session identifier. This is done for backward compatibility. The possible affected places are log files (names and content), admin protocol messages, keys of message storage and so on.
External acceptor applications
If Acceptor application doesn't use FIX Antenna library it may define its own rules on how to determine correspondence between sessions on initiator and acceptor side. For example, it may distinguish sessions based on TCP port which they are connected to. In this case, passing Session Qualifier in Logon message is not necessary and may even lead to rejection by acceptor side.
To disable passing Session Qualifier in Logon Message, it's enough just not add the LogonMessageSessionQualifierTag to configuration file. If user wants to disable passing Session Qualifier in Logon Message only for some particular session, they may add lines like below to configuration file
Session.Default.LogonMessageSessionQualifierTag = 9012
Session.Sender1/Target1.LogonMessageSessionQualifierTag = 0
In this example all sessions except "Sender1/Target1" will pass Session Qualifier as tag 9012 in Logon message.
Sample
The SessionQualifier sample application can be found in FA C++ package under "samples" directory.
The sample application registers two sessions with ids Acceptor1@Initiator@1 and Acceptor1@Initiator@2 on acceptor side. Then two Initiator sessions with ids Initiator@Acceptor1@1 and Initiator@Acceptor1@2 establish simultaneous connections to corresponding acceptor sessions and send order messages and receive responses.
At next step, initiator creates two sessions with ids Initiator@Acceptor2@1 and Initiator@Acceptor2@2 and connects to acceptor. Acceptor creates and registers corresponding sessions in onUnregisteredAcceptor handler. After having connections established, the initiator sessions send order messages and receive responses.
At the end all sessions are closed.
The information about received logon and logout messages as well as content of orders and execution reports messages can be seen in console. Logs are collected in directory "bin/logs".
To run sample just enter "sample/SessionQualifier/bin" directory and start run_*.bat on Windows or run.sh on Linux. To run debug version use corresponding command files with letter 'D' at the end. Note, the debug binaries are not included in the package, user needs to build them before running.