1.1. Message Switch Overview

The Message Switch is a Server-Resident Application (SRA) which runs in a Freeway server. It implements a switching function which transfers all data received by a set of client application sessions to one or more other sessions. The Message Switch software uses Simpact's Data Link Interface (DLI to open and manage Freeway client sessions to transmit and receive data.

The following is a quick overview of how to use the Message Switch software:

• Customize the provided configuration files to define the required client sessions for your Freeway environment, and to load and run the Message Switch.

• Boot the Freeway server. The Message Switch automatically configures itself, uses DLI to attach to one or more ICP ports, and begins transferring data. (ICP boards, or Intelligent Communications Processor boards, are the Protogate hardware product which implement various data communications protocols for sending and receiving data on a WAN link.)

• To communicate through the Message Switch, a client application can open a socket and send and receive data using the Freeway's IP address. Example programs are provided for testing purposes.

The following types of data can be exchanged through the Message Switch:

• Loopback

• Multicast (on Freeway platforms that support Multicast)

• Unicast

• WAN

The Message Switch offers an extremely flexible range of data-switching capabilities, all of which are available simply by modifying configuration files. For example, it is possible to use the Message Switch to translate data streams between different protocols, or between similar protocols with different characteristics (see Section A.3). Data streams can be replicated to multiple destinations (see Section A.4). Data streams from several sources can be combined into one (or more) destinations (see Section A.5). And the sources or destinations of any of these data streams can be WAN lines or IP unicast or multicast addresses, in any combination.

In addition, a Freeway which is running the Message Switch can be used by traditional DLI client application programs, in either Raw or Normal operation, and using either Simpact's DLI library or a simple socket interface (see Section A.6).

The Message Switch can greatly simplify the writing of client application programs which do not use Simpact's DLI library. For example, the Message Switch relieves the client application of the need to send and receive all the packets which are normally required to attach, bind, configure, and enable each data link. This is possible because the Message Switch does all the work necessary to bring up a link using data from its own configuration files (such as swdcfg).

After the Freeway and Message Switch are running, the client application program can simply open a socket and start sending and receiving data. For an example, see Section A.8 and the remarkably short program freeway/client/test/switch/apinull.c.

1.2. Freeway Server

Simpact provides a variety of user-programmable, wide-area network (WAN) connectivity solutions for real-time financial, defense, telecommunications, and process-control applications. Simpact software includes a wide variety of legacy and specialty protocols that run on Simpact's intelligent communication processor (ICP) boards residing in a Freeway communications server. The protocol software is independent of the hardware and operating system environment.

The Freeway server is a stand-alone box with pre-installed ICPs. It provides multiple data links and a variety of network services to LAN-based clients. Figure 1-1 shows a Freeway server configuration where the client application communicates with the Freeway ICPs using Simpact's data link interface (DLI). A variety of client operating systems are supported (UNIX, VMS, and Windows NT).

The Message Switch runs in the Freeway server processor (shown in Figure 1-1) and uses DLI to access WAN and IP links through ICP boards.

1.3. Message Switch Configuration Example

The Message Switch connects data streams between (and among) ICP devices, somewhat like an old-fashioned plug-in telephone switchboard. Figure 1-2 shows an example Freeway configured with four ICP devices:

1. Two WAN ICP boards (icp0 and icp1)

2. Two ICP_IP pseudo-devices (icp2 and icp3)

The Message Switch is shown as a set of arrows in the center of the circle. These arrows represent the switching paths of various data streams (icp0port0 to icp2port0, for example).

The Freeway and the Message Switch use several configuration files to specify the setup of various aspects of the system. These configuration files are described in more detail in Section 2.2. In the example system shown in Figure 1-2 the configuration is as follows:

In summary, the bootcfg file defines the ICP devices, the muxcfg and swtcfg files define the transport layer between the Message Switch and Freeway, the swdcfg file defines the characteristics of each data link, and the switch.cfg file defines the interconnections between data links.

1.4. DLI Concepts for the Message Switch

The Message Switch software uses Simpact's Data Link Interface (DLI), which is a high-level, session-oriented application programming interface (described in the Freeway Data Link Interface Reference Guide).

There are several DLI configuration concepts that you must keep in mind when using the Message Switch software:

• The DLI configuration file needs to include only those session parameters whose values differ from the defaults. Appendix B shows an example swdcfg DLI configuration file and swtcfg TSI configuration file for the Message Switch.

• The Message Switch software uses DLI Normal operation. Therefore, each session must have the "protocol" DLI configuration parameter set to a specific protocol; for example:

      protocol = "FMP"
  

