OSE Library Interface and Usage Guidelines

Contents

1. Abstract

OSE2 Access Library is a set of C++ components and interfaces designed to provide high-level access to Osaka Securities Exchange electronic Trading System (OSE-TS). Library components manage physical and logical connections with OSE-TS, allowing client to concentrate more on financial data manipulations. Library also provides representation of OSE-TS protocol messages and Data Items as a set of C++ classes with access methods for message fields specified by OSE-TS protocol.

NOTE: In this document OSE2 Access Library refers to a set of components for managing trading session with OSE Trading System Auction Trading.

NOTE: Access Library name prefix “OSE2” has been chosen because of internal naming conventions of JASMIN Exchange Access Library package designed and developed by Orchid Technolody K.K.

2. Design goals

3. A note about OSE-TS system

3.1 OSE-TS system overview

OSE Trading System consists of AP/DP server, which processes trading transactions, Communication Server, which acts as a front end for OSE system, handles connections with Transaction Participant System (TPS), which provides access to OSE-TS for Virtual Clients (Users).

OSE-TS system overview
In common case Transaction Participant System (TPS) consists of several Virtual Clients (Users) logged in to Logical Terminal.

A number of Communication and AP/DB servers exist in the OSE-TS system. Communication Server assigned to Transaction Participant System receives Order and other messages from TPS and delivers them to appropriate AP/DB server; it also collects Notification messages from AP/DB server and delivers them to Transaction Participant System.

For TPS ßà OSE-TS data exchange “Application Link” should be set up with Communication Server by establishing of  TCP/IP connection using specified IP addresses, Port numbers, Communication Server ID, Logical Terminal ID, Transaction Participant Code and other identification data provided by OSE-TS.

“Notification Link” should be established to receive Notification messages from OSE-TS.

3.2 OSE-TS session states


OSE-TS session begins with establishment of so called “Application Link”. It could be done after successfult TCP/IP connection by sending an “Application Start” request message with identification data required by OSE-TS. If authentification has completed normally, OSE-TS answers with “Application Start Response” message with Response Result Code “Normal”(0000) and most recent Receipt/Execute Notification Sequence numbers transmitted by OSE-TS. After that, OSE-TS sends information about current status of system and Products. This information is delivered by OSE-TS “Application Status” messages. “Application Link” is established after receiving “Application Start Response” and “Application Status” message(s). “Application Status” messages may be received from OSE-TS in batches of up to 20 Data Items if Logical Terminal has been prescribed by OSE advance application form.

Successfully established “Application Link” may be used to establish “Order Link” for user with User ID to allow sending “Order” messages to OSE-TS. To provide this additional Login procedure must be performed by sending “Login Request” message with specified User ID and Password to OSE-TS. After receiving “Login Response” message with “Normal” Response Result Code “Order Link” is established, and “Order” messages may be send for this user from Client Application to OSE-TS. Multiple “Login Request” messages for on Logical Terminal with different User IDs are supported by OSE-TS.

If Client Application needs to receive OSE-TS “Notification” Messages then “Notification Link” should be established after “Application Link” established successfully. It may be done by sending “Notification Start Request” message to OSE-TS. Notification Link is established if “Notification Start Response” with “Normal” Response Result Code received from OSE-TS.

3.3 Data flow

OSE-TS specifies several types of messages used in data exchange between Transaction Participant System and OSE-TS Communication Server. Those are “One-query-one-response” messages and “Broadcast” messages. These two types of messages are independent and can be sent in parallel.

By OSE-TS protocol requirements for every sent “One-query-one-response” message correspondent Response message must be sent back. Next “One-query-one-response” message may be sent only after Response message received.“Broadcast” messages do not require any Responses to be sent back.

For example, “Notification Start Request”, “Order” – are “One-query-one-response” messages and “System Error”, “Keep Alive” –  are “Broadcast” messages.

Order Data Items can be blocked into batches of up to 20 Data Items into one OSE-TS “Order” message for transmission from one Logical Terminal and different Virtual Clients (Users). All types of Order Data Items (such as New, Correction, Cancellation) are allowed in one batch. Once put together, batch is send as a single upstream “Order” message to OSE-TS. Number and sequence of Data Items in correspondent “Order Response” message received by TPS is the same as in correspondent “Order” message.

Specific messages which may be received by TPS are “Notification” messages. “Notification” messages are “One-query-one-response” messages. For every “Notification” message received by TPS, the correspondent Response message must be sent back to OSE-TS. “Notification” messages may be sent OSE-TS in batches of up to 20 Data Items, only if Logical Terminal has been declared in advance for blocking.

3.4 Sequence numbers and recovery mechanisms on OSE-TS

