Xobas Software'> ]> ProLinga-Validate Project Release: &PRODUCT;-&version; - March 21, 2008 Bas Driessen &xobas;
bas.driessen@xobas.com
 Original author and current maintainer. 2002-2008 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-Validate Project, how to build the software components and documents the API reference of the prolinga-validate library. ProLinga-Validate Project ProLinga-Validate is a tool that parses, validates and transforms ProLinga 4GL logic into an XML document. This result XML document, called a RunControl, is used at run-time by the ProLinga-Run binaries. It can further validate the physical presence of Objects, there where Objects are used as member Objects. For instance, if a record contains a Data Dictionary called order_no, ProLinga-Validate can check if this Data Dictionary exists in a specified application Repository. ProLinga-Validate works according the Request-Response mechanism. A request can be for instance to validate 4GL Logic called "Main". ProLinga-Validate will send out a request to get the logic from the ProLinga-Repository, transforms it into an XML document, validates the data references, writes the transformed results back as a response to the remote repository and returns a response to the caller. ProLinga-Validate can be configured as a Web Service (daemon) on the machine. A sophisticated SOAP layer on top controls the flow and processing of incoming and outgoing requests/responses over the TCP/IP network. Using this concept, programs can run locally on a machine while accessing a remote validate engine centrally located in an intranet environment or anywhere in the world via the internet. Main purpose for the creation of this project, is to provide an easy way to transform user readable 4GL code into XML documents that can be processed by the interpreter at run-time and to provide presence checks of member Objects. The current implementation is specifically written for the ProLinga 4GL logic and ProLinga environment. Therefore it can not directly be used in other non-ProLinga related projects at the moment, however the concept and portions of code can maybe help out there. Future releases maybe more configurable using language and grammer documents etc so make it a 4GL language independent tool. ProLinga-Validate has been built and tested on various popular GNU/Linux platforms as RedHat Fedora, Mandriva Linux, Debian, openSUSE and Ubuntu. Since all code is written in C++, it can be ported to all modern UNIX systems, Linux variants as well as MS-Windows and Mac O/S platforms. Transformation The 4GL logic produced by the developer-user, needs to be transformed to an XML format which can be used by the interpreter at runtime. These documents contain information about the logic commands as well about the program flow. The validate rules and formats are explained further on this page. The validate output documents have the following format: argument . . . . . . . . . . . . ]]> Example: TITLE "Variable - untitled" "Created new variable." Record Variable.Variable F-EditCode.Variable = P-EditCode(1) ALL ]]> This document is transformed from the following 4GL logic. SCREEN TITLE "Variable - untitled" MESSAGE "Created new variable." CLEAR RECORD Variable.Variable LET F-EditCode.Variable = P-EditCode(1) DISPLAY ALL Validation When the 4GL logic has been transformed into an XML document, syntax checking and validation will be performed. The grammar and syntax rules of the 4GL logic are outlined in a language validation file. Every 4GL logic command has an entry is this file. The folowing example describes the syntax of the 4GL logic command "LET". 3 999 . . . . . . ]]> The first step is to check if the number of arguments is within the limit of number of expected arguments. Next the arguments will be processed one by one and tried to be matched with a path entry starting with 1. If the argument does not match a path entry, the number will be raised and will be matched against the next path entry until all arguments are processed. As soon as a path entry is matched, the argument will be validated in case it is a data reference where the value needs to be read from the Repository. To indicate that arguments can be used more than once, the setting NextStep can be used to point back to the first repeating argument. The setting LastStep indicate if the argument can be the last one. If anything goes wrong in this whole validate process, an error will be generated and returned to the caller. The following styles are defined : Validation Styles Style Description AnyName: Any object name not being a datareference or string, which can not be validated. Example: CLEAR CONTAINER Main. Main is here a container on the current screen. At validate time we don't know this name of the current screen and container 'Main' can not further be validated. ControlFunctionName: Any name of a built-in control function. Example: CONTROL cancel MathFunction: Math functions like sin(1) or abs(L-value) MathOperator: Math Operators like + - >= etc. Numeric: Any numeric value. ObjectName NameOfObject: Validation of a base object. The name of the object will be lifted from the style name. Examples: ObjectNameDataDictionary SingleDataReference: Any DataReference that can hold a single value. Examples: L-Value P-size(2) C-MaxWeight SingleDataReferenceWrite: Any non-read-only SingleDataReference. GroupDataReference: Any DataReference that can hold a group of Data Dictionaries. like Records and VariableGroups. Examples: R-Size H-Selection GroupDataReferenceWrite: Any non-read-only GroupDataReference. Static: Hardcoded value. An attribute "Value=" need to be added containing the value. String: Any text between double quotes (" "). UnsignedInteger: Any whole positive number. Comparator: >= <>]]>
