Migration Guide

Although given release is based on the same processing core as a previous major version release, a lot of aspects have been principally redesigned and improved. Given section covers major differences for painless migration from previous releases.

Consolidated Listeners

In previous generations of SDK, listeners were designed to cover smallest aspects of market data processingand thus API contained bunch of listeners to be used to get market-related events handled in a regular application. For example, there was a OnixS::CME::MDP3::SecurityDefinitionListener whose members were involved once instrument definition was received and updated. For each type of book there was corresponding listener exposing books after updates. Atomic book changes could be accessed through another set of listeners.

To reduce overhead caused by necessity of using wide range of listeners and to bring more clarity, most of listeners have been consolidated.

Primary principle was to consolidated Handler, Market Data (message) and Security related events. Table below depicts basic correspondence between old and new listeners.

Old Listeners	New Listener	Notes
OnixS::CME::MDP3::HandlerStateChangeListener OnixS::CME::MDP3::WarningListener OnixS::CME::MDP3::ErrorListener	OnixS::CME::MDH::HandlerListener	State change and issue (warning, error) events were merged into the new listener containing callbacks which are invoked to notify users on various aspects of market data processing by Handler.
OnixS::CME::MDP3::MessageProcessingListener OnixS::CME::MDP3::EventMessageListener OnixS::CME::MDP3::EventListener	OnixS::CME::MDH::MarketDataListener	OnixS::CME::MDH::MarketDataListener represents adoptation of OnixS::CME::MDP3::MessageProcessingListener to the new messaging subsystem. Since unified FIX message container was substituted with typified SBE messages as they are defined in CME specification, listener was enhanced with overloads for each type of new message. Also, new members defining bounds of packet processing have been added. For this reason old EventMessageListener and EventListener listeners were removed from API as the improved market data listener allows to implement given event in easy way.
OnixS::CME::MDP3::SecurityDefinitionListener OnixS::CME::MDP3::MboBookUpdateListener OnixS::CME::MDP3::DirectBookUpdateListener OnixS::CME::MDP3::ImpliedBookUpdateListener OnixS::CME::MDP3::ConsolidatedBookUpdateListener OnixS::CME::MDP3::MboBookChangeListener OnixS::CME::MDP3::DirectBookChangeListener OnixS::CME::MDP3::ImpliedBookChangeListener OnixS::CME::MDP3::TradeListener OnixS::CME::MDP3::OrderIdListener OnixS::CME::MDP3::ElectronicVolumeListener OnixS::CME::MDP3::StatisticsListener OnixS::CME::MDP3::SecurityStatusListener OnixS::CME::MDP3::RequestForQuoteListener	OnixS::CME::MDH::SecurityListener	Security-related events are now consolidated into single listener. Following important changes were done in the how particular cases are handled: Unknown security definitions are now exposed through the OnixS::CME::MDH::SecurityListener::onUndefined member which also allows to update security attributes like security group, asset, etc. Previously, unknown securities were not exposed through security definition listeners. Instead, Handler raised a warning on absence of definition. Trade summary processing has been reworked. Previously, SDK exposed separate listeners for trades and order identifiers providing special indexing for linking order ids with the trades. Now, trades are always reported through the same OnixS::CME::MDH::SecurityListener::onTrade callback. Order ids refering to a particular trade summary can be gathered by the Handler and delivered together with a trade summary instance depending on a trade summary handling strategy controlled by OnixS::CME::MDH::HandlerSettings::tradeProcessing parameter value. See Trade Order Details for more information. Previously, maintenance of books of a particular type was enabled by Handler basing on registering instance of listener for that kind of books. Now, as Book update callbacks consolidated into single listener together with the other events maintenance is explicitly defined by corresponding parameters which define whether particular overload of OnixS::CME::MDH::SecurityListener::onBookUpdate will be invoked by the Handler or not.

Book Management

Previously, maitenance of books of particular type (MBO, direct, implied, consolidated) was automatically enabled by Handler if either corresponding listener was associated with an instance of OnixS::CME::MDH::Handler or book maintenance was forcibly enabled through Handler's settings.

Also, depending on which listeners are registered (for example, listener for atomic changes in direct order book), Handler selected appropriate source of recovery data to catch-up up-to-date market state during late join or after detecting gap in incremental data. For example, if user was interested in receiving MBO book updates without subscribing to MBP book updates, Handler listened to recovery data on MBO snapshot feed only without joining snapshot feed for MBP books.

In given release, Handler's behavior has been improved to be more clear for the users.