All messages sent/received to/from OSE-TS have special field in message header called “Message Sequence Number”. This field may be filled by TPS Client Application for some messages and for some messages it should be filled with spaces.

According to OSE-TS Specification contents of this field is never checked by OSE-TS. OSE-TS just copies the contents of this field when sending the response message to the TPS Client.

OSE-TS system introduces several types of Notifications. These Notification types are Receipt Notifications and Execute (Result) Notifications.

Each type of Notification is assigned its own Sequence Numbers. Notification Sequence Numbers are calculated and assigned by OSE-TS and should be returned with no changes by TPS in correspondent fields of Response messages. Notification Sequence Numbers are managed by OSE-TS and TPS and used to prevent duplicatied or missing notification messages.

OSE-TS system provides its clients with recovery mechanisms. Clients can request notifications to be retransmitted or to be re-routed from one of its Logical Terminals to another. These facilities are provided by OSE-TS via mechanism of Operating Messages such as “Retransmit Request” and “Proxy Request”.

4. Library Interface

4.1 Introduction to library interface

When client application code uses OSE2 Access Library, it operates with abstract entities called “Session”. In terms of C++, a single session with OSE-TS is represented by an object, which exposes a set of methods to control session state, sends commands(requests) to OSE-TS using Control Messages, Operating Messages and post financial transactions(also called Order(Application) Messages). As OSE-TS provides responses to posted commands(requests) and transactions, session object delivers those via a set of event notification callbacks.

An important notice is to be made: no interface method invocation results in a synchronous callback! Result of an operation is always provided as an interface method return value.Thus, client application code is protected from re-entries. On the contrary, a callback handler can safely invoke library interface methods.
Both exposed methods and delivered events form OSE2 Access Library interface, are described in more details in this section.

4.2 Session control and session state

Communication between TPS client and OSE-TS system can be thought of as two-layer. Lower level has little idea about financial information flow, its duties include:

Low level operations are represented by IOSE2_SessionControl interface. It is an abstract C++ structure, which contains two data types and several methods. The data types are:

After receiving "Application Start Response" message with Response Result Code “Normal”(0000), session object enters eOSE2_Online state, otherwise eOSE2_Disconnecting state and then after drop-off procedure to eOSE2_Disconnected state.


Session control methods are:

Invocations of methods listed above generally may result in response actions from OSE-TS side. All OSE-TS response messages are translated by session object into C++ callbacks, which are brought together by notification interface IOSE2_SessionNotification. This interface is also represented by a C++ structure that contains one data type and several event callback prototypes. Client code willing to receive session level notifications needs to derive from IOSE2_SessionNotification, implement its methods and provide session object with implementation. Data type enclosed in IOSE2_SessionNotification is described below:

An application that makes use of OSE2 Access Library can potentially have more than one session established with OSE-TS system, hence, it needs to differentiate between session objects.

OSE2 Access Library provides an additional property for session object, called "session ID" - an integer number assigned by client during session object construction. Sesison ID is of type TOSE2SessionID, which is a typedef for C++ unsigned long. OSE2 Access Library makes no use of this identifier, only provides it as the first parameter with every event callback for corresponding session.

Event callbacks notify clients about library session object events (such as OSE-TS disconnection) and about protocol messages received from OSE-TS.

Not all received messages cause callback invocation. For example, “Heartbeat” messages received from OSE-TS are processed automatically by the library object and there is no callback invocation in this case.

Callback parameter values provide all necessary data about correspondent event.

Pointers (e.g. const char*) and Data Iterators (e.g. CASDIIterator) with received data provided as callback parameters remain valid only inside callback invocation. Data contents should be copied by client application code to use them outside of the scope of callback invocation.

Event callback prototypes are described below:

4.3 Posting Orders and receiving Notifications

Two interfaces described above give user means to control a single OSE-TS session and receive information about session state transitions and session-level events. Rest of functionality, which includes formatting and posting financial transactions and receiving OSE-TS Notifications, is provided by the other two interfaces that represent the upper level of OSE2 Access Library. Unlike previously described session-related interfaces, these two are unaware of any session level details. Upper level interfaces handle the following tasks:

Transaction posting functionality is represented by IOSE2_AUCTradeControl interface. It is an abstract C++ structure, which has two data types and several methods. Data types are:

OSE2 Access Library's trading interface covers two different strategies of posting transactions.

First one implements a "query-one-post-one" algorithm, where user first requests an instance of desired input transaction Data Item, then either fills it with data and posts it, or drops it, releasing resources. A subsequent input transaction Data Item instance cannot be requested from the library without previous one being either posted or dropped. Attempt to do so will cause an error return value of eOSE2_AUCTradeControl_OutOfSequence. Types that represent transaction input Data Items are part of library interface:

Second strategy implies that client code does all routine concerning transaction Data Item formatting and provides library method with a ready buffer. This strategy imposes no extra limitations on how many posts are done in a row.

Taking the above into account, IOSE2_AUCTradeControl interface methods looks like the following:

OSE2 Access Library delivers OSE-TS Notifications to its client via IOSE2_AUCTradeNotification interface. Client code derives from an abstract C++ structure, implements its methods and registers implementation in session object in order to receive Notifications. Basically, all callbacks are similar in that they accept a session identifier, a reference to an object of a special type that represents OSE-TS message header and a reference to a particular Notification Data Item object. Classes representing OSE-TS Notification Data Items provide access and validation methods for all Data Item fields. Notification interface is outlined below:

The only callback that deserves special attention is OSE2_AUC_NotifyOSE2Notification. It is always invoked first, when a Notification message arrives from OSE-TS and it delivers to the client raw Notification buffer which may consist of multiple Notification Data Items blocked by OSE-TS specification rules. If return value is false then session object stops Notification processing and doesn’t invoke separate callbacks for particular Notification Data Items.

4.4 Administrative interface

Aside of the interfaces described above, session object provides initialization methods for user to register callback interfaces and to query control and trade interfaces. Prototypes for those methods are given below:

4.5 Financial data representation

OSE-TS system receives and transmits data over communication media using proprietary ASCII subset character format. OSE2 Access Library provides a convenient system of frame access classes capable of frame parsing and composition. For each data entity, such as an Order Data Item defined in OSE-TS data specification, a corresponding C++ class is defined. All data access classes have similar structure; their code has been automatically generated, based on formal data specification.

Data Item formats utilized by OSE-TS differ for different system types. OSE2 Access Library data framework follows this separation defining every system types data access classes in corresponding separate namespaces. However, since certain session-level messages, such as message header are common for all system types, those are defined in common OSE2:: namespace.

NOTE: Currently OSE2 Access Library defines separate namespaces for data access: OSE2AUC::, covering OSE Auction Trading System only.

Raw frame manipulation

Class CFrameWrapper represents a raw memory buffer allocated somewhere. It does not control buffer's allocation and release, instead it stores buffer pointer and length and provides a set of methods for accessing underlying buffer memory. CFrameWrapper's interface is divided into two parts:

As explained above, all the complexity of data formats used in data specification is concentrated in CFrameWrapper class.

OSE-TS system protocol has specific data formats such as prices and quantities that may require specific alignment and filling. For instance, price can be either 'Market price', 'Limit price', or 'Empty'. On user side such field's value is represented by an instance of CFrameWrapper::SOSE2Price structure.

Integer value fields which may be set to ‘Empty’ value are represented by CFrameWrapper::SUINTWithStatus or CFrameWrapper::SUINT64WithStatus data type.

To summarize, CFrameWrapper class has very simple contents - a pointer to raw buffer and its length. However, it contains sophisticated functionality for manipulating frame's content. CFrameWrapper objects can be instantiated on arbitrary buffers and can be used as a base for frame access classes, which can be attached to and detached from the designated frame.

Frame access classes

Frame access classes represent most valuable part of OSE2 Access library data access framework. Their objective is to simplify procedure of manipulating the content of raw character frames, understood by OSE-TS trading system. Any data block is naturally represented as sequence of fields, frame access classes contain access methods for every individual field.

All Frame Access classes have common functionality, concentrated in the base class - CGenericBlock. As explained in previous section all access classes can be attached to CFrameWrapper instance. This functionality is implemented by CGenericBlock::Attach(), CGenericBlock::Detach() methods. Also, every frame access class has a designated frame, assigned during attach operation. This frame is stored in CGenericBlock::m_Frame member and is accessed by implementations of all field access methods. CGenericBlock class also contains DynamicClone() method for polymorphic creation of frame access instances on the heap. This functionality is useful when instances are stored in heterogeneous containers forming queues or more sophisticated data structures.

Similar to DynamicClone() method of CGenericBlock, all frame access classes have Clone() method, which is not polymorphic and returns created instance to the caller on the stack.

Every field of a data block has special check_Field() method, that should be executed to check whether underlying data is properly formatted. However, individual check_Field() methods are not normally called by library users. Instead there is single check() method that invokes specific check_Field() method for every field in the message.

set_Field() methods are used to assign new values to corresponding fields. There can be several set_Field() for a single field. Different methods accept different parameters. If the parameter of the set_Field() method cannot be converted to valid value for the field, an exception is thrown.