Validate Commands Validate Commands are used to send out a request to the validate service to have some 4GL logic validated or to check for the physical presence of a member Object. A response will be send back. Behind the scenes, the validate service will communicate with the Repository service to retrieve and store the data involved. Validate Commands have the following format: . . . . . . ]]> The following Validate Commands are available: TransformOnly Validate Ping TransformOnly This setting only applies to Logic and it skips the validation step after transforming the 4GL logic into an XML document. The transformed document will get stored in the repository as type "RunControl". Example TransformOnly Request: ]]> Example TransformOnly Response: ]]> Validate Validation is implemented for Constant, Index, Logic, Record, Table, Variable and VariableGroup. Other objects will simply be ignored. Example Validate Request: ]]> Example Validate Response: ]]> Ping The ping command can be used to test if a validate host is on-line and responding to requests. Example Ping Request: ]]> Example Ping Response: ]]> Additional error information from the underlying SOAP layer will be presented as well in the response document in case of an error. Error Handling As soon as something goes wrong when processing a request, an error is generated and put into the response document. The status of the response will be set to "Error" or "Warning" depending on the severity of the error. In case of an error, processing will abort immediately, while in case of a warning processing continues. An error has the following format: Error/Warning Short description An external error text if available Error/Warning syntax_error_id error description
additional details
 . . . . . . ]]> Example response when trying to validate a constant with a non exisiting data dictionary: Error Contains Validate Errors Error 40009 Invalid Data Dictionary Name
Namexxx
 ]]> The "External" element will contain any error text passed on from the O/S or 3rd party products. The following errors are defined: Errors Error Id Severity Description 30000 Ok No Error 30001 Error Error parsing document 30002 Error Empty document 30003 Error Invalid root element 30004 Error Invalid validate XML file 30005 Warning No document match 30006 Warning Document not found 30007 Warning Document already deleted 30008 Error Can not parse return string 30009 Error Can not write document to repository 30010 Error Contains Validate Errors 30011 Error Invalid object document layout 30012 Warning Object does not need to be validated
