Freeway ® Client-Server Interface Control Document DC 900-1303C Simpact, Inc.
Simpact, Inc. 9210 Sky Park Court San Diego, CA 92123 (858) 565-1865 Freeway Client-Server Interface Control Document © 1994 through 1999 Simpact, Inc. All rights reserved Printed in the United States of America This document can change without notice. Simpact, Inc. accepts no liability for any errors this document might contain. Freeway is a registered trademark of Simpact, Inc. All other trademarks and trade names are the properties of their respective holders.
Contents List of Figures 5 Preface 7 1 Overview 1.1 1.2 2 Freeway Overview . . . . . . . . . . . . Freeway Client-Server Environment . . 1.2.1 Defining TSI Configuration . . . . 1.2.2 Establishing a Freeway Connection 1.2.3 Exchanging Data with Freeway . . 1.2.4 Closing a Freeway Connection. . . 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Freeway Client-Server Interface Control Document 3.1.1 Bind Request Packet. . . . . . . 3.1.2 Unbind Request Packet . . . . . 3.1.3 Unbind Force Request Packet. . 3.1.4 ACK Packet . . . . . . . . . . . 3.1.5 NAK Packet . . . . . . . . . . . 3.2 Freeway Control Packet Formats . . 3.2.1 Open Session Request Packet . . 3.2.2 Open Session Response Packet . 3.2.3 Close Session Request Packet . . 3.2.4 Close Session Response Packet . 3.2.5 Get Version Request Packet . . . 3.2.6 Get Version Response Packet . . 3.
List of Figures Figure 1–1: Typical Freeway Configuration . . . . . . . . . . . . . . . . . . . . . . . 15 Figure 1–2: Freeway Configuration with Clients That Do Not Use the DLI . . . . . . 18 Figure 2–1: TSI Connection Data Flow (Without Arbitration) . . . . . . . . . . . . . 25 Figure 2–2: TSI Connection Data Flow (With Arbitration) . . . . . . . . . . . . . . . 25 Figure 2–3: Freeway Session Initiation, Data Transfer, and Termination . . . . . . . .
Freeway Client-Server Interface Control Document 6 DC 900-1303C
Preface Purpose of Document This document describes the packets that are exchanged between a client and a Freeway server. It aids the client application developer in the construction of the data packets necessary to open and close sessions to the Freeway server and communicate with the ICP protocol logic. It is intended for use in the development of client applications that choose not to use the Data Link Interface (DLI) provided by Simpact.
Freeway Client-Server Interface Control Document Required Equipment A Freeway 1100/1150/1200/1300, Freeway 2000/4000, or Freeway 8800 server. Organization of Document Chapter 1 is an overview of Freeway and its client/server interface. It also describes the relationship of the various layers (application, DLI, TSI). Chapter 2 describes the various packet exchanges necessary to initiate and maintain communication with the Freeway server and its protocol logic.
Preface • • • • Freeway 2000/4000 Hardware Installation Guide DC-900-1331 Freeway 8800 Hardware Installation Guide DC-900-1553 Freeway ICP6000R/ICP6000X Hardware Description DC-900-1020 ICP6000(X)/ICP9000(X) Hardware Description and Theory of Operation DC-900-0408 • • • • ICP2424 Hardware Description and Theory of Operation DC-900-1328 ICP2432 Hardware Description and Theory of Operation DC-900-1501 ICP2432 Electrical Interfaces (Addendum to DC-900-1501) DC-900-1566 ICP2432 Hardware Install
Freeway Client-Server Interface Control Document Toolkit Programming Support • Freeway Server-Resident Application and Server Toolkit Programmer Guide DC-900-1325 • • OS/Impact Programmer Guide DC-900-1030 Protocol Software Toolkit Programmer Guide DC-900-1338 Protocol Support • • • • • • • • • • • • • • • ADCCP NRM Programmer Guide DC-900-1317 Asynchronous Wire Service (AWS) Programmer Guide DC-900-1324 AUTODIN Programmer Guide DC-908-1558 Bit-Stream Protocol Programmer Guide DC-900-1574
Preface The term “Freeway” refers to any of the Freeway server models (for example, Freeway 1100/1150/1200/1300, Freeway 2000/4000, or Freeway 8800. Physical “ports” on the ICPs are logically referred to as “links.” However, since port and link numbers are usually identical (that is, port 0 is the same as link 0), this document uses the term “link.” Program code samples are written in the “C” programming language.
Freeway Client-Server Interface Control Document 12 DC 900-1303C
Chapter 1 Overview This document describes Simpact’s client/server interface to the Freeway communications server. It’s primary purpose is to serve as a reference tool when you are writing client applications that do not use the data link interface (DLI). Note Two types of client applications are discussed in this document: ones that use the transport subsystem interface (TSI) and ones that do not. In either case, it is assumed that the applications do not use the data link interface (DLI).
Freeway Client-Server Interface Control Document The TSI and DLI provide a consistent, high-level, common interface across multiple hosts, operating systems, and transport services. Note the following similarities and differences between the DLI and TSI: • The DLI provides session-oriented data services to your client application with a subroutine library.
1: Overview Freeway VxWorks Server Resident Applications Message Multiplexor TSI SCADA ICP Defense Financial ● AAA AAA AAA AAA AAA AAA AAA AAA AAA Commercial X.25 Bisync HDLC . . .
Freeway Client-Server Interface Control Document Freeway can be configured with multiple WAN interface processor boards, which are Simpact intelligent communications processors (ICPs). Each ICP runs the communication protocol software using Simpact’s OS/Impact real-time operating system.
1: Overview 1.2 Freeway Client-Server Environment Freeway acts as a gateway that connects a client on a local-area network to a wide-area network. Through Freeway, a client application can exchange data with a remote data link application. Your client application must interact with the Freeway server and its resident ICPs before exchanging data with the remote data link application.
Freeway Client-Server Interface Control Document Client1 Client2 Application Application TSI TCP/IP Socket Interface TCP/IP Socket Interface Freeway TCP/IP Socket Interface Server TSI MsgMux ICP Device Driver ICPs X.
1: Overview Note Message formats and protocols used between the Freeway server and its client applications are subject to change in future releases. If you write applications without DLI or TSI layers, you may not be able to migrate the applications easily when the message formats and protocols change.
Freeway Client-Server Interface Control Document 1.2.2 Establishing a Freeway Connection After the TSI configuration is defined, the client application must establish a connection to the Freeway server. Applications that use the client TSI layer only need to make a library call (tConnect). Applications that do not use the client TSI layer must exchange “bind” and “open session” packets with the Freeway server TSI layer and MsgMux, respectively, as well as connect to the BSD socket. 1.2.
Chapter 2 Freeway Client-Server Protocol The Freeway client and server communicate via TCP/IP BSD-style sockets. (The serverresident client application that communicates via the shared-memory interface is not discussed in this document). The Freeway server acts as a TCP/IP socket server. It issues a listen() call for accepting incoming connections from the Freeway client. The Freeway client then issues the connect() call to request a connection to the Freeway server.
Freeway Client-Server Interface Control Document description of the well-known port parameter, see the “Customizing System Installation” chapter in the Freeway User Guide. The Freeway server uses the TSI logic and so expects the TSI-level packet exchanges that occur between a client and the server. All packets exchanged between the client and the server contain a TSI header, which indicates whether the packet is control information or data.
2: Freeway Client-Server Protocol of TSI data packets can begin immediately. Figure 2–1 on page 25 shows an example of this type of data flow. If the client receives a Bind request back from the server, it can accept the server communication conditions in the Bind request by sending an ACK packet to the server. When the server receives the ACK packet, it is ready to accept the first data packet. Figure 2–2 on page 25 shows an example of this type of data flow.
Freeway Client-Server Interface Control Document Echo request Not implemented at this time. Echo reply Not implemented at this time. ACK The ACK control packet indicates acceptance of a Bind or Unbind request packet from a partner TSI application. NAK The NAK control packet indicates rejection of a Bind or Unbind request packet from a partner TSI application. However, note that a TSI application must always accept an Unbind Force request. That is, it must respond with an ACK, not a NAK.
2: Freeway Client-Server Protocol Freeway Server TSI Client Application TSI Bind TSI ACK TSI Data Packet . . . TSI Data Packet TSI Unbind Force Figure 2–1: TSI Connection Data Flow (Without Arbitration) Freeway Server TSI Client Application TSI Bind TSI Bind TSI ACK TSI Data Packet TSI Unbind Force . . .
Freeway Client-Server Interface Control Document 2.1.2 TSI Data Packets A TSI data packet is a communication between a client and a server that is passed to or from the next higher level of processing (via tRead and tWrite calls when using TSI). Data packets are used after the two TSI applications have “bound” and are ready to exchange packets that control Freeway sessions and transfer data to and from the ICP protocol logic.
2: Freeway Client-Server Protocol Open Session This is the first TSI data packet that a client should send for a new Freeway session. This packet requests the Freeway server to open a session to a specific ICP, and specifies a client session ID to associate with this session. The ICP is specified as a string and must match one of the device names specified in the Freeway server boot configuration file (see the Freeway User Guide).
Freeway Client-Server Interface Control Document Get Time Not implemented at this time. Get Version This packet requests the Freeway software version string from the server. Get Version Response This packet reports the Freeway software version string in the data area. A typical string returned is Freeway Release 2.1. 2.1.2.2 Freeway Data Packets Either the client or server can issue Freeway data packets.
2: Freeway Client-Server Protocol Expedite Data Packet to ICP This packet is identical to the Data Packet to ICP, except it requests an expedited delivery to the ICP. This enables the client to send packets to the ICP that will be processed by the ICP before other data packets queued normally using the Data Packet to ICP. Data Packet From ICP This packet contains data received by MsgMux from the ICP. The server reports the client session ID and the Freeway session ID in the Freeway header.
Freeway Client-Server Interface Control Document 2.2 Example Client-Server Exchange (without Client TSI) Figure 2–4 shows an example client-server data exchange for a client application that bypasses the TSI and performs reads and writes directly through the TCP/IP BSD socket. The example consolidates the data flows shown earlier to illustrate the complete flow for a single Freeway session using an ICP protocol. Before the exchange, the client sends socket library calls to open the socket connection.
2: Freeway Client-Server Protocol 2.3 Freeway Packet Header Formats Several headers precede ICP data in packets exchanged between the client and the server. This design supports the DLI and TSI. The design also includes headers used by protocol client applications and the ICP-resident protocol logic. Note that applications that use the TSI do not include a pointer to the TSI header in buffers passed to the TSI tRead or tWrite routine.
Freeway Client-Server Interface Control Document 2.3.1 TSI Header Format The TSI header precedes all data sent over the BSD socket. If the client application is using the TSI, it does not need to construct this header; the TSI library routine will construct it and add it to the beginning of the buffer passed to the tWrite routine. Client applications not using the TSI must build this header for every packet sent to the server via the BSD socket. The TSI header must be in network byte order (big-endian).
2: Freeway Client-Server Protocol Packet Type (2 bytes) This field indicates the type of packet. There are two distinct types of packets under the TSI. One is the control packet, and the other is the data packet. If the control packet is used, the Command field is significant. Otherwise, the Command field is ignored. Valid packet types are: Control packet (1) A control packet is a packet that is received, validated, and processed by the TSI.
Freeway Client-Server Interface Control Document Echo request (4) Not implemented at this time. Echo reply (5) Not implemented at this time. ACK (6) There is no data area accompanying this packet and the Data Length field must be 0. NAK (7) There is no data area accompanying this packet and the Data Length field must be 0. ACK data (8) Not implemented at this time. NAK Data (9) Not implemented at this time. First Segment (2 bytes) This field is not used. Last Segment (2 bytes) This field is not used.
2: Freeway Client-Server Protocol 2.3.2 Freeway Header Format The Freeway header immediately follows the TSI header. All TSI Data packets must contain a Freeway header; these packets include Freeway control packets (Open Session and Close Session) and Freeway data packets (ICP protocol data). The Freeway header contains 44 bytes and must be in network byte order (big-endian).
Freeway Client-Server Interface Control Document Type (2 bytes) This field is equivalent to the usFWType field in the DLI_OPT_ARGS structure. (See the Freeway Data Link Interface Reference Guide for a detailed description of the DLI_OPT_ARGS structure.) The Type field indicates the type of packet. There are two valid types: Control (1) This type is for session control requests/responses and all other packets that will not be sent to the ICP.
2: Freeway Client-Server Protocol Data packet from ICP (3) Status (2 bytes) This field is equivalent to the usFWStatus field in the DLI_OPT_ARGS structure. This field is ignored by the Freeway server if the packet is from the client application. This field contains specific information about the cause of a failed request packet that originated from the client application. This field contains valid information only if the packet is from the Freeway server.
Freeway Client-Server Interface Control Document No session is available (3) The Freeway server is out of session entries to manage a new session. This is a serious error. Make sure that your application releases unused sessions with the Close Session request. Consult your Freeway User Guide for more information. Invalid Freeway session ID provided (4) The Freeway Session ID is invalid. Your application provided an invalid Session ID. Consider using the Freeway trace feature to isolate the problem.
2: Freeway Client-Server Protocol No more nodes are available (11) The server could not assign a node to the ICP on an Open Session request because all available nodes are in use. A Close Session request may have failed or the maximum number of ICP nodes (128) may have been reached. Client Session ID (2 bytes) When a client application requests the Freeway server to open a new session, the Freeway server copies this field into its internal session table after the session is successfully opened.
Freeway Client-Server Interface Control Document 2.3.3 ICP Header Format The ICP header immediately follows the Freeway header for all packets that are forwarded to the ICP. The ICP header consists of 16 bytes and must be in network byte order (big-endian). The use of the ICP’s header is protocol-specific. For detailed description of each field, refer to programmer’s guide for the appropriate protocol.
2: Freeway Client-Server Protocol Command (2 bytes) This field is equivalent to the usICPCommand field in the DLI_OPT_ARGS structure. For valid entries, refer to protocol specific documents. Status (2 bytes) This field is equivalent to the usICPStatus field in the DLI_OPT_ARGS structure. For valid entries, refer to protocol specific documents. Parameter 1 This field is equivalent to the usICPParms[0] field in the DLI_OPT_ARGS structure.
Freeway Client-Server Interface Control Document 2.3.4 Protocol Header Format The Protocol header immediately follows the ICP header for all packets that are forwarded to the ICP. The Protocol header is 16 bytes and must remain in the byte order of the machine on which the header is produced. The use of the Protocol header is protocol-specific. For a detailed description of each field, refer to the programmer’s guide for the appropriate protocol.
2: Freeway Client-Server Protocol Circuit ID (2 bytes) This field is equivalent to the usProtCircuitID field in the DLI_OPT_ARGS structure. Session ID (2 bytes) This field is equivalent to the usProtSessionID field in the DLI_OPT_ARGS structure. Sequence Number (2 bytes) This field is equivalent to the usProtSequence field in the DLI_OPT_ARGS structure. Reserved 1 (2 bytes) This field is equivalent to the usProtXParms[0] field in the DLI_OPT_ARGS structure.
Freeway Client-Server Interface Control Document 44 DC 900-1303C
Chapter 3 Packet Formats This chapter presents the format of each packet exchanged between the client application and the Freeway server. Individual ICP Protocol packets are not presented; please refer to the appropriate Freeway programmer’s guide for the protocol you are using. The sequence of packet data flow is presented in Chapter 2. 3.1 TSI Control Packet Formats Each TSI control packet contains a TSI header. Optionally, a TSI control packet can contain data immediately following the header. 3.1.
Freeway Client-Server Interface Control Document Data Max Packet Length = maxBufSize Max Header Length = 20 Segment Indicator = n/a Buffering Indicator = n/a Negotiable Indicator = n/a The data fields in the Bind request packet are as follows: Max Packet Length (2 bytes) This field indicates the largest packet length that the sender of this packet is able to transmit and receive.
3: Packet Formats 3.1.2 Unbind Request Packet The unbind request consists of a TSI header. Client applications should use this only if they are not using the client TSI layer. TSI Header Header Length = 20 Data Length = 0 Sequence Number = na Packet Type = 1 Command = 2 First Segment = n/a Last Segment = n/a a sequence number assigned by client 3.1.3 Unbind Force Request Packet The unbind force request consists of a TSI header.
Freeway Client-Server Interface Control Document 3.1.4 ACK Packet The ACK response consists of a TSI header. Client applications should use this only if they are not using the client TSI layer. TSI Header Header Length = 20 Data Length = 0 Sequence Number = na Packet Type = 1 Command = 6 First Segment = n/a Last Segment = n/a a sequence number assigned by client 3.1.5 NAK Packet The NAK response consists of a TSI header.
3: Packet Formats 3.2 Freeway Control Packet Formats Each Freeway control packet contains a TSI header and a Freeway header. Optionally, a Freeway control packet can contain data immediately following the Freeway header. The Freeway control packet is a type of TSI data packet. 3.2.1 Open Session Request Packet The Open Session request consists of a TSI header, Freeway header, and an ASCII character string specifying the ICP the client wants to communicate with during this session.
Freeway Client-Server Interface Control Document 3.2.2 Open Session Response Packet The Open Session response consists of a TSI header and a Freeway header, followed by the data area containing an ASCII character string specifying the Freeway software version. If an error has occurred, the server returns an error code in the status field. The Freeway Session ID is returned if the request was accepted and must be included in subsequent packets sent to the server for this session.
3: Packet Formats 3.2.3 Close Session Request Packet The Close Session request consists of a TSI header and a Freeway header.
Freeway Client-Server Interface Control Document 3.2.4 Close Session Response Packet The Close Session response consists of a TSI header and a Freeway header.
3: Packet Formats 3.2.5 Get Version Request Packet The Get Version request consists of a TSI header and a Freeway header.
Freeway Client-Server Interface Control Document 3.2.6 Get Version Response Packet The Get Version response consists of a TSI header and a Freeway header, followed by an ASCII character string specifying the Freeway server software version.
3: Packet Formats 3.3 ICP Protocol Packet Format Each ICP Protocol packet contains a TSI header, a Freeway header, an ICP header, and a Protocol header. Optionally, an ICP Protocol packet can contain data immediately following the Protocol header. The ICP Protocol packet is a type of TSI data packet, and is also known as a Freeway data packet.
Freeway Client-Server Interface Control Document ICP Headera Client ID 2 bytes Server ID 2 bytes Length 2 bytes Command 2 bytes Status 2 bytes Parameter 1 2 bytes Parameter 2 2 bytes Parameter 3 2 bytes a The ICP header is 16 bytes; a generic header is shown here. Refer to the appropriate protocol programmer's guide for valid packet formats.
Index A ACK 24, 34 ACK data 24, 34 ACK packet 48 Audience, intended 7 B Bind 22, 33 Bind request packet 45 Bit numbering 10 BSD socket 17, 20, 21 Byte ordering 10 C Circuit ID 43 Client ID 40 Client session ID 39 Client-server environment 17 Client-server exchange example 30 Client-server protocol 21 Close session 27 Close session request or response 36 Close session request packet 51 Close session response 27 Close session response packet 52 Closing a Freeway connection 20 Command 33, 41, 42 Command/respo
Freeway Client-Server Interface Control Document Exchanging data with Freeway 20 Expedite data packet to ICP 29 Expedite write to ICP request 36 F Features Freeway 16 First segment 34 Freeway client-server environment 17 features 16 overview 14 Freeway client-server protocol 21 Freeway control packet formats 49 Freeway control packets 26 Freeway data packets 28 Freeway header format 35 Freeway packet header formats 31 Freeway packet protocol 21 Freeway session ID 39 G Get time 28 Get time request 36 Get ver
Index Parameter 3 41 Private header size 35 Product support 11 Protocol header format 42 Protocol packet format ICP 55 Protocol, client-server 21 Purpose of document 7 R Reference documents 8 Required equipment 8 Reserved 35 Reserved 1 43 Reserved 2 43 Revision history 11 rlogin 16 TSI data packets 26 TSI header format 32 Type 36 U Unbind 23, 33 Unbind force 23, 33 Unbind force request packet 47 Unbind request packet 47 V VxWorks 14 W WAN interface processor 16 Write to ICP request 36 S Sequence Number 4
Freeway Client-Server Interface Control Document 60 DC 900-1303C
Freeway Client-Server Interface Control Document DC 900-1303C Customer Report Form We are constantly improving our products. If you have suggestions or problems you would like to report regarding the hardware, software or documentation, please complete this form and mail it to Simpact at 9210 Sky Park Court, San Diego, CA 92123, or fax it to (858)560-2838. If you are reporting errors in the documentation, please enter the section and page number.
Simpact, Inc.
