Connectivity Process

MMTP API Developer’s Guide

Document version: Software version: Date: Distribution:

1.10 2.14 March 31, 2006 Boston Equities Exchange, Market Participants

Document Status:

FINAL

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Revision History
Date March 15, 2006 March 31, 2006 Version 1.00 1.10 Description Boston Equities Exchange – First Release Added new names Bx Trade and Bx Connect

Version: 1.0

Page 2 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Table of Contents
1. MMTP Open Interface ......................................................................................................................4 1.1 Overview.................................................................................................................................4 1.2 Compliant Operating Systems ................................................................................................5 MMTP Protocol.................................................................................................................................6 2.1 Overview.................................................................................................................................6 2.2 Creating an MMTP Session ....................................................................................................7 2.3 MMTP Message Primitives .....................................................................................................8 2.4 Direction of Protocol................................................................................................................9 2.5 MMTP Message Structure ....................................................................................................10 2.6 Sequence Numbers and Message IDs .................................................................................10 2.7 Managing Windows for Sending Messages ..........................................................................11 MMTP API .......................................................................................................................................12 3.1 Session Management Functions...........................................................................................12 3.2 Protocol Management Functions ..........................................................................................12 3.3 Transmission Functions ........................................................................................................13 3.4 Logging Functions.................................................................................................................13 Session Management ....................................................................................................................14 4.1 Initializing an MMTP Session................................................................................................14 4.2 Creating an MMTP Session ..................................................................................................15 4.3 Transmitting Data .................................................................................................................16 4.4 Terminating an MMTP Session.............................................................................................17 4.4.1 Build vs. End Sessions ...........................................................................................19 4.5 MMTP Validation ..................................................................................................................19 Order Entry/Market Data Message Flow.......................................................................................21 5.1 Overview...............................................................................................................................21 5.2 Sending Order Messages .....................................................................................................22 5.3 Receiving Reply Messages...................................................................................................23 5.4 Receiving Market Data..........................................................................................................23 5.5 Restart/Recovery Scenarios .................................................................................................24 5.5.1 Unexpected Disconnection .....................................................................................24 5.5.2 Retrieval of an Unexpected Sequence Number ......................................................25 5.5.3 Retransmission of Messages..................................................................................26 5.5.4 Ignoring Outdated Messages..................................................................................26 5.6 Functions Employing Sequence Numbers and Message IDs ...............................................27 5.7 Message Formats .................................................................................................................27 API (Data Definition) ......................................................................................................................30 A.1 MMTPSESSION ...................................................................................................................30 A.2 MMTPAdminData .................................................................................................................30 A.3 MMTPMsg ............................................................................................................................32 A.4 Error Codes ..........................................................................................................................33 A.5 Connection Parameters ........................................................................................................35 A.6 Refusal Reason Codes for Connection Request...................................................................35 A.7 Refusal Reason Codes for Transmission/Retransmission Request......................................36 Page 3 of 116 March, 2006

2.

3.

4.

5.

A.

Version: 1.0

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

A.8 B.

Disconnection Reason Codes...............................................................................................36

API (Protocol Management Functions) ........................................................................................37 B.1 MMTPCheckConnectionRequest..........................................................................................37 B.2 MMTPCheckDisconnectionRequest .....................................................................................38 B.3 MMTPCheckHandle..............................................................................................................39 B.4 MMTPCheckLogicalConnection............................................................................................39 B.5 MMTPCheckPhysicalConnection..........................................................................................40 B.6 MMTPCheckStartRequest ....................................................................................................41 B.7 MMTPCheckSyncRequest....................................................................................................41 B.8 MMTPErrorDescription .........................................................................................................42 B.9 MMTPObtainNumberSessions .............................................................................................43 B.10 MMTPObtainPrimitiveName .................................................................................................44 B.11 MMTPSendError...................................................................................................................45 B.12 MMTPSetCheckAliveTimeout ...............................................................................................46 B.13 MMTPWaitForStartRequest..................................................................................................47 API (Session Management Functions) .........................................................................................49 C.1 MMTPAcceptConnection ......................................................................................................49 C.2 MMTPAcceptDisconnection..................................................................................................50 C.3 MMTPAcceptStart.................................................................................................................50 C.4 MMTPAcceptSync ................................................................................................................52 C.5 MMTPCancelConnectionRequest.........................................................................................52 C.6 MMTPCancelDisconnectionRequest ....................................................................................53 C.7 MMTPCancelStartRequest ...................................................................................................53 C.8 MMTPCancelSyncRequest...................................................................................................54 C.9 MMTPCloseSession .............................................................................................................54 C.10 MMTPConnectionRequest....................................................................................................55 C.11 MMTPCreateSession............................................................................................................57 C.12 MMTPDeleteSession ............................................................................................................57 C.13 MMTPDenyConnection.........................................................................................................58 C.14 MMTPDenyStart ...................................................................................................................59 C.15 MMTPDisconnectionRequest ...............................................................................................60 C.16 MMTPInitialize ......................................................................................................................60 C.17 MMTPOpenClientSession.....................................................................................................61 C.18 MMTPStartRequest ..............................................................................................................62 C.19 MMTPSyncRequest ..............................................................................................................63 C.20 MMTPTerminate ...................................................................................................................63 API (Logging Functions) ...............................................................................................................65 D.1 MMTPCloseLog ....................................................................................................................65 D.2 MMTPLogSession ................................................................................................................66 D.3 MMTPOpenLog ....................................................................................................................66 D.4 MMTPSetUserLogFct ...........................................................................................................68 API (Transmission Functions) ......................................................................................................69 E.1 MMTPReceiveMessage........................................................................................................69 E.2 MMTPSendMessage ............................................................................................................70 E.3 MMTPSendServiceMessage ................................................................................................73 E.4 MMTPTerminateWrite...........................................................................................................75 Program Highlights........................................................................................................................77 SMMTP (Simple MMTP) .................................................................................................................79 G.1 Overview...............................................................................................................................79 Page 4 of 116 March, 2006

C.

D.

E.

F. G.

Version: 1.0

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

G.2 G.3 G.4 G.5 G.6 G.7 G.8 G.9 H.

SMMTPMsg structure ...........................................................................................................80 SMMTPConnect ...................................................................................................................82 SMMTPClose........................................................................................................................84 SMMTPGet ...........................................................................................................................85 SMMTPGetSync ...................................................................................................................86 SMMTPPut ...........................................................................................................................87 SMMTPPutSync ...................................................................................................................88 SMMTPErrorDescription .......................................................................................................89

Sample Programs...........................................................................................................................92 H.1 Sample - receiver..................................................................................................................92 H.2 Sample – sender...................................................................................................................99

Version: 1.0

Page 5 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Preface
Purpose of Document
Through a set of standardized API functions, developers have the mechanism to build applications that submit orders/instructions to and receive information from Bx Trade (Boston Equities Exchange – Trading System). The key benefits of the solution are:
• • • • •

Standardized programming interface to the Trading Engines Standardized communication via the MMTP protocol to the Boston Equities Exchange network Simplified development process for adopters and member firms Data security through encryption Data compression

Version: 1.0

Page 1 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

MMTP API vs. SMMTP API
When developing an interface between the Bx Trade and an Order Entry Application or Market Data Application, the API developer can simplify the development effort with either of the following tools:

MMTP API C Libraries Library of 41 C-functions broadly divided into four categories: Session Management Functions Protocol Management Functions Transmission Functions Logging Functions

SMMTP API C Libraries Library of seven C-functions broadly divided into three categories: Open / Close Functions Send / Receive Functions Synchronize / Error Functions

Although Simple MMTP libraries may require less development effort, they also carry more functionality restrictions. This document provides a detailed description of both tools.

Document Scope
This document provides developers with sufficient information to build applications using the MMTP API. Topics covered include:
• • • • • • •

An overview of the technical architecture MMTP protocol MMTP API overview Usage of the MMTP API with respect to market data flows Detailed descriptions of the C functions Description of the SMMTP Simple MMTP API Sample programs

Readers of this document should have strong C development experience with a background in order entry applications and market data retrieval applications.

Version: 1.0

Page 2 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Related Documentation
This document is intended to provide detailed information regarding the MMTP API. For a detailed description of the MMTP protocol, refer to:

MMTP Technical Specifications MMTP protocol primitives and definitions, parameters, error messages, and data structures.

connection/disconnection

Version: 1.0

Page 3 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

1. MMTP Open Interface
This chapter describes the MMTP open interface and includes:
• •

An overview Compliant operating systems

1.1

Overview
The MMTP Open Interface is an integrated solution that provides a common access point for the exchange’s member firms. The core of the solution consists of the:
• • • •

MMTP Application Programming Interface (API) Bx Connect (Member Gateway) Bx Trade (Boston Equities Exchange Trading System) MMTP Protocol

The following diagram is an introductory view of the MMTP architecture:
Figure 1: Overview of MMTP Architecture
Inbound and Outbound Messages are sent via the API Client Application and the Member Gateway API DIRECT CLIENT APPLICATION Order Entry Application Market Data Application

API
Send

API MMTP MMTP Bx CONNECT GATEWAY Orders go to Trading System Replies From Trading System
Rec'v

Orders

Replies to Orders Market Data

Rec'v

Send

Bx TRADE

Rec'v

MMTP

Market Data

Market Data From Bex Trading System

Independent software vendors (ISVs) or member firms will be responsible for developing their own customized order entry application and market data applications. To develop these interfaces, the ISVs or member firms will have access to the MMTP API Developer’s Toolkit containing programming libraries for sending and receiving requests, responses, and market data. The MMTP API Developer’s Toolkit runtime libraries communicate directly with the exchangemaintained Bx Connect – Gateway. Bx Connect in turn route order entry information and market data to the appropriate destination. The software developer is responsible for formatting and parsing order entry and market data information.

Version: 1.0

Page 4 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

To simplify MMTP programming, an additional API is available called SMMTP (for Simple MMTP). This is a library of high-level functions allowing programmers to write simple client applications. A single SMMTP function call generates several MMTP function calls, making it faster to develop simple applications. For further information on the SMMTP protocol, please refer to Appendix F. The following concepts are used extensively in this document:

Client/Server

A client is the application that requests services from a remote server. Then the server processes these requests on behalf of the client. In this architecture, the API client application uses the MMTP APIs to communicate to Bx Connect. Bx Connect acts as the server to the API client application, and in turn becomes a client to the Bx Trade.

Sender/Receiver

A sender is an application that is responsible for transmitting messages to the receiver. The receiver reads the incoming messages and process them accordingly. As depicted in the diagram above, the API client application has two potential roles:

Sender: Transmits requests to Bx Connect. Bx Connect reads these messages and forwards them to Bx Trade. In this document, the term API client sender represents the application that sends messages. Receiver: Receives responses and market data messages. In this document, the term API client receiver represents the application that receives messages.

1.2

Compliant Operating Systems
MMTP API 2.14 is available for the following operating systems :
• • • •

Windows 2000 Service Pack 4 Windows 2003 Solaris 2.8 HP UX 11.i

Version: 1.0

Page 5 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

2. MMTP Protocol
This chapter describes the MMTP protocol and includes:
• • • • • • • •

An overview Access points How to create an MMTP session MMTP message primitives The direction of the protocol MMTP message structure Sequence numbers and message IDs How to manage windows for sending messages

2.1

Overview
An exchange needs a protocol to simplify and improve access to its services. The MMTP protocol allows API client applications to communicate with Bx Trade through Bx Connect. The MMTP protocol (Market Message Transfer Protocol) is designed to minimize the impact of the integration of new applications on the software infrastructure and the production environment. It provides a flexible and complete system that will serve as a base for future development. The MMTP protocol uses TCP/IP as a base transport mechanism. The following diagram depicts the MMTP protocol:

Version: 1.0

Page 6 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 2: Overview of the MMTP Protocol
MMTP Developer's Toolkit Access Point MMTP Orders go to BeX Trading System

Client Application

API
Orders Replies to Orders Market Data
Send

MMTP GATEWAY

Rec'v

MMTP

Bx CONNECT

Rec'v

MMTP

MMTP Replies From BeX Trading System

Market Data

As shown above, communications between the API client application and Bx Trade flow through Bx Connect server using the MMTP protocol.

2.2

Creating an MMTP Session
For an API client application to be able to communicate via MMTP, it must create an MMTP session. An MMTP session consists of three stages: 1. Connection/authentication 2. Transmission 3. Disconnection Connection / authentication occurs when a client connection request is initiated by the API client application. The API client application must supply an ID identifier. Bx Connect validates the information. If Bx Connect is able to validate this information, it sends a connection acceptance back to the client. Once a client connection request is granted, the API client application can submit requests, receive responses, or receive market data information. Communications between an MMTP server and the API client application can be disconnected in the following situations:
• •

When the API client application chooses to terminate communications with an MMTP server When an MMTP server forces a disconnection with the application client

Version: 1.0

Page 7 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

2.3

MMTP Message Primitives
The protocol uses a set of message primitives to exchange requests and acknowledgements between the sender and the receiver. This provides a mechanism for handshaking between the two parties. For instance, at the start of a session, the API client application will send a client connection request (CONXREQ) to the MMTP listener. Upon receiving the client connection request, the listener has the option of replying to the API client application with a positive acknowledgement to accept a connection (CONX-ACK) or a negative acknowledgement to refuse a connection (CONX-NACK). At this time, the sender proceeds accordingly. The following table lists the MMTP message primitives used by the protocol: MMTP Message primitives CONX-REQ CONX-ACK CONX-NACK DCNX-REQ DCNX-ACK START-REQ START-ACK START-NACK DATA-MSG SYNC-REQ SYNC-ACK ERR-IND SRVC-MSG PRSC-MSG Number 10 11 12 13 14 20 21 22 23 24 25 90 93 99 Description Client connection request Connection acceptance by Bx Connect Connection refusal by Bx Connect Disconnection request Disconnection request acknowledgement Transmission/retransmission request Transmission/retransmission request acknowledgement Transmission/retransmission request refusal Data transmission Acknowledgement request by data source Acknowledgement by data receiver Error indication by data receiver Service message Heartbeat message

Version: 1.0

Page 8 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

2.4

Direction of Protocol
The following table shows the direction in which each primitive is sent: Message Primitive Direction CONX-REQ CONX-ACK CONX-NAK DCNX-REQ DCNX-ACK START-REQ START-ACK START-NACK DATA-MSG SYNC-REQ SYNC-ACK ERR-IND SRVC-MSG PRSC-MSG Client Sends Data Client Bx Connect Bx Connect Client Client Receives Data Client Bx Connect Bx Connect Client

Version: 1.0

Page 9 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

2.5

MMTP Message Structure
All the protocol messages have the same header. It allows easy identification of messages in the character feed transmitted by TCP/IP and enables rapid rectification of transmission errors.

Field Name STX
Primitive Length Admin Data

Offset
0 1 5

Length
1 4 X

Type

Value
02

Comment
Message header. Value in hexadecimals. Total length of the message including STX and ETX. Defines the RLC message type (ie. Defines the type of message body). Body of message (ie. Data fields). Message footer. Value in hexadecimals.

Numeric

X+Y+6 Varies

Message Body EXT

5+X 5+X+Y

Y 1

Varies 03

Notes:
• •

Numerical data is inserted on the right and padded with zeros on the left. Other data is inserted on the left and padded with spaces on the right.

2.6

Sequence Numbers and Message IDs
MMTP message exchange is implemented through a windowing mechanism using both sequence numbers and message IDs. This allows the:
• • • •

Receiver to check that it has received all messages in the correct order Receiver to inform the sender of a sequence number inconsistency Sender to request the acknowledgement of a specific message Sender to ensure that the receiver gets all the messages

Sequence Numbers:

At the start of each MMTP session, the sender selects the sequence number to be assigned to the first message of the session and communicates it to the receiver. A sequence number can be used several times in consecutive sessions. It is not specific to a single message, but rather to a single session. It must always be eight numeric digits in length. On each successive message, the Sequence Number is incremented by one.

• • •

Version: 1.0

Page 10 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Message IDs:
• •

Are the internal identifiers of the message to the sending application. Must always be 24 alphanumeric characters long.

