bexmmtpdevelopersguide

Connectivity Process

MMTP API Developer’s Guide

Document version: 1.10

Software version: 2.14

Date: March 31, 2006

Distribution: Boston Equities Exchange,

Market Participants

Document Status: FINAL

Boston Equities Exchange BeX Connectivy Process MMTP API Developer’s Guide

Revision History

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

Version: 1.0 of 116 March, 2006


Table of Contents

1. MMTP Open Interface ......................................................................................................................4 1.1 Overview.................................................................................................................................4 1.2 Compliant Operating Systems ................................................................................................5

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

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

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

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

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



A.8 Disconnection Reason Codes...............................................................................................36

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

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

D. API (Logging Functions) ...............................................................................................................65 D.1 MMTPCloseLog ....................................................................................................................65 D.2 MMTPLogSession ................................................................................................................66 D.3 MMTPOpenLog ....................................................................................................................66 D.4 MMTPSetUserLogFct ...........................................................................................................68

E. API (Transmission Functions) ......................................................................................................69 E.1 MMTPReceiveMessage........................................................................................................69 E.2 MMTPSendMessage ............................................................................................................70 E.3 MMTPSendServiceMessage ................................................................................................73 E.4 MMTPTerminateWrite...........................................................................................................75

F. Program Highlights........................................................................................................................77

G. SMMTP (Simple MMTP) .................................................................................................................79 G.1 Overview...............................................................................................................................79



G.2 SMMTPMsg structure ...........................................................................................................80 G.3 SMMTPConnect ...................................................................................................................82 G.4 SMMTPClose........................................................................................................................84 G.5 SMMTPGet ...........................................................................................................................85 G.6 SMMTPGetSync ...................................................................................................................86 G.7 SMMTPPut ...........................................................................................................................87 G.8 SMMTPPutSync ...................................................................................................................88 G.9 SMMTPErrorDescription .......................................................................................................89

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



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


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.



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, connection/disconnection parameters, error messages, and data structures.



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

API DIRECT CLIENTAPPLICATION

OrderEntry

Application

Market DataApplication

API

MMTP

MMTP

Orders

Replies toOrders

MarketData

GATEWAY

BxCONNECT

Bx TRADE

API

Replies FromTrading System

Orders go toTrading System

Rec'v

Send

Rec'v Send

Rec'v

Market Data Market Data FromBex Trading System

Inbound and Outbound Messagesare sent via the API Client Application

and the Member Gateway

MMTP

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 exchange-maintained 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.



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



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:



Figure 2: Overview of the MMTP Protocol

API

MMTP

MMTP

MMTP

Orders

Replies toOrders

MarketData

GATEWAY

BxCONNECT MMTP

Replies FromBeX Trading System

MMTPOrders go toBeX Trading System

Rec'v

Send

Rec'v

Market Data

Client Application

MMTPDeveloper's

ToolkitAccessPoint

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



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 (CONX-REQ) 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

Number Description

CONX-REQ 10 Client connection request

CONX-ACK 11 Connection acceptance by Bx Connect

CONX-NACK 12 Connection refusal by Bx Connect

DCNX-REQ 13 Disconnection request

DCNX-ACK 14 Disconnection request acknowledgement

START-REQ 20 Transmission/retransmission request

START-ACK 21 Transmission/retransmission request acknowledgement

START-NACK 22 Transmission/retransmission request refusal

DATA-MSG 23 Data transmission

SYNC-REQ 24 Acknowledgement request by data source

SYNC-ACK 25 Acknowledgement by data receiver

ERR-IND 90 Error indication by data receiver

SRVC-MSG 93 Service message

PRSC-MSG 99 Heartbeat message



2.4 Direction of Protocol

The following table shows the direction in which each primitive is sent:

Message Primitive

Client Sends Data Client Receives Data

Direction Client Bx Connect

Bx Connect Client

Client Bx Connect

