Multi Process Message Formats

Copyright 1995-2011 by Pathfinder Solutions LLC

Multi-Process Message Formats

Version 0.1

March 17, 2011

PathMATE Technical Notes

Pathfinder Solutions 33 Commercial Drive, Suite 2

Foxboro, MA 02035 USA

www.PathfinderMDA.com +1 508-568-0068

ii

Table Of Contents

1 Introduction.......................................................................................... 1

2 Overview............................................................................................... 1

2.1 Terminology.................................................................................. 1 2.1.1 The TCP/IP Network model ....................................................... 1 2.1.2 Ethernet Link Protocol - Layer 1 ................................................ 1 2.1.3 Internet Protocol(IP)- Layer 2 ................................................... 2 2.1.4 TCP Transport Protocol - Layer 3 ............................................... 3 2.1.5 PathMATE Application Protocol - Layer 4..................................... 3

3 PathMATE Application Messaging Protocol ............................................ 5

3.1 Incident Message Type ................................................................... 5 3.1.1 Service Handle Incident Type.................................................... 5

3.1.1.1 32bit Signed Integer(INTEGER_VALUE) ...................................... 6 3.1.1.2 64bit Signed Integer(LONG_LONG_VALUE) ................................. 6 3.1.1.3 64bit Floating Point Value(REAL_VALUE)..................................... 6 3.1.1.4 32bit/64bit Pointer Value(POINTER_VALUE) ................................ 7 3.1.1.5 String Value(STRING_VALUE) ................................................... 7 3.1.1.6 Service Handle(SVCHANDLE_VALUE) ......................................... 7 3.1.1.7 Fine Grained Time Value(TIME_VALUE) ...................................... 7 3.1.1.8 Groups and External Serialized Types (SERIAL_VALUE or RC_SERIAL_VALUE) ............................................................................... 8

3.2 Init Connection Message Type ......................................................... 9

3.3 External Realized Message Type......................................................10

3.4 Shutdown Notification Message Type ...............................................10

A. Appendix - References ........................................................................ 10

Table Of Figures

Figure 1 - Ethernet Protocol............................................................................. 1

Figure 2 - IP Header and Data within an Ethernet Packet ..................................... 2

Figure 3 - IP Header Definition......................................................................... 2

Figure 4 - TCP Header and Data within an IP Packet............................................ 3

Figure 5 - TCP Header Definition ...................................................................... 3

Figure 6 - PathMATE Application Message Definition ............................................ 3

Figure 7 - Depiction PathMATE messages transmitted over Ethernet packets .......... 5

Multi-Process Messaging Formats

1

1 Introduction

This Technical Note describes the Message formats used in PathMATE Multi-Process deployments when communicating between any two process instances. Section 2 provides an overview of the different message protocol layers involved during transmission defining basic terminology and the basic concepts. Section 3 describes in the detail the PathMATE Application Messaging Protocol and all supported message formats, as defined for the CPP Transformation Maps in 8.2.0 software releases. Appendix A lists sources for referenced information for Ethernet and TCPIP protocols.

2 Overview

2.1 Terminology

In the document we first present the various network protocol layers used in sending PathMATE messages using the TCPIP protocol suite and over an Ethernet based network.

2.1.1 The TCP/IP Network model

The TCP/IP Network model defines four layers to define the combination of protocols used for communication:

Layer 1 - Link - The Link layer defines the device driver and network hardware(network interface card). Ethernet/IEEE 802.3 is handles the link layer.

Layer 2 - Internet(aka Network) - The Internet layer handles basic communication, addressing and routing. IP, ICMP, ARP and IGMP protocols are at the network layer.

Layer 3 - Transport Layer - The Transport layer handles flow of data among applications. It segments data into packets for transport over the network. TCP and UDP operate at the transport layer.

Layer 4 - Application - The Application layer handles details of the particular end-user applications. Commonly used TCP/IP applications include Telnet, FTP, SMTP, SNMP, DNS, RIP, NFS, NTP, Traceroute. In this document we will define the PathMATE application layer message protocol in detail.

2.1.2 Ethernet Link Protocol - Layer 1

