Perl Cd Bookshelf [Electronic resources] نسخه متنی

Setting Up Your C XML Development Environment

While much of your environment is already set up by an Oracle Database 10g installation, there are several steps that are platform-specific that you need to perform to both compile and run your Oracle C XML-enabled applications.

Note that in later sections the XDK directory is referred to as $XDK_HOME or %XDK_HOME% and the Oracle Home is referred to as $ORACLE_HOME or %ORACLE_HOME%.

UNIX Setup of XDK C Components

In order to successfully run your UNIX C application, several environment variables need to be set for the various components so they can find their support files.

ORA_NLS10

The environment variable ORA_NLS10 is set to point to the location of the NLS character-encoding definition files. If you have installed Oracle Database 10g, then you can set it as follows:

setenv ORA_NLS10 ${ORACLE_HOME}/nls/data

If you don’t have an Oracle database installed, you can use the NLS character-encoding definition files that come with the OTN Oracle XDK release, as follows:

setenv ORA_NLS10 ${XDK_HOME}/nls/data

ORA_XML_MESG

The environment variable ORA_XML_MESG is set to point to the location of the XML error message files. These files are provided in the xdk/mesg/ directory. Files ending in .msb are machine-readable and needed at runtime; files ending in .msg are human-readable and include cause and action descriptions for each error. For Oracle database installations, these message files exist in the $ORACLE_HOME/xdk/mesg directory and no environment variable is necessary. If no Oracle database is installed, you should set the environment variable ORA_XML_MESG to point to the absolute path of the xdk/mesg/ directory:

setenv ORA_XML_MESG ${XDK_HOME}/xdk/mesg

Checking Your C Run-Time Environment

Several ready-to-run XML utilities are included in Oracle XDK 10g. These make it easy for you to confirm that your run-time environment is properly configured. They all reside in $ORACLE_HOME/bin for Oracle database installations and $XDK_HOME/bin for OTN XDK installations. The following sections describe these XML utilities along with their command-line options.

xml

The C XML parser may be called as an executable by invoking xml from your $ORACLE_HOME/bin or $XDK_HOME/bin as follows:

xml options URI

The following is the list of options:

-c Perform conformance check only, no validation

-e encoding Specify default input file encoding (“incoding”)

-E encoding Specify DOM/SAX encoding (“outcoding”)

-f file Interpret as filespec, not as URI

-l language Specify language for error reporting

-n number Perform DOM traversal and report number of elements

-p Print document after parsing it

-v Display parser version then exit

-w Preserve all white spaces

-W Stop parsing after a warning

-x Exercise SAX interface and print document

xsl

The C XSLT processor may be called as an executable by invoking bin/xsl as follows:

xsl options URI

The following is the list of options:

-f file Interpret as filespec, not as URI

-h Show usage help and full list of flags

-i n Specify number of times to iterate the XSLT processing

-l language Specify language for error reporting

-o XSL outfile Specify output file of XSLT processor

-r Do not ignore <xsl:output> instruction in XSLT processing

-s stylesheet Specify the XSL stylesheet

-v Display XSLT processor version then exit

-V var value Test top-level variables in C XSLT

schema

The Schema Validator may be called as an executable by invoking bin/schema, which takes two arguments: the XML instance document and, optionally, a default schema to apply:

schema options document schema

The following is the list of options:

-0 Always exit with code 0 (success)

-e encoding Specify default input file encoding (“incoding”)

-E encoding Specify output/data/presentation encoding (“outcoding”)

-i Ignore provided schema file

-o num Specify validation options

-p Print instance document to standard output on success

-u Force the Unicode code path

-v Display version and then exit

Setting Up Your C Compile-Time Environment

To compile your code, you need to have the run-time environment set up and you need to have the header files for the components that you are using. These header files reside in the xdk/include directory in either installation. The following is a listing of each and its corresponding description:

oratypes.h Includes all the private Oracle C data types independent of XML.

oraxml.h Includes all the Oracle9i XML ORA data types and all the public ORA APIs in libxml. This is for backward compatibility only.

oraxmlcg.h Includes the C APIs for the C++ Class Generator.

oraxsd.h Includes the Oracle9i XSD validator data types and APIs. This is for backward compatibility only.

xml.h Is the header to handle the Unified DOM APIs transparently, whether using OCI or standalone.

xmlerr.h Includes the XML errors and their numbers.

xmlotn.h Includes all the other headers based upon whether you are compiling standalone or using OCI and the Unified DOM.

xmlproc.h Includes all the Oracle 10g XML data types and XML public parser APIs in libxml10.

xmlsch.h Includes all the Oracle 10g XSD validator public APIs.

xmlptr.h Includes all the XPointer data types and APIs. These are not currently documented or supported.

xmlxsl.h Includes all the XSLT processor data types and public APIs.

xmlxvm.h Includes all the XSLT compiler and VM data types and public APIs.