2.7

Managing Windows for Sending Messages
To minimize network traffic, messages can be sent in “windows”. A window of sent messages is the maximum number of messages that can be sent to the receiver before acknowledgement (from the receiver) is required by the sender. By sending messages in windows of more than one message, fewer acknowledgements are required by the sender. When the API Client Application is the Sender it must:
• • •

Define the size of the window (e.g. 20 messages) Define the frequency of the send of a Sync Req. message (e.g. Frequency of checking the synchronization between sender and receiver) Define routines to manage message overflows or blockages1.

When the API Client Application is the Receiver it must:
• •

Store the last Message ID acknowledged in case a crash or disconnection occurs. Monitor for gaps in the message sequence received and issue an error message to Bx Connect if a gap is identified. This message will generate a disconnection after which the Receiver must send a connection request to Bx Connect followed by a start request with the last Message ID acknowledged. Note that the Receiver does not need to manage a window of messages.

1

For example, where the receiving application is not acknowledging sent messages a timeout can be started. If acknowledgement is not received before the timeout has expired, the Sender can issue a disconnection request to Bx Connect followed immediately by a reconnection request. The reconnection will start from the last message acknowledged by Bx Connect.

Version: 1.0

Page 11 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

3. MMTP API
This chapter describes the four major categories of MMTP API functions which include:
• • • •

Session management functions Protocol management functions Transmission functions Logging functions

Detailed descriptions of the arguments for each category of functions are provided in Appendices B to E.

3.1

Session Management Functions
The Session Management functions consist of C functions that enable developers to:
• • •

Build and close communication connections. Build and close MMTP sessions. Accept or deny communication requests.

A valid connection and a session are required to send and receive messages. The following Session Management functions are available:
• MMTPAcceptConnection • MMTPAcceptDisconnection • MMTPAcceptStart • MMTPAcceptSync • MMTPCancelConnectionRequest • MMTPCancelDisconnectionRequest • MMTPCancelStartRequest • MMTPCancelSyncRequest • MMTPCloseSession • MMTPDenyConnection • MMTPConnectionRequest • MMTPCreateSession • MMTPDeleteSession • MMTPDisconnectionRequest • MMTPInitialize • MMTPOpenClientSession • MMTPDenyStart • MMTPStartRequest • MMTPSyncRequest • MMTPTerminate

3.2

Protocol Management Functions
The Protocol Management functions are comprised of C functions that allow the API developer to:
• •

Validate the logical and physical connection. Check the status of a pending connection, disconnection or synchronization request.
Page 12 of 116 March, 2006

Version: 1.0

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Manage the buffer.

The following Protocol Management functions are available:
• MMTPCheckConnectionRequest • MMTPCheckDisconnectionRequest • MMTPCheckHandle • MMTPCheckLogicalConnection • MMTPCheckPhysicalConnection • MMTPCheckStartRequest • MMTPCheckSyncRequest • MMTPErrorDescription • MMTPObtainNumberSession • MMTPObtainPrimitiveName • MMTPSendError • MMTPSetCheckAliveTimeout • MMTPWaitForStartRequest

3.3

Transmission Functions
The Transmission Functions are comprised of C functions that enable the API developer to:
• •

Send messages. Receive messages.

These functions allow member firms to submit requests, receive responses and receive market data information. The following Transmission functions are available:
• MMTPReceiveMessage • MMTPSendMessage • MMTPSendServiceMessage • MMTPTerminateWrite

3.4

Logging Functions
The Logging functions are comprised of C functions that permit the API developer to:
• •

Enable message logging. Disable message logging.

The Logging functions write all sent and received messages to a user-provided log file. This function is useful in debugging runtime errors. The following Logging functions are available:
• MMTPCloseLog • MMTPLogSession • MMTPOpenLog • MMTPSetUserLogFct

Version: 1.0

Page 13 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

4. Session Management
The purpose of this section is to describe the four common operations related to managing an MMTP session, which include:
• • • •

Initialization Creation Data Transmission Termination

These operations are required in order for the API client application to send or receive messages. Note: Detailed descriptions and usage of all MMTP API C functions are listed in Appendices B to E, classified by function type.

4.1

Initializing an MMTP Session
The sender/receiver must initialize an MMTP session before creating it. The MMTP API provides the MMTPInitialize C function that enables the API client application to allocate necessary local resources for building an MMTP session. This function allocates enough resources based on the number of sessions specified by an input parameter. The Initialization operation should be executed before the creation of one or more MMTP sessions. The diagram below shows an example of the MMTPInitialize function taking an integer (n) as a parameter to allocate resources for the nth MMTP session.

Version: 1.0

Page 14 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 3: Initializing an MMTP Session
Local allocations Client Program System resources 1st session MMTPInitialize nth sessions System resources nth session

4.2

Creating an MMTP Session
Before submitting requests or receiving responses, the API client application builds a physical connection and a logical session with the MMTP server. By using the MMTP APIs, the API client application can build the sessions required to exchange messages. To establish an MMTP session, the following three C functions are required:

Client-Initiated Requests
• • •

MMTPCreateSession MMTPOpenClientSession MMTPConnectionRequest

The following diagram illustrates the initiation of an MMTP session between the API client application and the MMTP server process. In this case, the API client application is the sender of messages and the MMTP server process is the receiver. The initial task when building a session is to create a logical session handle using MMTPCreateSession. This function is responsible for generating a unique session handle that is used throughout the duration of the logical session.

Version: 1.0

Page 15 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 4: Initiation of MMTP Session Between API Client and MMTP Server
Client Application

MMTPCreateSession Get session handle Open socket connection Port number Receiver's physical address MMTPConnectionRequest CONX-REQ Sender's identifier Connection parameters Sender's password Authentication Server

MMTPOpenClientSession

CONX-ACK

Connection accepted MMTPAcceptConnection

MMTPReceiveMessage CONX-NACK Connection denied MMTPDenyConnection

The next task when building a session is to open a physical socket between the sender and receiver using MMTPOpenClientSession. To open a physical connection, the API client application must specify the port number of the receiver’s listener process and the physical address of the receiver (hostname or IP address). The third task requires the sender to submit a connection request using MMTPConnectionRequest. Upon receiving the request, the receiver has the option to accept (CONX-ACK) or to refuse (CONX-NACK) the request with an acknowledgement. In the event that the API client application requires multiple sessions, then the procedure shown in the diagram is repeated until all the sessions are established.

4.3

Transmitting Data
Once a connection and session are established between the sender and the receiver, the MMTP API provides the following three C functions that allows developers to submit and retrieve messages:
• • •

MMTPStartRequest MMTPSendMessage MMTPReceiveMessage

The diagram below depicts a simple send message. As shown, the sender must wait until it receives the transmission/retransmission request (START-REQ) from
Version: 1.0 Page 16 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

the receiver. The transmission/retransmission request informs the sender that the receiver is ready to receive incoming messages. It is the receiver’s responsibility to submit this request using MMTPStartRequest. After the sender receives the transmission/retransmission request, it must acknowledge with a START-ACK. At this point, the sender may transmit messages to the receiver.
Figure 5: Transmitting Data
Sender Receiver

Initialization

Build session

MMTPReceiveMessage switch { . . START-REQ if allowed to submit MMTPStartAccept otherwise MMTPStartDeny . . }

START-REQ

START-ACK

MMTPStartRequest MMTPReceiveMessage switch { . START-ACK . . START-NACK }

START-NACK

MMTPSendMessage

In the MMTP architecture, the API client application can act as the sender of messages to the Bx Connect component as well as the receiver of incoming messages from Bx Connect.

4.4

Terminating an MMTP Session
To end a physical and logical session, the MMTP API provides four C functions. These functions request disconnection from the server, remove logical sessions, deallocate resources, and terminate the physical connection.

Version: 1.0

Page 17 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

To end an MMTP session, the following four C functions are provided: Client-Initiated Requests
• • • •

MMTPDisconnectionRequest MMTPCloseSession MMTPDeleteSession MMTPTerminate

The diagram below depicts a close session interaction between the API client application and the MMTP server. The API client application can submit a disconnection request (DCNX-REQ) by using the MMTPDisconnectionRequest function. The API client application informs the MMTP server of the last sequence number received and the reason for disconnection. The MMTP server in turn acknowledges with an acceptance for disconnection (DCNX-ACK). Then the API client application can proceed to end the physical connection between the two parties by invoking MMTPCloseSession. After MMTPCloseSession, the next step is to remove the logical session and free all related resources by using MMTPDeleteSession. If the API client application chooses to end all processing and shut down, it can use the MMTPTerminate function to free all remaining resources.
Figure 6: Terminating an MMTP Session
Client Application Server

MMTPDisconnectionRequest Close logical session

DCNX-REQ

1) Reason for disconnect 2) Last sequence number received
DCNX-ACK

Acknowledge disconnection MMTPAcceptDisconnect

MMTPCloseSession Terminate logical session 1) Break socket connection MMTPDeleteSession Free local resources

MMTPTerminate Free all remaining resources

In the MMTP architecture, the API client application ends sessions with the PACIn, PACOut, or PAC_RDF_MMTP at Bx Connect.
Version: 1.0 Page 18 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

4.4.1 Build vs. End Sessions
The diagram below shows the relationships between the build session versus the end session C functions. When building a session, the build session functions must be executed in a specific order for a handshake between the API client application and the MMTP server to occur. For example, the API client application must create a session, open a physical connection, and finally send a connection request. A similar process takes place at the termination of a session. The disconnection request function, MMTPDisconnectionRequest, is comparable to the connection request, MMTPConnectionRequest. Likewise, the MMTPCloseSession is comparable to the MMTPOpenClientSession function. The end session C functions must be executed in the order recommended in the diagram below to prevent any mismanagement of sessions and physical connections.
Figure 7: Steps for Build Session and End Session
Build Session End Session

MMTPInitialize Step 1

MMTPTerminate Step 8

MMTPCreateSession Step 2

MMTPDeleteSession Step 7

MMTPOpenClient Step 3

MMTPCloseSession Step 6

MMTPConnectionRequest Step 4

MMTPDisconnectionRequest Step 5

4.5

MMTP Validation
Developers have the capability to check a request while the request is still in progress. Although these functions are not required for session building and message delivery, they provide useful functionalities after the session has been built. The MMTP API provides several C functions that allow developers to:
• • • •

Validate the state of a connection (physical and logical) Check the validity of a session handle Check the status of an acknowledgement request by data source Check the status of a transmission/retransmission request

The following diagram depicts a simple process flow for session handle validation. The MMTPCheckHandle function verifies the validity of the session handle.
Version: 1.0 Page 19 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 8: Process Flow for Session Handle Variation
Sender/ Receiver

Define local variables Session handle of PgaSession data type

MMTPInitialize

1) Allocate resources for session number n

MMTPCheckHandle

2) Check if session handle defined is used by another process If not

MMTPCreateSession

3) Create a new MMTP session handle

Version: 1.0

Page 20 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

5. Order Entry/Market Data Message Flow
The purpose of this section is to describe the process of sending order entry messages, receiving reply messages, and retrieving market data feeds using the MMTP API. This description includes:
• • • • • • •

An overview Sending order messages Receiving reply messages Receiving market data Restart/recovery scenarios Functions employing sequence numbers and message Ids Message formats

5.1

Overview
The primary purpose of the MMTP API C functions is to provide an easy–to-use open interface to Bx Trade. It enables members or ISVs to build API client applications for submitting requests and retrieving market data. There are three types of messages between the Bx Trade and the API client application:
• • •

Order messages (e.g. order entry or give-up) Reply messages (e.g. execution notice or trade leg) Market Data Feed (e.g. price information or quote)

The architecture of Bx Connect uses three processes that interface with the API client application:
• • •

PACIn – receives incoming messages from the API client sender PACOut – sends reply messages from the Trading System to the API client receiver PAC_RDF_MMTP – sends market data information to the API client receiver

Version: 1.0

Page 21 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

5.2

Sending Order Messages
Order entry messages are submitted from the API client sender. The API client sender is required to execute the following MMTP operations in order to send order messages to Bx Trade: 1) Build an MMTP session with the PACIn process on Bx Connect. 2) Wait until the PACIn process sends a START-REQ 3) Issue a transmission/retransmission request acknowledgement, START-ACK, to inform the PACIn process that the sender is ready to submit messages 4) Map request attribute data to the MMTP message layout 5) Send the message using the C function MMTPSendMessage The following diagram illustrates how the API client sender submits requests:
Figure 9: Sending an Order Message
Sender Build session PACIn

LOOP
CONX-ACK

MMTPAcceptConnection

MMTPReceiveMessage switch { CONX-ACK CONX-NACK Error processing

START-REQ

MMTPStartRequest

START-ACK START-REQ MMTPAcceptStart Get out of loop }

MMTPSendMessage

DATA-MSG Sequence number Message body

MMTPReceiveMessage

Version: 1.0

Page 22 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

5.3

Receiving Reply Messages
To receive reply messages, the API client must: 1) Build an MMTP session with the PACOut process on Bx Connect 2) Send a transmission/retransmission request (START-REQ) to inform the PACOut process that the receiver is ready to accept messages 3) Receive messages (loop) 4) Inspect the function code of the message to determine the message type 5) Validate that the sequence number is not out of sequence (if so, indicate error to the PACOut process) 6) Store the sequence number The diagram below depicts the programming flow of receiving messages from Bx Trade using the MMTP C functions.
Figure 10: Receiving Reply Messages
Receiver

Build MMTP Session

MMTPStartRequest

START-REQ

LOOP MMTPReceiveMessage switch { START-ACK Store Message ID Store Sequence number DCNX-REQ Accept disconnection MMTPSendMessage DATA-MSG Process message } DATA-MSG - Data content Sequence number Message body PACOut

START-ACK Message ID Sequence number

MMTPAcceptStart

5.4

Receiving Market Data
To receive market data information, the API client receiver is responsible for performing the following tasks: 1) Build an MMTP session with the PAC_RDF_MMTP at Bx Connect. 2) Repeat the same steps as described in Section 5.3

Version: 1.0

Page 23 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Receiving Reply Messages. 3) Inspect the market feed code in the Instrument Header to determine the message type and process it accordingly. The market data messages are generated by the Trading System. The data feed occurs during the session. Through the MMTPReceiveMessage function, developers are able to inspect the message and identify the type of message.

5.5

Restart/Recovery Scenarios
MMTP allows the API client application to manage the message sequence associated with a session. This flexibility enables the application to track and identify any message sent or delivered out of order. The two fields provided by MMTP to ensure a consistent message delivery are:
• •

Sequence number – this number is unique to an MMTP session Message ID – this identifier is unique to a message

As mentioned previously, the API client application is responsible for storing and managing the message ID. This section discusses four sample scenarios that may require restart and/or recovery processes:
• • • •

Unexpected disconnection Retrieval of an unexpected sequence number Retransmission of messages Ignoring outdated messages

5.5.1 Unexpected Disconnection
In the event that the physical connection is lost between the API client application and the Bx Connect entities (PACIn, PACOut, PAC_RDF_MMTP), the MMTP session must be re-established between the two parties. The MMTPCheckPhysicalConnection function can be used to detect an unexpected disconnection. If a disconnection is detected, the API client application is required to do the following: 1) Create a physical connection MMTPOpenClientSession. with the receiver using

2) Create a logical connection (CONX-REQ) using MMTPConnectionRequest – the application must provide an identifier and password. 3) Send a transmission/retransmission request (START-REQ) using MMTPStartRequest indicating the last message ID that the API client application received from the sender (receiver only).

Version: 1.0

Page 24 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

4) Upon receiving the transmission/retransmission request acknowledgement (START-ACK) from the sender, the API client application uses the sequence number and the message ID sent from the sender to determine the order flow of the message exchange process. 5) Receive message and store the sequence number and the message ID accordingly. If a physical connection is lost between the API Client Application and Bx Connect, the API Client entities are required to re-establish connections with Bx Connect.

5.5.2 Retrieval of an Unexpected Sequence Number
In cases where an API client receiver retrieves a message with an unexpected sequence number, the application should send an alert to the sender (Bx Connect). For instance, an error in the sequence can occur when:
• •

