Open source application server for Progress
The project was started as an “open-source” alternative to Webspeed commercial product from Progress Software Corporation. The “open-source” project is hosted on SourceForge site the license used is GNU LGPL.
Various support options are available for your convenience so you can get all the help that you need starting from installation to development or migration.
Plus is an improved version with simple API interface add-on that allow simple calls from external clients (C, Php, Perl, Python) which extend the broker functionality beyond the web transaction server and allowing it to act as an application server.
Ganimede is trying to be an open-source alternative for WebSpeed, through this not means that is a free version of WebSpeed but it can help you to get started with opening your Progress application to the web. Conceptually Ganimede use the same approach as WebSpeed using one broker and more already connected agents instead of starting a new agent for each client request.The broker and agent’s processes are Progress procedures running in batch that use sockets communication in order to accept and serve the clients requests.
Other components are written in ANSI C this make Ganimede practically OS independent empowered by a distributed architecture that give you the complete freedom on where application components are located. Ganimede accept multiply brokers definition which are configurable form one unified configuration file; configuration option are available in the Ganimede shell. The program’s execution is limited to the sources from WebSrcPath; logging messages and error reporting page layout are localizable; clients access can be filtered upon access/deny basis at the broker level or at the messenger level; binaries files can be streamed directly through the messenger without using the broker.PowerPoint presentation is available here… for more detailed material see the documentation section.
Ganimede use a distributed n-tier architecture that will give you the complete freedom on where your application component will reside.The main part off Ganimede is written in Progress 4GL and it basically consists of one controlling process (broker) and more controlled process (agents). Both the broker and agents process are progress sessions running in batch and serve clients requests using socket communication.There are two other application components that was written in C; the shell application – used to administer and configure the broker (install/configure/start/stop/restart/status), and the messenger (cgi-bin) component used to redirect client web request to the broker.
1. Ganimede/Application Server
Ganimede server component needs to reside on the same machine that you use as Application Server, where your applications source code reside.For Ganimede server you’ll need at least Client Networking product from Progress Software Corporation or one of development suits (ProVision) if you want to do the development – version V9.1A or later. Ganimede need to run progress 4GL in batch mode, so it needs ‘_progres’ executable to be present.You can also use Ganimede server on the same machine as Database server, then the RDBMS product will be more than enough (WorkGroup or Enterprise RDBMS) as long they are from the V9 family.
2. Web Server
In order to use Ganimede Messenger (cgi-bin) component you need a CGI 1.1 compliant web server – this is the preferred architecture.You can optionally use one of the following available interfaces: PHP, Python or Zope.
3. Database server
Whatever Progress RDBMS product that you my have, even Development RDBMS that comes with ProVision Plus for testing purposes – version V8 or later (as V9 clients can connect to V8 database server).* In order to compile the source code you should have a Progress development product – ProVision, for the C coded part of Ganimede you can use your favorite C compiler.
This section will help you install and configure Ganimede broker on your system, for development documentation please go to the project download section on SourceForge where you can find all the API documented available in PDF or compiled help (CHM) formats. For Windows it’s most convenient to use the installation kit that will help you through the installation process and for Linux there is also a self-extracting shell script that will help to some extent, however for more advanced installation options like separate broker and messenger installation some manually setup might be needed. Normally you should find this information written down in INSTALL file from the distribution.
First you should download the distribution and unzip them on your machine, please go to the download page if you didn’t do this already. Depending on your platform you will find in distribution the binaries for shell application in the directory root and for the messenger application in cgi-bin subdirectory – if you want to re-compile them go to the next step. In order to install the messenger you need to call the shell application “gnm_adm”with the “–install” option, this will prompt you for your web server cgi-bin directory and will install the messenger in that location.
* For Unix platform the application install path is set at compile time and can be overwrite either by using GNM_HOME environment variable or by recompiling; for Win32 the information is stored in registry.
If you want to re-compile the C part of the application you’ll need any C compiler that you prefer, the applications are written entirely in ANSI C and I used for development the GNU C compiler and as IDE –KDevelop on Linux, and Bloodshed Dev-C++ on Windows. The sources are available under ‘src/3gl’ subdirectory under the application root directory.On Windows for both the shell application and messenger application I’ve created projects for Dev-C++ and Microsoft Visual C. You need to link the projects with WinSock2 library – Ws2_32.lib. On Unix systems you should follow the standard procedure:
- make install
Ganimede configuration has two distinct parts – broker and messenger configuration.While messenger configuration can only be done at this time by editing the configuration file, the broker part of configuration can be done using Ganimede’s shell application ‘gnm_adm’ with the ‘–configure’option followed by the name of the broker that you wish to configure. This is a simple Chui console application and I don’t plan to switch to some fancy GUI interface in the nearly future.
It basically prompt you with various menu option you can chose from by simply pressing the corresponding number taste and in the case you want to change a value you are prompted for it, at the end it will prompt you whether or not to save your changes. If you are editing a already defined broker you’ll see current values for each settings, if you don’t want to change one value just press ‘Enter’when prompted to replace them. The DLC setting are global for all brokers and should only be changed in the case when you’ve re-installed Progress in other location.
There is another global setting that you don’t manually edit, UTC – the time difference in hours between local time and GMT time.The configuration files are located in ‘conf‘ directory under the application root, ‘ganimede.conf‘ for broker settings respectively ‘gnm_cgi.conf‘ for messenger configuration. These informations should be listed onÂ CONFIGURE file from the distribution.
- Main menu
Main configuration screen, this is the entry point of configuration process. The use of interface are more than intuitive, basically you can only use the available menu options by pressing the corresponding numerical taste.When you change a configuration’s variable value you’ll be prompted to enter the new value, and if the variable was previously set it will be displayed – if you don’t want to change the value just hit Enter, this will keep the previous value in place.At the end of configuration process – when you press “0 – Done” on this screen – you’ll be prompted to save the changes made, this is your call.
- General options
Many of these settings are mandatory: DLC, broker administration password, broker listening port, starting port for listening agents, initial and maximum number of agents.The WebSrcPath should always be set because the broker will restrict the execution of programs to only that located in this path. The ProPath is not mandatory; the WebSrcPath is appended to PROPATH so you don’t need to duplicate the entries. DevelopmentMode will enable the execution of source code but this will only be available if you have the development product installed – if not will be downgraded whether or not you have it enabled in configuration.
- Log & Statistics
These options let you customise the logging options for the broker; you can change the default access and error reporting files – ‘access.log’ and ‘errors.log’ by default – so you can have separate log files for each broker. You can set the logging reporting level as well, the greatest level is 5 but you should never use a level greater than 1 unless you want to debug the broker or you have an error and want to report this to get support (errors and warnings are always reported). Optionally broker statistic can be enabled – that will keep trace on the number of requests received, how many of them were successfully served, denied or not served; minimum, maximum and average execution time for each agents.
- Extra Options
These are some extra options available for broker settings:
maximum execution time – after that if the agent was not released will be considered as timed-out and will be reused (you should adjust this to your needs, you can increase this to allow your programs to finish execution but this could lead to no agent being available)
communication time-out – used in broker-agent communication
message packet size – this is the size of packet in kilobytes used by agents when sending the result back to the requesting client (a greater value is much faster but will need more memory for running agents)
agents filtering options – this could be DENY or ALLOW, if you don’t specify a custom file the default will be used ([broker name].host
- Database connections
This section will give you the possibility to modify the list of agent’s databases.You can add or remove databases from the list (no update option available – you can edit the configuration file if you don’t want to do remove/add).Each database line should contain all connection parameters necessary including localisation’s ones, the database line format is as follow:[database physical name] [connection parameters]
- General considerations
You can configure as many agents that you want, you can use the shell application or you can edit the configuration file manually at your free choice. Same considerations about broker settings:
a greater log level will slightly decrease the performances because of the extra disk activity involved
statistics will not have a great impact over performances
client filtering will have some performance impact but not so big because the clients filter table are loaded into a temporary table at broker’s start-up so the file don’t get parsed on every client request
make sure you don’t put in the WebSrcPath the directory that have programs that users are forbidden to run, if you need them in your application just put them in ProPath configuration variable.
The messenger configuration at this time can only be made by manually editing the configuration file ‘gnm_cgi.conf’, this will be fixed soon. Every broker defined should have a corresponding line in the messenger configuration file, the format of this line are as follow:broker name@broker host:broker port[:time-out][:packet size][:host filter option] First three of them are mandatory, the others are optional and have the following meaning:
communication time-out (in seconds)
communication packet size (multiple of 1K)
client filtering option
- 0 – don’t filter client
- 1 – global allow clients (allow only clients present in ‘gnm_cgi.host’)
- 2 – global deny clients (deny all clients present in ‘gnm_cgi.host’)
- 3 – local allow clients (allow only clients present in ‘broker name.host’)
- 4 – local deny clients (deny all clients present in ‘broker name.host’)
error reporting option
- 0 – don’t use custom error reporting
- 1 – use global error file (‘gnm_cgi.err’)
- 2 – use local error file (‘broker name.err’)
READY TO USE
Now you can start using Ganimede broker you just have configured. You will use Ganimede’s shell application to control the broker:
- start: gnm_adm –start [broker name]
- debug: gnm_adm –debug [broker name]
- stop: gnm_adm –stop [broker name]
- restart: gnm_adm –restart [broker name]
- status: gnm_adm –status [broker name]
* You should always check the result in the log file, if not all databases needed are available the broker will stop. Debug option is only available for Win32 platform, there isn’t any Progress debugger available for Unix just yet. If all was going well you should be able to use your web-based application by entering the following address in your browser.http://[web.server.name]/cgi-bin/gnm_cgi/[broker]/[app entry point]
- *on Unix platform the messenger’s cgi is gnm_cgi, on Windows is gnm_cgi.exe.
For latest stable version you should go to the project download page on SourceForge.NetPowerPoint presentation is available here… Darrel Davis of Allegro kindly provided this presentation presented by him at some PUG meetings, thanks a lot. WsNewsKit project can be downloaded from SouceForge, the version included in Ganimede distribution isn’t necessary up to date.
For support options please contact me directly by email or phone, on-line support will be available shortly as soon as I manage to put the tracking system in place.
There are various support options available:
- Startup [150€] – one month of email based support only for installation/configuration problems.
- Standard [500€] – three months of email based support covering installation/configuration/development
- Plus [1000€] – one year of standard email based support, plus distribution of each major release on CD. Standard and Plus support options also gives you priority for your bug-report or improvement-request calls.
Various arrangements can be made in case you are interested to distribute Ganimede bundled within your application or you promote the solution to your clients.
If you are willing to contribute in any way to this project please feel free to contact me.
Email: firstname.lastname@example.org | email@example.com
Mail: 48A Florilor, Floresti, 407280, Cluj, Romania
You can log a call to report a bug, request a feature, seek help or simply express your opinion using the tracking system on SourceForge. Thanks to every ones who helped me on this project, many thanks to Rares Stanciulescu who is kind enough to host a demo site for the project… and especially my wife and my daughter for the supporting me throughout.
Here is a list of all persons who contributed in any way to Ganimede Project.
If you think your name should be included here, please contact us! We might have forgotten you.
Ganimede is completely free software published under the GNU Lesser General Public License, you should receive a copy of this document within the distribution if you didn’t you can read the latest version of the license on GNU – Free Software Foundation web site. Whatever, Ganimede uses Progress Software Corporation products that should be licensed, not any progress executables or binary code is distributed with Ganimede.You can check the PSC product license policy with your PSC Product Representative.
If you want to recompile the source code you’ll need development licenses – ProVision suite for progress 4GL code, and any of your favorite C compiler for the C part of the code.Ganimede broker and agents are progress sessions running in batch so based on current PSC license policy they don’t count as a ‘real users’.
You should have a number of license greater or equal with the maximum between the number of ‘active connection’ and the number of batch process – still make sure you consult PSC Product Representative on this matter.** In ‘_license’ table Ganimede’s agents count as ‘batch connection’; this is only true if you run the broker on the same machine as database server (self-service client).