Saxonica: Saxon/C product information

Saxon/C

On this page:

See also:


Optimized and packaged with Excelsior JET

XML document processing for the C/C++/PHP platforms

Saxon/C is a cross-compiled variant of Saxon from the Java platform to the C/C++ platform. All features of Saxon have been ported, other than those (such as collations) that are necessarily platform dependent. In particular, Saxon/C provides processing in XSLT, XQuery and XPath, and Schema validation. It therefore makes these processing capabilities available to a plethora of other languages that are strongly coupled to C/C++ such as PHP, Perl, Python, and Ruby. (For instance, saxon-node uses Saxon/C to create an interface with with node.js.)

Releases

Saxon/C 1.1.0, the first release in the 1.1 series, released 27 September 2017, on Linux, Mac OS X, and Windows.

Saxon/C 1.1 offers the main Saxon products Saxon-HE, Saxon-PE and Saxon-EE for the C/C++/PHP programming platforms. APIs are available to run XSLT 3.0, XQuery 3.1, XPath 3.1 and Schema Validation from C/C++ or PHP applications.

Saxon/C 1.1 is built from the Saxon 9.8.0.4 Java product using the Excelsior JET tool (version 11.3 MP1).

For detailed information on all Saxon/C releases, see the Release notes.

Download

Separate download files are available for the three product editions of Saxon/C, namely: Saxon-HE/C (open-source), Saxon-PE/C and Saxon-EE/C (commercial products).

DOWNLOAD

Download the latest Saxon/C releases from the C/C++/PHP platforms download page.

For older releases (including releases in the previous 1.0 series), go to Archive.

Return to top of page

License

The products Saxon-PE/C and Saxon-EE/C are commercial products, and require a license key. By downloading the software, you agree to the terms and conditions published at http://www.saxonica.com/license/eval-license.pdf (for use with a free evaluation license) or http://www.saxonica.com/license/paid-license.pdf (in the case of paid-up licenses, purchased from our online store).

Location of the Saxon license file for commercial products: Saxon/C looks in the path relative to where the main library has been installed. For example, in '/usr/lib', if this is where libsaxon[EDITION]c.so has been installed. Alternatively, Saxon also looks for the license according to the environment variable SAXONC_HOME, if this has been set. The license file can also be placed in the same directory as the stylesheet, but we advise against this for PHP servers where the license might be compromised.

The product Saxon-HE/C is open-source. The primary license is the Mozilla Public License version 2.0. In most cases, the source files are marked as being "incompatible with secondary licenses", which means that the code cannot be combined with code issued under a GPL license (the reason for this is the difficulty of contacting all past contributors to gain their assent).

Some components are licensed under the Apache version 2.0 license or under BSD-style licenses. For more information see Licenses.

Return to top of page

Documentation

Saxon/C version 1.1 see also PHP API

Saxon/C version 1.0 see also PHP API

Saxon/C beta version 0.3.1 see also PHP API

Return to top of page

Installation (Linux)

Prerequisites

Please have the following packages on your machine to build the Saxon/C PHP extension: make, php-devel, (php7.1-dev), apache2 or httpd, gcc-c++ or g++, gcj-jdk (or just link the jni.h file).

Saxon-[HE|PE|EE]/C

In the following, [EDITION] means one of: HE, PE, EE.

To install the Saxon-[EDITION]/C release, unzip the file libsaxon-[EDITION]C-setupv1.1.0.zip and execute the command:

./libsaxon-[EDITION]C-setup-v1.1.0

The first step is to select the destination where the product files will be installed. The product files are unpacked in the directory 'Saxon-[EDITION]C'.

Link the dynamic saxon library so it can be found. For example:

ln -s /usr/lib/Saxonica/Saxon-[EDITION]C1.1.0/libsaxon[EDITION].so /usr/lib/libsaxon[EDITION].so

You need to set up the environment for the jet jvm. The jvm is in the directory 'Saxonica/Saxon-[EDITION]C1.1.0/rt'. Link the jetvm library so it can be found. For example:

ln -s /usr/lib/Saxonica/Saxon-[EDITION]C1.1.0/rt /usr/lib/rt

This works best for a 32-bit system, and '/usr/lib64/' for a 64-bit system. Alternatively you can set the JET-home environment accordly, e.g. 'JET-home=Saxonica/Saxon-[EDITION]C1.1.0/rt'. The directory 'JET-home/lib/i386' must be listed in the LD_LIBRARY_PATH environment variable. For instance, if you are using a bash or Bourne shell, use the following command:

export LD_LIBRARY_PATH=/usr/lib/rt/lib/i386:/usr/lib/rt/lib/i386/jetvm:$LD_LIBRARY_PATH

Or on a 64-bit machine:

export LD_LIBRARY_PATH=/usr/lib64/rt/lib/amd64:/usr/lib64/rt/lib/amd64/jetvm:$LD_LIBRARY_PATH

So, for Ubuntu, you can create '/etc/ld.so.conf.d/jetvm.conf', with content (change amd64 to i386 for a 32-bit machine):

And then run:

$ sudo ldconfig

When working with PHP the export command above should be added to apache environment variables. The apache2 config file is located in one of the following locations depending on your linux distribution:

The C++ compiler requires the include path to the java header files during compilation. In most cases this is achieved simply by installing gcj-jdk. Alternatively, according to http://www.network-theory.co.uk/docs/gccintro/gccintro_23.html, add the java header file dirs in the JAVA_HOME directory to this environment variable used by the compiler. The following example is for a 64-bit machine:

CPLUS_INCLUDE_PATH=/usr/lib/rt/amd64:$JAVA_HOME/include/linux:$JAVA_HOME/include
export CPLUS_INCLUDE_PATH

For a 32-bit machine the 'rt' directory and libsaxon.so library must be copied to the location '/usr/lib'.

For a 64-bit machine the 'rt' directory and the libsaxon.so library must be copied to the location '/usr/lib64'. You must also copy the saxon-data directory to a respective location based on the machine.

PHP extension

We have includes builds for the php extension module in the directory 'php-library-module' for PHP5 and PHP7. See the file saxon.so. These were built on a Ubuntu machine with PHP 5.5.9 and PHP 7.2 respectively. It should be moved under the PHP installation where extension libraries are kept.

To build the PHP extension follow the steps below.

(Alternatively, you may like to use the installation script install.sh supplied by Petr Zak - written for a 64-bit machine, but can be changed for a 32-bit machine.)

Run the commands:

Building with PHP5: Replace the file config.m4 in the directory Saxon-C-API/ with the one held in Saxon-C-API/PHP5-Build. Then run the steps above.

Alternatively, you can update the php.ini file or added the 20-saxon.ini file under the conf.d directory (if using Ubuntu it is usually in the location '/etc/php/7.2/apache2/') to contain the PHP extension. Insert the following in the Dynamic Extensions section: extension=saxon.so, then run the command:

If you cannot load the extension from the php.ini file, you need to load it at script execution time with the following code. However this is not recommended as the loading and unloading can be slow:

Return to top of page

Installation (Windows)

Saxon-HE/C

To install the Saxon-HE/C release run the executable libsaxon-HEC-setup.exe.

The first step is to select the destination where the product files will be installed - the default is 'C:\Program Files\Saxonica\SaxonHEC1.1.0'. This is the location that the PHP extension looks for the Saxon-C DLL library, so we advise using this default location.

PHP extension

The PHP extension has not yet been built. It can be built using the PHP source. We hope to provide builds for the PHP on Windows soon.

Note: On Windows we recommend setting the cwd using the overloaded constructor because there remains an issue with building Saxon/C with PHP when using the function VCWD_GETCWD. That is,
$proc = new SaxonProcessor('C://www/html//trax//');
should replace instances of
$proc = new SaxonProcessor();
in your PHP scripts (see the
PHP example code in the Getting started section for an example).

