Be XMMTPDevelopers Guide

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

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
Inbound and Outbound Messages

are sent via the API Client Application
and the Member Gateway
API DIRECT CLIENT API API

Orders APPLICATION Orders go to
Send MMTP Trading System Rec'v
Order GATEWAY
Replies to Entry
Application
Rec'v MMTP Replies From Send
Orders Bx Trading System Bx TRADE
CONNECT
Market Market Data
Rec'v MMTP
Data Application
Market Data Market Data From

Bex Trading System
Independent software vendors (ISVs) or member firms will be responsible for

developing their own customized order entry application and market data
applications. To develop these interfaces, the ISVs or member firms will have
access to the MMTP API Developer’s Toolkit containing programming libraries
for sending and receiving requests, responses, and market data. The MMTP API
Developer’s Toolkit runtime libraries communicate directly with the 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
MMTP
Developer's Access
Client Application Toolkit Point
API
MMTP
Orders Send MMTP Orders go to
GATEWAY BeX Trading System
Replies to
Rec'v MMTP
Orders Bx
CONNECT MMTP
Replies From
Market BeX Trading System
Rec'v MMTP
Data
Market Data
As shown above, communications between the API client application and Bx Trade
flow through Bx Connect server using the MMTP protocol.
2.2 Creating an MMTP Session

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

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

primitives
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 Client Sends Data Client Receives Data

Primitive
Direction Client Î Bx Bx Connect Client Î Bx Bx Connect Î
Connect Î Client Connect Client
CONX-REQ 9 9
CONX-ACK 9 9
CONX-NAK 9 9
DCNX-REQ 9 9 9 9
DCNX-ACK 9 9 9 9
START-REQ 9 9
START-ACK 9 9
START-NACK 9 9
DATA-MSG 9 9
SYNC-REQ 9 9
SYNC-ACK 9 9
ERR-IND 9 9 9 9
SRVC-MSG 9 9 9 9
PRSC-MSG 9 9 9 9

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
Local allocations
Client Program
System
resources
1st session
MMTPInitialize
nth
sessions
System
resources
nth session
4.2 Creating an MMTP Session

Before submitting requests or receiving responses, the API client application builds
a physical connection and a logical session with the MMTP server. By using the
MMTP APIs, the API client application can build the sessions required to
exchange messages.
To establish an MMTP session, the following three C functions are required:
Client-Initiated Requests
• MMTPCreateSession
• MMTPOpenClientSession
• MMTPConnectionRequest
The following diagram illustrates the initiation of an MMTP session between the
API client application and the MMTP server process. In this case, the API client
application is the sender of messages and the MMTP server process is the receiver.
The initial task when building a session is to create a logical session handle using
MMTPCreateSession. This function is responsible for generating a unique session
handle that is used throughout the duration of the logical session.

Figure 4: Initiation of MMTP Session Between API Client and MMTP Server
Client Application
MMTPCreateSession
Get session
handle
Server
Open socket
connection
MMTPOpenClientSession
Port number
Receiver's physical
address
MMTPConnectionRequest
CONX-REQ Authentication
Sender's identifier
Connection parameters
Sender's password
Connection accepted
MMTPAcceptConnection
CONX-ACK
MMTPReceiveMessage
Connection denied
CONX-NACK
MMTPDenyConnection
The next task when building a session is to open a physical socket between the
sender and receiver using MMTPOpenClientSession. To open a physical
connection, the API client application must specify the port number of the
receiver’s listener process and the physical address of the receiver (hostname or IP
address).
The third task requires the sender to submit a connection request using
MMTPConnectionRequest. Upon receiving the request, the receiver has the option
to accept (CONX-ACK) or to refuse (CONX-NACK) the request with an
acknowledgement. In the event that the API client application requires multiple
sessions, then the procedure shown in the diagram is repeated until all the sessions
are established.
4.3 Transmitting Data

