OnixS C++ CBOE CFE Binary Order Entry (BOE) Handler  1.0.0
API documentation
Getting Started

All Handler classes are encapsulated into the OnixS::CboeCFE::Trading::BOE namespace. Header files are collected in the master "OnixS/CboeCFE/Trading/BOE.h" header file.

The typical way of using the Handler is as follows:

Handler Settings

The OnixS::CboeCFE::Trading::BOE::Handler constructor accepts an instance of the OnixS::CboeCFE::Trading::BOE::HandlerSettings class which defines values for various parameters that affect Handler's behavior. The section below describes the most important parameters.

Primary Settings

Directory for Log Files

By default,the Handler logs all important aspects of its activity while processing market data. Therefore, it must know where on local file system it can store this kind of information. The OnixS::CboeCFE::Trading::BOE::HandlerSettings::logDirectory parameter value must be defined to point the Handler in which directory it can place its log files.

Licensing the Handler

The Handler needs a license for successful execution. If the Handler is not able to find a valid License, it will throw an exception at the initialization stage.

The OnixS::CboeCFE::Trading::BOE::HandlerSettings structure exposes the OnixS::CboeCFE::Trading::BOE::HandlerSettings::licenseDirectory parameter which allows to instruct the Handler where to look for a valid license. By default, the Handler looks for a license in the current directory for the application which uses the Handler.

The Handler looks for a valid license in the specified folder and selects the best one. If multiple license is available, it will select most significant one (for example, Production instead of Trial if both are available).


Following example demonstrates how to setup primary settings for the Handler:

int main (int argc, char* argv[])
HandlerSettings settings;
// This option is used to control verbosity of logger.
// This option is used to specify extra logger settings.
// Logs will be stored in 'logs' local sub folder.
settings.logDirectory = "logs";
// This option is used to instruct the Handler where to look for a valid license.
settings.licenseDirectory = "../../license";
Handler handler (settings);
// ...


Before sending application messages an authorized connection must be established. This assumes providing username, password along with host and port and exchange protocol setup.

Most of the fields of the messages sent by the exchange are optional. The setup assumes choosing the fields the used want to recieve.

Each incoming message has a correspondent class to select fields the user interested in. For example, OrderAcknowledgment has correspondent OrderAcknowledgmentReturnFields class. To receive 'capacity' (Corresponds to OrderCapacity(47) in CFE FIX) field OrderAcknowledgmentReturnFields::enableCapacity() must be invoked. Then the object of OrderAcknowledgmentReturnFields must be passed to Handler::connect call.

// ...
LogonSettings logonSettings;
logonSettings.sessionSubId = sessionSubId;
logonSettings.userName = userName;
logonSettings.password = password;
OrderAcknowledgmentReturnFields orderAcknowledgmentReturnFields;
// Choose fields we want to receive in OrderAcknowledgment message
ReturnBitfieldsGroup returnBitfields;
handler.connect(logonSettings, returnBitfields, host, port);
// ...

After this setup, OrderAcknowledgment messages will have the following form:

1 OrderAcknowledgment [transactionTime=1516115893978365000, clOrdID=ABC125, orderID=150966786308967136, capacity=Customer, baseLiquidityIndicator=AddedLiquidity, subLiquidityIndicator=NoAdditionalInformation]

The other messages can be configured the same way.

Error Handling

Error Handling Concept

Being C++ class library, the Handler uses exceptions to Cashrt about error occurred while performing certain action. For example, the Handler will raise regular exception to Cashrt about inability to find actual license for the product. However, the Handler processes market data asynchronously, therefore it is not able to Cashrt about any further errors since market data processing is started. For this reason, the Handler exposes the OnixS::CboeCFE::Trading::BOE::ErrorListener interface and the OnixS::CboeCFE::Trading::BOE::Handler::registerErrorListener member to be able to subscribe and handle errors.

Once instance of OnixS::CboeCFE::Trading::BOE::ErrorListener is assigned to the Handler, it will invoke the OnixS::CboeCFE::Trading::BOE::ErrorListener::onError member each time error occurs. The OnixS::CboeCFE::Trading::BOE::ErrorListener::onError member has several incoming parameters one of which defines human-readable explanation (description) of the error.


Following sample demonstrates how to receive error notifications:

// ErrorListener interface can be hidden from publicity
// to make Handler 'exclusive' user of onError member.
class ErrorDumper : ErrorListener
// Assigns itself to given handler as error listener.
ErrorDumper(Handler& handler)
// Implements base interface to dump errors onto console.
virtual void onError(ErrorCode::Enum code, const std::string& description)
std::cout << "Error occurred, errorCode = " << enumToString (code) << ". Description: '" << description << "'" << std::endl;
Handler handler(handlerSettings);
ErrorDumper errorDumper(handler);

Warning Handling

Warnings Concept

Miscellaneous non-critical issues may occur while the Handler is being executed. The Handler will handle such issues by itself, thus no special handling is required for such cases. However, sometimes it's reasonable to be notified about such events. For this reason, a handler exposes the OnixS::CboeCFE::Trading::BOE::WarningListener class and will invoke its OnixS::CboeCFE::Trading::BOE::WarningListener::onWarning member each time a non-critical issue will take place.

Listening to incoming messages

Events in the Handler

Once the Handler is started, it listens to a message from the Mts Cash/SDP message flow, processes it and invokes client code for further processing.

The Handler processes messages asynchronously and uses concept of events and event listeners to notify client code about a particular occasion like reception of record.

Listening for a particular Event

For each event like Error Occurred Handler provides an interface (C++ class with pure virtual members) like OnixS::CboeCFE::Trading::BOE::ErrorListener. Client code must implement this interface (C++ class) to be able to handle events of a particular type. The Handler also exposes a member like OnixS::CboeCFE::Trading::BOE::Handler::registerErrorListener which allows to associate an instance of the event handler with an appropriate event in bounds of a particular instance of the OnixS::CboeCFE::Trading::BOE::Handler class.

Associating listener for a particular event with an instance of the OnixS::CboeCFE::Trading::BOE::Handler class must be performed while the Handler is in disconnected state. Once the Handler is started, changing listener-event associations is not allowed and can lead to unpredictable behavior as well as can cause unexpected errors.

Associating event listener with an instance of the OnixS::CboeCFE::Trading::BOE::Handler class is also called subscribing to an event.

For more and up-to-date information on getting started aspects, see GettingStarted sample from the samples collection available in distributive package.