XQuery from a C application

The SaxonC C API can be used to run queries from your own C application. Functions are provided to perform XQuery queries in SaxonCProcessor.h.

For these XQuery functions, the XML document source and XQuery string or file (and other properties) are supplied using the sxnc_property struct. The sxnc_parameter struct can be used to supply external variables defined in the query. The query results can be output to file using the executeQueryToFile() function, or string representation using the executeQueryToString() function.

You can perform a query 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 XQuery query. For further details 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. These properties are set using the setProperty() function. For instance, property 'q' is used to specify the file name of the query, or property 'qs' is used to pass the query as string. 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 for XSLT and XQuery processing. 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. Supply properties for the query using the setProperty() function. The query itself can either be supplied from a file using the property 'q' to specify the file name, or as a string using the property 'qs'.

    For example, set the source document, the current working directory, and the query string, as follows:

    setProperty(&properties, &propLen, &propCap, "s", "../data/cat.xml"); setProperty(&properties, &propLen, &propCap, "cwd", cwd); setProperty(&properties, &propLen, &propCap, "qs", "<out>{count(/out/person)}</out>");

  5. You can now execute the XQuery, using the executeQueryToFile() or executeQueryToString() functions. For example, you could execute a query and return the results as a string representation, using:

    const char *result = executeQueryToString(environi, processor, cwd, 0, properties, 0, propLen);]

  6. 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);