The number received corresponds to a message already received The number received is higher than the number expected

The API client receiver has the following options:
• •

Ignore the message Respond to the sender with an alert using the MMTPSendError

Note: It is recommended that the client application alert the sending application of the error and disconnect. If necessary, the client application should rebuild the connection. If the API client receiver chooses to send an alert to the sender, the following steps are required: 1) Send an alert to the sender using the MMTPSendError function passing the last message ID and sequence number received 2) Terminate the physical connection using MMTPCloseSession 3) Re-open a physical connection by invoking MMTPOpenClientSession 4) Send a transmission/retransmission request using MMTPStartRequest passing the last message ID received 5) Receive incoming messages The following diagram describes the programming flow for recovery of messages:

Version: 1.0

Page 25 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 11: Programming Flow for Recovering Messages
Receiver Build MMTP Session

MMTPStartRequest

LOOP MMTPReceiveMessage switch { . DATA-MSG Process message If sequence number <> the expected number MMTPSendError Close session Build new session MMTPStartRequest . START-ACK Store message ID Store sequence # . }
DATA-MSG - Data content

PACOut

MMTPSendMessage

Sequence number Message body
ERR-IND

Last sequence # received Last message ID received
START-REQ

Last message ID received

START-ACK

MMTPStartAccept

Message ID Sequence #

5.5.3 Retransmission of Messages
Another potential message recovery scenario is when the receiving application has lost the last received message and its identifier. For instance, the receiving application has received consecutive messages from the sender (PACOut) with identifier A through Z during the day. A failure occurred where all messages kept at the receiving application are lost. In order to recover, the receiving application must request for a re-send of all messages. The steps required to request a re-send of all messages from the CAP are as follows: 1) Send a transmission/retransmission request with an empty message ID. 2) Wait until a transmission/retransmission request acknowledgement is received with an empty message ID. 3) Invoke MMTPReceiveMessage.

5.5.4 Ignoring Outdated Messages
When the client-server communication restarts after a failure occurred during the market session, the receiving application could receive outdated market information. In order to retrieve only the real-time feed, the receiving application
Version: 1.0 Page 26 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

must request the CAP RDF_MMTP server to bypass all the awaiting messages. It proceeds as follow: 1) Send a transmission/retransmission request with the string START WITH NEXT MESSAGE! as message ID. 2) Wait until a transmission/retransmission request acknowledgement is received with the same text. 3) Invoke MMTPReceiveMessage.

5.6

Functions Employing Sequence Numbers and Message IDs
The following table summarizes the C functions that utilize the sequence number and message ID fields: C Function MMTPAcceptDisconnection MMTPAcceptStart MMTPAcceptSync MMTPStartDeny MMTPDisconnectionRequest MMTPStartRequest MMTPSendMessage MMTPSendError Sequence Number Last received Last received Last received Last received New Last received Last received Last received Last received New Last received Message ID

5.7

Message Formats
It is the responsibility of the API client application to format the request message based on the specification set by Bx Trade. Messages containing data are in a standardized format defined by Bx Trade. Sender The primary API function for sending messages is MMTPSendMessage. It requires five parameters:
• • • • •

Session handle Sequence number Administrative data Message data length Message

The following diagram describes the data format for the MMTPSendMessage C function:
Version: 1.0 Page 27 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 12: MMTPSendMessage C Function
MMTPSendMessage (Session handle, Sequence number, PgaAdminData, Message length, Message)

Session Handle

Sequence Number

MMTPAdminData

Message Length

Message -

MMTPAdminDataE0

MMTPAdminDataM0

MMTPAdminDataRR

MMTPAdminData Generic

The API client application is responsible for formatting the requests to the Message input argument of the MMTPSendMessage C function. Refer to the MMTPSendMessage section in Appendix B for a detailed description of the parameters required by this function. Receiver The primary API function for receiving messages is MMTPReceiveMessage. It requires three arguments:
• • •

Session handle Time out parameter MMTPMsg

The following diagram depicts the data format of the incoming message:

Version: 1.0

Page 28 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Figure 13: Format of Incoming Messages
MMTPReceiveMessage (Session handle, Time Out, MMTPMsg) MMTPMsg MMTPConxReq MMTPDataMsg MMTPDcnxReq

Sequence Number

Data Size

MMTPAdminData

Data

MMTPAdmin DataE0

MMTPAdmin DataM0

MMTPAdmin Generic

MMTP uses the MMTPMsg data structure to store the body of the message, the message ID, sequence number, and other critical information that the API client application may need to manage as messages are received from the sender. The API client application can retrieve responses and market data using the Data field of the MMTPDataMsg data structure. MMTPDataMsg structure is a subcomponent of the MMTPMsg.

Version: 1.0

Page 29 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

A. API (Data Definition)
This appendix describes the principal data types and data structures used in the MMTP protocol:
• • •

MMTPSESSION MMTPAdminData MMTPMsg

It also lists key codes and parameters used by the MMTP protocol, including:
• • • • •

Error codes Connection parameters Refusal reason codes for connection requests Refusal reason codes for transmission/retransmission requests Disconnection reason codes

A.1

MMTPSESSION
MMTPSESSION is an MMTP data type that is used for session handling. It is a predefined type definition in the libpga.h header file. This data type is implemented in the Session Management C functions: typedef void* MMTPSESSION;

A.2

MMTPAdminData
The MMTPAdminData data structure is used by the following functions:
• • • •

MMTPAdminDataInBuffer MMTPBufferInAdminData MMTPSendMessage MMTPReceiveMessage

The type definition resides in the Libpga.h header file. Note: See MMTP Technical Specifications for information about the use of the fields in the various AdminData envelopes (M0 and A1.), and which fields are mandatory. Some AdminData in libpga.h header file are not supported by MMTP API 2.14. Supported AdminData are M0 and A1.

Version: 1.0

Page 30 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

// E0-type administrative data. typedef struct { char MsgId[FIELD_SIZE_MSGID+1]; char SendTime[FIELD_SIZE_TIME+1]; char ReceiptTime[FIELD_SIZE_TIME+1]; char DeliveryTimeOut[FIELD_SIZE_TIMEOUT+1]; char RouteData[FIELD_SIZE_ROUTE_DATA+1]; char Filler[FIELD_SIZE_FILLER_E0+1]; } MMTPAdminDataE0; // A1-type administrative data. typedef struct { char MsgId[FIELD_SIZE_MSGID+1]; char SendTime[FIELD_SIZE_TIME+1]; char ReceiptTime[FIELD_SIZE_TIME+1]; char DeliveryTimeOut[FIELD_SIZE_TIMEOUT+1]; char ReceiveTime[FIELD_SIZE_TIME+1]; char SubsId[FIELD_SIZE_SUBS_ID+1]; char MemberId[FIELD_SIZE_MEMBER_ID+1]; char Domain[FIELD_SIZE_DOMAIN+1]; char Dest[FIELD_SIZE_SUBS_ID+1]; char Filler[FIELD_SIZE_FILLER_A1+1]; } MMTPAdminDataA1; typedef struct { char MsgId[FIELD_SIZE_MSGID+1]; char SendTime[FIELD_SIZE_TIME+1]; char ReceiptTime[FIELD_SIZE_TIME+1]; char DeliveryTimeOut[FIELD_SIZE_TIMEOUT+1]; char RouteData[FIELD_SIZE_ROUTE_DATA+1]; char OnMember[FIELD_SIZE_MEMBER_ID+1]; char Domain[FIELD_SIZE_DOMAIN+1]; char Dest[FIELD_SIZE_SUBS_ID+1]; char Filler[FIELD_SIZE_FILLER_M0+1]; } MMTPAdminDataM0; // Generic administrative data. typedef struct { char MsgId[FIELD_SIZE_MSGID+1]; char SendTime[FIELD_SIZE_TIME+1]; char ReceiptTime[FIELD_SIZE_TIME+1]; } MMTPAdminGeneric; // Administrative data. typedef struct { int Type; int Size; union { MMTPAdminDataA1 A1; MMTPAdminDataE0 E0; MMTPAdminDataE1 E1; MMTPAdminDataM0 M0; MMTPAdminGeneric Generic; char Data[FIELD_SIZE_ADMIN]; } Data; char Unknown[FIELD_SIZE_ADMIN]; } MMTPAdminData; Version: 1.0 Page 31 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

A.3

MMTPMsg
The MMTPMsg data type is used by the following functions:
• •

MMTPReceiveMessage MMTPSendError

// Contents of CONX-REQ message. typedef struct { char SubsId[FIELD_SIZE_SUBS_ID+1]; int Level; char Options[FIELD_SIZE_OPTIONS+1]; char AuthData[FIELD_SIZE_AUTH_DATA+1]; } MMTPConxReq; // Contents of CONX-ACK message. typedef struct { char Options[FIELD_SIZE_OPTIONS+1]; } MMTPConxAck; // Contents of CONX-NACK message. typedef struct { MMTPCnxNckRsn Reason; } MMTPConxNack; // Contents of START-REQ message. typedef struct { char MsgId[FIELD_SIZE_MSGID+1]; } MMTPStartReq; // Contents of START-ACK message. typedef struct { int SeqNb; char MsgId[FIELD_SIZE_MSGID+1]; } MMTPStartAck; // Contents of START-NACK message. typedef struct { MMTPStrtNckRsn Reason; char MsgId[FIELD_SIZE_MSGID+1]; } MMTPStartNack; // Contents of DATA-MSG message. typedef struct { int SeqNb; int DataSize; MMTPAdminData AD; char Data[FIELD_SIZE_DATA+1]; } MMTPDataMsg; // Contents of SYNC-ACK message. typedef struct { int SeqNb; Version: 1.0 Page 32 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

char MsgId[FIELD_SIZE_MSGID+1]; } MMTPSyncAck; // Contents of DCNX-REQ. typedef struct { MMTPDcnxRsn Reason; int SeqNb; } MMTPDcnxReq; // Contents of DCNX-ACK. typedef struct { int SeqNb; } MMTPDcnxAck; // Contents of ERR-IND. typedef struct { MMTPErrIndErr Error; int SubError; int SeqNb; int Length; char Body[FIELD_SIZE_ERROR_BODY+1]; } MMTPErrInd; // Contents of SRVC-MSG typedef struct { char Type[FIELD_SIZE_SERVICE+1]; int Size; char Data[FIELD_SIZE_DATA+1]; } MMTPSrvcMsg; typedef struct { long Length; short Type; union { MMTPConxReq ConxReq; MMTPConxAck ConxAck; MMTPConxNack ConxNack; MMTPErrInd ErrInd; MMTPDcnxReq DcnxReq; MMTPDcnxAck DcnxAck; MMTPDataMsg DataMsg; MMTPSyncAck SyncAck; MMTPStartReq StartReq; MMTPStartAck StartAck; MMTPStartNack StartNack; MMTPSrvcMsg SrvcMsg; } Data; } MMTPMsg;

A.4
Error Code 0

Error Codes
Value MMTP_OK No error.
Page 33 of 116 March, 2006

Description

Version: 1.0

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Error Code 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

Value MMTP_NOT_CONNECTED MMTP_INVALID_ADDRESS MMTP_CNX_LOST MMTP_NO_MESSAGE MMTP_INVALID_ARG MMTP_CLIENT_FCT MMTP_SERVER_FCT MMTP_INVALID_SESSION MMTP_ALREADY_IN_PRO GRESS MMTP_ALREADY_CONNE CTED MMTP_ALREADY_INITIAL IZED MMTP_NOT_INITIALIZED MMTP_CRYPT_ERROR MMTP_CANNOT_INIT_SOC KET MMTP_NOT_ENOUGH_ME MORY MMTP_TOO_MUCH_SESSI ONS MMTP_CANNOT_OPEN_LO GFILE MMTP_LOGFILE_NOT_OPE NED MMTP_SOCKET_FULL MMTP_SOCKET_ERROR MMTP_BUFFER_FULL MMTP_NOT_IN_PROGRESS MMTP_TOO_MUCH_LISTE N_PORTS MMTP_ENCRYPTION_UNA VAILABLE MMTP_INVALID_ENCRYPT ION_LIB

Description Logical connection not established. Invalid IP address. Physical connection lost. No message received. Invalid argument. Session open in server mode and the requested function is reserved for sessions open in client mode. Session open in client mode and the requested function is reserved for sessions open in server mode. Invalid session. A message of the same type is still awaiting acceptance. Logical connection already established. Library already initialized. Library not initialized. Encryption/decryption error. Unable to open socket. Insufficient memory. Maximum number of sessions open. Impossible to open the protocol transfer log file. Protocol transfer log file not open. Socket full. Socket system error. Write buffer full. Use MMTPWriteTerminate to empty it. Pending action to be interrupted does not exist. Too many listen ports open. Encryption feature not available. Encryption library invalid.
Page 34 of 116 March, 2006

Version: 1.0

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Error Code 26 27 28 29 30 31 32 33 34 35 36 37 38

Value MMTP_SYSTEM_EXCEPTI ON MMTP_SYSTEM_ERROR MMTP_BAD_KEY MMTP_INVALID_ARG1 MMTP_INVALID_ARG2 MMTP_INVALID_ARG3 MMTP_INVALID_ARG4 MMTP_INVALID_ARG5 MMTP_INVALID_ARG6 MMTP_INVALID_ARG7 MMTP_INVALID_ARG8 MMTP_INVALID_ARG9 MMTP_NO_KEY_DEFINED

Description System exception trapped. System error. Bad encryption/decryption key. The first argument is invalid. The second argument is invalid. The third argument is invalid. The fourth argument is invalid. The fifth argument is invalid. The sixth argument is invalid. The seventh argument is invalid. The eighth argument is invalid. The ninth argument is invalid. No key defined.

A.5

Connection Parameters
Connection parameters contain the values for the exchange session at the time of connection. They use a field of 16 characters specifying the dialog options. Each character corresponds to an option and can have a value of:
• •

0 if the option is not used 1 if the option is used Indication Encryption Disconnection on sequence error Reserved for future use

Offset 0 1 2 to 15

Note: For Bx Connect processes, the connection parameter must be set to 0100000000000000.

A.6

Refusal Reason Codes for Connection Request
A client connection request can be refused for the following reasons:

Refusal Code 01 02
Version: 1.0

Description Invalid client Bx Connect is not available
Page 35 of 116

Value MMTPCnxNckRsn_InvalidMember MMTPCnxNckRsn_HubNotReady
March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Refusal Code 03 04 05 06 07

Description Unknown client or wrong password Last connection too recent (retry later) Invalid version of MMTP Library Invalid option Too many connections

Value MMTPCnxNckRsn_UnknownMemb er MMTPCnxNckRsn_LastCnxTooRec ent MMTPCnxNckRsn_InvalidVersion, MMTPCnxNckRsn_InvalidOptions MMTPCnxNckRsn_TooManyCnx

A.7

Refusal Reason Codes for Transmission/Retransmission Request
A transmission/retransmission request can be refused for the following reasons:

Refusal Code 01 02 03

Description START-REQ already requested but not acknowledged No connection to Bx Connect exists Message indicated by MsgId not found

Value MMTPStrtNckRsn_StartReqInProgr ess MMTPStrtNckRsn_NoHubCnx, MMTPStrtNckRsn_MsgIdNotFound

A.8

Disconnection Reason Codes
A disconnection request can be invoked using one of the following reasons:

Reason Code 01 02 03 04 05

Description Normal disconnection Bx Connect administration request for disconnection Abnormal disconnection Session interrupted by Bx Connect START-ACK not received or the START-ACK MsgId does not correspond to the data requested in the START-REQ No more messages to be delivered Bad encryption/decryption key Admin data is invalid Access control list violation

Value MMTPDcnxRsn_Normal MMTPDcnxRsn_AskedByHub MMTPDcnxRsn_Abnormal MMTPDcnxRsn_SessionBroken MMTPDcnxRsn_InvalidStartAck

06 07 08 09

MMTPDcnxRsn_LastMsgSent MMTPDcnxRsn_InvalidKey MMTPDcnxRsn_InvalidAdminData MMTPDcnxRsn_AclViolation

