Previous  Top  Next

Altova.AltovaXML.XQuery

Description

The Altova.AltovaXML.XQuery object provides methods and properties to execute an XQuery 1.0 transformation using the Altova XQuery 1.0 Engine. Results can be saved to a file or returned as a string. The object also enables external XQuery variables to be passed to the XQuery document. The URLs of XQuery and XML files can be supplied as strings via the object's properties. Alternatively, the XML and XQuery documents can be constructed within the code as text strings.

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

Methods

The following methods are available:

Execute

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

ExecuteAndGetResultAsString

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

AddExternalVariable

Takes a variable name and the value of this variable as input arguments. Each external variable and its value is to be specified in a separate call to the method. Variables must be declared in the XQuery document, optionally with a type declaration. Whatever the type declaration for the external variable in the XQuery document, the variable value submitted to the AddExternalVariable does not need any special delimiter, such as quotes. 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 the lexical form 2004/Jan/01 will cause an error). Note that this also means that you cannot use an 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).) Providing an external variable that has the name of an existing (uncleared) variable causes an error.

ClearExternalVariableList

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

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

Properties

The following properties are defined:

XQueryFileName

A string input that is read as a URL to locate the XQuery file to be executed. If both the XQueryFileName property and XQueryFromText property are specified, then the property that 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 XML document. If both the InputXMLFileName property and InputXMLFromText property are specified, then the property that has been set later than the other (in the code sequence) is used.

XQueryFromText

A string input that constructs an XQuery document. If both the XQueryFileName property and XQueryFromText property are specified, then the property that has been set later than the other (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 InputXMLFileName property and InputXMLFromText property are specified, then the property that has been set later than the other (in the code sequence) is used.

LastErrorMessage

Returns the last error message.

Note: If an XML document is set and is not needed for a new XQuery execution, then it should be 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 string argument. Valid values are: xml, xhtml, html, and text. For example: objAltovaXML.XQuery.OutputMethod = "xml". If the value is invalid, it is ignored. The default output method is xml.

OutputOmitXMLDeclaration

You can specify whether the XML declaration should be omitted or included in the output by submitting true or false (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 or false (case-insensitive) as a Boolean argument. For example: objAltovaXML.XQuery.OutputIndent = "TRUE". If the value is invalid, an error is raised. The default option is False.

OutputEncoding

The required output encoding can be specified by submitting the encoding value as a string argument. For example: objAltovaXML.XQuery.OutputEncoding = "UTF-8". If the value 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 the Raw Interface, if no argument is provided with these properties, then the current value of the property is returned. You would use something like: put_OutputOption( VARIANT_BOOL bVal ) or VARIANT_BOOL bVal = get_OutputOption(), respectively, to set values and get values. In the Dispatch Interface, you can use b = myXQuery.OutputOption to get values and myXQuery.OutputOption = b to set values. For example, in the Dispatch Interface, Sheet1.Cells(10, 2) = objAltovaXML.XQuery.OutputEncoding would get the current output encoding.