TSE Access Library Interface and Usage Guidelines

Contents

1. Abstract

TSE Access Library is a set of C++ components and interfaces designed to provide high-level access to Tokyo Stock Exchange electronic trading systems using a number of instrument-specific protocols. Library components manage physical and logical connections with TSE systems, allowing client to concentrate on financial data manipulations. Library also provides representation of TSE protocol messages as a set of C++ classes with access methods for all message fields specified by TSE protocol. NOTE: In this document TSE Access Library refers to a set of components for managing trading session with TSE Stocks Trading System. TSE Access Library for Futures, Options and Indexes trading system differs only in financial data representation part.

2. Design goals

3. A note about TSE system

3.1 TSE system overview

The TSE trading system consists of a transaction server, which processes trading transactions, an an intersystem relay server, which acts as a front end for TSE system, handles connections with member systems, relays messages, etc., and a member (client) system.

TSE system overview
A number of transaction servers can co-exist in the system, each processing several markets. Relay server receives transactions and other messages from member system and delivers them to appropriate transaction servers; it also collects notices from transaction servers and delivers them to member systems.
Client system sets up a logical I/O device referred to as "virtual server", which is associated with one market. Term "market" corresponds to TSE product code, available codes are listed in TSE documentation. Examples of products are: stocks, futures, options, convertible bonds, etc. Each virtual server is assigned an identifier (VSID) provided by TSE.

3.2 TSE session states

TSE session begins with a log-on procedure, during which virtual server sends a "Virtual Server Ready" message and relay server responds with "Virtual Server Ready ACK" message. After virtual server receives a VS Ready ACK message, it waits for information about current system and market status. This information is delivered by TSE in a market control message. Once TSE has reported that order input is enabled, client system can post financial transactions. Further market control messages are possible, which indicate changes in the state of TSE system.

3.3 Data flow

TSE protocol specifies two types of messages that can be posted by a virtual server to TSE relay server. Those are transaction messages and instruction messages. Both kinds of messages are input in a one-query-one-response mode. The two kinds of messages are independent and can be input in parallel. One type of messages is specified by TSE protocol for output - those are referred to as notices. Notices are also output in one-query-one-response mode.
Each type of messages mentioned above has a corresponding acknowledgement message: once an acknowledgement is received, next message of corresponding type can be posted.
Orders can be blocked into batches of up to 20 blocks for transmission from virtual server. All types of orders are allowed in one batch. Once put together, batch is send as a single upstream message.
Similarly, notices are received from TSE in batches of up to 10 blocks.

3.4 Sequence numbers and recovery mechanisms on TSE

According to TSE protocol, each order is assigned one sequence number, each notice is assigned two sequence numbers. Order sequence numbers are provided by client system; order sequence number of succeeding order must be greater than order sequence number of preceding order. Gaps are allowed in order sequence numbers.
TSE system introduces several types of notices, each type is assigned its own sequence numbers. Two examples of notice types are order receipt/error notices and contract notices. Furthermore, each type of notices is assigned two different sequence numbers: one is bound to member, the other is bound to virtual server. Suppose one member has two virtual servers set up:

TSE dual VS configuration

When a receipt notice is sent to either of these virtual servers, member-bound sequence number for receipt notices is incremented. Also, virtual server-bound sequence number for receipt notices is incremented for virtual server, which receives the notice. In case of contract notices mechanism is the same. In the above case TSE system maintains the following notice sequences: TSE system provides its clients with recovery mechanisms. Member can request notices to be resent or to be re-routed from one of its virtual servers to another. These facilities are provided by TSE via mechanism of operating instructions.

4. Interface

4.1 Introduction to library interface

When client code uses TSE Access Library, it operates with entities called sessions. In terms of C++, a single session with TSE is represented by an object, which exposes a set of methods to control session state, send TSE operating instructions and post financial transactions. As TSE provides responses to posted commands and transactions, session object delivers those via a set of event notification callbacks.
The following UML diagram represents the core structure of TSE Access Library session object:

TSE Access Library core structure.

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 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 TSE Access Library interface, which is described in detail in this section.

4.2 Session control and session state

Communication between client and TSE 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 ITSE_SessionControl interface. It is an abstract C++ structure, which contains two data types and ten methods. The data types are:

Session control methods are:

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

An application that makes use of TSE Access Library can potentially have more than one session established with TSE system, hence, it needs to differentiate between session objects. A virtual server ID is by itself enough to identify a session in the system, however, TSE 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 TTSESessionID, which is a typedef for C++ unsigned long. TSE Access Library makes no use of this identifier, only provides it as the first parameter with every event callback for corresponding session.
Event callback prototypes are described below:

4.3 Posting orders and receiving notices