Version: 1.0

Page 36 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

B. API (Protocol Management Functions)
This appendix describes the Protocol Management functions available in the MMTP API. Functions are listed in alphabetical order.

B.1

MMTPCheckConnectionRequest
extern long MMTPCheckConnectionRequest(MMTPSESSION);

Description:
MMTPCheckConnectionRequest checks the time since the last connection request was sent.

Arguments:
Parameter
MMTPSESSION Session handle

Description

Input

Output

Input/ Output

Return Code:
Data Type Long Value Time in milliseconds -1 Description The time in milliseconds since the last connection request was sent. If no connection request is in progress or session is invalid or not connected.

Version: 1.0

Page 37 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Example:
The example below illustrates the invocation of MMTPCheckConnectionRequest before attempting to establish a logical connection. If the last connection request exceeds a pre-defined REPLY_TIMEOUT parameter, then the application should cancel the connection request and terminate the session.

// Initialize the MMTP library (for one session only). rc=MMTPInitialize(1); if(rc==MMTP_OK) { // Create the session. rc=MMTPCreateSession(NULL,NULL,&Session); . . // While the end is not asked or the logical connection exists. while(Quit==FALSE || MMTPCheckLogicalConnection(Session)==TRUE) { MustWait=TRUE; // If the physical connection is established or // the attempt to establish it successed. if(MMTPCheckPhysicalConnection(Session)==TRUE || EstablishConnection()==TRUE) { // If a connection request has been sent and reply timeout expired. if(MMTPCheckConnectionRequest(Session)>REPLY_TIMEOUT) { puts("Timeout in connection request."); // Cancel the connection request and close the session. MMTPCancelConnectionRequest(Session); MustWait=FALSE; }

B.2

MMTPCheckDisconnectionRequest
extern long MMTPCheckDisconnectionRequest(MMTPSESSION);

Description:
MMTPCheckDisconnectionRequest checks the time since the last disconnection request was issued.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Version: 1.0

Page 38 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Long Value Time in milliseconds -1 Description The time in milliseconds since the last disconnection request was sent. If no disconnection request is in progress or session is invalid or not connected.

B.3

MMTPCheckHandle
extern BOOL MMTPCheckHandle(MMTPSESSION);

Description:
MMTPCheckHandle validates a session handle. The function returns a Boolean of value FALSE if the handle is invalid or not recognized. This function is appropriate for applications that manage multiple MMTP sessions.

Arguments:
Parameter MMTPSESSION session handle Description Input Output Input/ Output

Return Code:
Data Type Boolean Value TRUE FALSE If the session handle is valid If the session is invalid or not recognized Description

B.4

MMTPCheckLogicalConnection
extern BOOL MMTPCheckLogicalConnection(MMTPSESSION);

Description:
MMTPCheckLogicalConnection checks the status of the MMTP logical connection that was established with the MMTPConnectionRequest C function.

Arguments:
Parameter MMTPSESSION
Version: 1.0

Description Session handle
Page 39 of 116

Input

Output

Input/ Output

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Boolean Value TRUE FALSE Description The logical connection is established. The logical connection is not established.

B.5

MMTPCheckPhysicalConnection
extern BOOL MMTPCheckPhysicalConnection(MMTPSESSION);

Description:
MMTPCheckPhysicalConnection checks the status of the physical connection established for the MMTP session. A physical connection is considered active after a binding agreement of sockets between the API client application and the MMTP server has occurred. This is accomplished through the MMTPOpenClientSession C function.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Boolean Value TRUE FALSE Description The physical connection is established. The physical connection is not established

Version: 1.0

Page 40 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

B.6

MMTPCheckStartRequest
extern long MMTPCheckStartRequest(MMTPSESSION);

Description:
MMTPCheckStartRequest checks the time since the last MMTPStartRequest (START-REQ) message was issued.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Long Value Time in milliseconds -1 Description The time in milliseconds since the last transmission/retransmission request was sent. If the transmission/retransmission request was not issued.

B.7

MMTPCheckSyncRequest
extern long MMTPCheckSyncRequest(MMTPSESSION);

Description:
MMTPCheckSyncRequest checks the time since the last MMTPSyncRequest (SYNC-REQ) message was issued.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Version: 1.0

Page 41 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Long Value Time in milliseconds -1 Description The time in milliseconds since the last acknowledgement request by data source (SYNC-REQ) was sent. If the acknowledgement request by data source (SYNC-REQ) was not issued.

B.8

MMTPErrorDescription
extern char* MMTPErrorDescription(int);

Description:
MMTPErrorDescription takes an MMTP session error code of the integer data type and converts it to a text message description.

Arguments:
Parameter Int Error code Description Input Output Input/ Output

Return Code:
Error Code 0 1 2 3 4 5 6 7 8 9 10 11 12 13
Version: 1.0

Description No error The logical connection is not established The IP address is invalid The physical connection is lost No message received Invalid argument Function only available for client session Function only available for server session The session is invalid A request of this type is already in progress The logical connection is already established The library is already initialized The library is not initialized Error during crypt/decrypt process
Page 42 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Error Code 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

Description Unable to open the socket Insufficient memory The maximum number of connections is reached Unable to open the log file The log file is not opened The socket is full Socket system error The write buffer is full The request to be cancelled does not exists Too many listen ports are opened Encryption feature not available Invalid encryption library System exception trapped A system error occurred Bad encryption/decryption key The first argument is invalid The second argument is invalid The third argument is invalid The fourth argument is invalid The fifth argument is invalid The sixth argument is invalid The seventh argument is invalid The eighth argument is invalid The ninth argument is invalid No key defined

B.9

MMTPObtainNumberSessions
extern int MMTPObtainNumberSessions(void);

Description:
MMTPObtainNumberSessions returns the current number of open sessions.

Version: 1.0

Page 43 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter Void No input Description Input Output Input/ Output

Return Code:
Data Type Int Value # of sessions Description Current number of open sessions

B.10 MMTPObtainPrimitiveName
extern char* MMTPObtainPrimitiveName(int);

Description:
MMTPObtainPrimitiveName translates the message primitive number into the equivalent name in a string format. This function is useful for error logging or logging of MMTP events such as START-REQ, START-ACK, CONX-REQ, CONX-ACK, etc.

Arguments:
Parameter Int Description MMTP Primitive Number Input Output Input/ Output

Return Code:
Data Type Char* Value and description Refer to the table of message primitives in Section 2.3 MMTP Message Primitives. When the primitive number cannot be translated, “UNKNOWN” is returned.

Version: 1.0

Page 44 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

B.11 MMTPSendError
extern int MMTPSendError(MMTPSESSION, int, int, int, MMTPMsg*);

Description:
In the event that the API client application detects an error during the message exchange, it can use MMTPSendError to send an error message to the MMTP server. The function sends an ERR-IND primitive to the MMTP server with the error code and the sequence number of the message in which the error occurs.

Arguments:
Parameter MMTPSESSION Int Int Int MMTPMsg Error Code 1 2 3 4 5 6 to 8 9 6 to 49 Greater than 49 Sequence number greater than expected Sequence number lower than expected Invalid field Inappropriate message Invalid message Reserved error code for future use Access Control List violation Reserved error code for future use User defined error code MMTPErrIndErr_AclViolation MMTPErrIndErr_MsgLost MMTPErrIndErr_MsgDuplicate MMTPErrIndErr_InvalidField MMTPErrIndErr_OutOfContext MMTPErrIndErr_InvalidMsg Session handle Error code Error sub-code The sequence number of the message in which the error occurs Message in which the error occurs Description Value Description Input Output Input/ Output

Version: 1.0

Page 45 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int 0 Greater than 0 Value No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
The sample send program uses the ProcessSyncAcknowledgement function to inspect the sequence number provided by the receiving application. If the sequence number is greater than the expected value, the send program sends an error message using the MMTPSendError function.
void ProcessSyncAcknowledgement(MMTPMsg* Msg) { // If the sequence number given in the ack is invalid, // send an error and close the session. if(Msg->Data.SyncAck.SeqNb>SyncSeqNb) { MMTPSendError(Session,1,3,LastSeqNb,Msg); MMTPCloseSession(Session); Quit=TRUE; }

B.12 MMTPSetCheckAliveTimeout
extern int MMTPSetCheckAliveTimeout(MMTPSESSION, int);

Description:
Use the MMTPSetCheckAliveTimeout to enable or disable heartbeat monitoring in the MMTPReceiveMessage function. It can be enabled once the socket connection is opened (disabled is the default state). When heartbeat monitoring in enabled, then while waiting for the next message, the MMTPReceiveMessage function checks that the server is still alive. It should regularly receive a PRSC-MSG primitive (the heartbeat) from the server. If the timeout has exceeded before having received a PRSC-MSG, then the socket connection has broken down and the MMTPReceiveMessage function returns a connection lost error. The timeout is reset after every message is transmitted (not just after the heartbeat).

Arguments:
Parameter MMTPSESSION
Version: 1.0

Description Session handle
Page 46 of 116

Input

Output

Input/ Output

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Parameter Int

Description Timeout in seconds (from 10 to 7200) for PRSC-MSG reception. If 0, the check will be disabled

Input

Output

Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

B.13 MMTPWaitForStartRequest
extern BOOL MMTPWaitForStartRequest(MMTPSESSION);

Description:
MMTPWaitForStartRequest allows the sending application to check if the receiving application had received and processed the transmission/retransmission request (START-REQ). Use this function to check that you can send data-messages to the client. This function returns FALSE if a transmission/retransmission request has been received and accepted with MMTPAcceptStart. Otherwise it returns TRUE (did not received a transmission/retransmission request, or received one but refused it with MMTPDenyStart).

Arguments:
Parameter MMTPSession Session handle Description Input Output Input/ Output

Version: 1.0

Page 47 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type BOOL Value TRUE Description The receiving application did not receive the transmission/retransmission request, or it received the transmission/retransmission request but refused the transmission/retransmission request with the MMTPDenyStart function. The transmission/retransmission request was received and accepted with the MMTPAcceptStart

FALSE

Version: 1.0

Page 48 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

C. API (Session Management Functions)
This appendix describes the Session Management functions available in the MMTP API. Functions are listed in alphabetical order.

C.1

MMTPAcceptConnection
extern int MMTPAcceptConnection(MMTPSESSION, char*);

Description:
MMTPAcceptConnection sends a connection acceptance (CONX-ACK) in response to the client connection request (CONX-REQ) from a requestor. The CONX-REQ primitive is triggered by the MMTPConnectionRequest function.

Arguments:
Parameter MMTPSESSION Char* Description Logical session handle Connection parameters Please refer to the table in the Connection Parameters section in Appendix A Input Output Input/ Output

Return Code:
Data Type
Int

Value
0 Greater than 0 No error – MMTP_OK

Description
Please refer to the list of possible error codes in Appendix A

Version: 1.0

Page 49 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

C.2

MMTPAcceptDisconnection
extern int MMTPAcceptDisconnection(MMTPSESSION,int);

Description:
MMTPAcceptDisconnection allows the sender or the receiver to respond with a disconnection request acknowledgement (DCNX-ACK) to its partner. The disconnection request is invoked by the C function MMTPDisconnectionRequest (DCNX-REQ). MMTPAcceptDisconnection also closes the session.

Arguments:
Parameter MMTPSESSION Int Description Logical session handle Last sequence number received Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.3

MMTPAcceptStart
extern int MMTPAcceptStart(MMTPSESSION, int, char*);

Description:
MMTPAcceptStart allows developers to send a transmission/retransmission request acknowledgement (START-ACK) in response to a transmission/retransmission request (START-REQ). The function accepts a session handle, the sequence number used when sending the next data message, and the message ID of the last message received. The transmission/retransmission request is invoked by the C function MMTPStartRequest.

Version: 1.0

Page 50 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter MMTPSESSION Int Char* Description Logical session handle Last sequence number received Message ID of the last message received Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
The ProcessStartRequest sample function invokes the MMTPAcceptStart function to inform the receiving application that the sequence number will start at 1 and the last message received is stored in the MsgId field.
void ProcessStartRequest(MMTPStartReq* StartReq) { int i; char Buffer[2000]; printf( "Start request received (MsgId %s)\n", (StartReq->MsgId[0]==0 ? "empty" : StartReq->MsgId)); // Fetch the number of the last line received by the server. LastMsgIdSent=atoi(StartReq->MsgId); // Go to the begining of the file. fseek(InputFile,SEEK_SET,0); // Put the file pointer on the right line. for(i=0;i<LastMsgIdSent;i++) { if(fgets(Buffer,sizeof(Buffer),InputFile)==NULL) { MMTPDenyStart(Session,3,StartReq->MsgId); LastMsgIdSent=0; return; } } // Compute the sequence numbers in relation with the sync request. LimitSeqNb=WINDOW_SIZE; SyncSeqNb=WINDOW_SIZE/2; LastSeqNb=0; MMTPAcceptStart(Session,1,StartReq->MsgId); }

Version: 1.0

Page 51 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

C.4

MMTPAcceptSync
extern int MMTPAcceptSync(MMTPSESSION, int, char*);

Description:
MMTPAcceptSync sends a synchronization acknowledgement (SYNC-ACK) in response to an acknowledgement request by data source (SYNC-REQ) from the sender. The function accepts a session handle and the last sequence number received. The acknowledgement request by data source is invoked by the C function MMTPSyncRequest.

Arguments:
Parameter MMTPSESSION Int Char* Description Logical session handle Last sequence number received Message ID of last data message received Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.5

MMTPCancelConnectionRequest
extern int MMTPCancelConnectionRequest(MMTPSESSION);

Description:
MMTPCancelConnectionRequest cancels the client connection request while the request is in progress. This function is appropriate when MMTPConnectionRequest (CONX-REQ) has been invoked and the connection acceptance (CONX-ACK) has not been received from the MMTP server. Furthermore, this function closes the session.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Version: 1.0

Page 52 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int 0 Greater than 0 Value No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.6

MMTPCancelDisconnectionRequest
extern int MMTPCancelDisconnectionRequest(MMTPSESSION);

Description:
MMTPCancelDisconnectionRequest cancels the disconnection request while the request is in progress. This function is appropriate when the MMTPDisconnectionRequest (DCNX-REQ) has been invoked and a disconnection request acknowledgement (DCNX-ACK) has not been received from the MMTP server. Similar to MMTPCancelConnectionRequest, this function closes the session.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.7

MMTPCancelStartRequest
extern int MMTPCancelStartRequest(MMTPSESSION);

Description:
MMTPCancelStartRequest cancels the transmission/retransmission request while the request is in progress. This function is appropriate when MMTPStartRequest (START-REQ) is invoked and a transmission/retransmission request acknowledgement (START-ACK) has not been received from the MMTP server.

Version: 1.0

Page 53 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.8

MMTPCancelSyncRequest
extern int MMTPCancelSyncRequest(MMTPSESSION);

Description:
MMTPCancelSyncRequest cancels the acknowledgement request by data source while the request is in progress. This function is appropriate when MMTPSyncRequest (SYNC-REQ) has been invoked and a Synchronization acknowledgement (SYNC-ACK) has not been received from the MMTP server.

Arguments:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.9

MMTPCloseSession
extern int MMTPCloseSession(MMTPSESSION);

Description:
MMTPCloseSession terminates the client session that was created by the MMTPOpenClientSession function. MMTPCloseSession breaks the physical socket connection between the API client application and the MMTP server.
Version: 1.0 Page 54 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Argument:
Parameter MMTPSESSION Description Logical session handle Input Output Input/ Output

Return Code:
Data Type Int 0 Greater than 0 Value No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.10 MMTPConnectionRequest
extern int MMTPConnectionRequest(MMTPSESSION, char*, char*, char*);

Description:
MMTPConnectionRequest initiates a request to connect to an MMTP partner by passing the CONX-REQ primitive. In the MMTP solution, the MMTP partner is Bx Connect. The API client application is responsible for passing its identifier and password for authentication. If the authentication is successful, communication is granted through CONX-ACK. Otherwise, a connection refusal is returned (CONX-NACK). This function is used after MMTPOpenClientSession has been invoked.

Version: 1.0

Page 55 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter MMTPSESSION Char* Char* Description Logical session handle obtained from MMTPCreateSession Client Identifier (up to 11 characters) Connection parameters (16 characters: 0 or 1) – Refer to the table in the Connection Parameters section in Appendix A Char* Client’s password Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example
The EstablishConnection example below describes the logic requires for building a session. The MMTPConnectionRequest function is used after a physical connection is established. The client connection request requires Client Identifier and its Password. The Client Identifier is stored in the User field.
BOOL EstablishConnection() { int rc; // If the physical connection is not established. if(MMTPCheckPhysicalConnection(Session)==FALSE) { // Try to physically connect the session to the server. rc=MMTPOpenClientSession(Session,TcpPort,IpAddr,0); // If the physical connection is established. if(rc==MMTP_OK) { puts("Physical connection established"); // Send a connection request. puts("Sending connection request"); rc=MMTPConnectionRequest(Session,User,"0000000000000000",Password) ; if(rc==MMTP_OK) { return(TRUE); }

Version: 1.0

Page 56 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

printf( in MMTPConnectionRequest : %d - %s\n", "Error rc,MMTPErrorDescription(rc)); Quit=TRUE; } else { if(rc!=MMTP_NOT_CONNECTED) { printf( "Error in MMTPOpenClientSession: %d - %s\n", rc,MMTPErrorDescription(rc)); Quit=TRUE; } } } return(FALSE); }