Once a connection and session are established between the sender and the receiver,
the MMTP API provides the following three C functions that allows developers to
submit and retrieve messages:
• MMTPStartRequest
• MMTPSendMessage
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
Receiver
Initialization
Build session
MMTPReceiveMessage
switch START-REQ MMTPStartRequest
{ MMTPReceiveMessage
. switch
. {
START-REQ .
if allowed to submit START-ACK
START-ACK
MMTPStartAccept .
.
otherwise
MMTPStartDeny START-NACK
START-NACK
.
. }
}
MMTPSendMessage
In the MMTP architecture, the API client application can act as the sender of
messages to the Bx Connect component as well as the receiver of incoming
messages from Bx Connect.
4.4 Terminating an MMTP Session

To end a physical and logical session, the MMTP API provides four C functions.
These functions request disconnection from the server, remove logical sessions, 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
MMTPDisconnectionRequest Server
DCNX-REQ
Close logical session
1) Reason for disconnect
2) Last sequence number
received
Acknowledge disconnection
DCNX-ACK MMTPAcceptDisconnect
MMTPCloseSession
Terminate logical session
1) Break socket
connection
MMTPDeleteSession
Free local resources
MMTPTerminate
Free all remaining
resources
In the MMTP architecture, the API client application ends sessions with the
PACIn, PACOut, or PAC_RDF_MMTP at Bx Connect.
4.4.1 Build vs. End Sessions
The diagram below shows the relationships between the build session versus the
end session C functions. When building a session, the build session functions must
be executed in a specific order for a handshake between the API client application
and the MMTP server to occur. For example, the API client application must
create a session, open a physical connection, and finally send a connection request.
A similar process takes place at the termination of a session. The disconnection
request function, MMTPDisconnectionRequest, is comparable to the connection
request, MMTPConnectionRequest. Likewise, the MMTPCloseSession is
comparable to the MMTPOpenClientSession function. The end session C functions
must be executed in the order recommended in the diagram below to prevent any
mismanagement of sessions and physical connections.
Figure 7: Steps for Build Session and End Session
Build Session End Session
MMTPInitialize MMTPTerminate
Step 1 Step 8
MMTPCreateSession MMTPDeleteSession
Step 7
Step 2
MMTPOpenClient MMTPCloseSession
Step 3 Step 6
MMTPConnectionRequest MMTPDisconnectionRequest
Step 4 Step 5
4.5 MMTP Validation

Developers have the capability to check a request while the request is still in
progress. Although these functions are not required for session building and
message delivery, they provide useful functionalities after the session has been
built.
The MMTP API provides several C functions that allow developers to:
• Validate the state of a connection (physical and logical)
• Check the validity of a session handle
• Check the status of an acknowledgement request by data source
• Check the status of a transmission/retransmission request
The following diagram depicts a simple process flow for session handle validation.
The MMTPCheckHandle function verifies the validity of the session handle.

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

Session handle of
PgaSession data type
1) Allocate resources
MMTPInitialize for session
number n
2) Check if session
MMTPCheckHandle handle defined is
used by another
process
If not
MMTPCreateSession 3) Create a new

MMTP session
handle

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
PACIn
LOOP
CONX-ACK MMTPAcceptConnection
MMTPReceiveMessage
switch
{
CONX-ACK START-REQ MMTPStartRequest
CONX-NACK
Error processing
START-ACK
START-REQ
MMTPAcceptStart
Get out of loop
MMTPSendMessage DATA-MSG MMTPReceiveMessage

y Sequence number
y Message 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
Receiver
Build MMTP Session
MMTPStartRequest START-REQ
LOOP
MMTPReceiveMessage
switch PACOut
{
START-ACK
Store Message ID
Store Sequence START-ACK MMTPAcceptStart
number y Message ID
y Sequence number
DCNX-REQ
Accept disconnection
MMTPSendMessage
DATA-MSG DATA-MSG - Data content
Process message
} y Sequence number
y Message body
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
Receiver
Build MMTP Session
MMTPStartRequest
LOOP
MMTPReceiveMessage
switch PACOut
{
.
DATA-MSG
DATA-MSG - Data content MMTPSendMessage
Process message
If sequence number <> Sequence number
the expected number Message body
MMTPSendError ERR-IND
Last sequence # received

Close session Last message ID received
Build new session
START-REQ
MMTPStartRequest
. Last message ID received
START-ACK
Store message ID
Store sequence # START-ACK MMTPStartAccept
.
} Message ID
Sequence #
5.5.3 Retransmission of Messages
Another potential message recovery scenario is when the receiving application has
lost the last received message and its identifier. For instance, the receiving
application has received consecutive messages from the sender (PACOut) with
identifier A through Z during the day. A failure occurred where all messages kept
at the receiving application are lost. In order to recover, the receiving application
must request for a re-send of all messages. The steps required to request a re-send
of all messages from the CAP are as follows:
1) Send a transmission/retransmission request with an empty message ID.
2) Wait until a transmission/retransmission request acknowledgement is received
with an empty message ID.
3) Invoke MMTPReceiveMessage.
5.5.4 Ignoring Outdated Messages
When the client-server communication restarts after a failure occurred during the
market session, the receiving application could receive outdated market
information. In order to retrieve only the real-time feed, the receiving application

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 Message ID

