Skip Headers
Oracle® XML Developer's Kit Programmer's Guide
12c Release 1 (12.1)

E17604-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

18 Getting Started with Oracle XML Developer's Kit for C

Oracle XML Developer's Kit C components are the building blocks for reading, manipulating, transforming, and validating XML.

This chapter contains the following topics:

Installing Oracle XML Developer's Kit C Components

The Oracle XML Developer's Kit C components are included with Oracle Database. This chapter assumes that you have installed Oracle XML Developer's Kit (XDK) with Oracle Database and also installed the demo programs on the Oracle Database Examples media. See "Installing Oracle XML Developer's Kit" for installation instructions and a description of the Oracle XML Developer's Kit directory structure.

The following set of examples shows the UNIX directory structure for the XDK demos and the libraries used by the XDK components. The subdirectories contain sample programs and data files for the Oracle XML Developer's Kit C components.

Example 18-1 lists the main directories under the Oracle home directory for C.

Example 18-1 Oracle XML Developer's Kit C Libraries, Header Files, Utilities, and Demos

- $ORACLE_HOME
    | - bin/
    | - lib/
    | - xdk/

The contents of each subdirectory under this main directory are listed individually.

The bin directory contains these components:

         schema
         xml
         xmlcg
         xsl
         xvm

The lib directory contains these components:

         libcore11.a
         libcoresh11.so
         libnls11.a
         libunls11.a
         libxml11.a
         libxmlsh10.a

The xdk directory contains this demo subdirectory:

         | demo/
            | - c/
                 | - dom/
                 | - parser/
                 | - sax/
                 | - schema/
                 | - webdav/
                 | - xslt/
                 | - xsltvm/

The /xdk/demo/c subdirectories contain sample programs and data files for Oracle XML Developer's Kit C components. The chapters in Part II, "Oracle XML Developer's Kit for C" explain how to use these programs to gain an understanding of the most important C features.

The xdk directory also contains this include subdirectory:

         | include/
            oratypes.h
            oraxml.h
            oraxmlcg.h
            oraxsd.h
            xml.h
            xmlerr.h
            xmlotn.h
            xmlproc.h
            xmlsch.h
            xmlxptr.h
            xmlxsl.h
            xmlxvm.h

Table 18-4 in "Setting Up and Testing the XDK C Compile-Time Environment on UNIX" describes the C header files.

See Also:

"Overview of Oracle XML Developer's Kit (XDK)" for a list of the Oracle XML Developer's Kit C components

Configuring the UNIX Environment for XDK C Components

This section contains the following topics:

Oracle XML Developer's Kit C Component Dependencies on UNIX

The C libraries described in this section are located in $ORACLE_HOME/lib. Oracle XML Developer's Kit C and C++ components are contained in the following library:

libxml11.a

The following Oracle XML Developer's Kit components are contained in the library:

  • XML parser, which checks an XML document for well-formedness, optionally validates it against a DTD or XML Schema, and supports DOM and SAX interfaces for programmatic access

  • XSLT processor, which transforms an XML document into another XML document

  • XSLT compiler, which compiles XSLT style sheets into byte code for use by the XSLT Virtual Machine

  • XSLTVM, which is an XSLT transformation engine

  • XML Schema processor, which validates XML files against an XML schema

Table 18-1 describes the Oracle CORE and Globalization Support libraries on which Oracle XML Developer's Kit C components (UNIX) depend.

Table 18-1 Dependent Libraries of Oracle XML Developer's Kit C Components on UNIX

Component Library Description

CORE library

libcore11.a

Contains the C run-time functions that enable portability across platforms.

CORE Dynamic linking library

libcoresh11.so

C run-time library that supports dynamic linking on UNIX platforms.

Globalization Support common library

libnls11.a

Supports the UTF-8, UTF-16, and ISO-8859-1 character sets. This library depends on the environment to locate encoding and message files.

Globalization Support library for Unicode

libunls11.a

Supports the character sets described in Oracle Database Globalization Support Guide. This library depends on the environment to locate encoding and message files.


