Altova XML

7/28/2019 Altova XML

1/159

AltovaXML 2011

User and Reference Manual


2/159

All rights reserved. No parts of this work may be reproduced in any form or by any means- graphic, electronic, or mechanical, including photocopying, recording, taping, orinformation storage and retrieval systems - without the written permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered

trademarks of the respective owners. The publisher and the author make no claim tothese trademarks.

While every precaution has been taken in the preparation of this document, the publisherand the author assume no responsibility for errors or omissions, or for damages resultingfrom the use of information contained in this document or from the use of programs andsource code that may accompany it. In no event shall the publisher and the author beliable for any loss of profit or any other commercial damage caused or alleged to havebeen caused directly or indirectly by this document.

Published: 2011

2011 Altova GmbH

AltovaXML 2011 User & Reference Manual


3/159

1AltovaXML 2011

Table of Contents

1 Introduction 3

................................................................................................................................... 41.1 Product Features

................................................................................................................................... 51.2 Available Functionality

................................................................................................................................... 61.3 System Requirements and Installation

................................................................................................................................... 71.4 About this Documentation

2 Usage 10

................................................................................................................................... 112.1 Command Line

..................................................................................................................... 13XML Validation and Well-Formedness2.1.1

..................................................................................................................... 16XSLT 1.0 Transformations2.1.2

..................................................................................................................... 18XSLT 2.0 Transformations2.1.3

..................................................................................................................... 20XQuery 1.0 Executions2.1.4

................................................................................................................................... 222.2 COM Interface

..................................................................................................................... 23Registering AltovaXML as a COM Server Object2.2.1

..................................................................................................................... 24AltovaXML Object Model2.2.2

..................................................................................................................... 25Application2.2.3

..................................................................................................................... 26XMLValidator2.2.4

..................................................................................................................... 28XSLT12.2.5

..................................................................................................................... 30XSLT22.2.6

..................................................................................................................... 33XQuery2.2.7

..................................................................................................................... 36Examples2.2.8

........................................................................................................... 36Visual Basic

........................................................................................................... 37JScript

........................................................................................................... 38C++

................................................................................................................................... 402.3 Java Interface

..................................................................................................................... 42Interfaces2.3.1

........................................................................................................... 42IAltovaXMLEngine

........................................................................................................... 43IAltovaXMLFactory

........................................................................................................... 44IExecutable

........................................................................................................... 44IReleasable

........................................................................................................... 45IXMLValidator

........................................................................................................... 46IXQuery

........................................................................................................... 48IXSLT


4/159

AltovaXML 20112

..................................................................................................................... 50Classes2.3.2

........................................................................................................... 50AltovaXMLFactory

........................................................................................................... 52XMLValidator

........................................................................................................... 54XQuery

........................................................................................................... 58XSLT1

........................................................................................................... 61XSLT2

................................................................................................................................... 642.4 .NET Interface

..................................................................................................................... 66General Usage and Example2.4.1

..................................................................................................................... 68Altova.AltovaXML.XMLValidator2.4.2

..................................................................................................................... 70Altova.AltovaXML.XSLT12.4.3

..................................................................................................................... 72Altova.AltovaXML.XSLT22.4.4

..................................................................................................................... 74Altova.AltovaXML.XQuery2.4.5

................................................................................................................................... 772.5 Explicitly Releasing AltovaXML COM-Server from C# and VB.NET

................................................................................................................................... 782.6 OOXML and ZIP Files

3 Engine Information 80

................................................................................................................................... 813.1 Altova XML Validator

................................................................................................................................... 823.2 XSLT 1.0 Engine: Implementation Information

................................................................................................................................... 843.3 XSLT 2.0 Engine: Implementation Information

..................................................................................................................... 85General Information3.3.1

..................................................................................................................... 87XSLT 2.0 Elements and Functions3.3.2

................................................................................................................................... 883.4 XQuery 1.0 Engine: Implementation Information

................................................................................................................................... 913.5 XPath 2.0 and XQuery 1.0 Functions

..................................................................................................................... 92General Information3.5.1

..................................................................................................................... 94Functions Support3.5.2

................................................................................................................................... 973.6 Extensions

..................................................................................................................... 98Java Extension Functions3.6.1

........................................................................................................... 99User-Defined Class Files

........................................................................................................... 101User-Defined Jar Files

........................................................................................................... 102Java: Constructors

........................................................................................................... 102Java: Static Methods and Static Fields

........................................................................................................... 103Java: Instance Methods and Instance Fields

........................................................................................................... 104Datatypes: XPath/XQuery to Java

........................................................................................................... 105Datatypes: Java to XPath/XQuery

..................................................................................................................... 106.NET Extension Functions3.6.2

........................................................................................................... 108.NET: Constructors

........................................................................................................... 108.NET: Static Methods and Static Fields

........................................................................................................... 109.NET: Instance Methods and Instance Fields

........................................................................................................... 110Datatypes: XPath/XQuery to .NET


5/159

3AltovaXML 2011

........................................................................................................... 111Datatypes: .NET to XPath/XQuery

..................................................................................................................... 112MSXSL Scripts for XSLT3.6.3

..................................................................................................................... 115Altova Extension Functions3.6.4

........................................................................................................... 115General Functions

........................................................................................................... 118Barcode Functions

........................................................................................................... 120Chart Functions

........................................................................................................... 124Chart Data XML Structure

........................................................................................................... 128Example: Chart Functions

4 License Information 134

................................................................................................................................... 1354.1 Electronic Software Distribution

................................................................................................................................... 1364.2 Software Activation and License Metering

................................................................................................................................... 1374.3 Intellectual Property Rights

................................................................................................................................... 1384.4 License Agreement

Index


6/159


7/159

Chapter 1

Introduction


8/159


9/159

2011 Altova GmbH

3Introduction

AltovaXML 2011

1 Introduction

AltovaXML 2011 Reporting Edition is an XML application package which contains the AltovaXML Validator, Altova XSLT 1.0 Engine, Altova XSLT 2.0 Engine, and Altova XQuery 1.0

Engine. The package is available, free of charge, as a single installer file from theAltovawebsite. AltovaXML can be used to validate XML documents, transform XML documents usingXSLT stylesheets, and execute XQuery documents.

AltovaXML can be used from the command line, via a COM interface, in Java programs, and in.NET applications. This documentation describes the usage of AltovaXML in all theseenvironments, and also lists implementation-specific aspects of the engines in the package.

Last updated: 06/07/2011
http://www.altova.com/download.htmlhttp://www.altova.com/download.html


10/159

4 Introduction Product Features

2011 Altova GmbHAltovaXML 2011

1.1 Product Features

The main features of AltovaXML are as follows:

Package

XML Validator, XSLT Engines, and XQuery Engine packaged as a single installer file. Installer file available for download fromAltova website free-of-charge. Easy installation of executable files on Windows systems.

Command line

Command line usage for validation, XSLT transformation, and XQuery execution. Validation of XML documents according to DTD and W3C XML Schema rules. Transformation of XML documents with XSLT 1.0 and XSLT 2.0 stylesheets in

conformance with respective W3C specifications. Execution of XQuery 1.0 documents in conformance with W3C specifications.

COM interface

Can be used via COM interface, and therefore with applications and scriptinglanguages that support COM.

COM interface support is implemented for Raw and Dispatch interfaces. Wide range of XML validation, XSLT transformation, and XQuery execution features

are available through interface properties. XML, DTD, XML Schema, XSLT, and XQuery input can be provided as files or as text

strings in scripts and in application data.

Java interface

AltovaXML functionality is available as Java classes that can be used in Java programs. Java classes provide XML validation, XSLT transformation, and XQuery execution

features.

.NET interface

A DLL file is built as a wrapper around AltovaXML and allows .NET users to connect tothe functionality of AltovaXML.

Provides primary interop assembly signed by Altova. Wide range of XML validation, XSLT transformation, and XQuery execution features