Number
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)
Session Sequence Message Message

MMTPAdminData
Handle Number Length
MMTPAdminData
MMTPAdminDataE0 MMTPAdminDataM0 MMTPAdminDataRR
Generic
The API client application is responsible for formatting the requests to the Message
input argument of the MMTPSendMessage C function.
Refer to the MMTPSendMessage section in Appendix B for a detailed description
of the parameters required by this function.
Receiver
The primary API function for receiving messages is MMTPReceiveMessage. It
requires three arguments:
• Session handle
• Time out parameter
• MMTPMsg
The following diagram depicts the data format of the incoming message:

Figure 13: Format of Incoming Messages
MMTPReceiveMessage
(Session handle, Time Out, MMTPMsg)
MMTPMsg
MMTPConxReq MMTPDataMsg MMTPDcnxReq
Sequence Data
MMTPAdminData Data
Number Size
MMTPAdmin MMTPAdmin MMTPAdmin

DataE0 DataM0 Generic
MMTP uses the MMTPMsg data structure to store the body of the message, the
message ID, sequence number, and other critical information that the API client
application may need to manage as messages are received from the sender.
The API client application can retrieve responses and market data using the Data
field of the MMTPDataMsg data structure. MMTPDataMsg structure is a 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 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 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
{
} 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
{
} MMTPStartReq;
// Contents of START-ACK message.

typedef struct
{
int SeqNb;
} MMTPStartAck;
// Contents of START-NACK message.

typedef struct
{
MMTPStrtNckRsn Reason;
} 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;

} 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 Value Description
Code
0 MMTP_OK No error.


Code
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_PRO A message of the same type is still awaiting
GRESS acceptance.
10 MMTP_ALREADY_CONNE Logical connection already established.
CTED
11 MMTP_ALREADY_INITIAL Library already initialized.
IZED
12 MMTP_NOT_INITIALIZED Library not initialized.
13 MMTP_CRYPT_ERROR Encryption/decryption error.
14 MMTP_CANNOT_INIT_SOC Unable to open socket.
KET
15 MMTP_NOT_ENOUGH_ME Insufficient memory.
MORY
16 MMTP_TOO_MUCH_SESSI Maximum number of sessions open.
ONS
17 MMTP_CANNOT_OPEN_LO Impossible to open the protocol transfer log file.
GFILE
18 MMTP_LOGFILE_NOT_OPE Protocol transfer log file not open.
NED
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_LISTE Too many listen ports open.
N_PORTS
24 MMTP_ENCRYPTION_UNA Encryption feature not available.
VAILABLE
25 MMTP_INVALID_ENCRYPT Encryption library invalid.
ION_LIB

Code
26 MMTP_SYSTEM_EXCEPTI System exception trapped.
ON
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 Description Value

Code
01 Invalid client MMTPCnxNckRsn_InvalidMember
02 Bx Connect is not available MMTPCnxNckRsn_HubNotReady

Code
03 Unknown client or wrong password MMTPCnxNckRsn_UnknownMemb
er
04 Last connection too recent (retry later) MMTPCnxNckRsn_LastCnxTooRec
ent
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:

Code
01 START-REQ already requested but not MMTPStrtNckRsn_StartReqInProgr
acknowledged ess
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 Description Value