To build the PHP extension yourself please see the Saxon-C-API Visual Studio 2008 project included in the installation (e.g. 'C:\Program Files\Saxonica\SaxonHEC1.1.0\Saxon-C-API').

Return to top of page

Building from source

We endeavour to build the library of Saxon/C on 32/64- bit machines for both linux and windows. But in the case where the binary is not available for a particular machine we suggest building the shared binary library from the Java jar file. To do this you will need the Excelsior Jet tool (version 11.3 MP1). Excelsior JET provides an evaluation package and free licenses for non-commercial use (see their website for more details).

Return to top of page

Getting started

To get started writing a C/C++ or PHP application, first browse the Saxon/C API starting with the SaxonProcessor class which acts as a factory class for generating the processors.

C

Saxon/C can be run from the commandline in a similar way to its Java counterpart (same options are available). See the file Transform.c, Query.c and Validate.c (which is available in Saxon-EE/C) in the directory 'command'. The build.sh script can be executed to build the commandline programs.

For C programming see the test harnesses for XSLT, XQuery, Schema Validation and XPath in C code along with the build and run script in the directory 'samples/cTests'. The following files are required to build Saxon/C on C++: SaxonCGlue.c, SaxonXProcessor.c, SaxonCXPath.c To compile the sample test code in C execute the 'build.sh' file the directory 'cTests'. This file builds executables for the test cases testing XSLT, XPath, XQuery and schema Validator. The command is similar to the following:
gcc -m32 -I$jdkdir/include -I$jdkdir/include/linux -I /System/Library/Frameworks/JavaVM.framework/Headers ../SaxonCGlue.c ../SaxonCProcessor.c ../SaxonCXPath.c testXSLT.c -o testXSLT -ldl -lc $1 ./testXSLT

C++

For C++ programming see sample code for XSLT, XQuery, Schema Validation and XPath in C++ code along with the build and run script in the directory 'samples/cppTests'. The following files are required to build Saxon/C on C++: SaxonCGlue.c, SaxonCXPath.c, XdmValue.cpp, XdmItem.cpp, XdmNode.cpp, XdmAtomicValue.cpp, SaxonProcessor.cpp, XsltProcessor.cpp and XQueryProcessor.cpp, XPathProcessor.cpp, SchemaValidator.cpp To compile the sample test code in C++ execute the 'build.sh' file the directory 'cppTests'. This file builds executables for the test cases testing XSLT, XPath, XQuery and schema Validator. The command is similar to the following:

To compile a C++ application see the example below:
g++ -m32 ../bin/SaxonCGlue.o ../bin/SaxonCXPath.o ../bin/SaxonProcessor.o ../bin/XQueryProcessor.o ../bin/XsltProcessor.o ../bin/XPathProcessor.o ../bin/XdmValue.o ../bin/XdmItem.o ../bin/XdmNode.o ../bin/XdmAtomicValue.o ../bin/SchemaValidator.o testXSLT.cpp -o testXSLT -ldl -lc $1 $2

./testXSLT

See further details of building C/C++ applications documentation

C++ Example 1:

newTransformer();
cout<<"Hello World"<transformFileToString("cat.xml","test.xsl")<

C++ Example 2:

newTransformer();
xslt->setSourceFile("xml/foo.xml");
XdmAtomicValue * xdmvaluex =processor->makeStringValue("Hello to you");
if(xdmvaluex !=NULL){
    cerr<<"xdmvaluex ok"<setParameter("a-param", xdmvaluex);
const char * result = test->transformFileToString(NULL, "xsl/foo.xsl");
if(result != NULL) {
    cerr<clearParameters(true);
processor->clearProperties();]]>

For more examples, see the files in the directory 'samples/cppTest' for C++ and 'samples/cTests' for C.

PHP

In the Saxon/C download please see the PHP unit tests for XSLT, XQuery, XPath and Schema Validator. The PHP test files are contained in the 'samples/php' folder along with associated files. Namely: xsltExamples.php, xqueryExamples.php, xpathExamples.php, validatorExamples.php. These files contain many useful examples which will get you started.