• If you are using a Simpact protocol in conjunction with the Message Switch software, DLI Normal operation allows you to define protocol-specific link configuration options in the DLI configuration file. Figure B-4 shows an example session configuration for FMP. Refer to your particular protocol Programmer's Guide for complete link configuration option details.

2.1. Overview

The Message Switch is a server-resident application (SRA) which runs in a Freeway server. It implements a switching function which transfers all data received by a set of client application sessions to one or more other sessions.

There is no restriction on the type of sessions which can be switched other than that they use DLI Normal operation. This allows data to be switched between ICP devices of different types (for example, ICP2432, ICP2424, or even ICP_IP devices), using different protocols, at different data rates, etc. Data from several sources can also be switched simultaneously to a single destination, or data from a single source may be switched to several destinations, in any combination.

2.2. Configuration Files

The five configuration files listed below must be present in the freeway/boot directory to tell the Message Switch how to switch data. The product distribution includes example configuration files containing comments describing the syntax and function of the commands allowed by each configuration file (these files are also shown in Appendix A and Appendix B). Together, these files configure Freeway so that the images built with the freeway/client/test/makeapi script can be used to test various features of the Message Switch.

Also included with the product are three object files, each customized to run with a different type of Freeway:

In addition to the configuration files and the object files, the distribution includes:

To use the Message Switch, follow the "Quick Start and Test" procedure in the next section. After you reboot your Freeway, the Message Switch starts running. It configures itself automatically, using the setup specified in your configuration files.

2.3. Quick Start and Test of the Message Switch

To quickly get the Message Switch software running and tested, perform the following steps:

1. Copy the three Message Switch object files (sw486.o, sw68k.o, and swppc.o) to your Freeway boot directory.

2. Copy the example Message Switch configuration files (bootcfg.sw, switch.cfg, swdcfg, and swtcfg) to your Freeway boot directory.

3. Change each occurrence of the string "192.168.135.22" in the file bootcfg.sw to the IP address of machine "A".

4. Add a default route line to the bootcfg.sw file. For example:

                 route_add = 0.0.0.0 192.168.135.22
              
   

5. Boot the Freeway, being sure that the boot parameters in your Freeway boot directory specify

                 Configuration File Name : bootcfg.sw
              
   

6. Notice a lot of configuration and status messages produced by the Message Switch immediately after the "FREEWAY SYSTEM ONLINE" message appears. The final message should say:

            "STATUS:  All Message Switch sessions ready."
              
   

7. Copy the Message Switch test program and build script to machine "A". These are the two files "makeapi" and "apinull.c", in the freeway/client/test/switch/ directory.

8. Change each occurrence of the string "192.168.135.1" in the file apinull.c to the IP address of your Freeway.

9. Execute the test program build script on the test machine (machine "A"). For example, if it is a UNIX machine, type "./makeapi". This builds four programs: "apinull0", "apinull1", "apinull2", and "apinull3", which will send/receive packets to the Freeway icp1port0 through icp1port3.

10. On machine "A", run the apinull0 program. This sends a small packet to the icp1port0 device on the Freeway, which the Message Switch receives and returns (via icp1port0) directly back to the apinull0 program. Section A.8.1 shows the switch.cfg file specifications.

11. On machine "A", run the apinull1 program. This sends a small packet to the icp1port1 device on Freeway, which the Message Switch receives and sends to several other places (as specified in the switch.cfg file), in addition to returning it (via icp1port1) directly back to the apinull1 program. Section A.8.2 shows the switch.cfg file specifications.

12. On machine "A", run the apinull2 program. This sends a small packet to the icp1port2 device on Freeway, which the Message Switch receives and sends through the icp2/icp3 connection (as specified in the bootcfg.sw and the switch.cfg files). When it receives the message packet (from icp3), it sends it (via icp1port2) to the apinull2 program. Section A.8.3 shows the switch.cfg file specifications.

To test the TCP/IP listening capabilities of the Message Switch and Freeway (see also Section A.8.5):

13. Open three separate terminal (xterm) windows.

14. In the first window, telnet to port 13824 of Freeway. For example, "telnet freeway0 13824". If you have previously run the apinull1 test program, this telnet window will immediately receive the string "abcdefghijklmnopqrstuvwxyz".

15. In the second window, telnet to port 13825 of Freeway. For example, "telnet freeway0 13825". If you have previously run the apinull1 test program, this telnet window will immediately receive the string "abcdefghijklmnopqrstuvwxyz".

16. In the third window, telnet to port 13826 of Freeway. For example, "telnet freeway0 13826". This telnet window will not receive data immediately, unless you have typed any characters in the first or second telnet sessions.

17. Type "telnet 1" in the first telnet window, followed by a carriage return. This string should be received by both of the other two telnet sessions.