C.11 MMTPCreateSession
extern int MMTPCreateSession(char*, char*,MMTPSESSION*);

Description:
MMTPCreateSession creates a logical MMTP session. MMTPCreateSession returns a session handle and a return code of MMTP_OK if successful. Otherwise, the function returns an error code and the session handle is set to NULL. For an API client application building multiple MMTP sessions, the API client application must invoke this function several times, one for each unique session.

Arguments:
Parameter Char* Char* MMTPSESSION* Description NULL indicator NULL indicator Pointer to a session handle Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.12 MMTPDeleteSession
extern int MMTPDeleteSession(MMTPSESSION);
Version: 1.0 Page 57 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Description:
MMTPDeleteSession terminates the MMTP session. The function deallocates the session buffer, decrements the number of active sessions, and releases the session handle. If MMTPCreateSession is invoked, then MMTPDeleteSession is required for removing the MMTP session.

Arguments:
Parameter MMTPSESSION Description Logical session handle Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.13 MMTPDenyConnection
extern int MMTPDenyConnection(MMTPSESSION, int);

Description:
MMTPDenyConnection rejects the client connection request (CONX-REQ) by sending a connection refusal (CONX-NACK). It uses the sender’s session handle to respond with the reason for connection refusal. The MMTPConnectionRequest C function initiates the client connection request.

Arguments:
Parameter MMTPSESSION Int Description Logical session handle obtained from MMTPCreateSession Reason for refusing connection – Refer to the Refusal Reason Codes for Connection Request section in Appendix A Input Output Input/ Output

Version: 1.0

Page 58 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.14 MMTPDenyStart
extern int MMTPDenyStart(MMTPSESSION, int, char *);

Description:
MMTPDenyStart rejects a transmission/retransmission request (START-REQ) by sending a transmission/retransmission request refusal (START-NACK). It uses the sender’s session handle to respond with the reason for refusal. To reject a transmission/retransmission request, the receiver uses this function.

Arguments:
Parameter MMTPSESSION Int Description Logical session handle obtained from MMTPCreateSession Reason for refusing startup – Refer to the Refusal Reason Codes for Connection Request section in Appendix A Char* Message ID of the last message received that was included in the START-REQ message. Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Version: 1.0

Page 59 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

C.15 MMTPDisconnectionRequest
extern int MMTPDisconnectionRequest(MMTPSESSION, int, int);

Description:
MMTPDisconnectionRequest allows the sender or the receiver to send a disconnection request (DCNX-REQ) primitive to its partner. The function accepts a session handle, an integer describing reason of disconnection, and the last sequence number received.

Arguments:
Parameter MMTPSESSION Int Description Logical session handle Reason for disconnection – Refer to the Disconnection Reason Codes section in Appendix A Int Last sequence number received Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.16 MMTPInitialize
extern int MMTPInitialize(int);

Description:
MMTPInitialize allocates session resources such as local memory based on the maximum number of sessions requested by the API client application. This function can be used at the beginning of the API client application so that all resource allocation is done up-front. The equivalent MMTPTerminate function is used during the shutdown process.

Argument:
Parameter Int
Version: 1.0

Description Maximum number of sessions which will be
Page 60 of 116

Input

Output

Input/ Output

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Parameter

Description opened at the same time

Input

Output

Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.17 MMTPOpenClientSession
extern int char*,int); MMTPOpenClientSession(MMTPSESSION, unsigned short,

Description:
MMTPOpenClientSession establishes a physical connection with an MMTP server. The client must pass the port number and the host name or IP address of the server. This function is performed after a logical session has been established using MMTPCreateSession. Once the socket connection is opened, the heartbeat mechanism is enabled in the client and the server. During periods of message inactivity, the API client application and the server will generate the PRSC-MSG primitive (the heartbeat) at regular time intervals (60 seconds during idle time). Use the MMTPSetCheckAliveTimeout function to monitor the heartbeat of the server.

Version: 1.0

Page 61 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter MMTPSESSION Unsigned short Description Logical session handle obtained from MMTPCreateSession The port number to establish the session. This number is used by the MMTP server to listen for incoming messages. Host name of the MMTP server. Timeout in milliseconds. If 0, function returns immediately Input Output Input/ Output

Char* Int

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A. When a system socket error occurs, use the Unix errno variable or the NT WSAGetLastError function to obtain more details. Description

C.18 MMTPStartRequest
extern int MMTPStartRequest(MMTPSESSION, char*);

Description:
MMTPStartRequest initiates a transmission/retransmission request (START-REQ) to the sender. This function informs the sender that the receiver is ready to obtain data messages. MMTPStartRequest must be invoked before the MMTPReceiveMessage function.

Arguments:
Parameter MMTPSESSION Char* Description Logical session handle Message ID of the last message received Input Output Input/ Output

Return Code:
Data Type Int
Version: 1.0

Value 0 No error – MMTP_OK
Page 62 of 116

Description

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Data Type

Value Greater than 0

Description Please refer to the list of possible error codes in Appendix A

C.19 MMTPSyncRequest
extern int MMTPSyncRequest(MMTPSESSION);

Description:
MMTPSyncRequest submits an acknowledgement request by data source (SYNCREQ) to the receiving application. This function asks the MMTP receiver to respond with its current sequence number. The MMTP receiver responds using the MMTPAcceptSync function.

Arguments:
Parameter MMTPSESSION Description Logical session handle Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

C.20 MMTPTerminate
extern int MMTPTerminate(void);

Description:
MMTPTerminate ends the remaining connection and frees session resources. It is recommended that the function be invoked before closing down the API client application.

Arguments:
Parameter Void No input Description Input Output Input/ Output

Version: 1.0

Page 63 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Version: 1.0

Page 64 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

D. API (Logging Functions)
This appendix describes the Logging functions available in the MMTP API. Functions are listed in alphabetical order.

D.1

MMTPCloseLog
extern int MMTPCloseLog(void);

Description:
MMTPCloseLog attempts to close a previously opened log file. If successful, a code if MMTP_OK is returned. Otherwise, an error code of MMTP_LOGFILE_NOT_OPENED is returned.

Argument:
Parameter Void No input Description Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Version: 1.0

Page 65 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

D.2

MMTPLogSession
extern int MMTPLogSession(MMTPSESSION, char*);

Description:
MMTPLogSession generates logging information for a specific session. The function uses the session handle to activate logging for that MMTP session. The logging information consists of sent and received messages that can be used as a historical trace or a debugging mechanism. Before applying this function, MMTPOpenLog must be invoked with success.

Arguments:
Parameter MMTPSESSION Char* Description Logical session handle obtained from MMTPCreateSession Unique name of the session identified by the application Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

D.3

MMTPOpenLog
extern int MMTPOpenLog(char*, BOOL);

Description:
MMTPOpenLog opens a log file for message logging. The opened log file is based on the input argument Log File Name. The function will return MMTP_OK if successful, else an error code MMTP_CANNOT_OPEN_LOGFILE is returned. The API client application can only open one log file at a time.

Version: 1.0

Page 66 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter Char* BOOL Description Name of the log file Boolean TRUE = creates a log file FALSE = appends to existing log file. If log file does not exist, then creates one. Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
Below is a sample invocation of the MMTPOpenLog function during the initialization process. The input arguments include the name of the log file and a Boolean. In this case the Boolean is set to TRUE to indicate that the log file will be created. If the Boolean is set to FALSE, log messages will be appended to the specified log file.
/**********************************************************/ /* Memory allocation of communication session */ /**********************************************************/ if (MMTPInitialize(SESSION_NB) != MMTP_OK) { fprintf(stderr,”Protocol intialization failed\n”); return (Member GatewayCC_FAILED); } /*******************************************************/ /* Open protocol trace file */ /*******************************************************/ if (MMTPOpenLog(LogFile, TRUE) != MMTP_OK) { fprintf(stderr,”Open trace file failed\n”); } return(Member GatewayCC_OK);

Version: 1.0

Page 67 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

D.4

MMTPSetUserLogFct
extern int MMTPSetUserLogFct(MMTPSESSION, void (*));

Description:
MMTPSetUserLogFct invokes the customized logging function. Developers are allowed to build customized logging functions. The MMTPSetUserLogFct function is responsible for launching it at execution time.

Arguments:
Parameter MMTPSESSION Void (* fct) Description Logical session handle obtained from MMTPCreateSession Pointer to a custom logging function. MMTP will execute the logging function. Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Version: 1.0

Page 68 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

E. API (Transmission Functions)
This appendix describes the Transmission functions available in the MMTP API. Functions are listed in alphabetical order.

E.1

MMTPReceiveMessage
extern int MMTPReceiveMessage(MMTPSESSION, int, MMTPMsg*);

Description:
MMTPReceiveMessage receives messages from the sending application. The body of the message is stored in the MMTPMsg data structure. The MMTPReceiveMessage function is used for retrieving session-based messages such as request and acknowledgement primitives (CONX-REQ, CONX-ACK, START-REQ, START-ACK). Moreover, the function is used to retrieve data messages (DATA-MSG) from the sending application. To receive data messages, the receiving application must send a transmission/retransmission request (START-REQ) to the sending application and wait until the sender responds with an acknowledgement (START-ACK or START-NACK). The START-ACK informs the receiving application that the sender will be sending messages of primitive DATA-MSG. Upon the invocation of MMTPReceiveMessage, the API client application must wait until the next message is received from the sender, or until the timeout parameter has exceeded. In this case, an error code of MMTP_NO_MESSAGE is returned.

Arguments:
Parameter MMTPSESSION Int MMTPMsg* Description Logical session handle obtained from MMTPCreateSession Timeout (in milliseconds) for message reception Pointer to buffer where the received message must be stored Input Output Input/ Output

Version: 1.0

Page 69 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int Value 0 4 Greater than 0 and # 4 No error – MMTP_OK MMTP_NO_MESSAGE MMTP error code is returned. Please refer to the list of possible error codes in Appendix A Description

Example:
The sample send and receive programs in Appendix H invoke the MMTPReceiveMessage function to retrieve data messages as well as communication messages.
rc=MMTPReceiveMessage(Session,0,&Msg);

switch(rc) { case MMTP_OK: { case CONX_ACK: case CONX_NACK: case DCNX_ACK: case START_REQ: case DATA_MSG: case SYNC_REQ: case DCNX_REQ: case SYNC_ACK: case SRVC_MSG: default: } case MMTP_CNX_LOST: case MMTP_NO_MESSAGE: default: }

E.2

MMTPSendMessage
extern int MMTPSendMessage(MMTPSESSION, int, MMTPAdminData*, int, char*);

Description:
MMTPSendMessage sends a data message to the receiver. The API client application must map the data to the last argument of this function. Upon invocation of the function, the MMTP primitive of DATA-MSG is sent to the receiver. The sender must receive a transmission/retransmission request (STARTREQ) from the receiver before it can start transmitting messages.

Version: 1.0

Page 70 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter MMTPSESSION Int MMTPAdminData* Int Description Logical session handle obtained from MMTPCreateSession. Message sequence number. Administrative data to be sent or NULL if no data. Size of the application data. This can be equal to 0 if there is no application data or if it is a string of characters ending with a binary 0. Application data to be sent (can be NULL). If this parameter is not NULL and if the DataSize parameter is equal to 0, then this is considered to be a string of characters ending with a binary 0. Input Output Input/ Output

Char*

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
Below is the SendMessageToServer routine used by the sample send application in Appendix H. This routine demonstrates the MMTPSendMessage function.
/**********************************************************/ /* S E N D M E S S A G E T O S E R V E R /**********************************************************/ BOOL SendMessageToServer() { char Buffer[2000]; int rc; MMTPAdminData AdminData; SYSTEMTIME st; /*******************************************/ /* If a start request has been received. */ /*******************************************/ if(LastSeqNb==SyncSeqNb && MMTPCheckSyncRequest(Session)==-1) { printf("Send sync request on %d sequence number.\n",SyncSeqNb); MMTPSyncRequest(Session); return(TRUE); } /*******************************************/ /* Get the next line of the file */ /*******************************************/ if(fgets(Buffer,sizeof(Buffer),InputFile)==NULL) Version: 1.0 Page 71 of 116 */

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

{ puts("End of file reached"); DcnxReason=6; Quit=TRUE; return(FALSE); } LastMsgIdSent++; LastSeqNb++; printf("Sending line %d (SeqNb %d)\n",LastMsgIdSent,LastSeqNb); /*******************************************/ /* Construct the administration data of the message */ /*******************************************/ AdminData.Type=ADMIN_DATA_E0; sprintf(AdminData.Data.E0.MsgId,"%08d",LastMsgIdSent); GetSystemTime(&st); sprintf( AdminData.Data.E0.SendTime,"%02d%02d%02d%02d%02d%02d", st.wMonth,st.wDay,st.wHour,st.wMinute,st.wSecond,st.wMilliseconds/10); AdminData.Data.E0.ReceiptTime[0]=0; AdminData.Data.E0.DeliveryTimeOut[0]=0; AdminData.Data.E0.RouteData[0]=0; AdminData.Data.E0.Filler[0]=0; /*******************************************/ /* Send the message */ /*******************************************/ rc=MMTPSendMessage(Session,LastSeqNb,&AdminData,0,Buffer); if(rc!=MMTP_OK && rc!=MMTP_BUFFER_FULL && rc!=MMTP_CNX_LOST) { printf("Error in MMTPSendMessage : %d - %s\n",rc,MMTPErrorDescription(rc)); Quit=TRUE; } /*******************************************/ /*Not useful, just permits ctrl+C */ /*******************************************/ Sleep(100); return(TRUE); }

Version: 1.0

Page 72 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

E.3

MMTPSendServiceMessage
extern int MMTPSendServiceMessage(MMTPSESSION, char*, int, char*);

Description:
MMTPSendServiceMessage checks the status of connectivity between the MMTP sender and receiver. There are two types of service messages: 1) PING is used to verify that a partner is still present 2) PONG used to reply to a PING message The sender invokes MMTPSendServiceMessage (SRVC-MSG) with a PING type and the message service data containing the date and time of transmission using the YYYYMMDDHHmmsscc format. The receiver responds with an MMTPSendServiceMessage with a PONG type and a copy of the message service data.

Arguments:
Parameter MMTPSESSION Char* Description Logical session handle obtained from MMTPCreateSession Message Service Type a) PING b) PONG Int Char* Size of the service data. If no data follows the message, the length is "0000". This field contains the service data. The contents of the field depend on the type of service. Type = PING is used to verify that a partner is still present. service data: Data field defined by the sender. The receiver replies with a PONG type and a copy of the service data received with the PING. Type = PONG is used to reply to the PING message. service data: The PING service data field is copied for the reply. Input Output Input/ Output

Version: 1.0