Bx Connect Client

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



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

Offset Length Type Value Comment

STX 0 1 02 Message header. Value in hexadecimals.

Primitive Length 1 4 Numeric X + Y + 6 Total length of the message including STX and ETX.

Admin Data 5 X Varies Defines the RLC message type (ie. Defines the type of message body).

Message Body 5 + X Y Varies Body of message (ie. Data fields).

EXT 5 + X + Y 1 03 Message footer. Value in hexadecimals.

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.



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.



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 • MMTPCancelSyncRequest • MMTPInitialize

• MMTPAcceptDisconnection • MMTPCloseSession • MMTPOpenClientSession

• MMTPAcceptStart • MMTPDenyConnection • MMTPDenyStart

• MMTPAcceptSync • MMTPConnectionRequest • MMTPStartRequest

• MMTPCancelConnectionRequest • MMTPCreateSession • MMTPSyncRequest

• MMTPCancelDisconnectionRequest • MMTPDeleteSession • MMTPTerminate

• MMTPCancelStartRequest • MMTPDisconnectionRequest

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.



• Manage the buffer.

The following Protocol Management functions are available:

• MMTPCheckConnectionRequest • MMTPCheckPhysicalConnection • MMTPObtainNumberSession

• MMTPCheckDisconnectionRequest • MMTPCheckStartRequest • MMTPObtainPrimitiveName

• MMTPCheckHandle • MMTPCheckSyncRequest • MMTPSendError

• MMTPCheckLogicalConnection • MMTPErrorDescription • 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



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.



Figure 3: Initializing an MMTP Session

MMTPInitialize

Client Program

Systemresources

nth session

Local allocations

nthsessions

Systemresources

1st 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.



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

Client Application

MMTPCreateSession

MMTPConnectionRequest

MMTPOpenClientSession

Get sessionhandle

Open socketconnection

Server

CONX-REQ Sender's identifier Connection parameters Sender's password

MMTPReceiveMessage

Authentication

Connection acceptedMMTPAcceptConnectionCONX-ACK

Connection deniedMMTPDenyConnectionCONX-NACK

Port numberReceiver's physical address

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


The diagram below depicts a simple send message. As shown, the sender must wait until it receives the transmission/retransmission request (START-REQ) from



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

Initialization

MMTPReceiveMessageswitch{ . . START-REQ if allowed to submit MMTPStartAccept

otherwise MMTPStartDeny . .}

Receiver

START-REQ

START-ACK

MMTPStartRequestMMTPReceiveMessageswitch{ . START-ACK . .

START-NACK }

Build session

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, de-allocate resources, and terminate the physical connection.



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

MMTPDisconnectionRequestClose logical session

Server

Acknowledge disconnectionMMTPAcceptDisconnect

DCNX-REQ

DCNX-ACK

1) Reason for disconnect2) Last sequence number received

MMTPCloseSessionTerminate logical session

MMTPDeleteSessionFree local resources

1) Break socket connection

MMTPTerminateFree all remaining

resources

In the MMTP architecture, the API client application ends sessions with the PACIn, PACOut, or PAC_RDF_MMTP at Bx Connect.



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

MMTPInitialize

End Session

MMTPCreateSession

MMTPTerminate

MMTPDeleteSession

MMTPOpenClient MMTPCloseSession

MMTPConnectionRequest MMTPDisconnectionRequest

Step 1

Step 2

Step 3

Step 4 Step 5

Step 6

Step 7

Step 8

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.



Figure 8: Process Flow for Session Handle Variation

Sender/ Receiver

Define local variablesSession handle of

PgaSession data type

1) Allocate resources for session number n

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

MMTPCreateSession 3) Create a new MMTP session handle

MMTPInitialize

If not



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



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

MMTPReceiveMessageswitch{

CONX-ACK

CONX-NACKError processing

START-REQMMTPAcceptStartGet out of loop

}

LOOP

