Index: trunk/docs/install/installation.rst =================================================================== --- trunk/docs/install/installation.rst (revision 819) +++ trunk/docs/install/installation.rst (revision 917) @@ -147,4 +147,37 @@ `_. +Metadata Database (Optional) +***************************** + +.. _zoo_create_metadb: + +It is possible to use a PostgreSQL database to store metadata +information about WPS Services. This support is optional and require +to be activated by using the ``--with-metadb=yes`` option. + +To create the database for storing the metadata informations about the +WPS Services, you may use the following command: + +.. code:: + + createdb zoo_metadb + psql zoo_metadb -f zoo-project/zoo-kernel/sql/zoo_collectiondb.sql + +In case you want to convert an existing zcfg file then, you can use +the ``zcfg2sql`` tool from the command line. It can be found in +``thirds/zcfg2sql`` and can be build simply by running the ``make`` +command. After compilation you only need to give it the path of the +zcfg file you want to obtain the SQL queries required to store the +metadata informations in the database rather than in zcfg file. + +For instance you may use the following command: + +.. code:: + + #Direct import in the zoo_metadb database + ./zcfg2sql /Path/To/MyZCFGs/myService.zcfg | psql zoo_metadb + #Create a SQL file for a futur import + ./zcfg2sql /Path/To/MyZCFGs/myService.zcfg > myService.sql + @@ -154,5 +187,5 @@ If ``yaml.h`` file is not found in your ``/usr/include`` directory and ``libyaml.so`` is not found in ``/usr/lib``, a ``--with-yaml`` option -can be used to specify its location. For instance, if the headeer file +can be used to specify its location. For instance, if the header file lies in ``/usr/local/include`` and the shared library is located in ``/usr/local/lib``, you may use the following command: Index: trunk/docs/kernel/configuration.rst =================================================================== --- trunk/docs/kernel/configuration.rst (revision 819) +++ trunk/docs/kernel/configuration.rst (revision 917) @@ -94,9 +94,18 @@ service providers, e.g., shared libraries with service implementations (the ``serviceProvider`` parameter in the service configuration (.zcfg) file). + * ``memory``: (Optional) can take the value ``load`` to ensure that + the value field of the inputs data will be filled by the ZOO-Kernel + or ``protected`` to have only the ``cache_file`` filled. + .. warning:: The ``libPath`` parameter is currently only recognized by services implemented in C/C++ or PHP, and may be moved to another section in future versions. - + + +.. warning:: + Depending on the ``memory`` parameter the WPS Service will receive + different fields (``value`` or ``cache_file``). + In case you have activated the MapServer support, please refer to :ref:`this specific section `. @@ -264,4 +273,20 @@ hosts=localhost,127.0.0.1 +Optionaly, you can also define the shared url(s), meaning that even if +the ressource requires authentication to be accessed, this +authentifcation won't be used to define the name for storing the +file. Hence, two user with different authentication will use the same +file as it is considerated as shared. You can find bellow a sample +security section containing the shared parameter. In this example, +every requests to access the coverage using the url defined in the +shared parameter (``myHost/cgi-bin/WCS_Server``) will be shared +between users. + +.. code:: + + [security] + attributes=Authorization,Cookie,User-Agent + hosts=localhost,127.0.0.1 + shared=myHost/cgi-bin/WCS_Server .. _zoo_activate_db_backend: @@ -300,4 +325,38 @@ to setup the database. + +Database section +............................... + +The database section allows to configure the ZOO-Kernel to access the +metadata information about WPS Services by using a PostgreSQL database +in addition to the zcfg files. + +.. code-block:: guess + + [metadb] + dbname=zoo_metadb + port=5432 + user=username + host=127.0.0.1 + type=PG + +This will generate strings to be passed to GDAL to connect the +database server: + +.. code-block:: guess + + :host= port= user= dbname= + + +With the previous database section, it will give the following: + +.. code-block:: guess + + PG:"dbname=zoo_metadb host=127.0.0.1 port=5432 user=username" + +Please refer to this `section `_ to learn how +to setup the database. + Include section ............................... Index: trunk/docs/kernel/hpc.rst =================================================================== --- trunk/docs/kernel/hpc.rst (revision 917) +++ trunk/docs/kernel/hpc.rst (revision 917) @@ -0,0 +1,339 @@ +.. _kernel-hpc: + +Optional HPC support +====================== + +The optional ZOO-Kernel HPC support gives you the opportunity to use +OGC WPS for invoking remote execution of OTB applications. The current +implementation rely on `OpenSSH `_ and the +`Slurm `_ scheduler. + +.. note:: + + |slurm| `Slurm `_ is an acronym for Simple Linux Utility for Resource Management. Learn more on official `website `__. + +For executing an OGC WPS Service using this HPC support, one should +use the OGC WPS version 2.0.0 and asynchornous request. Any tentative +to execute synchronously a HPC service will fail with the message "The +synchronous mode is not supported by this type of service". The +ZOO-Kernel is not the only responsible for the execution and will wait +for the execution on the HPC server to end before being able to +continue its execution. Also, transfering the data from the WPS server +to the cluster and downloading the data produced by the execution will +take time. Hence, when OGC WPS Client will request for GetCapabilities +or DescribeProcess only the "async-execute" mode will be present in +the jobControlOptions attribute for the HPC services. + +You can see in the sequence diagram below the interactions between +the OGC WPS Server (ZOO-Kernel), the mail daemon (running on the OGC +WPS server), the Callback Service and, the HPC Server during an +execution of a HPC Service. The dashed lines represent the behavior in +case the optional callback service invocation has been activated. These +invocations are made asynchronously for lowering their impact over the +whole process in case of failure of the callback service for instance. + +By now, the callback service is not a WPS service but an independent server. + +|hpc_support| + +.. |slurm| image:: https://slurm.schedmd.com/slurm_logo.png + :height: 100px + :width: 100px + :scale: 45% + :alt: Slurm logo + +.. |hpc_support| image:: ../_static/hpc_schema.svg + :scale: 65% + :alt: HPC Support schema + + +Installation and configuration +------------------------------ + +Follow the step described below in order to activate the ZOO-Project optional HPC support. + +Prerequisites +..................... + + * latest `ZOO-Kernel + `_ + trunk version + * `libssh2 `_ + * `MapServer `_ + * an access to a server with `Slurm `_ + and `OrfeoToolBox `_. + +Installation steps +........................... + +ZOO-Kernel +**************************** + +Compile ZOO-Kernel using the configuration options as shown below: + +.. code-block:: guess + + cd zoo-kernel + autoconf + ./configure --with-hpc=yes --with-ssh2=/usr --with-mapserver=/usr --with-ms-version=7 + make + sudo make install + +Optionally, you can ask your ZOO-Kernel to invoke a callback service +which is responsible to record execution history and data +produced. In such a case you can add the ``--with-callback=yes`` +option to the configure command. + +.. note:: + + In case you need other languages to be activated, such as Python + for exemple, please use the corresponding option(s). + +FinalizeHPC WPS Service +**************************** + +For being informed that the remote OTB application ends on the +cluster, one should invoke the FinalizeHPC service. It is responsible +to connect using SSH to the HPC server to run an ``sacct`` command for +extracting detailled informations about the sbatch that has been +run. If the ``sacct`` command succeed, and the service is no more +running on the cluster, then the informations are stored in a local +conf file containing a ``[henv]`` section definition, the service +connect to unix domain socket (opened by the ZOO-Kernel that has +initially schedduled the service through Slurm) to inform about the +end of the service run on the cluster. This makes the initial +ZOO-Kernel to continue its execution by downloading output data +produced over the execution of the OTB application on the cluster. So, +this service should be build and deployed on your WPS server. You can +use the following commands to do so. + +.. code-block:: guess + + cd zoo-service/utils/hpc + make + cp cgi-env/* /usr/lib/cgi-bin + mkdir -p /var/data/xslt/ + cp xslt/updateExecute.xsl /var/data/xslt/ + +You should also copy the +.. note:: + + FinalizeHPC should be called from a daemon, responsible for reading + mails sent by the cluster to the WPS server. + + +Configuration steps +............................... + +Main configuration file +**************************** + +When HPC support is activated, you can use different HPC configuration +by adding ``confId`` to your usual ``serviceType=HPC`` in your zcfg +file. For being able to find which configuration a service should +use, the ZOO-Kernel require to know what are the options for creating +the relevant sbatch. + +Also, you can define multiple configuration to run the OTB application +on the cluster(s) depending on the size of the inputs. You should +define in the section corresponding to your ``ServiceType`` the +treshold for both raster (``preview_max_pixels``) and vector +(``preview_max_features``) input. In case the raster or the vector +dataset is upper the defined limit, then the ``fullres_conf`` will +be used, in other case the ``preview_conf`` will be. + +For each of this configurations, you will have define the parameters +to connect the HPC server, by providing ``ssh_host``, ``ssh_port``, +``ssh_user`` and, ``ssh_key``. Also, you should set where the input +data will be stored on the HPC server, by defining +``remote_data_path`` (the default directory to store data), +``remote_presistent_data_path`` (the directory to store data +considerated as shared data, see below) and, ``remote_work_path`` the +directory used to store the SBATCH script created locally then, +uploaded by the ZOO-Kernel. + +Also, there are multiple options you can use to run your applications +using SBATCH. You can define them using ``jobscript_header``, +``jobscript_body`` and ``jobscript_footer`` or by using +``sbatch_options_`` where ```` should be +replaced by a real option name, like ``workdir`` in the following +example. For creating the SBATCH file, the ZOO-Kernel create a file +starting with the content of the file pointed by ``jobscript_header`` +(if any, a default header is set in other case), then, any option +defined in ``sbatch_options_*`` and a specific one: ``job-name``, +then, ``jobscript_body`` is added (if any, usually to load required +modules), then the ZOO-Kernel add the invocation of the OTB +application then, optionally the ``jobscript_footer`` is added, if +any. + +Finally, ``remote_command_opt`` should contains all the informations +you want to be extracted by the ``sacct`` command run by the +FinalizeHPC service. ``billing_nb_cpu`` is used for billing purpose to +define a cost for using a specific option (preview or fullres). + +In addition to the specific ``HPC_`` section and the corresponding +fullres and preview ones, you should define in the ``[security]`` +section using the ``shared`` parameter to set the URLs from where the +downloaded data should be considerated as shared, meaning that even if +this ressources requires authentication to be accessed, any +authenticated user will be allowed to access the cache file even if +it was created by somebody else. Also, this shared cache won't contain +any authentication informations in the cache file name as it is +usually the case. + +.. code-block:: guess + + [HPC_Sample] + preview_max_pixels=820800 + preview_max_features=100000 + preview_conf=hpc-config-2 + fullres_conf=hpc-config-1 + + [hpc-config-1] + ssh_host=mycluster.org + ssh_port=22 + ssh_user=cUser + ssh_key=/var/www/.ssh/id_rsa.pub + remote_data_path=/home/cUser/wps_executions/data + remote_persitent_data_path=/home/cUser/wps_executions/datap + remote_work_path=/home/cUser/wps_executions/script + jobscript_header=/usr/lib/cgi-bin/config-hpc1_header.txt + jobscript_body=/usr/lib/cgi-bin/config-hpc1_body.txt + sbatch_options_workdir=/home/cUser/wps_executions/script + sbatch_substr=Submitted batch job + billing_nb_cpu=1 + remote_command_opt=AllocCPUS,AllocGRES,AllocNodes,AllocTRES,Account,AssocID,AveCPU,AveCPUFreq,AveDiskRead,AveDiskWrite,AvePages,AveRSS,AveVMSize,BlockID,Cluster,Comment,ConsumedEnergy,ConsumedEnergyRaw,CPUTime,CPUTimeRAW,DerivedExitCode,Elapsed,Eligible,End,ExitCode,GID,Group,JobID,JobIDRaw,JobName,Layout,MaxDiskRead,MaxDiskReadNode,MaxDiskReadTask,MaxDiskWrite,MaxDiskWriteNode,MaxDiskWriteTask,MaxPages,MaxPagesNode,MaxPagesTask,MaxRSS,MaxRSSNode,MaxRSSTask,MaxVMSize,MaxVMSizeNode,MaxVMSizeTask,MinCPU,MinCPUNode,MinCPUTask,NCPUS,NNodes,NodeList,NTasks,Priority,Partition,QOS,QOSRAW,ReqCPUFreq,ReqCPUFreqMin,ReqCPUFreqMax,ReqCPUFreqGov,ReqCPUS,ReqGRES,ReqMem,ReqNodes,ReqTRES,Reservation,ReservationId,Reserved,ResvCPU,ResvCPURAW,Start,State,Submit,Suspended,SystemCPU,Timelimit,TotalCPU,UID,User,UserCPU,WCKey,WCKeyID + + [hpc-config-2] + ssh_host=mycluster.org + ssh_port=22 + ssh_user=cUser + ssh_key=/var/www/.ssh/id_rsa.pub + remote_data_path=/home/cUser/wps_executions/data + remote_persitent_data_path=/home/cUser/wps_executions/datap + remote_work_path=/home/cUser/wps_executions/script + jobscript_header=/usr/lib/cgi-bin/config-hpc2_header.txt + jobscript_body=/usr/lib/cgi-bin/config-hpc2_body.txt + sbatch_options_workdir=/home/cUser/wps_executions/script + sbatch_substr=Submitted batch job + billing_nb_cpu=4 + remote_command_opt=AllocCPUS,AllocGRES,AllocNodes,AllocTRES,Account,AssocID,AveCPU,AveCPUFreq,AveDiskRead,AveDiskWrite,AvePages,AveRSS,AveVMSize,BlockID,Cluster,Comment,ConsumedEnergy,ConsumedEnergyRaw,CPUTime,CPUTimeRAW,DerivedExitCode,Elapsed,Eligible,End,ExitCode,GID,Group,JobID,JobIDRaw,JobName,Layout,MaxDiskRead,MaxDiskReadNode,MaxDiskReadTask,MaxDiskWrite,MaxDiskWriteNode,MaxDiskWriteTask,MaxPages,MaxPagesNode,MaxPagesTask,MaxRSS,MaxRSSNode,MaxRSSTask,MaxVMSize,MaxVMSizeNode,MaxVMSizeTask,MinCPU,MinCPUNode,MinCPUTask,NCPUS,NNodes,NodeList,NTasks,Priority,Partition,QOS,QOSRAW,ReqCPUFreq,ReqCPUFreqMin,ReqCPUFreqMax,ReqCPUFreqGov,ReqCPUS,ReqGRES,ReqMem,ReqNodes,ReqTRES,Reservation,ReservationId,Reserved,ResvCPU,ResvCPURAW,Start,State,Submit,Suspended,SystemCPU,Timelimit,TotalCPU,UID,User,UserCPU,WCKey,WCKeyID + + [security] + attributes=Cookie,Cookies + hosts=* + shared=myhost.net/WCS + +You can see below an example of ``jobscript_header`` file. + +.. code-block:: guess + + #!/bin/sh + #SBATCH --ntasks=1 + #SBATCH --ntasks-per-node=1 + #SBATCH --exclusive + #SBATCH --distribution=block:block + #SBATCH --partition=partName + #SBATCH --mail-type=END # Mail events (NONE, BEGIN, END, FAIL, ALL) + #SBATCH --mail-user=user@wps_server.net # Where to send mail + +You can see below an example of ``jobscript_body`` file. + + +.. code-block:: guess + + # Load all the modules + module load cv-standard + module load cmake/3.6.0 + module load gcc/4.9.3 + module load use.own + module load OTB/6.1-serial-24threads + +In casse you have activated the callback service, then you should also +have a ``[callback]`` section, in which you will define ``url`` to +invoke the callback service, ``prohibited`` to list the services that +should not require invocation of the callback sercvice if any and, +``template`` pointing to the local ``updateExecute.xsl`` file used to +replace any inputs provided by value to the reference to the locally +published OGC WFS/WCS web services. This execute request is provided +to the callback service. + +.. code-block:: guess + + [callback] + url=http://myhost.net:port/callbackUpdate/ + prohibited=FinalizeHPC,Xml2Pdf,DeleteData + template=/home/cUser/wps_dir/updateExecute.xsl + + +OGC WPS Services metadata +**************************** + +To produce the zcfg files corresponding to the metadata definition of +the WPS services, you can use the otb2zcfg tool to produce them. You +will need to replace ``serviceType=OTB`` by ``serviceType=HPC`` and, +optionally, add one line containing ``confId=HPC_Sample`` for +instance. + +Please refer to `otb2zcfg +<./orfeotoolbox.html#services-configuration-file>`_ documentation to +know how to use this tool. + +Using the HPC support, when you define one output, there will be +automatically 1 to 3 inner outputs created for the defined output: + +download_link + URL to download to generated output + +wms_link + URL to access the OGC WMS for this output (only in case + `useMapserver=true`) + +wcs_link/wfs_link + URL to access the OGC WCS or WFS for this output (only in case + `useMapserver=true`) + +You can see below an example of Output node resulting of the +definition of one output named out and typed as geographic imagery. + + +.. code-block:: guess + + + Outputed Image + Image produced by the application + out + + Download link + The download link + download_link + + + + + + + WMS link + The WMS link + wms_link + + + + + + + WCS link + The WCS link + wcs_link + + + + + + + + + + + + Index: trunk/docs/kernel/index.rst =================================================================== --- trunk/docs/kernel/index.rst (revision 819) +++ trunk/docs/kernel/index.rst (revision 917) @@ -14,3 +14,3 @@ orfeotoolbox sagagis - + hpc Index: trunk/docs/kernel/mapserver.rst =================================================================== --- trunk/docs/kernel/mapserver.rst (revision 819) +++ trunk/docs/kernel/mapserver.rst (revision 917) @@ -73,11 +73,11 @@ * `MapServer `__ version >= 6.0.1 -First download the lastest zoo-kernel by checking out the svn. Use the following command from do the directory where your previously checked out (in this example we will use ```` to design this directory). - -.. code-block:: guess - - cd - svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel-ms - +First download the lastest zoo-kernel by checking out the svn. Use the following command from do the directory where your previously checked out (in this example we will use ``$PREV_SVN_CO`` to design this directory). + +.. code-block:: guess + + svn checkout http://svn.zoo-project.org/svn/trunk/ $PREV_SVN_CO + cd $PREV_SVN_CO + Then uncompress the MapServer archive (ie. ``mapserver-6.0.1.tar.bz2``) into ``/tmp/zoo-ms-src``, and compile it using the following command: @@ -92,18 +92,13 @@ cp mapserv /usr/lib/cgi-bin -Once done, compile ZOO-Kernel with MapServer support from the ```` directory, using the following command: - -.. code-block:: guess - - cd zoo-kernel-ms +Once done, compile ZOO-Kernel with MapServer support from the ``$PREV_SVN_CO`` directory, using the following command: + +.. code-block:: guess + + cd zoo-kernel autoconf ./configure --with-python --with-mapserver=/tmp/zoo-ms-src/mapserver-6.0.1 make - -You can then copy the new ZOO-Kernel to ``/usr/lib/cgi-bin`` directory, as follow: - -.. code-block:: guess - - cp zoo_loader.cgi /usr/lib/cgi-bin + sudo make install @@ -119,4 +114,14 @@ dataPath = /var/www/temp/ mapserverAddress=http://localhost/cgi-bin/mapserv + +You can also add the following lines to the ``[main]`` section, in case +you want to use a default style for Polygon, Lines and Points vector +layer. + +.. code-block:: guess + + msStylePoly=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 WIDTH 3 END + msStyleLine=STYLE OUTLINECOLOR 202 109 19 WIDTH 3 END + msStylePoint=STYLE COLOR 202 109 19 OUTLINECOLOR 105 105 105 SYMBOL 0 SIZE 14 END The ``dataPath`` directory is mandatory and must belong to the Apache user. @@ -175,4 +180,10 @@ ************* +You have different options to define the style of the layer created +using the data returned by your service. + +msStyle ++++++++ + The optional ``msStyle`` parameter can also be used to define a custom MapServer style block (used for vector datasource only), as follow: @@ -181,9 +192,88 @@ msStyle = STYLE COLOR 125 0 105 OUTLINECOLOR 0 0 0 WIDTH 3 END -If a WPS service outputs a one band raster file, then it is possible to add a ``msClassify`` parameter and set it to ``true`` in the output ComplexData ```` or ```` nodes of its ``zcfg`` file. This allows ZOO-Kernel to use its own default style definitions in order to classify the raster using equivalent intervals. - -.. code-block:: guess - - msClassify = .... +msClassify +++++++++++ + +If a WPS service outputs a one band raster file, then it is possible +to add a ``msClassify`` parameter and set it to ``true`` in the output +ComplexData ```` or ```` nodes of its zcfg +file. This allows ZOO-Kernel to use its own default style definitions +in order to classify the raster using equivalent intervals. + +.. code-block:: guess + + msClassify = true + + +msInclude ++++++++++ + +In case you want to use another layer which use the result of your +service, for instance to produce a `heatmap +`_, then you can use +the +``msInclude`` and ``msLayer`` options in the output ``ComplexData`` +```` or ```` nodes of its zcfg file. You can see below an +example of use of this two options with the associated mapfile. + +.. code-block:: guess + + msInclude = /var/data/template.map + msLayer = heatmap + +You can find below a sample ``/var/data/template.map``: + +.. code-block:: guess + + MAP + SIZE 1000 500 + EXTENT -180 -90 180 90 + NAME "test heat" + IMAGETYPE "png" + + WEB + METADATA + "ows_srs" "epsg:4326 epsg:3857 epsg:900913" + "ows_enable_request" "*" + END # METADATA + END # WEB + + PROJECTION + "+init=epsg:4326" + END # PROJECTION + + LAYER + NAME "heatmap" # Corresponding to the msLayer defined + TYPE raster + CONNECTIONTYPE kerneldensity + CONNECTION "Result" + STATUS on + PROCESSING "RANGE_COLORSPACE=HSL" + PROCESSING "KERNELDENSITY_RADIUS=20" + PROCESSING "KERNELDENSITY_COMPUTE_BORDERS=ON" + PROCESSING "KERNELDENSITY_NORMALIZATION=AUTO" + OFFSITE 0 0 0 + CLASS + STYLE + COLORRANGE "#0000ff00" "#0000ffff" + DATARANGE 0 32 + END # STYLE + STYLE + COLORRANGE "#0000ffff" "#ff0000ff" + DATARANGE 32 255 + END # STYLE + END # CLASS + END # LAYER + + LAYER + NAME "points" + STATUS on + TYPE POINT + #DATA "/Library/WebServer/cache//ef76ee6642c1ea704e847e28120ba1ca.zca" + END # LAYER + END # MAPFILE + + + Example @@ -216,5 +306,5 @@ useMapserver = true asReference = true - msClassify = .... + msClassify = true Index: trunk/docs/kernel/sagagis.rst =================================================================== --- trunk/docs/kernel/sagagis.rst (revision 819) +++ trunk/docs/kernel/sagagis.rst (revision 917) @@ -4,9 +4,9 @@ ====================== -`SAGA GIS `_ provides a comprehensive set of geoscientific methods and spatial algorithms. The optional SAGA GIS support is available since `ZOO-Project 1.5 `__. It allows to execute the `SAGA Modules `_ directly as ZOO WPS Services thanks to a :ref:`kernel_index` specific internal mechanism which is detailed in this section. +`SAGA GIS `_ provides a comprehensive set of geoscientific methods and spatial algorithms. The optional SAGA GIS support is available since `ZOO-Project 1.5 `__. It allows to execute the `SAGA Modules `_ directly as ZOO WPS Services thanks to a :ref:`kernel_index` specific internal mechanism which is detailed in this section. .. note:: - |saga| `SAGA GIS `__ is the System for Automated Geoscientific Analyses. Learn more on official `website `__. + |saga| `SAGA GIS `__ is the System for Automated Geoscientific Analyses. Learn more on official `website `__. @@ -27,19 +27,10 @@ * latest `ZOO-Kernel `_ trunk version - * SAGA GIS (`SAGA-GIS 2.1.4 `_ ) - * libLAS-1.2 (`LibLAS-1.2 `_ ) + * `SAGA GIS `_ (7.2.0) Installation steps ........................... -.. Note:: These installation steps were successfully tested on Ubuntu 14.4 LTS - -Download lastest ZOO-Kernel code from SVN. - -.. code-block:: guess - - svn checkout http://svn.zoo-project.org/svn/trunk/zoo-kernel zoo-kernel - -Then compile ZOO-Kernel using the needed configuration options as shown bellow: +Compile ZOO-Kernel using the configuration options as shown bellow: .. code-block:: guess @@ -47,9 +38,14 @@ cd zoo-kernel autoconf - ./configure --with-saga=/usr/local/ + ./configure --with-saga=/usr/local/ --with-saga-version=7 make -And copy the newly created zoo_loader.cgi to ``/usr/lib/cgi-bin`` : - +And copy the newly created zoo_loader.cgi to ``/usr/lib/cgi-bin``. + +.. note:: + + The ``--with-saga-version`` option let you set the major + version number of SAGA-GIS. + .. code-block:: guess @@ -62,6 +58,8 @@ **************************** -Building the `saga2zcfg -`_ utility is required to activate the available SAGA-GIS Modules as WPS Services. This can be done using the following command: +Building the +`saga2zcfg `_ +utility is required to activate the available SAGA-GIS Modules as WPS +Services. This can be done using the following command: .. code-block:: guess Index: trunk/docs/services/howtos.rst =================================================================== --- trunk/docs/services/howtos.rst (revision 819) +++ trunk/docs/services/howtos.rst (revision 917) @@ -439,2 +439,76 @@ } + +R +---------- + +ZOO API +********* + +For using the R language from the ZOO-Project, you have first to copy +``minimal.r`` in the same directory as the ZOO-Kernel. + +The ZOO-API is available from a R script and provide access to a +global zoo environment which contains both static variables and also +the dictionaries for outputs and conf: + +:int zoo[["SERVICE_SUCCEEDED"]]: + Value to return in case your service end successfully. +:int zoo[["SERVICE_FAILED"]]: + Value to retrun in case of failure. + +The ZOO-API provides the following functions: + +:string ZOOTranslate(String s): + This function call the internal ZOO-Kernel function responsible for + searching a translation of ``s`` in the zoo-services dictionary. + +:void ZOOUpdateStatus(ZMaps conf,String pourcent): + This function call the updateStatus ZOO-Kernel function responsible + for updating the status of the running service (only usefull when + the service has been called asynchronously). + + +R ZCFG requirements +********************************** + +.. Note:: For each Service provided by your ZOO R Services Provider, + the ZCFG File must be named the same as the R function name + (it is case-sensitive). + +The ZCFG file should contain the following : + +serviceType + R +serviceProvider + The name of the R file to use as a ZOO Service Provider. For instance, if your + script, located in the same directory as your ZOO Kernel, was named ``my_module.r`` then + you should use ``my_module.r``. + + +R Data Structure used +******************************** + +The three parameters of the function are passed to the R function as +R dictionaries. + +The specificity of the R language make that it was easier to use +global variales than passing parameters by reference as we do in +other progamming languages. It is the reason why you will have to +access outpus by using the global variable as for the main +configuration dictionary. + +Sample ZOO R Services Provider +****************************************** + +.. code-block:: javascript + + source("minimal.r") + + hellor <- function(a,b,c) { + # Set the result + zoo[["outputs"]][["Result"]][["value"]] <<- ZOOTranslate(paste("Hello",b[["S"]][["value"]],"from the R World!",sep=" ")) + # Return SERVICE_SUCCEEDEED + return(zoo[["SERVICE_SUCCEEDEED"]]) + } +