Two interfaces described above give user all means to control a single TSE session and receive information about session state transitions and session-level events. Rest of functionality, which includes formatting and posting financial transactions and receiving TSE notices, is provided by the other two interfaces that represent the upper level of TSE Access Library. Unlike previously described session-related interfaces, these two are unaware of any session level details. Upper level handles the following tasks: Transaction posting functionality is represented by ITSE_STSTradeControl interface. It is an abstract C++ structure, which has two data types and seven methods. Data types are: TSE Access Library's trading interface covers two different strategies of posting transactions. First one gives implements a "query-one-post-one" algorithm, where user first requests an instance of desired input message, then either fills it with data and posts it, or drops it, releasing resources. A subsequent input message 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 eTSE_STSTradeControl_OutOfSequence. Types that represent input messages are part of library interface.
Second strategy implies that client code does all the routine concerning message 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, ITSE_STSTradeControl interface methods looks like the following: TSE Access Library delivers TSE notices to its client via ITSE_STSTradeNotification 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 TSE message header and a reference to a particular notice object. Classes representing TSE notices provide access and validation methods for all message fields. Notification interface is outlined below: 
	  void TSE_STS_NotifyOrderStatus(const TTSESessionID& _refSessionID,
                                     const TSE::CHEADER& _refHeader, 
                                     const TSE::CReceipt_Status& _refNotice)
	  void TSE_STS_NotifyCrossOrderStatus(const TTSESessionID& _refSessionID, 
                                          const TSE::CHEADER& _refHeader, 
                                          const TSE::CCross_Order_Receipt_Status& _refNotice)
	  bool TSE_STS_NotifyTSENotice(const TTSESessionID& _refSessionID, 
                                   const TSE::CHEADER& _refHeader, 
                                   const char* _cszFrameStart, 
                                   int _iFrameLength)
	  bool TSE_STS_NotifyOrderReceipt(const TTSESessionID& _refSessionID,
                                      const TSE::CHEADER& _refHeader,
                                      const TSESTS::COrder_Receipt_Notice& _refNotice)
	  bool TSE_STS_NotifyOrderError(const TTSESessionID& _refSessionID,
                                    const TSE::CHEADER& _refHeader, 
                                    const TSESTS::CNew_Order_Error_Notice& _refNotice)
	  bool TSE_STS_NotifyCrossOrderError(const TTSESessionID& _refSessionID,
                                         const TSE::CHEADER& _refHeader,
                                         const TSESTS::CCross_Order_Error_Notice& _refNotice)
	  bool TSE_STS_NotifyCancelError(const TTSESessionID& _refSessionID,
                                     const TSE::CHEADER& _refHeader,
                                     const TSESTS::CCancellation_Order_Error_Notice& _refNotice)
	  bool TSE_STS_NotifyAmendError(const TTSESessionID& _refSessionID,
                                    const TSE::CHEADER& _refHeader,
                                    const TSESTS::CRevision_Order_Error_Notice& _refNotice)
	  bool TSE_STS_NotifyContract(const TTSESessionID& _refSessionID,
                                  const TSE::CHEADER& _refHeader,
                                  const TSESTS::CContract_Notice& _refNotice)
	  bool TSE_STS_NotifyCancel_Revision(const TTSESessionID& _refSessionID,
                                         const TSE::CHEADER& _refHeader, 
                                         const TSESTS::CCancellation_Revision_Notice& _refNotice)
	  bool TSE_STS_NotifyEndOfNotices(const TTSESessionID& _refSessionID,
                                      const TSE::CHEADER& _refHeader,
                                      const TSESTS::CEnd_Of_Receipt_Contract_Notice& _refNotice)
	  bool TSE_STS_NotifyExpiredOrder(const TTSESessionID& _refSessionID,
                                      const TSE::CHEADER& _refHeader, 
                                      const TSESTS::CExpired_Voided_Notice& _refNotice)
	  bool TSE_STS_NotifyRegistrationInvalidOrder(const TTSESessionID& _refSessionID,
                                                  const TSE::CHEADER& _refHeader, 
                                                  const TSESTS::CRegistration_Invalid_Order_Notice& _refNotice)
	  bool TSE_STS_NotifyRegistrationInvalidCrossOrder(const TTSESessionID& _refSessionID,
                                                       const TSE::CHEADER& _refHeader, 
                                                       const TSESTS::CRegistration_Invalid_Cross_Order_Notice& _refNotice)
	  bool TSE_STS_NotifyRegistrationInvalidCancelOrder(const TTSESessionID& _refSessionID,
                                                       const TSE::CHEADER& _refHeader,
                                                       const TSESTS::CRegistration_Invalid_Cancel_Order_Notice& _refNotice)
	  bool TSE_STS_NotifyRegistrationInvalidReviseOrder(const TTSESessionID& _refSessionID, 
                                                        const TSE::CHEADER& _refHeader, 
                                                        const TSESTS::CRegistration_Invalid_Revise_Order_Notice& _refNotice)
	  bool TSE_STS_NotifyStopOrderPriceInfo(const TTSESessionID& _refSessionID, 
                                            const TSE::CHEADER& _refHeader,
                                            const TSESTS::CStop_Order_Notice_Price_Information& _refNotice)
	  bool TSE_STS_NotifyStopOrderData(const TTSESessionID& _refSessionID,
                                       const TSE::CHEADER& _refHeader,
                                       const TSESTS::CStop_Order_Notice_Order_Data& _refNotice)
	  bool TSE_STS_NotifyOtherDataTypeErrorNotice(const TTSESessionID& _refSessionID,
                                                  const TSE::CHEADER& _refHeader,
                                                  const TSESTS::COthers_Data_Type_Error_Notice& _refNotice)