Code
01 Normal disconnection MMTPDcnxRsn_Normal
02 Bx Connect administration request for MMTPDcnxRsn_AskedByHub
disconnection
03 Abnormal disconnection MMTPDcnxRsn_Abnormal
04 Session interrupted by Bx Connect MMTPDcnxRsn_SessionBroken
05 START-ACK not received or the START-ACK MMTPDcnxRsn_InvalidStartAck
MsgId does not correspond to the data requested
in the START-REQ
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 9
Return Code:
Data Type Value Description
Long Time in The time in milliseconds since the last connection request was sent.
milliseconds
-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:
Output

Return Code:
Long Time in The time in milliseconds since the last disconnection request was
milliseconds 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:
Output
MMTPSESSION session handle 9
Return Code:
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:
Output

Return Code:
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:
Output
Return Code:
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:
Output
Return Code:
Long Time in The time in milliseconds since the last transmission/retransmission
milliseconds 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:
Output

Return Code:
Long Time in The time in milliseconds since the last acknowledgement request by
milliseconds 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:
Output
Int Error code 9
Return Code:
Error Description
Code
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:
Output
Void No input
Return Code:
Int # of Current number of open sessions
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:
Output
Int MMTP Primitive Number 9
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:
Output
Int Error code 9
Int Error sub-code 9
Int The sequence number of the message in which 9

the error occurs
MMTPMsg Message in which the error occurs 9
Error Description Value

Code
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 User defined error code
than 49

Return Code:
Int 0 No error – MMTP_OK
Greater Please refer to the list of possible error codes in Appendix A
than 0
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:
Output


Output
Int Timeout in seconds (from 10 to 7200) for 9
PRSC-MSG reception. If 0, the check will be
disabled
Return Code:
Greater Please refer to the list of possible error codes in Appendix A
than 0
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:
Output
MMTPSession Session handle 9

Return Code:
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:
Output
MMTPSESSION Logical session handle 9
Char* Connection parameters 9

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:
Output
Int Last sequence number received 9
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:
Output
Char* Message ID of the last message received 9
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:
Output
Char* Message ID of last data message received 9
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:
Output

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:
Output
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:
Output
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:
Output
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:
Output
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:
Output
MMTPSESSION Logical session handle obtained from 9
MMTPCreateSession
Char* Client Identifier (up to 11 characters) 9
Char* Connection parameters (16 characters: 0 or 1) 9

–
Refer to the table in the Connection Parameters
Char* Client’s password 9
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",
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:
Output
Char* NULL indicator 9
Char* NULL indicator 9
MMTPSESSION* Pointer to a session handle 9
Return Code:
C.12 MMTPDeleteSession
extern int MMTPDeleteSession(MMTPSESSION);
Description:
MMTPDeleteSession terminates the MMTP session. The function deallocates the

session buffer, decrements the number of active sessions, and releases the session
handle. If MMTPCreateSession is invoked, then MMTPDeleteSession is required
for removing the MMTP session.
Arguments:
Output
Return Code:
C.13 MMTPDenyConnection
extern int MMTPDenyConnection(MMTPSESSION, int);
Description:
MMTPDenyConnection rejects the client connection request (CONX-REQ) by

sending a connection refusal (CONX-NACK). It uses the sender’s session handle
to respond with the reason for connection refusal. The MMTPConnectionRequest
C function initiates the client connection request.
Arguments:
Output
MMTPCreateSession
Int Reason for refusing connection – 9
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:
Output
MMTPCreateSession
Int Reason for refusing startup – 9
Refer to the Refusal Reason Codes for
Connection Request
Char* Message ID of the last message received that 9
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:
Output
Int Reason for disconnection – 9

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:
Output
Int Maximum number of sessions which will be 9


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:
Output
MMTPCreateSession
Unsigned short The port number to establish the session. This 9
number is used by the MMTP server to listen
for incoming messages.
Char* Host name of the MMTP server. 9
Int Timeout in milliseconds. If 0, function returns 9

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:
Output
Char* Message ID of the last message received 9
Return Code:


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:
Output
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:
Output
Void No input 9

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:
Output
Void No input 9
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:
Output
MMTPCreateSession
Char* Unique name of the session identified by the 9
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:
Output
Char* Name of the log file 9
BOOL Boolean 9
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:
Output
MMTPCreateSession
Void (* fct) Pointer to a custom logging function. MMTP 9
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:
Output
MMTPCreateSession
Int Timeout (in milliseconds) for message reception 9
MMTPMsg* Pointer to buffer where the received message 9

