What is CFS-400 ?

CFS-400 is:

CFS-400 provides the infrastructure to enable ILE RPG developpers to create network services by calling a set of simple functions provided by CFS-400. ILE RPG developpers can create programs that connect to network services such as web services and also create programs that accept connections from network clients such as web browsers or any other protocol. Specifically, CFS-400 provides:

• A ready-to-run TCP server implementation for accepting connections from TCP clients.
• An implementation of the websocket protocol (a websocket echo server is given as an example).
• An application development framework for creating TCP clients and TCP service handlers in ILE RPG; those service handlers will be called by the server to handle client connections.

The following diagram shows where CFS-400 fits with different network agents:

TCP Server implementation

The TCP server implementation is made up of a main server daemon program that will accept connections from clients and a service handler program that will service client connections. This service handler will link ILE RPG programs to conencting clients via the CFS-400 API. The main daemon is implemented by the CLARAD.C source file and the service handler is implemented by the CLARAH.C source file.

A simple service handler is provided by CFS-400 that implements a basic echo service. This basic handler serves as a base to build an in-house proprietary service or perhaps a custom implementation of a standard service such as FTP or HTTP. The main purpose of CFS-400 is to provide the core framework for implementing TCP network services as easily as possible.

Application development framework

The application development framework is a set of functions that allow the reading and writing of TCP sockets. These functions can be used to create programs that connect to TCP services (such as HTTP servers) and service handlers that can be called by the CFS-400 daemon. Also provided is a set of functions that can implement a websocket client or websocket server.

How the CFS-400 TCP server Works

When the main daemon (CLARAD) is executed, a number of handler jobs are spawned (the number of jobs is specified as a command line argument to CLARAD). Each of these handler jobs (implemented by the CLARAH.C source file) has a local communication link with the main daemon; this link is a local domain socket, also known as a stream pipe. This stream pipe will enable the main daemon to pass over the client connection socket to the connected handler (CLARAH in this illustration).

When a client establishes a connection with the main daemon, the main daemon will obtain a connection socket from the system. The main daemon will then pass over this connection socket to an available handler job.

Once the handler job obtains the communication socket with the client, the main daemon is no longer involved and the client communicates directly with the handler job.

The stream pipe with the main daemon remains open however. The main daemon becomes available for other connecting clients. As other clients connect, the main daemon will hand over their communication socket to an available handler job. If no handler job is available, the main daemon can spawn additional handler jobs as required or until a certain threshold is reached (this threshold is specified as a command line agument to the main daemon).When the client disconencts from the handler job (or when the handler job disconnects from the client), the handler job will advise the main daemon via its stream pipe that it has become available to handle another client connection and this process will continue until the main daemon is shutdown. At present, when the main daemon is shutdown, all handler jobs are also terminated.

Building CFS-400 from source code

Upon receiving the sources, copy the files on your AS400 in a source file named QCSRC (the CFSREG source needs to be copied in the QDDSSRC source file). Next, you will create the following modules (compilation commands follow):

• CFSAPI
• CLARAD
• CLARAH
• CSLIST
• CSSTR
• CSWSCK

From the AS400 command line, execute the following comamnds to create the above modules:

Next, you need to create a SRVPGM object that exports the CFS-400 toolkit functions (we will call it CFSAPI) by issuing the following command:

Next, you must create the CFSREG file as follow:

You will now create the the main TCP server (daemon) and the demonstration echo handler (respectively CLARAD and CLARAH) by issuing the following command:

CFS-400 example ILE RPG service for use by network clients

To show how an ILE RPG program can be used to run as a handler, you will create the ILE RPG version of the websocket echo handler as follow: copy the ECHO.RPGLE and the ECHO.RPGH files from this repository to the QRPGLESRC source file on your system. You will then compile this source into a module by issuing the following command:

Next, you will create a SRVPGM object from the above module (notice this uses the CFSAPI service program built above):

For the CLARAH program to use the ILE RPG echo service, a record must be inserted into the CFSREG file:

Where LIBNAME is the name of the library where the ECHOSRV service program resides. All other fields have to be as shown above. Now, to test this ILE RPG service, you can execute the CFS-400 daemon from the command line (in production, this command would be run in its own subsystem) and instruct it to use the ECHOSRV service by issuing the follwng command (this assumes that CLARAH is also in library LIBNAME although this is not mandatory: the service library does not have to match the library where the daemon resides):

The above command will run three handler jobs and the main daemon job:

There are 3 handlers running, waiting for client connections; if all 3 handlers are busy servicing connections, then a fourth handler will be executed to handle an additional connexion (that is the meaning of the '3' '4' parameters to the command). To test the handler, you can open a websocket test client from your web browser at http://www.websocket.org/echo.html:

In the "Location" text box, input your AS400 machine address:

Notice that the port number is the same as the one from the command line used to execute the CFS-400 daemon. Click on the "Connect" button. You should get a "CONNECTED" message in the "Log" text area. You can then write messages to send over to your ILE RPG service in the "Message" text box and by clicking on the "Send" button. Your ILE RPG service will echo back the data you sent in the "Log" text area. One of your CLARAH jobs is busy servicing this connection. The other two CLARAH jobs are available for other connections. When you click on the "DISCONNECT" button, the CLARAH job that was servicing your connection continues to execute but is no longer busy and is now available for another connection.

This example shows how easy it is to create web front ends with CFS-400. You are not limited to the Websocket protocol. CFS-400 provides all the functions needed to use basic TCP sockets (either secured with SSL or not) and create your own networking protocols or to create clients for any other networking protocol: this means you can create your own HTTP, FTP, SMTP, etc clients in ILE RPG (but this requires in-depth knowledge of those protocols however)!