are available. XML, DTD, XML Schema, XSLT, and XQuery input can be provided as files or as text

strings in scripts and in application data.
http://www.altova.com/download.html


11/159

2011 Altova GmbH

Available Functionality 5Introduction

AltovaXML 2011

1.2 Available Functionality

AltovaXML provides the functionality listed below. Most of this functionality is common tocommand line usage and COM interface usage. One major difference is that COM interfaceusage allows documents to be constructed from text strings via the application or scripting code

(instead of referencing XML, DTD, XML Schema, XSLT, or XQuery files).

XML and XBRL Validation

Validates the supplied XML document, returning valid or invalid. Validation can be done against the DTD or XML Schema referenced within the XML

file, or against an external DTD or XML Schema supplied by a command line parameteror a COM interface property.

Checks well-formedness of the supplied XML document, separately from validation. Validates XBRL documents. The XBRL document is validated against an XBRL

taxonomy (which is a .xsd file) according to the rules of XBRL.

XSLT Transformations

Transforms supplied XML document using supplied XSLT 1.0 or XSLT 2.0 document. XML document can be provided as a file via the input of a URL. In the case of usage

via the COM interface, the XML document can alternatively be supplied as a text string. XSLT document can be provided as a file via the input of a URL. In the case of usage

via the COM interface, the XSLT document can alternatively be supplied as a textstring.

Returns output documents at the named location. When called via COM interface canalso return output documents as a string.

XSLT parameters can be supplied via the command line and via the COM interface. Altova extension functions (including, in the Reporting Edition, for charts) enable

specialized processing.

XQuery Execution

Executes the supplied XQuery 1.0 document, optionally against an XML documentnamed in a command line parameter or a COM interface property.

XQuery document can be provided as a file via the input of a URL. In the case of usagevia the COM interface, the XQuery document can alternatively be supplied as a textstring.

XML document can be provided as a file via the input of a URL. In the case of usagevia the COM interface, the XML document can alternatively be supplied as a text string.

Returns output documents at the named location. When called via COM interface canalso return output documents as a string.

External XQuery variables can be supplied via the command line and via the COM

interface. Serialization options include: output encoding, output method (that is, whether the

output is XML, XHTML, HTML, or Text), omitting the XML declaration, and indentation. Altova extension functions (including, in the Reporting Edition, for charts) enable

specialized processing.


12/159

6 Introduction System Requirements and Installation


1.3 System Requirements and Installation

System requirementsAltovaXML is supported on Windows NT, Windows XP, Windows Server 2003, Windows Server2008, Windows Vista, and Windows 7. To use AltovaXML via a COM interface, users should

have privileges to use the COM interface, that is, to register the application and execute therelevant applications and/or scripts. AltovaXML Reporting Edition is available for both 32-bit and64-bit machines. AltovaXML Community Edition is available for 32-bit machines only.

InstallationAltovaXML is available on theAltova website as a self-extracting download that will installAltovaXML with the necessary registrations. After you have downloaded the installer file (AltovaXML2011.exe) to your machine, double-click it to start the installation. The installer willinstall AltovaXML in the Altova/AltovaXML2011 folder in the Program Files folder. All thenecessary registrations to use AltovaXML via a COM interface, as a Java interface, and in the.NET environment will be done by the installer. This includes registering the AltovaXMLexecutable as a COM server object, installing AltovaXMLLib.dll (for Java interface usage)in the WINDIR\system32\ directory, and adding the Altova.AltovaXML.dll file to the.NET reference library.

You should note the following:

For command line usage, invoke the installed executable file (AltovaXML.exe). Thisfile can be copied to another accessible location on your machine or network andinvoked from there.

You can straightaway use AltovaXML via COM interface since the installed executablefile AltovaXML_COM.exe will have been registered as a COM server object. If youchange the location of the executable file AltovaXML_COM.exe to another location onyour machine or to a mapped network drive, then you must manually register it at itsnew location as a COM server object. How to do this described in the section,Registering AltovaXML as a COM server object.

In order to use AltovaXML via a Java interface, AltovaXML_COM.exe must be

registered as a COM server object and the path to the file AltovaXML.jar (installed inthe Altova/AltovaXML2011 folder) must be added to the CLASSPATH. Registrationas a COM server object is done automatically by the installer process. The installer alsoinstalls AltovaXMLLib.dll in the WINDIR\system32\ directory. However, notethat, if you change the location of the file AltovaXML_COM.exe after installation, thenyou must manually register it at its new location as a COM server object. SeeRegistering AltovaXML as a COM Server Object and Java Interface for details.
http://www.altova.com/download.html


13/159

2011 Altova GmbH

About this Documentation 7Introduction

AltovaXML 2011

1.4 About this Documentation

This documentation is the official product documentation of AltovaXML and providescomprehensive information about it. Its structure is as follows:

The Introduction describes the features of the AltovaXML product, the functionality itprovides, the main system requirements to use AltovaXML, and how AltovaXML is to beinstalled.

The Usage section describes how to use AltovaXML from the command line and via aCOM interface. The Command Line section provides details about the syntax used toinvoke the various functionalities of AltovaXML. The COM Interface section describeshow AltovaXML can be used with a COM interface; it provides a detailed description ofthe object model, its interfaces, and the properties of interfaces. The Java Interfacesection describes how AltovaXML can be used with Java and lists the defined Javainterfaces and classes. The .NET Interface section provides a description of usage andlists the various methods and properties that can be used.

The Engine Information section describes implementation-specific aspects of thevarious engines that are components of AltovaXML. Each engine is describedseparately.


14/159


15/159

Chapter 2

Usage


16/159

10 Usage


2 Usage

After AltovaXML has been downloaded and installed at the desired location, you can use it inthe following ways:

By calling the application from the command line, By using the application via a COM interface, By using the application via a Java interface, and By using the application in the .NET environment.


17/159

2011 Altova GmbH

Command Line 11Usage

AltovaXML 2011

2.1 Command Line

To use AltovaXML from the command line, the executable file (AltovaXML.exe) must beinstalled/copied to an accessible location on your machine or network. The general syntax tocall the application is:

AltovaXML functionality arg1 ... argN [options]

where

AltovaXML Calls the application.

functionality

Specifies whether the XML validation, well-formedness check, XSLT 1.0transformation, XSLT 2.0 transformation, or XQuery 1.0 executionfunctionality is called. Respective values are -validate (or-v),-wellformed (or-w),-xslt1, -xslt2, -xquery (or-xq).

arg1 ...

argN

The arguments of the called functionality.

options Each functionality has its own set of options. These are described in thecorresponding sub-sections of this section.

General options

-help, -h,or-?

Displays usage information, i.e. a list of all arguments and options.

-version,-ver

Displays the program version.

The following functionality is available, and the allowed arguments and options for eachfunctionality are described in detail in the corresponding sections:

XML Validation and Well-Formedness XSLT 1.0 Transformations XSLT 2.0 Transformations XQuery 1.0 Executions

Usage summaryGiven below is a summary of command line usage. For details, refer to the respective sections.

Using Altova XML Validator

-validate [-schema | -dtd ]

-wellformed

Using Altova XSLT 1.0 Engine

-xslt1 -in [-param name=value] [-out]

Using Altova XSLT 2.0 Engine


18/159

12 Usage Command Line


-xslt2 -in [-param name=value] [-out]

Using Altova XQuery 1.0 Engine

-xquery [-in ] [-param name=value] [-out

] [serialization options]

Note: If the filename or the path to it contains a space, then the entire path should be enclosedin quotes. For example: "c:\My Files\MyXML.xml" or"c:\MyFiles\My XML.xml".


19/159

2011 Altova GmbH


AltovaXML 2011

2.1.1 XML Validation and Well-Formedness

XML Validation syntaxThe syntax to invoke XML validation is:

AltovaXML -validatexmlfile

[-schemaschemafile

| -dtddtdfile

][options]

where