must be stored

Return Code:
4 MMTP_NO_MESSAGE
Greater than MMTP error code is returned. Please refer to the list of possible error
0 and # 4 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:
Output
MMTPCreateSession.
Int Message sequence number. 9
MMTPAdminData* Administrative data to be sent or NULL if no 9

data.
Int Size of the application data. This can be 9
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). 9
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 */
/*******************************************/

{
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:
Output
MMTPCreateSession
Char* Message Service Type 9
a) PING
b) PONG
Int Size of the service data. If no data follows the 9
message, the length is "0000".
Char* This field contains the service data. The 9
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.
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:
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:
Output
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;
}
.
.
.
{
MustWait=TRUE;
.
.

.
/**************************************************/
/* Verify that the MMTP write buffer is empty */
/**************************************************/
else if(MMTPTerminateWrite(Session)==MMTP_OK)
{
.
.
.
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:
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 Buffer for message data.
characters)
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 9 9
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 9
IpAddr char * IP address of the server 9
User char User name used to establish the connection 9
Password char * User password 9
Direction Int Must be equal to SMMTP_IN or 9

SMMTP_OUT.
- SMMTP_IN means that the session sends
messages.
- SMMTP_OUT means that the session
receives messages.
MsgId char * This parameter depends on the value of the
Direction parameter.
- If the Direction parameter is equal to 9
SMMTP_IN, then the MsgId parameter is a
pointer to a buffer which receives the MsgId of
the last message received by the server.
- If the Direction parameter is equal to 9
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 9
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. 9
If equal to INFINITE, the function blocks until
the connection is established (not
recommended).
Return Code:
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:
Handle SMMTPHANDLE A SMMTPHANDLE obtained with the 9
SMMTPConnect function.
Message SMMTPMsg * A pointer to a SMMTPMsg structure.
The client application must provide the 9
following field:
Msg→Reason (reason for the disconnection)
The function returns the following field: 9
Msg→Reason (on SMMTP_DISCONNECTION)

Timeout Int Maximum delay to send the disconnection 9
request.
If equal to INFINITE, the function blocks until a
disconnection request is sent.
Return Code:
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 9
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. 9
If equal to INFINITE, the function blocks until a
message is received.
Return Code:
Int 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.
disconnection.
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:
Msg SMMTPMsg * A pointer to a SMMTPMsg structure.
following field:
• Msg→MsgId (Message ID of the last message
processed by the client application)
• Msg→Reason (on
SMMTP_DISCONNECTION only)

Return Code:
Int SMMTP_OK If synchronization is successful.

disconnection.
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:
Message SMMTPMsg * A pointer to a SMMTPMsg structure that
contains the message to send.
following fields:
Msg→MsgId
Msg→Data
Msg→DataSize
Msg→RouteData
Msg→OnMember (for MAPI usage only)
Msg→Reason (on
SMMTP_DISCONNECTION only)
Timeout Int Maximum delay to send the message. 9


If equal to INFINITE, the function blocks until
a message is sent.
Return Code:
Int SMMTP_OK If the message is sent successfully.

disconnection..
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:
Msg SMMTPMsg * A pointer to a SMMTPMsg structure.
The function returns the following fields: 9
Msg→MsgId (last Message ID processed by the
Bx Connect Server)
Msg→Reason (on SMMTP_DISCONNECTION
only)

Return Code:
Int SMMTP_OK If the synchronization is successful.

disconnection..
G.9 SMMTPErrorDescription
extern const char * SMMTPErrorDescription( int Error );
Description:
Returns a descriptive text of a SMMTP error code.
Arguments:
Error Int Error code. 9
Return Code:
Data Error Code Value Error text returned
Type
char * 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.
8 SMMTP_INVALID_SESSION Invalid session.


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


Type
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("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);
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)
{
if(rc==MMTP_OK)
{
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]);
}
{
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.
// 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.
break;
// Other return code.

default:
printf(
"Error in MMTPReceiveMessage : %d - %s\n",
}
}
}
}
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.