START-ACK

START-REQ

MMTPSendMessage

MMTPAcceptConnectionCONX-ACK

MMTPStartRequest

PACIn

MMTPReceiveMessageDATA-MSGSequence numberMessage body



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

Build MMTP Session


START-ACKStore Message IDStore Sequencenumber

DCNX-REQAccept disconnection

DATA-MSGProcess message

}

START-REQ

DATA-MSG - Data content

Receiver

MMTPStartRequest

MMTPAcceptStartSTART-ACK

MMTPSendMessage

PACOut

Sequence numberMessage body

Message IDSequence number

LOOP

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



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 with the receiver using MMTPOpenClientSession.

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



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:



Figure 11: Programming Flow for Recovering Messages

Build MMTP Session


.DATA-MSG

Process messageIf sequence number <> the expected number

MMTPSendError

Close session Build new session

MMTPStartRequest.START-ACK

Store message IDStore sequence #

.}

LOOP

DATA-MSG - Data content

Receiver

MMTPStartRequest

MMTPSendMessage

PACOut

Sequence numberMessage body

ERR-IND

Last sequence # receivedLast message ID received

START-REQ

Last message ID received

START-ACK

Message IDSequence #

MMTPStartAccept

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



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 Sequence Number

Message ID

MMTPAcceptDisconnection Last received -

MMTPAcceptStart Last received Last received

MMTPAcceptSync Last received -

MMTPStartDeny - Last received

MMTPDisconnectionRequest Last received -

MMTPStartRequest - Last received

MMTPSendMessage New New

MMTPSendError Last received Last received

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:



Figure 12: MMTPSendMessage C Function

MMTPSendMessage(Session handle, Sequence number, PgaAdminData, Message length, Message)

SessionHandle

SequenceNumber MMTPAdminData Message

LengthMessage

MMTPAdminDataM0 MMTPAdminDataRR MMTPAdminDataGenericMMTPAdminDataE0

-

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:



Figure 13: Format of Incoming Messages

MMTPReceiveMessage(Session handle, Time Out, MMTPMsg)

MMTPConxReq MMTPDataMsg MMTPDcnxReq

MMTPAdminDataM0

MMTPAdminGeneric

MMTPAdminData DataSequenceNumber

DataSize

MMTPMsg

MMTPAdminDataE0

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 sub-component of the MMTPMsg.



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


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.



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



A.3 MMTPMsg

The MMTPMsg data type is used by the following functions:


• 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;



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 Codes Error Code

Value Description

0 MMTP_OK No error.



Error Code

Value Description

1 MMTP_NOT_CONNECTED Logical connection not established.

2 MMTP_INVALID_ADDRESS Invalid IP address.

3 MMTP_CNX_LOST Physical connection lost.

4 MMTP_NO_MESSAGE No message received.

5 MMTP_INVALID_ARG Invalid argument.

6 MMTP_CLIENT_FCT Session open in server mode and the requested function is reserved for sessions open in client mode.

7 MMTP_SERVER_FCT Session open in client mode and the requested function is reserved for sessions open in server mode.

8 MMTP_INVALID_SESSION Invalid session.

9 MMTP_ALREADY_IN_PROGRESS

A message of the same type is still awaiting acceptance.

10 MMTP_ALREADY_CONNECTED

Logical connection already established.

11 MMTP_ALREADY_INITIALIZED

Library already initialized.

12 MMTP_NOT_INITIALIZED Library not initialized.

13 MMTP_CRYPT_ERROR Encryption/decryption error.

14 MMTP_CANNOT_INIT_SOCKET

Unable to open socket.

15 MMTP_NOT_ENOUGH_MEMORY

Insufficient memory.

16 MMTP_TOO_MUCH_SESSIONS

Maximum number of sessions open.

17 MMTP_CANNOT_OPEN_LOGFILE

Impossible to open the protocol transfer log file.