Book updates are now exposed through OnixS::CME::MDH::SecurityListener::onBookUpdate members of consolidated listener for security-related data. However, overriding noted virtual member doesn't mean subscribing to a book updates. Book maintenance is explicitly defined by corresponding parameter from OnixS::CME::MDH::HandlerSettings::bookManagement() section:

Parameter Path	Description
handlerSettings.bookManagement().mboBooks().maintain(bool status)	Enables or disables MBO books maintenance
handlerSettings.bookManagement().directBooks().maintain(bool status)	Enables or disables direct books maintenance
handlerSettings.bookManagement().impliedBooks().maintain(bool status)	Enables or disables implied books maintenance
handlerSettings.bookManagement().consolidatedBooks().maintain(bool status)	Enables or disables consolidated books maintenance

Once parameter is turned on, Handler invokes OnixS::CME::MDH::SecurityListener::onBookUpdate overload corresponding to the type of book.

Also, behavior of the Handler in case of market recovery is now controlled by OnixS::CME::MDH::SessionSettings::marketRecovery parameter. It allows to define explicitly whether Handler must listen and process data from either MBO snapshot feed or MBP snapshot feed or both feeds.

Given improvement in behavior of the Handler allows users to obtain desired processing behavior without involving book maintenance.

Book Classes

Book classes have been cleaned up. OnixS::CME::MDP3::BookBase::securityId and OnixS::CME::MDP3::BookBase::lastAppliedSecurityLevelSeqNumber members have been removed.

Data exposed by eliminated members is now consolidated into a new OnixS::CME::MDH::Security class, containing all security-related attributes. Instances of given class are exposed in all callbacks of OnixS::CME::MDH::SecurityListener listener. Therefore, security identifier and instrument-level sequence number are now available for trade and statistics events.

Old Member	New Member	Description
OnixS::CME::MDP3::BookBase::securityId	OnixS::CME::MDH::Security::id	Security id relocated from book to security instance
OnixS::CME::MDP3::BookBase::lastAppliedSecurityLevelSeqNumber	OnixS::CME::MDH::Security::seqNumber	Now available in other security-related callbacks

Feed Engine

Concept of Setting Up Feed Engine was introduced in previous major release of the SDK and given release inherits given concept. However, a few important changes have been made.

Previosly, to provide backward compatibility with older minor releases, feed engine could be constructed explicitly and bound with OnixS::CME::MDH::Handler instances. If no instance of OnixS::CME::MDH::FeedEngine was associated with an instance of OnixS::CME::MDH::Handler, then Handler constructed private instance of the feed engine.

In given release, implicit construction has been eliminated to provide better clarity on Handler behavior and use of system resources. Therefore, to make live market data processing happen, instance of OnixS::CME::MDH::FeedEngine must be constructed and bound to the instance of OnixS::CME::MDH::Handler.

Note

There's no limitation on number of feed engine instances constructed. Therefore, having single instance of OnixS::CME::MDH::FeedEngine for each instance of OnixS::CME::MDH::Handler can be easy be achieved by constructing and binding pair of instances.

Feed Events

Feed-related events have been redesigned. First of all, direct access to sockets used to listen to multicast data has been eliminated. OnixS::CME::MDP3::FeedSocket class is not available any more. Feed identification in events have been improved and now feed is identified by OnixS::CME::MDH::NetFeed class containing primary attributes of the feed which caused an event.

Event listener was enhanced with a new member OnixS::CME::MDH::FeedListener::onFeedPacket allowing to trace market data received by the Handler on a particular feed. An important difference between this callback and the one in OnixS::CME::MDH::MarketDataListener is that given callback is invoked by Handler every time data is received no matter whether this is duplicated or out-of-order data. Given enhancement allows to implement various tracing facilities to determine issues in data reception or its sequencing.

OnixS::CME::MDP3::FeedListener::onFeedSequenceIssues event and related with it functionality was removed from the Handler. Instead, OnixS::CME::MDH::FeedListener::onFeedPacket can be used to trace feeds for the issues.

Instrument Definition Cache

Handler exposes ability to cache instrument definitions received on live instrument feed for further reuse at late join. Previously, Handler used predefined filename and stored cache in a certain location. Therefore, settings exposed boolean parameter OnixS::CME::MDP3::HandlerSettings::cacheSecurityDefinitions which allowed to either enable or disable instrument definition caching.

In given release, behavior was been improved and now Handler allows to specify arbitrary filename and location. Instrument definition caching is enabled while non-empty path to the cache is specified through OnixS::CME::MDH::HandlerSettings::instrumentCache parameter.

Message Processing

