XPath from a C application

The SaxonC C API can be used to evaluate XPath expressions from your own C application. Functions are provided to perform XPath processing in SaxonCXPath.h: namely evaluate(), evaluateSingle() and effectiveBooleanValue().

For these XPath evaluation functions, the XPath expression string is supplied as an argument, and expression parameters and other properties are supplied using the structs sxnc_parameter and sxnc_property, respectively. For evaluate() and evaluateSingle(), the results are returned as an XDM type given as the struct sxn_value. The effectiveBooleanValue() function returns a bool.

You can evaluate an XPath expression using the SaxonC C interface as follows:

1. The first step is the memory allocation for the processor and variables required by SaxonC. To simplify the process, the utility function initSaxonc() can be used to alloc the following variables:

   • environ - SaxonC environment given as the struct sxnc_environment.
   • processor - The SaxonC processor data structure given as the struct sxnc_processor which is used as a reference to the Saxon Processor object in Java.
   • parameters - The sxnc_parameter struct (an array) is used to represent the external variables supplied to the XPath expression. Note that there are several utility functions to construct XDM values provided in SaxonCXPath.h. For further details on supplying parameters, see the Configuration section in the SaxonC documentation.
   • properties - The sxnc_property struct (an array) is used to represent the required configuration properties and options for the processor. For a full list of the available properties see the Configuration section in the SaxonC documentation.

   For example:

   int cap = 10; sxnc_parameter *parameters; int parLen = 0, parCap; parCap = cap; sxnc_property *properties; int propLen = 0; parCap = cap; sxnc_environment *environ; sxnc_processor *processor; initSaxonc(&environ, &processor, &parameters, &properties, parCap, parCap);

2. Next set up the GraalVM environment to create and initialize a new independent VM instance, using the create_graalvm_isolate() function. This is required by the SaxonC processors.

   sxnc_environment *environ; create_graalvm_isolate(environi);

3. Use the c_createSaxonProcessor() function to create a SaxonC processor, which is used to create the XPath processor. The last argument is used to specify whether the processor is to be run with license enabled (i.e. for Saxon-EE and Saxon-PE) or off - set using values '1' and '0' respectively.

   int checkProc = c_createSaxonProcessor(environ, processor, 0);

4. Use the c_createXPathProcessor() function to create an XPath processor, which is used to evaluate XPath expressions.

   sxnc_xpath *xpathProc = (sxnc_xpath *)malloc(sizeof(sxnc_xpath)); int checkProc = c_createXPathProcessor(environi, processor, xpathProc);

5. Supply properties for the expression using the setProperty() function.

   For example, set the source document as follows:

   setProperty(&properties, &propLen, &propCap, "s", "../data/people.xml");

6. You can now evaluate an XPath expression, using the evaluate(), evaluateSingle() or effectiveBooleanValue() functions. For example, you could evaluate an XPath expression using:

   sxnc_value *result = evaluate(environ, xpathProc, cwd, "/out/person", parameters, properties, 0, propLen);

7. At the end of the program it is necessary to deallocate the memory created for the Saxon processor, parameters and properties; and cleanly release resources created by GraalVM.

   graal_tear_down(environi->thread); freeSaxonc(&environi, &processor, &parameters, &properties);