18. Type "telnet 2" in the second telnet window, followed by a carriage return. This string should be received only by the telnet session in the first window.

To test the TCP/IP connecting capabilities of the Message Switch and Freeway (see also Section A.8.6):

19. Copy the ICP_IP loopback test program and build script to a separate directory in machine "A". These are the two files "makeloop" and "loopback.c" in the freeway/client/test/iploop directory.

20. Execute the loopback program build script on machine "A". For example, if it is a UNIX machine, type "./makeloop". This builds 12 programs:

                     tcploop2110    tcploop2112    tcploop2114 
                     tcploop2120    tcploop2122    tcploop2124 
                     udploop2130    udploop2132    udploop2134 
                     mcastloop2140  mcastloop2142  mcastloop2144
            

21. On machine "A", run the tcploop2120 program. This opens two listening TCP sockets to which Freeway can connect. After a minute or two (you must wait until Freeway retries to connect), you should see the tcploop2120 program report "sockA and sockB ready".

22. Open two separate terminal (xterm) windows.

23. In the first window, telnet to port 13828 of Freeway. For example, "telnet freeway0 13828".

24. In the second window, telnet to port 13829 of Freeway. For example, "telnet freeway0 13829". If you have previously run the "apinull1" test program, this telnet window may immediately receive the string "abcdefghijklmnopqrstuvwxyz".

25. Type "telnet 3" in the first telnet window, followed by a carriage return. This string should be received by the telnet session in the second window.

26. Type "telnet 4" in the second telnet window, followed by a carriage return. This string should be received by the telnet session in the first window.

If you have an ICP board in your Freeway, and can load it with a protocol, you can also:

27. Uncomment (and modify, if necessary) the lines in bootcfg.sw which define icp0 (Figure B-1).

28. Uncomment the lines at the end of switch.cfg which specify a switch connection between icp1port3 and icp0port2/3 (Section A.8.4).

29. Install a loopback cable between port2 and port3 of icp0.

30. If necessary, modify the definitions of the icp0port2 and icp0port3 sections of the swdcfg configuration file to match the protocol and type of loopback cable you have (internal/external clocking, etc.).

31. Reboot your Freeway.

32. On machine "A", run the apinull3 program. This will send a small packet to the icp1port3 device on Freeway, which the Message Switch receives and sends to icp0port2. The loopback cable causes the message to arrive at icp0port3, where the Message Switch receives it and sends it (via icp1port3) back to the apinull3 program. Section A.8.4 shows the switch.cfg file specifications.