Page 73 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
Below is an example of the MMTPSendServiceMessage function. MMTPReceiveMessage is invoked to retrieve primitive related messages as well as data messages. If the message received is of type SRVC_MSG, the application checks to see if the service message is of type PING. If so, it replies with a PONG message along with the service data received from the PING.
rc=MMTPReceiveMessage(Session,0,&Msg); switch(rc) { case MMTP_OK: { case CONX_ACK: case CONX_NACK: case DCNX_ACK: case START_REQ: case DATA_MSG: case SYNC_REQ: case DCNX_REQ: case SYNC_ACK: case SRVC_MSG: if(!strcmp(Msg.Data.SrvcMsg.Type,"PING")) { MMTPSendServiceMessage( Session,"PONG",Msg.Data.SrvcMsg.Size,Msg.Data.SrvcMsg.Data); } else { printf( "The %s service message received is unknown.", Msg.Data.SrvcMsg.Type); } break; default: } case MMTP_CNX_LOST: case MMTP_NO_MESSAGE: default: }

Version: 1.0

Page 74 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

E.4

MMTPTerminateWrite
extern int MMTPTerminateWrite(MMTPSESSION);

Description:
MMTPTerminateWrite is used when the message send function MMTPSendMessage returns an error MMTP_BUFFER_FULL. This function must be repeated until the return code of the function is set to MMTP_OK.

Argument:
Parameter MMTPSESSION Session handle Description Input Output Input/ Output

Return Code:
Data Type Int Value 0 Greater than 0 No error – MMTP_OK Please refer to the list of possible error codes in Appendix A Description

Example:
In this example, the sending application verifies the buffer status before sending messages to the receiving application. The main function invokes the MMTPTerminateWrite function to ensure that the MMTP buffer is not full.
/**************************************************************/ /* M A I N */ /**************************************************************/ void main(int argc,char** argv) { int rc; MMTPMsg Msg; BOOL MustWait; if(argc!=6) { puts("Missing parameter(s)"); puts("Syntax : Sender <Port> <IpAddr> <User> <Password> <Input file>"); return; } . . . while(Quit==FALSE || MMTPCheckLogicalConnection(Session)==TRUE) { MustWait=TRUE; . . Version: 1.0 Page 75 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

. /**************************************************/ /* Verify that the MMTP write buffer is empty /**************************************************/ else if(MMTPTerminateWrite(Session)==MMTP_OK) { . . . rc=MMTPReceiveMessage(Session,0,&Msg); switch(rc) { case MMTP_OK: { case CONX_ACK: case CONX_NACK: case DCNX_ACK: case START_REQ: case DATA_MSG: case SYNC_REQ: case DCNX_REQ: case SYNC_ACK: case SRVC_MSG: default: } case MMTP_CNX_LOST: case MMTP_NO_MESSAGE: if(MMTPWaitForStartRequest(Session)==FALSE && LastSeqNb<LimitSeqNb && SendMessageToServer()==TRUE) /* send message routine */ { MustWait=FALSE; } break; default: } } } } } /* end main*/

*/

Version: 1.0

Page 76 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

F.Program Highlights
This appendix highlights the main programming steps of an application that connects to Bx Connect. Step 1:
// Initialize the MMTP library

Step 2:
returncode=MMTPInitialize();

Step 3:
// Check the return code for error management – ie. Check if initialisation achieved

Step 4:
// Create the MMTP session

Step 5:
returncode=MMTPCreateSession();

Step 6:
// Check the return code for error management

Step 7:
// While the end is not asked for or the logical connection exists while(Var_Quit==FALSE) or MMTPCheckLogicalConnection(Session)==TRUE { MustWait=TRUE;

Step 8:
// Check if the physical connection is established or the attempt to establish it (physical, logical & CNX_Req succeeded) if MMTPCheckPhysicalConnection(Session)==TRUE or My_Function_EstablishConnection()==TRUE {

Version: 1.0

Page 77 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Step 9:
// Check error cases if MMTPCheckConnectionRequest(Session)>VAR_TIMEOUT) { }

Step 10:
// If a message is received then check its type and process it returncode=MMTPReceiveMessage();

Step 11:
// Check the return code for error management or the processing of the message received.

Step 12:
// If a message isn’t received, verify that the start_req has been received by Bx Connect, that the “window of sent messages” is not full, and send a message to Bx Connect. My_function_to_message();

Step 13:
} // End check physical connection

Step 14:
} // End while

Step 15:
MMTPTerminate(); // Terminate the session and exit.

Version: 1.0

Page 78 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

G. SMMTP (Simple MMTP)
G.1 Overview
The purpose of this appendix is to introduce the SMMTP API and provide a detailed description of the SMMTP functions and their arguments.

Description
The SMMTP API is a library of functions that allows a programmer to write a simple client application based on the MMTP protocol without using any of the MMTP API functions. The SMMTP API provides high-level functions: a single SMMTP function call generates several MMTP function calls. SMMTP makes it faster to develop a simple client application. SMMTP API offers less functionality than the MMTP API, however:
• • • •

It allows only connection, message sending, message reading and disconnection. It is single-threaded: SMMTP can be used to manage several connections with one thread, but it cannot handle several threads. It is unidirectional: programmers must use separate functions for input and output. It is synchronous: once the client application calls an SMMTP function, execution of the client application is suspended until the function has completed execution.

Client applications written to communicate with Bx Connect normally connect to send messages to Bx Connect. A process called PACIn receives messages from the client application, compresses and encrypts them, and sends them on to the Trading System. When Bx Connect replies, the PacIn process replies back to the client application. The SMMTP API could be also used to interface central exchange applications to Bx Connect.

Version: 1.0

Page 79 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Available Functions
• SMMTPConnect • SMMTPClose • SMMTPGet • SMMTPGetSync • SMMTPPut • SMMTPPutSync • SMMTPErrorDescription

Advantage
• Allows faster development of MMTP client applications

Restrictions
• Provides only simple operations such as connection, disconnection,

message sending and reading
• Does not support multi-threading • Connections are unidirectional • Function calls are synchronous

G.2 SMMTPMsg structure
Description:
Data message structure used by SMMTP functions.

Version: 1.0

Page 80 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Contents:
Field MsgId RouteData OnMember AdminSize Admin DataSize Data Reason Type text (25 characters) text (12 characters) text (9 characters) number number text (9500 characters) number Note: When a function returns the SMMTP_DISCONNECTION error code, the Reason field in the SMMTPMsg structure contains a code representing the reason for disconnection given by Bx Connect Server. The following table lists the codes and their descriptions: Code 01 02 03 04 05 06 Reason Client is not authorized to access the Bx Connect Server. Bx Connect Server is not ready to accept connections from clients. Client identifier or password is incorrect. Last connection request is too recent (delay not respected). Incompatible protocol version. Invalid protocol options. The SMMTP_DISCONNECTION error code can be returned by any SMMTP function call. Message ID. Same as the routing data field in message header type E0. Name of the member for whom the message is sent (MAPI case only). Size of contents in the Admin buffer. Size of contents in the Data buffer. Buffer for message data. Reason when SMMTP_DISCONNECTION error code is returned. Description

text (256 characters) Buffer for administrative data.

Version: 1.0

Page 81 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

G.3 SMMTPConnect
extern int SMMTPConnect( SMMTPHANDLE * Handle, unsigned short Port, char * IpAddr, char User, char * Password, int Direction, char MsgId, int SyncFreq, int Timeout );

Description:
Opens a new SMMTP session.

Version: 1.0

Page 82 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Arguments:
Parameter Handle Type SMMTPHANDLE * Description On output, pointer to a SMMTPHANDLE which receives the handle of the new session. On input, enables message logging if equal to 0xFFFFFFFF. Port IpAddr User Password Direction unsigned short char * char char * Int Port number used by the server IP address of the server User name used to establish the connection User password Must be equal to SMMTP_IN or SMMTP_OUT. - SMMTP_IN means that the session sends messages. - SMMTP_OUT means that the session receives messages. MsgId char * This parameter depends on the value of the Direction parameter. - If the Direction parameter is equal to SMMTP_IN, then the MsgId parameter is a pointer to a buffer which receives the MsgId of the last message received by the server. - If the Direction parameter is equal to SMMTP_OUT, then the MsgId parameter is a pointer to a buffer that contains the MsgId of the last message received by the client application. SyncFreq Int Number of messages between two sync messages. Value of 0 means that no sync messages are needed. Not used in SMMTP_OUT sessions. Timeout Int Maximum delay to established the connection. If equal to INFINITE, the function blocks until the connection is established (not recommended). In Out

Return Code:
Data Type Int Value SMMTP_OK Description If the connection is established.

Version: 1.0

Page 83 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Data Type Error code

Value

Description When other problems occur. Refer to errors returned by the SMMTPErrorDescription function. If the connection is not established, then the handle that is returned in the Handle parameter is invalid (and unchanged).

G.4 SMMTPClose
extern int SMMTPClose( SMMTPHANDLE Handle, SMMTPMsg *Msg int Timeout );

Description:
Closes the SMMTP session.

Arguments:
Parameter Handle Message Type SMMTPHANDLE SMMTPMsg * Description A SMMTPHANDLE obtained with the SMMTPConnect function. A pointer to a SMMTPMsg structure. The client application must provide the following field: Msg→Reason (reason for the disconnection) The function returns the following field: Msg→Reason (on SMMTP_DISCONNECTION) Timeout Int Maximum delay to send the disconnection request. If equal to INFINITE, the function blocks until a disconnection request is sent. In Out

Return Code:
Data Type Int Value SMMTP_OK Description If the close request is executed successfully.

Version: 1.0

Page 84 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Data Type

Value SMMTP_DISCONNECTION

Description If a disconnection request is received from the CAP or the Bx Connect Server. This case is rare: it only occurs when the CAP or the Bx Connect Server sends a disconnection request before it receives the close request from the client application. In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection.

Error code

When other problems occur. Refer to errors returned by the SMMTPErrorDescription function.

G.5 SMMTPGet
extern int SMMTPGet( SMMTPHANDLE Handle, SMMTPMsg *Msg int Timeout );

Description:
Gets a message from the CAP or the Bx Connect Server. This function can be called in a SMMTP_IN session only.

Arguments:
Parameter Handle Msg Type SMMTPHANDLE SMMTPMsg * Description A SMMTPHANDLE obtained with the SMMTPConnect function. A pointer to a SMMTPMsg structure that receives the message. The function returns the following fields: Msg→Admin Msg→AdminSize Msg→MsgId Msg→Data Msg→DataSize Msg→RouteData (if header type is E0) Msg→Reason (on SMMTP_DISCONNECTION only) Timeout
Version: 1.0

In

Out

Int

Maximum delay to receive a message. If equal to INFINITE, the function blocks until a
Page 85 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

message is received. Return Code: Data Type Int Value SMMTP_OK SMMTP_NO_MESSAGE SMMTP_DISCONNECTION Description If a message is received from the server. If no message is received. If a disconnection request is received. In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection. Error code When other problems occur. Refer to errors returned by the SMMTPErrorDescription function.

G.6 SMMTPGetSync
extern int SMMTPGetSync( SMMTPHANDLE Handle, SMMTPMsg *Msg );

Description:
Sends to the SMMTP library the Message ID of the last message processed by the client application. This function allows the SMMTP library to send automatic synchronization messages between the client application and the CAP or the Bx Connect Server. This function can be called in a SMMTP_IN session only. The client application should call this function whenever it finishes processing the data contained in a message.

Arguments:
Parameter Handle Msg Type SMMTPHANDLE SMMTPMsg * Description A SMMTPHANDLE obtained with the SMMTPConnect function. A pointer to a SMMTPMsg structure. The client application must provide the following field:
• Msg→MsgId (Message ID of the last message

In

Out

processed by the client application) The function returns the following field:
• Msg→Reason (on

SMMTP_DISCONNECTION only)

Version: 1.0

Page 86 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int Value SMMTP_OK SMMTP_DISCONNECTION Description If synchronization is successful. If a disconnection request is received. In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection. Error code When other problems occur. Refer to errors returned by the SMMTPErrorDescription function.

G.7 SMMTPPut
extern int SMMTPPut( SMMTPHANDLE Handle, SMMTPMsg *Msg int Timeout );

Description:
Sends a message to the Bx Connect Server. This function can be called in a SMMTP_OUT session only.

Arguments:
Parameter Handle Message Type SMMTPHANDLE SMMTPMsg * Description A SMMTPHANDLE obtained with the SMMTPConnect function. A pointer to a SMMTPMsg structure that contains the message to send. The client application must provide the following fields: Msg→MsgId Msg→Data Msg→DataSize Msg→RouteData Msg→OnMember (for MAPI usage only) The function returns the following field: Msg→Reason (on SMMTP_DISCONNECTION only) Timeout
Version: 1.0

In

Out

Int

Maximum delay to send the message.
Page 87 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Parameter

Type

Description If equal to INFINITE, the function blocks until a message is sent.

In

Out

Return Code:
Data Type Int Value SMMTP_OK SMMTP_DISCONNECTION Description If the message is sent successfully. If a disconnection request is received. In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection.. Error code When other problems occur. Refer to errors returned by the SMMTPErrorDescription function.

G.8 SMMTPPutSync
extern int SMMTPPutSync( SMMTPHANDLE Handle, SMMTPMsg *Msg );

Description:
Returns the last Message ID processed by the Bx Connect Server. This function allows the SMMTP library to send automatic synchronization messages between the client application and the Bx Connect Server. This function can be called in a SMMTP_OUT session only. The client application can use this function to determine the last message processed by the Bx Connect server.

Arguments:
Parameter Handle Msg Type SMMTPHANDLE SMMTPMsg * Description A SMMTPHANDLE obtained with the SMMTPConnect function. A pointer to a SMMTPMsg structure. The function returns the following fields: Msg→MsgId (last Message ID processed by the Bx Connect Server) Msg→Reason (on SMMTP_DISCONNECTION only) In Out

Version: 1.0

Page 88 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Return Code:
Data Type Int SMMTP_OK SMMTP_DISCONNECTION Value Description If the synchronization is successful. If a disconnection request is received. In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection.. Error code When other problems occur. Refer to errors returned by the SMMTPErrorDescription function.

G.9 SMMTPErrorDescription
extern const char * SMMTPErrorDescription( int Error );

Description:
Returns a descriptive text of a SMMTP error code.

Arguments:
Parameter Error Return Code: Data Type char * 0 1 2 3 4 5 6 Error Code Value SMMTP_OK SMMTP_NOT_CONNECTED SMMTP_INVALID_ADDRESS SMMTP_CNX_LOST SMMTP_NO_MESSAGE SMMTP_INVALID_ARG SMMTP_CLIENT_FCT Error text returned No error. Logical established. connection not Int Type Error code. Description In Out

Invalid IP address. Physical connection lost. No message received. Invalid argument. Session open in server mode and the requested function is reserved for sessions open in client mode. Session opened in client mode and the requested function is reserved for sessions opened in server mode. Invalid session.
March, 2006

7

SMMTP_SERVER_FCT

8
Version: 1.0

SMMTP_INVALID_SESSION
Page 89 of 116

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Data Type 9 10 11 12 13 14 15 16 17 18 19 20 21

Error Code Value SMMTP_ALREADY_IN_PROGRESS SMMTP_ALREADY_CONNECTED SMMTP_ALREADY_INITIALIZED SMMTP_NOT_INITIALIZED SMMTP_CRYPT_ERROR SMMTP_CANNOT_INIT_SOCKET SMMTP_NOT_ENOUGH_MEMORY SMMTP_TOO_MUCH_SESSIONS SMMTP_CANNOT_OPEN_LOGFILE SMMTP_LOGFILE_NOT_OPENED SMMTP_SOCKET_FULL SMMTP_SOCKET_ERROR SMMTP_BUFFER_FULL

Error text returned A message of the same type is still awaiting acceptance. Logical connection established. Library already initialized. Library not initialized. Encryption/decryption error. Unable to open socket. Insufficient memory. Maximum number of sessions opened. Impossible to open the protocol transfer log file. Protocol transfer log file not opened. Socket full. Socket system error. Write buffer full. Use MMTPWriteTerminate empty it. to already

