CWXML library distribution version 4.0.5, 2004-09-09

Home Page: http://www.cubewerx.com/cwxml/

PURPOSE

The CWXML library is primarily intended as the reference implementation for the BXML (Binary-XML) format. BXML is an OpenGIS(R) Consortium (OGC) discussion-paper format that can be obtained from:

http://www.opengis.org/docs/03-002r8.pdf

The library also features a very efficient tokenizer that can be incorporated into other XML-processing libraries. It parses & generates regular plain-text XML, of course.

LICENSING

GNU LGPL. Read the included "LICENSE" and "LICENSE.LGPL.txt" files.

VERSIONS

The version number for the library is taken from a larger and commercial product called CubeSTOR®; this is why the first release of the library started at 3.3.0. The second number component of the version sequence indicates whether the library is from the development or stable streams in the same way as for the Linux kernel: an odd number means that the version is development, even, stable. Development versions are subject to arbitrary API changes.

LIMITATIONS

Need to integrate the networking code with this distribution. As-is, you can only parse local files, so you'll need to download and store external files before processing them.

Need to implement UTF-16 support sometime, since the XML 1.0 specification requires it.

The namespace-handling mechanism isn't yet implemented. An internal/ external prefix translation mechanism is planned. However, for now the library-access functions ignore the prefix of tag names when comparing them, so this doesn't cause too much of a loss of functionality.

The library also isn't thread-safe, because the underlying 'cwpublic' library isn't thread-safe. It needs a fair amount of cleaning up.

INSTALLING

You can just unpack the library into its final destination location. You can remove the "src" directory contents after building if you want to.

BUILDING

To build the cwxml library, you need the GNU Make utility and a C compiler. The build environment is a little funky in part because the library is part of a larger commercial product that isn't distributed. The build environment uses a main build of the source tree and CVS sandboxes, which may be one and the same.

You need to define the following environmental variables before trying a build:

CW_HOME - main directory of the distribution or installation CW_TARGET - system that you are running on CW_ORAVERSION - a dummy value in this context, should be "817"

PATH      - this needs to include the
            ${CW_HOME}/bin/${CW_ORAVERSION}/${CW_TARGET} directory

This environment will be changed in the future to make it more sensible for use with a public library.

The CW_TARGET variable can take the following values:

linux - Linux on an x86 processor and GCC compiler solaris - Solaris on a Sparc processor and GCC compiler sol86 - Solaris on an x86 processor and GCC compiler alpha - OSF/1 on an Alpha processor and GCC compiler win32 - Windows on x86 processor with MS VC++ compiler

The PATH environmental variable needs to include the ${CW_HOME}/bin/${CW_ORAVERSION}/${CW_TARGET} directory because an intermediate program called 'findlibs' is used by some Makefiles in this distribution to resolve library pathnames. Also, this will allow you to run cwxml programs from the command line.

The cwxml library depends on the third-party open-source 'zlib' GZIP-compression library, which has a home page at:

http://www.gzip.org/zlib/

A copy of the zlib-1.1.4 library is included in this distribution for convenience and a script called "build.sh" is present in the root directory of the cwxml distribution to build a static version of the zlib library and the cwxml libraries. This script will only work on Unix-compatible systems. I prefer static libraries because they cause fewer headaches in a development environment.

There is also a Makefile in the 'src' directory that will build the cwxml library and applications. Just using 'make' will build a debugging version of the library and 'make BUILD=optimize' will build an optimized version. 'make clean' will clean up.

The build environment can be tweaked in the 'src/makedefs' directory and in the Makefiles of the 'src' modules.

RUNNING

The CW_HOME environment variable needs to be set at runtime since message files are accessed at runtime.

The following programs come with this distribution, not counting the test programs that are internal to the library modules 'cwpublic' and 'cwxml':

xmlscan - translate to/from & reformat XML and BXML formats ppmtoxdi - translate PPM image to XML-Demo-Image foramt xditoppm - translate XML-Demo-Image format to PPM

Type the command name by itself to see the command-line arguments.

The 'ppmtoxdi' and 'xditoppm' programs have been developed to show how to use the XML parser and generator and to allow performance testing. The source files are in the "src/cwxmlutil" directory.\

XDI is a simple XML format that was made up just for demonstration purposes. Image representation is the butt of may jokes about the gross inefficiency of the XML format for representing some types of data, but when combined with BXML encoding and sample lists (rather than stupidly overstructuring the pixel components), it can be nearly as efficient as the PNG image format. XDI is defined only for RGB imagery. Sample types "byte", "float", and "double" are supported to test for different array types. The XDI format looks like:

      <Width>x</Width>
      <Height>y</Height>
      <SampleType>byte</SampleType>  <!-- or "float" or "double" -->

</Header>
<Scanline row="i">  <RgbSamples>r r r r r</RgbSamples> </Scanline>
...
</XmlDemoImage>

The 'xditoppm' program combines node-by-node scanning with DOM subtree parsing to show a sensible way to process potentially enormous scientific-data XML files such as GML (Geography Markup Language) format.

The converter scans the <XmlDemoImage> node, then the <Header> node and then reads the whole subtree for <Header> and extracts the image parameters using the DOM-subtree mode using "micro" XPath expressions. Then, it reads the <Scanline>s one at a time and DOMs the sample element. This makes it so that no matter how large the image is, the scanner is only holding a single scanline in memory at a time.

API

There is no formal documentation yet for the CWXML library, but you can check the following header files in the "${CW_HOME}/src/cwxml/include" directory:

cw_xmlscan.h
cw_xmltree.h
cw_xmlgen.h

You should avoid calling any of the 'cwpublic' functions directly, because lots of cleaning up and API changes are planned for the future.

LINKING YOUR OWN PROGRAMS

This distribution builds two static libraries and a collection of header files in the "${CW_HOME}/lib/${CW_ORAVERSION}/${CW_TARGET}" and "${CW_HOME}/include" directories, respectively. The 'zlib' library is compiled into the "${CW_HOME}/lib_3p/${CW_TARGET}" directory.

To build your own programs, the CW include directory will need to be in your compilation 'include path', and the libraries 'cwxml', 'cwpublic', and 'z' will need to be in your linking libraries.

CONTRIBUTING CHANGES

The library is distributed as a CVS sandbox, so changes can be resubmitted as a tar-gzip of the sandbox. The maintainer is:

Craig Bruce <csbruce@cubewerx.com>.