The following 4GL Syntax errors are defined: 4GL Syntax Errors Error Id Severity Description 40000 Ok No Error 40001 Error No language validation document 40002 Error Invalid logic command 40003 Error Invalid number of arguments 40004 Error Invalid argument 40005 Error Valid argument, invalid as closing argument 40006 Error Structure control command defined outside structure 40007 Error Structure close command defined outside structure 40008 Error Missing structure close command 40009 Error Invalid Data Dictionary name 40010 Error Invalid Record name 40011 Error Invalid Index Name 40012 Error Invalid Data Source Name 40013 Error Invalid Logic Name
Multiple Validate Commands It is possible to combine VCs in one single request. 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: ... ... ... ... ]]> Combining multiple VCs will result in better performance. ProLinga-Validate Programming Notes To test ProLinga-Validate, the best and easiest way is to use the binaries that come with the product. Configure so ProLinga-Validate is running as a Web Service and use the client binary to send and receive Validate Commands. See the User Guide section for more details. To access the Validate engine from a C++ application, either network (SOAP) calls to send and receive Validate Commands over the network or the C++ API to link with the ProLinga-Validate library can be used. Network Client To be able to send and receive ProLinga-Validate commands over the network as SOAP calls from a C++ application, 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 you have to change the example XML request document with a valid Validate Command. Alternatively, have a look at the source code file ValidateClient.cpp in the src directory of ProLinga-Validate. When using this method, ProLinga-Validate must be running as a Web Service. Validate Library To be able to link directly with Validate from a C++ application, the Validate Library (C++ API) can be used. A very basic example program using the Validate Library looks like this: int main() { /*Init */ xmlDocPtr docReq, docRes; xmlNodePtr curReq, curRes; xmlBufferPtr bufRes; PlValidate val; /* Open Validate Environment */ val.validateOpen("./prolingavalcfg.xml"); /* Create Validate 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 *)"Validate", (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 *)"Validate"); xmlNewProp (curReq, (const xmlChar *)"Mode", (const xmlChar *)"Request"); curReq = xmlNewTextChild (curReq, NULL, (const xmlChar *)"Object", (const xmlChar *)""); xmlNewProp (curReq, (const xmlChar *)"Application", (const xmlChar *)"MyOrder"); xmlNewProp (curReq, (const xmlChar *)"Type", (const xmlChar *)"Logic"); xmlNewProp (curReq, (const xmlChar *)"Name", (const xmlChar *)"RaiseStock"); /* Process Validate Command */ docRes = val.executeCommand(docReq); /* Print Response */ bufRes = xmlBufferCreate(); curRes = xmlDocGetRootElement(docRes); xmlNodeDump(bufRes, docRes, curRes, 0, 1); printf("%s\n", (char *)xmlBufferContent(bufRes)); /* Close Validate Environment */ val.validateClose(); /* Free */ xmlBufferFree(bufRes); xmlFreeDoc(docRes); xmlFreeDoc(docReq); /* Return */ return 0; } ]]> When running this application, a connection is made to the Validate environment. When opening this connection an argument with the path and name of the validate configuration file can be passed as an argument. The system then knows details as in which directory it can find the Language Validation file etc. The configuration file has to be in a certain format, which is explained further on. The Validate Command is then presented to the Validate process engine and a response is returned. This response is printed to to stdout (screen). The connection to Validate is closed and the program exits. After creating a connection using the openValidate class function, more than one VC can be executed without the need to close and open the Validate environment for every call. In fact performance wise this is the prefered 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 Validate code will be changed as the project progresses. The validate environment has to access the application Repository. This Repository can either be accessed via the network connecting to the Repository Web Service or it can be accessed using a direct local path to the Repository. To compile the program using the network Repository access, use the following command: g++ validate_test.cpp -o validate_test `pkg-config --cflags --libs prolinga-validate` ProLinga-Soap Library libprolingasoapclient has to be available for this option. To compile the program using direct local path Repository access, use the following command: g++ validate_test.cpp -o validate_test `pkg-config --cflags --libs prolinga-validate_nonet` ProLinga-Validate Library libprolingavalidate_nonet has to be available for this option. You may need to set the environment variable PKG_CONFIG_PATH to point to the directories where prolinga-validate.pc is located. This can be directory /usr/lib/pkgconfig or directory /usr/local/lib/pkgconfig on GNU/Linux for example. ProLinga-Validate 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. Download ProLinga-Validate 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-Validate Prerequisites ProLinga-Validate &version; has been built and tested on Fedora Core, Mandriva Linux, Debian, Ubuntu 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. ProLinga-Soap This product provides a SOAP/XML engine. Optional 3rd party package(s) for a successful build: ProLinga-Repository This product provides an Application XML Repository. It is only required for direct linkage with the ProLinga-Repository Library. When choosing the (prefered) Web Services access method, this product is not required. xsltproc. Command line processor. This package is only required to re-generate the HTML pages after making changes to the documentation. 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 ProLinga-Repository: Product root dir: /opt/builds/prolinga Current version: 0.0.1 Download: http://download.prolinga.org Build Instructions: cd /opt/builds/prolinga/prolinga-repository-0.0.1 ./configure --prefix=/opt/builds/prolinga/prolinga-repository-0.0.1 make make install See the ProLinga-Repository Project documentation for more installation information. 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. 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 External (API) header 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 link with ProLinga-Repository and build library libprolingavalidate_nonet, type: ./configure --enable-local-repository 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.5 --with-libxml-prefix=/path/to/libxml2 ProLinga Repository >=0.0.1 --with-prolingarepository-prefix=/path/to/prolingarepository 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. --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-Validate 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. Implement XML Schemas for validation. Libxml2 is finishing up XML schemas. If it is still too far away, start with DTD. ProLinga-Validate 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. Archiver at the moment can only be used to initialize the Repository. We should have options available as creating application dump, reading application dump etc. Code review and cleanup. Make it more C++ Object Oriented. Logging. A simple logging mechanism has been implemented. 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. As enhancements, we should look into making ProLinga-Validate a more useful product by itself, rather then "just" a project for the ProLinga environment. Add command line options to the binaries. At least a -? should be available. 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 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. 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-Validate C++ API This section contains the API reference for ProLinga-Validate. All the public interfaces are documented here. &prolinga-validate-API; ProLinga-Validate User Guide This section contains the user guide for the ProLinga-Validate. All the binaries are documented here. &prolinga-validate-userguide; &fdl;