22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
Version: 1.0

SMMTP_NOT_IN_PROGRESS SMMTP_TOO_MUCH_LISTEN_PORTS SMMTP_ENCRYPTION_UNAVAILABLE SMMTP_INVALID_ENCRYPTION_LIB SMMTP_SYSTEM_EXCEPTION SMMTP_SYSTEM_ERROR SMMTP_BAD_KEY SMMTP_INVALID_ARG1 SMMTP_INVALID_ARG2 SMMTP_INVALID_ARG3 SMMTP_INVALID_ARG4 SMMTP_INVALID_ARG5 SMMTP_INVALID_ARG6 SMMTP_INVALID_ARG7 SMMTP_INVALID_ARG8
Page 90 of 116

Pending action to be interrupted does not exist. Too many listening ports open. Encryption feature not available. Encryption library invalid. System exception trapped. System error. Bad encryption/decryption key. The first argument is invalid. The second argument is invalid. The third argument is invalid. The fourth argument is invalid. The fifth argument is invalid. The sixth argument is invalid. The seventh argument is invalid. The eighth argument is invalid.
March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

Data Type 37 38 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115

Error Code Value SMMTP_INVALID_ARG9 SMMTP_NO_KEY_DEFINED SMMTP_BAD_USER_OR_PWD SMMTP_UNEXPECTED_MSG SMMTP_ACCESS_DENIED SMMTP_SERVER_UNREADY SMMTP_LAST_CNX_TOO_RECENT SMMTP_INCOMPATIBLE_LIBRARIES SMMTP_INVALID_CNX_OPTIONS SMMTP_UNKNOWN_MMTP_ERROR SMMTP_MMTP_PROTOCOL_ERROR SMMTP_INVALID_MSGID SMMTP_OUT_FUNCTION SMMTP_IN_FUNCTION SMMTP_DISCONNECTION SMMTP_SYNC_DISABLED SMMTP_WAITING_SYNCACK SMMTP_NO_SERVER_RESPONSE

Error text returned The ninth argument is invalid. No key is defined. Invalid user or password. An unexpected message has been received. The server denies the connection. The server is not ready. The last attempt to establish the connection is too recent. The MMTP libraries incompatible between them. are

The connection options used are invalid. SMMTP received an unknown MMTP error code. An MMTP protocol error has occurred. The MsgId given is unknown. This function is for SMMTP_OUT sessions only. This function is for SMMTP_IN sessions only. The server sent a disconnection message. The sync process is disabled. Waiting for acknowledgement. No server response. a sync

Version: 1.0

Page 91 of 116

March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

H. Sample Programs
This appendix provides sample code illustrating how to use the MMTP API. These include:
• •

a sample receiver program a sample sender program

H.1

Sample - receiver

#ifdef NT #include <windows.h> #endif #include <stdio.h> #include <stdlib.h> #include <string.h> #if defined(AIX) || defined(SUNOS) || defined(UNIX_SV) || defined(HPUX) #include <time.h> #include <signal.h> #include <sys/types.h> #include <sys/time.h> typedef int BOOL; #define TRUE 1 #define FALSE 0 #endif #include "libpga.h" static char* Receiver_c_Rev="@(#) $Name: $ $Header: /home/dev/cvsroot/DTM/Member Gateway/mmtp_sdk/receiver/receiver.c,v 1.3 1999/06/08 11:34:33 jlv Exp $"; // Constants. // ---------#define REPLY_TIMEOUT 10000 #define LOOP_DELAY 100 // Global variables prototypes. // ---------------------------// Handle of the MMTP session. MMTPSESSION Session; // Next sequence number received by the server. int NextSeqNb=0; // Must quit the program ? BOOL Quit=TRUE; // Handle of the input file. FILE* OutputFile=NULL; // Tcp port of the server. short TcpPort; // Address IP of the server. char IpAddr[50]; // User name. Version: 1.0 Page 92 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

char User[50]; // Password of the user. char Password[50]; // Reason of the disconnection request. int DcnxReason=3; // Last message id received. char LastMsgId[FIELD_SIZE_MSGID+1]; // Next sequence number where we must send a SYNC-REQ. //static int SyncSeqNb; // Static functions prototypes. // ---------------------------BOOL EstablishConnection(void); void ProcessConnectionAccept(MMTPConxAck* ConxAck); void ProcessConnectionDeny(MMTPConxNack* ConxNack); void ProcessDataMessage(MMTPMsg* Msg); #ifdef NT BOOL WINAPI ControlHandler(DWORD Signal); #define WaitMs(x) Sleep(x) #elif defined(AIX) || defined(SUNOS) || defined(UNIX_SV) || defined(HPUX) void ControlHandler(int Signal); void WaitMs(unsigned long MilliSeconds); #endif int main(int argc,char** argv) { int rc; MMTPMsg Msg; BOOL MustWait; char* OpenOption; if(argc<6) { puts("Missing parameter(s)"); puts("Syntax : Receiver <Port> <IpAddr> <User> <Password> <Output file> [Last MsgId]"); return(1); } if(argc==7) { strcpy(LastMsgId,argv[6]); OpenOption="a"; } else { LastMsgId[0]=0; OpenOption="w"; } // Catch interrupt signals #ifdef NT SetConsoleCtrlHandler(ControlHandler,TRUE); #elif defined(AIX) || defined(SUNOS) || defined(UNIX_SV) || defined(HPUX) signal(SIGQUIT,ControlHandler); signal(SIGKILL,ControlHandler); signal(SIGTERM,ControlHandler); signal(SIGINT,ControlHandler); #endif TcpPort=(short)atoi(argv[1]); strcpy(IpAddr,argv[2]); strcpy(User,argv[3]); Version: 1.0 Page 93 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

strcpy(Password,argv[4]); // Open the input file. OutputFile=fopen(argv[5],OpenOption); if(OutputFile!=NULL) { // Initialize the MMTP library (for one session only). rc=MMTPInitialize(1); if(rc==MMTP_OK) { // Create the session. rc=MMTPCreateSession(NULL,NULL,&Session); if(rc==MMTP_OK) { Quit=FALSE; } else { printf( "Error in MMTPCreateSession : %d - %s\n",rc,MMTPErrorDescription(rc)); } } else { printf("Error in MMTPInitialize : %d - %s\n",rc,MMTPErrorDescription(rc)); } } else { printf("Cannot create the %s output file\n",argv[5]); } while(Quit==FALSE || MMTPCheckLogicalConnection(Session)==TRUE) { MustWait=TRUE; // If the physical connection is established or // the attempt to establish it successed. if(MMTPCheckPhysicalConnection(Session)==TRUE || EstablishConnection()==TRUE) { // If a connection request has been sent and reply timeout expired. if(MMTPCheckConnectionRequest(Session)>REPLY_TIMEOUT) { puts("Timeout in connection request."); // Cancel the connection request and close the session. MMTPCancelConnectionRequest(Session); MustWait=FALSE; } // If a disconnection request has been sent and reply timeout expired. else if(MMTPCheckDisconnectionRequest(Session)>REPLY_TIMEOUT) { puts("Timeout in disconnection request."); // Cancel the disconnection request and close the session. MMTPCancelDisconnectionRequest(Session); MustWait=FALSE; } else if(MMTPTerminateWrite(Session)==MMTP_OK) { // If the program must stop. if(Quit==TRUE && Version: 1.0 Page 94 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

MMTPCheckDisconnectionRequest(Session)==-1) { puts("Send disconnection request."); MMTPDisconnectionRequest(Session,DcnxReason,NextSeqNb); MustWait=FALSE; } else { // Look if a message is received. rc=MMTPReceiveMessage(Session,100,&Msg); // Process the return code. switch(rc) { // If a message has been received. case MMTP_OK: MustWait=FALSE; // Process the type of the received message. switch(Msg.Type) { // The connection request is accepted. case CONX_ACK: ProcessConnectionAccept(&Msg.Data.ConxAck); break; // The connection request is denied. case CONX_NACK: ProcessConnectionDeny(&Msg.Data.ConxNack); break; // Start request accepted. case START_ACK: printf( "Start request accepted (SeqNb %d).\n", Msg.Data.StartAck.SeqNb); NextSeqNb=Msg.Data.StartAck.SeqNb; break; // Start request denied. case START_NACK: printf( "Start request denied (reason %d). Program stopped\n", Msg.Data.StartNack.Reason); Quit=TRUE; break; // Disconnection request. case DCNX_REQ: printf("Disconnection request received\n"); MMTPAcceptDisconnection(Session,NextSeqNb); break; case DCNX_ACK: printf("Disconnection request accepted\n"); break; // Service message. case SRVC_MSG: if(!strcmp(Msg.Data.SrvcMsg.Type,"PING")) { MMTPSendServiceMessage( Session,"PONG", Msg.Data.SrvcMsg.Size,Msg.Data.SrvcMsg.Data); } Version: 1.0 Page 95 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

else { printf( "The %s service message received is unknown.", Msg.Data.SrvcMsg.Type); } break; case DATA_MSG: ProcessDataMessage(&Msg); break; case SYNC_REQ: puts("Sync request received."); MMTPAcceptSync(Session,NextSeqNb-1,LastMsgId); break; // Other message. default: printf( "%s message received and ignored\n", MMTPObtainPrimitiveName(Msg.Type)); } break; // The physical connection is lost. case MMTP_CNX_LOST: puts("Physical connection lost"); break; // No message received. case MMTP_NO_MESSAGE: break; // Other return code. default: printf( "Error in MMTPReceiveMessage : %d - %s\n", rc,MMTPErrorDescription(rc)); } } } } if(MustWait==TRUE) { WaitMs(LOOP_DELAY); } } if(MMTPCheckHandle(Session)==TRUE) { MMTPDeleteSession(Session); } MMTPTerminate(); if(OutputFile!=NULL) { fclose(OutputFile); } return(0); } Version: 1.0 Page 96 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

BOOL EstablishConnection() { int rc; // If the physical connection is not established. if(MMTPCheckPhysicalConnection(Session)==FALSE) { // Try to physically connect the session to the server. rc=MMTPOpenClientSession(Session,TcpPort,IpAddr,1); // If the physical connection is established. if(rc==MMTP_OK) { puts("Physical connection established"); // Send a connection request. puts("Sending connection request"); rc=MMTPConnectionRequest(Session,User,"0000000000000000",Password); if(rc==MMTP_OK) { return(TRUE); } printf( "Error in MMTPConnectionRequest : %d - %s\n", rc,MMTPErrorDescription(rc)); Quit=TRUE; } else { if(rc!=MMTP_NOT_CONNECTED) { printf( "Error in MMTPOpenClientSession: %d - %s\n", rc,MMTPErrorDescription(rc)); Quit=TRUE; } } } return(FALSE); } void ProcessConnectionDeny(MMTPConxNack* ConxNack) { printf("Connection request refused (reason %d).\n",ConxNack->Reason); if(ConxNack->Reason==1 || ConxNack->Reason==3) { MMTPCloseSession(Session); Quit=TRUE; } else { WaitMs(2000); } } void ProcessConnectionAccept(MMTPConxAck* ConxAck) { puts("Connection request accepted."); printf( "Send a start request (MsgId %s)\n", (LastMsgId[0]==0 ? "empty" : LastMsgId)); Version: 1.0 Page 97 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

MMTPStartRequest(Session,LastMsgId); } void ProcessDataMessage(MMTPMsg* Msg) { MMTPDataMsg* DataMsg=&Msg->Data.DataMsg; // For simplify the sample, we just store the message id // in memory. In a real application, it is necessary to // store it in a file or a database. strcpy(LastMsgId,DataMsg->AD.Data.Generic.MsgId); printf( "Data message received (SeqNb %d, MsgId %s)\n",DataMsg->SeqNb,LastMsgId); // If the message has already been received, close the session if(DataMsg->SeqNb<NextSeqNb) { puts("Sequence number already received."); MMTPSendError(Session,2,0,NextSeqNb,Msg); MMTPCloseSession(Session); Quit=TRUE; } // If the sequence number of the message is not the one we are // waiting for, we close the session. else if(DataMsg->SeqNb!=NextSeqNb) { puts("Break in sequence number."); MMTPSendError(Session,1,1,NextSeqNb,Msg); MMTPCloseSession(Session); Quit=TRUE; } // The sequence number of the message is the good one. else { NextSeqNb++; fprintf(OutputFile,"%s\n",DataMsg->Data); fflush(OutputFile); } } #ifdef NT BOOL WINAPI ControlHandler(DWORD Signal) { if(Signal==CTRL_BREAK_EVENT || Signal==CTRL_C_EVENT || Signal==CTRL_CLOSE_EVENT) { Quit=TRUE; DcnxReason=1; return(TRUE); } return(FALSE); } #elif defined(AIX) || defined(SUNOS) || defined(UNIX_SV) || defined(HPUX) void WaitMs(unsigned long MilliSeconds) { struct timeval t={ MilliSeconds/1000, (MilliSeconds%1000)*1000 }; Version: 1.0 Page 98 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

select(0,NULL,NULL,NULL,&t); } void ControlHandler(int Signal) { Quit=TRUE; DcnxReason=1; } #endif

H.2

Sample – sender

#ifdef NT #include <windows.h> #endif #include #include #include #include <stdio.h> <stdlib.h> <string.h> <time.h>

#if defined(AIX) || defined(SUNOS) || defined(UNIX_SV) || defined(HPUX) #ifndef UNIX #define UNIX #endif #include <signal.h> #include <sys/types.h> #include <sys/time.h> typedef int BOOL; #define TRUE 1 #define FALSE 0 #endif #include "libpga.h" static char* Sender_c_Rev _UNUSED_="@(#) $Name: $ $Header: /home/dev/cvsroot/DTM/Member Gateway/mmtp_sdk/sender/sender.c,v 1.4 1999/07/01 15:44:48 fred Exp $"; // Constants. // ---------#define REPLY_TIMEOUT 10000 #define LOOP_DELAY 100 #define WINDOW_SIZE 50 // Global variables prototypes. // ---------------------------// Handle of the MMTP session. MMTPSESSION Session; // Last sequence number sent to the server. int LastSeqNb=0; // Indicate if a Ctrl+C keystroke has been received. static BOOL Interrupt=FALSE; // Must quit the program ? BOOL Quit=TRUE; // Last message id sent to the server. char LastMsgIdSent[FIELD_SIZE_MSGID+1]; Version: 1.0 Page 99 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

// Handle of the input file. FILE* InputFile=NULL; // Tcp port of the server. short TcpPort; // IP Address of the server. char IpAddr[50]; // User name. char User[50]; // Password of the user. char Password[50]; // Last sequence number which can be sent without receipt of SYNC-ACK. static int LimitSeqNb; // Next sequence number where we must send a SYNC-REQ. static int SyncSeqNb; // Static functions prototypes. // ---------------------------static BOOL ConnectServer(void); static void DisconnectServer(MMTPDcnxRsn Reason); static BOOL ReceiveServerMessage(void); static void ProcessStartRequest(MMTPStartReq* StartReq); static void ProcessSyncAcknowledgment(MMTPMsg* Msg); static void ProcessServiceMessage(MMTPSrvcMsg* SrvcMsg); static BOOL SendMessageToServer(void); static int ProcessMmtpError(int Error); static void RemoveCrLf(char* Str); #ifdef NT BOOL WINAPI ControlHandler(DWORD Signal); #define WaitMs(x) Sleep(x) #elif defined(UNIX) void ControlHandler(int Signal); void WaitMs(unsigned long MilliSeconds); #endif /******************************************************************************* * int main(int argc,char** argv) * * Description * Main function of the program. * * Parameters * argc * Number of parameters * * argv * Parameters of the program. * * Return code * Always 0. *******************************************************************************/ int main(int argc,char** argv) { int rc; BOOL MustWait; if(argc!=6) { puts("Missing parameter(s)"); puts("Syntax : Sender <Port> <IpAddr> <User> <Password> <Input file>"); return(0); } // Catch interrupt signals Version: 1.0 Page 100 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

#ifdef NT SetConsoleCtrlHandler(ControlHandler,TRUE); #elif defined(UNIX) signal(SIGQUIT,ControlHandler); signal(SIGKILL,ControlHandler); signal(SIGTERM,ControlHandler); signal(SIGINT,ControlHandler); #endif TcpPort=(short)atoi(argv[1]); strcpy(IpAddr,argv[2]); strcpy(User,argv[3]); strcpy(Password,argv[4]); // Open the input file. InputFile=fopen(argv[5],"r+"); if(InputFile!=NULL) { // Initialize the MMTP library (for one session only). rc=MMTPInitialize(1); if(rc==MMTP_OK) { // Create the session. rc=MMTPCreateSession(NULL,NULL,&Session); if(rc==MMTP_OK) { Quit=FALSE; } // Error during create session. else { printf( "Error in MMTPCreateSession : %d - %s\n",rc,MMTPErrorDescription(rc)); } } // Error during MMTP library initialization. else { printf("Error in MMTPInitialize : %d - %s\n",rc,MMTPErrorDescription(rc)); } } // Error during accessing input file. else { printf("Cannot access to the %s input file\n",argv[5]); } // While the end is not asked or the logical connection exists. while(Quit==FALSE || MMTPCheckLogicalConnection(Session)==TRUE) { MustWait=FALSE; if(Interrupt==TRUE) { printf("Program interrupted by signal\n"); DisconnectServer(MMTPDcnxRsn_Normal); Interrupt=FALSE; } // If the logical connection with the server is not established. if(MMTPCheckPhysicalConnection(Session)==FALSE) { if(Quit==FALSE) Version: 1.0 Page 101 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

{ if(ConnectServer()==FALSE) { MustWait=TRUE; } } } else { rc=MMTPTerminateWrite(Session); if(rc==MMTP_OK) { if(ReceiveServerMessage()==FALSE) { if(MMTPWaitForStartRequest(Session)==TRUE || SendMessageToServer()==FALSE) { MustWait=TRUE; } } } else if(rc!=MMTP_BUFFER_FULL) { ProcessMmtpError(rc); WaitMs(10); } } if(MustWait==TRUE) { WaitMs(LOOP_DELAY); } } // Delete the session if its handle is valid. if(MMTPCheckHandle(Session)==TRUE) { MMTPDeleteSession(Session); } // Close the library. MMTPTerminate(); // Close the file, if opened. if(InputFile!=NULL) { fclose(InputFile); } return(0); } /******************************************************************************* * BOOL ConnectServer() * * Description * Try to establish physical connection with the server. * * Parameters * None * * Return code * TRUE if the physical connection is established. Otherwise FALSE. *******************************************************************************/ Version: 1.0 Page 102 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

