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:

• Create an instance of OnixS::CboeCFE::Trading::BOE::HandlerSettings class and adjust Handler's settings.
• Create an instance of OnixS::CboeCFE::Trading::BOE::Handler class using previously initialized instance of OnixS::CboeCFE::Trading::BOE::HandlerSettings.
• Register error and warning listener to be notified about failures occurred while the Handler processes market data.
• Register listeners for miscellaneous trading events.
• Establish the connection using the OnixS::CboeCFE::Trading::BOE::Handler::connect method.
• Start sending messages.
• Terminate the connection to Mts Cash using the OnixS::CboeCFE::Trading::BOE::Handler::disconnect(..) method.

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.

Note

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).

Example

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

using namespace OnixS::CboeCFE::Trading::BOE;

int main (int argc, char* argv[])
{
    HandlerSettings settings;

    // This option is used to control verbosity of logger.
    settings.logLevel = LogLevel::Debug;

    // This option is used to specify extra logger settings.
    settings.logSettings = LogSettings::Default;

    // 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);

    // ...
}

Connecting

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

using namespace OnixS::CboeCFE::Trading::BOE;

// ...

LogonSettings logonSettings;
logonSettings.sessionSubId = sessionSubId;
logonSettings.userName = userName;
logonSettings.password = password;

handler.connect(logonSettings, host, port);

 // ...

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.

Example

Following sample demonstrates how to receive error notifications:

using namespace OnixS::CboeCFE::Trading::BOE;

// ErrorListener interface can be hidden from publicity 
// to make Handler 'exclusive' user of onError member.

class ErrorDumper : ErrorListener
{
public:
    // Assigns itself to given handler as error listener.
    ErrorDumper(Handler& handler)
    {
        handler.registerErrorListener(this);
    }

private:
    // 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.

Note

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.

Note

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