Confirming Your C Compile-Time Environment

You can confirm your setup by compiling the demo programs, by using makefile in the $XDK_HOME/xdk/demo directory of the OTN release. The demos are not shipped with the Oracle Database 10g CD but are on the Companion CD and will be in the $ORACLE_HOME/xdk/demo directory once installed.

Windows Setup of XDK C Components

In order to successfully run your Windows C application, several environment variables need to be set for the various components so they can find their support files.

ORA_NLS10

The environment variable ORA_NLS10 is set to point to the location of the NLS character-encoding definition files. If you have installed Oracle Database 10g (and assuming that the variable ORACLE_HOME has been set), then you can set it as follows:

set ORA_NLS10 %ORACLE_HOME%\nls\data

If you don’t have an Oracle database installed, after setting a variable called XDK_HOME, you can use the NLS character-encoding definition files that come with the OTN Oracle XDK release as follows:

set ORA_NLS10 %XDK_HOME%\nls\data

ORA_XML_MESG

The environment variable ORA_XML_MESG is set to point to the location of the XML error message files. These files are provided in the xdk\mesg\ directory. Files ending in .msb are machine-readable and needed at runtime; files ending in .msg are human-readable and include cause and action descriptions for each error. For Oracle database installations, these message files exist in the $ORACLE_HOME\xdk\mesg directory and no environment variable is necessary. If no Oracle database is installed, you should set the environment variable, ORA_XML_MESG, to point to the absolute path of the xdk\mesg\ directory:

set ORA_XML_MESG %XDK_HOME%\xdk\mesg

Checking Your C Run-Time Environment

Several ready-to-run XML utilities are included in Oracle XDK 10g. They help you to make sure that your run-time environment is properly configured. They all reside in %ORACLE_HOME%\bin for Oracle database installations and %XDK_HOME%\bin for OTN XDK installations. The following sections describe these XML utilities. Their command-line options are the same as in the previous UNIX section.

xml.exe

The C XML parser may be called as an executable by invoking xml.exe in the bin directory as follows:

xml.exe options URI

xsl.exe

The C XSLT processor may be called as an executable by invoking xsl.exe in the bin directory as follows:

xsl.exe options URI

schema.exe

The Schema Validator may be called as an executable by invoking schema.exe in the bin directory, which takes two arguments: the XML instance document and, optionally, a default schema to apply:

schema options document schema

Setting Up Your C Compile-Time Environment

To compile your code, you need to have the run-time environment set up and you need to have the header files for the components that you are using. These header files reside in the xdk\include directory in either installation. These are the same files as described in the previous UNIX section.

Confirming Your C Compile-Time Environment

You can confirm your setup by compiling the demo programs, by using make.bat in the %XDK_HOME%\xdk\demo directory of the OTN release only. The demos are not shipped with the Oracle Database 10g release. The make file assumes you are using cl.exe and that you have it in your PATH. You also have to edit make.bat to provide the paths to the header files as well as the corresponding .lib files located in %ORACLE_HOME%\lib or %XDK_HOME%\lib.

Setting Up Microsoft Visual C/C++

Because much of the Windows C development is done using Microsoft Visual C/C++, we will show you how to set up a project and its settings for the applications covered in the later chapters. These instructions can also be used for the demos that are included in Oracle XDK 10g. These instructions assume Microsoft Visual C/C++ version 6.0a is compatible.

Creating a New Project

Projects need to be attached to workspaces; therefore, if you don’t already have one that you would like to use, you will need to create a blank one. You do so by clicking File | New | Workspaces and entering a name, after which you can click the now activated OK button to give you a new workspace.

To add a project to this new workspace or to an existing one, you need to click File | New| Projects at which point you will see the screen shown in Figure 18-1. For the applications in this book as well as the Oracle XDK 10g demos, you need to select Win32 Console Application and enter the name of your project. In Figure 18-1, this is CXMLApp.

Figure 18-1: New Projects window

Once you click OK, you will be asked the kind of console application you wish to create. You can select an empty project and click Finish. This will add your new project to your workspace in the FileView pane.

Configuring Your Project

Once you have created a project, you can then configure its settings. This is done by right-clicking the project name, selecting Settings, and then clicking C/C++ in the Project Settings window that appears. You’ll find numerous settings here, but, as you can see in Figure 18-2, you can keep them in their default configuration with or without Debug optimizations.

Figure 18-2: Project Settings: C/C++ window

At this point you can set up your link configuration by selecting the Link tab in the Project Settings window. You will then see the window shown in Figure 18-3.

Figure 8-3: Project Settings: Link window

Add oraxml10.lib as the first entry in the Object/Library Modules text box and it will be added to your link line automatically as shown in Figure 18-3. At runtime you will need the oraxml10.dll, oracore10.dll, and oranls10.dll to be in your PATH for the objects to be found. You can now click OK and begin populating the Source Files and Header Files folders.