Xobas Software'> ]> 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-Run Project, how to build the software components and documents the API reference of the prolinga-run library. ProLinga-Run is a 4GL run-time engine. It is a interpreter that processes XML documents generated from 4GL logic statements by ProLinga-Validate. 4GL statements include bindings to the popular GTK+ User Interface for the GNU/Linux (GNOME) desktop. ProLinga-Run communticates with other components in the ProLinga Network using request/response SOAP calls over a TCP/IP network. These other components include the application repository (prolingarepd) and user data (prolingadatd). Using this concept, programs appear to run locally on a machine, but in fact they can access a wide range of machines (= Web Services), centrally located in an intranet environment or anywhere in the world via the internet, to share the load and execute the application. ProLinga-Run has been built and tested on various popular GNU/Linux platforms as RedHat Fedora, Mandriva Linux, Debian, openSUSE, Ubuntu and MS-Windows (Cygwin), but 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. Since GTK+ has been ported to many UNIX and MS-Windows platforms, future releases of ProLinga-Run will include such ports as well. Currently there are two flavours of ProLinga-Run. The Desktop/Client binary (prolingarun) that runs on a user desktop machine. This binary is called from the start script prolinga. The Web Service binary (prolingarund) that runs as a daemon and is used by the ProLinga-Web component. In both cases, they contain the 4GL interpreter, while the desktop version also contains bindings to the GTK+ user interface. With the run-time environment I also refer to the user 4GL development environment, since it runs in the run-time environment being a development tool itself. The 4GL engine processes statements that have been generated from 4GL logic by the generator. 4GL statements typed in by a developer user may look like this for instance: SCREEN TITLE "Variable - untitled" MESSAGE "Created new variable." CLEAR RECORD Variable.Variable LET F-EditCode.Variable P-EditCode(1) DISPLAY ALL To be able to process these statements we need to put them in a format that can be processed in an efficient way by the interpreter. When this logic is saved in the 4GL development tool, an XML document will be generated by the Validate Web Service that looks like this: TITLE "Variable - untitled" "Created new variable." RECORD Variable.Variable F-EditCode.Variable P-EditCode(1) ALL ]]> Besides the statements and arguments, this document also contains control information as where to go after processing a statement. This is important when using statements like IF/THEN/ELSE or FOREVER loops. All data references also have been validated for their existence. While for the developer user it seems that the interpreter is a 4GL interpreter, in fact it is an XML interpreter. Using this format also opens the door for features as code generation and scripting. Since the XML parser used from libxml2 is as so called DOM parser, this model will work best with logic blocks of limited size. Benchmark test should tell us, but initial testing suggests a maximum of 500 lines per logic block must be set. For a 4GL this is a very reasonable limitation. For the User Interface in the desktop/client binary, the products GTK+, Glade and Libglade are used. Glade is a GUI builder built on top of the GTK+ widget set for the GNOME project. In the ProLinga Development Tool Developer, Glade will be called when (new) screens are to be painted. The screen will be stored in an XML format when saved in Glade. These Glade XML files will be stored in the remote repository. Libglade is a library that at run-time will generate the User Interface from the Glade XML documents. To be able to manage the Glade XML documents in the ProLinga Environment, an extra header is added (enveloppe) to the file. Below follows an example of a Glade file. Please note the Repository Command header "Get", which retrieves this document from the repository. ]]> The full document contains 406 lines. Advanced compression techniques in the SOAP engine insures very efficient processing over the network. The use of Libxml is widely accepted in the open source community and is already very stable proven technology. When this document is processed at run time by Libglade, the following screen will be visible on the desktop: screenshot stock application The contents (data) of the various fields in this screen will be placed in this screen after processing by Libglade. To interact with the 4GL interpreter without the need for a User Interface, Web Commands (WC) can be used to process 4GL logic. ProLinga-Web for instance generates WCs from URLs and sends/receives WC documents to/from the ProLinga-Run Web Service. For details on the format of these Web Commands, please have a look at the documentation of ProLinga-Web. At this stage only one Web Command has been implemented in ProLinga-Run and that is the command RunLogic. This command will run a 4GL logic block and returns a response after processing has been finished. Future Web Commands can be commands like RunBackground for instance to start a process as a background process (batch processing). To test ProLinga-Run, the best and easiest way is to use the binaries that come with the product. A correctly configured ProLinga Network is required. Run bin/prolinga to start the desktop client. To test browser access, configure so ProLinga-Run is running as a Web Service, the ProLinga-Web CGI application is in place and a Web Browser is available. Please read the documentation of ProLinga-Web for details how to set up Web Access. To access ProLinga-Run (4GL Interpreter) from a C++ application, either network (SOAP) calls to send and receive Web Commands over the network or the C++ API to link with the Run library can be used. To be able to send and receive Web Commands over the network as SOAP calls from a C++ application to access the ProLinga-Run environment, the application must link with the ProLinga-Soap Client Library (libprolingasoapclient). Details of how to do so are in the section "Programming Notes" of the ProLinga-Soap Project documentation. In the example shown there you have to change the example XML request document with a valid Web Command. Alternatively have a look at the source code file WebCgi.cpp and WCWebCommand.cpp in the src directory of ProLinga-Web. When using this method, ProLinga-Run must be running as a Web Service. To be able to link directly into ProLinga-Run from a C++ application, the Run Library (C++ API) can be used. A very basic example program using the Run Library, so it can access the 4GL interpreter looks like this: int main(int argc, char *argv[]) { /*Init */ xmlDocPtr docReq, docRes; xmlNodePtr curReq, curRes; xmlBufferPtr bufRes; PlRun run; /* Open Run Environment */ run.runOpen("./prolingaruncfg.xml", argc, argv); /* Create Web Command */ docReq = xmlNewDoc((const xmlChar *)"1.0"); docReq->children = xmlNewDocNode(docReq, NULL, (const xmlChar *)"ProLinga", NULL); curReq = xmlDocGetRootElement(docReq); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Web", (const xmlChar *)""); xmlNewProp (curReq, (const xmlChar *)"Version", (const xmlChar *)"1.0"); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Command", (const xmlChar *)""); xmlNewProp (curReq, (const xmlChar *)"Name", (const xmlChar *)"RunLogic"); xmlNewProp (curReq, (const xmlChar *)"Mode", (const xmlChar *)"Request"); xmlNewProp (curReq, (const xmlChar *)"SessionId", (const xmlChar *)"None"); xmlNewProp (curReq, (const xmlChar *)"Format", (const xmlChar *)"HTML"); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Object", (const xmlChar *)""); xmlNewProp (curReq, (const xmlChar *)"Service", (const xmlChar *)"Runner"); xmlNewProp (curReq, (const xmlChar *)"Application", (const xmlChar *)"stock"); xmlNewProp (curReq, (const xmlChar *)"Name", (const xmlChar *)"WPartLst"); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Parameters", (const xmlChar *)""); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Parameter", (const xmlChar *)"ALL"); xmlNewProp (curReq, (const xmlChar *)"Name", (const xmlChar *)"group_id"); /* Process Web Command */ docRes = run.executeCommand(docReq); /* Print Response */ bufRes = xmlBufferCreate(); curRes = xmlDocGetRootElement(docRes); xmlNodeDump(bufRes, docRes, curRes, 0, 1); printf("%s\n", (char *)xmlBufferContent(bufRes)); /* Close Run Environment */ run.runClose(); /* Free */ xmlBufferFree(bufRes); xmlFreeDoc(docRes); xmlFreeDoc(docReq); /* Return */ return 0; } ]]> When opening this connection an argument with the path and name of the run configuration file can be passed as an argument. The system then knows details as in where it can connect to to find the Repository etc. The configuration file has to be in a certain format, which is explained further on. The Web Command is then presented to the Run process engine. Within this Run environment, the RunLogic command is called. Arguments are the service name that represents a hostname and portnumber, the name of the application to access and the name of the logic to execute. Additional parameters are parameters dependent on what the logic needs to be able to execute. After executing a response is returned. This response is printed to to stdout (screen). The connection to the Run environment is closed, so data get flushed etc. and the program exits. After creating a connection using the openRun class function, more than one WC can be executed without the need to close and open the Run environment for every call. In fact performance wise this is the preferred method. The C API of the libxml2 toolkit has been used in this example, while it is probably better to use a C++ implementation of this toolkit as libxml++. Internal Run code will be changed as the project progresses. To compile the program, use the following command: g++ run_test.cpp -o run_test `pkg-config --cflags --libs prolinga-run` You may need to set the environment variable PKG_CONFIG_PATH to point to the directories where prolinga-run.pc is located. This can be directory /usr/lib/pkgconfig or directory /usr/local/lib/pkgconfig on GNU/Linux for example. ProLinga-Run is built using various 3rd party open source packages. These packages need to be available at compile time for a sucessful result. See the dependencies and prerequisites section for more details. There are two types of product versions available for download: Production Version Development 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. 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. ProLinga-Run &version; has been built and tested on RedHat Fedora, Mandriva Linux, Debian, openSUSE, Ubuntu and MS-Windows (Cygwin). 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. ProLinga-Calc This product provides a C expression calculator. Libglade This product loads XML files to create the user interface dynamically. GTK+ (GLib, GTK+, Pango, ATK) This project provides a complete set of widgets If ProLinga-Run is to be linked with other ProLinga libraries like Repository to create a stand-alone project, these libraries need to be available as well. 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. 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 Product root dir: /opt/builds/libxslt Current version: 1.1.22 Download: ftp://xmlsoft.org/libxslt/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 /opt/builds/libxml2/libxml2-2.6.30/lib/pkgconfig should be in your PKG_CONFIG_PATH if you want to link against the libxml2 built following the previous libxml2 installation instructions. Product root dir: /opt/builds/prolinga Current version: 0.0.2 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-soap-0.0.2 ./configure --prefix=/opt/builds/prolinga/prolinga-soap-0.0.2 make make install See the ProLinga-Soap Project documentation for more installation information. Product root dir: /opt/builds/prolinga Current version: 0.0.2 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-calc-0.0.2 ./configure --prefix=/opt/builds/prolinga/prolinga-calc-0.0.2 make make install See the ProLinga-Calc Project documentation for more installation information. Product root dir: /opt/builds/libglade Current version: 2.6.0 Download: ftp://ftp.gnome.org/pub/GNOME/sources/libglade/2.6/libglade-2.6.0.tar.gz Build Instructions: cd /opt/builds/libglade/libglade-2.6.0 ./configure --prefix=/opt/builds/libglade/libglade-2.6.0 make make install Use the GTK+ version that ships with the O/S. Version 2.6.0 or higher required. 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 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 External (API) header files. 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/ 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. Many of the ProLinga Projects are dependent on 3rd party libraries. These (non system) dependencies of ProLinga-Run 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. Dependency Version Configure Option libxml2 >=2.6.31 --with-libxml-prefix=/path/to/libxml2 libxslt >=1.1.22 --with-libxml-prefix=/path/to/libxslt ProLinga-Soap >=0.0.2 --with-prolingasoap-prefix=/path/to/prolingasoap ProLinga-Calc >=0.0.2 --with-prolingacalc-prefix=/path/to/prolingacalc Libglade >=2.6.0 --with-libglade-prefix=/path/to/libglade GTK+ >=2.6.0 --with-gtk-prefix=/path/to/gtk Dependency Version Configure Option ProLinga-Data >=0.0.2 --with-prolingadata-prefix=/path/to/prolingadata ProLinga-Repository >=0.0.2 --with-prolingarepository-prefix=/path/to/prolingarepository ProLinga-Validate >=0.0.2 --with-prolingavalidate-prefix=/path/to/prolingavalidate 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. --enable-warnings : Set all compiler warning flags --enable-debug : Enable all debug messages --enable-gprof : Enables profiling with gprof (GCC only) 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. 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. The 4GL-interpreter should be split from the user interface. A new project ProLinga-UI is introduced to realize this. Implement XML Schemas for validation. Libxml2 is finishing up XML schemas. If it is still too far away, start with DTD. ProLinga-Run is written in C++. Libxml2 however is C only. There is a C++ wrapper for this XML parser library. Details at http://libxmlplusplus.sourceforge.net/. Some strings/paths are hardcoded in the product. This all should be reviewed and be removed or made all configurable using a config file. Utilities. Code review and cleanup. Logging. Self-tests need to be developed for quality control. Porting to other platforms. (MS-Windows/Solaris?), so we can make a distribution available on a specific port if we need to. A Subversion tree containing the latest project sources is available at http://svn.prolinga.org. For access please contact the ProLinga Development team. 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. 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 ProLinga 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. Please 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? Please tell us the story and provide some screenshots. This section contains the API reference for ProLinga-Run. All the public interfaces are documented here. &prolinga-run-API; This section contains the user guide for ProLinga-Run. All the binaries are documented here. &prolinga-run-userguide; &fdl;