get_Field() method is used to retrieve field's value. It does not accept any parameters and returns converted value via stack. get_Field() should always be applied to properly formatted field, i.e. underlying code assumes that corresponding field has been checked with individual or generic check() method. This assumption allows simpler get_Field() method implementation, that should provide better performance. If prior check() operation has not been performed debug version of the library triggers runtime assertion to signal improper usage on early stage of the software development. There can be several get_Field() methods with different names to return different representations of the field's value.

As mentioned above, set_Field() and check_Field() methods can throw exceptions to signal improper parameter or field's value. Thrown exception has type CBlockException, defined inside frame access class. This class in inherited from global CFrameException class. CFrameException has single member - m_eReason, identifying error code, describing exceptional condition. By itself CBlockException class can be thrown from Attach() and Detach() methods to signal operation error. For example frame access object cannot be properly attached, because supplied frame is too small. In all other cases derived instance is thrown. All CBlockException classes have a single member, identifying the field that caused the exception, so that exception handler can report invalid field and reason for exception.

5. Configuration

When a session object is instantiated, it requires that the following configuration parameters are provided in constructor:

6. Usage guidelines

This section provides guidelines for efficient using OSE2 Access Library in client code. It consists of several points that should be kept in mind when using library.

Session object construction
Single session object is represented by an instance of COSE2AUCImpl class. Session object allows copy construction and assignment to enable its insertion into STL containers. Note that in case of copying, a newly created copy gains control over session lifetime. In case of assignment the object in the left side of the assignment operator gains control over session lifetime.

Invoking session control interface methods
User should always examine session state after a session control interface method failure. Some methods, being improperly invoked, can cause session termination, it is user's responsibility to handle such situations. When session is terminated, session object performs its total state reset. Session statistics returned by interface method is not guaranteed to be any real for a disconnected session object.

Posting transactions
OSE2 Access Library provides two ways to prepare Order Data Items and send it to OSE-TS:

Note that once OSE2_AUC_PostTransaction() or OSE2_AUC_PostForeignTransaction() has succeeded, transaction Data Item is stored within internal Transaction Queue waiting to be posted to OSE-TS. Depending on library configuration _uiOrderCollectionTimeoutMS parameter value, posting may happen immediately or may take some time. If during this time a disconnection from OSE-TS occurs, all Order Data Items stored by library in internal Transaction Queue, but not posted yet, are discarded.

OSE-TS “Final Order Inquiry” Request must be used after session recovery to determine the latest Order Data Item actually received by OSE-TS system.

Notification processing
When library receives a Notification message from OSE-TS, it first invokes OSE2_AUC_NotifyOSE2Notification callback to deliver the whole buffer to client. This callback has default implementation that just returns true. After that, Notification Data Items are extracted one by one and Notification-specific callbacks of IOSE2_AUCTradeNotification interface are invoked. If user only wants to receive the raw buffer, the first callback should be overridden and its implementation should return false. Generally, once a notification callback has returned false, subsequent notification extraction is not performed and notifications remaining in the buffer are discarded. This scenario may be used by applications which don't need to deal with separate notifications and only have to pass the whole buffer further on.

7. Dependencies

Current release of OSE2 Access Library has no specific software or hardware dependencies. Ordinary TCP/IP stack is used for communications and is accessed via sockets interface. OSE2 Access Library can be built on any system that has a standard-compliant C++ compiler and supports major POSIX system calls and Berkeley Sockets interface to TCP protocol.

OSE2 Access Library requires that application's implementation of main loop supports a predefined interface. Library is accompanied with an example of UNIX version of event manager that implements application's main loop. Description of required interface can be found in this document.

OSE2 Access Library's objects will make use of an event logging component if one is provided during construction. Event logging interface supported by library is described in this document. Event logging categories supported by session objects are: all predefined categories, "OSE2.raw.data" (controls dumping of data being passed in hexadecimal format) and "OSE2.comm.debug" (additional debugging information for communication level)

8. Development environment

9. Library usage example code

Library is shipped with a sample application that highlights library features described in this document and can be used as a test console for OSE-TS Trading System. Application reads a configuration file on startup and displays command prompt. User can create OSE2 sessions according to configuration file entries, perform establishing of “Application Link”, “Notification Link”, “Order Link”, load contents of transaction Data Items from text files, send multiple transactions and review state of existing session.

Additional commands are implemented to provide examples of using set_(), get_() check_() methods for OSE2 Access Library implementation of OSE-TS Price format.

Sample application includes implementations of event manager and event logger, which conform to library's requirements.

(C) Orchid Technology K.K. 2005-2008. All rights reserved.