Ethernet protocols refer to the family of local-area network (LAN) covered by the IEEE 802.3. Below is the basic IEEE 802.e Ethernet MAC Data Frame for 10/100Mbps Ethernet:

7 bytes

1 bytes

6 byte

s

6 Bytes

2 bytes 46-1500 bytes 4

bytes

Pre SFD DA SA Length Type Data unit + pad FCS

Figure 1 - Ethernet Protocol

Preamble (PRE)- 7 bytes. The PRE is an alternating pattern of ones and zeros that tells receiving stations that a frame is coming, and that provides a means to


2

synchronize the frame-reception portions of receiving physical layers with the incoming bit stream.

Start-of-frame delimiter (SFD)- 1 byte. The SOF is an alternating pattern of ones and zeros, ending with two consecutive 1-bits indicating that the next bit is the left-most bit in the left-most byte of the destination address.

Destination address (DA)- 6 bytes. The DA field identifies which station(s) should receive the frame..

Source addresses (SA)- 6 bytes. The SA field identifies the sending station. Length/Type- 2 bytes. This field indicates either the number of MAC-client data bytes

that are contained in the data field of the frame, or the frame type ID if the frame is assembled using an optional format.

Data- Is a sequence of n bytes (46=< n =<1500) of any value. (The total frame minimum is 64bytes.)

Frame check sequence (FCS)- 4 bytes. This sequence contains a 32-bit cyclic redundancy check (CRC) value, which is created by the sending MAC and is recalculated by the receiving MAC to check for damaged frames.

2.1.3 Internet Protocol(IP)- Layer 2

The Internet Protocol (IP) is the principal communications protocol used for relaying datagrams (packets) across an internetwork using the Internet Protocol Suite. Responsible for routing packets across network boundaries, it is the primary protocol that establishes the Internet.

MAC Header

IP Header IP Data MAC FCS

Figure 2 - IP Header and Data within an Ethernet Packet

00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

Version IHL Differentiated Services Total length

Identification Flags Fragment offset

TTL Protocol Header checksum

Source IP address

Destination IP address

Options and padding ::: Figure 3 - IP Header Definition

Specific field information is as follows: Version - Set to 4 for IP Protocol Protocol - Set to 6 when the next encapsulated protocol is TCP Padding - used to ensure that the IP Data starts at a 32-bit boundary. For more detailed IP Header information refer to the following link: http://www.networksorcery.com/enp/protocol/ip.htm


3

2.1.4 TCP Transport Protocol - Layer 3

TCP is a transport layer protocol used by applications that require guaranteed delivery. It is a sliding window protocol that provides handling for both timeouts and retransmissions. TCP establishes a full duplex virtual connection between two endpoints. Each endpoint is defined by an IP address and a TCP port number. The operation of TCP is implemented as a finite state machine. The byte stream is transferred in segments. The window size determines the number of bytes of data that can be sent before an acknowledgement from the receiver is necessary.

MAC Header

IP Header

TCP Header TCP Byte Stream Data MAC FCS

Figure 4 - TCP Header and Data within an IP Packet

00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31

Source Port Destination Port

Sequence Number

Acknowledgment Number

Data Offset reserved ECN Control Bits Window

Checksum Urgent Pointer

Options and padding ::: Figure 5 - TCP Header Definition

For more detailed TCP Header information refer to the following link: http://www.networksorcery.com/enp/protocol/tcp.htm

2.1.5 PathMATE Application Protocol - Layer 4

All PathMATE messages conform to format specified in the following figure.

4 bytes 4 bytes

1-2147483639 bytes (The actual Message Size Dependent on Type and will be limited to heap memory allocation restrictions on

each process)

Message Length Message Type Message Data

Figure 6 - PathMATE Application Message Definition

Message Length - 4 bytes. Indicates the number of bytes for the next message in the byte stream, including the Message Type (4 bytes) and the Message Data.


4

Message Type - 4 bytes. The message type indicates the specific contents of the Message Data. Currently there are four defined message types:

1. SW_SOCK_MSG_INIT_CONN = 18 - Message sent to remote process after a new connection is established.