For further details of building PHP applications with Saxon/C see: documentation

PHP example code:

newXsltProcessor();
    $version = $saxonProc->version();
    echo 'Saxon Processor version: '.$version;
    echo '
'; $xsltProc->setSourceFromFile($xmlfile); $xsltProc->compileFromFile($xslFile); $result = $xsltProc->transformToString(); if($result != null) { echo 'exampleSimple1:'; echo 'Output:'.$result; } else { echo "Result is null"; } $proc->clearParameters(); $proc->clearProperties();?>]]>

Also available is the file xslt30TestSuite.php. This is a test driver designed to run the public W3C XSLT test suite at https://dvcs.w3.org/hg/xslt30-test/. The test driver in its current form requires Saxon-EE, which is not yet available in this Saxon/C release; nevertheless, the program may serve as a useful example of how the API can be used. Note that it is written to use libXML to read the test catalog, but to use Saxon for running the tests and assessing the results.

Return to top of page

Debugging

Exceptions and errors are captured and maintained silently in Saxon/C, but can be accessed. This is due to the restrictions in JNI: "There is no uniform and general way to throw and catch exceptions in native languages compared to Java. The JNI therefore requires you to check for possible exceptions after calling JNI functions".

Any exceptions or errors found in a Saxon/C method can be retrieved by the method call 'getErrorMessage(n)', where n is an index number referring to the nth error message. The method getErrorCount() gets the total number of errors reported, which helps to loop through the errors if there are more than one of them. Please see the following PHP code snippet:

runQueryToString();
    if($result == NULL) {		
        $errCount = $query->getExceptionCount();
        if($errCount > 0 ){
            for ($i = 0; $i < $errCount; $i++) {
                $errC = $query->getErrorCode(intval(i));
                $errMessage = $query->getErrorMessage(intval(i));
                if($errC != NULL) {
                    echo 'Error found: '. $errC.' :'.$errMessage;	
                }
                $query->exceptionClear();
            }
        }
    }
    ...
?>]]>

Return to top of page

Support

Please use the help forums and bug trackers at saxonica.plan.io, or the saxon-help mailing list, if you need help or advice. For more details see Support.

Return to top of page

Troubleshooting

After installing Saxon/C, if you notice anomalies in execution then the apache log file usually has useful information on errors reported and crashes. We try to best describe some of the common errors and crashes, and their solutions, below:

Return to top of page

Archive

The latest Saxon/C series is 1.1 (for the latest downloads see C/C++/PHP platforms downloads). This section contains downloads for earlier series releases.

Previous series 1.0, latest maintenance release 1.0.2, released 5 August 2016:



Linux binary

32-bit and 64-bit versions
Saxon-HE/C Saxon-PE/C Saxon-EE/C
1.0.2
32-bit
(15.5Mb)
1.0.2
32-bit
(18.6Mb)
1.0.2
32-bit
(19.3Mb)
1.0.2
64-bit
(25.9Mb)
1.0.2
64-bit
(29.9Mb)
1.0.2
64-bit
(30.6Mb)


Mac OS X

64-bit versions
Saxon-HE/C Saxon-PE/C Saxon-EE/C
1.0.2
64-bit
(42Mb)
1.0.2
64-bit
(48.7Mb)
1.0.2
64-bit
(49.7Mb)

Beta release 0.3.1:

Linux binary

libsaxon-HEC-setup-v0.3.1.zip 32-bit version (13 MB)

libsaxon-HEC-setup64-v0.3.1.zip 64-bit version (39 MB)

Windows

libsaxon-HEC-setup-v0.3.1.exe 32-bit version (9.17 MB)
Compiled for PHP version 5.4 (TS/NTS)

Mac OS X

Saxon-HEC-v0.3.1.1-Mac-native.zip (38 MB)

Running with Excelsior Jet 10 evaluation version therefore is available for testing purposes.

Return to top of page

27 September 2017