18 MMTP_LOGFILE_NOT_OPENED

Protocol transfer log file not open.

19 MMTP_SOCKET_FULL Socket full.

20 MMTP_SOCKET_ERROR Socket system error.

21 MMTP_BUFFER_FULL Write buffer full. Use MMTPWriteTerminate to empty it.

22 MMTP_NOT_IN_PROGRESS Pending action to be interrupted does not exist.

23 MMTP_TOO_MUCH_LISTEN_PORTS

Too many listen ports open.

24 MMTP_ENCRYPTION_UNAVAILABLE

Encryption feature not available.

25 MMTP_INVALID_ENCRYPTION_LIB

Encryption library invalid.



Error Code

Value Description

26 MMTP_SYSTEM_EXCEPTION

System exception trapped.

27 MMTP_SYSTEM_ERROR System error.

28 MMTP_BAD_KEY Bad encryption/decryption key.

29 MMTP_INVALID_ARG1 The first argument is invalid.

30 MMTP_INVALID_ARG2 The second argument is invalid.

31 MMTP_INVALID_ARG3 The third argument is invalid.

32 MMTP_INVALID_ARG4 The fourth argument is invalid.

33 MMTP_INVALID_ARG5 The fifth argument is invalid.

34 MMTP_INVALID_ARG6 The sixth argument is invalid.

35 MMTP_INVALID_ARG7 The seventh argument is invalid.

36 MMTP_INVALID_ARG8 The eighth argument is invalid.

37 MMTP_INVALID_ARG9 The ninth argument is invalid.

38 MMTP_NO_KEY_DEFINED 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

Offset Indication 0 Encryption

1 Disconnection on sequence error

2 to 15 Reserved for future use

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

Description Value

01 Invalid client MMTPCnxNckRsn_InvalidMember

02 Bx Connect is not available MMTPCnxNckRsn_HubNotReady



Refusal Code

Description Value

03 Unknown client or wrong password MMTPCnxNckRsn_UnknownMember

04 Last connection too recent (retry later) MMTPCnxNckRsn_LastCnxTooRecent

05 Invalid version of MMTP Library MMTPCnxNckRsn_InvalidVersion,

06 Invalid option MMTPCnxNckRsn_InvalidOptions

07 Too many connections MMTPCnxNckRsn_TooManyCnx

A.7 Refusal Reason Codes for Transmission/Retransmission Request

A transmission/retransmission request can be refused for the following reasons:

Refusal Code

Description Value

01 START-REQ already requested but not acknowledged

MMTPStrtNckRsn_StartReqInProgress

02 No connection to Bx Connect exists MMTPStrtNckRsn_NoHubCnx,

03 Message indicated by MsgId not found MMTPStrtNckRsn_MsgIdNotFound

A.8 Disconnection Reason Codes

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

Reason Code

Description Value

01 Normal disconnection MMTPDcnxRsn_Normal

02 Bx Connect administration request for disconnection

MMTPDcnxRsn_AskedByHub

03 Abnormal disconnection MMTPDcnxRsn_Abnormal

04 Session interrupted by Bx Connect MMTPDcnxRsn_SessionBroken

05 START-ACK not received or the START-ACK MsgId does not correspond to the data requested in the START-REQ

MMTPDcnxRsn_InvalidStartAck�

06 No more messages to be delivered MMTPDcnxRsn_LastMsgSent

07 Bad encryption/decryption key MMTPDcnxRsn_InvalidKey

08 Admin data is invalid MMTPDcnxRsn_InvalidAdminData

09 Access control list violation MMTPDcnxRsn_AclViolation



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 Description Input Output Input/ Output

MMTPSESSION Session handle

Return Code:

Data Type Value Description Long Time in

milliseconds The time in milliseconds since the last connection request was sent.

-1 If no connection request is in progress or session is invalid or not connected.



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:





Return Code:


milliseconds The time in milliseconds since the last disconnection request was sent.