AltovaXML Calls the application

-validate (or-v) Specifies that the Altova XML Validator is to be used to validate the filexmlfile.

The following options are available:

-schema (or-s) Specifies the XML Schema file schemafile to be used forvalidation.

-dtd (or-d) Specifies the DTD file dtdfile to be used for validation.

-xbrlConsistency (or-xc)

Checks the semantics of XBRL documents.

Mapping optionsThe following mapping options are available using the XML Catalogs mechanism and AltovaGlobal Resources mechanism. (Altova Global Resources can be properly used only if an Altovaproduct that supports Altova Global Resources is installed, for example, Altova XMLSpy.)

-catalog (or-c)[]

Activates catalog mapping using the catalog given. If no file isspecified, a catalog named RootCatalog.xml in the AltovaXMLapplication folder will be assumed as the default.

-globalresources(or-gr)[]

Activates Altova global resource mapping using the given GlobalResources XML file or, if no file is specified, GlobalResources.xmlin My Documents/Altova.

-globalresourceconfig (or-gc)[]

Sets the active global resource configuration.

Note about Global ResourcesThere are two settings required to select a resource using the Altova Global Resourcesmechanism:

The Global Resources XML File contains definitions of the global resources. This filecan be specified with the -globalresources (or-gr) option. If no file is specified,then the file GlobalResources.xml in the My Documents/Altova folder will be used.

Each global resource in the Global Resources XML File can have multipleconfigurations, with each configuration mapping to a resource. The-globalresourceconfig (or-gc) option enables you to specify whichconfiguration to use, by extension specifying which resource to use.

Note:


20/159



When no XML Schema or DTD file is specified as a command line option, an XMLSchema or DTD file must be specified in the XML document itself.

If an XML Schema or DTD file is specified as a command line option and an XMLSchema or DTD file is referenced in the XML file, then the file specified in the commandline option is used for validation.

If an XBRL instance document is validated, the XBRL taxonomy, which is a .xsd file, islooked up. If semantic validation is required in addition to syntactic validity, use the-xbrlConsistency option.

Well-formedness Check syntaxThe syntax to invoke the well-formedness check is:

AltovaXML -wellformed xmlfile

where

AltovaXML Calls the application-wellformed (or-w)

Specifies that the Altova XML Validator is to be used to check thewell-formedness of the file xmlfile.


-catalog (or-c)[]







The Global Resources XML File contains definitions of the global resources. This file

can be specified with the -globalresources (or-gr) option. If no file is specified,then the file GlobalResources.xml in the My Documents/Altova folder will be used.


Examples


21/159

2011 Altova GmbH


AltovaXML 2011

AltovaXML -validate test.xml -schema testschema.xsd

AltovaXML -v test.xml -dtd testdtd.dtd

AltovaXML -wellformed test.xml

AltovaXML -w test.xml

AltovaXML -v test.xml -dtd testdtd.dtd -c MyCatalog.xml

AltovaXML -validate test.xml -schema testschema.xsd -xc

Note: For using Altova XML in batch commands, it is important to know the following:

The return code of the last executed command is stored in the errorlevel variable,the value of which can be retrieved with a batch command such as ECHO%errorlevel%.

The return codes are 0 = well-formed/valid; 1 = not well-formed/invalid.


22/159



2.1.2 XSLT 1.0 Transformations

SyntaxThe syntax to invoke XSLT 1.0 transformations is:

AltovaXML -xslt1 xsltfile -in xmlfile [-out outputfile] [options]

where


-xslt1 Specifies that the Altova XSLT 1.0 Engine is to be used for an XSLTtransformation; the engine uses the XSLT 1.0 file xsltfile for thetransformation.

-in Specifies the XML file xmlfile to be transformed and its location.

-out Specifies the output file outputfile and its location. If this option isomitted, the output is written to standard output.


-param Takes the instruction paramname=XPath expression. The -paramswitch is used before each global parameter. Double quotes must beused if a space is included in an XPath expressionwhether in a pathexpression itself or in a string literal in the expression. See examples.

-xslstack The stack size is the maximum depth of executed instructions, and canbe changed with the -xslstack value. The minimum allowed value is100. The default stack size is 1000. If the stack size is exceededduring a transformation, an error is reported.

-namedTemplate(or -n)

Sets the initial named template. A space separates the argument fromits value. Example: -namedTemplate MyTemplate

-mode (or -m) Sets the initial template mode. A space separates the argument from

its value. Example: -mode MyMode


-catalog (or-c)[]








23/159

2011 Altova GmbH


AltovaXML 2011


Each global resource in the Global Resources XML File can have multipleconfigurations, with each configuration mapping to a resource. The

-globalresourceconfig (or-gc) option enables you to specify whichconfiguration to use, by extension specifying which resource to use.

Note:

The XSLT file must be specified in the command line instruction; an XSLT filereferenced in an processing instruction in the XML documentis not automatically used.

If the -out parameter is omitted, output is written to the standard output.

Examples

AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml

-c MyCatalog.xml

AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml-param date=//node/@att1

AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml-param date="//node/@att1 | //node/@att2"

AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml-param date=node/@att1 -param title='stringwithoutspace'

AltovaXML -xslt1 test.xslt -in test.xml -out testout.xml-param date=node/@att1 -param title="'string with spaces'"


24/159



2.1.3 XSLT 2.0 Transformations

SyntaxThe syntax to invoke XSLT 2.0 transformations is:

AltovaXML -xslt2 xsltfile -in xmlfile [-out outputfile] [options]

where


-xslt2 Specifies that the Altova XSLT 2.0 Engine is to be used for an XSLTtransformation; the engine uses the XSLT 2.0 file xsltfile for thetransformation.

-in Specifies the XML file xmlfile to be transformed and its location.

-out Specifies the output file outputfile and its location. If this option isomitted, the output is written to standard output.


-param Takes the instruction paramname=XPath expression. The -paramswitch is used before each global parameter. Double quotes must beused if a space is included in an XPath expressionwhether in a pathexpression itself or in a string literal in the expression. See examples.

-xslstack The stack size is the maximum depth of executed instructions, and canbe changed with the -xslstack value. The minimum allowed value is100. The default stack size is 1000. If the stack size is exceededduring a transformation, an error is reported.

-namedTemplate(or -n)

Sets the initial named template. A space separates the argument fromits value. Example: -namedTemplate MyTemplate

-mode (or -m) Sets the initial template mode. A space separates the argument from

its value. Example: -mode MyMode


-catalog (or-c)[]








25/159

2011 Altova GmbH


AltovaXML 2011


Each global resource in the Global Resources XML File can have multipleconfigurations, with each configuration mapping to a resource. The

-globalresourceconfig (or-gc) option enables you to specify whichconfiguration to use, by extension specifying which resource to use.

Note:

The XSLT file must be specified in the command line instruction; an XSLT filereferenced in an processing instruction in the XML documentis not automatically used.

If the -out parameter is omitted, output is written to the standard output.

The XSLT 2.0 Engine can be used in its backward compatibility mode to process anXSLT 1.0 stylesheet. The output, however, could be different than that produced by theXSLT 1.0 Engine processing the same XSLT 1.0 stylesheet.

Examples

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml-c MyCatalog.xml

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml-param date=//node/@att1

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml-param date="//node/@att1 | //node/@att2"

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml-param date=node/@att1 -param title='stringwithoutspace'

AltovaXML -xslt2 test.xslt -in test.xml -out testout.xml-param date=node/@att1 -param title="'string with spaces'"


26/159



2.1.4 XQuery 1.0 Executions

SyntaxThe syntax to invoke XQuery 1.0 executions is:

AltovaXML -xquery xqueryfile [-in inputXMLfile -out outputfile][options]

where


-xquery (or-xq) Specifies that the Altova XQuery 1.0 Engine is to be used for anXQuery execution of the file xqueryfile.

-in Specifies the input XML file.

