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 performed 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 on UNIX or %XDK_HOME% on Windows and that the Oracle Home is referred to as $ORACLE_HOME on UNIX or %ORACLE_HOME% on Windows.

UNIX Setup of XDK C++ Components

In order to successfully run your UNIX C++ XML application, you need to set several environment variables for the various components so that the components can find their support files, and you need to establish the run-time configuration.

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 which 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 an Oracle database is not 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

There is no command-line C++ XML parser utility; however, 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 Interpret as filespec, not as URI

–l language Specify language for error reporting

–n Perform DOM traversal and report number of elements

–p Print document after parsing it

–v Display parser version then exit

–w Preserve all whitespace

–W Stop parsing after a warning

–x Exercise SAX interface and print document

xsl

There is no command-line C++ XSLT processor; however, the C XSLT processor may be called as an executable by invoking xsl from your $ORACLE_HOME/bin or $XDK_HOME/bin as follows:

xsl options URI

The following is the list of options:

-f Interpret as filespec, not 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 XSLoutfile 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

There is no command-line C++ schema validator; however, the C XML Schema Validator may be called as an executable by invoking bin/schema, which takes two arguments: the XML instance document and 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 stdout on success

-u Force the Unicode code path

-v Display version then exit

xmlcg

The stand-alone C++ XML Class Generator may be called as an executable by invoking xmlcg from your $ORACLE_HOME/bin or $XDK_HOME/bin. The following is the command line with its syntax and options:

 xmlcg [flags] <input file>

The following are the option flags and their descriptions:

-d name Generate name.cpp and name.h when there is an external DTD

-o directory Display output directory for generated files (default is current directory)

-e encoding Specify default input file encoding

-h Show this usage help

-s name Generate name.cpp and name.h when input is an XML schema;

-v Show the Class Generator version

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. Refer to Chapter 18 for a description of the C header files. The following is a listing of the C++ files and their corresponding description:

oraxml.hpp 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.hpp Includes the Oracle9i XSD validator data types and APIs. This is for backward compatibility only.

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

xmlotn.hpp Includes all the common APIs, whether you are compiling standalone or using OCI and the Unified DOM.

xmlctx.hpp Includes all the initialization and exception-handling 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/cpp directory of the OTN release or in the $ORACLE_HOME/xdk/demo/cpp directory if you have installed the Oracle Database 10g Companion CD in $ORACLE_HOME.

Windows Setup of XDK C++ Components

In order to successfully run your Windows C++ XML application, you need to set several environment variables for the various components so that the components can find their support files, and you need to establish the run-time configuration.

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:

set 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:

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 an Oracle database is not 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 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. Their command-line options are the same as in the previous UNIX section.

xml.exe

There is no command-line C++ XML parser utility; however, the C XML parser may be called as an executable by invoking xml.exe from your %ORACLE_HOME%/bin or %XDK_HOME%/bin as follows:

xml.exe options URI

xsl.exe

There is no command-line C++ XSLT processor; however, the C XSLT processor may be called as an executable by invoking xsl.exe from your %ORACLE_HOME%/bin or %XDK_HOME%/bin as follows:

xsl.exe options URI

schema.exe

There is no command-line C++ XML; however, the Schema Validator may be called as an executable by invoking schema.exe from your %ORACLE_HOME%/bin or %XDK_HOME%/bin, which takes two arguments: the XML instance document and, optionally, a default schema to apply:

schema.exe options document schema

xmlcg.exe

The stand-alone C++ XML class generator may be called as an executable by invoking xmlcg.exe from your %ORACLE_HOME%/bin or %XDK_HOME%/bin. The following is the command line with its syntax and options:

 xmlcg.exe [flags] <input file>

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 makefile.bat in the %XDK_HOME%\xdk\demo\new directory of the OTN release only or in the %ORACLE_HOME%\xdk\demo\cpp\new directory if you have installed the Oracle Database 10g Companion CD in $ORACLE_HOME.

The make file assumes you are using cl.exe for compiling and link.exe for linking and that you have both in your PATH. You also have to edit the make.bat file 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++

Since 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 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 or 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 workspace. You do so by choosing File | New | Workspaces and entering a name, after which the OK button is activated, and clicking it gives you a new workspace.

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

Once you click OK, you will be asked what kind of console application you wish to create. You can simply 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 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. There are numerous settings here but, as you can see in Figure 22-2, you can keep them in their default configuration with or without Debug optimizations.

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

At this point you can set up your link configuration using another tab in the Project Settings window. Click the Link tab and you will see the window shown in Figure 22-3. Enter “oraxml10.lib” in the Object/Libraries Modules text box to add it to your link line automatically, as shown here. Note, 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.

Figure 22-3: Project Settings: Link window