-1 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:


MMTPSESSION session handle

Return Code:

Data Type Value Description Boolean TRUE If the session handle is valid

FALSE If the session is invalid or not recognized

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:





Return Code:

Data Type Value Description Boolean TRUE The logical connection is established.

FALSE 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:



Return Code:

Data Type Value Description Boolean TRUE The physical connection is established.

FALSE The physical connection is not established



B.6 MMTPCheckStartRequest

extern long MMTPCheckStartRequest(MMTPSESSION);

Description:

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

Arguments:



Return Code:


milliseconds The time in milliseconds since the last transmission/retransmission request was sent.

-1 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:





Return Code:


milliseconds The time in milliseconds since the last acknowledgement request by data source (SYNC-REQ) was sent.

-1 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:


Int Error code

Return Code:

Error Code

Description

0 No error

1 The logical connection is not established

2 The IP address is invalid

3 The physical connection is lost

4 No message received

5 Invalid argument

6 Function only available for client session

7 Function only available for server session

8 The session is invalid

9 A request of this type is already in progress

10 The logical connection is already established

11 The library is already initialized

12 The library is not initialized

13 Error during crypt/decrypt process



Error Description Code

14 Unable to open the socket

15 Insufficient memory

16 The maximum number of connections is reached

17 Unable to open the log file

18 The log file is not opened

19 The socket is full

20 Socket system error

21 The write buffer is full

22 The request to be cancelled does not exists

23 Too many listen ports are opened

24 Encryption feature not available

25 Invalid encryption library

26 System exception trapped

27 A system error occurred

28 Bad encryption/decryption key

29 The first argument is invalid

30 The second argument is invalid

31 The third argument is invalid

32 The fourth argument is invalid

33 The fifth argument is invalid

34 The sixth argument is invalid

35 The seventh argument is invalid

36 The eighth argument is invalid

37 The ninth argument is invalid

38 No key defined

B.9 MMTPObtainNumberSessions

extern int MMTPObtainNumberSessions(void);

Description:

MMTPObtainNumberSessions returns the current number of open sessions.



Arguments:


Void No input

Return Code:

Data Type Value Description Int # of

sessions 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:


Int MMTP Primitive Number

Return Code:

Data Type Value and description Char* Refer to the table of message primitives in Section 2.3 MMTP Message Primitives.

When the primitive number cannot be translated, “UNKNOWN” is returned.



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:



Int Error code

Int Error sub-code

Int The sequence number of the message in which the error occurs

MMTPMsg Message in which the error occurs

Error Code

Description Value

1 Sequence number greater than expected MMTPErrIndErr_MsgLost

2 Sequence number lower than expected MMTPErrIndErr_MsgDuplicate

3 Invalid field MMTPErrIndErr_InvalidField

4 Inappropriate message MMTPErrIndErr_OutOfContext

5 Invalid message MMTPErrIndErr_InvalidMsg

6 to 8 Reserved error code for future use

9 Access Control List violation MMTPErrIndErr_AclViolation

6 to 49 Reserved error code for future use

Greater than 49

User defined error code



Return Code:

Data Type Value Description Int 0 No error – MMTP_OK

Greater than 0

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

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 Description Input Output Input/

Output Int Timeout in seconds (from 10 to 7200) for

PRSC-MSG reception. If 0, the check will be disabled

Return Code:


Greater than 0

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

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:


MMTPSession Session handle



Return Code:

Data Type Value Description BOOL TRUE 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.

FALSE The transmission/retransmission request was received and accepted with the MMTPAcceptStart



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:


MMTPSESSION Logical session handle

Char* Connection parameters

Please refer to the table in the Connection Parameters

section in Appendix A

Return Code:


Greater than 0 Please refer to the list of possible error codes in Appendix A



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:



Int Last sequence number received

Return Code:



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.



Arguments:




Char* Message ID of the last message received

Return Code:



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



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:




Char* Message ID of last data message received

Return Code:



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:





Return Code:



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:



Return Code:



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.



Arguments:



Return Code:



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:



Return Code:



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.



Argument:



Return Code:



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.



Arguments:


MMTPSESSION Logical session handle obtained from MMTPCreateSession

Char* Client Identifier (up to 11 characters)

Char* Connection parameters (16 characters: 0 or 1) –

Refer to the table in the Connection Parameters


Char* Client’s password

Return Code:



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



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

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:


Char* NULL indicator

Char* NULL indicator

MMTPSESSION* Pointer to a session handle

Return Code:



C.12 MMTPDeleteSession

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


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

MMTP session. for removing the

Arguments:

Description Input Output Input/ Parameter Output

MMTPSESSION n handle Logical sessio

Return Code:

Data Type lue Va Description Int 0 No error – MMTP_OK

Gre e refer to the list of possible error codes in Appendix A ater than 0 Pleas

C.13 MMTPDenyConn

t (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

es the client connection request.

ection

extern int MMTPDenyConnection(MMTPSESSION, int);

Description:

MMTPDenyConnection rejects the client connection reques

C function initiat

Arguments:

Description Input Output Input/ Parameter Output

MMTPSESSION n handle obtained from MMTPCreateSession

Logical sessio

Int Reason for refusing connection –

Refer to the Refusal Reason Codes for

Connection Request




Return Code:



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:



Int Reason for refusing startup –

Refer to the Refusal Reason Codes for Connection Request


Char* Message ID of the last message received that was included in the START-REQ message.

Return Code:





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:



Int Reason for disconnection –

Refer to the Disconnection Reason Codes



Return Code:



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:


Int Maximum number of sessions which will be



Parameter Description Input Output Input/

Output opened at the same time

Return Code:



C.17 MMTPOpenClientSession

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

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.



Arguments:



Unsigned short The port number to establish the session. This number is used by the MMTP server to listen for incoming messages.

Char* Host name of the MMTP server.

Int Timeout in milliseconds. If 0, function returns immediately

Return Code:


Greater than 0 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.

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:



Char* Message ID of the last message received

Return Code:




Data Type Value Description


C.19 MMTPSyncRequest

extern int MMTPSyncRequest(MMTPSESSION);

Description:

MMTPSyncRequest submits an acknowledgement request by data source (SYNC-REQ) 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:



Return Code:



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:


Void No input



Return Code:





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:


Void No input

Return Code:





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:



Char* Unique name of the session identified by the application

Return Code:



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.



Arguments:


Char* Name of the log file

BOOL Boolean

TRUE = creates a log file

FALSE = appends to existing log file. If log file does

not exist, then creates one.

Return Code:



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



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:



Void (* fct) Pointer to a custom logging function. MMTP will execute the logging function.

Return Code:





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:



Int Timeout (in milliseconds) for message reception

MMTPMsg* Pointer to buffer where the received message must be stored



Return Code:


4 MMTP_NO_MESSAGE

Greater than 0 and # 4

MMTP error code is returned. Please refer to the list of possible error codes in Appendix A

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 (START-REQ) from the receiver before it can start transmitting messages.



Arguments:


MMTPSESSION Logical session handle obtained from MMTPCreateSession.

Int Message sequence number.

MMTPAdminData* Administrative data to be sent or NULL if no data.

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

Char* 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.

Return Code:



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)



{ 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); }



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:



Char* Message Service Type

a) PING

b) PONG

Int Size of the service data. If no data follows the message, the length is "0000".

Char* 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.



Return Code:



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: }



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:



Return Code:



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