-out Specifies the output file and its location. If this option is omitted, outputis written to the standard output.


-var Specifies an external variable and its value. Takes the formname=value. Any number of external variables can be submitted, buteach must be preceded by the -var keyword. Variable values mustbe strings that conform to the lexical form of the datatype as which thevariable has been declared.

-xparam Specifies an XQuery parameter name and the parameter's value.Takes the form name=XPathExpression. Use double quotes toenclose the XPath expression if the expression contains spaces. Usesingle quotes to delimit string literals in the XPath expression. Anynumber of parameters can be submitted, but each must be precededby the -xparam keyword.

-outputMethod(or-om) Serialization option to specify the type of output. Valid values are xml,html, xhtml, and text. Default is xml.

-omitXMLDeclaration(or-od)

Serialization option to specify whether the XML declaration should beomitted from the output or not. Valid values are yes and no. Defaultis yes.

-outputIndent(or-oi)

Serialization option to specify whether the output should be indentedor not. Valid values are yes and no. Default is no.

-outputEncoding(or-oe)

Serialization option to specify the character set of the output. Validvalues are names in the IANA character set registry. Default is UTF-8.


-catalog (or-c)[]



27/159

2011 Altova GmbH


AltovaXML 2011



-globalresourceconfig (or-gc)

[]





Note: If the -out parameter is omitted, output is written to the standard output.

Examples

AltovaXML -xquery testquery.xq -out testout.xml

AltovaXML -xquery testquery.xq -in products.xml -outtestout.xml-var company=Altova -var date=2006-01-01

AltovaXML -xquery testquery.xq -out testout.xml-xparam source=" doc( 'c:\test\books.xml' )//book "

AltovaXML -xquery testquery.xq -in products.xml -outtestout.xml-var company=Altova -omitXMLDeclaration no -oe ASCII


28/159

22 Usage COM Interface


2.2 COM Interface

When registered as a COM server object, AltovaXML can be invoked from within applicationsand scripting languages that have programming support for COM calls. This is useful because itenables XML document validation, XSLT transformations (XSLT 1.0 and XSLT 2.0), and

XQuery 1.0 document executions to be performed, by AltovaXML, from within a wide range ofuser applications.

To use AltovaXML with applications and scripting languages that have a COM interface, youmust first register AltovaXML as a COM server object. How to do this is described inRegistering AltovaXML as a COM server object.

The AltovaXML object model and its properties are described in the following sub-sections ofthis section. (Note that you can use both the Raw Interface and Dispatch Interface of COM. TheRaw Interface is used for programming languages (such as C++).The Dispatch Interface isused for scripting languages (such as JavaScript) that do not allow passing parameters byreference.) You can therefore use AltovaXML with:

Scripting languages such as JavaScript or any other scripting language that supports

the COM interface. Programming languages such as C++ or any other that supports the COM interface. Java and .NET, for which interfaces are built as a wrapper, with classes being created

around the COM interface.

This section on COM interface usage ends with a set of examples of how various functionalitiesof AltovaXML can be invoked from within a variety of user applications.

ExamplesFor examples additional to those in this section, see the example files in the Examples folder inthe application folder.


29/159

2011 Altova GmbH

COM Interface 23Usage

AltovaXML 2011

2.2.1 Registering AltovaXML as a COM Server Object

When you install AltovaXML 2011, AltovaXML_COM.exe will automatically be registered as aCOM server object. If you need to change the location ofAltovaXML_COM.exe, it is best tode-install AltovaXML and then re-install it at the required location. In this way the necessary

unregistration and registration are carried out by the installer process. If you copy AltovaXML_COM.exe to another machine, you must manually register AltovaXML at its new location as aCOM server object. How to do this is explained below. This description assumes thatAltovaXML has been successfully installed.

Manual registrationTo register AltovaXML as a COM server object, do the following:

1. Copy AltovaXML_COM.exe to the required location. If this location is not on the localmachine, map this location to a network folder.

2. Open a Windows Command Prompt window, or, from the Start menu, select Run....3. Register the application as a COM server object by using the /regserver parameter.

For example, ifAltovaXML_COM.exe is in the folderc:\AltovaXML, then key in:

c:\AltovaXML\AltovaXML_COM.exe /regserverand press Enter.

Checking success of the registrationIf the registration was successful, the Registry should contain the classesAltovaXML.Application and AltovaXML.Application.1. These two classes willtypically be found underHKEY_LOCAL_MACHINE\SOFTWARE\Classes .

Manual unregistrationIf the AltovaXML_COM.exe has been manually registered and you now wish to unregister it,then it should be manually unregistered. To manually unregister AltovaXML, call the applicationwith the /unregserver parameter. For example, if the AltovaXML executable is in the folderc:\AltovaXML, then open a Windows Command Prompt window, key in c:\AltovaXML\AltovaXML_COM.exe /unregserver, and press Enter. You can check the Registry Editor

for confirmation of unregistration.

Note: If AltovaXML was registered by the installer, the unregistration should be done by theinstallerthat is, by de-installing AltovaXML from the machine.


30/159



2.2.2 AltovaXML Object Model

The starting point for using the functionality of AltovaXML is the Application interface. Thisobject contains the four objects that provide the AltovaXML functionality: XML validation, XSLT1.0 transformations, XSLT 2.0 transformations, and XQuery 1.0 document processing. Theseobjects have dual interfaces: the Dispatch Interface and the Raw Interface, which enables themto be used in scripting languages as well as in applications.

The object model of the AltovaXML API is depicted in the following diagram.

The hierarchy of the object model is shown below, and the five interfaces are described in detailin the corresponding sections. The properties and usage of each interface are described in thesection for that interface.

Application

XMLValidator

XSLT1

XSLT2

XQuery

Note:Note the following general points about COM Interface usage:

The term XML document refers not only to an XML document contained in an XML filebut also to an XML document created with the InputXMLFromText property.

Properties that take a resource location as its input accept absolute paths, as well asthe HTTP and FTP protocols.

When relative paths are used by a method to locate a resource, the resolution of therelative path should be defined in the calling module.


31/159

2011 Altova GmbH


AltovaXML 2011

2.2.3 Application

DescriptionAltovaXML.Application is the root for all other objects. It is the only object you can createwith the CreateObject function (of VisualBasic) or other similar COM-related functions.

PropertiesAltovaXML.Application has the four properties listed below. Each of these functionsreturns the interface for the specific component. The details of each interface are given in therespective sections listed below.

XMLValidator XSLT1 XSLT2 XQuery

Methods

The following methods, which are available on the application object, enable the addition ofcatalogs used for document lookup. After catalogs are added they are used for lookup till theCOM server terminates. Added catalogs cannot be removed.

app.AddXMLCatalogDefault()

Adds Altova's default RootCatalog.xml to the catalogs

app.AddXMLCatalogFromFile( string catalogfilename )

Adds the catalog identified by catalogfilename to the catalogs

app.AddXMLCatalogFromText( string catalogtext )

Adds the catalog with content catalogtext to the catalogs

ExamplesGiven below is a Visual Basic script that first creates the AltovaXML object, and then callsproperties of the application interface.

Sub CommandButton1_Click()Set objAltovaXML = CreateObject("AltovaXML.Application")

objAltovaXML.XMLValidator.InputXMLFileName ="c:\AltovaXML\test.xml"

Sheet1.Cells(5, 2) = objAltovaXML.XMLValidator.IsValid

objAltovaXML.XSLT1.InputXMLFromText = ""

objAltovaXML.XSLT1.XSLFileName = "c:\workarea\altova_xml\1.xslt"

Sheet1.Cells(6, 2) =objAltovaXML.XSLT1.ExecuteAndGetResultAsString

End Sub


32/159



2.2.4 XMLValidator

DescriptionThe XMLValidator interface provides methods to test:

The well-formedness of an XML document. The validity of an XML document against a DTD or XML Schema referenced from