{
// Try to physically connect the session to the server.
// 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",
Quit=TRUE;
}
else
{
{
printf(
"Error in MMTPOpenClientSession: %d - %s\n",
Quit=TRUE;
}
}
}
return(FALSE);
}
void ProcessConnectionDeny(MMTPConxNack* ConxNack)

{
printf("Connection request refused (reason %d).\n",ConxNack->Reason);
if(ConxNack->Reason==1 || ConxNack->Reason==3)
{
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);
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);
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);
}
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("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)
{
if(rc==MMTP_OK)
{
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(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.

if(rc==MMTP_OK)
{
printf("Physical connection with the server established\n");
return(TRUE);
}
{
}
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.

// 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);
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.
return(FALSE);
// Other return code.

default:
}
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++)
{
{
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.

{
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:
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_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

Be XMMTPDevelopers Guide

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Be XMMTPDevelopers Guide

Caricato da

Copyright:

Formati disponibili

Connectivity Process

MMTP API Developer’s Guide

Document version: 1.10

Version: 1.0 Page 2 of 116 March, 2006

1. MMTP Open Interface ......................................................................................................................4

3. MMTP API .......................................................................................................................................12

4. Session Management ....................................................................................................................14

5. Order Entry/Market Data Message Flow.......................................................................................21

A. API (Data Definition) ......................................................................................................................30

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

B. API (Protocol Management Functions) ........................................................................................37

C. API (Session Management Functions) .........................................................................................49

D. API (Logging Functions) ...............................................................................................................65

E. API (Transmission Functions) ......................................................................................................69

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

Version: 1.0 Page 4 of 116 March, 2006

G.2 SMMTPMsg structure ...........................................................................................................80

Version: 1.0 Page 5 of 116 March, 2006

Version: 1.0 Page 1 of 116 March, 2006

MMTP API vs. SMMTP API

Version: 1.0 Page 2 of 116 March, 2006

Version: 1.0 Page 3 of 116 March, 2006

1. MMTP Open Interface

This chapter describes the MMTP open interface and includes:

Figure 1: Overview of MMTP Architecture

Inbound and Outbound Messages

API DIRECT CLIENT API API

Market Data Market Data From

Independent software vendors (ISVs) or member firms will be responsible for

Version: 1.0 Page 4 of 116 March, 2006

To simplify MMTP programming, an additional API is available called SMMTP

1.2 Compliant Operating Systems

Version: 1.0 Page 5 of 116 March, 2006

This chapter describes the MMTP protocol and includes:

Version: 1.0 Page 6 of 116 March, 2006

Figure 2: Overview of the MMTP Protocol

2.2 Creating an MMTP Session

Version: 1.0 Page 7 of 116 March, 2006

2.3 MMTP Message Primitives

MMTP Message Number Description

Version: 1.0 Page 8 of 116 March, 2006

2.4 Direction of Protocol

Message Client Sends Data Client Receives Data

Version: 1.0 Page 9 of 116 March, 2006

2.5 MMTP Message Structure

Field Name Offset Length Type Value Comment

STX 0 1 02 Message header. Value in

2.6 Sequence Numbers and Message IDs

Version: 1.0 Page 10 of 116 March, 2006

• Are the internal identifiers of the message to the sending application.

2.7 Managing Windows for Sending Messages

3.1 Session Management Functions

• MMTPAcceptConnection • MMTPCancelSyncRequest • MMTPInitialize

3.2 Protocol Management Functions

Version: 1.0 Page 12 of 116 March, 2006

• Manage the buffer.

• MMTPCheckConnectionRequest • MMTPCheckPhysicalConnection • MMTPObtainNumberSession

3.3 Transmission Functions

3.4 Logging Functions

Version: 1.0 Page 13 of 116 March, 2006

4.1 Initializing an MMTP Session

Version: 1.0 Page 14 of 116 March, 2006