. /**************************************************/ /* 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*/



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 {



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.



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.



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.



Contents:

Field Type Description MsgId text (25 characters) Message ID.

RouteData text (12 characters) Same as the routing data field in message header type E0.

OnMember text (9 characters) Name of the member for whom the message is sent (MAPI case only).

AdminSize number Size of contents in the Admin buffer.

Admin text (256 characters) Buffer for administrative data.

DataSize number Size of contents in the Data buffer.

Data text (9500 characters)

Buffer for message data.

Reason number Reason when SMMTP_DISCONNECTION error code is returned.

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 Reason 01 Client is not authorized to access the Bx Connect Server.

02 Bx Connect Server is not ready to accept connections from clients.

03 Client identifier or password is incorrect.

04 Last connection request is too recent (delay not respected).

05 Incompatible protocol version.

06 Invalid protocol options.

The SMMTP_DISCONNECTION error code can be returned by any SMMTP function call.



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.



Arguments:

Parameter Type Description In Out Handle SMMTPHANDLE * On output, pointer to a SMMTPHANDLE

which receives the handle of the new session.

On input, enables message logging if equal to 0xFFFFFFFF.

Port unsigned short Port number used by the server

IpAddr char * IP address of the server

User char User name used to establish the connection

Password char * User password

Direction Int 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.

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.

MsgId char *

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

Return Code:

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




Error code 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 Type Description In Out Handle SMMTPHANDLE 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)

Message SMMTPMsg *

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.

Return Code:

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




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



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:



Msg

SMMTPMsg * 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 Int Maximum delay to receive a message.

If equal to INFINITE, the function blocks until a



message is received.

Return Code:


SMMTP_OK If a message is received from the server.

SMMTP_NO_MESSAGE If no message is received.

SMMTP_DISCONNECTION If a disconnection request is received.


Int



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:



A pointer to a SMMTPMsg structure.

The client application must provide the following field:

• Msg→MsgId (Message ID of the last message processed by the client application)

Msg SMMTPMsg *


• Msg→Reason (on SMMTP_DISCONNECTION only)



Return Code:

Data Type Value Description SMMTP_OK If synchronization is successful.



Int



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:



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)

Message SMMTPMsg *



Timeout Int Maximum delay to send the message.



Parameter Type Description In Out

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

Return Code:

Data Type Value Description SMMTP_OK If the message is sent successfully.


In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection..

Int



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:



A pointer to a SMMTPMsg structure. Msg SMMTPMsg *

The function returns the following fields:

Msg→MsgId (last Message ID processed by the Bx Connect Server)




Return Code:

Data Type Value Description SMMTP_OK If the synchronization is successful.


In this case the Reason field of the SMMTPMsg parameter contains the reason code for the disconnection..

Int



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

Description:

Returns a descriptive text of a SMMTP error code.

Arguments:

Parameter Type Description In Out Error Int Error code.

Return Code:

Data Type

Error Code Value

Error text returned

0 SMMTP_OK No error.

1 SMMTP_NOT_CONNECTED Logical connection not established.

2 SMMTP_INVALID_ADDRESS Invalid IP address.

3 SMMTP_CNX_LOST Physical connection lost.

4 SMMTP_NO_MESSAGE No message received.

5 SMMTP_INVALID_ARG Invalid argument.

6 SMMTP_CLIENT_FCT Session open in server mode and the requested function is reserved for sessions open in client mode.

7 SMMTP_SERVER_FCT Session opened in client mode and the requested function is reserved for sessions opened in server mode.

char *

8 SMMTP_INVALID_SESSION Invalid session.



Data Type

Error Code Value Error text returned

9 SMMTP_ALREADY_IN_PROGRESS A message of the same type is still awaiting acceptance.

10 SMMTP_ALREADY_CONNECTED Logical connection already established.

11 SMMTP_ALREADY_INITIALIZED Library already initialized.

12 SMMTP_NOT_INITIALIZED Library not initialized.

13 SMMTP_CRYPT_ERROR Encryption/decryption error.

14 SMMTP_CANNOT_INIT_SOCKET Unable to open socket.

15 SMMTP_NOT_ENOUGH_MEMORY Insufficient memory.

