Application Programming Interface (API) for the PCRaster Model Engine

The API consists of a series of C functions. The list of functions and Api Examples should be used as starting point.

Deployment

All functions reside in the dynamic library PCRasterModelEngine.dll/libPCRasterModelEngine.so. The dynamic libraries on which PCRasterModelEngine library depends are listed in the deployment.txt file in the Developer/LinkOut directory. Note that for linux all the libraries PCRasterModelEngine depends on are compiled with an rpath value of ".". That means that libraries should be installed in the same directory as PCRasterModelEngine itself.

API conventions

All functions have the calling convention common to the operating system the API is compiled for:

The calling conventions rationale and the PCR_DLL_FUNC macro are present in pcrdll.h

Note that all strings (char *) are currently encoded as C-strings whith ANSI encoding (1 byte per char) and are not UniCode (2 bytes per char).

Api Examples

The code examples are present in:

the apiExamples directory uses the pcrcitd.exe driver to process the XML files (see demo.bat). pcrcitd looks like this:

      #include <stdlib.h>
      #include <stdio.h>

      #include "pcrcalc.h"


      static void checkError(PcrScript *s)
      {
        if (pcr_ScriptError(s)) {
          fprintf(stderr,pcr_ScriptErrorMessage(s));
          exit(1);
        }
      }
 
     // change " within PCRasterLicense file to ' if neccesary
     const char *licString =
     "<?xml version = '1.0' encoding = 'UTF-8'?>"\
     " <!DOCTYPE systemLicense PUBLIC '-//PCRaster//Generic' 'pcraster.dtd'>"\
     "<systemLicense>"\
     " <licensee value='ThisCompany inc.' />"\
     " <licensedFeature value='DevelopersLicense' />"\
     "  .... some elements removed .... "\
     " <licenseKey value='741604gy6s2k9ga0pfck24jg0l3ffo' />"\
     "</systemLicense>";
 
 
      int main(int argc, char *argv[])
      {
         PcrScript* s;
         char* installError;
         if (argc <= 1) {
           fprintf(stderr,"PCRaster XML client interface test driver\n");
           fprintf(stderr,"USAGE: pcrcitd inputModelFile.xml\n");
           exit(1);
         }
         const char *msg = pcr_installDevelopersLicense(licString);
         if (msg) {
           fprintf(stderr,msg);
           exit(1);
         }
 
 
         /* argv[1] is an xml file */
         s=pcr_createScriptFromXMLFile(argv[1]);
         if (!s) {
            printf("PANIC allocation of a few bytes failed");
            abort();
         }
 
         /* typical error: case.xml is not existant */
         checkError(s);
 
         pcr_ScriptExecute(s);
         /* typical errors:
 - case.xml is malformed
 - some inputs are not found
 - resource error: memory/disk full
          */
         checkError(s);
 
         pcr_destroyScript(s);
 
         return 0;
      }

The examples in csharp/ScriptTest.cs uses the API "as-is" in respect to minimizing the use of C# language features. Therefor the code can be used as examples for other client languages such as Java, Delphi or Visual Basic.

The XML vocabulary

A single XML vocabulary defined in PCRaster.xsd is used in two roles (in and out):

Within the PCRaster.xsd schema the XML nodes are documented within an xs:annotation element (view XML source in Visual Studio). The difference in application of the [in] and [out] case of certain nodes is clearly stated. Note that not all nodes present in PCRaster.xsd are used in the current API.

Error Handling

All functions will store a possible error description in the PcrScript object. The success of all functions can be checked of the function call by evaluating the result of pcr_ScriptError() and/or pcr_ScriptErrorMessage(). Errors on a PcrScript object are NOT recoverable; All successive calls on the same PcrScript will do nothing. A PcrScript object in error state should still be deleted with pcr_destroyScript().

Generated on Tue Apr 14 08:35:58 2015 for PCRaster LinkOut API by  doxygen 1.6.3