Iris was designed to allow interprocess communication between any application and a pool of pre-started programs. For this document and the initial development the focus has been on communication between a web server and a pool of Progress batch clients, however, keep in mind that many other combinations are possible.
The application consists of three basic parts. First is the request courier (iris.pl, called iris). It is launched by the requesting program (the web server) and handed any necessary data. The courier will contact the request administrator (iris_rad.pl,referred to after this as iris_rad) and get the address of an available request executioner (iris_rex.pl / iris_rex.p, referred to collectively after this as iris_rex). The courier will then connect to the executioner, pass in the data it is carrying and wait for a response. The executioner will parse the data, extract the name of the program to run (some Progress program), run it, and hand the output of that program back to the courier. The courier will then pass that output back to the program that originally called it (the web server).
Iris_rex is actually two programs, iris_rex.p and iris_rex.pl. Iris_rex.p is a Progress program that is launched by iris_rad.pl. It in turn launches iris_rex.pl using an “input-output stream stx through” command. The purpose of iris_rex.pl is simply to provide TCP/IP sockets communication. Everything that is received by iris_rex.pl through it’s TCP/IP port is passed through to it’s STDOUT which is the input side of stream stx in iris_rex.p. Everything output by iris_rex.p through stream stx is read on STDIN by iris_rex.pl and passed through to it’s TCP/IP port. Of course with version 9.1 of Progress you could write the sockets communications directly into iris_rex.p, but I started this before 9.1 existed and I though I would keep it this way for those who have not upgraded. It also allows the possibility of using other languages for the back end.
Here is a very basic diagram of how Iris works.
Iris was written in perl and therefore should be able to run on most popular platforms provided that the suitable perl modules are available. It has currently been successfully run on the following platforms:
Operating System | Perl Distribution | Web Server | Progress Version |
Win NT Server 4.0 | Active State 5.6 | Apache / IIS | 8.2A |
Win 2000 Pro | Active State 5.6 | Apache / IIS | 8.2A |
Red Hat Linux 6.1 | Active State 5.6 | Apache | 8.3B |
Solaris 7 (Sparc) | Active State 5.6 | Apache | 8.2B |
A Progress DB license is all that is required to use iris,however, you will also need a development license on some system so that you can compile or x-code your Progress code.
Using Iris with Progress will require either an NT/2000 or Linux/UNIX platform, or Progress 9.1. Iris_rex.p uses the “input-output through” command which is only supported on NT/2000 and Linux/UNIX platforms. It does not work on Win9X platforms because of the way pipes are (or are not) implemented there. You could use Iris with Progress on Win9X if you have Progress version 9.1 and you modify iris_rex.p. With version 9.1 you could write the sockets communications directly into iris_rex.p and eliminate the need for iris_rex.pl and the “input-output through” command.
Perl Note: The Active State ( www.activestate.com) distribution of perl comes with all of the modules necessary for iris. I have had some trouble running iris on Linux using the perl distribution that comes with it. I believe the trouble revolves around the IO::Select module. Substituting the module from Active State may solve the problems but in the interest of time I simply installed ActivePerl. For other platforms such as HP-UX it may be necessary to try replacing the IO::Select module.
Progress Note: I had trouble running iris on NT with Progress 8.1A. The problems seemed to involve the “input-output through” command. Installing 8.2A fixed the trouble, I have not spent the time to go back and trouble shoot. At this point versions of Progress prior to 8.2 may not work.
For the purposes of this document we will assume that you will not use things such as remsh or rcmd to execute commands on remote machines. The courier (iris.pl) must be installed on the same system as the web server. The request administrator and request executioner must be installed together (because the administrator issues the commands to launch the executioner) but they can be installed on a machine separate from the courier. For best performance you would probably want to install them on the same system as the db so that you can use self-server (shared memory) Progress clients, however, for load balancing you could have your Progress clients and db server on separate machines as long as you have a network client license.
Be sure perl and your web server are properly installed. Copy iris.pl and iris.cfg to the cgi directory of your web server, usually cgi-bin (Apache, Netscape) or scripts (IIS). If you are using IIS be sure the perl to .pl association is set up. This should be done automatically by the perl installation program if you are using ActiveState’s distribution. If you are using Apache, check the first line of iris.pl. This is called the shebang (#!) line. It should contain the proper path to your perl executable. On NT this is often “#! /perl/bin/perl.exe”, on Linux/UNIX it is often “#! /usr/bin/perl”, without the quotes.
Place the rest of the iris distribution, including another copy of iris.cfg, in any directory on the system you want to use for the rad/rex. If this system is NT check that the .pl to perl interpeter file association is set up. If this is Linux/UNIX check the shebang line as described above.
Notes on configuring perl with IIS: The perl installation routine may not set up the file associations properly for IIS 4 and 5. To check/fix this do the following. Open the MS Management Console. Open the IIS folder if it's not already and open the web site you are using for Iris.
Right click on the "scripts" virtual directory you are using for Iris and select "Properties" from the menu. In the dialog box that pops up, you should be on the "Virtual Directory" tab.
At the bottom there is a box labeled "Application Settings". Be sure permissions are set to "Script". Click the "Configuration..." button. Another dialog should pop up and you should be on a tab labeled "App Mappings". Check the list of "Application Mappings". There should be one with the file extension of ".pl" and the executable path similar to C:\perl\bin\perl.exe "%s" %s.
If it's not there, add it. If it is there edit it and see that it is similar to this.
Be sure the box labeled "Script Engine" is check and the box labeled "Check that file exits" is NOT. Lastly you might want to check the tab labeled "App Options". I don't know if any settings here will have an effect, but this is the way I've got mine set up and it's working.
Configuration is handled by the file iris.cfg. You will remember from the installation that there are two copies of iris.cfg. In almost all cases these copies should be identical. Future enhancements will try to reduce this to one configuration file when all components are installed on the same system. Here is an example of a typical iris.cfg:
# Rad TCP Host RadHost=192.168.0.100 # Rad TCP Port RadPort=2350 # Rad Timeout (seconds) RadTimeout=30 #Rex Timeout (seconds) RexTimeout=30 # Rex Min/Max TCP Ports RexMin=2351 RexMax=2355 # Initial number of Rexs to start RexInit=2 # Rex low water mark, start more when the number # available reaches this number until max is reached RexLwm=1 # Rex startup command (NOTE: -param is necessary for all Progress useage) # Win NT/2000 example RexExe=/dlcpv82a/bin/prowin32.exe RexArg=iristest.db -b -T /tmp -p /iris/iris_rex.r -param # UNIX/Linux example # RexExe=/u/dlc82b/bin/mbpro # RexArg=iristest.db -T /tmp -p iris_rex.r -param # HTML Error Pages NoRadErr=/IrisErrs/NoRadErr.html RadTimeoutErr=/IrisErrs/RadTimeoutErr.html NoRexErr=/IrisErrs/NoRexErr.html RexTimeoutErr=/IrisErrs/RexTimeoutErr.html NoRexAvailErr=/IrisErrs/NoRexAvailErr.html
I think most parameters are pretty obvious but I will elaborate on them all anyway.
RadHost – The IP address of the system where iris_rad is installed.
RadPort – The TCP port that iris_rad will listen on for connections.
RadTimeout – Once iris connects to iris_rad and requests the port of an available iris_rex, it will wait this many seconds before disconnecting and redirecting to an error page.
RexTimeout – This is the max amount of seconds that iris will wait for data once it connects to iris_rex. If no data is received in this many seconds after the initial connection, iris will redirect to an error page. If the flow of data stops for this many seconds at any time after it has started, iris will flush the data it has and then display a message reporting the delay in data flow.
RexMin – The beginning TCP port to use for iris_rex instances.
RexMax – The last TCP port to use for iris_rex instances. Right now, the difference between RexMax and RexMin determines the max number of iris_rex instances that could be running. That will probably change as enhancements are made.
RexInit – The initial number of iris_rex instances to start.
RexLwm – iris_rad will start another instance of iris_rex whenever the number of available iris_rex instances reaches this number, as long as it has not reached RexMax.
RexExe – The full path and name of the Progress executable to use when starting new instances of iris_rex. For NT systems this will usually be the path to prowin32.exe, for Linux/UNIX systems it will probably be the path to mbpro. On NT systems, if your license will allow it, you might not want use the -b option. Using it causes two entries in the task bar for each instance of iris_rex, one for the Progress session and one for the DOS box (iris_rex.pl). Not using the -b option eliminates the Progress session entry. This may all change once I look into things like running Iris as an NT service.
RexArg – Progress command line arguments to be used when starting a new instance or iris_rex. They will usually be things like –pf, -T, etc. It should always include “-p iris_rex.r –param”. The parameters to be passed to the Progress session will be provided by iris_rad.pl, but the “-param” should be include here.
NoRadErr – The path to the HTML error page you want displayed if iris cannot connect to iris_rad. The path listed here should be relative to your web servers root.
RadTimeoutErr - The path to the HTML error page you want displayed if iris does not receive an iris_rex port from iris_rad in the specified amount of time. The path listed here should be relative to your web servers root.
NoRexErr - The path to the HTML error page you want displayed if iris cannot connect to the instance of iris_rex it was given by iris_rad. The path listed here should be relative to your web servers root.
RexTimeoutErr - The path to the HTML error page you want displayed if iris does not receive an initial response from iris_rex within the specified amount of time. The path listed here should be relative to your web servers root.
NoRexAvailErr - The path to the HTML error page you want displayed if iris receives a blank reply from iris_rad (no iris_rex instances are available). The path listed here should be relative to your web servers root.
Once everything is installed and configured, and your database is started, you simply run iris_rad.pl. On NT, if your file associations are set up correctly you should be able to simply type iris_rad.pl from a command prompt in the installation directory, or double click on iris_rad.pl in Windows Explorer. On a Linux/UNIX system you should be able to enter iris_rad.pl on the command line. If you path is not set up to include “.” you may need to enter ./iris_rad.pl. In any case you could also enter “perl iris_rad.pl”. When iris_rad.pl starts it will report a few things on STDOUT. It will display the port it is listening on, and each port it is starting an instance of iris_rex on.
There are two additional programs included. Rad_stat.pl will report the status of all iris_rex instances by polling iris_rad. Rad_stop.pl will send a quit message to iris_rad. It in turn will send quit messages to all instances of iris_rex. If you simply kill iris_rad with a Ctrl-C or kill command etc. the instances of iris_rex will not die. You will have to stop each of them manually.
To test your installation a small Progress program has been included called echo.p. It simply echos back to the browser any CGI data passed to it and includes the time and date. You would access it with a URL similar to http://192.168.0.100/cgi-bin/iris.pl/echo.p. Another program included is custlist.p. It works with the sports database and will display a table of all customers and their info.
At this point, programming is similar to using a cgi-wrapper with WebSpeed. In fact, you should be able to take cgi-wrapper programs written in WebSpeed, remove the standard include files, add iris.i, recompile with your Progress 4GL client and run them. Of course you will need to be sure you haven’t used any of the WebSpeed functions or API’s which are not yet supported by iris. At this time there are only a few supported functions, but that will change soon.
You can also use WebSpeed for development using Embedded SpeedScript. When you compile your ESS program, choose the option to save the .w. In the .w WebSpeed will have inserted a .i, replace it with iris.i and recompile. It should now run with iris, of course the same warning about unsupported functions and API’s applies.
General
iris.pl
iris_rad.pl
iris_rex.pl
iris_rex.p
iris_fnc.i and iris_def.i
Much work is needed here.