Freeway ® Server-Resident Application (SRA) Programmer Guide DC 900-1325I Protogate, Inc.
Protogate, Inc. 12225 World Trade Drive, Suite R San Diego, CA 92128 (858) 451-0865 Freeway Server-Resident Application (SRA) Programmer Guide © 2000 - 2011 Protogate, Inc. All rights reserved Printed in the United States of America This document can change without notice. Protogate, Inc. accepts no liability for any errors this document might contain. Freeway® is a registered trademark of Protogate, Inc. All other trademarks and trade names are the properties of their respective holders.
Contents List of Figures 7 Preface 9 1 Introduction 1.1 1.2 2 Freeway Server-Resident Applications (SRAs) . Overview of Example SRA Types . . . . . . . . 1.2.1 Basic SRA Configuration. . . . . . . . . . 1.2.2 Protocol Converter Configuration. . . . . 1.2.3 NON-API Client Interface . . . . . . . . . 1.2.4 Message Filtering SRA . . . . . . . . . . . 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Freeway Server-Resident Application (SRA) Programmer Guide 2.7.2 Secondary SRA Startup File (rc.startsra.local). . . . . . . . . . . . . 3 Interfacing to DLI/TSI and Protocol Software 43 3.1 Files Associated with DLI and TSI . . . . . . . 3.1.1 Source Files . . . . . . . . . . . . . . . . . 3.1.2 Binary Files . . . . . . . . . . . . . . . . . 3.1.3 Log and Trace Files . . . . . . . . . . . . . 3.2 DLI Normal Operation versus Raw Operation . 3.2.1 Link Configuration Parameters . . . . . . 3.2.
Contents 5.2 5.3 5.4 6 Socket Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 NFS Mount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Web Browser Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 LAN Message Filtering 6.1 6.2 6.3 6.4 6.5 6.6 msgmux Filter Hook . . . . . . . SRA Filter Functions . . . . . . . Freeway Server Message Buffers . Filter Restrictions . . . . . . . . . Example SRA Filters. . . . . . . .
Freeway Server-Resident Application (SRA) Programmer Guide 6 DC 900-1325I
List of Figures Figure 1–1: Freeway Server Data Flow (Without an SRA). . . . . . . . . . . . . . . . . 17 Figure 1–2: Example of a Basic SRA . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Figure 1–3: Example of an SRA Protocol Converter . . . . . . . . . . . . . . . . . . . . 20 Figure 1–4: Example of a NON-API Client Interface . . . . . . . . . . . . . . . . . . . 21 Figure 2–1: Example rc.startsra file from Protogate . . . . . . . . . . . . . . . . . . . .
Freeway Server-Resident Application (SRA) Programmer Guide 8 DC 900-1325I
Preface Purpose of Document This document describes the design approaches to and constraints regarding the development of a Freeway server-resident application (referred to as “SRA” throughout this document). Intended Audience This document should be read by any programmer who wishes to extend Freeway server functionality by supplementing the server code with customer-developed software.
Freeway Server-Resident Application (SRA) Programmer Guide Organization of Document Chapter 1 gives an overview of the software components necessary for the development of a server-resident application (SRA) as well as some example SRA types. Chapter 2 describes how to develop and build the SRA software. It also describes how to start your server-resident application. Chapter 3 describes how to interface the SRA with the DLI API and protocol software on the ICP boards.
Preface • • ICP2432B Hardware Description and Theory of Operation DC-900-2006 ICP2432B Hardware Installation Guide DC-900-2009 Freeway Software Installation and Configuration Support • • • Freeway Message Switch User Guide DC-900-1588 Freeway User Guide DC-900-1333 Freeway Loopback Test Procedures DC-900-1533 Embedded ICP Software Installation and Programming Support • • • • • • ICP2432 User Guide for Digital UNIX DC-900-1513 ICP2432 User Guide for OpenVMS Alpha DC-900-1511 ICP2432 User
Freeway Server-Resident Application (SRA) Programmer Guide • • • • • • • • BSCDEMO User Guide DC-900-1349 DDCMP Programmer Guide DC-900-1343 Military/Government Protocols Programmer Guide DC-900-1602 N/SP-STD-1200B Programmer Guide DC-908-1359 SIO STD-1300 Programmer Guide DC-908-1559 X.25 Call Service API Guide DC-900-1392 X.25/HDLC Configuration Guide DC-900-1345 X.
Preface The term “Freeway” refers to any of the Freeway models (Freeway 3110, 3112, 3210, 3410, or 3610). Earlier Freeway terminology used the term “synchronous” for blocking I/O and “asynchronous” for non-blocking I/O. Some parameter names reflect the previous terminology. Physical “ports” on the Freeway ICPs are logically referred to as “links.
Freeway Server-Resident Application (SRA) Programmer Guide Revision Release Date Description DC 900-1325H December 1999 Update area code and references DC 900-1325I March 2011 Update document for Protogate, Inc. and current Freeway models. Update SRA development information to FreeBSD OS. Remove references to the “Server Toolkit” which described Tornado software tools for VxWorks. All BSD software tools are now included on all Freeways.
Chapter 1 Introduction In addition to offloading interrupt-intensive communications tasks from clients, a Protogate Freeway communications server can offload additional applications processing with its unique server-resident application (SRA) functionality. SRAs operating on a Freeway server can execute such functions as data screening/stripping, data compression, byte swapping, character translation, protocol conversion, and encryption.
Freeway Server-Resident Application (SRA) Programmer Guide server using software development tools which are installed on all Freeway servers. You can then run these applications in two ways: when Freeway boots, or as requested from the interactive FreeBSD command shell. Your SRA can be designed to perform any task within the constraints of the FreeBSD operating system and the Freeway hardware/software architecture.
1: Introduction communications processor (ICP) device driver. In this fashion, data is moved from the client to the WAN protocol software executing on the ICP.
Freeway Server-Resident Application (SRA) Programmer Guide 1.2.1 Basic SRA Configuration When the client application resides within the Freeway environment instead of the client system, the application is called a server-resident application or SRA. In the Freeway environment, the DLI and TSI layers still exist. The SRA interfaces with these layer in the same manner as on the client system.
1: Introduction Client Login to Freeway Menu Ethernet Freeway Loopback Network Interface TSI TSI MSGMUX DLI SRA ICPs 4014 ICP Device Driver Figure 1–2: Example of a Basic SRA DC 900-1325I 19
Freeway Server-Resident Application (SRA) Programmer Guide Client Login to Freeway (optional) Ethernet Freeway Loopback Network Interface TSI TSI MSGMUX DLI SRA ICP 0 ICP 1 4015 ICP Device Driver Figure 1–3: Example of an SRA Protocol Converter 20 DC 900-1325I
1: Introduction 1.2.3 NON-API Client Interface Instead of running an application on the client and using DLI/TSI to receive messages from the Freeway server, you can program an SRA to read the messages from the ICP boards and send them to the client via another method such as FTP or an NFS mounted disk. Delivering the messages in this manner has the advantage of not having to do any programming on the client system. Figure 1–4 shows this configuration.
Freeway Server-Resident Application (SRA) Programmer Guide 1.2.4 Message Filtering SRA The MSGMUX software on the Freeway server has an additional feature that allows an SRA to intercept packets that are exchanged between the client application and the ICP protocol software. The purpose of this is to allow an SRA to do data filtering or format translation on the Freeway server instead of having the client application perform this additional task.
Chapter 2 Server-Resident Application Software Development The Freeway server contains all the tools that allow you to edit, compile, link and run your SRA. Before you begin to design your SRA, you should be familiar with C programming language. All of the example source code in written in C. It would help if you are also familiar with the BSD make utility. However, there are example make files included that you will be able to modify without much knowledge of the make utility.
Freeway Server-Resident Application (SRA) Programmer Guide 2.1.1 Freeway Disk Partitions The Freeway server disk drive consists of either a flash drive or a rotating disk drive. The disk drive contains a small DOS partition for booting and a larger UNIX partition for the Freeway server software. The UNIX partition is divided into several sub-partitions by the FreeBSD OS.
2: Server-Resident Application Software Development 2.1.2 Software Development Directory Structure Protogate has provided a directory hierarchy for the development of SRAs and other software on the Freeway. Listed below are the directories that are important for developing software on the Freeway server: /usr/local/freeway/client/test/sra This directory includes the source code and make file for the sample SRA (filter.c).
Freeway Server-Resident Application (SRA) Programmer Guide /usr/local/freeway/client/bsd/bin This directory contains the executable files built as a result of the compilation of each of the source files in the SRA and loopback source directories. It also contains the binary versions of the DLI and TSI configuration files that are used by the loopback and/or SRA executable files. Executable files are normally run from this directory.
2: Server-Resident Application Software Development able files. Since this directory is located in the RAM-disk partition, it is always mounted read-write. The files in this directory are copied from the permanent storage directory (/usr/local/freeway/boot.src) each time the Freeway boots. Any files placed in this directory are deleted after a reboot unless they are copied into the permanent storage area. /usr/local/freeway/boot.
Freeway Server-Resident Application (SRA) Programmer Guide Makefile This is the make file that compiles and links the filter.c file into a shared object file that is later accessed by the Freeway daemon. Refer to Chapter 6 for more information about the example filter SRA. 2.2.2 Loopback Test Programs Each protocol software distribution CDROM includes a loopback test program designed to work with the protocol image. In most cases these files are already installed on the Freeway server disk drive.
2: Server-Resident Application Software Development the three files created above and moves them to the bsd binary directory (/usr/local/freeway/client/bsd/bin). Makefile This file is a “soft link” that points to the file makefile.bsd. This file simply streamlines the make process such that you only have to type make to build the loopback program as opposed to typing make -f makefile.bsd.
Freeway Server-Resident Application (SRA) Programmer Guide 2.3 Creating a New SRA Development Environment In this section, we will go through the steps of creating a new SRA build environment using a loopback program as a starting point. Most SRAs developed on the Freeway server interface with protocol software on the ICP boards.
2: Server-Resident Application Software Development Step 3: Create the new SRA development sub-directory by entering the following command.
Freeway Server-Resident Application (SRA) Programmer Guide scp, or any other method to copy the files. If you choose to edit the files on a Windows machine, be sure that your editor maintains the text file type as UNIX (text lines end with a single line-feed) rather than DOS (text lines end with a carriage-return and a line-feed).
2: Server-Resident Application Software Development Note that the DLI and TSI log and trace files must be created on a partition which is always writable. If the original loopback program had previously been run on the Freeway server, then the log and trace files should already have a path prepended to the file name (for example, "/tmp/awsalpdli.log" and "/tmp/awsalpdli.trc").
Freeway Server-Resident Application (SRA) Programmer Guide Input file: mysratcfg Result file: mysratcfg.bin mysratcfg completed successfully. mv mysratcfg.bin ../../bsd/bin Step 2: Check the output of the make utility for errors. If errors exist, edit the source file indicated by the error, correct the error, and try the make again. Note that once the SRA is built successfully, only the SRA object file is left in the SRA source directory. All binary files have been moved to the binary directory.
2: Server-Resident Application Software Development -rwxr-xr-x -rw-r--r--rw-r--r-- 1 root 1 root 1 root guest guest guest 237519 Mar 14 23:56 mysra 73440 Mar 14 23:56 mysradcfg.bin 1608 Mar 14 23:56 mysratcfg.bin Step 2: Run the SRA simply by entering “./” followed by the SRA executable filename and then . (Note that entering just the SRA name without the “./” will also work on the default Freeway configuration because the path is not restricted, but will not work if the path is restricted.
Freeway Server-Resident Application (SRA) Programmer Guide Loopback test complete Step 3: After the program completes, you can verify that the program created the DLI and TSI trace and log files by looking in the /tmp directory which is a read-write partition in memory. These files will be overwritten each time the SRA is run.
2: Server-Resident Application Software Development • You need to increase the number of connections (NUM_CONNECTIONS) to the actual number of sessions you will be using. This will create a SESS_TBL_ENTRY structure for each connection. The current loopback program number of connections is only 2. • You should disable or remove the timer function left over from the loopback program to prevent your SRA from exiting when the timer expires.
Freeway Server-Resident Application (SRA) Programmer Guide cd /usr/local/freeway/client/bsd/bin ls -l mysra* -rwxr-xr-x 1 root guest 237519 Mar 14 23:56 mysra -rw-r--r-- 1 root guest 73440 Mar 14 23:56 mysradcfg.bin -rw-r--r-- 1 root guest 1608 Mar 14 23:56 mysratcfg.bin mount -u -o rw /usr cp -p mysra* /usr/local/freeway/boot.src mount -u -o ro /usr Step 2: Reboot the Freeway server.
2: Server-Resident Application Software Development Receive overrun errors Block check errors Parity errors Framing errors Transmit underruns Characters sent Characters received Frames sent Frames received 0 0 0 0 0 38675 38610 0 0 0 0 0 38610 38675 595 594 594 595 Loopback test complete 2.7 Starting the SRA at Freeway Boot-up Once you are able to run your modified SRA successfully from the BSD shell, you will want to put it into use on the Freeway system.
Freeway Server-Resident Application (SRA) Programmer Guide If the file rc.startsra already exists on your system, then refer to Section 2.7.2 for adding your SRA start commands. If the file doesn’t exist (you see the above results), then use the following steps to create this file: Step 1: Login to the FreeBSD shell and create the file in the non-volatile storage area: cd /usr/local/freeway/boot.src mount -u -o rw /usr vi rc.
2: Server-Resident Application Software Development When the Freeway reboots, the rc.startsra file will be copied to the /tmp/boot directory and executed after the bootcfg file is processed. Rather than use the vi editor, you may also create the rc.startsra file on your PC, then transfer it to the Freeway disk drive. Refer to Section 4.2.1 on page 59 for further information on this method. 2.7.2 Secondary SRA Startup File (rc.startsra.local) If the rc.
Freeway Server-Resident Application (SRA) Programmer Guide #!/bin/sh # # file name: rc.startsra # Additional commands for the Monitor Freeway system ● ● ● [ startup commands ] ● ● ● # # # # Allow local configuration overrides (rc.startsra.local can be created by customers to customize a specific Freeway, without the risk of being overwritten by the next software upgrade -- because software upgrades will not overwrite any rc.startsra.local* file). if [ -f /tmp/boot/rc.startsra/local ]; then .
Chapter 3 Interfacing to DLI/TSI and Protocol Software Most SRAs built to run on the Freeway server will need to access protocol software running on an ICP board. The Freeway server code includes an ICP device driver that coordinates moving data from the server platform to the ICP. The only server code that interacts with the ICP device driver is the message multiplexor (msgmux) process. The TSI code communicates with the msgmux process which makes calls to the ICP driver.
Freeway Server-Resident Application (SRA) Programmer Guide process, we will use an example SRA (simply named sra.c) along with its DLI and TSI configuration files. 3.1.1 Source Files In our example SRA, the source files we use are as follows: sra.c This is the C source file for the SRA. sradcfg This is the DLI configuration text file used by the SRA. sratcfg This is the TSI configuration text file used by the SRA.
3: Interfacing to DLI/TSI and Protocol Software /* SRA C Source Code File Name: sra.c */ main { if ( dlInit ("sradcfg.bin", (char *)work_array, callback1 ) == ERROR ) { printf("main: dlInit failed with error (%d).\n", dlerrno); op_state = TERMINATE; } ● ● ● if ( dlOpen ("icp0port0", callback2 ) == ERROR ) { printf("main: dlOpen failed with error (%d).
Freeway Server-Resident Application (SRA) Programmer Guide // SRA DLI Configuration File (text version) Name: sradcfg main { TSICfgName = "sratcfg.bin"; // Name of SRA TSI config. file (binary version) ● ● ● } // First Session Definition Section - ICP 0, Port 0 icp0port0 // Session Name { ● ● ● Transport = "conn0"; // Matches connection in SRA TSI config.
3: Interfacing to DLI/TSI and Protocol Software 3.1.2 Binary Files In our example SRA, the binary files we use are as follows: sra This is the executable file for the SRA. sradcfg.bin This is the DLI configuration binary file used by the SRA. sratcfg.bin This is the TSI configuration binary file used by the SRA. These three binary files are created by commands within the make file.
Freeway Server-Resident Application (SRA) Programmer Guide makefile.bsd sra.c cc libbsdfw GNU Compiler and Linker sradcfg dlicfg DLI Text Configuration File DLI Configuration Preprocessor sratcfg tsicfg TSI Text Configuration File TSI Configuration Preprocessor SRA Executable File sradcfg.bin DLI Binary Configuration File sratcfg.
3: Interfacing to DLI/TSI and Protocol Software ent/bsd/bin, then the DLI and TSI binary files must be moved or copied to the same directory in order for the SRA to work properly. 3.1.3 Log and Trace Files DLI and TSI log and/or trace files may be created during the normal execution of your SRA. Log and trace files are specified in the DLI and TSI configuration text file.
Freeway Server-Resident Application (SRA) Programmer Guide 3.2 DLI Normal Operation versus Raw Operation The DLI interface can be programmed in two modes of operation: Normal operation and Raw operation. The Freeway Data Link Interface Reference Guide (DC-900-1385) goes into more detail about these modes of operation. This section will give a brief summary of these modes as they pertain to programming the SRA, but they also apply to any other DLI/TSI application as well.
3: Interfacing to DLI/TSI and Protocol Software If you opened the same session in Normal operation, then all of the above actions could be performed automatically when your SRA issues the dlOpen call. The information normally supplied by the SRA for the above calls is instead placed in the DLI configuration file. In Normal operation the DLI API takes this information and uses it to automatically generate the additional dlWrite calls at session open time.
Freeway Server-Resident Application (SRA) Programmer Guide 3.2.2 Set Buffer Size If applicable to your protocol, you can set the buffer size in the DLI configuration file port definition section as in the following example: BufferSize = 256; On some protocols the following format is used instead: MsgBlkSize = 256; The DLI will send the Buffer Size command to the ICP as the first command after the Attach command.
3: Interfacing to DLI/TSI and Protocol Software Note When using non-blocking I/O, a read request must be queued to receive the Local Acks. The read buffer associated with this request remains queued. If your SRA is using DLI Raw operation, or if you are using a protocol that requires Raw operation, then you will need to handle the Local Ack packets from within your SRA.
Freeway Server-Resident Application (SRA) Programmer Guide parameters without having to go through the entire SRA make process. To do this, use the following steps: Step 1: Log into the FreeBSD Shell, and go to the operational directory: cd /tmp/boot ls -l mysra* -rwxr-xr-x 1 root -rw-r--r-- 1 root -rw-r--r-- 1 root Step 2: guest guest guest 237519 Mar 14 23:56 mysra 73440 Mar 14 23:56 mysradcfg.bin 1608 Mar 14 23:56 mysratcfg.
3: Interfacing to DLI/TSI and Protocol Software Step 4: Set the new script file executable, copy it to the non-volatile storage area, and run the script file. The script file will mount the /usr partition back to read-only: chmod u+x dliupdate mount -u -o rw /usr cp -p dliupdate /usr/local/freeway/boot.src ./dliupdate Once the above procedure is in place, it becomes easier to update any parameters in the DLI configuration file.
Freeway Server-Resident Application (SRA) Programmer Guide 56 DC 900-1325I
Chapter 4 SRA Design Tips and Restrictions This chapter describes some additional information that is useful to know when designing and running your SRA. Also included are some system limitations to watch out for. 4.1 Managing RAM Memory The Freeway server utilizes RAM memory in many ways during normal operation. Buffer pools, queues, system logging, and RAM-disk partitions all make use of the available RAM memory. The default size of the RAM-disk partition is 128 Megabytes.
Freeway Server-Resident Application (SRA) Programmer Guide 4.1.2 TSI Configuration The TSI buffer pool can also consume a large area of memory. Two parameters in your SRA’s TSI configuration file are of particular importance to memory utilization: MaxBufSize and MaxBuffers. These parameters are described in the Freeway Transport Subsystem Interface Reference Guide.
4: SRA Design Tips and Restrictions want to save, consider using the BSD shell to create a separate directory in the read-only /usr partition and moving the files there. 4.2 Updating Files The Freeway server makes use of read-only partitions and RAM-disk partitions specifically so the server can be switched off at any time without damage to the disk drive. Operational files are stored in the read-only partitions and copied to the RAM-disk partitions at boot time.
Freeway Server-Resident Application (SRA) Programmer Guide tion.
4: SRA Design Tips and Restrictions What this menu item does is copy all of the files in the operational directory (/tmp/boot) back to the non-volatile storage directory (/usr/local/freeway/boot.src) in one action. This saves you from having to type BSD commands to mount the /usr partition as read-write and manually copy each file to non-volatile storage. At this point you normally would want to reboot the Freeway server so that it will use the updated files.
Freeway Server-Resident Application (SRA) Programmer Guide The following procedure is an example of updating the bootcfg file on the Freeway server using the CDROM update method. Step 1: If you have a copy of the original bootcfg file on your client system or PC, edit this file to make the desired changes, or create a new bootcfg file from scratch. Step 2: Create a text file called command.sh on your client system or PC.
4: SRA Design Tips and Restrictions This is especially true with the FreeBSD operating system on the Freeway server. When transferring text files to the Freeway server, care must be taken to make sure that the text files are in UNIX format. Script files, make files, and configuration files will not be executed properly under BSD if they are in Windows format. For example, if the bootcfg file used in the update procedure in Section 4.2.
Freeway Server-Resident Application (SRA) Programmer Guide After completing the above commands, when you open the file again with the vi editor, you will see that the Ctrl-m characters are gone. If you edited the file in the operational directory, be sure to save the changes by using the menu (5-3-3) or other method. 4.3 Message Logging The "C" file descriptors stdin, stdout, and stderr can be used (via the standard I/O library functions printf, fprintf, etc.
4: SRA Design Tips and Restrictions The next parameter is a format string, equivalent to that which would be used in a printf statement, followed by the variable-length parameter list of values that get expanded into the formatted string. The log entry contains up to 255 characters. Consult the Freeway User’s Guide for the procedure to display log messages. 4.3.2 Syslog The syslogd daemon provides UNIX-style logging for applications running on the Freeway server.
Freeway Server-Resident Application (SRA) Programmer Guide contains /var/log/, which is normally enough for several weeks of uptime. You can run the "df /var/log" command occasionally to tell you how much free space is left. On Freeway servers with rotating hard drives, you can set up the “s2g” partition as a read-write partition and direct your syslog entries to be written there as outlined in Section 4.4.1.
4: SRA Design Tips and Restrictions much more disk storage space than the flash drive, making it ideal for storing large numbers of messages and/or log entries. The Freeway Software CD pre-installs all the Freeway software on a rotating hard drive, just as it does on a flash drive. The /usr partition is still mounted as read-only.
Freeway Server-Resident Application (SRA) Programmer Guide Note Some Protogate-supplied SRA installations (such as the Monitor) will mount the “s2g” partition as “/var” instead of “/cache”. On these systems, the /var partition on the hard drive takes the place of the RAM-disk partition found on standard Freeway servers. Once you start using a disk file system mounted read-write, you can no longer just power off the Freeway server at any time.
4: SRA Design Tips and Restrictions 4.4.2 Non-Blocking (Asynchronous) I/O All DLI and TSI applications on the Freeway server must use non-blocking (asynchronous) I/O. The DLI and TSI libraries do not support blocking (synchronous) I/O on the server. If you need a blocking I/O capability, you must develop a layer to provide the blocking characteristics. This layer would lie between your blocking application and the library. 4.4.
Freeway Server-Resident Application (SRA) Programmer Guide VI-200-3243: FWSER 5.
4: SRA Design Tips and Restrictions This will display all the tasks running on the Freeway server. Look for your SRA name and note the PID number (as indicated in bold in the example display above). You can also get the same task list above by typing “ps -aux” from the BSD shell.
Freeway Server-Resident Application (SRA) Programmer Guide 72 DC 900-1325I
Chapter 5 Interfacing with the SRA Chapter 3 discussed how the SRA interfaced with ICP protocol software using the DLI API. This chapter outlines some of the ways that users and client systems can interface with the SRA. 5.1 Initialization Files The protocol loopback programs are designed to be run from the BSD shell, as such they use the console to input data from the user pertaining to which ICP and port to run on.
Freeway Server-Resident Application (SRA) Programmer Guide Figure 5–1 shows an example of an SRA initialization text file. In this example file, each text field is separated with a ‘|’ separator character making it easy to use UNIX string extraction and conversion routines such as strtok_r and strtol. ################################################################ # # SRA SERIAL PORT LIST (/tmp/boot/sra_init.dat) # # Field positions and lengths are fixed. # The key field can hold 1-64.
5: Interfacing with the SRA Since separate data packets in the TCP/IP stream may get sent as a single TCP/IP transmission, you would need to design your own TCP/IP packet format in order for the SRA and client program to be able to read the data correctly. A simple packet design example is shown below: token length command data Where the fields of the packet could be as follows: • token (32-bit) - Any unique 32-bit pattern that would be recognizable as the start of a packet (such as 0xABCDEF01).
Freeway Server-Resident Application (SRA) Programmer Guide The NFS configuration consists of 1. a server containing directories and files to be accessed, and 2. one or more clients that remotely access the data that is stored on the server machine. A Freeway can be configured as an NFS client, an NFS server, or even as both client and server at the same time.
5: Interfacing with the SRA 5.4 Web Browser Interface The Freeway can easily be configured as a web server to allow a standard web browser on any client system to access Freeway menu functions. If you are proficient in HTML and PHP, you can design a similar web browser interface to access your SRA.
Freeway Server-Resident Application (SRA) Programmer Guide 78 DC 900-1325I
Chapter 6 LAN Message Filtering This chapter describes the recommended approach to implementing a server-resident filter that edits messages moving to and from the WAN. This approach is appropriate regardless of whether the client application transferring data executes on the Freeway server itself (such as an SRA) or on a remote computer connected to the Freeway server through a LAN. The message multiplexor (msgmux) process controls the movement of all messages to and from the WAN.
Freeway Server-Resident Application (SRA) Programmer Guide Client Client Application DLI TSI TCP/IP Socket Interface Ethernet Freeway TCP/IP Socket Interface SRA Filter Functions: toWANFilter fromWANFilter TSI MSGMUX ICPs 3034 ICP Device Driver Figure 6–1: WAN Message Filtering Example 80 DC 900-1325I
6: LAN Message Filtering way's msgmux process. Once loaded, the msgmux process executes the fwymod_init() function in that library. 2. It provides a function called muxFilterHook(), which can be used to specify two user-written functions: one to be called for every packet received from a WAN link and another to be called for every packet destined for a WAN link. Together these two actions make it easy to create filter SRAs.
Freeway Server-Resident Application (SRA) Programmer Guide muxFilterHook function can be called at any time, and any number of times, to begin, end, or resume filtering of messages. 6.2 SRA Filter Functions An SRA filter function is declared as follows: int sraFilter(char *pBuf); The argument in the call is defined as follows: pBuf This is the buffer containing the data to be filtered. The address is that of a structure referred to as the ICP header. 6.
6: LAN Message Filtering TSI header Freeway header ICP header Protocol header . . . 3032 Protocol data Figure 6–2: Freeway Server Message Buffer The ICP header includes a field that specifies the number of bytes in the combined protocol header and data areas. If a filter function changes the number of bytes in the protocol data and header area, it must change the byte count field in the ICP header as well. Failure to do so results in failures at the ICP or the protocol application.
Freeway Server-Resident Application (SRA) Programmer Guide 6.4 Filter Restrictions Filters are limited in what they can and can’t do, and some of these restrictions are described in this section. Most notable among these is the issue of byte ordering. As mentioned in Section 6.3, the pointer received as a parameter by a filter function points at the ICP header, which is always in network byte order.
6: LAN Message Filtering Support Department as described on page 14 for help in determining how to identify a session for a given protocol. It was mentioned earlier that the protocol command might need to be scanned to determine the type of packet being filtered. However, each protocol is different, and different protocols use different values for their respective commands.
Freeway Server-Resident Application (SRA) Programmer Guide 6.5 Example SRA Filters The source code for two example filter functions (one which filters messages to the WAN, and another which filters messages from the WAN) is in freeway/client/test/sra. Specifically, the filter.c file contains the source code for the two filter functions which implement DOS to UNIX text format conversions (as described in Section 4.2.4 on page 62).
6: LAN Message Filtering Next, the function strips all carriage return characters from the data. Recall that one of the limitations on filters is that special control sequences to be detected and replaced must be contained entirely within a buffer. Hence, the function implicitly assumes that there is no carriage return in the data stream unless it is part of an EOL sequence. Note that the data size is updated whenever a carriage return is removed from the data stream.
Freeway Server-Resident Application (SRA) Programmer Guide Next, the function inserts carriage returns as needed, incrementing the data count and monitoring for buffer overflow as it does so. Finally, the packet size in the ICP header is updated to account for any insertions that were made. 6.6 Building the Example Filter Code This example code is intended to be compiled directly on the Freeway server.
Index A Asynchronous I/O 69 Attach command 69 Audience 9 B Blocking I/O 69 Building the SRA 33 files 27 C Creating SRA directory 30 Customer support 14 Customizing the SRA 36 D Development environment 23 server-resident application software 23 DLI attach command 69 DLI configuration parameters maxSess 57 traceSize 57 DLI/TSI Interfacing to 43 Document conventions 12 Documents reference 10 Drives rotating 66 F File management 58 DC 900-1325I Files filter.c 86 initialization 73 libbsdcs.a 26 libbsdfw.
Freeway Server-Resident Application (SRA) Programmer Guide I ICP access to links 69 iMaxBufSize 87 Interfacing to DLI and TSI 43 I/O, asynchronous 69 I/O, blocking 69 I/O, non-blocking 69 I/O, synchronous 69 L LAN message filtering 79 libbsdcs.a 26 libbsdfw.a 26 Library files libbsdcs.a 26 libbsdfw.
Index T Technical support 14 TraceSize parameter 57 TSI configuration parameters maxbuffers 58 maxBufSize 85 maxbufsize 58 maxConns 58 U Updating files 59 CDROM method 61 File Transfer 59 Menu 5-3-3 method 59 DC 900-1325I 91
Freeway Server-Resident Application (SRA) Programmer Guide 92 DC 900-1325I
Freeway Server-Resident Application (SRA) Programmer Guide DC 900-1325I 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 Protogate at 12225 World Trade Drive, Suite R, San Diego, CA 92128, or fax it to (877) 473-0190. If you are reporting errors in the documentation, please enter the section and page number.
Protogate, Inc.