16 SMMTP_TOO_MUCH_SESSIONS Maximum number of sessions opened.

17 SMMTP_CANNOT_OPEN_LOGFILE Impossible to open the protocol transfer log file.

18 SMMTP_LOGFILE_NOT_OPENED Protocol transfer log file not opened.

19 SMMTP_SOCKET_FULL Socket full.

20 SMMTP_SOCKET_ERROR Socket system error.

21 SMMTP_BUFFER_FULL Write buffer full.

Use MMTPWriteTerminate to empty it.

22 SMMTP_NOT_IN_PROGRESS Pending action to be interrupted does not exist.

23 SMMTP_TOO_MUCH_LISTEN_PORTS Too many listening ports open.

24 SMMTP_ENCRYPTION_UNAVAILABLE Encryption feature not available.

25 SMMTP_INVALID_ENCRYPTION_LIB Encryption library invalid.

26 SMMTP_SYSTEM_EXCEPTION System exception trapped.

27 SMMTP_SYSTEM_ERROR System error.

28 SMMTP_BAD_KEY Bad encryption/decryption key.

29 SMMTP_INVALID_ARG1 The first argument is invalid.

30 SMMTP_INVALID_ARG2 The second argument is invalid.

31 SMMTP_INVALID_ARG3 The third argument is invalid.

32 SMMTP_INVALID_ARG4 The fourth argument is invalid.

33 SMMTP_INVALID_ARG5 The fifth argument is invalid.

34 SMMTP_INVALID_ARG6 The sixth argument is invalid.

35 SMMTP_INVALID_ARG7 The seventh argument is invalid.

36 SMMTP_INVALID_ARG8 The eighth argument is invalid.



Data Type

Error Code Value Error text returned

37 SMMTP_INVALID_ARG9 The ninth argument is invalid.

38 SMMTP_NO_KEY_DEFINED No key is defined.

100 SMMTP_BAD_USER_OR_PWD Invalid user or password.

101 SMMTP_UNEXPECTED_MSG An unexpected message has been received.

102 SMMTP_ACCESS_DENIED The server denies the connection.

103 SMMTP_SERVER_UNREADY The server is not ready.

104 SMMTP_LAST_CNX_TOO_RECENT The last attempt to establish the connection is too recent.

105 SMMTP_INCOMPATIBLE_LIBRARIES The MMTP libraries are incompatible between them.

106 SMMTP_INVALID_CNX_OPTIONS The connection options used are invalid.

107 SMMTP_UNKNOWN_MMTP_ERROR SMMTP received an unknown MMTP error code.

108 SMMTP_MMTP_PROTOCOL_ERROR An MMTP protocol error has occurred.

109 SMMTP_INVALID_MSGID The MsgId given is unknown.

110 SMMTP_OUT_FUNCTION This function is for SMMTP_OUT sessions only.

111 SMMTP_IN_FUNCTION This function is for SMMTP_IN sessions only.

112 SMMTP_DISCONNECTION The server sent a disconnection message.

113 SMMTP_SYNC_DISABLED The sync process is disabled.

114 SMMTP_WAITING_SYNCACK Waiting for a sync acknowledgement.

115 SMMTP_NO_SERVER_RESPONSE No server response.



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.



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



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 &&



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



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



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



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 };



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 <stdio.h> #include <stdlib.h> #include <string.h> #include <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];



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



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



{ 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. *******************************************************************************/



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



* 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;



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



* * 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;



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



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



// 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 MMTP_CANNOT_INIT_SOCKET: case MMTP_NOT_ENOUGH_MEMORY: case MMTP_TOO_MUCH_SESSIONS: case MMTP_SOCKET_ERROR: case MMTP_INVALID_ADDRESS:



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;




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

bexmmtpdevelopersguide

Documents

boston equities

static bool

bex trading

functions

bad encryptiondecryption

tcp port

api client

data type