If you have an ICP_IP protocol module [such as Simpact's Translator for FMP (TFM) product] you can also:

33. Uncomment (and modify, if necessary) the line toward the end of bootcfg.sw which loads your protocol translator module (see Figure B-1). For example,

                  "sra_module = ipfmp486.o"
               
    

34. Change the lines which specify ipnull in the bootcfg.sw file to specify your protocol module for icp2 and icp3, and/or in icp4 and icp5 (see Figure B-1). If you have the TFM product you would change the lines to (for example):

             "internal_protocol = ipfmp"
               
    

35. Reboot Freeway.

36. Test with the appropriate protocol loopback program (for example, for the ipfmp protocol module you could test loopbacks on icp2port0 and icp2port1 with the fmpalp test program).

To test sending and receiving of multicast packets, you can also:

37. If your Freeway has more than one ethernet interface (you have uncommented and modified the "added_interface_xxx" lines at the end of bootcfg.sw), you may also have to add a "route_add" line to the bootcfg.sw file, to specify which interface the multicast packets should be sent through (as in the commented-out route_add example toward the end of bootcfg.sw). See Figure B-1.

38. Uncomment the two lines in switch.cfg which specify a link between icp5port0 and icp5port1 (see Section A.8.2).

39. Change the three lines in switch.cfg which specify the link between icp1port2 and the icp2/icp3 connection to use the icp4/icp5 connection instead (a commented-out example is shown in that file; you can simply comment-out the icp2/icp3 lines, and uncomment the icp4/icp5 lines). (see Section A.8.3).

40. Reboot Freeway.

41. On machine "A", run the apinull2 test program to test the icp4/icp5 connection (which uses multicast). Section A.8.3 shows the switch.cfg file specifications.

42. If you are using a protocol module other than ipnull, you can also test with the appropriate protocol loopback program on icp4port0 and icp4port1, as in test step 36 above. It may be necessary to modify the loopback test program to allow use of icp4, and to add definitions for icp4port0 and icp4port1 to the loopback test program's DLI configuration file.

2.4. ICP_IP Devices

The ICP_IP devices which have been added to Freeway's capabilities behave similarly to any ordinary ICP device (ICP6000, ICP2432, etc.). The desired configuration of an ICP_IP device must be specified in the boot configuration file (this is the file which is specified as the "Configuration File Name" field of the Freeway boot parameters). An example configuration file containing ICP_IP configuration specifications is provided with the Freeway software release (called bootcfg.ip). See that file for a description of the configuration options which have been added to support ICP_IP.

The steps required to use the new ICP_IP devices are:

1. Edit bootcfg.ip to change the IP addresses as appropriate for your system.

   • All references to "192.168.135.1" should be changed to the IP address of your Freeway system

   • All references to "192.168.135.22" should be changed to the IP address of a system (or systems) which will send or receive IP packets to or from your Freeway system

   • If you plan to use the second ethernet interface, all references to "192.168.136.1" and "192.168.136.22" must also be changed

2. Change the following boot parameters for your Freeway system:

   • Change the "FREEWAY Server Name" and "FREEWAY Inet Address" to tell the Freeway system where it is configured in your network.

   • Change the "Boot Server Name" and "Boot Server Inet Address" to specify a machine from which the Freeway boot directory can be accessed.

   • Change the "System Boot Directory" to point to your Freeway boot directory.

   • Change the "System Boot File Name" to the name of your Freeway image.

   • Change the "Configuration File Name" to bootcfg.ip.

3. Reboot Freeway.

4. The new ICP_IP devices can now be used in either raw or normal mode by any client application, simply by specifying the appropriate ICP name in the call to dlOpen. For example, if Freeway is configured as shown in the supplied bootcfg.ip file, a call to dlOpen for a port definition with BoardNo set to 3 will use a socket configured as specified in icp3 in bootcfg.ip.

   The mapping looks like this:

   • The dlOpen function is called with a session name. For example: server0icp3port4

   • The session name is matched to a section in the DLI configuration file, and the appropriate BoardNo and PortNo values are saved. For example:

                       BoardNo = 3
                       PortNo = 4
                    
     

   • The BoardNo, appended to the ascii string "icp", is used to find the device specified in the Freeway boot configuration file. The device specifies the type of data transfer to be used, local and foreign IP addresses, base port numbers, etc. The PortNo from the DLI configuration file is added to the local_port_base and foreign_port_base fields from the boot configuration file to generate the port numbers used for this IP device.

     For example:

                       device = icp3
                       type = sock_dgram
                       local address = ANY
                       local port = 0x2130 + 4 = 0x2134
                       foreign address = 192.168.135.22
                       foreign port = 0x2130 + 4 = 0x2134
                    
     

   • To test an ICP_IP link, you may run the "makeloop" script on a UNIX machine to compile the loopback test programs. This script and the accompanying loopback.c source file reside in the directory freeway/client/test/iploop. These programs perform the same function for ICP_IP links as the physical loopback cables perform for real wired FMP links; they take data being sent to one ICP_IP link and return it to the next adjacent ICP_IP link.

     • Make sure the Freeway system has an ICP_IP device pointing to the UNIX machine where the test program is running, (change the foreign_address to the IP address of the machine where the test program is running) then run any normal test program (for example, fmpalp).

     • The loopback test programs correspond to the ICP_IP devices as configured in the supplied bootcfg.ip file:

                                    server0icp1port0 (and port1) tcploop2110 
                                    server0icp1port2 (and port3) tcploop2112 
                                    server0icp1port4 (and port5) tcploop2114
           
                                    server0icp2port0 (and port1) tcploop2120 
                                    server0icp2port2 (and port3) tcploop2122 
                                    server0icp2port4 (and port5) tcploop2124
           
                                    server0icp3port0 (and port1) udploop2130 
                                    server0icp3port2 (and port3) udploop2132 
                                    server0icp3port4 (and port5) udploop2134
           
                                    server0icp4port0 (and port1) mcastloop2140 
                                    server0icp4port2 (and port3) mcastloop2142 
                                    server0icp4port4 (and port5) mcastloop2144
                          
       

       Note: The mcastxxxx programs must be compiled and run on a multicast-capable machine, and are necessary only for testing a multicast-capable Freeway.

       For example, if you set foreign_address for icp3 to the IP address of a machine running udploop2134, you can run fmpalp on any client machine (with the "server" field in fmpaltcfg pointing to your Freeway), select "3" when asked for the "ICP board on which to run test", select "4" when asked for the "Even port number", and fmpalp will run normally. The data will be going from fmpalp on your client machine, to Freeway, out the ICP_IP device to the machine running udploop2134, back to Freeway on the alternate-numbered ICP_IP link, then back to fmpalp on your client machine.