Message Formats and Interface Methods

1 Message Formats and Interface Methods

To develop the third-party PMS Interface, use the message formats and the interface methods described in this section.

Interface Methods

The third-party PMS Interface supports a TCP-based interface.

TCP Interface

This interface connects Simphony to Microsoft Windows based systems and other systems using the TCP/IP networking protocol. This interface facilitates communications between the POS application and third-party applications that reside on the same Windows platform as the Simphony software.

This interface is also compatible with many forms of local area networks (LANs), including Ethernet, etc.

TCP Connection

The Simphony POS System connects to the TCP port as a socket-client. The third-party PMS application interface must act as a socket-server and accept TCP connections from the Simphony POS system on the default port 5009. This port should be configurable so changes may be made to any value above 5009, if needed. The Simphony POS system does not close the port unless it is shutting down, but includes of course functionality to determine if the third-party PMS application disconnected and reconnects when needed. The third party PMS application interface on the other side should not close the port unless it is shutting down, but should include functionality to determine if the Simphony POS workstation is disconnected.

Even though a Simphony POS system can handle up to hundreds of workstations, there is only one interface connection (for example, an open socket-pair) to the third-party PMS application per physical Simphony server.

Message Format

The format of all messages between the Simphony POS System and the third-party PMS application include three segments and have the following layout:

SOH <POS Source ID> STX FS <Application Seq.> <Application Data> ETX <Checksum> EOT

SOH

The SOH character (Start of Header) serves as a message lead-in character that identifies the start of a new message. The SOH character is represented by the 7-bit hexadecimal value 01h, plus a parity bit, if applicable.

SOH <POS Source ID> STX FS <Application Seq.> <Application Data> ETX <Checksum> EOT

The <POS Source ID> character field identifies the source (when sent by the Simphony POS System) and the destination of a message (when replied by the third-party PMS application). The <POS Source ID> field contains either 18 or 25 characters. The interface definition record may be configured to supply either a two-character or a nine-character Workstation Number, which is followed by the Outgoing Message Name (16 characters). The Workstation Number is a 2- or 9-bytes numeric character field in the range 1 through 99 (or 1 to 999999999 respectively). It is represented by ASCII character codes in the range Hex 30 through Hex 39, plus parity bits, if applicable. The digits are right justified within the field with leading ‘0’ (ASCII zero character, Hex 30) or leading blanks (ASCII blank character, Hex 20). Leading characters appear only if the number of characters in the field is less than the total field size. The Outgoing Message Name is a 16-byte alphanumeric character field stored in the Simphony Interface Definition. This field is represented by ASCII character codes, plus parity bits, if applicable. It identifies and differentiates the source(s) of the communications message(s).

Examples, the character "·" represents a single SPACE (20h):

2-character Workstation Number:

01PMS INTERFACE···

9-character Workstation Number:

000000001PMS INTERFACE···

STX

The STX (Start of TeXt) serves as a data field lead-in character that identifies the start of the message data block. The STX character is represented by the 7-bit hexadecimal value 02h, plus a parity bit if applicable.

The FS (Field Separator) identifies this message as a SIM message data block. The FS character is represented by the 7-bit hexadecimal value 1Ch, plus a parity bit if applicable.

SOH <POS Source ID> STX FS <Application Seq.> <Application Data> ETX <Checksum> EOT

The <Application_Seq.> segment comprises a two-digit sequence number and a retransmission flag. Each Simphony POS workstation application increments its own sequence number with each message. When a message is retransmitted, the same sequence number will be used as the original message. In addition, a retransmission flag character is provided.

The format of this segment is as follows:

Table 1-1 <Application Seq.> Segment

Field	Length	Format	Remarks
Applications Sequence Number	2 Bytes	2 ASCII digits	May contain leading spaces or zeroes and is between 01 and 99
Retransmission Flag Character	1 Byte	Space or “R”	“R” character (ASCII 52h) is placed in this field if this is a retransmission message

The Application_Sequence number is initially set to “01” when the Simphony POS workstation applications starts. The application rolls the sequence number back to “01” after “99”. If the third-party system receives a message containing the same sequence number as the previous message and the retransmission flag is set, the third party should retransmit the last response.

SOH <POS Source ID> STX FS <Application Seq.> <Application Data> ETX <Checksum> EOT

The <Application Data> segment is the actual payload of the message. It leads with a message ID field that identifies the message type. Permissible message IDs are listed on the following pages. A variable number of fields follow the message ID field. These fields constitute the body of the actual message and are defined for each message type. These fields are variable in length, consequently, each field is separated by an ASCII File Separator character (FS = 1Ch) which serves to determine the start of each field. The format of applications data segment looks like this:

The total size of the message can be 32K from the SOH to the EOT. There are a maximum of 37 bytes overhead, which means that the maximum byte count of all fields and field separators is 32768 – 37, or 32731 bytes.

SOH <POS Source ID> STX FS <Application Seq.> <Application Data> ETX <Checksum> EOT

The Checksum field is only used when communicating over an asynchronous serial interface. A TCP-based PMS Interface will ignore this field, so it can be omitted from the message format. When the Checksum is part of the message, however, format it as follows:

Table 1-2 Checksum Field

Field	Length	Format	Remarks
Checksum	4 bytes	4 ASCII Hex characters	Contains ASCII characters in the range 30H-39H and 41H-46H (0-9 and A-F)

The Checksum is the 16-bit binary addition (excluding parity, if applicable) of all characters after the SOH, up to and including the ETX character. The Checksum is initially set to zero. For asynchronous, serial transmission, the Checksum is represented as four ASCII-Hex characters.

EOT

The EOT (End Of Transmission) serves as a message lead-out character and identifies the end of a message. The EOT character is represented by the 7-bit hexadecimal value 04h, plus a parity bit, if applicable.

Pinging

The TCP connection has a typical “keep-alive” time-out of two hours, to detect a “down” interface more quickly and re-establish the connection, the Simphony PMS interface periodically sends a “ping” message to the server about every five minutes. The third-party PMS application should detect the ping message and return the message in its original format. The format of the ping message should be as follows:

SOH <POS Source ID> STX ETX EOT

The <POS Source ID> segment contains a null address: the workstation number will be zero and the interface name will be blank.

Example, the numbers in square brackets "[]" represent the decimal ASCII value of a single, non-printable character and the character "·" represents a single SPACE (20h):

2-character Workstation Number:

[1]·0················[2][3][4]

9-character Workstation Number:

[1]········0················[2][3][4]