The only callback that deserves special attention is TSE_STS_NotifyTSENotice. It is always invoked first, when a notice message arrives from TSE and it delivers raw notice buffer to the client.

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

TSE system receives and transmits data over communication media using proprietary binary format. TSE Access Library provides a convenient system of frame access classes capable of frame parsing and composition. For each data entity, such as an Order block defined in TSE data specification, a corresponding C++ class is defined. All data access classes have similar structure, their code being being automatically generated, based on formal data specification.

Data formats utilized by TSE differ for different markets. TSE Access Library data framework follows this separation defining every market's data access classes in corresponding separate namespaces. However, since certain session-level messages, such as message header are common for all markets, those are defined in common TSE:: namespace. Currently TSELib defines two separate namespaces for data access: TSESTS::, covering Stocks trading and TSEFOI:: for Futures, Options and Indices. Upcoming releases will include TSETST:: (ToSTNet) and TSEBTS:: (Bond Trading system).

Following UML diagram presents general picture of the data manipulation framework. For simplicity only one data access class, namely COrder_New is displayed.

Data Framework 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 frame. 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. TSE system protocol has specific data formats such as prices and quantities that require specific alignment and filling. For instance, price can be either 'Market price', 'Limit price', or 'Unfilled'. On user side such field's value is represented by an instance of CFrameWrapper::STSEPrice structure. Integer value fields with similar characteristics are represented by CFrameWrapper::SUITWithStatus 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 TSELib's data access framework. Their objective is to simplify procedure of manipulating the content of raw character frames, understood by TSE 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_() method, that should be executed to check whether underlying data is properly formatted. However, individual check_() methods are not normally called by library users. Instead there is single check() method that invokes specific check_() method for every field in the message.

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

get_() method is used to retrieve field's value. It does not accept any parameters and returns converted value via stack. get_() 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_() 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_() methods with different names to return different representations of the field's value.

As mentioned above, set_ and check_() 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 TSE Access LIbrary in client code. It consists of several points that should be kept in mind when using library.

Session object construction
A single session object is represented by an instance of CTSESTSImpl 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
TSE Access Library provides two ways to prepare order data and send it to TSE:

Note that once TSE_STS_PostTransaction or TSE_STS_PostForeignTransaction has succeeded, transaction message is stored within internal data structure waiting to be posted. Depending on library configuration, posting may take some time. If during this time a disconnection occurs, all orders stored by library, but not posted yet are discarded. First market control message after session recovery must be used to determine the latest order actually received by TSE system.

Notice processing
When library receives a notice message from TSE, it first invokes callback to deliver the whole buffer to client. This callback has default implementation that just returns true. After that, notices are extracted one by one and notice-specific callbacks of ITSE_STS_Trade_Notification 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 notice callback has returned false, subsequent notice extraction is not performed and notices remaining in the buffer are discarded. This scenario may me used by applications which don't need to deal with separate notices and only have to pass the whole buffer further on.

7. Dependencies

Current release of TSE Access Library has no specific software or hardware dependencies. Ordinary TCP/IP stack is used for communications and is accessed via sockets interface. TSE 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.

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

TSE 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 categories supported by session objects are: all predefined categories, "TSE raw data" (controls dumping of data being passed in hexadecimal format) and "TSE 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 TSE Stocks Trading System. Application reads a configuration file on startup and displays command prompt. User can create TSE sessions according to configuration file entries, load order data, send multiple transactions and review state of existing sessions. Sample application includes implementations of event manager and event logger, which conform to library's requirements.

10. Licensing information

If you're interested in this library, please contact us:

© Orchid Technology K.K. 2002 All rights reserved