Xobas Software'> ]> ProLinga-Web Project Release: &PRODUCT;-&version; - &release-date; Bas Driessen &xobas;
bas.driessen@xobas.com
 Original author and current maintainer. 2002-©right-year; The ProLinga Team Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". This document describes the ProLinga-Web Project and how to build the software components. ProLinga-Web Project The ProLinga-Web is a small project that focusses on the development of a CGI applications. These applications generate an XML request file based on the URL given by a user or application. This request file will be send to a ProLinga-4GL Run-Time processor, which processes the request and then sends a response back. This response is an XML document which can contain any type of information in its response body. Most likely this body information will be HTML or XML, that will be displayed in an Internet Web Browser. If the content of the response file is XML, it can be transformed using an built-in XSLT transformer. Managing and processing of the requests and responses is controlled by Web Commands (WC). A WC request is an XML document containing a command generated from an URL. A command can be to run a block of logic in the ProLinga Runner. The current CGI application prolingaweb is a standalone CGI application that lives in a script (prolinga-cgi) directory on a Web Server. The flow and processing of incoming and outgoing requests and responses can either be controlled by a sophisticated SOAP layer on top or direct links using the C++ API of the software component to connect to. Since all code is written in C++, it can be ported to all modern UNIX systems, GNU/Linux variants as well as MS-Windows. ProLinga-Web as a communication channel is extremely fast and very reliable. Main purpose for the creation of this project, is to provide an easy way to access 4GL run-time processing engine using a Web browser as the user interface. ProLinga-Web has been built and tested on many popular GNU/Linux platforms as RedHat Fedora, Mandriva Linux, Ubuntu, Debian and openSUSE. Since all code is written in C++, it can be ported to all modern UNIX systems, GNU/Linux variants as well as MS-Windows and Mac O/S platforms. Portions of code are lifted from the CGI tutorial written by James Marshall. Web Command Web Commands are used to retrieve data from an URL, manage and return data to the browser or requesting party. Web Commands have the following format: webcmdsessidformat ]]>value . . . . . . ]]> Since Web Commands will be passed on to other services, no Web Commands besides a Ping command are pre-defined. URL details will be placed into a Web Request enveloppe. Web Request As mentioned before, URL details will be transformed to a web request. Example Web Request: ]]> The reserved URL parameters and their default values are: webcmd: Default session: none format: HTML service: Default appn: Default name: Default All additional URL name/value pairs will be added as a Parameter tag within the Object section of the request file. Web Response Web responses are created/generated by remote (Web) Services. ProLinga-Web, receives this response file, performs a transformation if required and creates a return document to display in the browser or to send back to the requester. Example Web response: http://localhost/Partslist.xsl Parts List

List of Parts.