2. SW_SOCK_MSG_INTERPROCESS_INCIDENT_HANDLE = 353 - Message used to send messages containing an incident, which currently can only be a service incident type (used to send domain service handles and class service handles).

3. SW_SOCK_MSG_INTERPROCESS_SHUTDOWN = 355 - When a process is shutdown, it send this message to remote processes on all active connections to notify that it is shutting down.

4. SW_SOCK_MSG_REALIZED_EXTERNAL = 777 - Message type used to allow sharing of PathMATE socket connections with external realized code. This allows communications between realized code integrated with PathMATE and external processes executing realized code developed independently of PathMATE.

Message Data - Contains the message type specific data. See section 3 for more detail regarding each message type.

As with all TCPIP standard based protocols, PathMATE adheres to serializing and transmitting all multi-byte data types in Network Byte Order (which is also the same as Big Endian). That is, the Most Significant Byte is transmitted first. For example, the Message Length is sent as a 32-bit word, byte offset 0 contains the most significant byte and byte offset 3 contains the least significant byte. On a 0x86 PC data is stored natively in Little Endian format, where the Least Significant Byte(LSB) is stored in offset 0, and the Most Significant Byte(MSB) is stored in byte offset 3. When transmitting a message from a little endian based processor, all multi-byte data types are converted to match Network Byte Order. Vice-Versa, when receiving data the data is converted to the native little endian format. On Big Endian based processors no conversion is necessary.

PathMATE messages are sent on an established TCP/IP based socket, which is a guaranteed delivery based protocol. A PathMATE message is inserted into the socket byte stream. A TCP packet can contain a single or multiple PathMATE messages, and on the Process receiving the byte stream the PathMATE messages are distinguished with the following procedure:

1. After a socket is established, the Transmitting process sends the complete PathMATE message over the socket. The number of bytes transmitted MUST match the number of bytes comprising the message length (4 bytes) + the message type (4 bytes) + the message data (the actual message data length + the message type MUST match exactly the length indicated in the message length field. Any deviation from this will prevent the receiver process to achieve message synchronization.

2. The receiving process will first read ONLY 4 bytes, which contain the message length of the remaining bytes to read. Once the Message length is read, it then can read the remaining message using the received message length.

3. Subsequent messages can be read following the previous step.

As TCP sends data as a byte stream, each TCP packet can contain multiple PathMATE messages or a portion of a single large PathMATE message. The figure on the next page shows a depiction of how messages can appear on TCP/IP packets over Ethernet. The


5

number within the TCP Data field indicates distinct PathMATE messages. The figure shows 3 complete messages and a partial message (the 4th message).

Data Packet 1

MAC Header

IP Header

TCP Header

TCP Byte Stream Data 1 1 2 2

MAC FCS

Data Packet 2

MAC Header

IP Header

TCP Header

TCP Byte Stream Data 2 3 3

MAC FCS

Data Packet 3

MAC Header

IP Header

TCP Header

TCP Byte Stream Data 3

MAC FCS

Data Packet 4

MAC Header

IP Header

TCP Header

TCP Byte Stream Data 3 4 4

MAC FCS

Figure 7 - Depiction PathMATE messages transmitted over Ethernet packets

3 PathMATE Application Messaging Protocol

The following sections describe more detail for each PathMATE message types.

3.1 Incident Message Type

3.1.1 Service Handle Incident Type

The following figure shows the fixed portion of service handle incident message. Relative Byte

Offset (in Hex)

Size (bytes)

Data Name Data Values

00 4 Message Length Length of Message Type + Message Data

04 4 Message Type 00 00 01 61 (353) 08 4 Incident Type 00 00 00 00 (0) 0C 4 Process Type Deployment value index for

Process Type 10 4 Sentinel Value DE AD FA CE 14 4 Message Version 00 00 00 01 18 4 Process ID Unique Process Identifier 1C 4 Domain Index Deployment value index for

Domain 20 4 Service Index Deployment value index for

Domain or Class Service 24 4 Task Index Deployment value index for Task

ID 28 2 Destination(not used) 2 byte string -> "0," 2A 4 Priority (not set) 00 00 00 00 2E 4 Sender Process (not set) 00 00 00 00


6

Relative Byte Offset

(in Hex)

Size (bytes)


32 4 Sender Task (not set) 00 00 00 00 36 4 Parameter Count # of parameters for domain or

class service 3A 4 Provided Parameter Count # of of provided parameters for

domain or class service 3E 4 Parameter 1 "name" index Deployment value index for

parameter name 42 4 Parameter 1 native data

type value index for native data type

46 Based on native data

type

Parameter 1 Value Based on data type

The Remainder of Message depends on the # parameters for domain or class service. The item after the Parameter 1 value is the Parameter 2 "name" index, assuming there are 2 or more parameters specified.

The following sub sections describes the various PathMATE native data types.

3.1.1.1 32bit Signed Integer(INTEGER_VALUE)


(in Hex)

Size (bytes)


00 4 INTEGER_VALUE 00 00 00 01 04 4 32bit Signed Integer Value -2147483648 (80 00 00 00) to

2147483647(7F FF FF FF)

3.1.1.2 64bit Signed Integer(LONG_LONG_VALUE)


(in Hex)

Size (bytes)


00 4 LONG_LONG_VALUE 00 00 00 0A 04 8 64bit Signed Integer Value -9223372036854775808

(80 00 00 00 00 00 00 00) to 9223372036854775807 (7F FF FF FF FF FF FF FF)

3.1.1.3 64bit Floating Point Value(REAL_VALUE)


(in Hex)

Size (bytes)


00 4 REAL_VALUE 00 00 00 02 04 8 64bit IEEE-754 Floating

Point Value BIT63: Sign Bit

BITS[62-52]:Exponent BITS[51-0]:Fraction


7

3.1.1.4 32bit/64bit Pointer Value(POINTER_VALUE)


(in Hex)

Size (bytes)


00 4 POINTER_VALUE 00 00 00 04 04 8 Native Host Pointer Value.

Warning: Only relevant on Source Process or Shared Memory Map Address. On 32 bit processors the pointer is stored in the first most significant 32 bits.

Any Pointer Value

3.1.1.5 String Value(STRING_VALUE)


(in Hex)

Size (bytes)


00 4 STRING_VALUE 00 00 00 03 04 String Length

+ 1 Null Terminated String The last byte is a NULL character.

3.1.1.6 Service Handle(SVCHANDLE_VALUE)


(in Hex)

Size (bytes)


00 4 SVCHANDLE_VALUE 00 00 00 05 The rest of the message is exactly as shown in section 3.1.1 - Service Handle Incident Type.

04 4 Incident Type 00 00 00 00 (0) 08 4 Process Type Deployment value index for

Process Type 0C 4 Sentinel Value DE AD FA CE 10 4 Message Version 00 00 00 01

...

3.1.1.7 Fine Grained Time Value(TIME_VALUE)

NOTE: Currently Fine Grained time is not implemented. If an attempt to send a Fine Grain Time is attempted it will first be converted into a double floating point variable, then into a string representation of the value. The receiving process will have no way of knowing that it is a time variable. The current serialized output is shown here:


(in Hex)

Size (bytes)


00 4 STRING_VALUE 00 00 00 03 04 String Length

+ 1 Null Terminated String representing the fine grained time in milliseconds.

The last byte is a NULL character. Examples:

"1259009.0023" <- (in milliseconds)


8

In the future we may represent it natively as follows:


(in Hex)

Size (bytes)


00 4 TIME_VALUE 00 00 00 09 04 4 Seconds Number of seconds since the

process started 08 4 Nano-seconds Number of fractional nano-

seconds in the current second

3.1.1.8 Groups and External Serialized Types (SERIAL_VALUE or RC_SERIAL_VALUE)

PathMATE provides the ability to serialize/de-serialize externally defined types; to learn more about how to do this please refer to the advanced realized types technical note. There are two types of serialized data types: SERIAL_VALUE & RC_SERIAL_VALUE. They are serialized/de-serialized exactly the same, the difference being that the RC_SERIAL_VALUE provides an indication to the receiving process that the data type container class needs to have pointer reference counting. Here we will show the format for groups of specific native data types. Relative

Byte Offset (in Hex)

Size (bytes)


00 4 SERIAL_VALUE RC_SERIAL_VALUE

00 00 00 07 00 00 00 08

04 4 SERIAL_TYPE_[groupname] Group of Integer Example: SERIAL_TYPE_GroupListInteger

Deployment value index for the group data type. This will not vary on the same deployment

08 4 Number of Items(N) 1 or higher 0C datasize Value 1 Dependent on type

0C + datasize datasize Value 2 Dependent on type ...

0C + datasize*N

datasize Value N Dependent on type

The format for groups of generic data types is as follows:


(in Hex)

Size (bytes)


00 4 SERIAL_VALUE RC_SERIAL_VALUE

00 00 00 07 00 00 00 08

04 4 One of the following: SERIAL_TYPE_ListGroupGeneric SERIAL_TYPE_ArrayGroupGeneric SERIAL_TYPE_HashGroupGeneric

Deployment value index for the generic group

type. This will not vary on the same deployment

08 4 Number of Items(N) 1 or higher 0C 4 Native Data Type for value 1 One of the following:

INTEGER_VALUE, LONG_LONG_VALUE,


9


(in Hex)

Size (bytes)


REAL_VALUE, POINTER_VALUE

SVCHANDLE_VALUE, STRING_VALUE, SERIAL_VALUE,

RC_SERIAL_VALUE 10 Datasize_item1 Value 1 Dependent on native

data type 10 +

datasize_item1 4 Native Data Type for value 2 One of the following:

INTEGER_VALUE, LONG_LONG_VALUE,

REAL_VALUE, POINTER_VALUE

SVCHANDLE_VALUE, STRING_VALUE, SERIAL_VALUE,

RC_SERIAL_VALUE 10 +

datasize_item1 + 04

Datasize_item2 Value 2 Dependent on native data type

... 0C +

SUM[N-1] (04 +

datasize_itemx)

4 Native Data Type for value N One of the following: INTEGER_VALUE,

LONG_LONG_VALUE, REAL_VALUE,

POINTER_VALUE SVCHANDLE_VALUE,

STRING_VALUE, SERIAL_VALUE,

RC_SERIAL_VALUE 0C +

SUM[N-1] (04 +

datasize_itemx) + 04

Datasize_itemN Value N Dependent on native data type

3.2 Init Connection Message Type

The following message is sent on the transmit socket after the Sender process establishes a socket with a process listening on a port. All of the provided data is from the Sender process.


(in Hex)

Size (bytes)


00 4 Message Length 00 00 00 14 (20) 04 4 Message Type 00 00 01 12 (18) 08 4 Process Type Deployment index value for

process type 0C 4 OS Process Id Runtime and OS dependent


10


(in Hex)

Size (bytes)


10 4 Process ID Unique Process Identifier 14 4 Connection Count prior to

this connection. 0 and higher

3.3 External Realized Message Type

External realized message types are simply defined by setting the message type field to 777, which over the network will be sent (shown in hex) as 00 00 03 09. The message data contents are user defined based on the external realized code


(in Hex)

Size (bytes)


00 4 Message Length Length of Message Type + user defined size

04 4 Message Type 00 00 03 09 (777) 08 User defined

size User Data Contains data defined by external

software

3.4 Shutdown Notification Message Type

This message is sent to all connected remote processes to notify when the local process will close all connections and shut down.


(in Hex)

Size (bytes)


00 4 Message Length 00 00 00 04 ( 4) 04 4 Message Type 00 00 01 63 (355)

A. Appendix - References

The following references where used in creating this document

1. PathMATE CPP Mechanisms 8.2.0 source code 2. http://en.wikipedia.org/wiki/IP_Protocol 3. http://en.wikipedia.org/wiki/IP 4. http://www.networksorcery.com/enp/protocol/ip.htm 5. http://www.networksorcery.com/enp/protocol/tcp.htm 6. http://www.speedguide.net/articles/the-tcpip-and-osi-network-models-120

Technology

Multi Process Message Formats