static BOOL ConnectServer() { int rc; printf("Try to establish the physical connection with the server\n"); // Try to establish physical connection with the server. rc=MMTPOpenClientSession(Session,TcpPort,IpAddr,0); if(rc==MMTP_OK) { printf("Physical connection with the server established\n"); return(TRUE); } if(rc!=MMTP_NOT_CONNECTED) { ProcessMmtpError(rc); } return(FALSE); } /******************************************************************************* * void DisconnectServer(MMTPDcnxRsn Reason) * * Description * Closes the connection with the server. Sends a disconnection request if the * logical connection with the server is established. * * Parameter * Reason * The reason code of the disconnection. * * Return code * None *******************************************************************************/ static void DisconnectServer(MMTPDcnxRsn Reason) { Quit=TRUE; if(MMTPCheckLogicalConnection(Session)==TRUE && MMTPTerminateWrite(Session)==MMTP_OK) { printf( "Send disconnection request to the server (reason %d, SeqNb %d)\n", Reason,LastSeqNb); ProcessMmtpError(MMTPDisconnectionRequest(Session,Reason,LastSeqNb)); return; } if(MMTPCheckPhysicalConnection(Session)==TRUE) { printf("Physical connection with server is closed\n"); ProcessMmtpError(MMTPCloseSession(Session)); } } /******************************************************************************* * BOOL ReceiveServerMessage() * * Description * Receives messages from the server and processes them. * Version: 1.0 Page 103 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

* Parameter * Reason * The reason code of the disconnection. * * Return code * TRUE if a message has been received, FALSE otherwise. *******************************************************************************/ static BOOL ReceiveServerMessage() { int rc; int Duration; MMTPMsg Msg; // If the logical connection with the server is not established. if(MMTPCheckLogicalConnection(Session)==FALSE) { // Get the time passed since the sending of the connection request. Duration=MMTPCheckConnectionRequest(Session); // If no connection request has been sent, sends one. if(Duration==-1) { printf("Sends a connection request.\n"); ProcessMmtpError( MMTPConnectionRequest(Session,User,"0000000000000000",Password)); } // If timeout, Cancels the connection request. else if(Duration>REPLY_TIMEOUT) { printf("Timeout on connection request. Cancels it.\n"); ProcessMmtpError(MMTPCancelConnectionRequest(Session)); Quit=TRUE; return(TRUE); } } if(MMTPCheckDisconnectionRequest(Session)>REPLY_TIMEOUT) { printf("Timeout on connection request. Cancels it.\n"); ProcessMmtpError(MMTPCancelDisconnectionRequest(Session)); return(TRUE); } // Look if a message is received. rc=MMTPReceiveMessage(Session,0,&Msg); // Process the return code. switch(rc) { // If a message has been received. case MMTP_OK: // Process the type of the received message. switch(Msg.Type) { // The connection request is accepted. case CONX_ACK: printf("Connection request accepted\n"); break; // The connection request is denied. case CONX_NACK: printf( "Connection request denied (reason %d)\n",Msg.Data.ConxNack.Reason); MMTPCloseSession(Session); Quit=TRUE; break; Version: 1.0 Page 104 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

// Disconnection request. case DCNX_REQ: printf( "Disconnection request received (SeqNb %d)\n", Msg.Data.DcnxReq.SeqNb); MMTPAcceptDisconnection(Session,LastSeqNb); Quit=TRUE; break; // The disconnection request is accepted. case DCNX_ACK: printf( "Disconnection request accepted (SeqNb %d)\n", Msg.Data.DcnxAck.SeqNb); break; // Start request. case START_REQ: ProcessStartRequest(&Msg.Data.StartReq); break; // Sync accept received. case SYNC_ACK: ProcessSyncAcknowledgment(&Msg); break; // Service message. case SRVC_MSG: ProcessServiceMessage(&Msg.Data.SrvcMsg); break; // Sync request. case DATA_MSG: ProcessMmtpError(MMTPAcceptSync(Session,0,"")); break; // Other message. default: printf( "%s message received and ignored\n", MMTPObtainPrimitiveName(Msg.Type)); } break; // The physical connection is lost. case MMTP_CNX_LOST: printf("Physical connection lost\n"); break; // No message received. case MMTP_NO_MESSAGE: return(FALSE); // Other return code. default: ProcessMmtpError(rc); } return(TRUE); } /******************************************************************************* * void ProcessStartRequest(MMTPStartReq* StartReq) Version: 1.0 Page 105 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

* * Description * Processes a start request message received from the server. * Accept or denied it according to the validity of the MsgId of the message. * * Parameter * StartReq * The received start request. * * Return code * None *******************************************************************************/ static void ProcessStartRequest(MMTPStartReq* StartReq) { int i; int len; char Buffer[FIELD_SIZE_DATA+1]; char* MsgId=StartReq->MsgId; int LineNumber; printf("Start request received (MsgId <%s>)\n",MsgId); len=strlen(MsgId); if(len!=0 && len!=6) { printf(" MsgId <%s> has invalid length\n",MsgId); ProcessMmtpError(MMTPDenyStart(Session,MMTPStrtNckRsn_MsgIdNotFound,MsgId)); } else { for(i=0;i<len;i++) { if(MsgId[i]<'0' || MsgId[i]>'9') { printf(" MsgId <%s> contains invalid caracters\n",MsgId); ProcessMmtpError( MMTPDenyStart(Session,MMTPStrtNckRsn_MsgIdNotFound,MsgId)); return; } } // Fetch the number of the last line received by the server. LineNumber=atoi(MsgId); strcpy(LastMsgIdSent,MsgId); // Go to the begining of the file. fseek(InputFile,SEEK_SET,0); // Put the file pointer on the right line. for(i=0;i<LineNumber;i++) { if(fgets(Buffer,sizeof(Buffer),InputFile)==NULL) { printf(" MsgId <%s> cannot be found\n",MsgId); ProcessMmtpError( MMTPDenyStart(Session,MMTPStrtNckRsn_MsgIdNotFound,MsgId)); return; } } // Compute the sequence numbers in relation with the sync request. LimitSeqNb=WINDOW_SIZE; SyncSeqNb=WINDOW_SIZE/2; LastSeqNb=0; Version: 1.0 Page 106 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

MMTPAcceptStart(Session,1,MsgId); } } /******************************************************************************* * void ProcessSyncAcknowledgment(MMTPMsg* Msg) * * Description * Processes a sync acknowledgment message received from the server. * Send an error to the server if the sequence number given in the message is * invalid. Resends a sync request if the sequence numbre given in th message * is too small. * * Parameter * Msg * Message received from the server. * * Return code * None *******************************************************************************/ static void ProcessSyncAcknowledgment(MMTPMsg* Msg) { printf("Sync acknowledgment received (SeqNb %d)\n",Msg->Data.SyncAck.SeqNb); // If the sequence number given in the mzssage is invalid, // send an error and close the session. if(Msg->Data.SyncAck.SeqNb>SyncSeqNb) { printf("The SeqNb of the Sync acknowledgment is invalid\n"); ProcessMmtpError( MMTPSendError(Session,MMTPErrIndErr_InvalidField,3,LastSeqNb,Msg)); ProcessMmtpError(MMTPCloseSession(Session)); Quit=TRUE; } // The sequence number given is valid. else { // If it is too small, we send another sync request. if(Msg->Data.SyncAck.SeqNb+WINDOW_SIZE<=LimitSeqNb) { ProcessMmtpError(MMTPSyncRequest(Session)); } // Otherwise, compute the new sequence number in relation with the sync. else { SyncSeqNb=Msg->Data.SyncAck.SeqNb+WINDOW_SIZE; LimitSeqNb=SyncSeqNb+WINDOW_SIZE/2; } } } /******************************************************************************* * void ProcessServiceMessage(MMTPSrvcMsg* SrvcMsg) * * Description * Processes a sservice message received from the server. * Sends a PONG service message if the service message received is a PING. * Ignores any other service messages. * * Parameter * SrvcMsg * Service message received from the server. * * Return code Version: 1.0 Page 107 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

* None *******************************************************************************/ static void ProcessServiceMessage(MMTPSrvcMsg* SrvcMsg) { // if the service message is PING, reply a PONG. if(!strcmp(SrvcMsg->Type,"PING")) { MMTPSendServiceMessage(Session,"PONG",SrvcMsg->Size,SrvcMsg->Data); } // else, ignored the message. else { printf("The %s service message received is unknown\n",SrvcMsg->Type); } } /******************************************************************************* * BOOL SendMessageToServer() * * Description * Sends the next line of the file to the server. If the end of the file is * reached, sends a disconnection request. * * Parameter * None * * Return code * TRUE if a message has been sent. Otherwise FALSE. *******************************************************************************/ static BOOL SendMessageToServer() { char Buffer[FIELD_SIZE_DATA+1]; MMTPAdminData AdminData; int LineNumber; struct tm* tm; struct timeb tb; if(MMTPCheckDisconnectionRequest(Session)!=-1) { return(FALSE); } // If a start request has been received. if(LastSeqNb==SyncSeqNb && MMTPCheckSyncRequest(Session)==-1) { printf("Send sync request on %d sequence number.\n",SyncSeqNb); ProcessMmtpError(MMTPSyncRequest(Session)); return(TRUE); } // Get the next line of the file. if(fgets(Buffer,sizeof(Buffer),InputFile)==NULL) { printf("End of file reached\n"); DisconnectServer(MMTPDcnxRsn_LastMsgSent); return(TRUE); } LineNumber=atoi(LastMsgIdSent)+1; sprintf(LastMsgIdSent,"%06d",LineNumber);; LastSeqNb++; printf("Sending line %d (SeqNb %d)\n",LineNumber,LastSeqNb); Version: 1.0 Page 108 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

// Construct the administration data of the message. AdminData.Type=ADMIN_DATA_E0; strcpy(AdminData.Data.E0.MsgId,LastMsgIdSent); ftime(&tb); tm=localtime(&tb.time); sprintf( AdminData.Data.E0.SendTime,"%02d%02d%02d%02d%02d%02d", tm->tm_mon,tm->tm_mday,tm->tm_hour,tm->tm_min,tm->tm_sec,tb.millitm/10); AdminData.Data.E0.ReceiptTime[0]=0; AdminData.Data.E0.DeliveryTimeOut[0]=0; AdminData.Data.E0.RouteData[0]=0; AdminData.Data.E0.Filler[0]=0; RemoveCrLf(Buffer); // Send the message. ProcessMmtpError(MMTPSendMessage(Session,LastSeqNb,&AdminData,0,Buffer)); // Not useful. just permits ctrl+C. WaitMs(100); return(TRUE); } /******************************************************************************* * int ProcessMmtpError(int Error) * * Description * Process MMTP return codes. * * Parameters * Error * Return code to process. * * Return code * The return code given in parameter. *******************************************************************************/ int ProcessMmtpError(int Error) { switch(Error) { case MMTP_OK: case MMTP_NO_MESSAGE: break; case MMTP_CNX_LOST: printf("MMTP physical connection lost\n"); break; case MMTP_NOT_CONNECTED: printf("MMTP logical connection not established\n"); break; case MMTP_BUFFER_FULL: printf("Warning : the server socket is full\n"); break; case case case case case Version: 1.0 MMTP_CANNOT_INIT_SOCKET: MMTP_NOT_ENOUGH_MEMORY: MMTP_TOO_MUCH_SESSIONS: MMTP_SOCKET_ERROR: MMTP_INVALID_ADDRESS: Page 109 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

case MMTP_INVALID_ARG: case MMTP_INVALID_ARG1: case MMTP_INVALID_ARG2: case MMTP_INVALID_ARG3: case MMTP_INVALID_ARG4: case MMTP_INVALID_ARG5: case MMTP_INVALID_ARG6: case MMTP_INVALID_ARG7: case MMTP_INVALID_ARG8: case MMTP_INVALID_ARG9: case MMTP_CLIENT_FCT: case MMTP_SERVER_FCT: case MMTP_INVALID_SESSION: case MMTP_NOT_INITIALIZED: case MMTP_SYSTEM_EXCEPTION: printf( "Fatal error in MMTP connection : %d - %s\n", Error,MMTPErrorDescription(Error)); DisconnectServer(MMTPDcnxRsn_Abnormal); Quit=TRUE; break; default: printf( "Error in MMTP connection : %d - %s\n", Error,MMTPErrorDescription(Error)); } return(Error); } /******************************************************************************* * void RemoveCrLf(char* Str) * * Description * Removes carriage return and line feed at the end of a string. * * Parameters * Str * String to be modified. * * Return code * None *******************************************************************************/ static void RemoveCrLf(char* Str) { int len=strlen(Str)-1; while(len>=0 && (Str[len]=='\n' || Str[len]=='\r')) { Str[len]=0; len--; } } #ifdef NT BOOL WINAPI ControlHandler(DWORD Signal) { if(Signal==CTRL_BREAK_EVENT || Signal==CTRL_C_EVENT || Signal==CTRL_CLOSE_EVENT) { Interrupt=TRUE; Version: 1.0 Page 110 of 116 March, 2006

Boston Equities Exchange 

BeX Connectivy Process MMTP API Developer’s Guide

return(TRUE); } return(FALSE); } #elif defined(UNIX) void ControlHandler(int Signal) { Interrupt=TRUE; } void WaitMs(unsigned long MilliSeconds) { struct timeval t={ MilliSeconds/1000, (MilliSeconds%1000)*1000 }; select(0,NULL,NULL,NULL,&t); } #endif

Version: 1.0

Page 111 of 116

March, 2006