One of major improvements done in given release is redesigned message subsystem. In previous releases, market data was exposed through the OnixS::CME::MDP3::Message class representing an unified container of FIX fields. In given release message subsystem has been redesigned. Now market data messages are exposed to the users as they are defined in XML-based specification published by CME. Given approach gives more clarity on data structure and use and increases robustness.

3.X Release	4.X Release
OnixS::CME::MDP3::Message	OnixS::CME::MDH::ChannelReset
	OnixS::CME::MDH::AdminLogin
	OnixS::CME::MDH::AdminLogout
	OnixS::CME::MDH::InstrumentDefinitionFuture
	OnixS::CME::MDH::InstrumentDefinitionSpread
	OnixS::CME::MDH::InstrumentDefinitionOption
	OnixS::CME::MDH::SecurityStatus
	OnixS::CME::MDH::IncrementalRefreshBook
	OnixS::CME::MDH::IncrementalRefreshOrderBook
	OnixS::CME::MDH::IncrementalRefreshTrade
	OnixS::CME::MDH::IncrementalRefreshTradeSummary
	OnixS::CME::MDH::IncrementalRefreshVolume
	OnixS::CME::MDH::IncrementalRefreshSessionStatistics
	OnixS::CME::MDH::IncrementalRefreshDailyStatistics
	OnixS::CME::MDH::IncrementalRefreshLimitsBanding
	OnixS::CME::MDH::SnapshotFullRefresh
	OnixS::CME::MDH::SnapshotFullRefreshOrderBook
	OnixS::CME::MDH::QuoteRequest

OnixS::CME::MDH::MarketDataListener as the listener for the received market data was enhanced with overloads for each type of SBE message.

Additionaly, since given release original network packets received on live feeds are exposed to the users through OnixS::CME::MDH::MarketDataListener interface as instances of OnixS::CME::MDH::Packet class. Correspondently, listener was enhanced with OnixS::CME::MDH::MarketDataListener::onPacket and OnixS::CME::MDH::MarketDataListener::onEndOfPacket allowing to determine bounds of packet processing.

Event And Data Logging

Logging layer was significantly reworked and abstraction of logging service was introduced. Now users can implement their logging service including memory-based ones. SDK offers ready-to-use implementation for logging events into a file.

Following examples depict how to enable file-based logging for the Handler in previous and current releases:

Enabling logging in previous generations of SDK

HandlerSettings handlerSettings;

handlerSettings.logDirectory("logs");
handlerSettings.logMode(LogModes::Debug);
handlerSettings.advancedLogOptions(AdvancedLogOptions::LogEverything);

Handler handler(handlerSettings);

Enabling logging in latest generation of SDK

HandlerSettings handlerSettings;
..
Handler handler(handlerSettings);

//

FileLoggerSettings loggerSettings;

loggerSettings.filename("LogFile.txt");
loggerSettings.severityLevel(LogSeverity::Debug);

FileLogger logger(loggerSettings);

handler.bindLogger(logger);

For more information see Logging Services.

Log File Replay

The behavior of the Handler in case of replaying a log file has been changed. In previous releases, the replay was performed asynchronously. When a user invoked the OnixS::CME::MDH::Handler::start overload, the Handler spawned a new thread. The actual log replay was done in the body of that thread. Therefore, the OnixS::CME::MDH::Handler::start overload returned control to its caller as soon as a new thread was launched. Also, the end of replay could be detected only by using a special listener designed for that purpose.

In the given major release, log file replay is a synchronous operation. Therefore, OnixS::CME::MDH::Handler::replay member does not return unless a log file is replayed. The new behavior simplifies user’s interaction with the replay and reduces the use of the system resources.

However, the previous behavior of the replay functionality can be achieved. Users may launch additional threads and invoke the OnixS::CME::MDH::Handler::replay in the bodies of those threads. The previous behavior is achieved in such way.

Filtering

Starting from given release, SDK exposes improved filtering to the users. Previously, market data filtering was managed by set of routines exposed by the OnixS::CME::MDH::Handler class like OnixS::CME::MDP3::Handler::addSecurityIdFilter. Also, there were inconsistency related with filtering security definitions which consisted in the fact security definitions were not filtered no matter users were interested in them or not.

In given release filtering was been redesigned and eliminates existent albiguities and inconsistencies available in previous releases. According to new concept, filtering is applied to security-related events consolidated into OnixS::CME::MDH::SecurityListener listener. Filtering is not used by the Handler on a market data level, therefore members of OnixS::CME::MDH::MarketDataListener are always invoked under same conditions and filtering has no influence on their invocation.

For more information on how security-related events can be filtered, see Selecting Securities of Interest.