text text text ...

] ]> ]]> The tag Transform is optional and will only be used in case of a document in XML format. When the format is set to XML, there will not be a CDATA section, but normal well-formed XML data. Whatever is within the Response tags will be send back to the caller. If Transform is present and the format is XML, the document will first be transformed using xslt before returned. For the XSLT transformation file, both an URL as file name can be used. Ping Since the Ping Web Command will be processed internally by ProLinga-Web, no Web request/response as described above will be created. Depending on the format, there will be a response telling the caller if the pinged service is dead or alive. Error Handling As soon as something goes wrong when processing a request, an error is generated and send back to the caller. In xml, an error document has the following format: Error/Warning Short description An external error text if available ]]> For all other formats, like HTML, a message will be send back in that format containing the same details as the error described for XML. Multiple Web Commands It is possible to combine WCs in one single request, but this is not possible via the CGI implementation. You need to connect to the Web Service directly and provide own post-processing like XSLT transformation if required. There will be one response file, but with results for every command, unless an error has been encountered before the end of processing. The format is as follows: ]]>value . . . . . . ]]>value . . . . . . . . . . . . ]]> Combining multiple WCs will result in better performance. Download ProLinga-Web There are two types of product versions available for download: Production Version Development Version Production Version The production version is an official product release. This is a stable completed version which should be used in production environments. At this stage the product is only available as a source archive. Binary packages for a wide range of platforms will be available for download as the project progresses. Please visit the download page for the latest details. Development Version The development version is a snapshot of the latest source files. Since it can contain bugs as part of "work in progress", this version should not be used in production environments. Only developers who want to help with further development of the ProLinga Projects should download this version. Please read the details at the Subversion section of how to obtain the latest development version. Build ProLinga-Web Prerequisites ProLinga-Web &version; has been built and tested on RedHat Fedora, Mandriva Linux, Ubuntu, Debian and openSUSE. The product should compile and run successfully on other GNU/Linux distributions as well as UNIX. GNU gcc/g++ >= 3.3 compilers/tools are required for a successful build. Required 3rd party package(s) for a successful build: libxml2. This product provides XML libraries. libxslt. This product provides XSLT transformations. ProLinga-Soap This product provides a SOAP/XML engine. Optional 3rd party package(s) for a successful build: FastCGI This product provides a high performance CGI channel. ProLinga-Run This product provides a 4GL language interpreter and run-time environment. General Download and Installation Instructions 3rd Party Products. Assuming the directory /opt/builds will be used for 3rd party products, then in general the following steps need to be taken to download and extract a 3rd party product source archive. Download source tar/gz archive to /opt/builds/[product] Example: place libxml2-x.x.x.tar.gz in /opt/builds/libxml2 Use 'gunzip' to unzip the archive Use 'tar xvf [product.tar] to extract the archive. Example: tar xvf libxml2-x.x.x.tar. A new sub directory will be created with the new version of the product. Example: /opt/builds/libxml2/libxml2-x.x.x This way several versions of the same products can be installed next to each other. For product specific installation instructions see following sections. Libxml2: Product root dir: /opt/builds/libxml2 Current version: 2.6.31 Download: ftp://xmlsoft.org/libxml2/libxml2-2.6.31.tar.gz Build Instructions: cd /opt/builds/libxml2/libxml2-2.6.31 ./configure --prefix=/opt/builds/libxml2/libxml2-2.6.31 make make install Libxslt: Product root dir: /opt/builds/libxslt Current version: 1.1.22 Download: ftp://xmlsoft.org/libxml2/libxslt-1.1.22.tar.gz Build Instructions: cd /opt/builds/libxslt/libxslt-1.1.22 ./configure --prefix=/opt/builds/libxslt/libxslt-1.1.22 make make install ProLinga-Soap: Product root dir: /opt/builds/prolinga Current version: 0.0.1 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-soap-0.0.1 ./configure --prefix=/opt/builds/prolinga/prolinga-soap-0.0.1 make make install See the ProLinga-Soap Project documentation for more installation information. FastCGI: There are two parts to this product: Web Server Module Application Library To be able to use FastCGI, the Web Server needs to have access to a FastCGI module. At this stage only Apache Web Server on GNU/Linux has been tested and the following build instructions applies to that combination only (assuming a Apache binary distribution). For other combinations, please find the information on the homepage of FastCGI. Web Server Module : mod_fastcgi.so To find out if this Apache module is installed check if mod_fastcgi.so is in the directory /etc/httpd/modules. The httpd-development kit needs to be installed. Product root dir: /opt/builds/fastcgi Current version: 2.4.6 (Only works with Apache 1.3 and later) Download: http://www.fastcgi.com/dist/mod_fastcgi-2.4.6.tar.gz Build Instructions: cd /opt/builds/fastcgi/mod_fastcgi-2.4.6 cp Makefile.AP2 Makefile make top_dir=/usr/lib/httpd make top_dir=/usr/lib/http install Edit the file /etc/httpd/conf/httpd.conf and add the following line: LoadModule fastcgi_module modules/mod_fastcgi.so Set the following directive: FastCgiIpcDir /tmp Application Library (Development Kit) Product root dir: /opt/builds/fastcgi Current version: 2.4.0 Download: http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz Build Instructions: cd /opt/builds/fastcgi/fcgi-2.4.0 mkdir fcgi (install in build dir triggers errors) ./configure --prefix=/opt/builds/fastcgi/fcgi-2.4.0/fcgi make make install An alias has to be setup, so images etc. can be displayed: html_root_dir_nameinstalldir Example: Alias /prolinga-web/ "/home/prolinga/prolinga-web/var/www/html/" To be able to run prolingaweb from within a web browser, an Alias has to be setup on the (Apache) Web Server: For traditional CGI: cgi_dir_nameinstalldir Example: ScriptAlias /prolinga-cgi/ "/home/prolinga/prolinga-web/var/www/cgi-bin/" For FastCGI: Add a similar section to httpd.conf Alias /[]]>cgi_dir_nameinstalldirinstalldir SetHandler fastcgi-script Options +ExecCGI ]]> Example: Alias /prolinga-cgi/ "/home/prolinga/prolinga/]]>prolinga-webprolinga-web SetHandler fastcgi-script Options +ExecCGI ]]> For Apache edit the file httpd.conf (most likely in /etc/httpd/conf) and restart the httpd daemon (/etc/rc.d/init.d/httpd restart). ProLinga-Run: Product root dir: /opt/builds/prolinga Current version: 0.0.1 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-run-0.0.1 ./configure --prefix=/opt/builds/prolinga/prolinga-run-0.0.1 make make install See the ProLinga-Run Project documentation for more installation information. This product is only required for a traditional access method (=library linkage), rather than the prefered Web Services access method. Build Instructions Extracting archive The product archive can be extracted to any desired directory using unzip (.zip file extension) or gunzip (.gz file extension)/ bunzip2 (.bz2 file extension) and tar. After extracting, the following directories will be created: Directory Structure. Directory Description &PRODUCT;-&version; Product version root directory. &PRODUCT;-&version;/config Config build information. &PRODUCT;-&version;/doc Documentation. &PRODUCT;-&version;/src All source and internal header files. &PRODUCT;-&version;/tests Self tests. &PRODUCT;-&version;/prolinga Raw configuration files.
Compiling and Linking To build the product go to the product root directory and run the configure script. For default installation in /usr/local type: ./configure To install into another directory type: ./configure --prefix=/any/dirname/ To compile as traditional instead of FastCGI: ./configure --disable-fastcgi To link against the ProLinga-4GL language interpreter and run-time environment, type: ./configure --enable-run For all other configure options, type: ./configure --help After running the configure script, the product can be build with: make To run the optional self-test type: make check After compilation, the binaries, libraries and header files can be installed with: make install You may need root access for this last option. By default, HTML documentation pages are available in the doc/html directory. These pages are generated from DocBook XML file format files in /doc. To re-generate the HTML pages from these files type: make html The command line XSLT processor xsltproc must be available from $PATH to be able to generate the HTML documentation. Dependencies Many of the ProLinga Projects are dependent on 3rd party libraries. These (non system) dependencies of ProLinga-Validate are outlined below. If these 3rd party products are not installed in either /usr/bin, /usr/lib, /usr/include or /usr/local/bin, /usr/local/lib, /usr/local/include, the additional configure option needs to be provided when building. Dependencies Dependency Version Configure Option libxml2 >=2.6.31 --with-libxml-prefix=/path/to/libxml2 libxslt >=1.1.22 --with-libxslt-prefix=/path/to/libxslt ProLinga-Run >=0.0.1 --with-prolingarun-prefix=/path/to/prolingarun ProLinga-Soap >=0.0.1 --with-prolingasoap-prefix=/path/to/prolingasoap
Choosing the right type of build The default configuration options provide libraries which can be used both to develop/debug as to run the product. However better builds are possible for a dedicated development or production environment. In production environments, builds are needed which contain minimal (debug) overhead, so they are fast and small. To build such binaries/libraries, the --enable-final options can be used. Example: ./configure --enable-final The enable-final flag is configured to be used with GCC environments only. If access to more compilers become available over time, the enable-flag will be ported to those compilers as well. In development environments, builds are needed producing warnings, enabling maximum debugging info etc. Several options are available here. --disable-fastcgi : Compile as traditional instead of FastCGI --enable-warnings : Set all compiler warning flags --enable-debug : Enable all debug messages --enable-gprof : Enables profiling with gprof (GCC only) Further development of ProLinga-Web All ProLinga Projects are under constant active development. This includes issues related to fixing bugs, increasing performance etc, as well as expanding the various projects with new features. This chapter provides information of all these types of tasks as well as details of how to join the development team. To-do List This section contains a list of work that needs to be done on the product. A more detailed and up to date list is available on the ProLinga Bugzilla Server. Self tests need to be developed. Porting. Utilities. Code review and cleanup. Automatic script installation Apache Web Server. Add command line options to the binaries. Better use of/review config file prolingawebsvc.xml. Subversion A Subversion tree containing the latest project sources is available at http://svn.prolinga.org. For access please contact the ProLinga Development team. Bugzilla Bugzilla software development and bug tracking system to manage the ProLinga projects is available at http://bugzilla.prolinga.org. For access please contact the ProLinga Development team. Help to Develop Are you ready to join the ProLinga development team? There are several ways you can help: Use the product. Tell us what you think, ideas, bugs etc. Fixing bugs. Visit the development section on the Web Site, choose a bug, fix it and send us the code changes. Enhancements. Have a look at the enhancement section of the to-do list and let us know which new feature you want to help to develop. Porting. To be successful it is essential that the ProLinga Projects are available on a wide range of platforms. We need help in porting and testing as well as providing binary releases for many different platforms. Let us know if and how you can help out. Real world examples. Are you using ProLinga products or do you know people who are happily using it. Tell us the story and provide some screenshots. ProLinga-Web User Guide This section contains the user guide for the ProLinga-Web. All the binaries and configuration files. &prolinga-web-userguide; &fdl;