Setting Oracle XML Developer's Kit C Environment Variables on UNIX

Table 18-2 describes the UNIX environment variables required for use with Oracle XML Developer's Kit C components.

Table 18-2 UNIX Environment Settings for Oracle XML Developer's Kit C Components

Variable Description Setting

$ORA_NLS10

Sets the location of the Globalization Support character-encoding definition files. The encoding files represent a subset of character sets available in Oracle Database.

Set to the location of the Globalization Support data files. Set the variable as follows:

setenv ORA_NLS10 $ORACLE_HOME/nls/data

$ORA_XML_MESG

Sets the location of the XML error message files. Files ending in .msb are machine-readable and required at run time. Files ending in .msg are human-readable and contain cause and action descriptions for each error.

Set to the path of the mesg directory. For example:

setenv ORA_XML_MESG $ORACLE_HOME/xdk/mesg

$PATH

Sets the location of the Oracle XML Developer's Kit C executables.

You can set the PATH as follows:

setenv PATH ${PATH}:${ORACLE_HOME}/bin

Testing the Oracle XML Developer's Kit C Run-time Environment on UNIX

You can test your UNIX run-time environment by running any of the utilities described in Table 18-3.

Table 18-3 Oracle XML Developer's Kit C/C++ Utilities on UNIX

Executable Directory Description

schema

$ORACLE_HOME/bin

C XML Schema validator

See Also: "Using the C XML Schema Processor Command-Line Utility"

xml

$ORACLE_HOME/bin

C XML parser

See Also: "Using the C XML Parser Command-Line Utility"

xmlcg

$ORACLE_HOME/bin

C++ class generator

See Also: "Using the XML C++ Class Generator Command-Line Utility"

xvm

$ORACLE_HOME/bin

C XVM processor

See Also: "Using the XVM Processor Command-Line Utility"


Run these utilities with no options to display the usage help. Run the utilities with the -hh flag for complete usage information.

Setting Up and Testing the XDK C Compile-Time Environment on UNIX

Table 18-4 describes the header files required for compilation of Oracle XML Developer's Kit C components. These files are located in $ORACLE_HOME/xdk/include. Your run-time environment must be set up before you can compile your code.

Table 18-4 Header Files in the Oracle XML Developer's Kit C Compile-Time Environment

Header File Description

oratypes.h

Includes the private Oracle C data types.

oraxml.h

Includes the Oracle9i XML ORA data types and the public ORA APIs included in libxml.a (for backward compatibility only). Use xml.h instead.

oraxmlcg.h

Includes the C APIs for the C++ class generator (for backward compatibility only).

oraxsd.h

Includes the Oracle9i XSD validator data types and APIs (for backward compatibility only).

xml.h

Handles the unified DOM APIs transparently, whether you use them through OCI or standalone. It replaces oraxml.h, which is deprecated.

xmlerr.h

Includes the XML errors and their numbers.

xmlotn.h

Includes the other headers depending on whether you compile standalone or use OCI.

xmlproc.h

Includes the Oracle XML data types and XML public parser APIs in libxml11.a.

xmlsch.h

Includes the Oracle XSD validator public APIs.

xmlptr.h

Includes the XPointer data types and APIs, which are not currently documented or supported.

xmlxsl.h

Includes the XSLT processor datat ypes and public APIs.

xmlxvm.h

Includes the XSLT compiler and VM data types and public APIs.


Testing the Oracle XML Developer's Kit C Compile-Time Environment on UNIX

The simplest way to test your compile-time environment is to run the make utility on the sample programs, which are located on the Examples media rather than on the Oracle Database CD. After installing the demos, they are located in $ORACLE_HOME/xdk/demo/c. A README in the same directory provides compilation instructions and usage notes.

Build and run the sample programs by executing the following commands at the system prompt:

cd $ORACLE_HOME/xdk/demo/c
make

Verifying the Oracle XML Developer's Kit C Component Version on UNIX

To obtain the version of Oracle XML Developer's Kit you are working with, change directory into $ORACLE_HOME/lib and run the following command:

strings libxml11.a | grep -i developers

Configuring the Windows Environment for XDK C Components

This section contains the following topics:

Oracle XML Developer's Kit C Component Dependencies on Windows

The C libraries described in this section are located in %ORACLE_HOME%\lib. Oracle XML Developer's Kit C components are contained in the following library:

libxml11.dll

The following Oracle XML Developer's Kit components are contained in the library:

  • XML parser

  • XSLT processor

  • XSLT compiler

  • XSLT VM

  • XML Schema processor

Table 18-5 describes the Oracle CORE and Globalization Support libraries on which Oracle XML Developer's Kit C components (Windows) depend.

Table 18-5 Dependent Libraries of Oracle XML Developer's Kit C Components on Windows

Component Library Description

CORE library

libcore11.dll

Contains the run-time functions that enable portability across platforms.

Globalization Support common library

libnls11.dll

Supports the UTF-8, UTF-16, and ISO-8859-1 character sets. This library depends on the environment to find encoding and message files.

Globalization Support library for Unicode

libunls11.dll

Supports the character sets described in Oracle Database Globalization Support Guide. This library depends on the environment to find encoding and message files.


Setting Oracle XML Developer's Kit C Environment Variables on Windows

Table 18-6 describes the Windows environment variables required for use with the Oracle XML Developer's Kit C components.

Table 18-6 Windows Environment Settings for Oracle XML Developer's Kit C Components

Variable Description Setting

%ORA_NLS10%

Sets the location of the Globalization Support character-encoding definition files. The encoding files represent a subset of character sets available in Oracle Database.

This variable must be set to the location of the Globalization Support data files. Set the variable as follows:

set ORA_NLS10=%ORACLE_HOME%\nls\data

%ORA_XML_MESG%

Sets the location of the XML error message files. Files ending in .msb are machine-readable and required at run time. Files ending in .msg are human-readable and contain cause and action descriptions for each error.

Set to the path of the mesg directory. For example:

set ORA_XML_MESG=%ORACLE_HOME%\xdk\mesg 

%PATH%

Sets the location of the Oracle XML Developer's Kit C DLLs and executables.

You can set the PATH as follows:

path %path%;%ORACLE_HOME%\bin

Testing the Oracle XML Developer's Kit C Run-time Environment on Windows

You can test your Microsoft Windows run-time environment by running any of the utilities described in Table 18-7.

Table 18-7 Oracle XML Developer's Kit C/C++ Utilities on Windows

Executable Directory Description

schema.exe

%ORACLE_HOME%\bin

C XML Schema validator

See Also: "Using the C XML Schema Processor Command-Line Utility"

xml.exe

%ORACLE_HOME%\bin

C XML parser

See Also: "Using the C XML Parser Command-Line Utility"

xmlcg.exe

%ORACLE_HOME%\bin

C++ class generator

See Also: "Using the XML C++ Class Generator Command-Line Utility"

xvm.exe

%ORACLE_HOME%\bin

C XVM processor

See Also: "Using the XVM Processor Command-Line Utility"


Run these utilities with no options to display the usage help. Run the utilities with the -hh flag for complete usage information.

Setting Up and Testing the XDK C Compile-Time Environment on Windows

Table 18-4 in the section "Setting Up and Testing the XDK C Compile-Time Environment on UNIX" describes the header files required for compilation of the C components on Microsoft Windows. The relative file names are the same on both UNIX and Windows installations.

On Windows the header files are located in %ORACLE_HOME%\xdk\include. You must set up your run-time environment before you can compile your code.

Testing the Oracle XML Developer's Kit C Compile-Time Environment on Windows

You can test your compile-time environment by compiling the demo programs, which are located in %ORACLE_HOME%\xdk\demo\c after you install them from the Oracle Database Examples media. A README file in the same directory provides compilation instructions and usage notes. Before you compile the demo programs, edit the Make.bat files as described in "Editing the Make.bat Files on Windows".

Editing the Make.bat Files on Windows

