Skip Headers
Oracle® XML Developer's Kit Programmer's Guide
10g Release 2 (10.2)

Part Number B14252-01
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
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

14 Getting Started with C XDK Components

The XDK C components are the building blocks for reading, manipulating, transforming, and validating XML.

This chapter contains the following topics:

Installing C XDK Components

The C XDK components are included with Oracle Database. This chapter assumes that you have installed XDK with Oracle Database and also installed the demo programs on the Oracle Database Companion CD. Refer to "Installing the XDK" for installation instructions and a description of the XDK directory structure.

Example 14-1 shows the UNIX directory structure for the XDK demos and the libraries used by the XDK components. The $ORACLE_HOME/xdk/demo/c subdirectories contain sample programs and data files for the XDK for C components. The chapters in Part II, "XDK for C" explain how to understand and use these programs.

Example 14-1 C XDK Libraries, Header Files, Utilities, and Demos

- Oracle_home_directory
    | - bin/
         schema
         xml
         xmlcg
         xsl
         xvm
    | - lib/
         libcore10.a
         libcoresh10.so
         libnls10.a
         libunls10.a
         libxml10.a
| - xdk/
         | demo/
            | - c/
                 | - dom/
                 | - parser/
                 | - sax/
                 | - schema/
                 | - webdav/
                 | - xslt/
                 | - xsltvm/
         | 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

The subdirectories contain sample programs and data files for the C XDK components. The chapters in Part II, "XDK for C" explain how to use these programs to gain an understanding of the most important C features.


See Also:

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

Configuring the UNIX Environment for C XDK Components

This section contains the following topics:

C XDK Component Dependencies on UNIX

The C libraries described in this section are located in $ORACLE_HOME/lib. The XDK C and C++ components are contained in the following library:

libxml10.a

The following XDK 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 stylesheets 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 14-1 describes the Oracle CORE and Globalization Support libraries on which the XDK C components (UNIX) depend.

Table 14-1 Dependent Libraries of XDK C Components on UNIX

Component Library Description
CORE library libcore10.a Contains the C runtime functions that enable portability across platforms.
CORE Dynamic linking library libcoresh10.so C runtime library that supports dynamic linking on UNIX platforms.
Globalization Support common library libnls10.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 libunls10.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 C XDK Environment Variables on UNIX

Table 14-2 describes the UNIX environment variables required for use with the XDK C components.

Table 14-2 UNIX Environment Settings for XDK 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 runtime. 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 C XDK executables. You can set the PATH as follows:
setenv PATH ${PATH}:${ORACLE_HOME}/bin

Testing the C XDK Runtime Environment on UNIX

You can test your UNIX runtime environment by running any of the utilities described in Table 14-3.

Table 14-3 C/C++ XDK 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"

xsl $ORACLE_HOME/bin C XSLT processor

See Also: "Using the C XSLT Processor 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 C XDK Compile-Time Environment on UNIX

Table 14-4 describes the header files required for compilation of the C components. These files are located in $ORACLE_HOME/xdk/include. Note that your runtime environment must be set up before you can compile your code.

Table 14-4 Header Files in the C XDK Compile-Time Environment

Header File Description
oratypes.h Includes the private Oracle C datatypes.
oraxml.h Includes the Oracle9i XML ORA datatypes 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 datatypes 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 10g XML datatypes and XML public parser APIs in libxml10.a.
xmlsch.h Includes the Oracle 10g XSD validator public APIs.
xmlptr.h Includes the XPointer datatypes and APIs, which are not currently documented or supported.
xmlxsl.h Includes the XSLT processor datatypes and public APIs.
xmlxvm.h Includes the XSLT compiler and VM datatypes and public APIs.

Testing the C XDK 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 Companion CD rather than on the Oracle Database 10g CD. After you install the demos, they will be 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 C XDK Component Version on UNIX

To obtain the version of XDK you are working with, change into $ORACLE_HOME/lib and run the following command:

strings libxml10.a | grep -i developers

Configuring the Windows Environment for C XDK Components

This section contains the following topics:

C XDK Component Dependencies on Windows

The C libraries described in this section are located in %ORACLE_HOME%\lib. The XDK C components are contained in the following library:

libxml10.dll

The following XDK components are contained in the library:

  • XML parser

  • XSLT processor

  • XSLT compiler

  • XSLT VM

  • XML Schema processor

Table 14-5 describes the Oracle CORE and Globalization Support libraries on which the XDK C components (Windows) depend.

Table 14-5 Dependent Libraries of XDK C Components on Windows

Component Library Description
CORE library libcore10.dll Contains the runtime functions that enable portability across platforms.
Globalization Support common library libnls10.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 libunls10.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 C XDK Environment Variables on Windows

Table 14-6 describes the Windows environment variables required for use with the XDK C components.

Table 14-6 Windows Environment Settings for C XDK 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 should 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 runtime. 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 C XDK DLLs and executables. You can set the PATH as follows:
path %path%;%ORACLE_HOME%\bin

Testing the C XDK Runtime Environment on Windows

You can test your Windows runtime environment by running any of the utilities described in Table 14-7.

Table 14-7 C/C++ XDK 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"

xsl.exe %ORACLE_HOME%\bin C XSLT processor

See Also: "Using the C XSLT Processor 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 C XDK Compile-Time Environment on Windows

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

On Windows the header files are located in %ORACLE_HOME%\xdk\include. Note that you must set up your runtime environment before you can compile your code.

Testing the C XDK 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 10g Database Companion CD. A README in the same directory provides compilation instructions and usage notes.

Setting the C XDK 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 as shown in Figure 14-1 and click OK.

    Figure 14-1 Setting the Path for the C XDK Compiler and Linker on Windows

    This graphic is described in the surrounding text.
Editing the Make.bat Files on Windows

Each subfolder of the %ORACLE_HOME%\xdk\demo\c folder contains a Make.bat file. Update the Make.bat file in each folder by adding the path of the libraries and the header files to the compile command. You should not need 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 14-1 uses bold text to show the path that you need to include.

Example 14-2 Editing a C XDK 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

Using the C XDK Components with Visual C/C++ on Windows

You can set up a project in Microsoft Visual C/C++ and use it for the demos included in the XDK.

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

Follow these steps to set the path for a project:

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

  2. Navigate to the Tools menu and select Options.

  3. Select the Directories tab and set your include path to %ORACLE_HOME%\xdk\include as shown in the example in Figure 14-2.

Figure 14-2 Setting the Include Path in Visual C/C++

Description of c6.gif follows
Description of the illustration c6.gif

Setting the Library Path in Visual C/C++ on Windows

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

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

  2. Navigate to the Tools menu and select Options.

  3. Select the Directories tab and set your library path to %ORACLE_HOME%\lib as shown in the example in Figure 14-3.

    Figure 14-3 Setting the Static Library Path in Visual C/C++

    Description of c7.gif follows
    Description of the illustration c7.gif
  4. After setting the paths for the static libraries in %ORACLE_HOME%\lib, set the library name in the compiling environment of Visual C++. Navigate to the Project menu in the menu bar and select Settings.

  5. Select the Link tab in the Object/Library Modules field and enter the names of XDK C components libraries, as shown in the example in Figure 14-4.

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

    Description of cpp8.gif follows
    Description of the illustration cpp8.gif

Overview of the Unified C API

The unified C API is a programming interface that centralizes the functionality required by the XDK and Oracle XML DB. XSLT and XML Schema are primary customers of the API.

As shown in Table 14-4, the unified C API is declared in xml.h, which replaces the oraxml.h file used in releases prior to Oracle Database 10g. Table 14-8 summarizes the C XDK API. Refer to Oracle XML API Reference for the complete API documentation.

Table 14-8 Summary of the XDK C API

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 such as the following:

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

Both the XDK and the Oracle XML DB required 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. 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.

Initialization, which is the acquisition of an xmlctx, is an implementation-specific step. After an application obtains xmlctx, it uses unified DOM calls, all of which take an xmlctx as the first argument.

The unified interface supersedes the C API in releases prior to Oracle Database 10g. In particular, the XDK has deprecated the oraxml interfaces (top-level, DOM, SAX and XSLT) and oraxsd (Schema) interfaces.

Globalization Support for the C XDK Components

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