within the XML document. The validity of an XML document against a DTD or XML Schema supplied externally via

the code. The validity of an XBRL document against an XBRL taxonomy (a .xsd file).

All these methods return Boolean TRUE orFALSE. See examples below.

Note: Where string inputs are to be interpreted as URLs, absolute paths should be used. If arelative path is used, a mechanism to resolve the relative path should be defined in the callingmodule.

MethodsThe following methods are available:

IsWellFormed

IsWellFormed checks the well-formedness of the XML document. Returns TRUE if the XMLdocument is well-formed, FALSE if it is not well-formed.

IsValid

IsValid validates the XML document against the DTD or XML Schema referenced in the XMLdocument. Returns TRUE if the XML document is valid, FALSE if invalid. To validate against aDTD or XML Schema not referenced in the XML document, use the methodIsValidWithExternalSchemaOrDTD .

IsValidWithExternalSchemaOrDTD

IsValidWithExternalSchemaOrDTD validates the XML document against the DTD or XMLSchema supplied by any one of the following properties: SchemaFileName, DTDFileName,SchemaFromText, orDTDFromText. If more than one of these properties has values set for it,then the IsValidWithExternalSchemaOrDTD method uses the property that has been setlast. Returns TRUE if the XML document is valid, FALSE if invalid. To validate against a DTD orXML Schema referenced in the XML document, use the method IsValid.

Note: Validation and well-formedness checks must always occur after assigning the XMLand/or DTD or XML Schema document to the respective properties.

PropertiesThe following properties are defined:

InputXMLFileName

A string input that is read as a URL to locate the XML file to be validated.

SchemaFileName

A string input that is read as a URL to locate the XML Schema file against which the XMLdocument is to be validated.

DTDFileName

A string input that is read as a URL to locate the DTD file against which the XML document is tobe validated.


33/159

2011 Altova GmbH


AltovaXML 2011

InputXMLFromText

A string input that constructs an XML document.

SchemaFromText

A string input that constructs an XML Schema document.

DTDFromText

A string input that constructs a DTD document.

LastErrorMessage

Returns the last error message.

TreatXBRLInconsistenciesAsErrors

If set to True, returns XBRL semantic inconsistencies as errors. Default is False.

ExamplesGiven below is a single Visual Basic procedure that shows how the methods and properties of

the XMLValidator interface can be used. This code is intended for use as a macro in an MSExcel worksheet, and references to worksheet cells indicate locations of input or output data.The file c:\AltovaXML\test.xml is assumed to contain a reference to a DTD.


objAltovaXML.XMLValidator.InputXMLFromText = ""

Sheet1.Cells(4, 2) = objAltovaXML.XMLValidator.IsWellFormed


Sheet1.Cells(5, 2) = objAltovaXML.XMLValidator.IsValid


objAltovaXML.XMLValidator.DTDFileName = "c:\AltovaXML\test.dtd"Sheet1.Cells(6, 2) =

objAltovaXML.XMLValidator.IsValidWithExternalSchemaOrDTD

objAltovaXML.XMLValidator.InputXMLFromText = ""

objAltovaXML.XMLValidator.DTDFileName = "c:\AltovaXML\test.dtd"Sheet1.Cells(7, 2) =

objAltovaXML.XMLValidator.IsValidWithExternalSchemaOrDTDEnd Sub


34/159



2.2.5 XSLT1

DescriptionThe XSLT1 interface provides methods and properties to execute an XSLT 1.0 transformationusing the Altova XSLT 1.0 Engine. Results can be saved to a file or returned as a string. The

interface also enables XSLT parameters to be passed to the XSLT stylesheet. The URLs ofXML and XSLT files can be supplied as strings via interface properties. Alternatively, the XMLand XSLT documents can be constructed within the scripting or programming code as textstrings. See examples below.



Execute

Execute executes an XSLT 1.0 transformation and saves the result to an output file, the nameand location of which is provided as an input string to the Execute method.

ExecuteAndGetResultAsString

ExecuteAndGetResultAsString executes an XSLT 1.0 transformation and returns theresult as a UTF-16 text string.

AddExternalParameter

Takes a parameter name and the value of this parameter as input arguments. Each externalparameter and its value is to be specified in a separate call to the method. If multiple callsspecify the same parameter name the value set by the latest will be used. Since parametervalues are XPath expressions, parameter values that are strings must be enclosed in singlequotes. See examples below.

ClearExternalParameterListNo argument should be provided. The ClearExternalParameterList clears the externalparameters list created with AddExternalParameter methods.

Note: Transformation must always occur after assigning the XML and XSLT documents.


InputXMLFileName

A string input that is read as a URL to locate the XML file to be transformed.

XSLFileName

A string input that is read as a URL to locate the XSLT file to be used for the transformation.

InputXMLFromText


XSLFromText

A string input that constructs an XSLT document.

XSLStackSize

The stack size is the maximum depth of executed instructions. The stack size can be changed


35/159

2011 Altova GmbH


AltovaXML 2011

with the XSLStackSize property. The minimum allowed stack size is 100. The default stacksize is 1000. If the stack size is exceeded during a transformation, an error is reported.

LastErrorMessage


JavaExtensionsEnabled

Enables Java extensions. You can specify whether Java extensions should be enabled or notby submitting true orfalse (case-insensitive) as a Boolean argument.

DotNetExtensionsEnabled

Enables .NET extensions. You can specify whether .NET extensions should be enabled or notby submitting true orfalse (case-insensitive) as a Boolean argument.

ExamplesGiven below is a single Visual Basic procedure that shows how the various methods andproperties of the XSLT1 interface can be used. This code is intended for use as a macro in anMS Excel worksheet, and references to worksheet cells indicate locations of input or output

data.


objAltovaXML.XSLT1.InputXMLFromText = "

"objAltovaXML.XSLT1.XSLFileName = "c:\AltovaXML\test.xslt"objAltovaXML.XSLT1.Execute "c:\AltovaXML\test_result.xml

objAltovaXML.XSLT1.XSLStackSize = "500"objAltovaXML.XSLT1.InputXMLFromText = "

2005"objAltovaXML.XSLT1.XSLFileName = "c:\AltovaXML\test.xslt"objAltovaXML.XSLT1.AddExternalParameter "web", "'www.altova.com'"objAltovaXML.XSLT1.AddExternalParameter "year", "/company/year"Sheet1.Cells(6, 2) =

objAltovaXML.XSLT1.ExecuteAndGetResultAsStringobjAltovaXML.XSLT1.ClearExternalParameterListobjAltovaXML.XSLT1.AddExternalParameter "web",

"'www.nanonull.com'"objAltovaXML.XSLT1.AddExternalParameter "year", "/company/year"Sheet1.Cells(7, 2) =

objAltovaXML.XSLT1.ExecuteAndGetResultAsStringEnd Sub


36/159



2.2.6 XSLT2

DescriptionThe XSLT2 interface provides methods and properties to execute an XSLT 2.0 transformationusing the Altova XSLT 2.0 Engine. Results can be saved to a file or returned as a string. The

interface also enables XSLT parameters to be passed to the XSLT stylesheet. The URLs ofXML and XSLT files can be supplied as strings via interface properties. Alternatively, the XMLand XSLT documents can be constructed within the scripting or programming code as textstrings. See examples below.

Note:

Where string inputs are to be interpreted as URLs, absolute paths should be used. If arelative path is used, a mechanism to resolve the relative path should be defined in thecalling module.

The XSLT 2.0 Engine can be used in its backward compatibility mode to process anXSLT 1.0 stylesheet. The output, however, could be different than that produced by theXSLT 1.0 Engine processing the same XSLT 1.0 stylesheet.


Execute

Execute executes an XSLT 2.0 transformation and saves the result to an output file, the nameand location of which is provided as an input string to the Execute method.


ExecuteAndGetResultAsString executes an XSLT 2.0 transformation and returns theresult as a UTF-16 text string.

AddExternalParameter