Each subfolder of the %ORACLE_HOME%\xdk\demo\c folder contains a file Make.bat. Update the Make.bat file in each folder by adding the path of the libraries and the header files to the compile command. You do not have to edit the paths in the :LINK section because /libpath:%ORACLE_HOME%\lib already points to the C libraries. The section of a Make.bat file in Example 18-2 uses bold text to show the path that you must include.

Example 18-2 Editing an Oracle XML Developer's Kit C Make.bat File on Windows

:COMPILE
set filename=%1
cl -c -Fo%filename%.obj %opt_flg%  /DCRTAPI1=_cdecl /DCRTAPI2=_cdecl /nologo /Zl
/Gy /DWIN32 /D_WIN32 /DWIN_NT /DWIN32COMMON /D_DLL /D_MT /D_X86_=1 
/Doratext=OraText -I. -I..\..\..\include -I%ORACLE_HOME%\xdk\include %filename%.c
goto :EOF
 
:LINK 
set filename=%1
link %link_dbg% /out:..\..\..\..\bin\%filename%.exe 
/libpath:%ORACLE_HOME%\lib /libpath:..\..\..\..\lib 
%filename%.obj oraxml10.lib user32.lib kernel32.lib msvcrt.lib ADVAPI32.lib 
oldnames.lib winmm.lib
Setting the Oracle XML Developer's Kit C Compiler Path on Windows

The demo make.bat file assumes that you are using the cl.exe compiler, which is freely available with the Microsoft .NET Framework Software Development Kit (SDK).

To set the path for the cl.exe compiler on Windows XP, follow these steps:

  1. In the Start menu, select Settings and then Control Panel.

  2. Double-click System.

  3. In the System Properties dialogue box, select the Advanced tab and click Environment Variables.

  4. In System variables, select Path and click Edit.

  5. Append the path of cl.exe to the %PATH% variable and click OK.

Build and run the sample programs by executing the following commands at the system prompt:

cd $ORACLE_HOME/xdk/demo/c
make

Using the Oracle XML Developer's Kit C Components and Visual C++ in Microsoft Visual Studio

You can set up a project with a Visual C++ template and use it for the demos included in Oracle XML Developer's Kit.

Setting a Path for a Project in Visual C++ on Windows

Follow these steps to set the path for a project:

  1. Open a project in Visual C++ and include the *.c files for your project.

  2. Navigate to the Project menu and select Properties.

  3. When Property Pages appear, expand Configuration Properties and select VC++ Directories.

  4. Under General on the right side, select Include Directories.

    Figure 18-1 The Property Pages

    Description of Figure 18-1 follows
    Description of "Figure 18-1 The Property Pages"

  5. Click the arrow at the end of the line, and select the second line, which reads <Edit...>.

  6. When the Include Directories window appears, click New Line from the tool bar and enter this include path, %ORACLE_HOME%\xdk\include, as shown in the example in Figure 18-2 and click OK.

Figure 18-2 Setting the Include Path in Visual C++

Description of Figure 18-2 follows
Description of "Figure 18-2 Setting the Include Path in Visual C++"

Setting the Library Path in Visual C++ on Windows

Follow these steps to set the library path for a project:

  1. Open a project in Visual C++ and include the *.c files for your project.

  2. Navigate to the Project menu and select Properties.

  3. When Property Pages appear, expand Configuration Properties and select VC++ Directories.

  4. Under General on the right side, select Library Directories.

  5. Click the arrow at the end of the line, and select the second line which reads <Edit...>.

  6. When the Library Directories window appears, click New Line from the tool bar and enter this library path, %ORACLE_HOME%\lib, as shown in the example in Figure 18-3 and click OK.

  7. Figure 18-3 Setting the Static Library Path in Visual C++

    Description of Figure 18-3 follows
    Description of "Figure 18-3 Setting the Static Library Path in Visual C++"

  8. After setting the paths for the static libraries in %ORACLE_HOME%\lib, navigate to the Project menu and select Properties.

  9. In the Properties Page, select and expand Linker under Configuration Properties, and select Input.

  10. Select Additional Dependencies and click the arrow at the end of the line. Select the second line which reads <Edit...>.

  11. Enter these additional dependencies: oraxml9.lib, oraxmlg9.lib, and oraxsd9.lib as shown in Figure 18-4 and click OK.

    Figure 18-4 Setting the Names of the Libraries in Visual C++ Project

    Description of Figure 18-4 follows
    Description of "Figure 18-4 Setting the Names of the Libraries in Visual C++ Project"

Overview of the Unified C API

The unified C API is a programming interface that unifies the functionality required by both Oracle XML Developer's Kit and Oracle XML DB. This API is used primarily by XSLT and XML Schema.

As shown in Table 18-4, the unified C API is declared in the xml.h header file. Table 18-8 summarizes the Oracle XML Developer's Kit C APIs. See Oracle Database XML C API Reference for complete documentation.

Table 18-8 Summary of Oracle XML Developer's Kit C APIs

Package Purpose

Callback APIs

Define macros that declare functions (or function pointers) for XML callbacks.

DOM APIs

Parse and manipulate XML documents with DOM. The API follows the DOM 2.0 standard as closely as possible, although it changes some names when mapping from the objected-oriented DOM specification to the flat C namespace. For example, the overloaded getName() methods become getAttrName().

Range APIs

Create and manipulate Range objects.

SAX APIs

Enable event-based XML parsing with SAX.

Schema APIs

Assemble multiple XML schema documents into a single schema that can be used to validate a specific instance document.

Traversal APIs

Enable document traversal and navigation of DOM trees.

XML APIs

Define an XML processor in terms of how it must read XML data and the information it must provide to the application.

XPath APIs

Process XPath-related types and interfaces.

XPointer APIs

Locate nodes in an XML document.

XSLT APIs

Perform XSL processing.

XSLTVM APIs

Implement a virtual machine that can run compiled XSLT code.


The API accomplishes the unification of the functions by conforming contexts. A top-level XML context (xmlctx) shares common information between cooperating XML components. This context defines information about the following:

  • Data encoding

  • Error message language

  • Low-level allocation callbacks

An application needs this information before it can parse a document and provide programmatic access through DOM or SAX interfaces.

Both Oracle XML Developer's Kit and Oracle XML DB require different startup and tear-down functions for the top-level and service contexts. The initialization function takes implementation-specific arguments and returns a conforming context.

The unification is made possible by using conforming contexts. A conforming context means that the returned context must begin with a xmlctx; it may have any additional implementation-specific parts after the standard header.

After an application obtains xmlctx, it uses unified DOM calls, all of which take an xmlctx as the first argument.

Globalization Support for the Oracle XML Developer's Kit C Components

The Oracle XML Developer's Kit C parser supports over 300 IANA character sets. These character sets include those listed in "Character Sets Supported by Oracle XML Developer's Kit for C". Note the following considerations when working with character sets:

  • It is recommended that you use IANA character set names for interoperability with other XML parsers.

  • XML parsers are only required to support UTF-8 and UTF-16, so these character sets are preferable.

  • The default input encoding ("incoding") is UTF-8. If an input document's encoding is not self-evident (by HTTP character set, Byte Order Mark, XMLDecl, and so on), then the default input encoding is assumed. It is recommended that you set the default encoding explicitly if using only single byte character sets such as US-ASCII or any of the ISO-8859 character sets because single-byte performance is fastest. The flag XML_FLAG_FORCE_INCODING specifies that the default input encoding is always applied to input documents, ignoring any BOM or XMLDecl. Nevertheless, a protocol declaration such as HTTP character set is always honored.

  • Choose the data encoding for DOM and SAX ("outcoding") carefully. Single-byte encodings are the fastest, but can represent only a very limited set of characters. Next fastest is Unicode (UTF-16), and slowest are the multibyte encodings such as UTF-8. If input data cannot be converted to the outcoding without loss, then an error occurs. For maximum utility, use a Unicode-based outcoding because Unicode can represent any character. If outcoding is not specified, then it defaults to the incoding of the first document parsed.