Takes a parameter name and the value of this parameter as input arguments. Each external

parameter and its value is to be specified in a separate call to the method. If multiple callsspecify the same parameter name the value set by the latest will be used. Since parametervalues are XPath expressions, parameter values that are strings must be enclosed in singlequotes. See examples below. Notice in the examples that the date parameter is given a valuethat is an XPath 2.0 function (current-date()).

ClearExternalParameterList

No argument should be provided. The ClearExternalParameterList clears the externalparameters list created with AddExternalParameter methods.

InitialTemplateName

Sets the initial named template. The argument is the name of the template from whichprocessing is to start.

InitialTemplateModeSets the initial mode for processing. The argument is the name of the required initial mode.Templates with this mode value will be processed.

Note: Transformation must always occur after assigning the XML and XSLT documents.



37/159

2011 Altova GmbH


AltovaXML 2011

InputXMLFileName

A string input that is read as a URL to locate the XML file to be transformed.

XSLFileName

A string input that is read as a URL to locate the XSLT file to be used for the transformation.

InputXMLFromText


XSLFromText

A string input that constructs an XSLT document.

XSLStackSize

The stack size is the maximum depth of executed instructions. The stack size can be changedwith the XSLStackSize property. The minimum allowed stack size is 100. The default stacksize is 1000. If the stack size is exceeded during a transformation, an error is reported.

LastErrorMessage






ExamplesGiven below is a single Visual Basic procedure that shows how the various methods andproperties of the XSLT2 interface can be used. This code was intended for use as a macro inan MS Excel worksheet, and references to worksheet cells indicate locations of input or output

data.


objAltovaXML.XSLT2.InputXMLFromText = "

"objAltovaXML.XSLT2.XSLFileName = "c:\AltovaXML\test.xslt"Sheet1.Cells(7, 2) =

objAltovaXML.XSLT2.ExecuteAndGetResultAsString

objAltovaXML.XSLT2.XSLStackSize = "500"objAltovaXML.XSLT2.InputXMLFromText = "2005"objAltovaXML.XSLT2.XSLFileName = "c:\workarea\AltovaXML\2.xslt"objAltovaXML.XSLT2.AddExternalParameter "date", "current-date()"objAltovaXML.XSLT2.AddExternalParameter "hq", "'Vienna, Austria'"Sheet1.Cells(8, 2) =

objAltovaXML.XSLT2.ExecuteAndGetResultAsStringobjAltovaXML.XSLT2.AddExternalParameter "web",

"'www.nanonull.com'"objAltovaXML.XSLT2.AddExternalParameter "year", "/company/year"objAltovaXML.XSLT2.Execute


38/159



"c:\workarea\AltovaXML\test_result_xslt2.xml"Sheet1.Cells(9, 2) =

objAltovaXML.XSLT2.ExecuteAndGetResultAsStringEnd Sub


39/159

2011 Altova GmbH


AltovaXML 2011

2.2.7 XQuery

DescriptionThe XQuery interface provides methods and properties to execute an XQuery 1.0transformation using the Altova XQuery 1.0 Engine. Results can be saved to a file or returned

as a string. The interface also enables external XQuery variables to be passed to the XQuerydocument. The URLs of XQuery and XML files can be supplied as strings via interfaceproperties. Alternatively, the XML and XQuery documents can be constructed within thescripting or programming code as text strings. See examples below.



Execute

Execute executes an XQuery 1.0 transformation and saves the result to an output file, thename and location of which is provided as an input string to the Execute method.


ExecuteAndGetResultAsString executes an XQuery 1.0 transformation and returns theresult as a UTF-16 text string.

AddExternalVariable

Takes a variable name and the value of this variable as input arguments. Each externalvariableand its value is to be specified in a separate call to the method. Variables must bedeclared in the XQuery document, optionally with a type declaration. Whatever the typedeclaration for the external variable in the XQuery document, the variable value submitted tothe AddExternalVariable method does not need any special delimiter, such as quotes (seeexample below). However, the lexical form must match that of the expected type (for example,

a variable of type xs:date must have a value in the lexical form 2004-01-31; a value in thelexical form 2004/Jan/01 will cause an error). Note that this also means that you cannot usean XQuery 1.0 function (for example, current-date()) as the value of an external variable(since the lexical form of the function as it is written will either not match the required data type(if the datatype is specified in the declaration of the external variable) or will be read as a string(if the datatype is not specified).) If multiple calls specify the same variable name the value setby the latest will be used.

AddExternalVariableAsXPath

Takes a variable name and the value of this variable as input arguments. Similar toAddExternalVariable method, except that AddExternalVariableAsXPathwill beevaluated first as an XPath 2.0 expression. This makes it possible to pass in nodes andsequences with more than one element.

ClearExternalVariableList

No argument should be provided. The ClearExternalVariableList clears the externalvariables list created with AddExternalVariable methods.

Note: Setting the optional XML document must always be done before query execution.



40/159



XQueryFileName

A string input that is read as a URL to locate the XQuery file to be executed. If both theXQueryFileName property and XQueryFromText property are specified, then the propertythat has been set later than the other (in the code sequence) is used.

InputXMLFileName

A string input that is read as a URL to locate the XML file that will be loaded into the query.XQuery navigation expressions are evaluated with reference to the document node of this XMLdocument. If both the InputXMLFileName property and InputXMLFromText property arespecified, then the property that has been set later than the other (in the code sequence) isused.

XQueryFromText

A string input that constructs an XQuery document. If both the XQueryFileName property andXQueryFromText property are specified, then the property that has been set later than theother (in the code sequence) is used.

InputXMLFromText

A string input that constructs an XML document. XQuery navigation expressions are evaluated

with reference to the document node of this XML document. If both the InputXMLFileNameproperty and InputXMLFromText property are specified, then the property that has been setlater than the other (in the code sequence) is used.

LastErrorMessage






Note: If an XML document is set and is not needed for a new XQuery execution, then it shouldbe cleared with an empty string assignment.

The following serialization options are defined:

OutputMethod

The required output method can be specified by submitting the required value as a stringargument. Valid values are: xml, xhtml, html, and text. For example:objAltovaXML.XQuery.OutputMethod = "xml". If the value is invalid, it is ignored. Thedefault output method is xml.

OutputOmitXMLDeclarationYou can specify whether the XML declaration should be omitted or included in the output bysubmitting true orfalse (case-insensitive) as a Boolean argument. For example:objAltovaXML.XQuery.OutputOmitXMLDeclaration = "FALSE". If the value is invalid,an error is raised. The default option is TRUE.

OutputIndent

You can specify whether the output should be indented or not by submitting true orfalse(case-insensitive) as a Boolean argument. For example:objAltovaXML.XQuery.OutputIndent = "TRUE". If the value is invalid, an error israised. The default option is False.


41/159

2011 Altova GmbH


AltovaXML 2011

OutputEncoding

The required output encoding can be specified by submitting the encoding value as a stringargument. For example: objAltovaXML.XQuery.OutputEncoding = "UTF-8". If thevalue is invalid, it is ignored. The default output encoding is UTF-8.

Note: For the serialization options, Raw Interface and Dispatch Interface usage differs. In theRaw Interface, if no argument is provided with these properties, then the current value of theproperty is returned. You would use something like: put_OutputOption( VARIANT_BOOLbVal ) orVARIANT_BOOL bVal = get_OutputOption(), respectively, to set values andget values. In the Dispatch Interface, you can use b = myXQuery.OutputOption to getvalues and myXQuery.OutputOption = b to set values. For example, in the DispatchInterface, Sheet1.Cells(10, 2) = objAltovaXML.XQuery.OutputEncoding wouldget the current output encoding.

ExamplesGiven below is a single Visual Basic procedure that shows how the various methods andproperties of the XQuery interface can be used. This code was intended for use as a macro in

an MS Excel worksheet, and references to worksheet cells indicate locations of input or outputdata.


objAltovaXML.XQuery.InputXMLFileName = "c:\AltovaXML\test.xml"objAltovaXML.XQuery.XQueryFromText = " xquery version '1.0';

declare variable $string as xs:string external;declare variable $num as xs:decimal external;declare variable $date as xs:date external;$string, ' ', 2*$num, ' ', $date "

objAltovaXML.XQuery.AddExternalVariable "string", "A string"objAltovaXML.XQuery.AddExternalVariable "num", "2.1"

objAltovaXML.XQuery.AddExternalVariable "date", "2005-04-21"Sheet1.Cells(10, 2) = objAltovaXML.XQuery.OutputEncodingobjAltovaXML.XQuery.OutputMethod = "text"Sheet1.Cells(11, 2) = objAltovaXML.XQuery.OutputMethodobjAltovaXML.XQuery.OutputIndent = "TRUE"Sheet1.Cells(12, 2) = objAltovaXML.XQuery.OutputIndentobjAltovaXML.XQuery.OutputOmitXMLDeclaration = "FALSE"Sheet1.Cells(13, 2) = objAltovaXML.XQuery.OutputOmitXMLDeclarationSheet1.Cells(14, 2) =

objAltovaXML.XQuery.ExecuteAndGetResultAsStringEnd Sub


42/159



2.2.8 Examples

This section contains example code in (i) Visual Basic for an Excel macro; (ii) JScript; and (iii)C++. These examples will give you an idea of how you can use AltovaXML with a COMInterface.

For more detailed examples, see the example files in the Examples folder in the applicationfolder.

Visual Basic

The following Visual Basic example is the code for a macro in an Excel worksheet (screenshotbelow). The macro has been assigned to the button Run Expressions. On clicking thebutton, the Visual Basic code is executed.

Code sampleThe Visual Basic code below uses the XQuery interface.


objAltovaXML.XQuery.XQueryFromText = Sheet1.Cells(2, 1)

Sheet1.Cells(2, 2) =objAltovaXML.XQuery.ExecuteAndGetResultAsString

objAltovaXML.XQuery.InputXMLFromText = Sheet1.Cells(3, 1)objAltovaXML.XQuery.XQueryFromText = "translate(node, ';-', '. ')"Sheet1.Cells(3, 2) =

objAltovaXML.XQuery.ExecuteAndGetResultAsString

objAltovaXML.XQuery.InputXMLFromText = ""

objAltovaXML.XQuery.XQueryFromText = "string(/a/@*)"Sheet1.Cells(4, 2) =

objAltovaXML.XQuery.ExecuteAndGetResultAsStringEnd Sub

On clicking the button Run Expressions in the Excel worksheet, the following three XQueryinstructions are executed:

1. The input for the XQueryFromText property is an XQuery expression taken as textfrom the Excel worksheet cell 2A. The ExecuteAndGetResultAsString propertyexecutes the XQuery expression and places the result in the Excel worksheet cell 2B.

2. The input for the InputXMLFromText property is an XML fragment taken from theExcel worksheet cell 3A. The XQuery expression is given to the XQueryFromTextproperty directly in the code. The result is placed in the Excel worksheet cell 3B.

3. The InputXMLFromText property creates an XML tree from the XML fragment


43/159

2011 Altova GmbH


AltovaXML 2011

provided to it. The XQuery expression is given to the XQueryFromText propertydirectly in the code, and the result is placed in the Excel worksheet cell 4B.

JScript

Given below is a JScript code sample that shows how AltovaXML can be used via the COMinterface.

Code sample

// //////////// global variables /////////////////var objAltovaXML = null;

// /////////////////////// Helpers //////////////////////////////

function Exit(strErrorText){

WScript.Echo(strErrorText);

if (objAltovaXML != null)

objAltovaXML.Quit();

WScript.Quit(-1);}

function ERROR(strText, objErr){

if (objErr != null)Exit ("ERROR: (" + (objErr.number & 0xffff) + ")" + objErr.description +

" - " + strText);else

Exit ("ERROR: " + strText);}

function CreateGlobalObjects (){

// create the AltovaXML connection// if there is a running instance of AltovaXML (that never had aconnection) - use it

// otherwise, we automatically create a new instancetry{

objAltovaXML = WScript.GetObject("", "AltovaXML.Application");//WScript.Echo("Successfully accessing AltovaXML.Application");

}catch(err){WScript.Echo(err)

{ Exit("Can't access or create AltovaXML.Application"); }}

}

// /////////////////////// MAIN //////////////////////////////

CreateGlobalObjects();

objAltovaXML.XQuery.InputXMLFromText = " \ \ \

TCP/IP Illustrated \StevensW. \AW \65.95 \


44/159



\ \

Advanced Programming in the Unix Environment \StevensW. \AW \65.95 \

\ \Data on the Web \AbiteboulSerge \AbiteboulSerge \AbiteboulSerge \John Jameson Publishers \39.95 \

\ \

Digital TV \GassyViktorCITI \

Kingston Academic Press \129.95 \

\ ";

objAltovaXML.XQuery.XQueryFromText = "\(: Filename: xmpQ1.xq :) \(: Source: http://www.w3.org/TR/xquery-use-cases/#xmp-data :) \(: Section: 1.1.1.9 Q1 :) \(: List books published by AW after 1991, including their year and title.:)\ \{ \

for $b in /bib/book where $b/publisher = \"AW\" and $b/@year > 1991 \return { $b/title }

\} \

";

var sResult = objAltovaXML.XQuery.ExecuteAndGetResultAsString();WScript.Echo(sResult);

C++

Given below is a C++ code sample that shows how AltovaXML can be used via the COMinterface.

Code sample

// TestAltovaXML.cpp : Defines the entry point for the console application.//#include "objbase.h"#include #include "atlbase.h"

#import "AltovaXML_COM.exe" no_namespace raw_interfaces_only// - or -//#import "AltovaXML_COM.exe" raw_interfaces_only//using namespace AltovaXMLLib;

int main(int argc, char* argv[]){

HRESULT hr = S_OK;


45/159

2011 Altova GmbH


AltovaXML 2011

hr = CoInitialize(NULL);if ( hr == S_OK ){

IApplicationPtr ipApplication;

hr = CoCreateInstance(

__uuidof( Application),NULL,CLSCTX_ALL,__uuidof(IApplication),

reinterpret_cast(&ipApplication));

if ( hr == S_OK ){

IXQueryPtr ipXQuery;hr = ipApplication->get_XQuery( &ipXQuery );

if ( hr == S_OK ){

CComBSTR sXQExpr( "(1 to 10)[. mod 2 != 0]" );

BSTR bstrResult;

hr = ipXQuery->put_XQueryFromText( sXQExpr );hr = ipXQuery->ExecuteAndGetResultAsString(

&bstrResult );

std::cout


46/159

40 Usage Java Interface


2.3 Java Interface

The AltovaXML Java interface (AltovaXML.jar) connects to the AltovaXML COM interfaceusing native functions in the AltovaXMLLib.dll. This DLL will have been installed in theWINDIR\system32\ directory when you install AltovaXML using the AltovaXML installer.

AltovaXML.jar contains the package com.altova.engines, which is the packagecontaining the Altova engines.

SetupIn order to use the Java interface, add the AltovaXML.jar file to the CLASSPATH. COMregistration is done automatically by the AltovaXML Installer. If you change the location of thefile AltovaXML_COM.exe after installation, you should register AltovaXML as a COM serverobject by running the command AltovaXML_COM.exe /regserver. See RegisteringAltovaXML as a COM Server Object for more details.

DocumentationThis section contains a detailed description of the AltovaXML Java interface. Thisdocumentation is also available in HTML format in the ZIP archive, AltovaXMLJavaDocs.zip, which is located in the AltovaXML2011 application folder.

ExamplesFor detailed examples, see the example files in the Examples folder in the application folder.

The com.altova.engines package

To use the Java interface, your starting point is the package com.altova.engines. This isthe Java interface for the AltovaXML COM server object; it provides access to XMLValidatorand to the XSLT 1.0, XSLT 2.0 and XQuery 1.0 engines.

The com.altova.engines package provides connection to the AltovaXML COM interfaceusing the native functions in AltovaXMLLib.dll, which is installed in theWINDIR\system32\ directory.

To connect to a new instance of AltovaXML COM server object, use the static methodgetInstance() of the AltovaXMLFactory class. From the returned interface you canchoose the required engine using the getENGINENAMEInstance() function.

Given below is a sample of code that uses the Java interface:

import com.altova.engines.*;

/*** Test application for AltovaXML COM components java interface

*/public class AltovaXMLTest {

/*** public constructor for AltovaXMLTest*/public AltovaXMLTest(){}

/*** application main*/public static void main(String[] args) {


47/159

2011 Altova GmbH

Java Interface 41Usage

AltovaXML 2011

System.out.println("AltovaXML Java Interface Test Application");

//request a COM server object - fails if AltovaXML is not registeredIAltovaXMLFactory objXmlApp = AltovaXMLFactory.getInstance();

if ( objXmlApp != null ) {

//get interface for the XQuery engineIXQuery xquery = objXmlApp.getXQueryInstance();//set XQuery statementxquery.setXQueryStatement("{1 to 3}This data is

well-formed.");//execute the statement previously set.//There was no input XML specified so the initial context is

empty.String sres = xquery.executeAndGetResultAsString();//release XQuery engine's connection to the COM server objectxquery.releaseInstance();System.out.println(sres);

IXMLValidator validator = objXmlApp.getXMLValidatorInstance();validator.setInputXMLFromText(sres);

boolean b = validator.isWellFormed();if ( b )System.out.println("XML data is well-formed.");

elseSystem.out.println("Data is not well-formed.");

validator.releaseInstance();

//release Application object connection to the COM server object.//After this the COM server object will shut down automatically.objXmlApp.releaseInstance();

} else{System.out.println("Creating instance of IAltovaXMLFactory

failed.");System.out.println("Please make sure AltovaXML.exe is correctly

registered!");}

}}


48/159



2.3.1 Interfaces

Given below is a summary of the interfaces ofcom.altova.engines. Detailed descriptionsare given in the respective sections.

IAltovaXMLEngineBasic interface for XMLValidator, and XSLT 1.0, XSLT 2.0, and XQuery 1.0 engines. IAltovaXMLFactory

Interface for AltovaXML COM object wrapper. IExecutable

Executable interface for engines. IReleasable

Interface for Release functionality. IXMLValidator

Interface for XMLValidator. IXQuery

Interface for the XQuery 1.0 engine. IXSLT

Interface for the XSLT engines.

IAltovaXMLEngine

Basic interface for XMLValidator, XSLT 1.0, XSLT 2.0 and XQuery engines. Public interface

that extends IReleasable.

Superinterface: IReleasableSubinterface: XMLValidator, IXQuery, IXSLTImplementing classes: XMLValidator, XQuery, XSLT1, XSLT2

Methods

The following methods are defined.

setInputXMLFileNamepublic void setInputXMLFileName(java.lang.String filename)

Sets the file name for the input XML data. Please note that you have to use absolute URLs.

Parameters:

filename: an absolute URL giving the base location of the XML data.

setInputXMLFromTextpublic void setInputXMLFromText(java.lang.String text)Sets the text value for the input XML data. For example: setInputXMLFromText( "

text " )Parameters:

text: a string containing XML data.

getLastErrorMessagepublic java.lang.String getLastErrorMessage()

Gets the last error message from the engine.Returns:a string containing the last error message.


49/159

2011 Altova GmbH


AltovaXML 2011

IAltovaXMLFactory

Interface for AltovaXML COM object wrapper. Provides access to the interfaces ofXMLValidator, XSLT 1.0, XSLT 2.0 and Xquery 1.0 engines. Public interface that extends

IReleasable.

Superinterface: IReleasableImplementing classes: AltovaXMLFactory

MethodsThe following methods are defined.

getXQueryInstancepublic IXQuerygetXQueryInstance()Creates a new instance of XQuery class for the current XQuery engine instance. The object'sconnection to the engine must be released after use. To do this, use the function

releaseInstance() declared in the IReleasable interface.

Returns:the IXQuery interface of the newly created class.

getXSLT1Instancepublic IXSLTgetXSLT1Instance()Creates a new instance of XSLT1 class for the current XSLT 1.0 engine instance. The object'sconnection to the engine must be released after use. To do this, use the function


Returns:the IXSLT interface of the newly created class.

getXSLT2Instancepublic IXSLTgetXSLT2Instance()Creates a new instance of XSLT2 class for the current XSLT 2.0 engine instance. The object'sconnection to the engine must be released after use. To do this, use the function


Returns:the IXSLT interface of the newly created class.

getXMLValidatorInstancepublic IXMLValidatorgetXMLValidatorInstance()Creates a new instance of XMLValidator class for the current XML Validator instance. The

object's connection to the engine must be released after use.To do this, use the functionreleaseInstance() declared in the IReleasable interface.

Returns:the IXMLValidator interface of the newly created class.

The following methods enable the addition of catalogs used for document lookup. After catalogsare added they are used for lookup till the COM server terminates. Added catalogs cannot beremoved.


50/159



app.AddXMLCatalogDefault()

Adds Altova's default RootCatalog.xml to the catalogs

app.AddXMLCatalogFromFile( string catalogfilename )

Adds the catalog identified by catalogfilename to the catalogs

app.AddXMLCatalogFromText( string catalogtext )

Adds the catalog with content catalogtext to the catalogs

IExecutable

Executable interface for engines. Public interface.

Subinterface: IXQuery, IXSLTImplementing classes: XQuery, XSLT1, XSLT2

Methods


executepublic boolean execute(java.lang.String outfilename)Executes and saves the result to file. In case of an error, you can use the function

getLastErrorMessage() declared in IAltovaXMLEngine to get additional information.Parameters:outfilename: an absolute URL giving the location of the output file.Returns:true on success, false on error.

executeAndGetResultAsString

public java.lang.String executeAndGetResultAsString()Executes and returns the result as string.In case of an error, you can use the function

getLastErrorMessage() declared in IAltovaXMLEngine to get additional information.Returns:string containing the serialized result. On error, will return the empty string.

enableJavaExtensionspublic void enableJavaExtensions(boolean bEnable)Enables/disables .NET extension functions.

enableDotNetExtensions

public void enableDotNetExtensions(boolean bEnable)Enables/disables Java extension functions.

IReleasable

Public interface for Release functionality. When an object implementing this interface is notused any more, then the releaseInstance() function must be called in order to releaseconnection to the COM server. The COM server will shut down automatically when allconnections to it are released.


51/159

2011 Altova GmbH


AltovaXML 2011

Subinterface: IXQuery, IXSLTImplementing classes: XQuery, XSLT1, XSLT2

Methods


releaseInstancepublic void releaseInstance()

Releases the object's connection to the COM server.

IXMLValidator

Interface for the XML Validator. Public interface that extends IAltovaXMLEngine.

Superinterface: IAltovaXMLEngine, IReleasableImplementing classes: XMLValidator

MethodsThe following methods are defined.

isValidpublic boolean isValid()Validates the input XML data against the DTD/Schema specified in it.Returns:true on success, false on failure. In case of failure, you can use the functiongetLastErrorMessage() declared in IAltovaXMLEngine to get additional information.

isWellFormed

public boolean isWellFormed()Checks the input XML data for well-formedness.Returns:true on success, false on failure. In case of failure, you can use the functiongetLastErrorMessage() declared in IAltovaXMLEngine to get additional information.

isValidWithExternalSchemaOrDTDpublic boolean isValidWithExternalSchemaOrDTD()Validates the input XML data agains

Altova XML

Documents

Transcript of Altova XML